Audit unused and hotspots result-volume and suppression-boundary behavior

[Widthdom]

Context

Dogfooding the graph-derived analysis commands found large result-volume surfaces around unused and hotspots. These are useful commands, but their count, limit, suppression, and JSON output behavior needs tighter contract coverage for automation.

Representative commands:

dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll unused --count --limit 200
dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll unused --by-bucket --json --limit 200
dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll hotspots --count --limit 200
dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll hotspots --format count --limit 200

Observed baseline:

• unused --count --limit 200 returned 928 and reported 10462 low-confidence contract-domain candidates suppressed by default.
• Suppressed domains included test_contract: 7021, documentation_surface: 1280, cli_contract: 946, public_api_surface: 541, json_contract: 357, mcp_contract: 99, lsp_contract: 17, and others.
• unused --by-bucket --json --limit 200 returned 200 rows plus a very large payload that the caller truncated at roughly 61k tokens. The returned rows included .agent_harness, docs, Dockerfile, Makefile, and README symbols under maybe_unused_nonpublic.
• hotspots --count --limit 200 printed progress and then 11371; progress included phase=write_output limit=200 group_by=symbol rows=11371, so the count/limit relationship is hard to infer.
• hotspots --format count is rejected; the supported shape is --count, unlike search-oriented commands that accept --format count.

Audit questions

• Are unused suppression categories stable enough for machine triage and support docs?
• Should unused --by-bucket --json have --max-json-bytes, compact summary, or top-path-only projections comparable to recipe output?
• Should generated/docs/test/build artifacts be easier to suppress when the user wants production runtime dead-code candidates?
• Should hotspots --count --limit clarify whether the limit affects counted rows, emitted rows, or progress rows?
• Can unused and hotspots share count/format conventions with search where practical?

Acceptance criteria

• Large unused and hotspots runs have bounded, automation-friendly JSON summary modes.
• Limit semantics are documented and tested for count and JSON modes.
• Default suppression metadata is stable, compact, and sufficient to explain omitted candidates.
• Production-only or source-scope triage is possible without manual filtering of docs, tests, and build metadata.

[Widthdom]

Additional dogfood coverage from the 2026-07-07 pass.

Runtime observations:

• unused --json --summary-only --limit 5 is not supported and returned a usage error.
• unused --json --compact --limit 5 worked and reported:
  • 5 returned maybe_unused_nonpublic candidates.
  • 10462 suppressed low-confidence candidates.
  • suppressed domains included public API surface, CLI contract, JSON contract, MCP contract, LSP contract, configuration contract, documentation surface, test contract, framework override, and exception diagnostic.
• hotspots --json --summary-only --limit 5 returned quickly.
• hotspots --json --limit 5 --group-by file returned after roughly 60 seconds.

Follow-up angles:

• Decide whether unused should support --summary-only, since compact output already has strong summary data.
• Review whether hotspot file grouping can short-circuit on --limit or report scan-cost metadata.

[Widthdom]

Additional dogfood coverage from the 2026-07-07 pass.

Unused/hotspot observations:

• unused --count --json succeeded and returned 928 unsuppressed candidates across 165 files.
• The same output reported 10462 suppressed low-confidence candidates.
• unused --json --compact --by-bucket --limit 3 succeeded and returned compact bucket summaries plus representative symbols.
• hotspots --count --json --group-by file took about 26 seconds and reported 568 files; count ignores limit.

Follow-up angles:

• Preserve unused --count as the lightweight summary substitute while unused --summary-only remains unsupported.
• Consider surfacing scan-cost metadata in hotspot count modes.

[Widthdom]

Round8 dogfooding adds one more result-volume case:

• unused --count --json returned a count-oriented result, but still included rich bucket taxonomy and suppression detail.
• unused --by-bucket --json returned useful detail, but the payload is too large for repeated batch triage.
• In the safe batch, unused --count --json reported 928 candidates across 165 files plus 10462 suppressed low-confidence candidates.
• unused --count --json --actionable returned 0, but still carried the full taxonomy shape.

The taxonomy is valuable, but for high-volume dogfood loops there should be a compact count/summary mode that emits only counts, suppression totals, and resume/filter hints unless detail is requested.

[Widthdom]

Work started on branch fix-issue4309-4315-4322-4344-4353.