codependix-triage

codependix の失敗への対処

codependix はいくつかの異なる結果を報告します。どの結果が発生したかを読み取ることが、作業の大半を占めます。まず、それぞれを区別してください。境界違反は実際のコードにある実際のエッジ、古いエクスポートは不整合、失敗はエクスポートを生成するところまで到達しなかったプロジェクト、そして何も書き込まなかった実行は通常、そのどちらでもありません。

境界違反

--check boundaries によって、宣言されたルールに反するエッジまたはサイクルが見つかりました。各違反には、グラフのレベル、見つかったスコープ、ルール、両端のノード、対象となるプロジェクト、およびそのルールが示す発生理由が記載されています。

失敗に示されたプロジェクトから始めてください。 Nx ワークスペースでは、各プロジェクトに独自の codependix-gate ターゲットがあります。そのため、nx run <project>:codependix-gate が失敗した場合、検出事項はそのプロジェクトに課されています。つまり、禁止されたエッジはそのソースを所有するプロジェクトに、サイクルはそのサイクル上のすべてのプロジェクトに課されます。同じターゲットで再現するか、codependix map --check boundaries --projects <project> --config configuration/codependix.config.ts を実行してください。検出事項をデータとして読むには、--format json を追加します。ゲートを失敗させる検出事項は、そのプロジェクトに課されているものです。「依存先 X では失敗していません」という行は注記であり、失敗するのは X 自身のゲートです。検出事項を出力したプロジェクトではなく、注記に示された場所で修正してください。

再実行しても直らない検出事項は、これだけです。 古いものは何もなく、再生成も必要ありません。エッジはコード内にあるため、次のどちらかを行う必要があります。

1. エッジを取り除く。 通常はこれが正しい対応であり、見た目より小さな変更で済むことが多いです。型を *.types.ts ファイルに移す、依存関係を逆転させる、または両端から参照できるパッケージに共有要素を切り出す方法があります。
2. ルールを変更する。 ルール自体に誤りがある場合に行います。理由とともに codependix.config.ts に明記すべき意図的な判断であり、実行が成功するまでセレクターをひそかに広げることではありません。

失敗したチェックを通すことだけを目的に、セレクターを狭めたり、除外を追加したり、ルールを削除したりしてはいけません。通すために緩めたゲートは、もはや何も保護しません。また、次に読む人には、それが以前は何かを保護する意図だったと知る手がかりがありません。

違反が nx レベルにあり、背後にインポート文のないエッジが示されているなら、それがこのレベルの役割です。implicitDependencies の項目は実際のプロジェクトグラフのエッジであり、@nx/enforce-module-boundaries からは見えません。その項目を削除するか、ルールを変更する必要があります。

古い --check reports

設定されたエクスポートの一つ以上が、新たに構築されたグラフと一致していません。実行結果にはプロジェクト名が示されます。

--write を再実行してください。それだけで修正できます。 グラフは、それが表すワークスペースとともに変化します。そのため、プロジェクトグラフが変わると、それをもとに生成されたすべてのエクスポートが古くなります。これは調査すべき欠陥ではなく、更新すべき不整合です。

アンカーマーカーの内側を手動で編集してはいけません。 次の --write でブロック全体が置き換えられるため、図を編集しても差分ができ、次回の実行時に気づかれないまま消えます。単独の Markdown ファイルも同様です。内容全体を codependix が管理します。

古いチェックが意味しないことが、ほかに二つあります。

• conformetry の準拠状況の違いではありません。 codependix:start ／ codependix:end マーカーは codependix 独自の構文であり、conformetry-* パッケージへの依存はありません。準拠チェックを実行したり、conformetry のジェネレーターを使ったりしても、ここでの問題は解決しません。
• アンカーがないことの証拠ではありません。 一度もエクスポートされていないプロジェクトには比較するブロックがなく、ほかの不整合と同様に古いものとして報告されます。

失敗したプロジェクト

失敗はプロジェクトごとに収集され、名前で報告されます。一つのプロジェクトが失敗しても、残りは停止しません。 その実行で残りのプロジェクトはすべて引き続き処理され、それ以前の処理が失敗したかどうかに関係なく、4 種類すべてのグラフの処理が試行されます。そのため、3 件の失敗が示された実行は、再試行すべき不安定な実行ではなく、修正すべき問題が 3 件あるということです。

Markdown ファイルが存在しない

完全に失敗する唯一のアンカー問題です。アンカーブロックがない場合は--writeで自動作成されますが、ファイルがない場合は作成されません。READMEがまったくないプロジェクトは、配置されていないブロックよりも深刻な問題であり、ファイルを新規作成することは、依頼されていないドキュメントを執筆することになるためです。

ファイルを作成してください。少なくとも見出しを含むプロジェクトのREADMEを用意してから、再実行してください。

--writeでアンカーブロックがない場合

失敗ではありません。--writeは、安全な次の2か所のいずれかにブロックを作成します。

• ファイル末尾に、新しい## 🕸️ Codependixセクションとして追加します。導入行と、グラフの種類に対応する### <Subheading>を含みます。
• 先行するグラフの種類によって既に## 🕸️ Codependixセクションが作成されている場合は、その末尾に新しい### <Subheading>として挿入します。

誰かが作成しているドキュメント内の別の場所にブロックを配置することはなく、見出しを重複させることもありません。ブロックが意図しない場所に配置された場合は、マーカーペア全体を一度手動で移動してください。以降の--writeでは、その位置で内容が置き換えられます。

コンテナーの起動に失敗したNestJSプロジェクト

NestJSのパスでは、プレビューモードでプロジェクトのコンテナーを調べます。このモードでは、モジュールとプロバイダーをすべて登録しますが、どれもインスタンス化しません。TypeOrmModule.forRootAsyncのオプションファクトリーを構築するプロジェクトでは、データベースへの接続は発生しません。そのため、このパスで問題になるのは、モジュールの「登録」中に例外をスローするケースだけです。たとえば、存在しない変数を参照する静的なforRoot引数を持つモジュール、モジュールファイルのトップレベルで例外をスローする処理、またはパスが期待するものをエクスポートしていないルートモジュールを持つプロジェクトなどです。そうした箇所を確認してください。

起動に失敗したコンテナーを持つプロジェクトに失敗が計上されます。失敗の原因となったモジュールまたはクラスが別のプロジェクトに属する場合は、メッセージにそのプロジェクト名も示されます。インポート時に例外をスローするエンティティパッケージをインポートしているプロジェクトも失敗し、修正すべき箇所はその所有元のプロジェクトです。デコレーターが、モジュールの評価完了前にクラスを読み取ってしまうエンティティファイル間の値インポートの循環は、ここでCannot access 'X' before initializationとして表面化します。これは起動時の失敗であり、acyclicの検出結果ではありません。

アプリケーションは、nestjsModules.rootModulesエントリーで指定されたモジュールとエクスポートをルートとします。そのようなファイルを持たないライブラリパッケージは、そのパッケージが定義するすべての*.module.tsから合成モジュールを構築してルートとするため、単独ではインポートできないモジュールファイルがあると、アプリケーションでは気付かれない問題がライブラリで発生します。

もっともらしく見えても解決にならない方法が2つあります。データベースを起動またはシードすること（このパスはデータベースに接続しません）と、先にプロジェクトをビルドすること（プロジェクト自身のTypeScriptモジュールソースを直接インポートします）です。

CLIを別のローダー経由でTypeScriptソースから実行している場合は、デコレーターのメタデータが保持されているか確認してください。NestJSのコンストラクターインジェクションはメタデータを読み取りますが、通常の型削除ではそれが消去されるため、コンテナーが自身のプロバイダーを解決できないように見える失敗が発生します。公開されているcodependixバイナリはデコレーターを保持するローダーを自動で登録し、Nxゲートも同様です（@codependix/nx/loader経由で登録するため、ワークスペースに@swc-node/registerは不要です）。独自の実行方法を用意している場合は、同じ設定が必要です。ローダーはワークスペースルートのtsconfig.jsonを読み取るため、ルートのtsconfig.jsonでデコレーターのメタデータが出力されない場合も、同じ問題が発生します。

Nxプロジェクトグラフを構築できなかった

nxProjectsレベルではワークスペース全体のグラフを1つ構築するため、構築できない場合、判定対象のすべてのプロジェクトに失敗が計上されます。各ゲートでその失敗が報告され、判定対象のプロジェクトが複数ある場合、プロジェクトの一覧ではなく「判定対象のプロジェクトN件すべて」と表示されます。これはN件の問題ではなく、1つの問題です。個々のプロジェクトではなく、プロジェクトグラフそのものを確認してください。構築を妨げる原因は、どのゲートでも同じように影響します。

期待より少ない対象を判定して成功した実行

--projects または --tags のリストに、存在するプロジェクトと存在しないプロジェクトが含まれていても実行は続行され、一致した項目だけが判定されます。実行時には標準エラー出力に 🕸️ Ignored selection entries that matched no project が記録され、一致しなかった projects と tags が、スペルを確認するよう促すヒントとともに一覧表示されます。終了結果は一致した項目によって決まります。入力したリストから選択した実行が成功した場合は、標準エラー出力を確認し、信頼する前にスペルを修正してください。何も一致しない選択は、代わりに拒否されます。

拒否されたコマンドライン

--check には、boundaries と reports から選んだ値をカンマ区切りで指定します。コマンドライン全体は、ほかの処理が始まる前に読み取られます。

• --check needs a value — 値のない --check、または値が区切り文字だけの --check です。値を指定してください。フラグを外してはいけません。「何もゲートしない」と解釈すると、失敗できないゲートになってしまいます。
• --check does not accept "..." — 別のツールの名前です。limits は codometer のもので、depth は callidescope のものです。共通しているのは reports だけです。
• --write cannot be combined with --check reports — 書き込んだばかりの実行で、そのエクスポートが古い状態になることはありません。--write --check boundaries は有効です。
• --check も --write も指定しない場合は、ターミナル上で確認が求められます。それ以外の場所ではすべて拒否されます。エージェントや CI ジョブが行う実行も同様です。どちらにも回答できるターミナルがないためです。何も推測されず、デフォルトの書き込みも行われません。

1 つのコマンドラインに複数の間違いがある場合、報告する前にすべて収集されます。そのため、2 件の指摘は、2 回実行するのではなく、修正すべき事項が 2 つあることを意味します。

コマンドは、単独の codependix ではなく codependix map です。サブコマンドのないコマンドラインは、これらの条件が適用される前に引数パーサーによって拒否されます。--config <path> がない場合も同様です（このリポジトリでは --config configuration/codependix.config.ts）。このフラグは必須であり、エラーにはその旨が示されます。

ファイルが生成されなかった --write

最も目立たない結果で、バグであることはほとんどありません。実行は 0 で終了し、設定されたエクスポートがすべて最新であると報告して、何も書き込みません。これは、何も設定されていなかったためです。未設定の target はすべてデフォルトで "none" になり、"none" に解決されるプロジェクトは、最新として報告されるのではなく、結果から完全に除外されます。そのため、レポートのプロジェクト数が 0 なら、codependix は何も生成しないよう設定されています。

ツールを疑う前に、次の点を順に確認してください。

1. --config には意図したファイルが指定されていますか？ このフラグは必須で、ファイルが存在する必要があります。そのため、パスが存在しないかスペルが間違っていると、明確なエラーになります。ただし、別のファイルを指定している場合は、空のファイルを指定したときとまったく同じように見えます。
2. target は設定されていますか？ 出力先を持つグラフ型であっても、target がなければ "none" に解決されます。
3. フィールド名は defaults ですか？ default は不明なキーとして除外され、効果がありません。
4. 設定に include は指定されていますか？ デフォルトでは何も含まれないため、defaults だけを指定した設定では、どのプロジェクトも選択されず、エクスポートも行われません。実行時には 🕸️ Selected no project to export と警告されますが、終了コードは 0 のままです。また、--check boundaries は include にかかわらずすべてのプロジェクトを判定するため、成功のままです。ワークスペース全体を対象にするには、include: ["**"] と記述してください。
5. プロジェクトは include に一致し、exclude の対象から外れていますか？ どちらも、プロジェクトの Nx 名とワークスペースからの相対ルートの両方に照合されます。
6. --directory はワークスペースのルートですか？ すべてのプロジェクトのパスが解決される基準であり、スキャン対象のサブツリーではありません。Nx はプロセスの作業ディレクトリからグラフ自体を解決します。単一プロジェクトのフォルダーを指定すると、実行は引き続きグラフ全体を読み取りますが、すべてのプロジェクトをそのフォルダー配下に解決するため、エクスポート先が予期しない場所になったり、README が存在しないために失敗したりします。

codependix-configure スキルでは、これらのフィールドをそれぞれ解説しています。

拒否される設定

検証では、要求された内容の一部だけを黙ってエクスポートするのではなく、出力先の不一致を2種類拒否します。json の出力先がない状態での "both" または "json" ターゲットと、markdown の出力先がない状態での "both" または "markdown" ターゲットです。同じ理由から、anchor も path も指定されていない markdown 出力先も拒否されます。エクスポート先を示すものが何もないためです。

グラフの問題を解決するのは誰か

完成したエクスポートは説明であって、判定ではありません。エクスポートはコードベースの構造に対して何も制限を課さず、制限を課すのは宣言された境界ルールだけです。循環や、プロジェクトが想定をはるかに超える依存関係を持つなど、警戒すべきものを示す図は、どのルールにも違反していなくても、コードに関する実際の指摘です。修正すべきなのはエクスポート設定ではなくコードです。変更を加える前に、codependix-navigate スキルを使って、グラフが実際に何を示しているのかを確認してください。