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>	1 つのファイルの分類、インポート、違反内容を説明する	--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 から aliases ブロックが生成されます。
3. onioncry check を実行します。
4. エージェントが読み取りやすい出力には、onioncry check --llm-mode または onioncry check --format json を使用してください。コードスキャンとの統合には --format sarif を使用します。
5. 1 つのファイルを診断するには、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 でフィンガープリント化されます（行番号や列番号は含まれないため、通常の編集では項目が無効になりません）。古くなった項目、つまり現在の違反に一致しないベースライン項目がある場合は、--write-baseline を付けて再実行するよう促す、ブロックされない stderr 警告が出力されます。ベースラインファイルをコミットし、時間をかけて縮小してください（ラチェット）。新しい違反を黙らせるために増やしてはいけません。

設定

• OnionCry はまず .onioncryrc.jsonc を検索し、次に .onioncryrc.json を検索します。JSONC のコメントは公開仕様です。
• エイリアスの解決は設定で明示してください。tsconfig からエイリアスを導出する方法としてサポートされているのは init --from-tsconfig です。コミットする前に、生成されたブロックを確認してください。
• パッケージごとに境界ルールが異なるモノレポでは、パッケージごとの設定を使用してください。
• 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