archora-dev/archora

# Archora 一个本地分析器，可读取前端代码库，并告诉你架构哪里正在腐化 —— 包括循环依赖、热点区域、分层违规、契约破坏、包体积膨胀以及变更耦合模块。可作为桌面应用、CLI 或在 CI 中运行。代码不会离开你的机器。 文档：**[docs.archora.dev](https://docs.archora.dev)** ## 团队为何使用它 - 在 PR 中发现架构退化，避免其演变为大规模重构。 - 使用 `architectureBudget` 维护基准，而不是争论个人偏好。 - 将循环依赖、分层违规和热点区域转化为带有证据的修复队列。 - 为不熟悉 CLI 的队友提供一个桌面工作区，用于查看 Impact、Rules、Cycles 和报告。 - 保持本地优先：扫描和报告在你的机器或 CI 内运行。 ## 具体功能 给定一个 Vue / TS / JS 项目的路径，Archora 会： 1. 解析每个源文件（使用 TypeScript compiler API 解析 `.ts`/`.tsx`，使用 `@vue/compiler-sfc` 解析 `.vue`），跨 `tsconfig` 别名链解析导入，构建依赖图。 2. 运行 Tarjan 的 SCC 算法查找循环依赖；将直接循环（长度 ≤ 2）与间接循环区分开来。 3. 计算每个模块的 fan-in、fan-out、不稳定性、深度、耦合度和热度。 4. 将模块映射到 FSD 风格的分层（`shared → entities → features → widgets → pages → app`）上，并标记每一个指向错误方向的边。 5. 检查 `.archora.json` 中用户声明的契约：边界规则、包预算、API 稳定性和 bundle 阈值。 6. 如果你传入 `git log`，它会计算每个模块的变动，并查找时间耦合对 —— 即那些总是同时更改，但在它们之间没有静态边的文件。这通常意味着缺失了抽象。 7. 如果你传入 webpack/rollup 统计信息，它会查找 bundle 膨胀 —— 跨 chunk 重复的模块、重型 chunk、以及在 chunk 中占据主导地位的单个模块。 8. 以 JSON、Markdown 或独立的 HTML 文件输出结果报告，你可以将其发送给审查者。 在 10 个项目的参考语料库中，关于循环依赖、热点区域和分层违规的精确率/召回率保持在 F1 = 1.0。实时评分表见 [BENCHMARKS.md](./BENCHMARKS.md)。 ## 功能对比 | | Archora | madge | dependency-cruiser | knip | | ----------------------------------------------------------- | ------- | ----- | ------------------ | ------- | | 依赖图 | ✓ | ✓ | ✓ | 部分 | | 循环检测 (SCC) | ✓ | ✓ | ✓ | – | | 分层规则 | ✓ | – | ✓ (配置繁琐) | – | | 架构契约 (边界 / 预算 / API 冻结) | ✓ | – | 部分 | – | | Bundle 膨胀 (webpack / rollup 统计信息) | ✓ | – | – | – | | Server/client (RSC) 边界泄漏 | ✓ | – | – | – | | 时间耦合 (git 变动相关性) | ✓ | – | – | – | | 桌面 UI / 浏览器 | ✓ | – | – | – | | 独立的 HTML 报告 | ✓ | – | 部分 | – | | 本地优先，无遥测 | ✓ | ✓ | ✓ | ✓ | 与 `madge` 和 `dependency-cruiser` 的重叠之处在于依赖图和循环检测。而差异点则在于此后的所有功能 —— 分层/契约执行、bundle 和 git 信号融合到同一个报告中，以及一个你可以直接交给非 CLI 队友使用的桌面 UI。 ## 安装方式 npm 发布后： ``` npx @archora/cli init . --dry-run npx @archora/cli init . npx @archora/cli baseline write . -o .archora/baseline.json npx @archora/cli check . npx @archora/cli report . --format html -o archora-report.html ``` 推荐的 GitHub Actions 方式： ``` - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npx -y @archora/cli@1.0.3 check . --fail-on grade:F ``` 当前仓库的 checkout 方式： ``` git clone https://github.com/archora-dev/archora.git cd archora npm install npm run dev # web dev server (Vite) npm run tauri:dev # desktop dev (Tauri 2) npm run cli -- init ./your-project --dry-run npm run cli -- analyze ./your-project -o scan.json npm run cli -- report ./your-project --format html -o report.html ``` 从仪表板打开一个项目目录。Web 构建版本使用 File System Access API（Chromium 浏览器）。桌面构建版本使用 Tauri 的目录选择器。 ## CLI ``` archora init . --dry-run # inspect conservative config archora init . # write .archora.json archora baseline write . -o .archora/baseline.json # intentional mainline baseline archora check . # architecture budget / fail-on gate archora review . --base .archora/baseline.json --pr-comment archora report . --format html -o archora.html archora report . --format fix-plan -o fix-plan.json ``` 当违反阈值时，`check` 会以非零状态退出，因此它可以作为回归门禁直接插入到任何 CI 中。 ## 演示脚本 演练脚本位于： - [`apps/docs/guide/demo-script.md`](./apps/docs/guide/demo-script.md) 预期的流程是 Review → Impact → Cycles/Rules → Report。该产品不再使用全项目图作为主 UI。 ## 架构 采用 Feature-Sliced Design，并有一个硬性规则：`packages/core` 没有任何 Vue / Pinia / Tauri / 框架的导入，它可以在 Node 和 Web Worker 中不加修改地运行。UI 层遵循 `app → pages → widgets → features → entities → shared`。这两项规则均由 ESLint 强制执行，而不仅仅是约定。 ``` packages/ core/ analyzer pipeline, dependency model, diff, metrics, report builders, contract engine cli/ @archora/cli — thin wrapper around core src/ app/ providers, router, layouts, global stores pages/ route containers widgets/ architecture workspace, scan progress, search overlay, … features/ open-project, scan-project, export-report, apply-fix, layer-rules entities/ project / scan / history / export-history / settings Pinia stores shared/ UI primitives, hotkeys, i18n, Tauri runtime src-tauri/ Rust shell, IPC commands, file watcher apps/docs/ VitePress site (docs.archora.dev) ``` 分析器 pipeline： ``` discoverFiles → parseFiles → resolveImports → buildGraph → detectCycles → computeMetrics → rankHotZones → ScanResult ``` `FileSource` 是唯一的 IO 边界。目前已有针对 Node FS、浏览器 File System Access API、内存（测试、Web Worker payload）和 Tauri 的实现。 ## 许可证 **专有、源码可见、仅供付费使用。** 法律文本请参阅 [`LICENSE`](./LICENSE)，许可条款请参阅 [`COMMERCIAL-LICENSE.md`](./COMMERCIAL-LICENSE.md)。 **在没有付费商业许可证的情况下，你只能：** - 在 GitHub 上阅读源码。 - 克隆副本用于个人的短期评估（≤ 30 天），以决定是否购买许可证。 - 在合理使用 (fair use) 原则下引用或摘录简短片段。 **对于其他任何用途，你都需要付费商业许可证**，包括： - 在短期评估之外，针对任何代码库（你自己的或他人的）运行 Archora。 - 在 CI 中、工作工作站上或任何个人/爱好项目中使用它。 - 打包、重新分发、修改、托管 Archora 或将其作为服务提供。 - 将其源码或输出用于模型训练。 商业许可： | 层级 | 价格 | | ------- | ---------------------- | | Solo | $19/月 或 $190/年 | | Team | $49/席位/月 | | Company | 定制 | 联系方式：**[akotov@archora.dev](mailto:akotov@archora.dev)** · Telegram **@akotofff** 在接入结账与授权分发系统之前，试用密钥暂时使用手动的签名密钥流程： ``` npx @archora/cli@1.0.3 license request --plan trial --out license-request.md npx @archora/cli@1.0.3 license activate npx @archora/cli@1.0.3 license status ``` ## 状态 Archora CLI `1.0.3` 已为发布到 npm 做好准备。分析器核心、CLI、桌面包装器、报告、历史记录、契约引擎以及 bundle/RSC/时间耦合信号均已就绪。Architecture Explorer 现在以分析器为核心；旧版的产品图 UI 已被移除。剩余的外部发布工作包括：发布已签名的桌面制品、接入结账/授权分发系统以及录制公开演示视频。 ## 验证 ``` npm run lint npm run typecheck npm run test npm run build npm run bench # accuracy: precision/recall on reference corpus npm run bench -- --threshold-precision=0.9 # use as a hard gate ``` CI 会在每次 push 和 PR 时运行 `web`（lint + 类型检查 + 测试 + 覆盖率 + 构建 + `npm audit` + 性能门禁）和 `tauri`（cargo + bundle 冒烟测试）任务。 ## 链接 - 文档：[docs.archora.dev](https://docs.archora.dev) - Bug 报告、功能请求、授权：**akotov@archora.dev** · Telegram **@akotofff** - 基准测试：[BENCHMARKS.md](./BENCHMARKS.md) - 隐私：[PRIVACY.md](./PRIVACY.md) — 工具会接触哪些数据以及哪些数据会保留在磁盘上 - 安全政策：[SECURITY.md](./SECURITY.md)

标签：TypeScript, 依赖图, 前端架构, 可视化界面, 安全插件, 开源框架, 技术债, 持续集成, 自动化攻击, 错误基检测, 静态代码分析