用途:为 JavaScript/TypeScript 仓库安装机械化的模块边界与文件放置检查,使越界导入在构建/CI 中失败,而非依赖代码评审。规则是:模块 M 之外的文件只能通过 M 的公共入口(通常为 index.ts barrel)导入 M,M 内部文件彼此自由导入。语义决策(模块划分与入口)写在 module-boundaries.json 地图中,转换为 lint 规则则是确定性的,因此只编辑地图,不编辑生成的配置。
主要能力:提供依赖喷射(dependency-cruiser)配置生成器、CI 工作流模板,以及三个放置检查脚本(root-files-check.mjs、kind-folder-check.mjs、earned-shared-check.mjs,共用 module-map.mjs 读取地图)。检查内容涵盖:只能经公共入口导入、可选的方向性分层、模块根目录允许散放的文件、按名称禁止 utils/types/helpers 等 kind 文件夹、以及仅被单一模块引用的共享层符号(按符号而非按文件计数)。放置检查无法被依赖图覆盖,需单独计入。
使用方式:检测包管理器与锁文件、源码位置、tsconfig,然后按工作区生成 module-boundaries.json;将配置放入 <workspace>/scripts/,从工作区根运行 depcruise 扫描 src,安装依赖 <pm> add -D dependency-cruiser,并添加 package script,例如 bun 用 "boundaries": "bun --bun x depcruise --config scripts/dependency-cruiser.cjs src"。首次运行暴露真实泄漏,优先修复(改为经公共入口导入),确属超出范围的可用 baseline 文件记录并加 --ignore-known。放置脚本加入 quality 脚本,CI 复制 module-boundaries.yml,替换 {{SWAP_FOR_YOUR_PM}} 与 {{WORKSPACE_DIR}}。结构变化时需更新地图(新增 path、publicEntry、placement.rootFiles),可在 CLAUDE.md/AGENTS.md 中说明。
限制:仅适用于具备真实内部结构的 TS/JS 仓库;若模块地图只列一个巨型模块或公共入口为 .*,则实际不检查任何内容。baseline 是唯一允许的豁免通道,应逐步缩减;不得放宽正则。缺失信息:未提供具体价格、平台支持范围或性能数据。