lindseystead/ArchGuard

# ArchGuard [](https://github.com/lindseystead/ArchGuard/actions/workflows/ci.yml) [](https://github.com/lindseystead/ArchGuard/releases/latest) [](LICENSE) **面向 AI 辅助 React PR 的架构守卫。** ArchGuard 在 React + TypeScript 项目中强制执行层级导入边界 —— 具备五分钟快速设置、monorepo 支持、面向遗留代码的 baseline 模式，以及专为 coding agent 设计的 CI 输出。 ## 为什么选择 ArchGuard AI 编程助手引入架构违规的速度远超人工审查的速度。ESLint 和 TypeScript 并不强制执行文件夹层级规则。dependency-cruiser 虽然功能强大，但配置繁琐，且不提供 PR diff 模式或面向 agent 的输出。 ArchGuard 填补了这一空白： | 你需要…… | ArchGuard 提供…… | | --- | --- | | 简易设置 | 一个 `architecture.yaml`，几分钟内运行 `archguard init` | | 层级强制执行 | 在 `domain`、`features`、`ui` 等之间实现确定性的导入边界 | | Monorepo 支持 | `--root`、workspace 包、tsconfig project references | | 遗留代码 | baseline 模式 —— 仅针对**新**违规报错 | | AI 工作流 | Agent JSON、`AGENTS.md` 同步、Cursor/Copilot 规则、MCP server | | 快速 PR 检查 | `--diff` 模式 (v2.1) | 有关与 dependency-cruiser、eslint-plugin-boundaries 和 Steiger 的客观对比，请参阅 [docs/COMPARISON.md](docs/COMPARISON.md)。 ## 功能状态 | 功能 | 状态 | | --- | --- | | 层级导入边界 | ✅ 已发布 | | 循环依赖检测 | ✅ 已发布 | | baseline / 增量采用 | ✅ 已发布 | | Monorepo `--root` + workspace 解析 | ✅ 已发布 | | JSON / SARIF / GitHub Action | ✅ 已发布 | | React UI 启发式检测（循环、组件内 fetch） | ✅ 已发布（可选） | | npm install (`@lifesavertech/archguard-cli`) | ✅ 已发布 (v2.1.0) | | 自定义层 `paths` 映射 | ✅ 已发布 (v2.0.4) | | `patterns:` schema + 智能 `init` | ✅ 已发布 (v2.0.5) | | `--config`, `--json`, `--format github` | ✅ 已发布 (v2.0.6) | | Agent 输出 (`--format agent`，修复提示) | ✅ 已发布 (v2.0.6) | | `archguard sync` + `sync --check` | ✅ 已发布 (v2.0.7) | | Action SARIF 上传 + `sync-check` | ✅ 已发布 (v2.0.7) | | PR diff 模式 (`--diff`) | ✅ 已发布 (v2.1.0) | | 多 Agent 输出 | ✅ 已发布 (v2.1.0) | | MCP server (`@lifesavertech/archguard-mcp`) | ✅ 已发布 (v2.1.0) | | Barrel 绕过检测 | ✅ 已发布 (v2.2.0) | | Mermaid 图表 | 🔜 v2.3 | | VS Code 扩展 | 🔜 v2.4 | 完整路线图：[ROADMAP.md](ROADMAP.md) · 采用指南：[docs/ADOPTION.md](docs/ADOPTION.md) ## 快速开始 ### 安装 ``` npm install -D @lifesavertech/archguard-cli@2.2.0 npx archguard --version npx archguard check --json # machine-readable CI output npx archguard check --format github # GitHub Actions annotations ``` 要求 **Node.js 20 或更高版本**（`package.json` 中的 `engines.node`）。在 Node 18 上，CLI 会以明确的错误提示退出，而不是安装损坏的依赖。 ### 自定义文件夹布局 默认预设匹配文件夹**名称**（`domain/`、`features/`、`ui/`）。对于 `components/`、`db/`、`pages/` 等，请使用 `patterns`（推荐）或 `layers.*.paths` 映射文件夹： ``` patterns: root: src ignore: ["**/*.test.{ts,tsx}", "**/__tests__/**"] layers: ui: include: [components/**, pages/**] db: include: [db/**] exclude: [db/migrations/**] layers: ui: allowedImports: [features, db] db: allowedImports: [] ``` 简写（仍然支持）： ``` layers: ui: paths: [src/components, src/pages] allowedImports: [features, db] db: paths: [src/db] allowedImports: [] ``` 如果启用了边界规则但**没有任何文件匹配到任何层**，`check` 将报错，而不是报告虚假的通过。 **GitHub Action (CI):** ``` - uses: lindseystead/ArchGuard@v2 # or @v1 for legacy ``` **从源码运行（npm 发布前）：** ``` git clone https://github.com/lindseystead/ArchGuard.git cd ArchGuard npm install && npm run build && npm link ``` ### 初始化 ``` archguard init # smart-detect folders + boundaries-only rules archguard init --no-detect # static preset only (skip repo scan) archguard init --preset react-layered # detected layout + UI heuristics rules archguard init --preset feature-sliced-react ``` 写入 `architecture.yaml`、`AGENTS.md` 和 `.archguard/ARCHITECTURE_RULES.md`。 ### 检查 ``` archguard check ``` 示例输出： ``` ✗ Found 3 violation(s): src/ui/UserProfile.tsx:2:1 - Layer 'ui' cannot import from 'domain'. Import from allowed layers only: features, shared. Move the imported code to an allowed layer or restructure dependencies. (layer-import-boundary) ``` ### Monorepo ``` archguard check --root apps/web --verbose ``` ### 增量采用 ``` archguard check --update-baseline # capture existing violations archguard check --baseline # fail only on new ones ``` ## 配置 `architecture.yaml` 是唯一事实来源： ``` layers: domain: allowedImports: [] features: allowedImports: [domain, shared] ui: allowedImports: [features, shared] shared: allowedImports: [] uiLayers: [ui] # optional: scope React UI rules rules: enforceLayerBoundaries: true noCircularLayerDeps: true # Optional UI heuristics (off by default in v2 init; use react-layered preset to enable) noBusinessLogicInComponents: false noDataFetchingInUI: false ``` 完整参考：[docs/architecture.example.yaml](docs/architecture.example.yaml) `enforceFeatureBoundaries` 仍然是 `enforceLayerBoundaries` 的已弃用别名。 ## 命令参考 | 命令 | 描述 | | --- | --- | | `archguard init` | 生成配置脚手架（默认仅包含边界规则） | | `archguard init --preset ` | `boundaries-only`, `react-layered`, `feature-sliced-react` | | `archguard check --diff` | PR 范围扫描（更改的文件 + 导入相邻文件） | | `archguard check --diff-base ` | 用于 diff 的 Git 引用（默认为 `origin/main`） | | `archguard sync` | 根据配置重新生成指南 | | `archguard sync --check` | 如果指南已过期则报错 (CI) | | `archguard sync --targets cursor,copilot` | 仅写入 Cursor/Copilot 规则文件 | | `archguard sync --force` | 覆盖现有的 agent 规则文件 | | `archguard check` | 全仓库扫描 | | `archguard check --root ` | 扫描 monorepo 应用包 | | `archguard check --config ` | 使用自定义的 `architecture.yaml` | | `archguard check --baseline` | 屏蔽已知的违规 | | `archguard check --update-baseline` | 写入 baseline 文件 | | `archguard check --json` | JSON 输出（别名） | | `archguard check --format json\|sarif\|github\|agent` | 结构化输出 | | `archguard check --verbose` | 解析诊断信息 | **同时可用：** `archguard diagram`（计划于 v2.3 推出）—— 参见 [ROADMAP.md](ROADMAP.md)。 ## GitHub Actions ``` - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: lindseystead/ArchGuard@v2 with: diff-only: true diff-base: origin/main baseline: .archguard-baseline.json format: agent ``` Monorepo、SARIF 上传、sync-check 和 baseline 工作流：[docs/github-action.md](docs/github-action.md) ## MCP server (Cursor / Claude) ``` npm install -D @lifesavertech/archguard-mcp@2.1.0 ``` 添加至 `.cursor/mcp.json`： ``` { "mcpServers": { "archguard": { "command": "npx", "args": ["-y", "@lifesavertech/archguard-mcp@2.1.0"] } } } ``` 工具：`archguard_check`、`archguard_explain`、`archguard_init`（通过 `ARCHGUARD_MCP_ALLOW_WRITE=true` 开启写入权限）。 ## 项目结构 ``` ArchGuard/ ├── packages/ │ ├── core/ # Config, parsing, resolution, workspace discovery │ ├── cli/ # archguard command + presets/ │ │ └── src/presets/ # init preset definitions │ ├── rules-react/ # Boundary, cycle, and optional UI rules │ ├── guidance/ # AGENTS.md generation │ └── mcp/ # MCP server for AI agents ├── tests/fixture-*/ # CI fixtures ├── examples/react-layered-app/ ├── docs/ # Adoption, comparison, engineering plan ├── action.yml # Composite GitHub Action └── architecture.schema.ts ``` ## 文档 | 文档 | 描述 | | --- | --- | | [docs/ADOPTION.md](docs/ADOPTION.md) | 团队逐步采用指南 | | [docs/COMPARISON.md](docs/COMPARISON.md) | 对比 dependency-cruiser, ESLint, Steiger | | [docs/PRODUCT.md](docs/PRODUCT.md) | 产品定位与目标用户 | | [docs/ENGINEERING_PLAN.md](docs/ENGINEERING_PLAN.md) | v2 重构计划（面向维护者） | | [docs/architecture.example.yaml](docs/architecture.example.yaml) | 配置参考 | | [docs/github-action.md](docs/github-action.md) | Action 输入项与工作流 | | [docs/migration/v1-to-v2.md](docs/migration/v1-to-v2.md) | 升级指南 | | [ROADMAP.md](ROADMAP.md) | 已发布与计划中的功能 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发环境设置 | | [PUBLISHING.md](PUBLISHING.md) | 发布流程 | ## 示例项目 [examples/react-layered-app](examples/react-layered-app) —— 通过检查的参考示例，采用 `domain` / `features` / `ui` 布局。 ## 工作原理 1. 使用 TypeScript compiler API 解析 `.ts` / `.tsx` 2. 通过精确的路径段（`src/ui`，而非子字符串）将文件映射到层级 3. 解析导入：相对路径、tsconfig 别名、workspace 包、project references 4. 评估来自 `architecture.yaml` 的边界规则 5. 以文本、JSON 或 SARIF 格式输出违规项 `AGENTS.md` 是为贡献者和 agent 准备的参考材料。强制执行通过 CLI 和 `architecture.yaml` 进行。编辑配置后，请运行 `archguard sync` 以保持指南同步。 ## 已知限制 - UI 行为规则基于启发式算法，需**主动开启**（在 v2 的 `init` 中默认关闭） - 层级检测使用**精确路径段** - Barrel/re-export 绕过通过 `no-barrel-boundary-bypass` 检测（在强制执行层级边界时默认开启） - 全仓库扫描仍然是默认设置；建议在 CI 中定期安排全量扫描，并与 PR diff 检查结合使用 - npm 包：`@lifesavertech/archguard-cli`（待发布） - 暂无 IDE 扩展 (v2.4) —— 目前仅支持 CI 和 CLI ## 测试 ``` npm test ``` 涵盖核心、CLI（包括预设）、规则和指南的 37 项测试。CI 会对 Action、通过的示例、失败的 fixture 以及 monorepo `--root` 进行冒烟测试。 ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。在开始 v2 相关工作之前，请阅读 [docs/ENGINEERING_PLAN.md](docs/ENGINEERING_PLAN.md)。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：MITM代理, React, Syscalls, TypeScript, 云安全监控, 安全插件, 架构守护, 自动化攻击, 静态分析