conformetry-generate

conformetry による生成

conformetry のジェネレーターは、テンプレート（通常のファイルをまとめた通常のフォルダー）を、ディスク上のインスタンスにレンダリングします。同じテンプレートが、その後インスタンスを評価する基準となります。そのため、生成は単なる利便性ではありません。テンプレートですでに定義されている形式で手書きしたコードは、最初から適合性に失敗します。

ファイルを手書きする前に、ジェネレーターがないか確認してください

推測したジェネレーター名は拒否されるため、名前を推測せずにレジストリを確認してください。

conformetry templates --config configuration/conformetry.config.ts

すべての conformetry コマンドで --config <path> が必要です。既定のファイルは想定されていません。Nx ワークスペースでは、出力されたプラグインでも同じ情報を確認できます。

nx list conformetry

どちらも最新の設定を読み取るため、現在のワークスペースに対して正確な情報が得られます。ジェネレーターの追加に伴って出力内容は変わるため、どちらの出力もメモに保存しておく価値はありません。

生成では無条件に上書きされます

書き込み処理には、ファイルの存在確認も、存在する場合にスキップする機能も、マージも、競合検出もありません。テンプレート内のすべてのファイルがレンダリングされ、既存の内容があれば上書きされます。

残しておきたい作業がすでにあるパスを、ジェネレーターの出力先に指定しないでください。 既存のインスタンスを変更する場合は、編集してください。既存の内容を破棄する意図がある場合、またはテンプレートで必要なファイルがインスタンスに欠けており、置き換えられる内容を確認した場合にのみ、再生成してください。

Nx の経路では Tree を介して書き込むため、--dry-run は実際に機能し、どのような内容が書き込まれるかを正確に表示します。

nx g conformetry:<generator> --name=<name> --project=<project> --dry-run

出力先が不明な場合は、まずこれを実行してください。

2 つのエントリーポイントでは、入力の扱いが異なります

これは生成に関して最も混乱しやすい点ですが、不具合ではありません。同じジェネレーターでも、呼び出し方によって動作が異なります。

	Nx プラグイン	コマンドラインホスト
呼び出し方法	nx g conformetry:<name>	conformetry generate --config <path> --template <name>
入力	宣言されたすべての入力が必須	常に必須ではありません
入力が不足している場合	拒否されるか、入力を求められます	テンプレートで補間される場合は拒否されます
既定の出力先	ワークスペースを基準に解決されます	generated/<generator-name>

残る違いは、不足している値が検出されるタイミングです。Nx の経路では宣言されたすべての入力が最初から必須のため、レンダリング開始前に拒否されます。コマンドラインホストでは入力は必須ではなく、テンプレートが値を要求した時点で不足が検出されます。エラーは MissingSubstitutionError で、プレースホルダーとテンプレートファイルの名前が示されます。

そのため、テンプレート内で一度も補間されない入力は、コマンドラインホストでは省略できますが、Nx の経路では省略できません。テンプレートで実際に補間される値は、どちらでも必須です。

どちらの経路でも、すべての入力を明示的に渡してください。 「任意」を意味するテンプレートでは、{{#owner}}…{{/owner}} のようなセクションを使います。これなら owner がない場合は何もレンダリングされません。単独の {{owner}} に頼らないでください。

どちらの経路でも、ジェネレーターは完全な名前で指定します。短い別名はありません。名前を間違えると、どちらのホストでも正しい名前が一覧表示されます。

フラグは --generator ではなく --template です。 設定（templatePath）、templates コマンド、適合性レポートですでに使われている用語に合わせています。--generator は別名として残さず削除されており、指定するとフラグ名を示して拒否されます。このコマンドは、テンプレートの入力をフラグとして渡せるよう、不明なフラグを受け付けます。そのため、この拒否がなければ、古いスクリプトの --generator は黙って無視され、正常に動作したように見えてしまいます。

--template は、コマンドラインでは省略することもできます。ターミナルで省略すると、説明付きで設定済みのすべてのテンプレートが表示され、オートコンプリートで選択できます。エージェントシェルはターミナルではないため、必ず指定してください。 エージェントシェルで省略すると、プロンプト待ちのままになるのではなく、利用可能な名前の一覧を表示して実行が拒否されます。

出力先

Nx の場合、出力先は次の順で解決され、最初に一致したものが採用されます。

1. 明示的に指定した --directory。
2. project 入力がない場合 — 新しいプロジェクトとして扱われ、type 入力に基づき、同じタイプのプロジェクトと同じ場所に配置されます。
3. module 入力がある場合 — その既存のモジュールに配置されます。存在しないモジュールを指定した場合はエラーになり、作成されることはありません。
4. ジェネレーターのインスタンスグループにある最初のタグ付きパターンから決まる、ジェネレーター固有のスコープ付きディレクトリ。
5. そのジェネレーターのインスタンスが最も多く配置されているディレクトリ。
6. プロジェクトのルート。

手順 4 と 5 があるため、ジェネレーターには通常、出力先を指定する必要はありません。自身のインスタンスがどこにあるかを把握しているためです。この慣例から外れた場所に意図的に配置する場合は、--directory を指定してください。

コマンドラインホストで適用されるのは --directory だけです。指定がない場合は generated/<generator-name> になります。これはスクラッチ用の場所であり、ソースツリーではありません。ワークスペース内に書き込む場合は、必ず --directory を指定してください。

人がその場にいない状態での実行

コマンドラインホストは、stdin がターミナルの場合は常にプロンプトを表示します。これを無効にするフラグはありません。ターミナルが接続されていることだけが条件なので、エージェントのシェル、フック、CI ジョブでプロンプトが表示されることはありません。

ジェネレーターが宣言する入力はすべて必須です。どちらのエントリポイントでも同じです。ジェネレーターは各プレースホルダーを置換しますが、mustache は入力がない場合にエラーを出さず、空文字列としてレンダリングするため、入力を任意にすると、生成ファイルに気付かないまま空欄が生じます。ターミナルがない状態では、渡していない入力があると、そのフラグ名を示すハードエラーになります。暗黙のデフォルトになることも、応答できる人がいない場面でメニューが表示されることもありません。テンプレートが宣言する入力をすべて渡すか、質問に答えられる環境で実行してください。

生成後

どちらも手間がかからず、よくある種類のミスをまとめて検出できる 2 つの手順があります。

1. 生成したものの準拠状況を確認します。生成されたインスタンスは構造上、準拠しているため、差異がある場合は、出力先が間違っている、入力が空だった、または既存のものを上書きしたことを意味します。conformetry-validate スキルを参照してください。
2. 生成されたファイル内に実装します。 その隣に別の構造を作らないでください。テンプレートのセクションコメントと宣言が契約です。内容を追加するのは常に問題ありませんが、削除すると壊れます。

ジェネレーターがまだ存在しない場合

ジェネレーターの追加はコード変更ではなく、設定変更です。conformetry-configure スキルを参照してください。追加直後に注意すべき点が 2 つあります。生成された Nx プラグインは nx sync で再生成する必要があり、定義が古いまま動作することを避けるため、conformetry の各コマンドは最新でない状態では実行を拒否します。

読むだけでなく、実際に試す

conformetry-examples には、設定、テンプレート、インスタンス、コマンドをそれぞれ備えた、自己完結型の例が 12 個あります。見慣れないものをスキャフォールディングする前に、次の 2 つを実行してみてください。

• hello-template — 存在する最小のジェネレーターです。2 つのコマンドで生成から検証まで行うため、一連の流れを最初から最後まで確認できます。
• case-variants — パスと内容におけるすべての派生ケースバリアントと、明示的な入力でその 1 つを上書きする方法を確認できます。

それぞれ約 1 秒で実行でき、ガイドには生成される出力が記載されています。その出力は、パッケージ独自のテストスイートで検証されます。各例がどの質問に答えるのかは、その AGENTS.md を参照してください。