453 lines
9.1 KiB
Markdown
453 lines
9.1 KiB
Markdown
# 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核心原则
|
||
- 提高代码质量和一致性
|
||
- 减少代码审查负担
|
||
|
||
---
|
||
|
||
*下一步：实现规则检查引擎*
|