Fix Markdown dependency noise evidence

DEVELOPER_GUIDE.md

@@ -1978,7 +1978,21 @@ Different graph entry points walk different `reference_kind` subsets by design.
 | `deps` (default = forward) | source file → target file | all kinds; metadata rows require class-like + metadata-eligible targets (`has_metadata_target_kind`) and a unique resolution (`target_ambiguity`); MSBuild imports/project references resolve paths relative to the declaring project instead of matching shared package names | `DbReader.GetFileDependencies` |
 | `deps --reverse` | target file → source file | same as forward `deps` (same SQL) | `DbReader.GetFileDependencies` |
 
-`deps --symbol`, `--symbol-family`, and `--suppress-noise` are pushed into the logical-reference and target-candidate SQL scopes before candidate ranking and `--limit`; cycle and cross-workspace reads apply the same filters before their candidate limits. Consequently, `reference_count`, ranking, and the `symbol_filter` before/after counters describe the SQL-filtered scope rather than the whole pre-filter workspace. Long SQLite dependency reads also register command cancellation with the query token.
+`deps --symbol`, `--symbol-family`, and the generic-symbol part of
+`--suppress-noise` are pushed into the logical-reference and target-candidate
+SQL scopes before candidate ranking and `--limit`; cycle and cross-workspace
+reads apply the same name filters before their candidate limits. Markdown
+heading-name matches are classified separately as
+`markdown_heading_name_match` evidence. Suppressed queries prioritize retained
+evidence before candidate limits, then remove only that evidence in the CLI
+layer, so explicit Markdown path links remain visible even when an edge also
+contains legacy heading fanout. Machine-readable edges expose
+`source_language`, `origin`, `reference_kind`, `target_kind`, and
+`reference_count` distributions in `evidence`; `symbol_filter` adds reference
+before/after totals and per-reason affected/removed counts. Generic-symbol
+counters still describe the SQL-filtered scope rather than the whole pre-filter
+workspace. Long SQLite dependency reads also register command cancellation with
+the query token.
 
 Practical consequence: `impact <ClassName>` on a class-like symbol returns the heuristic file-dependency-hint fallback (with metadata edges) when no member-level callers exist, whereas default `callers <ClassName>` returns only executable edges. Both are correct under their own contracts; counts will not match. To reconcile, run `references <ClassName> --kind attribute` (or `annotation`), or pass an explicitly supported non-default kind to `callers` / `callees`, to surface edges that the default call graph intentionally drops.
 
@@ -5256,7 +5270,18 @@ USER_GUIDEの[終了コード](USER_GUIDE.md#終了コード)セクションを
 | `deps` (デフォルト = forward) | source file → target file | 全 kind。metadata 行は class-like かつ metadata-eligible な target (`has_metadata_target_kind`) と一意解決 (`target_ambiguity`) を要求。MSBuild の import / project reference は共有 package 名との一致ではなく、宣言元 project 相対の path として解決 | `DbReader.GetFileDependencies` |
 | `deps --reverse` | target file → source file | forward `deps` と同じ SQL を共有 | `DbReader.GetFileDependencies` |
 
-`deps --symbol`、`--symbol-family`、`--suppress-noise` は、候補の ranking と `--limit` より前に logical-reference と target-candidate の SQL scope へ push down される。cycle と cross-workspace の read も、各候補上限より前に同じ filter を適用する。そのため `reference_count`、ranking、`symbol_filter` の before/after counter は、絞り込み前の workspace 全体ではなく SQL で絞り込まれた scope を表す。長時間の SQLite dependency read では query token による command cancellation も登録する。
+`deps --symbol`、`--symbol-family`、`--suppress-noise` の汎用 symbol 部分は、候補の
+ranking と `--limit` より前に logical-reference と target-candidate の SQL scope へ
+push down される。cycle と cross-workspace の read も、各候補上限より前に同じ名前
+filter を適用する。Markdown の見出し名一致は
+`markdown_heading_name_match` evidence として別に分類する。抑制時は候補上限より前に
+保持対象 evidence を優先し、CLI 層でこの evidence だけを除くため、旧 index 由来の
+見出し fanout と同じ edge に含まれる明示的な Markdown path link も残る。
+machine-readable edge の `evidence` は `source_language`、`origin`、`reference_kind`、
+`target_kind`、`reference_count` の分布を公開し、`symbol_filter` は reference の
+before/after 合計と理由別の affected / removed 件数を加える。汎用 symbol の counter は
+引き続き、絞り込み前の workspace 全体ではなく SQL で絞り込まれた scope を表す。
+長時間の SQLite dependency read では query token による command cancellation も登録する。
 
 実運用上の帰結: クラスのようなシンボルに対する `impact <ClassName>` は、member-level の caller が存在しない場合 heuristic file-dependency-hint fallback (metadata エッジを含む) を返し、一方の既定 `callers <ClassName>` は実行可能 edge だけを返す。両方とも個々の契約上は正しいが、件数は一致しない。差分を埋めるには `references <ClassName> --kind attribute`（または `annotation`）を使うか、`callers` / `callees` に明示的に対応する非既定 kind を渡し、既定 call graph が意図的に落としている edge を確認する。
 

README.md

@@ -159,6 +159,12 @@ For generated or dense source that emits excessive reference rows, use
 `cdidx . --max-references-per-file <n>` to keep text search and symbols indexed
 while skipping references for only the over-limit file.
 
+For file-dependency audits, `cdidx deps --suppress-noise` removes generic
+framework symbols and legacy Markdown heading-name fanout without hiding
+explicit Markdown links. JSON edges expose the origin, reference kind, target
+kind, and count in `evidence`; `symbol_filter` reports before/after counts and
+the `markdown_heading_name_match` suppression reason.
+
 If one file throws during indexing, cdidx commits successful files and their graph
 edges, reports structured `file_errors`, and exits with partial-result code `11`.
 Use `--allow-partial` only when automation deliberately accepts exit `0` for that
@@ -583,6 +589,11 @@ structured identity key を保持します。
 `cdidx . --max-references-per-file <n>` を使うと、text search と symbols は保持しつつ
 上限を超えたファイルだけ references をスキップできます。
 
+ファイル依存関係の監査では、`cdidx deps --suppress-noise` が明示的な Markdown link を
+隠さずに、汎用 framework symbol と旧 index 由来の Markdown 見出し名 fanout を除外します。
+JSON edge の `evidence` は origin、reference kind、target kind、件数を公開し、
+`symbol_filter` は before/after 件数と `markdown_heading_name_match` の抑制理由を返します。
+
 index 中に 1 ファイルで例外が発生した場合、cdidx は成功ファイルとその graph edge を
 commit し、構造化 `file_errors` を返して partial-result 終了コード `11` で終了します。
 不完全 generation の終了コード `0` を automation が意図的に許容するときだけ

USER_GUIDE.md

@@ -2070,7 +2070,7 @@ same source location.
 | `--since <datetime>` | `search`, `definition`, `symbols`, `files` | Filter to files modified since this ISO 8601 timestamp. Offsetless values (e.g. `2024-01-01T00:00:00`) are treated as UTC so the same flag resolves to the same instant in every timezone; append `Z` or an explicit offset (`+09:00`) to be explicit. |
 | `--no-dedup` | `search` | Disable overlapping-chunk deduplication and return every raw chunk hit; useful for debugging chunk boundaries or measuring raw match density |
 | `--reverse` | `deps` | Reverse lookup: show files that depend ON the matched path |
-| `--symbol <name>` / `--symbol-family <prefix>` / `--suppress-noise` | `deps` | Restrict dependency edges by an exact symbol, a symbol-name prefix, or the built-in noise profile. These filters run in SQLite before candidate ranking and `--limit`, including cycle and cross-workspace queries. `reference_count`, ranking, and JSON `symbol_filter` counters therefore describe the filtered scope. |
+| `--symbol <name>` / `--symbol-family <prefix>` / `--suppress-noise` | `deps` | Restrict dependency edges by an exact symbol, a symbol-name prefix, or the built-in noise profile. Exact/prefix filters and generic-symbol suppression run in SQLite before candidate ranking and `--limit`, including cycle and cross-workspace queries. `--suppress-noise` also classifies legacy Markdown heading-name matches as evidence, prioritizes retained evidence before candidate limits, and removes only that evidence so explicit Markdown links remain visible. JSON edges expose the `source_language` / `origin` / `reference_kind` / `target_kind` / `reference_count` distribution in `evidence`; `symbol_filter` reports reference before/after totals and per-reason affected/removed counts. |
 | `--cycles` / `--graph-budget <n>` / `--cursor <value>` | `deps` | Compute deterministic, stably ranked dependency SCCs. `--graph-budget` independently bounds analyzed edges (default `10000`), while `--limit` pages the ranked SCCs and an opaque `next_cursor` continues the same filtered graph. JSON reports `analysis_complete`, `graph_edge_count`, `graph_edge_budget`, ranking metadata, authoritative-total status, and continuation metadata. When the graph budget is exhausted, the SCC set and total are explicitly non-authoritative; increase `--graph-budget` or narrow the graph with `--suppress-noise`, `--symbol`, `--symbol-family`, or `--path`. |
 | `--strict-not-found` | Query commands | Return exit code `2` when a valid query produces zero rows. Without this flag, zero-result queries normally exit `0` and keep their normal empty/zero-result output; the default-format `definition --json` miss is an intentional exception that always emits `E018_QUERY_NOT_FOUND` and exits `2`. |
 | `--top <n>` | Query commands | Alias for `--limit` |
@@ -5262,7 +5262,7 @@ raw match density を正確に測る、といった理由で全 raw chunk hit 
 | `--since <datetime>` | `search`, `definition`, `symbols`, `files` | 指定タイムスタンプ以降に変更されたファイルのみ（ISO 8601）。オフセットなしの値（例: `2024-01-01T00:00:00`）は UTC として解釈されるため、どのタイムゾーンから呼び出しても同じ UTC 時点になります。明示したい場合は末尾に `Z` または `+09:00` 等のオフセットを付与してください。 |
 | `--no-dedup` | `search` | overlap chunk の重複排除を無効化し、全 raw chunk hit を返す。chunk 境界の debug や raw match density 計測向け |
 | `--reverse` | `deps` | 逆引き: 指定パスに依存しているファイルを表示 |
-| `--symbol <name>` / `--symbol-family <prefix>` / `--suppress-noise` | `deps` | 完全一致のシンボル、シンボル名の接頭辞、または組み込み noise profile で依存 edge を絞り込む。cycle と cross-workspace query を含め、これらの filter は候補の ranking と `--limit` より前に SQLite 内で適用される。そのため `reference_count`、ranking、JSON の `symbol_filter` counter は絞り込み後の scope を表す。 |
+| `--symbol <name>` / `--symbol-family <prefix>` / `--suppress-noise` | `deps` | 完全一致のシンボル、シンボル名の接頭辞、または組み込み noise profile で依存 edge を絞り込む。完全一致 / 接頭辞 filter と汎用 symbol 抑制は、cycle と cross-workspace query を含め、候補の ranking と `--limit` より前に SQLite 内で適用される。`--suppress-noise` は旧 index 由来の Markdown 見出し名一致も evidence として分類し、候補上限より前に保持対象 evidence を優先したうえで、その evidence だけを除くため明示的な Markdown link は残る。JSON edge の `evidence` は `source_language` / `origin` / `reference_kind` / `target_kind` / `reference_count` の分布を公開し、`symbol_filter` は reference の before/after 合計と理由別の affected / removed 件数を返す。 |
 | `--cycles` / `--graph-budget <n>` / `--cursor <value>` | `deps` | 決定的かつ安定順位付きの依存 SCC を計算する。`--graph-budget` は解析する edge 数を独立して制限し（既定値 `10000`）、`--limit` は順位付け済み SCC をページ分割し、不透明な `next_cursor` で同じ filter 済み graph の続きを取得する。JSON は `analysis_complete`、`graph_edge_count`、`graph_edge_budget`、ranking metadata、総件数が authoritative かどうか、continuation metadata を返す。graph budget 枯渇時は SCC 集合と総件数が non-authoritative であることを明示するため、`--graph-budget` を増やすか、`--suppress-noise`、`--symbol`、`--symbol-family`、`--path` で graph を絞り込む。 |
 | `--workspace-db <path>` | `deps` | file dependency query に別の CodeIndex DB を追加する。最大 7 個の distinct な追加 DB（`--db` を含め合計 8 個）まで繰り返し指定でき、JSON edge には同じ相対パスを区別できるよう `source_db` / `target_db` が含まれる。 |
 | `--strict-not-found` | クエリ系 | 有効な query の結果が 0 件なら終了コード `2` を返す。この flag がない場合、0 件の query は通常、既存の empty / zero-result output を維持して終了コード `0` を返す。ただし既定 format の `definition --json` 未検出は意図的な例外で、常に `E018_QUERY_NOT_FOUND` と終了コード `2` を返す。 |

changelog.d/unreleased/4868.fixed.md

@@ -0,0 +1,25 @@
+---
+category: fixed
+issues:
+  - 4868
+affected:
+  - src/CodeIndex/Models/DependencyNoiseProfile.cs
+  - src/CodeIndex/Models/QueryResults.cs
+  - src/CodeIndex/Database/DbReader.Dependencies.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.Dependencies.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs
+  - tests/CodeIndex.Tests/QueryCommandRunnerTests.cs
+  - README.md
+  - USER_GUIDE.md
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Dependency noise suppression now recognizes legacy Markdown heading fanout (#4868)** — `deps --suppress-noise` classifies heading-name matches separately from explicit Markdown path links, prioritizes retained evidence before dependency and cycle candidate limits, and removes only the heading-derived reference counts. JSON and JSON-graph edges expose origin, reference-kind, target-kind, and count distributions through `evidence`, while `symbol_filter` reports reference-count deltas and per-reason affected/removed totals.
+
+## 日本語
+
+- **依存ノイズ抑制が旧 Markdown 見出し fanout を識別するようになりました (#4868)** — `deps --suppress-noise` は見出し名一致を明示的な Markdown path link と分けて分類し、依存辺と cycle の候補上限より前に保持対象 evidence を優先したうえで、見出し由来の reference 件数だけを除外します。JSON / JSON-graph edge は `evidence` で origin、reference kind、target kind、件数の分布を公開し、`symbol_filter` は reference 件数の差分と理由別の affected / removed 合計を返します。

src/CodeIndex/Cli/CliFlagSchema.cs

@@ -311,7 +311,7 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--summary-only", Description = "Map/Diff/Recipes/Audit/Files/Symbols/Deps/Hotspots/Languages: return only aggregate summary fields where supported", PrimaryCommands = Set(SummaryOnlyCommands) },
             new() { Name = "--cycles", Description = "Deps: return deterministically ranked dependency SCCs with stable pagination", PrimaryCommands = Set(DependencyCycleCommands) },
             new() { Name = "--graph-budget", ValuePlaceholder = "<n>", Description = $"Deps cycles: maximum graph edges analyzed for SCC completeness (default: {QueryCommandRunner.DefaultDependencyCycleGraphBudget})", PrimaryCommands = Set(DependencyCycleCommands) },
-            new() { Name = "--suppress-noise", Description = "Deps: suppress generic framework/noise symbols in edge symbol samples", PrimaryCommands = Set("deps") },
+            new() { Name = "--suppress-noise", Description = "Deps: suppress generic framework symbols and legacy Markdown heading-name fanout while preserving explicit links", PrimaryCommands = Set("deps") },
             new() { Name = "--symbol", ValuePlaceholder = "<name>", Description = "Deps: keep only edges with an exact sampled symbol name", PrimaryCommands = Set("deps") },
             new() { Name = "--symbol-family", ValuePlaceholder = "<prefix>", Description = "Deps: keep only edges with a sampled symbol prefix/family", PrimaryCommands = Set("deps") },
             new() { Name = "--indexed-only", Description = "Languages: list only languages present in the current index", PrimaryCommands = Set(LanguagesFilterCommands) },

src/CodeIndex/Cli/JsonOutputContracts.cs

@@ -1109,6 +1109,7 @@ internal sealed record ValidateConfigJsonResult(
 [JsonSerializable(typeof(ExcerptContentLineSpan))]
 [JsonSerializable(typeof(ExcerptRecoveryHint))]
 [JsonSerializable(typeof(ExcerptSemanticToken))]
+[JsonSerializable(typeof(FileDependencyEvidence))]
 [JsonSerializable(typeof(FileDependencyResult))]
 [JsonSerializable(typeof(FileExcerptResult))]
 [JsonSerializable(typeof(FileFindResult))]
@@ -1158,6 +1159,7 @@ internal sealed record ValidateConfigJsonResult(
 [JsonSerializable(typeof(List<CallerResult>))]
 [JsonSerializable(typeof(List<CliJsonMessage>))]
 [JsonSerializable(typeof(List<DefinitionResult>))]
+[JsonSerializable(typeof(List<FileDependencyEvidence>))]
 [JsonSerializable(typeof(List<FileDependencyResult>))]
 [JsonSerializable(typeof(List<FileFindResult>))]
 [JsonSerializable(typeof(List<FileIssue>))]