ucn

UCN - Universal Code Navigator

監査可能な回答を提供します。すべての一致数を数え、不確かなものには印を付け、見落としがある箇所も明示します。

AI エージェントを使っている場合は、UCN を スキルまたは MCP ツールとして追加してください。1 つのツールで、呼び出し元、影響範囲、テストに関する質問に対し、ソースへのリンク付きの簡潔な回答をエージェントに提供できます。不確かな点には推測ではなく明示的に印を付けます。回答は質問者ではなく、インデックス化されたソースに基づきます。ターミナル上の人間も、MCP 経由のエージェントも、同じ質問には同じ記録を受け取ります。

概念図 · 静止画

CLI を直接使うか、エージェントスキルをインストールするか、MCP 経由で接続してください。いずれも同じエンジンを使用します。

  Terminal              AI Agents           Agent Skills
       │                    │                    │
      CLI                  MCP                 Skill
       └────────────────────┼────────────────────┘
                            │
                     ┌──────┴──────┐
                     │ UCN Engine  │
                     │  commands   │
                     │ tree-sitter │
                     └─────────────┘

UCN は静的コード解析に tree-sitter の抽象構文木（AST）を使用し、プロジェクトのコンパイルや言語サーバーの起動は行いません。CLI は必要に応じて実行され、インクリメンタルインデックスを再利用します。MCP は繰り返しクエリに対応できるよう、プロセスを起動したままにします。プロジェクトの設定は不要で、キャッシュはリポジトリの外部に保存されます。

JavaScript、TypeScript、JSX/TSX、Python、Go、Rust、Java、C、C++、C#、および HTML のインラインスクリプトに対応しています。

インストール

npm install -g ucn                    # Node.js 20+

シェルで使う

プロジェクトディレクトリから実行します。

ucn repo
ucn show handleRequest --lines
ucn source handleRequest --raw
ucn impact --staged --lines
ucn check --staged

repo はプロジェクトをマッピングします。show --lines は呼び出し元を特定し、source --raw は実装を取得します。impact と check はステージされた変更を調べます。名前が曖昧な場合、find は後続のコマンドで使える file:line:name 形式のハンドルを返します。

--lines は path:line:text 形式のレコードを返し、--raw はソースコードを返します。どちらも、人間が読みやすいレポートを解析せずに、エージェントが既存のスクリプトで利用できます。

テキスト検索は、コメント、設定、文字列、対応言語以外のコードを調べる際にも役立ちます。タスクで呼び出し以外も含むすべての出現箇所が必要な場合は、usages を使うとリテラル名の一覧を取得できます。

コードのナビゲーションと変更の分析

show はシンボルのシグネチャ、ソース、呼び出し元、呼び出し先、関連コンテキストをまとめて取得します。必要なセクションを選ぶか、出力予算を設定して回答を絞り込めます。trace はファイルをまたいで呼び出しグラフをたどり、呼び出し先の深部へ進むか、呼び出し元をさかのぼってエントリーポイントを探します。検証されていない関係も見える状態に保たれ、探索が止まった箇所はツリーの集計情報に報告されます。

impact はシンボルまたは Git の差分を呼び出し元に結び付けます。tests はインデックス化された呼び出し経路と参照経路をたどり、数ホップ離れたものも含め、静的にリンクされたテストを特定します。plan はリネームやシグネチャ変更をプレビューし、ソースの場所とレビュー項目を提示します。ファイルは編集しません。これらのコマンドは、ターミナルや AI エージェントからのコード探索、リファクタリング、変更レビューを支援します。

回答で確認できること

呼び出し元に関する回答では、UCN がバインディング、インポート、レシーバーの型、所有権を確認し、選択した定義への呼び出しと、その名前の別の使用を区別します。 十分な根拠がない呼び出しは、理由とともに未検証として表示されます。 メソッド名が一致するだけでは、どの実装が実行されるかは確定しません。 レシーバーと所有権に関する根拠に基づいて、候補が分類されます。

82313cf9 の ripgrep では、選択した file_name ヘルパーに、確認済みの呼び出し箇所が 4 つ、未検証の候補が 1 つあります。このアニメーションは、UCN の出力から描画されたインポート関係と同名の定義とともに、一致した 29 行すべてを網羅しています。

取得結果 · 静止画 · データ

ACCOUNT 行では、観測された名前の出現箇所を、確認済みの呼び出し、未検証の候補、呼び出し以外の出現箇所、別の対象に帰属する一致に分類して照合します。各出現箇所は必ず 1 つのカテゴリだけに数えられるため、信頼を前提とするのではなく、行ごとに合計を確認できます。CONTRACT は、その集計の対象範囲を説明します。警告には、インデックスが網羅できなかったソースが示されます。こうした詳細は、エージェントの出力予算に合わせてテキストが切り詰められても保持されます。予算がこれらを収めるには小さすぎる場合、回答は提示されず、必要な予算が示されます。

したがって、空の結果は、調査対象のコードについて特定の意味を持ちます。リフレクション、生成コード、実行時の登録、外部の利用者がシンボルに到達しないことまでは証明できません。deadcode は調査候補を提示しますが、削除には引き続き裏付けが必要です。リファクタリングのプレビューにも、引き続きコンパイラーとテストが必要です。

精度と検証

リリースのゲートでは、ピン留めされた本番コードベース10件からなるボード上で、UCNの回答を独立したコンパイラーおよび言語サーバーと比較します。2026年10月4日に実施したローカル評価では、呼び出し元の結果を次のようにサンプリングしました。

この評価では、呼び出し元と呼び出し先の両方の回答で、対象範囲内にあるオラクルのエッジの欠落はゼロでした。また、コマンド間の比較8,000件で不一致はゼロでした。デフォルトのデッドコード監査では、採点対象の主張9件に誤ったデッド判定はありませんでした。さらに4件の主張はオラクルで特定できなかったため、採点対象外でした。10件すべてのリポジトリがパフォーマンス予算を満たし、定常状態のクエリのp95は4.7～101.1 msでした。この計測にはプロセスの起動時間とインデックス作成時間は含まれていません。コールドビルドとキャッシュの読み込みは別途計測します。

サンプルは決定論的で、参照アクティビティに基づいて層化されています。確認済み適合率は採点対象の主張に適用されます。再現率は、確認済みまたは未検証の区分で見つかった、対象範囲内のオラクルのエッジ数を数えます。未検証の候補、オラクルの回答保留、採点対象外の検出結果は、それぞれ別に扱います。これらの測定結果は、実行時の知識が完全であることや、すべてのマシンで性能が同一であることを証明するものではありません。

スケジュールされたボードは、上記の10件に加え、zod、express、hono、zustand、fastify、rich、click、attrs、grpc-go、chi、cursive、itertools、rayon、gson、jsoupを含む、ピン留めされた25件のリポジトリを対象とします。ローテーション方式の新規リポジトリ枠では、ピン留めされたボード以外のコードベースを検証します。

リポジトリマニフェストには、すべてのコミットが記録されています。Publish ワークフローはリリースをゲートし、Eval ワークフローはスケジュールに従って、または必要に応じてチェックを実行します。各ワークフローの実行ページでは、CIの結果と評価成果物を確認できます。オラクルの依存関係をインストールした状態で、次のコマンドを使ってローカルでチェックを再現できます。

npm run verify
npm run trust:gate

コマンド

deps --cycles は循環依存をグループ化し、即時インポートと遅延インポートまたは型のみのエッジを区別します。列挙の上限は明示されます。repo はプロジェクト構造に加えてソースのカバレッジも報告します。HOT ランキングでは、確認済みの本番環境での呼び出し元を正確にカウントします（非常に大規模なリポジトリでは、精緻化の予算が制限されます。その場合は明示されます）。また、repo --sections=stats --hot はすべての呼び出し元に基づいてランキングします。

endpoints --bridge は、フレームワーク抽出器が認識したサーバールートとクライアントリクエストを照合します。plan は、所有関係が解決されている場合、インポート、オーバーライド、インターフェースまたはトレイトのメソッドなどのコード上の関係を処理します。曖昧な関係はレビュー項目として残されます。

フラグについては ucn --help を実行するか、 コマンドリファレンスを参照してください。

シェル出力

レコードとコードは stdout に、集計情報と注記は stderr に出力されます。未検証のレコードには、タブ区切りの理由が付記されます。結果が空の一覧は終了コード 1、エラーは終了コード 2、正常な一覧は終了コード 0 で終了します。--lines は find、show、usages、search、impact に対応します。show --lines はデフォルトで呼び出し元を一覧表示します。スクリプトで構造化フィールドやツリー形式の結果が必要な場合は、--json を使用してください。

同じソースツリーに対する一覧の結果は決定的です。新規ビルド、キャッシュの読み込み、増分ビルドで、同じレコードが同じ順序で返されます。デフォルトの行数上限はありません。明示的な上限を指定した場合は、省略された内容が示されます。また、シェルモードの文字数上限を超えると、出力の一部を書き込む前にエラーになります。source --raw は、明示的に行数上限が指定されている場合を除き、関数とクラス全体を抽出します。切り詰めが発生した場合は、その旨が stderr に報告されます。

通常のテキストモードでのコマンドエラーも終了コード 2 で終了します。JSON モードでは、結果が空でも成功なら終了コード 0、コマンドエラーなら終了コード 1 となります（meta.ok: false と error を含みます）。UCN 内部で例外が発生した場合は、コードについての回答ではなく、Internal error: ... として報告されます（JSON では meta.internalError: true が追加されます）。対象を指定しない check は、TRUST が BLOCKED の場合は終了コード 1、その他のチェック完了時は 0、実行できなかった場合は 2 で終了します。

--lines を除き、find、テキスト形式の search、deadcode、api、repo --sections=files の結果は、デフォルトで最大 500 件です。find のテキスト出力では、上位 5 件を詳細に表示し、残りは件数を示します（JSON では最大 500 件を返します）。--limit=N を指定すると、両方の上限が引き上げられます。より多くの結果を要求するには --limit=N を使用してください。usages は、上限または --exclude-tests が指定されていない限り、テストファイルも含めてすべての箇所を一覧表示します。広範な find クエリでは、定義に固定された呼び出し元のアクティビティを計算する前に、使用のおおよその合計数で候補を選択します。結果に上限がある場合は、この選択についても明示されます。

*.min.js、*.bundle.js、*.map という名前のファイルは、スキップされたソースとして報告され、完全性は部分的になります。--include-bundled（MCP では include_bundled=true）を指定すると、ユーザーによる除外設定を尊重しながら JavaScript バンドルをインデックス化します。この指定により共有キャッシュは使用されません。ソースマップは報告されますが、インデックス化されません。

AI のセットアップ

1 つのツール、18 個のコマンド。切り詰められた場合も信頼性のメタデータを保持する、簡潔でソースにリンクされた回答を提供します。

MCP

# Claude Code
claude mcp add ucn -- npx -y ucn --mcp

# OpenAI Codex CLI
codex mcp add ucn -- npx -y ucn --mcp

# VS Code Copilot
code --add-mcp '{"name":"ucn","command":"npx","args":["-y","ucn","--mcp"]}'

{
  "mcpServers": {
    "ucn": {
      "command": "npx",
      "args": ["-y", "ucn", "--mcp"]
    }
  }
}

{
  "servers": {
    "ucn": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ucn", "--mcp"]
    }
  }
}

エージェントスキル（サーバー不要）

macOS / Linux：

# Claude Code
mkdir -p ~/.claude/skills
cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.claude/skills/

# OpenAI Codex CLI
mkdir -p ~/.agents/skills
cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.agents/skills/

Windows PowerShell：

$npmRoot = npm root -g
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills"
Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.claude\skills\"

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills"
Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.agents\skills\"

このスキルは、エージェントがコードベースを把握し、シンボルを特定し、有用な範囲で最小のコマンドを選び、証拠の各レベルを解釈し、不完全な回答から復旧する方法を教えます。これは同じエンジンに対するガイダンスであり、別の実装ではありません。

対象範囲

UCN は、1 つのプロジェクト内のインデックス化されたソースを分析します。プログラムの実行や、node_modules、site-packages などのインストール済み依存関係のインデックス化は行いません。repo --sections=health --deep は、ソースのカバレッジと既知の分析上の制限を報告します。

C および C++ では、インクルードパスとヘッダーのコンテキストに compile_commands.json を使用できますが、UCN はプリプロセッサを実行せず、コンパイラのビルドごとのビューを再現することもありません。C# のソースジェネレーターと外部アセンブリもインデックスの対象外です。HTML にはリグレッションテストのカバレッジはありますが、コンパイラ／LSP のリポジトリオラクルはありません。

CLI、MCP、スキルは、同じ解決ルールと証拠を共有します。通信方式を変えても、エンジンがコードについて把握している内容は変わりません。

MIT