onioncry

OnionCry

在 JavaScript 和 TypeScript 代码库中使用 OnionCry 检查架构边界。将其视为确定性验证工具：在目标代码库中运行它，查看输出，并通过最小幅度的架构或配置更改解决报告的边界问题。

本文档介绍已发布的 v0.1.0 命令接口。OnionCry 代码库中 .agents/skills/onioncry/ 下的副本是规范版本；每当 CLI 行为发生变化时，都必须更新该副本。

可用性

选择目标项目已在使用的包管理器：

bunx onioncry --help        # ad-hoc, no install (npx works too)
bun add -d onioncry         # per-project devDependency
cargo install onioncry      # global binary from crates.io

npm 包通过 optionalDependencies 仅安装与当前计算机匹配的平台二进制文件。没有 postinstall 脚本。

命令

每个子命令都接受 --help。

命令	用途	主要标志
check	根据架构规则检查已配置的文件范围	--format pretty|json|sarif、--fail-on error|warning、--llm-mode、--tips、--files <PATH>...、--baseline <PATH>、--write-baseline、--no-baseline、--config
explain <FILE>	说明单个文件的分类、导入和违规项	--format pretty|json、--tips、--config
graph	渲染边界依赖图	--format mermaid|json、--config
rules	列出内置规则	--format pretty|json
schema	输出 .onioncryrc JSON Schema	--write <PATH>
init	创建保守的 .onioncryrc.jsonc 模板	--force、--from-tsconfig [<PATH>]

--files 会将报告范围限定为列出的文件；分析仍会针对整个项目进行。

退出代码

退出代码约定属于公开 API：

• 0 — 在配置的阈值下没有问题（--fail-on 默认值为 error，因此只有警告时仍以 0 退出）
• 1 — 存在达到或超过 --fail-on 阈值的违规项
• 2 — 操作错误（缺少配置、用法错误）；请先修复，再解读架构诊断信息

工作流

1. 确认 CLI 可用：onioncry --help（或 bunx onioncry --help）。
2. 如果目标仓库没有配置，请在仓库根目录运行 onioncry init 创建配置。运行检查前，请先查看 .onioncryrc.jsonc。仅当用户明确要求覆盖现有配置时才使用 --force。对于带有路径别名的 TypeScript 项目，onioncry init --from-tsconfig 会根据 compilerOptions.paths 生成别名配置块，供你检查。
3. 运行 onioncry check。
4. 如需 Agent 可读的输出，优先使用 onioncry check --llm-mode 或 onioncry check --format json。与代码扫描集成时，请使用 --format sarif。
5. 诊断单个文件时，使用 onioncry explain <file>（可添加 --format json 或 --tips）。如需查看边界拓扑，请使用 onioncry graph。
6. 修改架构、导入、路径或配置后，重新运行触发该问题的同一条 OnionCry 命令。

llm-mode 报告

check --llm-mode 会打印摘要标题（包含 status、filesChecked、problemCount、errorCount、warningCount、groupCount），随后列出诊断分组，每组包含 rule、severity、message、why、tip 和 locations。报告末尾带有一个带版本号的页脚：

onioncry-llm-report v1 revision: <hash>

将页脚视为完整性标记：如果缺少页脚，说明报告被截断。页脚版本是公开契约。

违规基线（在旧版仓库中引入 OnionCry）

基线会将现有问题纳入记录，使新增违规仍会导致检查失败，同时将已知问题记录在可供审查的文件中：

onioncry check --write-baseline   # record current violations in .onioncry-baseline.json
onioncry check                    # consumes the baseline by default; only new debt fails
onioncry check --no-baseline      # full, unfiltered architecture result
onioncry check --baseline <PATH>  # use a baseline at a custom path

基线条目按 rule + file + target 生成指纹（不包含行号和列号，因此常规编辑不会导致条目失效）。过时条目（即与当前任何违规都不匹配的基线条目）会输出非阻断性的 stderr 警告，建议重新运行并添加 --write-baseline。提交基线文件，并随着时间推移逐步缩减它（逐步收紧），绝不要为了压下新违规而扩大基线。

配置

• OnionCry 会优先查找 .onioncryrc.jsonc，然后查找 .onioncryrc.json。JSONC 注释属于公开契约。
• 请在配置中明确设置别名解析。init --from-tsconfig 是根据 tsconfig 推导别名的受支持方式；提交前请检查生成的配置块。
• 如果 monorepo 中各软件包的边界规则不同，请使用软件包本地配置。
• 在 Bun/Turbo 工作区中，添加调用 OnionCry 的软件包脚本，然后通过工作区运行器从根目录分发执行：

{
  "scripts": {
    "onioncry": "bunx onioncry check --llm-mode"
  }
}

修复策略

• 如果诊断指出存在实际的架构违规，请修复代码边界。
• 仅当规则范围、别名或软件包边界有误时，才修改 .onioncryrc.jsonc。
• 不要将 Oxlint、TypeScript、Biome 和通用格式问题纳入 OnionCry 修复范围。OnionCry 负责架构边界检查，而非所有 JavaScript 或 TypeScript 规则。
• 优先将代码调整为符合预期的依赖方向，而不是抑制规则。
• 优先修复违规，而不是将其纳入基线；--write-baseline 用于引入工具，而非掩盖新增问题。

注意事项

• 对配置范围之外的路径（包括不存在的文件）运行 explain，会返回 layer: unclassified，并以退出码 0 结束。请先确认路径，再采信“unclassified”结果。
• 退出码为 0 不代表没有发现问题：默认 --fail-on error 下，警告不会导致检查失败。请查看报告中的 warningCount；如果警告也必须阻断检查，请使用 --fail-on warning 运行。

开发检查

修改 OnionCry 本身时，请在 OnionCry 仓库中运行项目验证命令：

make verify

针对 Rust 的定向开发，请使用该仓库中范围更小的检查：

cargo fmt --all -- --check
cargo check
cargo clippy --all-targets --all-features -- -D warnings
cargo test