konsistent-config

konsistent の設定

プロジェクトの構造上の規約を適用する konsistent.json ファイルを作成または編集します。konsistent CLI はファイルシステムの構造と TypeScript のエクスポート／インポートをチェックします。スタイルリンターではありません。

主な目的

重要な注意事項： konsistent のチェック実行時にエラーがゼロになるような konsistent.json ファイルは作成しないでください。それでは目的を果たせません。コードベースで使われているパターンへの違反を特定する konsistent.json ファイルを作成することが目的です。パターンが完全には守られていない場合でも同様です。コードベースで優勢なパターンに基づいて規約を追加してください。他の箇所でそのパターンに違反していても構いません。

既存のコードベースは、すべての規約を受け入れなければならない仕様ではなく、規約を推測するための根拠として扱ってください。優勢なパターンに従っていない既存ファイルは、想定される検出結果であり、その規約が誤っている証拠ではありません。

設定が正常でも、konsistent は違反を報告して終了することがあります。それらの違反は、意図された監査結果です。エラーなしで成功することが期待されるのは、konsistent validate のみです。

ワークフロー

1. konsistent CLI のセットアップ（まだセットアップされていない場合のみ）

konsistent パッケージがすでにインストールされているか確認します。

• ルートの package.json で konsistent が利用可能
• node_modules/konsistent ディレクトリが存在する
• package.json に konsistent スクリプトが存在する

インストールされていない場合は、まず konsistent CLI をインストールする必要があります。プロジェクトのパッケージマネージャーを使用してください。たとえば、PNPM の場合：

pnpm add konsistent --save-dev

次に、package.json に konsistent CLI を実行する konsistent スクリプトがあることを確認してください。最低限、次のようにします。

  "scripts": {
    "konsistent": "konsistent"
  }

これらすべての準備ができたら、セクション 2 に進みます。

2. konsistent.json ファイルの有無に基づく操作モードの決定

1. プロジェクトのルートに konsistent.json がすでに存在するか確認します。
2. node_modules/konsistent/konsistent.schema.json を読み、正式な構造を確認します。
3. 変更を行う前に、node_modules/konsistent/docs/ にある関連ドキュメント（下記の参考資料を参照）を読みます。
4. konsistent.json が存在する場合：内容を読み、ユーザーの依頼に応じて規約を追加、削除、更新します。
5. konsistent.json が存在しない場合：プロジェクトのルートに作成します。

3. konsistent.json ファイルの作成または編集

ユーザーのコードベースを調査して、既存の構造と命名パターンを把握します。確認すべき点については、node_modules/konsistent/docs/guides/exploring-codebases.md を参照してください。

コードベースを全体的に見渡して、構造上の規約を確認してください。ネストされたサブディレクトリが複数階層にわたる大規模なコードベースでは、コードベースの各セクションを個別のサブエージェントに調査させることを検討してください。各サブエージェントには、以下のサブセクションで説明する分析要件をすべて伝え、最終的な優勢パターンの判断ではなく、根拠となる生データの収集を担当させてください。

サブエージェントが別々のセクションを調査する場合、その調査結果を統合して、関連するコホート全体を構成できるようにしてください。各サブエージェントは、調査対象の範囲、その範囲に含まれる合計インスタンス数、規約に適合する数と適合しない数、競合するパターン、代表的な例を報告する必要があります。メインエージェントはこれらの調査結果を統合し、コホート全体を再構成したうえで、統合した根拠に基づいて優勢パターンを判断してください。委任したセクション内で優勢なパターンが、コホート全体でも優勢とは限りません。

単一ファイル内だけでなく、関連ファイル間の規約も考慮してください。haveFiles 述語を使って、照合されたファイルに基づき特定の別ファイルが存在することを確認し、for.files を使って、照合されたファイルに基づき特定の関連ファイル内で規約を適用してください。

必須のパターン証拠

各候補の規約について証拠を記録するまでは、設定を記述しないでください。候補ごとに、次の手順を実行します。

1. すべての兄弟パッケージ、アダプター、ルート、またはバレルファイルなど、関連するコホート全体を定義します。単一ファイル内だけでなく、関連ファイル間の規約も検討してください。

• たとえば、haveFiles 述語を使って、マッチしたファイルに基づき特定の別ファイルが存在することを確認し、for.files を使って、マッチしたファイルに基づき、関連する特定の別ファイル内で規約を適用します。

2. コホートの総数、規約に従っているもの、従っていないものを数えます。必ず分母を含めてください。少数の一致例だけでは、優勢なパターンとは言えません。
3. 裏付けとなる例を探すのと同じくらい意識的に、反例を探します。規約に従っている例と従っていない例の両方から、代表的なものを調べてください。
4. 競合するパターンを比較します。デフォルトでは、候補が少なくとも3回出現し、関連するコホートの3分の2以上を占める場合に限り、その候補を優勢とします。
5. 優勢な「勝者」がいない競合パターンに遭遇した場合は、いったん立ち止まり、どのパターンを適用するか（またはどれも適用しないか）ユーザーに尋ねてください。
6. 確立された各規約（優勢な候補またはユーザーの判断によるもの）について、規約に従わない例が違反なのか、それとも意味的に異なるコホートに属するのかを判断します。既存の差異があるだけでは、正当な例外とは言えません。

調査中は、次の証拠表を使用してください。

候補の規約	コホート	適合	違反	競合するパターン	決定
各パッケージに src/index.ts がある	12 パッケージ	10	2	なし	適用
サービスファイルに -service 接尾辞を使用する	9 個のサービスファイル	5	4	-service と -svc	あいまい。ユーザーに確認

競合するすべてのバリエーションを有効にするような条件を作ってはいけません。証拠があいまいな場合は、どの規約を適用するか、あるいはどれも適用しないかをユーザーに確認するため、いったん作業を止めてください。

敵対的レビュー

候補を設定に反映する前に、それを否定することを試みてください。

• 裏付けとなる例をいくつか見つけた時点で止めず、コホート全体を検索します。
• より強い競合規約や、コホートを変える意味的な境界がないか確認します。
• 別のツールがすでにその動作を適用していないか確認します。
• 既存のファイルをすべて説明できる規則よりも、真の逸脱を明らかにする規則を優先します。

このレビューの目的は、根拠の弱いパターンや捏造されたパターンを排除することです。強いパターンへの違反をなくすことではありません。

既存の設定を変更する場合：

• ユーザーの依頼に関係しない規約はすべて維持します。
• 変更を求められない限り、既存の name、description、severity の値を維持します。
• 規約を追加する場合は、conventions 配列の末尾に追加します。
• ユーザーから違反の報告があった場合は、既存の設定と違反しているファイルを読み、設定を修正すべきか、コードの修正を提案すべきか判断します。

禁止されている最適化

以下のいずれかの結果を得るために、設定を最適化してはいけません。

• 報告される違反をゼロにする。
• 既存のファイルをすべて有効にする。
• 確認されたすべてのバリエーションを許容する。
• CLI 実行後の違反数を減らす。
• CLI の終了コードを 0 にするためだけに、規約の severity を「warning」に設定する。

既存のコードが規約に違反しているという理由だけで、規約を弱めたり、範囲を狭めたり、条件を追加したり、除外したりしてはいけません。

検証

package.json スクリプト経由で konsistent validate を実行し、生成した設定を検証します（例：pnpm konsistent validate）。

検証に成功したら、エビデンスに基づく設定を確定し、引数を指定せずに package.json スクリプト経由で konsistent を実行して、実際のコードベースを監査します。報告された違反は設定の失敗ではなく、監査結果として扱います。

監査後に設定を変更できるのは、次のいずれかに該当する場合のみです。

• 設定がエビデンス表に記録されたパターンを表現していない。
• パスパターンに、別個の意味的コホートが誤って含まれている。
• 設定で konsistent のスキーマまたは述語 API が誤って使用されている。
• 新たに見つかったコードによって記録済みのエビデンスが大きく変わり、候補が最多ではなくなった。

「既存ファイルがこのルールに違反している」は、設定を変更する十分な理由には決してなりません。監査後に変更を行う場合は、該当する許可理由を明記し、必要に応じて記録済みのエビデンスを更新してください。

参考資料

正式なドキュメントはすべて node_modules/konsistent/docs/ にあります（パッケージに同梱）。設定を作成する前に、以下を読んでください。

• node_modules/konsistent/docs/reference/configuration.md — トップレベルの konsistent.json の構造（version、conventions、severity、excludeFiles）。
• node_modules/konsistent/docs/reference/predicates.md — すべての must 述語（haveType、haveFiles、export、exportTypes、exportConstants、exportFunctions、exportInterfaces、exportClasses、import、importTypes）。
• node_modules/konsistent/docs/reference/path-patterns.md — glob、プレースホルダー、ケース変換（toPascalCase、toCamelCase、toFlatCase、toNthSegment、extract など）、否定。
• node_modules/konsistent/docs/reference/constraints.md — インラインのパス制約に使用する matches、segments と if.placeholderSatisfies。
• node_modules/konsistent/docs/reference/conditional-rules.md — must が配列の場合の if／for／excludeFiles ブロック。
• node_modules/konsistent/docs/reference/case-maps.md — 頭字語や特殊な大文字・小文字の使い分けに用いる kebabToPascalMap、kebabToCamelMap。
• node_modules/konsistent/docs/guides/examples.md — コピーして使える一般的なパターン（プロバイダーパッケージ、ファクトリー、アダプター、条件付きルールなど）。
• node_modules/konsistent/docs/guides/exploring-codebases.md — ルールを記述する前のパターン特定手法。

設定構文に関する推奨事項

• 識別可能な ID を付けるため、conventions には name を使用してください（kebab-case にする必要があります）。
• convention 名だけでは内容が明確でない場合は、description を使用してください。
• ハードコードした名前より、ケース変換を使ったテンプレートを優先してください。これが konsistent の大きな強みです。
• 同じパスに適用される関連述語は、1 つの convention にまとめてください。
• 同じパスに異なる重大度が必要な場合は、別々の convention を使用してください。
• 既知の例外を除外するにはパスの否定を使用できます。ただし、生成ファイル、フィクスチャ、ベンダーコード、または明確に区別されたパッケージカテゴリなど、convention の対象コホートの範囲外である意味的カテゴリに限ります。

設定構文での注意点

• 宣言名やエクスポート名に * を使用しないでください。これらのワイルドカードはパスセグメントでのみ使用できます。

完了報告

設定を引き継ぐ際は、次の内容を報告してください。

• 推定したすべての convention と、そのエビデンス比率（例：12 件中 10 件）。
• パターンに準拠している代表的な例。
• 監査で見つかった代表的な違反、または違反がなかったことを明示する記述。
• 意図的に採用を見送った、曖昧な候補パターン。
• 各除外項目と、それが対象コホートの範囲外である意味的な理由。

成功を「konsistent がパスする」と表現しないでください。スキーマ検証の成功と、コードベース監査の結果を区別してください。