Archprint

项目简介

Archprint 是一款开源 TypeScript 架构 lint 工具，能够从代码库的导入依赖图中自动挖掘已有的架构规则，并将其转换为可直接安装的 ESLint 规则。用户无需手动编写规则，Archprint 通过静态分析推断出代码已经遵守的边界，然后附上统计数据置信度，只将高置信度的规则自动生成并写入配置文件，其余结构推断类规则交由人工复核。

核心功能

• 导入图静态分析：扫描 TypeScript 代码库的完整导入图，理解模块间的依赖关系和边界
• 规则自动推断：从真实代码中推断架构规则，包括禁止循环依赖、层级边界、UI/数据分离、入口纯净性等
• 置信度门控机制：采用 Wilson Score 下界统计方法评估每条规则的可靠性，只在 95% 置信区间下界达到 90% 以上时自动生成规则
• 多框架适配：自动识别 Next.js、Nest、SvelteKit、Nuxt、Remix 等主流框架，对 React Angular Vue Svelte 组件进行分类
• 规则自动写入：将推断出的规则以 ESLint 插件格式写入 archprint-rules/ 目录，支持自动接入现有 ESLint 或 dependency-cruiser 配置
• 循环依赖检测：确保模块依赖图保持无环状态，防止隐式的强耦合蔓延
• 测试隔离验证：确保生产代码不会导入测试或 spec 文件，保持代码纯净性
• Phantom 依赖检测：捕获未在 package.json 中声明的传递依赖，防止隐式引入
• 导入风格规范：推荐使用 workspace alias 路径别名而非深层相对导入，提升代码可读性
• Console 隔离规则：确保非 CLI 库代码不调用 console.* 方法，防止生产环境日志泄露

技术实现

Archprint 的核心工作流程分为三个阶段。第一阶段是导入图构建，Archprint 解析 TypeScript 项目的 tsconfig.json 和全部 .ts/.tsx/.vue/.svelte 文件，构建精确的模块依赖图，同时利用 Wilson Score 下界评估每条候选规则的统计置信度。第二阶段是规则推断，对于机械类规则家族（如禁止循环依赖、生产代码不导入测试文件、不导入 dependency 内部 src 等），由对抗性正确性审计确认零误报后，直接自动生成为 enforcement 规则；对于结构推断类规则家族（如层级边界、UI/数据分离等），因路径推断的 layer/role 可能存在偏差，默认保留供人工复核，用户可通过 --include-structural 参数自行决定是否生成。第三阶段是规则写入，archprint generate 将规则输出为 archprint-rules/ 目录下的规则文件及 ESLint 配置文件，archprint wire 自动检测项目现有的 enforcement 工具并插入托管引用，实现零破坏性接入，已在 92,861 个真实公开 TypeScript 仓库上完成全量扫描和全流程往返测试，零崩溃。

快速上手

第一步：安装 Archprint

在项目中执行以下命令安装 archprint 作为开发依赖：

npm install --save-dev archprint

第二步：初始化项目配置

执行 init 命令，Archprint 会自动检测项目使用的技术栈，并将推断规则写入 archprint.json 配置文件：

npx archprint init apps/web

第三步：扫描代码库查看规则

运行 scan 命令，查看代码库当前已经遵守的架构规则及其统计数据和置信度：

npx archprint scan apps/web

第四步：生成并接入规则

将自动信任的规则（mechanical families）写入 archprint-rules/ 目录并接入 ESLint 配置：

npx archprint generate apps/web --out archprint-rules
npx archprint wire

如需包含结构推断类规则，请添加 --include-structural 参数。

第五步（可选）：推荐规则集

对于新项目或代码量较少的仓库，使用 recommend 命令获取基于 92,861 个真实 TypeScript 仓库统计数据的推荐规则集：

npx archprint recommend apps/web

适用人群

• TypeScript 开发团队：希望建立并强制执行代码架构规范，无需手动编写和维护 lint 规则
• AI 编程工具用户：Claude Code、Cursor、Windsurf 等 AI 编程助手用户，希望保持 AI 生成代码的架构一致性
• 代码审查者和架构师：需要快速了解大型代码库的架构边界和潜在违规问题
• 工程团队负责人：推动架构规范落地，需要数据驱动的规则生成而非主观定义