Explain ambiguous language candidates

DEVELOPER_GUIDE.md

@@ -2009,7 +2009,7 @@ 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`; unresolved `.m` files run the bounded MATLAB and Objective-C symbol/reference paths after a shared position-preserving comment mask, while Prolog and `ambiguous_pl` advertise conservative reference/graph support and the ambiguous `.pl` bucket uses union symbol/reference rules without changing content-based classification (#4612, #4738, #4746).
+- **Ambiguous source extensions stay explicit** — `.m` and `.pl` are not assigned to Objective-C and Perl by default. After language-map overrides and built-in exact/prefix filename rules, `FileIndexer` checks an authoritative recognized shebang whose first physical line is bounded to 256 bytes, 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. A first line that reaches the shebang boundary without a terminator falls through instead of selecting an interpreter. Conflicting or weak evidence is indexed as `ambiguous_m` / `ambiguous_pl`; unresolved `.m` files run the bounded MATLAB and Objective-C symbol/reference paths after a shared position-preserving comment mask, while Prolog and `ambiguous_pl` advertise conservative reference/graph support and the ambiguous `.pl` bucket uses union symbol/reference rules without changing content-based classification. The detector owns the ordered candidate descriptors, filename patterns, exact content patterns, project markers, bounded shebang rules, and reason/confidence vocabulary; CLI/MCP `extension_lookup` diagnostics and dry-run `language_detections` consume that same source so catalog guidance cannot drift from indexing decisions (#4612, #4738, #4746, #4901).
 - **Dynamic reference-graph readiness follows extractor contracts** — when indexed Crystal, Groovy, Tcl, Prolog, or `ambiguous_pl` rows have a missing or stale symbol-extractor version stamp, status reports `dynamic_reference_graph_contract_stale` and keeps `reference_graph_complete` / `graph_data_current` false until a normal index refresh rewrites those rows (#4746).
 - **Hotspot marker fingerprints share one bounded tree traversal** — full/update CLI and MCP indexing compute C#, VB, F#, and MSBuild marker fingerprints together instead of walking the directory tree once per language. Each distinct marker glob retains the platform filesystem's matching behavior and is enumerated once per visited directory, while child directories are enumerated once; marker sets, budgets, truncation sentinels, and warning order remain isolated per language. The single-language API delegates to the same engine, preserving ignore rules, nested-repository/submodule boundaries, and MCP authorized-read failures.
 - **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. NuGet lock symbols and references preserve the current file, target/RID, parent package, and exact JSON property span; candidate resolution stays file-local, while file-level `deps` suppresses cross-file package-name inference. Normal index updates invalidate the prior dependency-lock extraction and reference-identity contracts, so `callers` identifies the requiring package without connecting unrelated lock files or collapsing repeated declarations to the first matching line (#4409, #4845).
@@ -5454,7 +5454,7 @@ 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 し、未確定の `.m` は位置を保つ共通コメントマスクの後で上限付きの MATLAB / Objective-C symbol・reference 経路を実行します。一方、Prolog と `ambiguous_pl` は保守的な reference / graph 対応を広告し、曖昧な `.pl` bucket は content-based classification を変えずに symbol / reference rule の和集合を使います（#4612、#4738、#4746）。
+- **曖昧な source extension は曖昧なまま明示** — `.m` と `.pl` を既定で Objective-C / Perl に割り当てません。language-map override と built-in の完全一致/prefix filename rule の後で、`FileIndexer` は先頭物理行を 256 byte に制限した authoritative な認識済み shebang、64 KiB 上限 prefix 内の相互排他的で強い Objective-C/MATLAB または Perl/Prolog marker、各 ancestor directory 最大 256 entry の保守的な project marker の順に確認します。行終端なしで shebang 境界に達した先頭行は interpreter を選択せず、後続判定へ進みます。競合または弱い証拠は `ambiguous_m` / `ambiguous_pl` として index し、未確定の `.m` は位置を保つ共通コメントマスクの後で上限付きの MATLAB / Objective-C symbol・reference 経路を実行します。一方、Prolog と `ambiguous_pl` は保守的な reference / graph 対応を広告し、曖昧な `.pl` bucket は content-based classification を変えずに symbol / reference rule の和集合を使います。順序付き candidate descriptor、filename pattern、正確な content pattern、project marker、上限付き shebang rule、reason/confidence 語彙は detector 自身が所有し、CLI/MCP の `extension_lookup` diagnostic と dry-run の `language_detections` は同じ source を使うため、catalog guidance と indexing 判定が乖離しません（#4612、#4738、#4746、#4901）。
 - **動的言語の reference-graph readiness は extractor contract に従う** — index 済みの Crystal、Groovy、Tcl、Prolog、`ambiguous_pl` row で symbol-extractor version stamp が欠落または古い場合、status は `dynamic_reference_graph_contract_stale` を報告し、通常の index refresh が対象 row を更新するまで `reference_graph_complete` / `graph_data_current` を false に保ちます（#4746）。
 - **hotspot marker fingerprint は上限付きtree traversalを1回共有** — full/update CLIとMCP indexingは、directory treeを言語ごとに歩かず、C#、VB、F#、MSBuildのmarker fingerprintをまとめて計算します。各directoryでは固有marker globごとにplatform filesystemのmatching挙動を保って1回ずつ列挙し、child directoryも1回だけ列挙する一方、marker集合、budget、truncation sentinel、warning順は言語別に分離します。single-language APIも同じengineへ委譲し、ignore rule、nested repository/submodule境界、MCP authorized read failureを維持します。
 - **lock file の依存グラフは package 間の関係をモデル化** — `packages.lock.json`、`package-lock.json`、`npm-shrinkwrap.json` は package 宣言を symbol として保持しますが、`dependency` reference は明示された親 package → 子 package の項目だけに出力します。NuGet lock の symbol / reference は現在の file、target/RID、親 package、正確な JSON property span を保持し、candidate 解決を file 内に限定します。file 単位の `deps` は package 名による file 間推論を抑止し、通常の index update は以前の dependency-lock 抽出 contract と reference-identity contract を無効化します。そのため、`callers` は無関係な lock file を接続したり、反復宣言を最初の一致行へ畳み込んだりせず、要求元 package を特定できます（#4409、#4845）。

TESTING_GUIDE.md

@@ -157,6 +157,7 @@ Use `docs/test-doc-maintenance-plan.md` before moving oversized suites or adding
   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 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`.
+  Ambiguous-extension diagnostic coverage keeps `.M` case normalization, ordered Objective-C/MATLAB candidates, aliases, exact/prefix filename precedence, the 256-byte unterminated-shebang boundary, shebang/content/project evidence, override examples, empty/binary outcomes, and detector reason/confidence parity together across `FileIndexerTests`, CLI `languages`, MCP `languages`, and index dry-run fixtures (#4901).
   Directory-entry snapshot coverage requires one ordered, scan-local filesystem enumeration for each normally visited root/child directory and shares it between the default case probe and entry processing. Keep custom case-probe invocation counts, the legacy injected `enumerateFiles` path, dangling-entry diagnostics, and single-error enumeration failures explicit when changing traversal.
   Project-marker fingerprint coverage requires the C#/VB/F#/MSBuild batch to share one directory-tree traversal while retaining one enumeration per distinct marker glob and one child-directory enumeration per visited directory. Pin known hashes and single-language delegation, independent budgets/truncation/warning order, ignore/nested-repository/submodule and platform-casing boundaries, traversal failure and cancellation propagation, and MCP fingerprint/authorization parity.
 - `PathCompatibilityMatrixTests.cs`
@@ -1107,6 +1108,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   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、レコード構築のテスト。完全一致/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` に置きます。
+  曖昧拡張子 diagnostic の coverage は、`.M` の大小文字正規化、順序付き Objective-C/MATLAB candidate、alias、完全一致/prefix filename の優先順位、行終端なしで到達する 256 byte shebang 境界、shebang/content/project evidence、override 例、空・binary 入力の結果、detector の reason/confidence parity を `FileIndexerTests`、CLI `languages`、MCP `languages`、index dry-run fixture の間でまとめて維持します（#4901）。
   directory entry snapshot の coverage では、通常scanで訪問するroot/child directoryごとに順序付き・scan-localなfilesystem列挙を1回だけ行い、既定case probeとentry処理で共有することを必須とします。traversal変更時はcustom case probeの呼出回数、旧injected `enumerateFiles`経路、dangling entry診断、列挙失敗が1 errorだけになる契約を明示的に維持してください。
   project marker fingerprint の coverage では、C#/VB/F#/MSBuild batch が1回の directory-tree traversal を共有しつつ、各directoryで固有marker globごとに1回、child directoryは1回だけ列挙することを必須とします。既知hashとsingle-language delegation、言語別budget/truncation/warning順、ignore/nested repository/submoduleとplatform casingの境界、traversal failure/cancellationの伝播、MCP fingerprint/authorization parityを固定してください。
 - `PathCompatibilityMatrixTests.cs`