Moving Beyond Raw Git Diffs: Evidence-Backed Symbol Change Reports

Git diffs are the universal standard for code review, but they operate at the line level rather than the semantic level. A one-line signature change in an exported function can have a higher blast radius than a 200-line CSS refactor, yet git treats them both as raw text changes.

In TokenCap, we built src/diff/buildDiffReport.js to produce evidence-backed semantic diff reports.

What the Semantic Diff Report Computes

1. Symbol Changes: Identifies exactly which functions, methods, and classes were added, modified, or deleted.
2. Breaking Change Detection: Flags parameter list alterations and removed exports that break existing call sites.
3. Test Association: Scans the call graph to list the specific test files covering the modified symbols.
4. Risk Rating: Computes risk (LOW, MEDIUM, HIGH, CRITICAL) based on transitive caller volume and module boundary crossings.

CLI Inspection

tokencap diff

Output:

Comparing working tree against origin/main...
Files Changed: 4 files (+42, -18 lines)
Symbol Alterations:
  - MODIFIED: src/auth/jwt.js:verifyToken (Signature changed: +options param)
Breaking Change Risk: HIGH
Downstream Impact:
  - 4 direct call sites affected
  - 18 transitive callers across 3 clusters
Recommended Tests to Run:
  - test/auth.test.js
  - test/session.test.js
Report generated in .tokencap/diff/review-packet.md

You can inject this report directly into your PR description or pass it to an AI agent to verify that all affected call sites were updated.

Learn more at tokencap.vansharora.app