Merge remote-tracking branch 'origin/main' into fix-issue4608

# Conflicts:
#	TESTING_GUIDE.md
#	src/CodeIndex/Indexer/Scanning/FileIndexer.Types.cs

Author: Widthdom

DEVELOPER_GUIDE.md

@@ -1491,6 +1491,8 @@ Process exit codes are coarse (`0` success including valid zero-row queries, `1`
 
 ## Design decisions
 
+- **Language capability patterns remain typed at the integration boundary** — CLI/MCP `languages` rows expose suffix-only `extensions`, literal `exact_filenames`, and `<suffix>`-rendered `filename_prefix_patterns`. `legacy_patterns` preserves the former combined list during deprecation, and `pattern_provenance` identifies built-in, plugin/pattern, and language-map override ownership. Round-trip tests feed every advertised typed pattern back through `FileIndexer.DetectLanguage` (#4617).
+- **Ambiguous source extensions stay explicit** — `.m` and `.pl` are not assigned to Objective-C and Perl by default. `FileIndexer` checks an authoritative recognized shebang, then a 64 KiB bounded prefix for strong mutually exclusive Objective-C/MATLAB or Perl/Prolog markers, then at most 256 entries per ancestor directory for conservative project markers. Conflicting or weak evidence is indexed as `ambiguous_m` / `ambiguous_pl`; MATLAB and Prolog have conservative symbol patterns but deliberately advertise no reference/graph support (#4612).
 - **Lock-file dependency graphs model package relationships** — `packages.lock.json`, `package-lock.json`, and `npm-shrinkwrap.json` keep package declarations as symbols, but emit `dependency` references only for explicit parent-package to child-package entries. The parent package is stored as the reference container, so `callers` can identify which package requires a child and `deps` does not infer lock-file-to-lock-file similarity merely because two files contain the same resolved package set (#4409).
 - **No ORM** — Raw `Microsoft.Data.Sqlite` with parameterized queries. Keeps dependencies minimal and control explicit.
 - **Batch commits** — 500 records per transaction for write performance. Reduces fsync overhead.
@@ -2714,7 +2716,12 @@ Downstream users can add lightweight language support without rebuilding
 
 - extension aliases are read from `~/.config/cdidx/langmap.yaml` and the first
   workspace ancestor `.cdidx-langmap.yaml`; workspace entries override user
-  entries;
+  entries. A trusted suffix override is evaluated before built-in exact-filename,
+  filename-prefix, and extension rules. If the closest workspace map cannot be
+  probed or read, ancestor workspace lookup stops for that subtree instead of
+  reusing a parent map; `languages --json` and the MCP `languages` tool expose
+  the sanitized failure in `language_map_diagnostics` and publish the effective
+  order in `detection_policy.precedence`;
 - regex-backed symbol patterns are read from `.cdidx/patterns/*.yaml` and
   `~/.config/cdidx/patterns/*.yaml`; sidecars must be regular files under
   non-symlink pattern directories, discovery accepts at most 128 candidates per
@@ -4348,6 +4355,8 @@ USER_GUIDEの[終了コード](USER_GUIDE.md#終了コード)セクションを
 
 ## 設計判断
 
+- **integration boundary では language capability pattern の型を維持** — CLI/MCP の `languages` 行は suffix のみの `extensions`、literal な `exact_filenames`、`<suffix>` 表記の `filename_prefix_patterns` を公開します。`legacy_patterns` は deprecation 中に従来の combined list を保持し、`pattern_provenance` は built-in、plugin/pattern、language-map override の所有元を示します。round-trip test は広告した全 typed pattern を `FileIndexer.DetectLanguage` に戻して検証します（#4617）。
+- **曖昧な source extension は曖昧なまま明示** — `.m` と `.pl` を既定で Objective-C / Perl に割り当てません。`FileIndexer` は authoritative な認識済み shebang、64 KiB 上限 prefix 内の相互排他的で強い Objective-C/MATLAB または Perl/Prolog marker、各 ancestor directory 最大 256 entry の保守的な project marker の順に確認します。競合または弱い証拠は `ambiguous_m` / `ambiguous_pl` として index し、MATLAB / Prolog は保守的な symbol pattern を持つ一方、reference / graph 対応を意図的に広告しません（#4612）。
 - **lock file の依存グラフは package 間の関係をモデル化** — `packages.lock.json`、`package-lock.json`、`npm-shrinkwrap.json` は package 宣言を symbol として保持しますが、`dependency` reference は明示された親 package → 子 package の項目だけに出力します。親 package を reference container に保存するため、`callers` はどの package が子 package を必要としているかを特定でき、`deps` は同じ resolved package 集合を持つだけの lock file 同士を類似関係として推論しません（#4409）。
 - **ORMなし** — `Microsoft.Data.Sqlite`でパラメータ化クエリを直接使用。依存関係を最小限に、制御を明確に。
 - **バッチコミット** — 書き込み性能のため1トランザクション500レコード。fsyncオーバーヘッドを削減。
@@ -4995,6 +5004,11 @@ cleared range を証明するテストが必要です。Bounded accumulation pat
 
 - 拡張子 alias は `~/.config/cdidx/langmap.yaml` と、最初に見つかった workspace
   祖先の `.cdidx-langmap.yaml` から読み込まれ、workspace 側が user 側を上書きします。
+  信頼済み suffix override は built-in の完全一致 filename、filename-prefix、extension rule
+  より先に評価されます。最も近い workspace map を probe または read できない場合、その subtree
+  では親 map を再利用せず ancestor workspace 探索を停止します。`languages --json` と MCP の
+  `languages` tool は sanitization 済み失敗を `language_map_diagnostics` に公開し、実効順序を
+  `detection_policy.precedence` で示します。
 - regex ベースのシンボルパターンは `.cdidx/patterns/*.yaml` と
   `~/.config/cdidx/patterns/*.yaml` から読み込まれます。sidecar は symlink ではない
   pattern directory 配下の通常ファイルのみが対象で、探索候補は pattern directory ごとに

TESTING_GUIDE.md

@@ -118,9 +118,9 @@ Use `docs/test-doc-maintenance-plan.md` before moving oversized suites or adding
   TypeScript inline-class coverage uses one multi-method declaration for single-member recognition, sibling splitting, exact signatures, and shared class-container metadata.
   TypeScript same-line sibling-class coverage keeps distinct and identical method-name cases in one source, using four class containers to preserve attribution diagnostics.
 - `FileIndexerTests.cs`, `FileIndexerContentLoadingTests.cs`, `FileIndexerTestSupport.cs`
-  File scanning, language detection, scan-result language reuse, content-sensitive header safeguards, content loading/canonicalization, checksum, Git LFS pointer detection, and record-building behavior, including extensionless shebang detection's 256-byte first-line cap, binary/NUL-byte rejection, and Windows-only >=260-character path walker/purge coverage. Keep `.h` lexical-detection coverage consolidated across comment-only markers, spliced strings/comments and delimiters, long macro/raw-string/block-comment state, UTF-8 byte-budget sampling, partial-token sample boundaries, long physical lines, genuine mixed C/C++ code, and source/confidence metadata. Shared `FileIndexerTests` helpers live in `FileIndexerTestSupport.cs`.
+  File scanning, language detection, scan-result language reuse, content-sensitive header safeguards, content loading/canonicalization, checksum, Git LFS pointer detection, and record-building behavior, including authoritative language-map suffix overrides across exact/prefix/extension rules, fail-visible child-map probe/read diagnostics that block parent inheritance, typed `languages` pattern schemas with provenance and detection round trips, extensionless/unknown/ambiguous-extension shebang detection's override precedence, `detection_source`, 256-byte first-line cap, binary/NUL-byte rejection, conservative `.m` / `.pl` content/project classification with explicit ambiguity buckets, and Windows-only >=260-character path walker/purge coverage. Keep `.h` lexical-detection coverage consolidated across comment-only markers, spliced strings/comments and delimiters, long macro/raw-string/block-comment state, UTF-8 byte-budget sampling, partial-token sample boundaries, long physical lines, genuine mixed C/C++ code, and source/confidence metadata. Shared `FileIndexerTests` helpers live in `FileIndexerTestSupport.cs`.
 - `PathCompatibilityMatrixTests.cs`
-  Cross-platform path compatibility matrix coverage for path casing, boundary-prefix comparisons, Windows long-path prefixing, POSIX sensitive-file permissions, symlink/dangling-entry scan behavior, submodule passthrough under default skip directories, and git skip-worktree path normalization. Keep new platform/path fixture scenarios here when the same assumption needs to be visible across indexing, Git helper, DB/query, installer, or status surfaces.
+  Cross-platform path compatibility matrix coverage for path casing, boundary-prefix comparisons, private-child case probes (including numeric root basenames), filesystem-aware exact/prefix filename language detection, Windows long-path prefixing, POSIX sensitive-file permissions, symlink/dangling-entry scan behavior, submodule passthrough under default skip directories, and git skip-worktree path normalization. Keep new platform/path fixture scenarios here when the same assumption needs to be visible across indexing, Git helper, DB/query, installer, or status surfaces.
 - `DatabaseTests.cs`, `DatabasePermissionPolicyTests.cs`, `DbReader*Tests.cs`
   SQLite schema, write paths, migrations, and query behavior. DbReader coverage is split by query family, including search, SQL qualified-name handling, file dependencies, impact, and symbol-query suites, while shared seeded fixture state remains on the root `DbReaderTests` part.
   Graph-kind regressions keep default canonical `call` / `instantiate` / `subscribe` output, raw-kind output, and explicit non-default kind access in the same seeded fixture so filtering and projection cannot drift apart.
@@ -818,9 +818,9 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   TypeScript inline-class coverage は、single-member recognition、sibling 分割、正確な signature、共通 class-container metadata を1つの multi-method declaration で検証します。
   TypeScript same-line sibling-class coverage は、distinct/identical method-name case を1 source にまとめ、4つの class container で attribution の診断性を維持します。
 - `FileIndexerTests.cs`、`FileIndexerContentLoadingTests.cs`、`FileIndexerTestSupport.cs`
-  ファイル走査、言語判定、scan result 言語の再利用、content loading / canonicalization、checksum、レコード構築のテスト。拡張子なし shebang 判定の「先頭物理行 256 byte 上限」、binary/NUL byte 除外、Windows 専用の 260 文字以上 path walker/purge カバレッジも含みます。`.h` の字句判定カバレッジは、コメントだけのマーカー、splice された文字列・コメント・delimiter、長いマクロ・raw string・block comment の状態、UTF-8 byte budget sampling、token 途中の sample 境界、長い物理行、実際の C/C++ 混在コード、判定元・信頼度 metadata を一まとまりで検証します。共有 `FileIndexerTests` helper は `FileIndexerTestSupport.cs` に置きます。
+  ファイル走査、言語判定、scan result 言語の再利用、content loading / canonicalization、checksum、レコード構築のテスト。完全一致/prefix/extension rule を横断する authoritative な language-map suffix override、親継承を遮断して失敗を可視化する child map の probe/read diagnostic、provenance と detection round trip を持つ typed `languages` pattern schema、拡張子なし/未知拡張子/曖昧拡張子の shebang 判定における override precedence、`detection_source`、「先頭物理行 256 byte 上限」、binary/NUL byte 除外、明示 ambiguity bucket を持つ保守的な `.m` / `.pl` content/project 分類、Windows 専用の 260 文字以上 path walker/purge カバレッジも含みます。`.h` の字句判定カバレッジは、コメントだけのマーカー、splice された文字列・コメント・delimiter、長いマクロ・raw string・block comment の状態、UTF-8 byte budget sampling、token 途中の sample 境界、長い物理行、実際の C/C++ 混在コード、判定元・信頼度 metadata を一まとまりで検証します。共有 `FileIndexerTests` helper は `FileIndexerTestSupport.cs` に置きます。
 - `PathCompatibilityMatrixTests.cs`
-  path casing、boundary-prefix 比較、Windows long-path prefix、POSIX の sensitive file 権限、symlink / dangling entry の scan 挙動、既定 skip directory 配下の submodule passthrough、git skip-worktree path 正規化を横断する compatibility matrix カバレッジです。同じ platform/path 前提を indexing、Git helper、DB/query、installer、status の各 surface で見える形にしたい場合は、新しい fixture シナリオをここに追加してください。
+  path casing、boundary-prefix 比較、数字だけの root basename を含む private-child case probe、filesystem-aware な完全一致/prefix ファイル名言語判定、Windows long-path prefix、POSIX の sensitive file 権限、symlink / dangling entry の scan 挙動、既定 skip directory 配下の submodule passthrough、git skip-worktree path 正規化を横断する compatibility matrix カバレッジです。同じ platform/path 前提を indexing、Git helper、DB/query、installer、status の各 surface で見える形にしたい場合は、新しい fixture シナリオをここに追加してください。
 - `DatabaseTests.cs`、`DatabasePermissionPolicyTests.cs`、`DbReader*Tests.cs`
   SQLite スキーマ、書き込み経路、マイグレーション、クエリ挙動のテスト。DbReader のカバレッジは search、SQL qualified name、file dependency、impact、symbol query などの query family ごとの partial suite に分割し、共有の seed 済み fixture 状態は root 側の `DbReaderTests` に残します。
   graph kind の回帰では、既定 canonical `call` / `instantiate` / `subscribe` 出力、raw-kind 出力、明示的な非既定 kind access を同じ seed 済み fixture にまとめ、filtering と projection のずれを検出します。