Arch-Lint

架构层级依赖检查工具，基于 dependency-cruiser 自动检测逆向依赖违规。

特性

• 🔍 自动检测分层架构的逆向依赖
• 📊 生成详细的违规报告（终端 + JSON）
• 🔧 提供修复建议
• 🚀 引导创建修复 PR
• ⚙️ 通用配置，适用于任何分层架构项目

可以用多种方式使用：

| 方式 | 适用场景 | 用法概要 | | ----------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Monorepo 中的一个 package | 多包仓库里统一做架构检查 | 放在 packages/arch-lint/，arch-config.json 里 projectRoot 指向各子包（如 ../capy），用 pnpm --filter arch-lint check 运行。 | | 单仓库的 devDependency | 只有一个前端/全栈项目 | 安装 pnpm add -D @kookapp/arch-lint，在项目根放 arch-config.json（projectRoot: "."），在项目根执行 npx arch-lint check 即可；报告会写在项目内 .reports/arch-violations.json。 | | 独立克隆/复制使用 | 不想装进仓库，只偶尔检查 | 克隆或复制 arch-lint 到任意目录，编辑其下的 arch-config.json，projectRoot 指向要检查的项目路径，在该目录运行 pnpm check。 | | 全局 CLI | 多项目、临时检查 | npm i -g @kookapp/arch-lint 后，在任意项目根放 arch-config.json（projectRoot: "."），在该目录执行 arch-lint check 即可（会优先读 cwd 下的配置）。 |

配置解析顺序：优先读**当前工作目录（cwd）**下的 arch-config.json（适合单仓库：在项目根执行即可）；若无则读 arch-lint 包内的默认配置。支持 --config <path> 显式指定配置文件。当配置来自 cwd 时，projectRoot 填 "." 表示当前项目，报告会写入项目内 .reports/。

发布到 npm 后：单仓库使用（推荐）

发布后作为 devDependency 使用非常方便，三步即可：

# 1. 安装
pnpm add -D @kookapp/arch-lint

# 2. 在项目根目录创建 arch-config.json（projectRoot 填 "." 表示当前项目）

arch-config.json 示例（放在项目根）：

{
  "projectRoot": ".",
  "layers": [
    { "name": "UI", "patterns": ["^src/components/"] },
    { "name": "Application", "patterns": ["^src/services/", "^src/app/"] },
    { "name": "Domain", "patterns": ["^src/types/", "^src/domain/"] },
    { "name": "Infrastructure", "patterns": ["^src-tauri/", "^src/infra/"] }
  ],
  "direction": "topDown",
  "extraForbidden": [
    {
      "from": "UI",
      "to": "Infrastructure",
      "severity": "error",
      "reason": "UI 禁止直接依赖 Infrastructure"
    }
  ]
}

# 3. 在项目根执行（会优先读取项目根下的 arch-config.json）
npx arch-lint check
npx arch-lint check --ci          # CI 用
npx arch-lint check --fix-pr      # 引导创建修复 PR

可选：在 package.json 的 scripts 里加上：

"scripts": {
  "arch-lint": "arch-lint check",
  "arch-lint:ci": "arch-lint check --ci"
}

之后直接 pnpm arch-lint 即可。报告会生成在项目根下的 .reports/arch-violations.json。建议在项目 .gitignore 中加入 .reports/。

快速开始（从源码/ monorepo 内使用）

1. 安装依赖

pnpm install

2. 配置架构规则

编辑 arch-config.json：

{
  "projectRoot": "../your-project",
  "layers": [
    { "name": "UI", "patterns": ["^src/components/"] },
    { "name": "Application", "patterns": ["^src/services/"] },
    { "name": "Domain", "patterns": ["^src/types/"] },
    { "name": "Infrastructure", "patterns": ["^src-tauri/"] }
  ],
  "direction": "topDown",
  "extraForbidden": [
    {
      "from": "UI",
      "to": "Infrastructure",
      "severity": "error",
      "reason": "UI 禁止直接依赖 Infrastructure"
    }
  ]
}

3. 运行检查

# 手动检查
pnpm check

# CI 模式（有违规则 exit 1）
pnpm check:ci

# 检查并引导创建修复 PR
pnpm check:fix-pr

配置说明

layers

定义架构层级，按照依赖方向排序。

• name: 层级名称
• patterns: 文件路径正则表达式数组

direction

• topDown: 上层（数组前面）可以依赖下层（数组后面），反之禁止
• bottomUp: 下层可以依赖上层，反之禁止

extraForbidden

额外的禁止规则，用于声明跳层依赖等特殊约束。

集成到 CI

单仓库（npm 安装后）：在 .github/workflows/lint.yml 中：

- name: Check architecture boundaries
  run: pnpm exec arch-lint check --ci
# 或
  run: npx arch-lint check --ci

Monorepo 内：

- name: Check architecture boundaries
  run: pnpm --filter arch-lint check:ci

定时检查

Windows Task Scheduler

$action = New-ScheduledTaskAction -Execute "pnpm" -Argument "--filter arch-lint check:fix-pr" -WorkingDirectory "D:\code\k\agent"
$trigger = New-ScheduledTaskTrigger -Daily -At 9am
Register-ScheduledTask -TaskName "ArchLint" -Action $action -Trigger $trigger

Cron (Linux/Mac)

0 9 * * * cd /path/to/agent && pnpm --filter arch-lint check:fix-pr

工作原理

1. 从 arch-config.json 读取架构层级定义
2. 生成 dependency-cruiser forbidden 规则
3. 扫描目标项目的源码依赖
4. 提取违规项并生成报告
5. 可选：引导创建修复 PR

与 Constraint-Driven 体系的关系

此工具实现了 constraint-driven-agent-coding.md 第 10.4 节的原则：

硬约束的最佳载体不是自定义的 JSON 文件和 Python 脚本，而是项目中已有的工程工具链。

arch-config.json 本身就是架构约束的机器可读声明，取代了 .agent/constraints/architecture.json。

示例文件

examples/ 目录包含各种集成示例：

• arch-config.template.json - 通用配置模板（三层、六边形、Clean Architecture）
• pre-commit-hook.sh - Git pre-commit hook 脚本
• lefthook.yml - Lefthook 配置
• husky-pre-commit - Husky hook 配置
• github-workflow.yml - GitHub Actions workflow

详细用法参见 USAGE.md。

License

MIT