db-naming

db-naming (M7)

命名はスキーマのドキュメントです。一貫性があり予測しやすい識別子を使えば、結合が分かりやすくなり、ORM やエンジン間で生じがちな引用符や大文字・小文字のバグを減らせます。重みは低く（命名カテゴリ、設計軸）、実際に重要ではありますが、決して主題にはなりません。このモジュールは設計軸であり、スコアの上限には影響しません。

チェック内容

• 大文字・小文字／複数形の一貫性：1 つのスキーマ内で snake_case と camelCase が混在していたり、単数形と複数形のテーブル名（user、orders、OrderItem）が混在していたりする場合は、どちらかに統一してください。
• 予約語と大文字・小文字の折りたたみに関する落とし穴：SQL の予約語（user、order、group、select）である識別子や、大文字・小文字に依存する識別子（引用符で囲まれた "User"）が該当します。Postgres では引用符で囲まれていない名前は小文字に変換され、MySQL ではファイルシステムや大文字・小文字の設定によって挙動が変わります。引用符の付け方が混在すると、「relation does not exist」エラーの原因になります。
• FK の命名：FK 列が予測可能な <referenced>_id のパターンに従っていないため、結合先が一目で分かりません。
• ブール値の命名：ブール値の名前に is_／has_／can_ の接頭辞がない場合や、ロジックを反転させる否定形の名前（not_active）が使われている場合が該当します。
• 不透明／曖昧な名前：data、info、value、flag、temp、col1、用語集にない略語、または _at で終わらないタイムスタンプ名が該当します。

軸と重大度

• 軸：設計。重大度はほぼ常に低で、実態に即したバンドを設定します。
• エンジン間で問題を引き起こす、引用符で囲まれていない予約語識別子：重大度 2～3、warn。
• スキーマ全体にわたる大文字・小文字／複数形の不統一：重大度 2、warn、fixable: proposed（名前変更は影響範囲が広いため、auto は決して指定しません）。
• 不透明な列名／_at 接尾辞の欠落：重大度 1、warn。
• M7 がスコアの上限に影響することはありません。設計カテゴリの中で最も重みが小さいカテゴリです。

Tier-0 静的チェック

scripts/parse-schema.mjs で DDL／スナップショットを解析します。識別子の大文字・小文字のスタイルとテーブルの複数形を集計し、エンジンごとの予約語リストと識別子を照合し、FK 列が <table>_id のパターンに従っているかを確認し、is_／has_／can_ が付いていないブール値列や不透明な名前を検出します。これは完全に静的なチェックで、判定はdirectionalです。

Tier-1 検証クエリ

実環境の識別子一覧と引用符の使用を確認します。

-- $DATABASE_URL, read-only
SELECT table_name, column_name FROM information_schema.columns
WHERE table_schema NOT IN ('pg_catalog','information_schema')
ORDER BY table_name;   -- inspect casing/plurality/reserved words across the real catalog

検出結果

schema/finding.schema.json に従って出力します。例：

• M7.schema.mixed_casing — スキーマ内で snake_case と camelCase の識別子が混在しています（重大度 2、warn、軸 design、fixable: proposed）。
• M7.user.reserved_word_table — user というテーブル名には引用符が必要で、引用符で囲まれていない参照で問題が発生します（重大度 2、warn、軸 design）。
• M7.accounts.active_boolean_unprefixed — ブール値 active の名前に is_active が使われていません（重大度 1、warn）。 各検出結果では、evidence.observed に識別子をそのまま引用します。verification.reproduce には上記の実行可能なクエリを指定します（method: ddl_parse／schema_introspect）。expected_impact はバンド（通常は low）とし、根拠を添えて信頼度を directional にします。

注意事項

• 命名に関する検出結果は、推奨レベルの改善にすぎません。レポートで過度に強調したり、機能上の欠陥を示唆したりしないでください。
• 名前の変更は破壊的で、アプリケーションコードやマイグレーションに影響します。推奨は proposed／advisory とし、決して auto にしないでください。
• 予約語と大文字・小文字の折りたたみの挙動はエンジン固有です。普遍的なルールとして断定せず、検出されたエンジンに範囲を限定して各検出結果を記述してください。