# 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 → NAC Lens
   - 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原则，避免以太坊遗留*