434 lines
8.1 KiB
Markdown
434 lines
8.1 KiB
Markdown
# NAC Lint编译辅助检查器 - 集成指南
|
||
|
||
## 概述
|
||
|
||
NAC Lint是一个编译前置检查工具，自动检测违反NAC原则的代码。本指南介绍如何将NAC Lint集成到您的开发工作流程中。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 基本使用
|
||
|
||
```bash
|
||
# 检查单个文件
|
||
python3 memory/tools/nac_lint.py check --path src/main.rs
|
||
|
||
# 检查整个目录
|
||
python3 memory/tools/nac_lint.py check --path src/
|
||
|
||
# 列出所有规则
|
||
python3 memory/tools/nac_lint.py list-rules
|
||
|
||
# 生成JSON报告
|
||
python3 memory/tools/nac_lint.py check --path src/ --output json --output-file report.json
|
||
```
|
||
|
||
### 2. 检查结果解读
|
||
|
||
```
|
||
❌ CRITICAL: 3 violation(s)
|
||
- 阻止编译，必须修复
|
||
|
||
⚠️ HIGH: 2 violation(s)
|
||
- 强烈建议修复，但不阻止编译
|
||
|
||
ℹ️ MEDIUM: 1 violation(s)
|
||
- 建议修复
|
||
|
||
💡 LOW: 0 violation(s)
|
||
- 可选修复
|
||
```
|
||
|
||
---
|
||
|
||
## 集成方式
|
||
|
||
### 方式1: Git Pre-commit Hook（推荐）
|
||
|
||
**优点**: 在提交前自动检查，防止违规代码进入仓库
|
||
|
||
**安装步骤**:
|
||
|
||
```bash
|
||
# 1. 复制pre-commit脚本
|
||
cp memory/tools/pre-commit .git/hooks/pre-commit
|
||
|
||
# 2. 设置可执行权限
|
||
chmod +x .git/hooks/pre-commit
|
||
|
||
# 3. 测试（尝试提交一个违规文件）
|
||
git add src/test.rs
|
||
git commit -m "test"
|
||
# 如果有违规，提交会被阻止
|
||
```
|
||
|
||
**工作流程**:
|
||
1. 开发者执行 `git commit`
|
||
2. Git自动运行pre-commit hook
|
||
3. NAC Lint检查staged文件
|
||
4. 如果发现CRITICAL违规，阻止提交
|
||
5. 开发者修复违规后重新提交
|
||
|
||
---
|
||
|
||
### 方式2: Cargo Build Script
|
||
|
||
**优点**: 在cargo build时自动检查
|
||
|
||
**安装步骤**:
|
||
|
||
```bash
|
||
# 1. 复制build.rs模板到项目根目录
|
||
cp memory/tools/build.rs.template build.rs
|
||
|
||
# 2. 在Cargo.toml中添加（如果还没有）
|
||
# [build-dependencies]
|
||
# （build.rs不需要额外依赖）
|
||
|
||
# 3. 测试
|
||
cargo build
|
||
# 如果有违规，构建会失败
|
||
```
|
||
|
||
**工作流程**:
|
||
1. 开发者执行 `cargo build`
|
||
2. Cargo运行build.rs
|
||
3. build.rs调用NAC Lint检查src/
|
||
4. 如果发现CRITICAL违规，panic阻止构建
|
||
5. 开发者修复违规后重新构建
|
||
|
||
**注意**:
|
||
- 只在debug模式下运行检查（加快release构建）
|
||
- 可以通过环境变量 `SKIP_NAC_LINT=1` 跳过检查
|
||
|
||
---
|
||
|
||
### 方式3: Makefile集成
|
||
|
||
**优点**: 统一的命令接口，易于使用
|
||
|
||
**安装步骤**:
|
||
|
||
```bash
|
||
# 1. 将Makefile.template内容添加到项目Makefile
|
||
cat memory/tools/Makefile.template >> Makefile
|
||
|
||
# 2. 使用
|
||
make lint # 运行检查
|
||
make build # 先检查再构建
|
||
make test # 先检查再测试
|
||
make install-hooks # 安装Git hooks
|
||
```
|
||
|
||
**可用命令**:
|
||
- `make lint` - 运行NAC Lint检查
|
||
- `make lint-json` - 生成JSON报告
|
||
- `make lint-rules` - 列出所有规则
|
||
- `make build` - 先检查再构建
|
||
- `make test` - 先检查再测试
|
||
- `make install-hooks` - 安装Git hooks
|
||
|
||
---
|
||
|
||
### 方式4: GitHub Actions CI/CD
|
||
|
||
**优点**: 在PR和push时自动检查，团队协作友好
|
||
|
||
**安装步骤**:
|
||
|
||
```bash
|
||
# 1. 创建GitHub Actions工作流目录
|
||
mkdir -p .github/workflows
|
||
|
||
# 2. 复制工作流文件
|
||
cp memory/tools/nac-lint.yml.template .github/workflows/nac-lint.yml
|
||
|
||
# 3. 提交并推送
|
||
git add .github/workflows/nac-lint.yml
|
||
git commit -m "Add NAC Lint CI"
|
||
git push
|
||
```
|
||
|
||
**工作流程**:
|
||
1. 开发者push代码或创建PR
|
||
2. GitHub Actions自动运行NAC Lint
|
||
3. 生成检查报告并上传为artifact
|
||
4. 如果是PR，自动在PR中评论检查结果
|
||
5. 如果有CRITICAL违规，CI失败
|
||
|
||
---
|
||
|
||
### 方式5: 手动集成
|
||
|
||
**适用场景**: 自定义构建流程
|
||
|
||
```bash
|
||
# 在任何脚本中调用
|
||
python3 memory/tools/nac_lint.py check --path src/
|
||
if [ $? -ne 0 ]; then
|
||
echo "NAC Lint check failed"
|
||
exit 1
|
||
fi
|
||
```
|
||
|
||
---
|
||
|
||
## 配置文件
|
||
|
||
### .naclintrc
|
||
|
||
在项目根目录创建 `.naclintrc` 配置文件：
|
||
|
||
```bash
|
||
# 复制模板
|
||
cp memory/tools/.naclintrc.template .naclintrc
|
||
|
||
# 编辑配置
|
||
vim .naclintrc
|
||
```
|
||
|
||
**配置选项**:
|
||
|
||
```json
|
||
{
|
||
"version": "1.0",
|
||
"enabled": true, // 是否启用检查
|
||
"severity_threshold": "high", // 严重性阈值
|
||
"exclude_paths": [ // 排除路径
|
||
"target/",
|
||
"node_modules/",
|
||
"*.test.rs"
|
||
],
|
||
"rules": {
|
||
"terminology": {
|
||
"enabled": true,
|
||
"severity": "critical"
|
||
},
|
||
"naming": {
|
||
"enabled": true,
|
||
"severity": "high"
|
||
}
|
||
},
|
||
"fail_on_critical": true, // CRITICAL时失败
|
||
"fail_on_high": false, // HIGH时不失败
|
||
"output_format": "console", // 输出格式
|
||
"verbose": true // 详细输出
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 检查规则
|
||
|
||
### 当前规则（23条）
|
||
|
||
#### CRITICAL级别（必须修复）
|
||
|
||
1. **TERM_001-010**: 术语检查
|
||
- Token → Asset
|
||
- Contract → Certificate
|
||
- Balance → Holdings
|
||
- PoW/PoS → CBPP
|
||
- P2P → CSNP
|
||
- RPC → NRPC3.0
|
||
- EVM → NVM
|
||
- SHA256 → Blake3
|
||
- Governance Token → XIC
|
||
- Stablecoin → XTZH
|
||
|
||
2. **TERM_011-020**: 协议和工具检查
|
||
- ERC-20 → ACC-20
|
||
- Wallet → Asset Vault
|
||
- Transaction → Asset Transfer
|
||
- Block Explorer → Quantum Holographic Explorer
|
||
|
||
#### HIGH级别（强烈建议修复）
|
||
|
||
1. **ARCH_002**: OpCode命名必须使用UPPER_CASE
|
||
2. **ARCH_003**: 必须使用Blake3哈希算法
|
||
3. **ARCH_004**: 禁止使用#[allow(unused)]
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 如何跳过某个文件的检查？
|
||
|
||
**方法1**: 在.naclintrc中添加排除路径
|
||
```json
|
||
{
|
||
"exclude_paths": [
|
||
"src/legacy/old_code.rs"
|
||
]
|
||
}
|
||
```
|
||
|
||
**方法2**: 在文件顶部添加注释（未实现，计划中）
|
||
```rust
|
||
// nac-lint: disable
|
||
```
|
||
|
||
### Q2: 如何临时禁用检查？
|
||
|
||
```bash
|
||
# 环境变量
|
||
SKIP_NAC_LINT=1 cargo build
|
||
|
||
# 或在Git提交时
|
||
git commit --no-verify
|
||
```
|
||
|
||
### Q3: 检查太慢怎么办？
|
||
|
||
```bash
|
||
# 只检查修改的文件
|
||
git diff --name-only | xargs python3 memory/tools/nac_lint.py check --path
|
||
|
||
# 使用快速模式（只检查CRITICAL）
|
||
python3 memory/tools/nac_lint.py check --path src/ --severity critical
|
||
```
|
||
|
||
### Q4: 如何添加自定义规则？
|
||
|
||
创建 `memory/rules/custom_rules.json`:
|
||
|
||
```json
|
||
{
|
||
"rule_id": "CUSTOM_001",
|
||
"category": "custom",
|
||
"severity": "medium",
|
||
"title": "自定义规则",
|
||
"pattern": "your_regex_pattern",
|
||
"suggestion": "建议修复方式"
|
||
}
|
||
```
|
||
|
||
然后在.naclintrc中引用：
|
||
|
||
```json
|
||
{
|
||
"custom_rules": [
|
||
"memory/rules/custom_rules.json"
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 团队协作
|
||
|
||
- ✅ 在项目README中说明NAC Lint的使用
|
||
- ✅ 在onboarding时安装Git hooks
|
||
- ✅ 在CI/CD中强制执行检查
|
||
- ✅ 定期更新规则库
|
||
|
||
### 2. 开发流程
|
||
|
||
```bash
|
||
# 开发前
|
||
make install-hooks # 安装Git hooks
|
||
|
||
# 开发中
|
||
# ... 编写代码 ...
|
||
|
||
# 提交前（自动运行）
|
||
git commit -m "..."
|
||
|
||
# 如果被阻止
|
||
make lint # 查看详细违规
|
||
# ... 修复违规 ...
|
||
git commit -m "..."
|
||
|
||
# 构建前（自动运行）
|
||
make build
|
||
```
|
||
|
||
### 3. CI/CD流程
|
||
|
||
```yaml
|
||
# .github/workflows/nac-lint.yml
|
||
- name: NAC Lint
|
||
run: make lint-json
|
||
|
||
- name: Upload Report
|
||
uses: actions/upload-artifact@v3
|
||
with:
|
||
name: lint-report
|
||
path: lint-report.json
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### 问题1: Python找不到
|
||
|
||
```bash
|
||
# 检查Python版本
|
||
python3 --version
|
||
|
||
# 如果没有Python 3，安装
|
||
sudo apt install python3
|
||
```
|
||
|
||
### 问题2: 规则文件找不到
|
||
|
||
```bash
|
||
# 确保记忆系统目录结构完整
|
||
ls -la memory/principles/
|
||
ls -la memory/tools/
|
||
|
||
# 如果缺失，重新创建
|
||
# （参考记忆系统安装指南）
|
||
```
|
||
|
||
### 问题3: Git hook不工作
|
||
|
||
```bash
|
||
# 检查hook是否可执行
|
||
ls -la .git/hooks/pre-commit
|
||
|
||
# 设置可执行权限
|
||
chmod +x .git/hooks/pre-commit
|
||
|
||
# 测试hook
|
||
.git/hooks/pre-commit
|
||
```
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2026-02-07)
|
||
- ✅ 初始版本
|
||
- ✅ 23条检查规则
|
||
- ✅ Git Hook集成
|
||
- ✅ Cargo集成
|
||
- ✅ Makefile集成
|
||
- ✅ GitHub Actions集成
|
||
- ✅ 配置文件支持
|
||
|
||
### 计划中的功能
|
||
|
||
- [ ] 自动修复（--fix选项）
|
||
- [ ] IDE集成（VS Code插件）
|
||
- [ ] 实时检查（保存时检查）
|
||
- [ ] AI辅助检查
|
||
- [ ] 检查报告仪表板
|
||
|
||
---
|
||
|
||
## 支持
|
||
|
||
如有问题，请查看：
|
||
- 记忆系统文档: `memory/README.md`
|
||
- 快速参考卡: `memory/QUICK_REFERENCE.md`
|
||
- 设计文档: `memory/tools/LINT_CHECKER_DESIGN.md`
|
||
|
||
---
|
||
|
||
*NAC Lint - 确保代码符合NAC原则，避免以太坊遗留*
|