gkhan205/arcovia

 # Arcovia **理解、衡量并改进 React 和 Next.js 应用的架构。** Arcovia 会扫描项目，构建其依赖模型，评估确定性的架构规则，并生成具有可操作性的架构报告。它旨在回答三个实用问题： 1. 这个前端架构健康吗？ 2. 为什么得到这个分数？ 3. 团队应该优先修复什么？ Arcovia 的发现和评分完全来自确定性的静态分析。 ## 快速开始 在你要检查的项目中运行 Arcovia： ``` npx arcovia analyze . ```  ## 为什么选择 Arcovia？ | 传统工具 | Arcovia | | --- | --- | | Lint 警告 | 架构智能 | | 文件级检查 | 全项目分析 | | 难以确定优先级 | 优先级热点和 Quick Wins | | 没有架构评分 | 可解释的架构评分 | | 静态诊断 | 可操作的路线图 | ## 支持的框架 - ✅ React - ✅ Next.js - ✅ Vite - 🧪 Remix（实验性 React 兼容分析） ## 功能 - ✅ 架构评分 - ✅ 依赖图 - ✅ 热点 - ✅ Quick Wins - ✅ 架构时间线 - ✅ 离线 HTML 报告 - ✅ JSON 报告 - ✅ 确定性规则 - ✅ 无需云服务 ## 隐私 Arcovia 完全在你的本地机器上运行。没有任何源代码会离开你的计算机，无需注册账号，并且 Arcovia 不收集任何遥测数据。 ## 报告 每次分析都会生成终端摘要以及可移植的报告： - `report.html` — 离线交互式架构报告 - `analysis.json` — 带有版本号的、机器可读的分析工件 HTML 报告包含： - 架构评分、字母等级和可见的分数计算过程 - 基于证据的架构概述和已证实的优势 - 可筛选的发现，包含位置、证据和建议 - 分组的依赖图，将用户代码与外部包区分开 - 类别健康度和评分贡献因素 - 热点、Quick Wins 以及三步重构路线图 - 可选的同业基准上下文 - 从之前归档的 Arcovia 报告中提取的分数时间线 或者全局安装它： ``` npm install -g arcovia arcovia analyze . ``` 默认情况下，Arcovia 会将报告写入所分析项目的 `.arcovia-report` 目录中： ``` .arcovia-report/ analysis.json report.html ``` 在任何浏览器中打开 `report.html`。它是完全独立的：不需要服务器、账号或网络连接。 ## 命令 ``` # 分析当前项目并创建 HTML + JSON 报告 arcovia analyze . # British-English 别名 arcovia analyse . # 分析另一个项目 arcovia analyze ../my-next-app # 选择输出目录 arcovia analyze . --output ./reports # 仅生成选定的 artifacts arcovia analyze . --html arcovia analyze . --json # 生成 HTML 报告并在默认浏览器中打开 arcovia analyze . --open # 检查 CLI 环境 arcovia doctor ``` ## 报告历史与时间线 Arcovia 会将最新的报告保存在可预测的路径中，并在每次新分析时归档之前的版本： ``` .arcovia-report/ analysis.json report.html history/ analysis-2026-07-18T12-00-00-000Z.json report-2026-07-18T12-00-00-000Z.html ``` 下一次报告会读取已归档的分析工件，并在 HTML 时间线中显示最多八个历史评分点。定期运行 Arcovia —— 每周运行或在 CI 中运行，可以让架构进展随时间变得可见。 ## 评分 Arcovia 不仅仅是简单地对发现的问题进行计数。最终评分旨在奖励健康的类别，同时确保真正的架构债务保持可见。 ``` 100 − category deductions − maintenance-burden adjustment − critical-risk adjustment = final architecture score ``` ### 类别健康度 规则发现会影响以下加权类别： | 类别 | 权重 | | --- | ---: | | 架构 | 30% | | 导入 | 15% | | 组件 | 15% | | 复杂度 | 10% | | Hooks | 10% | | 性能 | 10% | | Context | 5% | | 路由 | 5% | 重复的发现采用递减的惩罚机制，并且某些基础规则设有上限，因此数百个几乎相同的信号不会主导最终结果。 ### 维护负担 大量的警告、错误和信息性债务会应用一个单独的、有上限的调整。这可以防止一个有许多可操作发现的项目看起来完美无瑕，同时也避免了走向另一个极端，使项目看起来无可救药。 ### 严重风险 经验证的严重发现会应用 `10 + 8 + 6 + 4` 分的有限调整（最高 28 分）。 报告会将此项与类别健康度分开显示。 ### 等级 | 分数 | 等级 | | --- | --- | | 97–100 | A+ | | 93–96.99 | A | | 90–92.99 | A− | | 85–89.99 | B+ | | 75–84.99 | B | | 65–74.99 | C+ | | 55–64.99 | C | | 40–54.99 | D | | 低于 40 | F | 在热点、Quick Win 或路线图项目中显示的预计恢复分数，仅是相关类别的加权扣分值。它是一个规划估算，而不是重构后最终分数的保证。 ## Arcovia 当前评估的发现 示例包括： - 循环模块依赖 - 孤立模块 - 重复导入 - 未使用的内部导出 - 过大的组件和深层嵌套的 JSX - 上帝模块 - 高扇入和高扇出模块 - 深层依赖链 框架感知行为避免了 Next.js 常见的误报，包括如 `GET` 和 `POST` 这样的路由处理方法、路由页面导出，以及 Next.js 的元数据导出如 `generateMetadata`、`generateStaticParams` 和 `revalidate`。 ## 基准测试 无需文件即可运行内置的 Arcovia 质量带基线： ``` arcovia analyze . --benchmark ``` 这提供的是阈值上下文，而不是关于同业百分位数的声明。提供一个带版本号的基准配置文件以获取真实的同业环境比较： ``` arcovia analyze . --benchmark ./arcovia-benchmark.json ``` 示例配置文件： ``` { "cohort": "Next.js production applications", "framework": "next", "sampleSize": 40, "score": { "p25": 55, "p50": 70, "p75": 85 }, "version": "2026.07" } ``` Arcovia 会将最终得分与分布情况进行比较： | 分数 | 报告标签 | | --- | --- | | 达到或高于 p75 | 头部四分之一 | | 达到或高于 p50 | 中位数以上 | | 达到或高于 p25 | 中间水平 | | 低于 p25 | 中位数以下 | 基准测试框架必须与扫描的项目相匹配。如果没有提供配置文件，或者配置文件不匹配，报告会明确指出无法进行同业比较，而不是捏造一个百分比。 ## 环境要求 - Node.js 22 或更高版本 - 仓库开发需要 pnpm 10 或更高版本 ## 开源 Arcovia 基于 [MIT License](LICENSE) 发布。在贡献代码之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)、[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 和 [SECURITY.md](SECURITY.md)。常规帮助请参阅 [SUPPORT.md](SUPPORT.md)，已发布的 更新记录在 [CHANGELOG.md](CHANGELOG.md) 中。有关项目品牌使用和徽标/图标来源，请参见 [TRADEMARKS.md](TRADEMARKS.md)。 ## 开发 ``` pnpm install pnpm build pnpm test pnpm lint pnpm typecheck ``` 使用以下命令运行本地编译的 CLI： ``` node dist/cli.js analyze . ``` ## 仓库布局 ``` src/ cli/ command interface core/ pipeline orchestration and report history scanner/ file discovery parser/ AST parsing graph/ dependency relationships rules/ deterministic checks score/ architecture scoring reporters/ terminal, JSON, and offline HTML rendering ``` ## 路线图 - GitHub Action - VS Code 扩展 - 报告比较 - 扩展的趋势分析 - 团队仪表板 - AI 架构教练（基于云，选择加入） ## 体验 Arcovia ``` npx arcovia analyze . ``` 如果你发现了 bug 或者有好的想法，我们非常欢迎你通过 [GitHub Issues](https://github.com/gkhan205/arcovia/issues) 和 [GitHub Discussions](https://github.com/gkhan205/arcovia/discussions) 提供反馈。

标签：MITM代理, React, Syscalls, WebSocket, 云安全监控, 依赖分析, 前端架构, 自动化攻击, 静态分析