feat(mcp): surface alias keys a documented data-shape omits

[RaghavChamadiya]

What

Follow-up to #779. The documented-shape path answers "what fields does <blob> contain" at high confidence and tells the caller no verification Read is needed. But a docstring lists the declared shape, which can be a subset of what the records actually carry: consumers often read a legacy alias the doc never mentions.

Concrete case in this repo: for co_change_partners_json, four consumers defensively read

partner.get("co_change_count") or partner.get("count")   # count is an alias
partner.get("file_path")       or partner.get("path")    # path is an alias

The docstring at coupling/graph.py:53 lists only file_path, co_change_count, last_co_change. So the old response was confidently incomplete — it said "cite it, no Read needed" while hiding keys an agent editing this code would need to handle.

How

After the documented shape is chosen, scan the identifier's consumer files for the alias idiom:

<recv>.get("<A>") or <recv>.get("<B>")

where one key is a documented field — the other is an alias for it. Requiring the or fallback on a shared receiver keeps this tight and avoids false positives: an assignment that merely co-mentions a documented key on an unrelated record (meta["other_count"] = ...meta["file_path"]) or a test assertion does not match.

The extras come back in a new data_shape.also_accessed block (field + file:line), and the answer names them so the agent handles them. The documented fields stay authoritative and confidence stays high on the declared core; the response just stops hiding the divergence.

Example response for co_change_partners_json:

{
  "confidence": "high",
  "grounding": "data_shape",
  "data_shape": {
    "identifier": "co_change_partners_json",
    "fields": ["file_path", "co_change_count", "last_co_change"],
    "also_accessed": [
      {"field": "path",    "file": ".../pr_blast.py", "line": 187},
      {"field": "count",   "file": ".../pr_blast.py", "line": 188},
      {"field": "partner", "file": ".../routers/stats.py", "line": 476}
    ]
  }
}

Tests

Three new tests: an omitted or-fallback alias is surfaced, a clean shape with no divergence carries no also_accessed, and a cross-record co-mention (an assignment, not a fallback) is correctly not reported as an alias. The alias detection is a generic Python idiom — the tests use synthetic identifiers, not the repo's own field names.

[repowise-bot]

✅ Health: 7.6 (unchanged)

📋 At a glance
3 hotspots touched · 3 new findings introduced · 5 co-change pairs left out · 1 file with recent fix history · 1 dead-code finding.

Files & modules (2)

• packages (2 files)
  • .../tool_answer/answer.py
  • .../tool_answer/data_shape.py
• tests (1 file)
  • .../mcp/test_answer_data_shape.py

⚠️ Change risk: moderate _{(riskier than 44% of this repo's commits · raw 8.7/10)}
This change's risk is driven by:

• more lines added than baseline
• more scattered than baseline

🩹 Review priority _{(files here with the most recent bug-fix history — defects cluster, so review these first)}

• .../tool_answer/answer.py — fixed 2× in the last ~6 months

🔎 More signals (3)

🔥 Hotspots touched (3)

• .../mcp/test_answer_data_shape.py — 1 commits/90d, 0 dependents · primary owner: Raghav Chamadiya (100%)
• .../tool_answer/answer.py — 12 commits/90d, 2 dependents · primary owner: Swati Ahuja (55%)
• .../tool_answer/data_shape.py — 1 commits/90d, 2 dependents · primary owner: Raghav Chamadiya (100%)

🔗 Hidden coupling (1 file)

• .../tool_answer/answer.py co-changes with these files (not in this PR):
  • .../tool_answer/config.py (6× — 🟢 routine)
  • .../tool_answer/symbols.py (5× — 🟢 routine)
  • .../mcp_server/tool_symbol.py (3× — 🟢 routine)
  • .../mcp/test_answer_calibration.py (3× — 🟢 routine)
  • .../mcp_server/tool_search.py (3× — 🟢 routine)

💀 Dead code (1 finding)

• 💀 .../tool_answer/answer.py _json_default (confidence 0.65)

---

📊 Full report · ⭐ Star Repowise · 📥 Install bot · Last updated 2026-07-11 12:23 UTC
_{Silence on a single PR with [skip repowise] in the title · Per-repo toggle on repowise.dev/settings?tab=bot}