codependix-export

codependix のエクスポートを実行する

Codependix は Nx ワークスペース内の各プロジェクトの依存関係を読み取り、4 種類の形式で出力します。Nx プロジェクトグラフ、NestJS プロジェクトのモジュールグラフ、TypeScript プロジェクトのファイルレベルのインポートグラフ、そして Python プロジェクトのグラフです。その後、プロジェクトごとに設定で指定された出力先（JSON ファイル、既存ファイルに挿入する Markdown アンカーブロック、またはその両方）へ、それぞれのグラフを出力します。

すべては設定で決まります

グラフの種類を選択するフラグも、グラフの種類ごとのサブコマンドもありません。 どのプロジェクトでどのグラフを実行し、エクスポート先をどこにするかは、すべて codependix.config.ts の設定によって決まります。--nestjs、--imports、--only nx を探しても、そのようなものは存在しません。

まず知っておくべきなのは、次の失敗パターンです。

プロジェクトを選択しない設定では、すべてのプロジェクトのすべてのグラフ種別が target: "none" に解決され、何も生成されません。 実行は成功して終了コード 0 を返し、設定済みのエクスポートはすべて最新であるとログに記録しますが、ファイルは書き込まれません。何も設定されていないためです。これは正しい動作であり、バグではありません。

つまり、--write を実行して何も書き込まれなかった場合は、デバッグではなく設定の問題です。不具合を探す前に、次の順序で確認してください。

1. --config で指定したファイルが意図したものか確認します。このフラグは必須で、指定したファイルは存在していなければなりません。そのため、ファイルを指定しない場合や、ファイルが見つからない場合は、何も書き込まずに明確なエラーが発生します。しかし、別のファイルを指定している場合は、空の設定ファイルとまったく同じように動作します。
2. 想定しているグラフ種別の target が "none" 以外に設定されていることを確認します。未設定の target はすべて "none" になります。
3. 想定しているプロジェクトが、設定済みの include glob に一致し、どの exclude glob にも一致しないことを確認します。include のデフォルトは何も指定しない状態です。そのため、プロジェクトを一つも指定していない設定では、どのプロジェクトも選択されません。この場合、実行時に警告が表示されますが、終了コードは 0 のままです。

codependix-configure スキルでは、この3点すべてを扱っています。

1 つの --write と、--check でゲートできる 2 つの項目

--check にはカンマ区切りのセットを指定します。どのセットを指定するかによって、どの検出結果で実行が失敗するかが決まります。

モード	意味
--check boundaries	宣言されたルールに違反するエッジまたは循環がある場合に失敗します。出力先を読み込まず、何も書き込みません
--check reports	設定された出力先に、今回新たに実行した場合に書き込まれる内容が保持されていない場合に失敗します
--write	設定されたすべてのエクスポートを書き込みます

--check に 2 つの名前があるのは、検出結果がプルリクエストの対極にあるからです。境界の破損はブランチによって引き起こされ、ブランチで修正されるため、すべてのブランチでゲートします。古いエクスポートは、それが説明するワークスペースとともに変化するため、これをゲートすると、ブランチで行った変更ではなく、プロジェクトグラフを変更したすべてのブランチで失敗します。reports という名前は、callidescope と codometer のものと意図的に同じ表記にしています。同じ検出結果だからです。

組み合わせ：

• --write --check boundaries は有効です。境界には古くなる出力先がありません。
• --check boundaries では --format、--json-output、--markdown-output も使用できます。検出結果がレポートとして出力されます。下の 境界レポート を参照してください。
• --write --check reports は拒否されます。書き込んだばかりの実行で、エクスポートが古くなることはありません。
• 値のない --check、または値がカンマだけの --check は拒否されます。「何もゲートしない」と解釈すると、失敗しないゲートになってしまいます。--check needs a value で実行が拒否された場合、修正方法はセットを指定することであり、フラグを外すことではありません。
• --check も --write も指定しない場合、どちらを使うかを 3 項目のメニューで尋ねます。モードが推測されることはなく、デフォルトで書き込みが行われることもありません。

エージェントは必ずモードを明示的に指定してください。 プロンプトを抑制するフラグはありません。エージェントによる実行にはプロンプトを表示する端末がないため、その実行はただちに失敗し、必要なフラグを示します。この失敗をツールの不具合と捉えるのは誤りです。フラグが不足しているのであり、修正するには --check <set> または --write を追加します。

選択したモードに関係なく使えるオプションは 2 つあり、最初のオプションは必須です。

オプション	意味
--config <config>	必須。 codependix 設定ファイルへのパスです。作業ディレクトリを基準に解決し、次にワークスペースルートを基準に解決します。省略すると実行は失敗し、設定ファイルの検索も行われません
-d, --directory [directory]	この実行で Nx プロジェクトグラフを読み取るワークスペースルートです。デフォルトは作業ディレクトリです

codependix map --write --config configuration/codependix.config.ts
codependix map --check boundaries --directory . --config configuration/codependix.config.ts
codependix map --check reports --directory . --config configuration/codependix.config.ts

Codependix は Nx プロジェクトグラフを読み取ります

ディレクトリを走査する測定ツールと異なるのが、この特性です。Nx はプロセスの作業ディレクトリからプロジェクトグラフを独自に解決するため、グラフを指定するフラグはありません。--directory で指定するのは、各プロジェクトのパスを解決する基準となるワークスペースルートです。設定ファイルの場所には影響しません。設定ファイルの場所は常に --config のパスで決まります。

そのため、--directory は走査対象のサブツリーではありません。単一のプロジェクトのフォルダーを指定しても、そのプロジェクトだけがエクスポートされるわけではありません。すべてのプロジェクトのルートがそのフォルダーの下にあるものとして解決され、エクスポート先が誤った場所になるか、存在しない Readme の読み取りに失敗します。一方、グラフ自体には影響しません。

ワークスペースルートから codependix を実行し、--directory . を渡してください。ディレクトリではなく、設定の include／exclude グロブ、または --projects／--tags でプロジェクトを選択します。

プロセスが配置されていないワークスペースのグラフを作成する

設定では、グラフを解決する代わりに、読み込む projectGraph ファイルを指定できます。

{ projectGraph: "artifacts/graph.json" }

これは、nx graph --file=graph.json が出力する JSON への、ワークスペースルートからの相対パスです。プロセスがその中にいないワークスペースのグラフを作成する方法はこれだけです。たとえば、あるリポジトリをチェックアウトして別のリポジトリのグラフを作成するジョブや、配下に Nx ワークスペースがない実行などです。このパスは、他のすべてのエクスポートパスと同じルートを基準に解決され、指定したグラフのノードルートもワークスペース相対で、そのルート配下に解決されます。

これはフラグではなく設定フィールドです。実行が読み込むグラフは、説明対象のワークスペースの属性であり、固定されたチェックアウトのグラフを作成するジョブでは、一度指定しておくのが適切だからです。

指定したグラフは信頼され、検証されません。 Nx が作成したものなので、その内容はそのまま扱われます。プロジェクトグラフではないファイルだけは、後でファイルを特定できないままクラッシュするのではなく、名前を示して拒否されます。古いグラフや手作業で編集されたグラフの場合、失敗するのではなく、誤った図が生成されます。

いずれにしても、実際のファイルがディスク上に必要なものが2つあるため、グラフを指定しても実行全体がワークスペース不要になるわけではありません。nestjs レベルでは各コンテナーを起動し、imports レベルでは実際の ts.Program を構築します。nx レベルではグラフのみを読み込みます。

4種類のグラフとワークスペース

それぞれ設定内で名前をキーとして指定します。

キー	エクスポートする内容	表示されるプロジェクト
nx	プロジェクトの1ホップ近傍 — 依存先と、そのプロジェクトに依存しているもの	ワークスペースルート自体を除き、Nx グラフが認識するすべてのプロジェクト
nestjs	プロジェクトの NestJS モジュールインポートグラフ	framework:nestjs タグが付いたプロジェクトのみ
imports	プロジェクト独自のファイルレベル TypeScript インポートグラフ	独自の tsconfig.json を持つすべてのプロジェクト
pythonImports	import / from ... import ステートメントから解析した Python 版	language:python タグが付いたプロジェクトのみ

ワークスペース全体の Nx グラフは、workspace.nx の下で別途設定します。プロジェクトごとではなくリポジトリごとに1回エクスポートされ、プロジェクトごとのオーバーライドはなく、include/exclude の影響も受けません。ノードの集合を絞り込むのは --projects/--tags です。詳細は以下をご覧ください。

各グラフタイプへの参加条件はタイプごとに異なり、共通のルールはありません。 あるグラフタイプが適用されないプロジェクトは、そのタイプの結果に表示されないだけです。そのため、すべてのプロジェクトにグラフタイプを設定してもコストはかかりません。NestJS コンテナーがないプロジェクトは、NestJS の処理で失敗するのではなく、対象外になります。

--projects と --tags でコマンドラインからプロジェクトを選択する

どちらもカンマ区切りのリストを受け取り、同時に次の2つの処理を行います。

codependix map --write --projects widgets,tools/reporting --config configuration/codependix.config.ts
codependix map --write --tags framework:nestjs,language:python --config configuration/codependix.config.ts

エクスポート対象を広げます。 include glob、--projects glob、--tags タグのいずれかで指定されたプロジェクトが対象になります。フラグは設定で選択済みの対象を置き換えるのではなく、追加します。そのため、include が ["**"] のワークスペースで --projects widgets を指定しても、以前とまったく同じものがエクスポートされます。exclude は引き続き3つすべてより優先されます。フラグで除外されたプロジェクトを復活させられると、exclude が単なる助言になってしまうためです。

--projects は include と同様に、プロジェクトの名前またはワークスペース相対のルートに対する glob として照合されるため、--projects packages/* と --projects codependix-* はどちらも機能し、指定どおりの意味になります。--tags はプロジェクト自身の Nx タグと完全一致で照合されます。

描画および判定の対象を絞り込みます。 選択対象を指定すると、ワークスペース全体のグラフのノード集合も選択したプロジェクトに絞られ、--check boundaries が判定するプロジェクトもそれらだけになります。どちらも指定しない場合はすべてが選択されるため、デフォルトの動作は変わりません。

ゲートは依存先を含めて構築されます。 --check boundaries は、選択したプロジェクトと、それらが推移的に依存するすべての対象を含めて、各レベルのグラフを構築します。また、各検出結果をプロジェクトに割り当てます。循環はその中のすべてのプロジェクトに、禁止されたエッジはそのソースのプロジェクトに、コンテナーの起動失敗はそのコンテナーのプロジェクトに割り当てられます。検出結果が選択したプロジェクトに割り当てられた場合にのみ、実行は失敗します。依存先にのみ割り当てられた検出結果は、失敗にはならない注記「in dependency」としてログに記録されます。--no-dependencies を指定すると、選択したプロジェクトだけを対象に構築されます。高速になりますが、選択範囲外へ出るエッジは描画されなくなるため、依存先を経由して閉じる循環を見逃します。--no-dependencies で成功しても、デフォルト設定で成功した場合より意味するところは小さくなります。ローカルでの反復作業に使ってください。

どの対象にも一致しない選択は、どのモードでも拒否されます。 名前のスペルミス、どのプロジェクトも持っていないタグ、または（選択可能なプロジェクトではない）ワークスペースのルートを指定すると、何も判定しないままゲートを通過するのではなく、パターンを示すコマンドライン拒否としてゼロ以外の終了コードで終了します。

一部だけ一致する選択は拒否されず、警告されます。 --projects widgets,typo は widgets を判定し、stderr に警告 🕸️ Ignored selection entries that matched no project を記録します。一致しなかった projects と tags が一覧表示され、スペルを確認するための hint が示されます。終了コードは変わりません。そのため、正しい項目と並んだスペルミスの項目は、判定結果ではなくログに現れます。

include／exclude ではこのようなことは起こりません。これらはどのプロジェクトのエクスポートを書き出すかを決めるものであり、ワークスペースグラフやゲートには関与したことがありません。この違いが、これらのフラグが設定フィールドではなくフラグとして存在する理由です。

意図的に、Nx 独自の --projects=tag:foo という表記ではなく、2つのフラグを用意しています。それぞれが --help に独自の名前で表示されます。この違いを「修正」しないでください。

一度に1つのプロジェクトをゲートする

--check boundaries --projects <name> は、シェルから実行できるプロジェクト単位のゲートであり、Nx ワークスペースでは自動的に推論されます。@codependix/nx プラグインは、ワークスペースのルートを除き、project.json で記述されたすべてのプロジェクトに、キャッシュ可能な codependix-gate ターゲットを追加します。このターゲットは、NestJS が必要とするデコレーターを保持するローダーのもとで、ワークスペースのルートからこのコマンドをそのまま実行します。このローダーは、プラグイン自身の依存関係から登録されます。

nx run lexico-entities:codependix-gate   # one project
nx affected -t codependix-gate           # only what a change touched

各プロジェクトのゲートは、そのプロジェクトに割り当てられた問題があると失敗します。そのため、境界違反があれば、そのエッジを所有するプロジェクトと、サイクル上のすべてのプロジェクトが失敗します。どのプロジェクトの問題かを示さない、ワークスペース全体を対象とする単一のタスクが失敗するわけではありません。問題のあるプロジェクトに依存するだけのプロジェクトは、その問題を注記として表示して合格します。失敗するのは問題のあるプロジェクト自身のゲートなので、失敗を再現するには、表示されたプロジェクトのゲートを実行してください。

キャッシュキーには、プロジェクト、その依存関係、設定、codependix のコマンドラインが含まれますが、テストファイルは含まれません。選択対象が自分自身のプロジェクトと異なるゲートは、これらの入力でカバーされていないプロジェクトを判定するため、キャッシュから再実行されることはありません。自分自身のプロジェクトだけを判定するゲートは、通常どおりキャッシュされます。このターゲットは構成を宣言しないため、--configuration=check を指定したアグリゲーター実行では、デフォルト設定にフォールバックします。callidescope の callidescope-gate がその例です。このリポジトリでは、guard-code がこのターゲットに依存しています。ワークスペース全体の configuration:codependix ターゲットは書き込み専用です。デフォルトブランチでエクスポートを公開しますが、ゲートは実行しません。

実行結果のレポート

以前の実行が失敗していても、すべての処理が試行されます。また、あるプロジェクトの失敗はそのプロジェクトだけに分離されます。README がない場合や、NestJS プロジェクトでコンテナーの起動に失敗した場合は、そのプロジェクトの失敗として収集されますが、ほかのプロジェクトはすべて実行されます。--write は、完全に成功するか、失敗したプロジェクトを正確に示します。

3種類の問題が個別に報告され、いずれか1つでもあれば実行は失敗します。

• Failures — エクスポートを解決する前に例外が発生したプロジェクト、または判定対象のグラフを構築できなかったプロジェクトです。
• Stale exports — --check reports の実行時に、設定済みのエクスポートと、新たに構築されたグラフが一致しないものです。
• Boundary violations — --check boundaries の実行時に、宣言されたルールに違反するエッジやサイクルです。それぞれに、レベル、スコープ、ルール、両端、割り当て先のプロジェクト、そしてルールに記載された違反理由が含まれます。これらはコンソールと終了コードに反映され、レポートへの出力は --format、--json-output、または --markdown-output で求められた場合に限られます。現在問題になっている項目の一覧は、コミットする価値のある文書ではないため、--write が README に挿入するエクスポートに含まれることはありません。

target: "none" に解決されるプロジェクトは、最新であると報告されるのではなく、結果から完全に除外されます。そのため、終了コードは codependix が実際に生成するよう設定されたエクスポートだけに基づきます。--check の実行結果でプロジェクト数が 0 と報告された場合、生成対象が何も設定されていないことを意味します。

境界レポート

--check boundaries を実行し、--format json、--json-output <path>、または --markdown-output <path> を指定すると、検出結果がレポートとして出力されます。JSON では グラフの種類と並ぶ boundaries キーとして、Markdown では ### Boundaries セクションとして出力されます。--check boundaries のみを指定した実行では何もエクスポートされないため、レポートだけが出力されます。これらのフラグを指定しない場合、境界チェックのみの実行では何も出力されず、エクスポートも行う実行では、これまでどおりグラフが出力されます。

codependix map --check boundaries --projects lexico-entities --format json --config configuration/codependix.config.ts

boundaries.judgedProjects には、検出結果によって実行が失敗するプロジェクトが一覧表示されます。 violations と failures の各項目には、課金対象の projects と verdict が含まれます。fail は実行を失敗させ、note は判定対象プロジェクトの依存先で見つかった検出結果であり、実行を失敗させません。failures の項目（起動できなかったコンテナー）には、そのコンテナーが失敗したプロジェクトとは別のプロジェクトに属するクラスが原因の場合、ownerProject も記載されます。 fail の行を確認し、note の行は依存先自身のゲートで扱うものとしてください。

nxProjects レベルでの失敗（Nx プロジェクトグラフを構築できなかった場合）は、判定対象プロジェクトを判定できなかったため、すべての判定対象プロジェクトに課金されます。判定対象が複数の場合、一覧ではなく all N judged projects として出力され、Markdown レポートでは各プロジェクトの下ではなく、#### All judged projects の下に一度だけ記載されます。JSON には完全な projects 配列が保持されます。それ以外の各レベルではプロジェクトごとにグラフを構築するため、そこでの失敗は、起動できなかったコンテナーを含め、そのプロジェクトのみに課金されます。箇条書きのエラーテキストは改行を維持し、箇条書きの下にインデントして表示されます。また、テキストが HTML コメントを閉じないよう、--> は --> として記述されます。

エクスポートの読み方

Markdown の出力先には Mermaid 図が書き込まれます。アンカーモードでは、アンカー名を示す 2 つの HTML コメントマーカーの間に図が挿入されます。

```mermaid
graph LR
  widgets["widgets"]
  logger["logger"]
  widgets --> logger
  classDef subject fill:#7c3aed,color:#fff,stroke:#4c1d95,stroke-width:2px
  class widgets subject
```

強調表示された subject ノードは、Neighborhood の中心となるプロジェクトです。 ノード識別子は名前やパスから無害化されているため、識別子ではなく引用符で囲まれたラベルを確認してください。

JSON の出力先には、グラフ固有の形式で書き込まれます。Nx Neighborhood には dependencies、dependents、edges、projectName が含まれます。インポートグラフには fileNames、edges、isolatedFileNames、projectName が含まれます。NestJS モジュールグラフには、図から意図的に除外されたエッジを持つグローバルモジュールの ambientModuleNames が追加されます。

コミット済みのグラフを使ってコードベースに関する質問（これに依存しているものは何か、名前変更で影響を受ける箇所はどこか、インポートサイクルは実在するのか）に答えるには、codependix-navigate スキルを利用してください。

マーカーの内側を手作業で編集しないでください

次回の --write は、アンカーブロック全体を置き換えます。手作業で編集した図は、次の実行時に差分がひそかに消えてしまい、レビュー担当者には、理由も分からないまま変更が元に戻ったように見えます。

古くなった --check reports を修正するには、--write を再実行するだけで十分です。 ただし、--check boundaries の失敗を修正する方法にはなりません。これは実際のコードにある実際のエッジであり、エクスポートを書き込んでも解消されません。どちらの場合も codependix-triage スキルを利用し、ルール自体を確認または変更するには codependix-configure を利用してください。