npm package: @kookapp/arch-lint
Description: Architecture layer dependency checker using dependency-cruiser
Latest version: 0.1.0

# 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 使用非常方便，三步即可：

```bash
# 1. 安装
pnpm add -D @kookapp/arch-lint

# 2. 在项目根目录创建 arch-config.json（projectRoot 填 "." 表示当前项目）
```

`arch-config.json` 示例（放在项目根）：

```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"
    }
  ]
}
```

```bash
# 3. 在项目根执行（会优先读取项目根下的 arch-config.json）
npx arch-lint check
npx arch-lint check --ci          # CI 用
npx arch-lint check --fix-pr      # 引导创建修复 PR
```

可选：在 `package.json` 的 `scripts` 里加上：

```json
"scripts": {
  "arch-lint": "arch-lint check",
  "arch-lint:ci": "arch-lint check --ci"
}
```

之后直接 `pnpm arch-lint` 即可。报告会生成在项目根下的 `.reports/arch-violations.json`。建议在项目 `.gitignore` 中加入 `.reports/`。

## 快速开始（从源码/ monorepo 内使用）

### 1. 安装依赖

```bash
pnpm install
```

### 2. 配置架构规则

编辑 `arch-config.json`：

```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. 运行检查

```bash
# 手动检查
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` 中：

```yaml
- name: Check architecture boundaries
  run: pnpm exec arch-lint check --ci
# 或
  run: npx arch-lint check --ci
```

**Monorepo 内**：

```yaml
- name: Check architecture boundaries
  run: pnpm --filter arch-lint check:ci
```

## 定时检查

### Windows Task Scheduler

```powershell
$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)

```bash
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](../skills/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](./USAGE.md)。

## License

MIT