fix(mcp): weight hotspots by file churn

[devin-ai-integration]

Summary

• tracedecay_hotspots now ranks by score = total * (churn + 1). churn is the 90-day commit count for the symbol's file, read from the existing file_churn miner that test_risk already uses. Ties fall back to total, then to id.
• Each HotspotV1 row now includes churn and score, so callers can see both factors.

Fixes #3011

Motivation

The module doc said "churn-weighted complexity ranking", but the sort used only incoming plus outgoing edge counts and never read git history. A heavily connected symbol that never changes outranked a moderately connected one that changes every week. The second case is the usual meaning of a hotspot.

Changes

• crates/tracedecay-mcp/src/handlers/analysis/hotspots.rs: build the rows with churn/score, then sort and truncate them. file_churn errors propagate the same way they do in test_risk; a project that is not a repo, or has no commits yet, gets churn = 0, so score equals total there.
• HotspotV1 contract: added churn and score. Regenerated sdks/typescript/src/operations.ts with sdks/codegen.
• Rewrote the catalog and tool descriptions, the module doc and docs/USER-GUIDE.md to describe the churn-weighted ranking.

Test plan

• New mcp_handler_test::graph_analysis_test::hotspots_weights_connectivity_by_file_churn: stable.ts (committed once) holds hub with 3 edges, and churned.ts (committed 3 times) holds mid with 2 edges. Through production MCP tools/call, mid (churn 3, score 8) ranks above hub (churn 1, score 6).
  • It fails on master with the product changes stashed: hub is ranked first and the rows have no churn/score fields.
  • It passes with this branch: bash scripts/require-exact-test.sh cargo test -p tracedecay --features test-transport --test mcp_suite mcp_handler_test::graph_analysis_test::hotspots_weights_connectivity_by_file_churn -- --exact (1 passed).
• Updated hotspots_ranks_symbols_by_edge_degree_and_clamps_limit to the new literal churn/score values (single-commit fixtures, so churn is 1) and the new markdown field order. Passes under require-exact-test.sh.
• cargo clippy -p tracedecay-mcp -p tracedecay-contracts -p tracedecay-mcp-catalog --all-targets -- -D warnings and cargo clippy -p tracedecay --features test-transport --test mcp_suite -- -D warnings are clean.
• cargo test -p tracedecay-contracts -p tracedecay-mcp-catalog passes, and so does cargo test in sdks/codegen (codegen parity).
• cargo fmt --all -- --check and node scripts/lint-commit-range.mjs --repository . origin/master HEAD both pass.

Checklist

• CHANGELOG.md updated (under [Unreleased] if no version bump)
• No secrets, credentials, or .env files included
• Breaking changes documented (if any): HotspotV1 gains two required output fields (additive for readers)

Link to Devin session: https://app.devin.ai/sessions/78b7824a1ea149d1986e4c22568e80e1
Open in Devin Desktop: https://app.devin.ai/desktop/session/78b7824a1ea149d1986e4c22568e80e1?variant=devin
Requested by: @ScriptedAlchemy

---

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1f0b113

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR