Trace Callers Before the Diff: A Blast-Radius Card for Shared OSS Helpers

说明与用途

逐步流程创建和使用 blast‑radius 卡，识别共享助手的所有调用点，防止在更改超时时出现回归。

问题

A timeout fix for a shared helper caused a release candidate to fail because a worker still used the old signature via another package, revealing that green tests in the helper’s directory do not guarantee all import paths are safe.

结果

The workflow yields a reproducible blast‑radius card that prevents regressions by ensuring all call sites are considered before code changes, reducing review time and avoiding post‑release failures.

工作流

• 1. Create BLAST_RADIUS.md with the provided template. 2. Harvest call sites using ripgrep or git grep, filtering out vendor/dist directories. 3. Paste each hit into the card with path:line. 4. Classify each hit as caller, re‑export, wrapper, test double, or noise. 5. Record exclusions with reasons (import boundary, generated file, unused extra). 6. Commit the harvest file alongside BLAST_RADIUS.md. 7. Freeze a contract table mapping call sites to inputs, old/new observables, and owner tests. 8. Edit production code only after the card and table are committed, ensuring changes stay within listed symbols. 9. Update or add tests that own the affected rows. 10. Review and merge once all tests pass and the card is complete.

证据

Maintainers then rebuilt the call graph by hand, which delayed the tag and exhausted scarce review time.

来源

Keep one markdown file in the branch, named BLAST_RADIUS.md, and treat it as a merge gate rather than decoration.

来源