Archrad Deterministic Mcp

@archrad/deterministic

コードを1行も書く前に、アーキテクチャは乖離し始めます。archrad validate は、その乖離を決定論的に、CI で、PR がマージされる前に検出します。

システムをグラフとして定義します。ArchRAD はそれをコンパイルし、アーキテクチャルールに照らしてリントし、意見ではなくルールコードとともに、何が問題なのかを正確に示します。

0.7.x の新機能 — archrad demo はセットアップなしで完全なサンプルを実行し、archrad scan はあらゆるリポジトリから、すべてのノードに file:line の引用を付けた IR を作成します。このリリースではリント結果は減少するのみです。0.6.x で合格したものが不合格になることはありません。 変更履歴をご覧ください。

---

クイックスタート（60秒）

npm install -g @archrad/deterministic
archrad demo

IR ファイルも、フラグも、設定も不要です。どのディレクトリからでも実行できます。バンドルされたサンプルをリントし、結果を表示します。

    orders-api (http)  ──▶  orders-db (postgres)

⚠️ IR-LINT-DIRECT-DB-ACCESS-002: API node "orders-api" connects directly to datastore node "orders-db"
   Fix: Introduce a service or domain layer between HTTP handlers and persistence.
⚠️ IR-LINT-MISSING-AUTH-010: HTTP entry node "orders-api" has no auth node or auth config …
⚠️ IR-LINT-NO-HEALTHCHECK-003: No HTTP node exposes a typical health/readiness path …

次に、自分のリポジトリで実行します

archrad scan . --out draft.ir.json    # draft an IR — every node cited to file:line
archrad validate --ir draft.ir.json   # lint it

scan は、Docker Compose、Kubernetes マニフェスト、Terraform、OpenAPI、パッケージマニフェスト、ソースコードを読み込み、すべてのノードを信頼度で評価します。これにより、解析されたものと推測されたものを確認できます。出力は通常の IR ファイルです。内容を確認・編集し、コミットしてください。

OpenAPI 仕様または Backstage カタログがすでにある場合は、スキャンを省略できます。

archrad ingest openapi --spec ./openapi.yaml --out ./graph.json
archrad ingest backstage --catalog . --out ./graph.json

グラフをコミットしたら、archrad validate を CI のゲートとして使用します。終了コード 1 によりマージがブロックされます。

---

機能

ArchRAD はブループリントコンパイラーであり、ガバナンスレイヤーです。アーキテクチャを IR（ノード、エッジ、許可される接続）として定義すると、ArchRAD は決定論的なルールエンジンに照らして検証します。同じ IR、同じルール、同じ入力であれば、常に同じ結果が得られます。

コマンド	検証内容	コード
archrad validate	グラフ構造 + アーキテクチャリント	IR-STRUCT-* IR-LINT-*
archrad lint	アーキテクチャリントのみ（高速な開発ループ向け。構造チェックは省略）	IR-LINT-*
archrad explain <code>	パスを実行せずに、標準ルールのガイダンスを表示	—
archrad policies-sha256 --dir <policies>	署名済み PolicyPack 用の archrad-policy-pack.sha256 マニフェストを生成	—
archrad validate-drift	IR とディスク上の生成済みコードを比較	DRIFT-*
archrad scan	リポジトリからドラフト IR を作成 — トポロジー、OpenAPI、マニフェスト、コード。すべてのノードに引用と信頼度評価を付与	—
archrad reconstruct	ソースコードのみからドラフト IR を作成（scan の4つのシグナルソースの1つで、単独でも使用可能）	—
archrad ingest openapi	OpenAPI から IR を導出（--spec にはローカルパスまたは https URL、URL の認証ヘッダーには -H を使用）	—
archrad ingest backstage	Backstage の catalog-info.yaml → IR（Component、Resource、API、System。Location のファイルターゲット）	—
archrad fragment merge	2つ以上の IR ファイルをマージ — node.id で統合（競合は stderr へ出力）。互いに素な和集合には --prefix-fragments を使用	—
archrad export	IR を FastAPI または Express + Docker にコンパイル	—

取り込みとマージのワークフロー： docs/INGEST.md。全コマンド／フラグ： docs/CLI_REFERENCE.md。コード生成（export）： docs/EXPORT.md。

---

実際のリポジトリから IR をドラフトする（archrad scan）

archrad scan はリポジトリを指定して、ドラフト IR を出力します。最終回答ではなく、必ずレビューして編集する必要があります。推測の度合いに応じて評価された 6 つのエクストラクターを実行します。

ソース	シグナル	信頼度
トポロジ	docker-compose.yml、Kubernetes マニフェスト	高 — 実際の宣言を解析します
インターフェース	OpenAPI / Swagger	中 — 実際のインターフェースを記述しますが、記載されている内容に限られます
Infrastructure-as-code	Terraform（*.tf）	中 — 実際の宣言ですが、真の HCL パースではなく正規表現で読み取ります
マニフェスト	package.json、requirements.txt、go.mod、pom.xml	低 — ドライバーの依存関係は接続を示唆しますが、実際に使われている証拠ではありません
コード	ソースコードのパターンスキャン（Node.js/TS、Python、C#）	低 — テキストに対する正規表現であり、意味的な理解はありません

すべてのノードとエッジには config.provenance[] が付与され、inferred_from: "file:line"、confidence、検出したエクストラクターが記録されるため、何も根拠なく信じる必要はありません。複数のエクストラクターが同じ内容を記述している場合、scan は重複やエラーを発生させずにそれらを統合します（信頼度が最も高い本文を保持し、すべての来歴情報を統合します）。

archrad scan . --dry-run                       # print the draft, write nothing
archrad scan ./server --out draft.ir.json       # write it
archrad scan . --extractors compose,manifest    # only run specific extractors
archrad scan . --scope all                      # include tests, examples, docs, and demos

CLI スキャンでは、フィクスチャ、ドキュメントの例、Storybook のストーリー、テスト専用のマニフェストが本番環境の検出結果にならないよう、デフォルトで --scope production が設定されます。これらのアーティファクトをレビュー対象にする場合は、--scope all を使用してください。ライブラリの呼び出しでは、後方互換性を保つため、デフォルトは scope: 'all' のままです。

出力は通常の IR ファイルです。レビュー後、そのまま archrad validate にパイプで渡せます。すべてのフラグについては、docs/CLI_REFERENCE.md を参照してください。

---

実装ガバナンス（archrad reconstruct + --codebase）

「IR は問題なさそうですが、実際にリリースされたものもそうなっていますか？」

上記の検証パイプラインは、作成した IR（設計上の契約）をチェックします。--codebase フラグは、ソースコードから IR を再構築して比較することで、実際のコードベースとのギャップを埋めます。

「ダミー IR」攻撃 — その検出方法

開発者は、実際のコードが文書化されたアーキテクチャを回避していても、準拠した IR（すべての IR-STRUCT-* および IR-LINT-* ルールに合格するもの）を作成できます。最も危険なパターンは、IR ではクリーンなサービスレイヤーが示されている一方、コードではデータベースに直接クエリーしているケースです。

# Catch discrepancies between the authored design and the shipped code
archrad validate --ir authored-ir.json --codebase ./src --report findings.html

--codebase が指定されると、パイプラインは次の 3 つのステージを実行します。

1. 作成した IR に対する IR-STRUCT-* 構造検証
2. 作成した IR に対する IR-LINT-* アーキテクチャリンティング
3. 作成した IR と再構築したコードベース IR の比較（IR-DRIFT-IMPL-*）

IR-DRIFT-IMPL-* ルール

実装のドリフトには個別の終了しきい値が適用されます。--fail-on、--fail-on-warning、--max-warnings は IR-STRUCT-、IR-LINT-、および統合された PolicyPack の検出結果にのみ適用されます。IR-DRIFT-IMPL-* は --impl-drift-fail-on のみで判定されます（デフォルトでは、ドリフトの重大度が error の場合にコマンドが失敗します）。

コード	重大度	検出内容
IR-DRIFT-IMPL-000	warning	ドリフト比較のために作成した IR を解析できませんでした（まず構造上の問題を修正してください）
IR-DRIFT-IMPL-001	warning	IR は HTTP のようなエントリーノードを宣言していますが、再構築時に --codebase でアーティファクトが 0 件検出されました
IR-DRIFT-IMPL-002	warning	コードに HTTP / ヘルスルートがありますが、作成した IR に HTTP のようなノードがありません
IR-DRIFT-IMPL-003	error	コードに DB への直接接続がありますが、作成した IR に DB エッジがありません
IR-DRIFT-IMPL-004	error	コードの HTTP ルートが作成した IR にありません
IR-DRIFT-IMPL-005	warning	コードにサービス間呼び出しがありますが、作成した IR にエッジがありません
IR-DRIFT-IMPL-006	info	コードに認証ミドルウェアがありますが、作成した IR に認証ノードがありません

IR-DRIFT-IMPL-003 は重要なルールです。ここでエラーが発生した場合、作成した IR が DB への直接依存を隠していることを意味します。

単独で再構築する

# Just reconstruct — write the IR without comparing
archrad reconstruct --from ./src --output reconstructed-ir.json

# Force language detection
archrad reconstruct --from ./src --language python --output py-ir.json

# Print to stdout (dry-run)
archrad reconstruct --from ./src --dry-run

# Show every detected artifact
archrad reconstruct --from ./src --verbose

対応言語

言語	検出されるパターン
Node.js / TypeScript	Express、Fastify、NestJS のルートとコントローラー；BullMQ ワーカー、Agenda ジョブ、cron スケジュール；pg、Prisma、TypeORM、Sequelize、Mongoose、Redis、BullMQ、Firebase；Passport、express-jwt、NestJS ガード、Auth0、Okta、Keycloak、Cognito；axios、got、node-fetch、gRPC；送信先ごとに抽出される送信 HTTP URL
Python	Flask、FastAPI、Django URL、DRF @action；SQLAlchemy、psycopg2、asyncpg、PyMongo、motor、redis-py；login_required、jwt_required、FastAPI OAuth2；requests、httpx、aiohttp、gRPC
C#	Minimal API の MapGet/MapPost；ASP.NET Core の [HttpGet]/[ApiController]；EF Core DbContext、Npgsql、Dapper；[Authorize]、AddAuthentication、JWT bearer；HttpClient、gRPC、RestSharp

サービスの分解（Node.js）

リコンストラクターはサービス境界を検出し、すべてを単一のゲートウェイにまとめるのではなく、サービスごとに1つのノードを作成します。

構成	検出シグナル	結果
routes/ または controllers/ ディレクトリ内のファイル	専用ファイル内の router.get/post/…	ファイルごとに1つの service ノード
NestJS コントローラー	@Controller デコレーター / *.controller.ts という命名	コントローラーファイルごとに1つの service ノード
app.listen() を含むエントリーファイル	他のルーターをマウント	gateway ノード
BullMQ / Agenda / cron ファイル	new Worker(…)、agenda.define(…)	worker ノード
モノリシックファイル（すべてのルートが1つのファイルにある）	単一ファイルで、routes/ ディレクトリがない	単一の gateway ノード — 強制的な分割は行いません

ノード間のエッジには、再構築で検出された内容が反映されます。

• 分解されたすべてのサービスに対して、gateway → service エッジが追加されます。
• service → database エッジは、ルートファイル自体に DB インポートまたは環境変数の参照がある場合にのみ作成されます（共有ユーティリティモジュールの背後に DB アクセスが隠れている場合は作成されません）。

ノードの命名

DB ノードとキャッシュノードには、ユーザーが最も認識しやすい名前を使用します。

1. 環境変数名 — process.env.REDIS_URL → ノード名は "redis"、process.env.SESSION_REDIS_URL → "session-redis"
2. 接続変数名 — const userDb = new Pool(…) → ノード名は "userDb"（変数名が一意の場合）
3. ライブラリ / ドライバー名 — 環境変数名や名前付き変数を検出できない場合のフォールバック

ノード ID と名前に env_var やその他の検出方法に関するメタデータが含まれることはありません。

外部サービスの識別

送信 HTTP/gRPC 呼び出しでは、送信先ごとに個別の外部ノードが作成されます。

• axios.post('https://api.stripe.com/…') → ノード "stripe"
• fetch('https://auth0.com/oauth/token') → ノード "auth0"
• new PaymentServiceClient('payments-svc:50051') → ノード "payment"（gRPC）
• URL を検出できないクライアントには、共通の "external-service" ノードを1つ使用する一般的なフォールバック

スコープの制限について

再構築で得られるのは確実な情報ではなく、可能な限りのシグナルです。

1. 動的なパターン — eval、リフレクション、メタプログラミング、生成コードは検出されません。
2. 実行時設定 — 実行時に行われるトポロジーの決定（機能フラグ、設定に基づくルーティング）は静的に解析できません。
3. 複数言語にまたがるサービス — 1つのコードベースに複数の言語ランタイムが含まれている場合、精度が低下します。
4. 複雑な抽象化 — マクロベースのフレームワークやアノテーションプロセッサーを多用するフレームワークでは、ルートや接続が見えにくくなることがあります。
5. 共有データアクセスレイヤー — DB 接続がルートファイル自体ではなく、共有ユーティリティファイル（例：db.ts、firebaseAdmin.ts）にある場合、それらの接続は個々のサービスノードにリンクされません。再構築された IR では、静的に追跡できないエッジを正直に省略します。

再構築された IR の lint 検出結果の解釈

再構築された IR に対して archrad validate を実行すると、次のような検出結果が表示されることがあります。

検出結果	再構築された IR での状況	解釈
IR-LINT-DEAD-NODE-011（サービスノード、出力エッジなし）	サービスが共有データアクセス層を使用している場合は想定どおりです	実際の問題ではありません。ルートファイルには直接検出された下流エッジがありません
ゲートウェイの IR-LINT-HIGH-FANOUT-004	大規模なモノレポでは想定どおりです	ゲートウェイからサービスへのエッジ数は、ルートファイル数を反映しています
ゲートウェイの IR-LINT-DIRECT-DB-ACCESS-002	実際の検出結果です	エントリーファイル内のルートが、サービス層を介さずに DB に直接アクセスしています
IR-LINT-NO-HEALTHCHECK-003	ヘルスエンドポイントが別の routes/health.ts サービスノードにある場合に検出されることがあります	ヘルスルートにエントリーポイントから到達できるか確認してください

再構築された IR での IR-LINT-DIRECT-DB-ACCESS-002 は、特に重要なルールです。gateway ノードで検出された場合、エントリーファイル自体が DB に直接アクセスしており、サービス層に委譲されていないことを意味します。分解によってゲートウェイとデータベースの間にサービスノードが正しく特定されていれば、このルールは検出されないはずです。

再構築された IR は、正解ではなく、人が確認するための下書きとして扱ってください。 作成されたアーキテクチャと実際のコードとの明らかな乖離を見つけるために使用し、システムの確定的な全体像として扱わないでください。

IR-DRIFT-IMPL-* の検出結果は、絶対的な事実ではなく、**「要確認」**として扱ってください。再構築された IR が示すのは手がかりであり、確実な情報ではありません。

実例 — 「ダミー IR」を見つける

作成された IR（authored.json）には、きれいなレイヤードアーキテクチャが示されています。

{ "graph": { "nodes": [
  { "id": "api", "type": "gateway", "name": "API" },
  { "id": "svc", "type": "service", "name": "Order Service" },
  { "id": "db", "type": "postgres", "name": "Orders DB" }
], "edges": [
  { "from": "api", "to": "svc" },
  { "from": "svc", "to": "db" }
]}}

しかし、src/api/routes.ts には次の内容があります。

import { Pool } from 'pg';
const db = new Pool({ connectionString: process.env.DATABASE_URL });
// direct DB query in the route handler — bypasses the service layer
app.get('/orders', async (req, res) => res.json(await db.query('SELECT * FROM orders')));

archrad validate --ir authored.json --codebase ./src を実行します。

❌ IR-DRIFT-IMPL-003: Direct database connection(s) detected in code (pg (PostgreSQL) → postgres) but no DB edges exist in the authored IR
   Fix: Either add the missing DB edges to the authored IR, or confirm the codebase points to the correct service.
   Suggestion: This discrepancy is a governance red flag: the authored IR could be masking a direct DB dependency.
   Impact: CRITICAL — this pattern is exploited in "dummy IR" attacks where clean design docs conceal direct database access in shipped code.

IR では DB に直接アクセスしないとされていましたが、コードは異なる状態を示していました。IR-DRIFT-IMPL-003 がその差を検出しました。

プロジェクト設定（archrad.yml）

リポジトリのルートに archrad.yml を配置すると、フラグを再入力せずに済みます。

# archrad.yml
ir: ./archrad-graph.json
target: python
output: ./generated
failOn: warning
policies: ./policies

archrad validate          # uses ir, failOn, policies
archrad export            # uses ir, target, output
archrad validate-drift    # uses ir, target, output

archrad は CWD から上位のディレクトリをたどり、archrad.yml（または archrad.yaml）を探します。明示的に指定した CLI フラグは、常に設定より優先されます。検出されたファイルを無視するには --no-config を使用し、標準外の場所を指定するには --config <path> を使用してください。完全なスキーマについては、docs/CONFIG.md を参照してください。

高速な開発ループ：archrad lint + archrad explain

# Iterate on lint without re-checking IR structure every run:
archrad lint --ir ./graph.json

# Focus on a single rule while fixing it:
archrad lint --ir ./graph.json --rule IR-LINT-MISSING-AUTH-010

# Understand a rule code without running a pass:
archrad explain IR-LINT-DIRECT-DB-ACCESS-002
archrad explain --list                  # every known rule code

archrad lint は高速な開発ループに使用します。CI ゲートの前には一度 archrad validate を実行し、IR の構造も検証してください。リポジトリのルートに archrad.yml があれば、どちらもフラグなしで実行できます。

CI 連携

# Fail on any structural error (default):
archrad validate --ir ./graph.json

# Also fail on lint warnings:
archrad validate --ir ./graph.json --fail-on-warning

# Machine-readable output for GitHub Actions:
archrad validate --ir ./graph.json --json

MCP サーバー（Cursor / Claude Desktop）

インストール後、archrad-mcp を PATH から利用できます。IDE に追加してください。

{
  "mcpServers": {
    "archrad": { "command": "archrad-mcp" }
  }
}

エージェントは、6 つの MCP ツール（例：archrad_validate_ir、archrad_lint_summary、archrad_validate_drift、archrad_policy_packs_load、archrad_list_rule_codes、archrad_suggest_fix）を使って、CLI と同じエンジンを呼び出せます。パラメーターとローカルでのテストについては、docs/MCP.md を参照してください。

---

仕組み（アーキテクチャ）

IR (nodes/edges)  →  validateIrStructural (IR-STRUCT-*)  →  errors block export
                           ↓
                    validateIrLint (IR-LINT-*)  →  warnings (CI: --fail-on-warning / --max-warnings)
                           ↓
              pythonFastAPI | nodeExpress generators
                           ↓
              openapi.yaml + app code + package metadata
                           ↓
              golden layer (Dockerfile, docker-compose.yml, Makefile, README; host→container e.g. 8080:8080)
                           ↓
              validateOpenApiInBundleStructural(openapi.yaml)  →  document-shape warnings (not full API lint)
                           ↓
              { files, openApiStructuralWarnings, irStructuralFindings, irLintFindings }

  Optional CI: archrad validate-drift  →  re-export IR in-memory, diff vs existing ./out  →  DRIFT-MISSING / DRIFT-MODIFIED (thin deterministic gate)

検証レベル（簡単な仕様）

1. JSON Schema 検証 — IR ドキュメントの形式を schemas/archrad-ir-graph-v1.schema.json と照合します（エディター／CI 向け。実行時は任意です）。
2. IR 構造検証 — validateIrStructural：配列、ID、HTTP config、エッジ参照、サイクル（IR-STRUCT-*）を検証します。内部の正規化済みグラフを使用します（docs/IR_CONTRACT.md を参照）。
3. エクスポート時の生成 OpenAPI 構造検証 — 生成された openapi.yaml を解析し、必須フィールドを検証します（ドキュメントの形式を検証するもので、Spectral は使用しません）。

アーキテクチャ lint（IR-LINT-*）は構造チェックの後に実行されます。解析済みグラフに対するルールビジターを使用します（スキーマではなく、ヒューリスティックです）。

検証レイヤー（命名）

レイヤー（OSS）	内容	コード
IR 構造検証	グラフの整合性：ID、エッジ、循環、HTTP パス／メソッド	IR-STRUCT-*
アーキテクチャ lint（基本）	決定論的なヒューリスティックのみ（AI なし、組織ポリシーなし）	IR-LINT-*
OpenAPI 構造検証（ドキュメントの形式）	生成された仕様に対する解析と、必須のトップレベル OpenAPI フィールドの確認	(文字列の警告。IR コードではありません)

レイヤー（Cloud — このパッケージの対象外）	例
ポリシーエンジン	SOC2、組織ルール、エンタイトルメント
アーキテクチャインテリジェンス	より高度な NFR／コスト／セキュリティの推論
AI による修正	修復ループ、編集案

1. IR 構造検証： ノード ID の重複／欠落、不正な HTTP config.url／config.method、不明なエンドポイントを持つエッジ、有向循環。
2. アーキテクチャ lint： 解析済みグラフ上のビジター関数のレジストリとして実装されています（buildParsedLintGraph → src/lint-rules.ts の LINT_RULE_REGISTRY）。IR を解析できない場合、buildParsedLintGraph は null ではなく { findings }（IR-STRUCT-）を返します。isParsedLintGraph() を使用するか、これらの findings を引き継ぐ validateIrLint を呼び出してください。各ルールは IrStructuralFinding[] を返し、runArchitectureLinting／validateIrLint がそれらをフラット化します。カスタム組織ルール： CI で runArchitectureLinting と独自の (g) => findings を組み合わせるか（実例：docs/CUSTOM_RULES.md）、標準の archrad validate CLI に独自コードを出力させる必要がある場合は フォークして LINT_RULE_REGISTRY に追加してください。CLI の archrad validate／archrad export は、構造検証とは別にグループ化して、**Architecture lint (IR-LINT-)** の下に lint を出力します。コードには IR-LINT-DIRECT-DB-ACCESS-002、IR-LINT-SYNC-CHAIN-001、IR-LINT-NO-HEALTHCHECK-003、IR-LINT-HIGH-FANOUT-004、IR-LINT-ISOLATED-NODE-005、IR-LINT-DUPLICATE-EDGE-006、IR-LINT-HTTP-MISSING-NAME-007、IR-LINT-DATASTORE-NO-INCOMING-008、IR-LINT-MULTIPLE-HTTP-ENTRIES-009、IR-LINT-MISSING-AUTH-010、IR-LINT-DEAD-NODE-011 があります。Sync-chain の深さは同期エッジのみを数えます。メッセージ／キュー／非同期のホップは edge.metadata.protocol／config.async で示してください（lint-graph.ts の edgeRepresentsAsyncBoundary と docs/ENGINEERING_NOTES.md を参照）。
3. ジェネレーター → openapi.yaml、ハンドラー、依存関係。
4. ゴールデンパス → make run／docker compose up --build。
5. バンドルに対する OpenAPI ドキュメントの形式 — Spectral レベルの lint ではありません。問題は openApiStructuralWarnings に出力されます。

IR コントラクト： schemas/archrad-ir-graph-v1.schema.json。パーサー境界と正規化された形式： docs/IR_CONTRACT.md（normalizeIrGraph → materializeNormalizedGraph）。

Trust builder： IR-STRUCT-* エラーはエクスポートをブロックします。IR-LINT-* 警告は表示され、--fail-on-warning／--max-warnings によって CI のゲート条件にできます。OpenAPI 形式の問題はエクスポート警告として表示されます。

リファレンス（OSS）： docs/DRIFT.md（決定論的な validate-drift）、docs/RULE_CODES.md（finding コード。MCP の docsUrl は GitHub アンカーを参照します）、docs/MCP.md（MCP ツールとローカルテスト）。

コード生成と検証（リトライ、タイムアウト、ポリシー）

ジェネレーターは、対応するエッジまたはノードの設定（例：retryPolicy）が IR に含まれている場合、リトライ／タイムアウト／サーキットブレーカーのコードを生成することがあります。これはコード生成であり、保証ではありません。OSS では現在、「すべての外部呼び出しにタイムアウト／リトライが必要」という要件も、その要件に対する lint もありません。この種のルールはセマンティック／ポリシーに関するものであり、ArchRad Cloud または IR 上に構築するカスタムリンターに適しています。

---

使用方法

モード	最適な用途	例
CLI	ローカルでの迅速な足場作成、CI、「Node プロジェクトを作成しない」用途	archrad export --ir graph.json --target python --out ./out
YAML → IR	YAML でグラフを記述し、検証／エクスポート用に JSON を出力する場合	archrad yaml-to-ir -y graph.yaml -o graph.json
OpenAPI → IR	OpenAPI 3.x から HTTP ノードを導出する場合（YAML の場合と同じ IR 構造）。ArchRad Cloud のマージでは同じライブラリを使用します	archrad ingest openapi --spec openapi.yaml -o graph.json
CLI validate	CI／pre-commit：IR の構造検証とアーキテクチャの lint。コード生成は行いません	archrad validate --ir graph.json
CLI validate-drift	エクスポートまたはマージ後：ディスク上のツリーと、同じ IR から新たに生成した決定論的なエクスポートを比較します	archrad validate-drift -i graph.json -t python -o ./out
ライブラリ（@archrad/deterministic）	IDP／パイプライン	runDeterministicExport → ファイルと検出結果。ドリフトの確認には runValidateDrift ／ runDriftCheckAgainstFiles
MCP（archrad-mcp）	Cursor／Claude Desktop／その他の MCP ホスト	stdio サーバー：IR の検証、lint の概要、ドリフト、ポリシーパック、静的 archrad_suggest_fix — docs/MCP.md を参照

MCP（Cursor の例）： npm i -g @archrad/deterministic（または npx）の実行後、コマンドを archrad-mcp、引数なし（stdio）にしてサーバーを追加します。ir を直接渡すか、大きなグラフの場合は JSON ファイルへの irPath を渡します。archrad_suggest_fix は、検出コード（例：IR-LINT-MISSING-AUTH-010）に対応する厳選されたテキストを返します。機械生成の IR パッチは返しません。手順に沿ったテスト（スモークスクリプト、MCP Inspector、Cursor のチャットプロンプト）：docs/MCP.md の Local testing セクションを参照してください。

CLI

入力は自然言語ではなく、構造化された IR（JSON）です。 archrad export --prompt "..." のようなコマンドはありません。グラフファイル（ノード／エッジ）を渡してください。

フィクスチャ（このリポジトリ内）：fixtures/minimal-graph.json（小規模）、fixtures/demo-direct-db-violation.json／fixtures/demo-direct-db-layered.json（IR-LINT-DIRECT-DB-ACCESS-002 の検出前／検出後）、fixtures/ecommerce-with-warnings.json（多数の lint ルール）、fixtures/payment-retry-demo.json（export でのリトライ関連のコード生成）。--target python は FastAPI バンドルです。fastapi ターゲットは別途ありません。通常の英語 → IR に変換するには、ArchRad Cloud または独自の LLM ステップを使用してください。このパッケージが行うのは IR → ファイル の変換のみです。

デモと GIF の録画（VHS、ストーリーボード、ドリフトの再生）：scripts/README_DEMO_RECORDING.md のみを参照してください。CLI の使用には必要ありません。

OpenAPI → JSON（仕様を信頼できる唯一の情報源として使用）：paths 内の各オペレーションは http ノード（config.url + config.method）になります。その後、他の IR と同様に検証して export します。

archrad ingest openapi --spec ./openapi.yaml --out ./graph.json
archrad validate --ir ./graph.json
archrad export --ir ./graph.json --target python --out ./out

OpenAPI のセキュリティ → IR → lint：取り込み時に、グローバルおよびオペレーションごとの security 要件名が各 HTTP ノードの config.security にコピーされます（ソートされ、決定論的です）。security: [] が明示されたオペレーションは config.authRequired: false になります（意図的に公開されています）。仕様のいずれのレベルにも security が宣言されていない場合、ノードにはそれらのフィールドが設定されません。その場合、archrad validate は HTTP のようなエントリノードに対して IR-LINT-MISSING-AUTH-010 を検出できます（仕様アーティファクトのみから分かるコンプライアンス上のギャップです）。

YAML → JSON（より簡易な記述方法）： fixtures/minimal-graph.yaml（または独自のファイル）を編集して IR JSON にコンパイルし、その後検証または export します。

archrad yaml-to-ir --yaml fixtures/minimal-graph.yaml --out ./graph.json
archrad validate --ir ./graph.json
# or pipe: archrad yaml-to-ir -y fixtures/minimal-graph.yaml | archrad validate --ir /dev/stdin   # on Unix; on Windows use --out then validate

YAML にはトップレベルの graph:（オブジェクト）またはトップレベルの nodes:（配列）のいずれかが必要です。ラップされていないグラフは、自動的に { "graph": { ... } } としてラップされます。

npm install -g または npx の後（一般的な使用方法）：

archrad export --ir ./graph.json --target node --out ./my-express-api

# Validate IR (structural + architecture lint). Pretty output; exit 1 on structural errors by default:
archrad validate --ir ./graph.json
# Machine-readable + CI gates:
archrad validate --ir ./graph.json --json
archrad validate --ir ./graph.json --fail-on-warning
archrad validate --ir ./graph.json --max-warnings 0
# Structural only (skip IR-LINT-*):
archrad validate --ir ./graph.json --skip-lint
# Declarative PolicyPack YAML/JSON in a directory (after IR-LINT-*; skipped with --skip-lint):
archrad validate --ir ./graph.json --policies ./policy-packs

git clone からの使用（コントリビューター向け）：パッケージのルートで npm ci && npm run build を実行してください（prepare フックはありません。docs/ENGINEERING_NOTES.md を参照）。その後、archrad を使うのと同じ方法で node dist/cli.js を使用します（例：node dist/cli.js validate --ir fixtures/minimal-graph.json）。

決定論的なドリフト検出（軽量なオープンソース版）：ディスク上の既存の export ツリーを、同じ IR から新たに生成した export と比較します。生成ファイルの欠落／変更を検出します（改行コードは正規化されます）。--strict-extra を指定すると、ディスク上にはあるものの参照先の export にはないファイルも検出します。これは「コードが意図と一致しているか」という意味上のチェックではありません。ArchRad Cloud では、ビルダー／UI のドリフトチェックと、より広範なガバナンス機能を提供します。

archrad export -i ./graph.json -t python -o ./out
# …edit files under ./out…
archrad validate-drift -i ./graph.json -t python -o ./out --skip-host-port-check
# CI-friendly:
archrad validate-drift -i ./graph.json -t python -o ./out --skip-host-port-check --json
# Fail if the tree has extra files not in the reference export:
archrad validate-drift -i ./graph.json -t python -o ./out --strict-extra

例：アーキテクチャを検証する

archrad validate --ir fixtures/minimal-graph.json

出力例（stderr）：

archrad validate:
⚠️ IR-LINT-NO-HEALTHCHECK-003: No HTTP node exposes a typical health/readiness path (...)
   Fix: Add a GET route such as /health for orchestrators and load balancers.
   Suggestion: Expose liveness vs readiness separately if your platform distinguishes them.
   Impact: Weaker deploy/rollback safety and harder operations automation.

構造エラーは ❌ IR-STRUCT-... の形式で表示され、Fix: の行が続きます。GitHub Actions やその他の CI で検出結果を処理するには、--json を使用します。

• --ir — JSON：{ "graph": { "nodes", "edges", "metadata" } } または生のグラフ（CLI がラップします）。
• --target — python | node | nodejs
• --out — 出力ディレクトリ（必要に応じて作成されます）
• --host-port <n> — Docker が公開するホストポート（デフォルトは 8080。コンテナ内では引き続き 8080 で待ち受けます）。環境変数 ARCHRAD_HOST_PORT と同じです。
• --skip-host-port-check — エクスポート前に 127.0.0.1 を確認しません。
• --strict-host-port — ホストポートが使用中と見られる場合、エラー終了します（CI に適しています）。
• --danger-skip-ir-structural-validation — 安全ではありません：エクスポート前の validateIrStructural をスキップします（CI では絶対に使用しないでください）。解析／正規化エラー（ルートが無効、グラフが空など）は引き続き validateIrLint で検出され、irStructuralFindings に IR-STRUCT-* を含めてエクスポートをブロックします。非表示の --skip-ir-structural-validation は非推奨の別名として残されています。
• --skip-ir-lint — エクスポート時の validateIrLint をスキップします。
• --fail-on-warning / --max-warnings <n> — 設定されている場合、IR の構造検証とリントの検出結果がポリシーに違反すると、ファイルは書き込まれません（validate と同じ動作）。

デフォルトでは、localhost で 8080（または指定した --host-port）が使用中と見られる場合、CLI が警告します。これにより、docker compose がバインドエラーで失敗する前にポートを変更できます。

エクスポートでは、まず IR の構造検証を実行し、次にアーキテクチャのリント、最後にコード生成を実行します。構造エラーがあると、ファイルは書き込まれずに処理が中止されます。irLintFindings に含まれるのは IR-LINT-* のみです。解析に失敗した場合の IR-STRUCT-* は、構造検証がスキップされた場合も含め、常に irStructuralFindings に表示されます。リントの警告はデフォルトで表示されます。CI で書き込みをブロックするには、--fail-on-warning / --max-warnings を使用します。

ライブラリ

import {
  runDeterministicExport,
  runValidateDrift,
  validateIrStructural,
  validateIrLint,
  sortFindings,
  shouldFailFromFindings,
} from '@archrad/deterministic';

const { files, openApiStructuralWarnings, irStructuralFindings, irLintFindings } =
  await runDeterministicExport(ir, 'python', {
    hostPort: 8080,
    skipIrLint: false, // default
  });
// Structural errors → empty files (unless skipIrStructuralValidation). Lint is non-blocking for export unless you check policy in your pipeline.

const drift = await runValidateDrift(ir, 'python', '/path/to/existing-export', {
  skipIrLint: false, // set true to match CLI --skip-ir-lint on reference export
});
// drift.ok, drift.driftFindings, drift.exportResult — same core semantics as CLI validate-drift (CLI also probes host port before calling the library)

const all = sortFindings([...validateIrStructural(ir), ...validateIrLint(ir)]);
if (shouldFailFromFindings(all, { failOnWarning: true })) {
  /* gate your CI */
}

必要に応じて、同じパッケージの isLocalHostPortFree / normalizeGoldenHostPort を使って、独自の事前チェックを実行できます。

---

ゴールデンパス（コントリビューター — ローカルクローン）

この手順では、リポジトリをクローンし、パッケージのルートで npm ci && npm run build を実行済みであることを前提とします。npm install -g @archrad/deterministic でインストールした場合は、node dist/cli.js の代わりに archrad を使用してください（フラグは同じです）。

node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./out
cd ./out
make run
# In another terminal, once the API is up:
curl -sS -X POST http://localhost:8080/signup -H "Content-Type: application/json" -d '{}'

422 Unprocessable Entity（FastAPI/Pydantic）または、内容が明確な 400 が表示されるはずです。これは、スタックが稼働しており、サイレントな 500 ではなく、仕様どおりの検証が行われていることを示します。

クローン後の簡易チェック：cd packages/deterministic && npm ci && npm run build && npm test を実行し、続いて ./tmp-out にエクスポートしてから、cd tmp-out && make run を実行し、上記のように curl を実行します。8080 が使用中の場合は、--host-port 18080（または node dist/cli.js export ... --host-port 18080）を使用します。

必要に応じて、bash scripts/golden-path-demo.sh で同じ手順を実行できます。デモの録画（GIF、テープ、ドリフトの再生）については、scripts/README_DEMO_RECORDING.md を参照してください。

---

オープンソース版と ArchRad Cloud

このリポジトリは決定論的なエンジンのみを提供します — ローカルで動作し、オフラインで、外部への通信はありません。

こちら（OSS）	ArchRad Cloud（商用製品）
IR の構造とアーキテクチャの lint（validate、IR-STRUCT-*、IR-LINT-*）、コンパイラー（export）、validate-drift（ディスク上の内容と新しいエクスポートの比較）、OpenAPI のドキュメント構造に関する警告、golden Docker/Makefile	ポリシーエンジン、より高度なアーキテクチャインテリジェンス、AI による修正、ビルダー内でのより充実したドリフト／同期の UX
このパッケージではアカウント不要で、archrad CLI をいつまでも利用できます	認証、組織、クォータ、課金
独自のLLMオーケストレーションや「修復」ループはありません	LLM による生成、修復、複数モデルのルーティング
このリポジトリには Git 同期も、エンタープライズポリシーの注入もありません	Git へのプッシュ、ガバナンス、コンプライアンスダッシュボード

ArchRad Cloud を利用しなくても、この CLI とライブラリを利用できます。クラウド製品は、同じ決定論的な契約を基盤として、コラボレーション機能と AI 機能を提供します。

---

コントリビューション

CONTRIBUTING.md を参照してください。

---

ライセンス

Apache-2.0 — LICENSE を参照してください。