Make large dependency cycles actionable (#5197)

DEVELOPER_GUIDE.md

@@ -2768,6 +2768,8 @@ Process exit codes are coarse (`0` success including valid zero-row queries, `1`
 - **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).
 - **Dependency-cycle audits separate analysis from display** — CLI `deps --cycles` and MCP `deps` with `cycles=true` analyze a deterministic, path-ordered edge set up to the independent `--graph-budget` / `graphBudget` before computing and stably ranking strongly connected components. `--limit` / `limit` only paginates that ranked SCC set, and opaque cursors are bound to the filters, graph budget, and indexed graph that produced them. Machine-readable responses expose `analysis_complete`, graph edge count/budget, stable ranking mode, authoritative total-cycle status, and continuation metadata; exhausting the graph budget is reported as an explicitly incomplete analysis rather than a complete cycle audit (#4731).
+- **Large dependency SCCs use bounded presentation, not bounded facts** — SCC analysis and ranking always retain authoritative component size, edge/reference totals, the largest-component summary, and evidence breakdowns independently of node presentation. CLI and MCP materialize 50 path-ordered nodes per returned component by default; human, JSON, DOT, GraphML, and JSON graph output project presentation to that sample, expose omitted-node and display-truncation metadata, support compact summaries, and require explicit `--all-cycle-nodes` / `includeAllCycleNodes` opt-in for raw expansion. The MCP cycle schema gives component node arrays a specialized maximum equal to the graph budget ceiling, so an allowed raw expansion remains schema-valid without weakening ordinary row-array bounds. Machine-readable metadata aggregates total, materialized, and omitted nodes for the current returned SCC page separately from the global largest-component summary, so later cursor pages remain authoritative. Retained-evidence summaries aggregate source language, origin, resolution state, reference kind, target kind, and suppression reason. Noise suppression classifies evidence before candidate budgeting and drops only legacy Markdown heading matches plus qualified C# calls classified by a current reference-identity contract as unresolved, ambiguous, or resolved to a target in another file. Stale or absent identity metadata fails closed to retained evidence with `resolution_state=unavailable`; the confirmed target file takes authoritative precedence even when it contains same-name overloads, and resolved partial-family groups retain only files represented by their persisted candidate set. Grouping metadata is file-level and explicitly reports that partial-type-family collapse was not applied (#5197).
+- **Dependency-cycle cursors bind presentation evidence as well as topology** — the graph fingerprint includes each retained evidence row's source language, origin, resolution state, reference kind, target kind, suppression reason, and count in deterministic order. A metadata-only graph refresh therefore rejects an older cursor instead of mixing evidence summaries from different snapshots. MCP `format=json-graph` cycle requests use the same bounded node/edge projection as CLI graph output, and the specialized graph node/edge schema limits match the maximum cycle graph budget (#5197).
 - **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.
 - **Set-based C# instantiation fallback** — The rank-5 unqualified `instantiate` candidate stage materializes C# type members, unique raw-name/arity families, family-scoped constructor members, and per-family explicit-constructor summaries before matching references. Unique families drive indexed constructor lookups instead of scanning every constructor or running correlated type/constructor scalar probes per candidate. Raw type names, identities, and constructor containers remain `BINARY`, family/member arity joins remain NULL-safe, partial types keep their path/start/id representative, and the final lower-rank suppression stays reference-scoped so the optimization preserves overload, implicit-default, value-type, enum, delegate, ambiguity, and unparseable-arity semantics.
@@ -6945,6 +6947,8 @@ USER_GUIDEの[終了コード](USER_GUIDE.md#終了コード)セクションを
 - **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）。
 - **依存サイクル監査では解析と表示を分離** — CLI の `deps --cycles` と MCP `deps` の `cycles=true` は、独立した `--graph-budget` / `graphBudget` まで path 順で決定的な edge 集合を解析してから、強連結成分を安定順位付けします。`--limit` / `limit` はその SCC 順位集合をページ分割するだけで、不透明 cursor は生成時の filter、graph budget、indexed graph に結び付けます。machine-readable 応答は `analysis_complete`、graph edge 件数/予算、安定 ranking mode、authoritative な総 cycle 件数かどうか、continuation metadata を公開し、graph budget 枯渇時は完全な cycle 監査を装わず明示的な未完了解析として報告します（#4731）。
+- **大規模な依存 SCC は事実ではなく表示だけを制限する** — SCC の解析と順位付けは、node 表示とは独立して authoritative な component size、edge / reference 合計、最大 component summary、evidence breakdown を保持します。CLI / MCP は各返却 component について path 順 node を既定で 50 件だけ materialize し、human、JSON、DOT、GraphML、JSON graph の各出力をその sample へ投影して、省略 node 数と表示 truncation metadata を公開し、compact summary を提供します。raw 展開には `--all-cycle-nodes` / `includeAllCycleNodes` の明示 opt-in が必要です。MCP cycle schema は component node array 専用の最大値を graph budget 上限と同じ値にするため、通常の row array 上限を緩めずに許可済み raw 展開を schema-valid に保ちます。machine-readable metadata は current な返却 SCC page の node 合計、materialize 済み件数、省略件数を global な最大 component summary とは別に集計するため、後続 cursor page でも authoritative な件数を維持します。retained-evidence summary は source language、origin、resolution state、reference kind、target kind、suppression reason を集計します。noise 抑制は candidate budget より前に evidence を分類し、旧 Markdown 見出し一致に加え、current な reference-identity contract によって未解決、曖昧、または別 file の target へ解決済みと分類された C# 修飾 call だけを除外します。identity metadata が stale または absent の場合は `resolution_state=unavailable` の retained evidence として fail closed します。同名 overload がある場合も確認済み target の file を authoritative に優先し、解決済みpartial-family groupも保持します。grouping metadata は file 単位で、partial type family の collapse を適用していないことを明示します（#5197）。
+- **依存 cycle cursor は topology に加えて表示 evidence にも束縛する** — graph fingerprint は retained evidence 各行の source language、origin、resolution state、reference kind、target kind、suppression reason、件数を決定的な順序で含めます。そのため metadata だけが更新された graph でも古い cursor を拒否し、異なる snapshot の evidence summary を混在させません。MCP の `format=json-graph` cycle request は CLI graph 出力と同じ上限付き node / edge 投影を使い、専用 graph node / edge schema の上限も cycle graph budget の最大値と一致させます（#5197）。
 - **ORMなし** — `Microsoft.Data.Sqlite`でパラメータ化クエリを直接使用。依存関係を最小限に、制御を明確に。
 - **バッチコミット** — 書き込み性能のため1トランザクション500レコード。fsyncオーバーヘッドを削減。
 - **C# instantiation fallback の集合処理** — rank 5 の無修飾 `instantiate` candidate 段階は、参照との照合前に C# type member、raw name / arity 単位の一意 family、family 内 constructor member、family ごとの明示 constructor summary を materialize します。一意 family から indexed constructor lookup を駆動するため、全 constructor scan や candidate ごとの相関 type / constructor scalar probe を行いません。raw type name・identity・constructor container は `BINARY`、family/member の arity join は NULL-safe のまま維持し、partial type は path/start/id 順の代表を使い、最後の lower-rank suppression も reference 単位に保つため、overload、implicit default、value type、enum、delegate、ambiguity、arity を解析できない場合の意味を変えずに高速化します。