codependix-navigate

codependix でコードベースを把握する

Codependix は、Nx ワークスペース、NestJS コンテナー、ファイル単位の TypeScript および Python のインポートを対象に、依存関係グラフを構築してクエリを実行します。「X はどのように Y に到達するのか？」「Z を変更すると何が壊れるのか？」「このパッケージは何に依存しているのか？」を調べる場合は、codependix のコマンドで関係を直接クエリするか、ディスク上にすでにコミットされているグラフを確認してください。

まずはコマンド：依存関係パスをクエリする

図を解析したり、ソースファイルを手作業で grep したりせずに、2 つのノード間の有向依存関係パスをたどるには、codependix path を使います。すべての実行で --config <path> を指定します。このリポジトリでは configuration/codependix.config.ts です。検索対象は自動で探されず、デフォルトもありません。

# How does project-a reach project-c?
codependix path project-a project-c --config configuration/codependix.config.ts

# How does one file import another?
codependix path src/modules/auth/auth.service.ts src/modules/users/user.entity.ts --config configuration/codependix.config.ts

# What NestJS modules connect two modules in a container?
codependix path AuthModule DatabaseModule --config configuration/codependix.config.ts

パスのクエリフラグと絞り込み

ワークスペース全体を対象に実行すると、モノレポ全体の Nx プロジェクト、TypeScript AST、コンテナー登録を解析するため、時間がかかることがあります。絞り込みフラグを使って実行範囲を限定し、実行時間を最小限に抑えてください。

フラグ	目的
-f, --format <format>	出力形式：markdown（デフォルト）、json、または mermaid
--nx-projects / --no-nx-projects	Nx ワークスペースのプロジェクト依存関係グラフの検索を切り替えます
--file-imports / --no-file-imports	内部のファイル単位のインポートグラフ検索を切り替えます
--nestjs-modules / --no-nestjs-modules	NestJS コンテナーモジュールグラフの検索を切り替えます
--projects <names>	検索対象とするプロジェクト名または glob をカンマ区切りで指定します
-d, --directory <dir>	読み込む Nx ワークスペースのディレクトリ
--include <globs> / --exclude <globs>	設定済みのプロジェクト包含または除外 glob を上書きします
--tags <tags>	フィルターに使用する Nx プロジェクトタグをカンマ区切りで指定します
--config <path>	必須。 codependix 設定ファイルへのパス。このページのすべての例で指定されています

パスの結果

• パスが見つかった場合：<from> から <to> をつなぐ最短の有向パスを出力します（例：project-a → project-b → project-c）。
• パスがない場合：_No path connects "<from>" to "<to>"._ と報告します（または JSON で空のリストを返します）。終了コードは 0 です。パスが見つからないことは結果であり、エラーではありません。

CLI を実行せず、コミット済みの図を確認する場合

CLI を実行すると、ソースファイルからグラフ表現が構築されます。コマンドを実行する前に、ディスク上にコミット済みの成果物があり、すでに答えが得られるか確認してください。

1. モノレポ内の各パッケージには、それぞれのグラフがコミットされています。 各プロジェクトの README.md にある ## 🕸️ Codependix セクション、または `` マーカーの間を確認してください。
2. 直近の影響範囲（1 ホップ）： プロジェクトのコミット済み Nx Neighborhood 図には、直近の dependencies（依存先）と dependents（公開 API を変更した場合に影響を受けるもの）がすべて記載されています。
3. 内部ファイル構造： プロジェクトのコミット済み File import graph には、そのプロジェクト内のファイル間インポートと、他のファイルから参照されていないファイルがすべて記載されています。
4. コンテナー構造： プロジェクトのコミット済み NestJS module graph には、接続されているコンテナーモジュールが記載されています。
5. ワークスペース全体の構造： リポジトリのルートにある README.md には、コミット済みのワークスペースグラフが含まれています。

コストの目安：

• 単一ホップの依存関係、直近の影響範囲、ローカルのファイル構成には、README の図または JSON を確認します（ビルドコストなしで、ディスク上ですぐに回答を得られます）。
• 複数ホップの推移的なパス、プロジェクト間の到達可能性、ステージング前の変更の検証、または機械可読な JSON の生成には、codependix path を実行します。

4 種類のグラフと、それぞれが答える質問

グラフ	範囲	答える質問
Nx Neighborhood	プロジェクト	1 つのプロジェクトが依存する先と、変更時に影響を受けるプロジェクト（依存元）は何か
Workspace graph	ワークスペース	アーキテクチャの大まかなレイヤー構成と、パッケージ間の関係は何か
NestJS module graph	コンテナ	DI コンテナが実行時にどのモジュールを接続するか
File import graph	プロジェクトのファイル	ファイル間のインポート関係、循環参照、ローカルなリファクタリングの影響範囲は何か

グラフの成果物の読み方

Nx Neighborhood：影響範囲

Neighborhood は、焦点となるプロジェクト（図では強調表示）から各方向に 1 ホップの範囲を示します。

• dependents は、破壊的変更の影響範囲です。 一覧にあるすべてのプロジェクトが、新しい構成を前提にビルドする必要があります。より深いレイヤーにまたがる破壊的変更の場合は、Neighborhood を 1 つずつ外側へたどるか、codependix path を実行してください。
• dependencies は、許可された範囲です。 プロジェクトがインポートできるのは、ここに宣言されたものだけです。
• implicit とマークされたエッジは、コードのインポートではなく、Nx ワークスペース設定による依存関係です。

File import graph：リファクタリングと移動

エッジは、同じプロジェクト内のファイル間に限定されます。

• 外部パッケージとプロジェクト間のインポートは、設計上除外されています（これらは Nx Neighborhood に含まれます）。
• isolatedFileNames は調査候補の一覧であり、デッドコードではありません。 孤立したファイルは、エントリーポイント、外部へのエクスポート、または設定ファイルである可能性があります。
• 循環参照は実際に問題になります。 プロジェクト内のインポート循環は、実行時に undefined のバインディングや初期化順序の不具合を引き起こします。循環のエッジをたどり、切り離す箇所を特定してください。
• ファイル名を変更しますか？ 古い相対パスを指すエッジから、正確な影響範囲がわかります。

NestJS module graph：DI コンテナの接続

コンテナモジュールを評価して構築されます。

• グローバルモジュールまたはアンビエントモジュール： ほぼすべてのモジュールがインポートするモジュール（たとえば、コアのロギングや設定）は、図の視覚的な煩雑さを避けるため、個別のエッジが省略されます。これらは ambientModuleNames の下に一覧表示され、角丸で描画されます。
• 動的ラッパーモジュール： forRoot または動的プロバイダーによって作成される、非公開の内部ホストモジュールは、宣言元のモジュールにまとめられます。
• モジュールが見つからない場合、そのモジュールはコンテナ階層に登録されていません。そのため、エクスポートされたプロバイダーは利用できません。

コミット済みのグラフを信頼する前に最新状態を確認する

コミット済みのグラフは、最後に codependix map --write を実行した時点のリポジトリの状態を反映しています。コミット済みのグラフが最新かどうかを確認するには、次のコマンドを実行してください。

# Check if any committed reports are stale without modifying files
codependix map --check reports --config configuration/codependix.config.ts

# Update all committed graphs across the workspace
codependix map --write --config configuration/codependix.config.ts

コミット済みのグラフが最近のローカル編集を反映していない場合は、codependix map --write を再実行するか、リアルタイムのクエリに codependix path を使用してください。