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

## 概述

NAC编译辅助检查器（NAC Lint Checker）是一个编译前置工具，自动检测违反NAC原则的代码，包括：
- 以太坊术语使用
- ERC标准依赖
- 错误的命名规范
- 违反架构原则的代码

## 设计目标

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

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

## 检查规则分类

### 1. 术语检查（Terminology Check）
**严重性**: CRITICAL

检测以太坊术语的使用：
- ❌ Token → ✅ Asset
- ❌ Contract → ✅ Certificate
- ❌ Balance → ✅ Holdings
- ❌ Miner/Validator → ✅ CBP (Constitutional Block Producer)
- ❌ Gas → ✅ Gas (保留但实现不同)

**检查范围**：
- 变量名
- 函数名
- 结构体名
- 注释内容
- 文档字符串

**示例**：
```rust
// ❌ 错误
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

**示例**：
```toml
# ❌ 错误
[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
- 常量定义
- 函数名
- 结构体名

**示例**：
```rust
// ❌ 错误
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哈希

**检查范围**：
- 属性宏
- 哈希函数调用
- 序列化代码

**示例**：
```rust
// ❌ 错误
#[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集成)
```

### 规则定义格式

```json
{
  "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. 编译前检查
```bash
# 在cargo build之前运行
nac-lint check

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

### 2. Git提交前检查
```bash
# Git pre-commit hook
nac-lint check --staged

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

### 3. CI/CD检查
```yaml
# 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输出
```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集成
```toml
# Cargo.toml
[build-dependencies]
nac-lint = "1.0"

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

### 2. Git Hook集成
```bash
# .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集成
```yaml
# .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
```json
{
  "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/`目录下添加自定义规则：

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

### 规则优先级
1. 记忆系统内置规则（memory/principles/）
2. 项目自定义规则（memory/rules/）
3. 用户配置规则（.naclintrc）

## 性能考虑

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

### 快速模式
```bash
# 只检查critical级别
nac-lint check --fast

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

## 未来扩展

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

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

## 总结

NAC编译辅助检查器是确保代码质量和原则一致性的关键工具。通过在编译前自动检测违规，可以：
- 避免以太坊遗留代码进入代码库
- 强制执行NAC核心原则
- 提高代码质量和一致性
- 减少代码审查负担

---

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