conformetry-validate

適合性の確認と差分の修正

適合性は、インスタンス（ディスク上に生成されたコード）を、そのコードの元になったテンプレートと照合して測定します。差分とは、テンプレートで宣言されているものの、インスタンスにないものです。

すべての言語に適用される唯一のルール

インスタンスには、テンプレートで宣言されているものをすべて含める必要があります。追加したものが差分になることはありません。

宣言、キー、行、ファイルの追加や、クラスメンバーの並べ替えは、すべて問題ありません。したがって、差分の修正では、余分なものを削除するのではなく、不足しているものを追加するのがほとんどの場合に正しい方法です。適合させるためにファイルの内容を削除し始めるエージェントは、この仕組みに逆らっています。

生成されたファイル内では自由に実装できます。関数本体は一切比較されません。

実行方法

プロジェクトごと、またはワークスペース全体で実行します。

nx run <project>:conformetry-validate
nx run-many --targets=conformetry-validate

Nx を使用しない場合も、--config <path> を指定すれば、コマンドラインホストで同じ処理を実行できます。このフラグは必須で、デフォルトのファイルは想定されません。

conformetry validate --config configuration/conformetry.config.ts

Nx ワークスペースでは、パスは nx.json にある @conformetry/nx プラグインの configurationPath オプションから取得されます。エグゼキューターと sync ジェネレーターでも configuration オプションとして指定でき、その値が優先されます。パスを指定しないと、不足しているフラグまたはオプションを示す ConfigurationPathRequiredError が返され、実行は拒否されます。

どちらも言語で絞り込めます。また、コマンドラインホストでは、設定済みのインスタンスの代わりに一時的な glob を指定したり、照合対象のテンプレートを指定する --templates フィルターを使用したりできます。対象の絞り込みは反復作業のために使い、最終的な判定には全体の実行を使ってください。

conformetry validate --config configuration/conformetry.config.ts --templates nestjs-service-module
conformetry validate --config configuration/conformetry.config.ts --templates nestjs-service-module --languages typescript

--templates と --instances はペアリングの異なる側をそれぞれ絞り込み、実行対象は両方の条件の共通部分になります。どちらか一方がもう一方を上書きすることはありません。存在しないテンプレートを指定すると、実際の名前が一覧表示されて拒否されます。また、選択条件に一致するインスタンスがない場合は、正常なレポートとしてではなく "no instances belong to …" と報告されるため、タイプミスが合格と誤認されることはありません。

インスタンスグループに tags が付いたテンプレートは、コマンドラインホストでは検索できません。 これらの glob は、タグで選択された各プロジェクト内で読み込まれるため、src/modules/* はプロジェクトルートと結合されるまで意味を持ちません。ホストは、そのようなグループを作業ディレクトリから glob で検索せず、絞り込みを行った実行では、何も見つからなかったことを報告します。その場合は Nx のターゲットを使うか、パスを指定して --instances を渡してください。これが、conformetry validate --config configuration/conformetry.config.ts --templates nestjs-service-module では確認対象がないと報告されても、nx run <project>:conformetry-validate では多数の対象が確認される理由です。

エージェントのシェルはターミナルではありません。 そのため、そこで --templates を省略すると、このフラグが存在する前と同じようにすべてのテンプレートが検証されます。ターミナルで表示される選択画面を待つことはありません。--templates all は同じ意味を明示的に指定します。all は予約語であり、テンプレート名には使えません。

レポートの読み方

完全一致を下回るスコアがある場合、レポートの冒頭にスコアの概要が表示されます。続いて各ファイル、比較したインスタンスとテンプレート、そして推奨される修正を添えた各差分が一覧表示されます。

  1. file: orders.service.ts
     Instance: packages/widgets/src/modules/orders/orders.service.ts
     Template: configuration/conformetry-templates/nestjs-service-module/…

     1. Missing Decorator "Injectable"
        Instance: Line 12, Column 1
        Template: Line 8, Column 1
        Fix     : Add the missing Decorator "Injectable" to the instance file.

修正方法を考える前に、Fix 行を読んでください。 各差分には必ず修正方法が示されており、ファイル全般ではなく、具体的な構成要素が記されています。

位置は 1 始まりです。JSON の差分では、整形し直されたファイルではキーに意味のある行番号がないため、行番号ではなく scripts.build[0] のようなパスが報告されます。

特定のファイル形式で差分が何を意味するか（文字列リテラルをそのまま記述する必要がある理由、見出しのレベルが固定される理由、関数本体が自由な理由）については、references/languages.md を参照してください。

差分の種類と、それぞれに必要な対応

ファイルまたはディレクトリが見つからない場合。 内容の比較より先に確認され、ディレクトリ が見つからない場合、その中のファイルについては報告されません。そのため、ディレクトリを作成して再実行すると、その内容を示す新しい一連の報告が出ます。これはチェックが正しく機能しているのであって、リグレッションではありません。

宣言またはコメントが見つからない場合。 追加してください。コメントは順序付きの部分列として比較されるため、セクションマーカーが正しくない位置にあると、テキストが存在していても見つからないものとして扱われます。

Could not infer {{…}}: no instance node aligned with the template text that uses it — テンプレートではプレースホルダーが使われていますが、置換値が与えられておらず、テンプレート内の周辺テキストに対応するインスタンスノードもないため、検証で値を読み取れませんでした。インスタンスは、どのしきい値でも失敗します。ほかの検出結果も引き続き報告されます。プレースホルダーの位置に実際の値を入れて、そのテンプレートのテキストをインスタンスに戻すか、インスタンスグループの substitutions に値を指定してください。値が読み取られた場合、後続の使用箇所で値が一致しないと、通常の差分として表示されます。その場合は、誤っている方の箇所を修正してください。値の読み取り方法については、conformetry-configure スキルで説明しています。

インスタンスがどのテンプレートにも一致しない場合 — このパスを説明できるテンプレートがありません。そのパスが生成コードではなく、インスタンスの glob に含めるべきでないか、どのテンプレートでも認識できないほど乖離しています。

インスタンスが曖昧な場合 — 2 つのテンプレートが同程度に一致し、どちらも部分的にしか一致していません。テンプレートごとに識別可能なファイルを用意するか、適用対象が 1 つになるよう glob を絞り込んでください。

この最後の 2 つは内容ではなく帰属の失敗であり、報告だけから対応するのが最も難しいものです。どのテンプレートがそのパスを説明できるかを確認して、原因を特定してください。

conformetry templates --config configuration/conformetry.config.ts --instances packages/widgets/src/modules/orders

  nestjs-service-module (nsm)
    Generate a NestJS service module
    Template: configuration/conformetry-templates/nestjs-service-module
    Instances:
      packages/widgets/src/modules/orders 5/5 files 100%
  nestjs-command-module (ncm)
    Generate a NestJS command module
    Template: configuration/conformetry-templates/nestjs-command-module
    Instances:
      packages/widgets/src/modules/orders 3/5 files 60%

そのパスを説明できるテンプレートは、勝者だけでなくすべて表示されます — それが重要な点です。1 つのパスが正当に複数のテンプレートに属する場合があるため、判定を 1 つに絞ると、差分の原因となった同率の一致が隠れてしまいます。これは順位として読み取ってください。上位にあると思っていたテンプレートが下位にある場合、そのテンプレートのファイルがインスタンス側の配置と合っていません。

逆方向を確認するには、生成コードがどこにあり、それぞれがどのテンプレートに対応するかを調べます。

conformetry instances --config configuration/conformetry.config.ts
conformetry instances --config configuration/conformetry.config.ts --templates nestjs-service-module

表示される各パスは、上記の --instances 引数として使用できるため、2 つのコマンドを組み合わせて実行できます。--templates を指定すると、特定のテンプレートが説明できるインスタンスに絞り込めます。これにより、そのテンプレートを変更した場合に影響を受けるすべてのインスタンスを確認できます。

どちらのコマンドも、解析用に --json を指定できます。すべてのコマンドで --config <path> が必須です。既定のファイルは想定されていません。references/template-matching.md では、帰属の仕組みと順位の読み方を説明しています。

バグのように見えて、そうではない 3 つの動作

すべて修正したのに、2 回目の実行で新しい差分が報告されることがあります。 ファイルごとに報告されるのは、最も一致度の高い小さいテンプレートの要件だけです。それらを満たすと、より大きなテンプレートに固有の要件が表面化します。2 回目の報告をリグレッションと見なすのではなく、差分がなくなるまで繰り返してください。

Python インタープリターが見つからない場合、クラッシュではなく差分として報告されます。 .py ファイルに対して Python が利用できないという差分が表示された場合、テンプレートを変更するのではなく、python3 をインストールしてください。

自動修正は行われません。 自動修正機能も書き込みモードもありません。結果を変える唯一のフラグは --threshold で、ファイルを変更するのではなく、何を合格とするかを変更します。修正するには、インスタンスを手動で編集するか、再生成する必要があります。ただし、再生成では無条件に上書きされるため、実行する前に conformetry-generate を確認してください。

編集するか再生成するかの判断

差分が少なく、そのファイルに残したい作業が含まれている場合は、インスタンスを編集してください。 ほとんどの場合、それが正解です。

インスタンスが大きく乖離し、手作業で再構築するほうが手間になる場合に限り、再生成してください。また、再生成によって何が失われるかを確認してから行ってください。生成処理には、既存ファイルの確認、マージ、競合検出の機能がありません。

スコアとしきい値

実行結果は、インスタンスが適合しているかどうかだけでなく、テンプレートの要件をどの程度満たしているかも採点し、スコアが適用されるしきい値を下回った場合、そのインスタンスを失敗とします。差分には重みがあり、スコアは重み付けされた要件のうち、満たされているものの割合です。

レポートには、差分の上にConformance scores:の概要が出力されます。完全一致に達しなかったすべてのインスタンスについて、しきい値を満たしたかどうかと、ワークスペース全体の合計が表示されます。

しきい値のデフォルトは完全一致を意味する1なので、新しいワークスペースでは厳格です。 3 つのレベルで設定でき、より狭い範囲の設定が優先されます。順に、インスタンスグループのthreshold、ジェネレーターのthreshold、実行時の--thresholdです。

覚えておきたい点が 2 つあります。

• しきい値を下げると、差分が許容されるだけで、差分が隠されるわけではありません。 しきい値を満たしたインスタンスの差分も引き続き出力されます。レポートに差分があっても、実行が失敗したとは限りません。スコアの概要を確認してください。
• しきい値を下げるのは移行のためであり、差分を黙らせるためではありません。 既存のインスタンスを新しいテンプレートに段階的に移行するための機能です。インスタンスを適合させられるなら、適合させてください。なお、差分ごとに重大度を下げる機能はありません。

作業完了を宣言する前に

適合チェックを問題なく通過することは、任意の仕上げではありません。生成されたコードが今も標準に一致しているかを確認するためのものです。生成後、生成されたファイルの編集後、そして実装の完了を宣言する前に実行してください。

サンドボックスで差分を再現する

conformetry-examplesには、差分の種類ごとに意図的に壊したインスタンスが 1 つずつ用意されているため、周辺プロジェクトの規約に惑わされずにレポートを理解できます。

• drift-catalogue — ファイルの欠落、ディレクトリの欠落、エクスポートの削除、セクションコメントの脱落、クラス名の変更を含み、レポート全体も引用されています。
• structural-not-textual — フォーマットし直したインスタンスは合格し、その一方で、エクスポートが 1 つだけ欠けたインスタンスは不合格になります。
• scoring-thresholds — しきい値を下げて合格したインスタンスの差分が出力される例と、それでも終了コードが 0 になる実行例です。
• ambiguous-attribution — 2 つのテンプレートが同じ程度に説明できるインスタンスです。
• failure-modes — 誤った理由で適合している 2 つの例です。

その AGENTS.mdでは、レポートの文言と、それを再現する例を対応付け、インスタンスへの変更のうち、差分になるものとならないものを一覧にしています。ここにある壊れたインスタンスは意図的に壊されています。修復しないでください。