9.1 KiB

Raw Blame History

NAC编译辅助检查器设计文档

概述

NAC编译辅助检查器（NAC Lint Checker）是一个编译前置工具，自动检测违反NAC原则的代码，包括：

以太坊术语使用
ERC标准依赖
错误的命名规范
违反架构原则的代码

设计目标

核心目标

零容忍以太坊遗留 - 检测所有以太坊相关术语、依赖、实现方式
强制NAC原则 - 确保代码符合NAC核心原则
实时反馈 - 编译前立即警示，避免错误代码进入代码库
可扩展规则 - 规则可以从记忆系统动态加载

非目标

不是代码格式化工具（使用rustfmt）
不是性能分析工具
不是安全漏洞扫描工具

检查规则分类

1. 术语检查（Terminology Check）

严重性: CRITICAL

检测以太坊术语的使用：

❌ Token → ✅ Asset
❌ Contract → ✅ Certificate
❌ Balance → ✅ Holdings
❌ Miner/Validator → ✅ CBP (Constitutional Block Producer)
❌ Gas → ✅ Gas (保留但实现不同)

检查范围：

变量名
函数名
结构体名
注释内容
文档字符串

示例：

// ❌ 错误
struct TokenBalance {
    token_id: u64,
    balance: u128,
}

// ✅ 正确
struct AssetHoldings {
    asset_id: u64,
    holdings: u128,
}

2. 依赖检查（Dependency Check）

严重性: CRITICAL

检测以太坊相关依赖：

❌ ethers
❌ web3
❌ openzeppelin-contracts
❌ @openzeppelin/contracts
❌ solidity-*
❌ erc20, erc721, erc1155

检查范围：

Cargo.toml dependencies
package.json dependencies
import/use statements

示例：

# ❌ 错误
[dependencies]
ethers = "2.0"
openzeppelin-contracts = "4.9"

# ✅ 正确
[dependencies]
nac-core = "1.0"
nac-acc20 = "1.0"

3. 命名规范检查（Naming Convention Check）

严重性: HIGH

检测违反命名规范的代码：

OpCode必须使用UPPER_CASE
常量必须使用UPPER_CASE
结构体使用PascalCase
函数使用snake_case

检查范围：

OpCode enum variants
常量定义
函数名
结构体名

示例：

// ❌ 错误
enum OpCode {
    Push1,      // 应该是 PUSH1
    SStore,     // 应该是 SSTORE
    CrCreate,   // 应该是 CR_CREATE
}

// ✅ 正确
enum OpCode {
    PUSH1,
    SSTORE,
    CR_CREATE,
}

4. 架构原则检查（Architecture Principle Check）

严重性: HIGH

检测违反架构原则的代码：

不允许删除代码（检测大量删除）
不允许使用#[allow(unused)]
不允许使用#[ignore]
不允许使用serde_json序列化复杂类型
必须使用Blake3哈希

检查范围：

属性宏
哈希函数调用
序列化代码

示例：

// ❌ 错误
#[allow(unused)]
fn some_function() { }

use sha256::digest;  // 应该使用Blake3

// ✅ 正确
fn some_function() { }  // 如果未使用，添加proper imports

use blake3::hash;

5. 协议检查（Protocol Check）

严重性: CRITICAL

检测错误的协议使用：

❌ ERC-20 → ✅ ACC-20
❌ ERC-721 → ✅ ACC-20C
❌ IBC → ✅ CSNP
❌ TCP/IP → ✅ CSNP

检查范围：

注释和文档
协议名称引用
标准引用

6. 共识检查（Consensus Check）

严重性: CRITICAL

检测错误的共识概念：

❌ PoW/PoS/DPoS/BFT → ✅ CBPP
❌ 投票机制（在共识层） → ✅ 规则验证
❌ SPV → ✅ Constitutional Layer Validation

检查范围：

共识相关代码
投票相关代码（区分治理和共识）

检查器架构

组件设计

NAC Lint Checker
├── Rule Engine (规则引擎)
│   ├── Rule Loader (从记忆系统加载规则)
│   ├── Rule Matcher (规则匹配器)
│   └── Rule Evaluator (规则评估器)
├── Code Scanner (代码扫描器)
│   ├── Rust Scanner (扫描.rs文件)
│   ├── Toml Scanner (扫描Cargo.toml)
│   ├── JSON Scanner (扫描package.json)
│   └── Markdown Scanner (扫描文档)
├── Violation Reporter (违规报告器)
│   ├── Console Reporter (控制台输出)
│   ├── JSON Reporter (JSON格式)
│   └── HTML Reporter (HTML报告)
└── Integration (集成)
    ├── Pre-commit Hook (Git钩子)
    ├── Cargo Build Script (Cargo集成)
    └── CI/CD Integration (CI/CD集成)

规则定义格式

{
  "rule_id": "TERM_001",
  "category": "terminology",
  "severity": "critical",
  "title": "禁止使用Token术语",
  "description": "NAC使用Asset而非Token",
  "pattern": {
    "type": "regex",
    "match": "\\b[Tt]oken\\b",
    "exclude_patterns": [
      "// ALLOWED: token",
      "TokenStream"  // Rust宏相关，允许
    ]
  },
  "suggestion": {
    "replace": "Asset",
    "example": "struct AssetHoldings { ... }"
  },
  "references": [
    "memory/principles/terminology.json#TERM_001"
  ]
}

工作流程

1. 编译前检查

# 在cargo build之前运行
nac-lint check

# 如果发现违规，阻止编译
# 如果通过，继续编译

2. Git提交前检查

# Git pre-commit hook
nac-lint check --staged

# 如果发现违规，阻止提交

3. CI/CD检查

# GitHub Actions
- name: NAC Lint Check
  run: |
    cd nac-workspace/memory
    python3 tools/nac_lint.py check --all

输出格式

控制台输出

NAC Lint Checker v1.0.0
Scanning: nac-udm/src/l1_protocol/nvm/opcode.rs

❌ CRITICAL: 禁止使用Token术语 [TERM_001]
   File: nac-udm/src/l1_protocol/nvm/opcode.rs:45:12
   Found: struct TokenBalance
   Should be: struct AssetHoldings
   Reference: memory/principles/terminology.json#TERM_001

⚠️  HIGH: OpCode命名必须使用UPPER_CASE [ARCH_002]
   File: nac-udm/src/l1_protocol/nvm/opcode.rs:120:5
   Found: Push1
   Should be: PUSH1
   Reference: memory/principles/architecture.json#ARCH_002

Summary:
  ❌ 2 critical violations
  ⚠️  1 high violation
  ✅ 0 warnings

Build blocked due to critical violations.

JSON输出

{
  "version": "1.0.0",
  "timestamp": "2026-02-07T07:30:00Z",
  "summary": {
    "total_files": 150,
    "scanned_files": 150,
    "violations": {
      "critical": 2,
      "high": 1,
      "medium": 0,
      "low": 0
    }
  },
  "violations": [
    {
      "rule_id": "TERM_001",
      "severity": "critical",
      "file": "nac-udm/src/l1_protocol/nvm/opcode.rs",
      "line": 45,
      "column": 12,
      "message": "禁止使用Token术语",
      "found": "struct TokenBalance",
      "suggestion": "struct AssetHoldings",
      "reference": "memory/principles/terminology.json#TERM_001"
    }
  ]
}

集成方式

1. Cargo集成

# Cargo.toml
[build-dependencies]
nac-lint = "1.0"

# build.rs
fn main() {
    nac_lint::check_all().expect("NAC lint check failed");
}

2. Git Hook集成

# .git/hooks/pre-commit
#!/bin/bash
cd nac-workspace/memory
python3 tools/nac_lint.py check --staged
if [ $? -ne 0 ]; then
    echo "❌ NAC lint check failed. Commit blocked."
    exit 1
fi

3. CI/CD集成

# .github/workflows/nac-lint.yml
name: NAC Lint Check
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run NAC Lint
        run: |
          cd nac-workspace/memory
          python3 tools/nac_lint.py check --all --output json

配置文件

.naclintrc

{
  "version": "1.0",
  "enabled": true,
  "severity_threshold": "high",
  "exclude_paths": [
    "target/",
    "node_modules/",
    "*.test.rs"
  ],
  "rules": {
    "terminology": {
      "enabled": true,
      "severity": "critical"
    },
    "dependency": {
      "enabled": true,
      "severity": "critical"
    },
    "naming": {
      "enabled": true,
      "severity": "high"
    },
    "architecture": {
      "enabled": true,
      "severity": "high"
    }
  },
  "custom_rules": [
    "memory/rules/custom_rules.json"
  ]
}

扩展性

自定义规则

用户可以在memory/rules/目录下添加自定义规则：

{
  "rule_id": "CUSTOM_001",
  "category": "custom",
  "severity": "medium",
  "title": "自定义检查规则",
  "pattern": {
    "type": "regex",
    "match": "custom_pattern"
  }
}

规则优先级

记忆系统内置规则（memory/principles/）
项目自定义规则（memory/rules/）
用户配置规则（.naclintrc）

性能考虑

增量检查

只检查修改的文件
缓存检查结果
并行扫描多个文件

快速模式

# 只检查critical级别
nac-lint check --fast

# 只检查staged文件
nac-lint check --staged

未来扩展

Phase 2

IDE集成（VS Code插件）
实时检查（保存时检查）
自动修复（--fix选项）

Phase 3

AI辅助检查（使用LLM理解代码意图）
团队规则共享
检查报告仪表板

总结

NAC编译辅助检查器是确保代码质量和原则一致性的关键工具。通过在编译前自动检测违规，可以：

避免以太坊遗留代码进入代码库
强制执行NAC核心原则
提高代码质量和一致性
减少代码审查负担

下一步：实现规则检查引擎

9.1 KiB Raw Blame History Unescape Escape

NAC编译辅助检查器设计文档

概述

设计目标

核心目标

非目标

检查规则分类

1. 术语检查（Terminology Check）

2. 依赖检查（Dependency Check）

3. 命名规范检查（Naming Convention Check）

4. 架构原则检查（Architecture Principle Check）

5. 协议检查（Protocol Check）

6. 共识检查（Consensus Check）

检查器架构

组件设计

规则定义格式

工作流程

1. 编译前检查

2. Git提交前检查

3. CI/CD检查

输出格式

控制台输出

JSON输出

集成方式

1. Cargo集成

2. Git Hook集成

3. CI/CD集成

配置文件

.naclintrc

扩展性

自定义规则

规则优先级

性能考虑

增量检查

快速模式

未来扩展

Phase 2

Phase 3

总结

9.1 KiB

Raw Blame History