Grep The Blast Radius

Grep the Blast Radius of a Contract Change

Type: Open-source — client-agnostic methodology, no project-specific detail.

Created by akbarsha — https://github.com/iamakbarsha1

Distilled from repeated cases where a shared contract changed, the edited package's tests stayed green, and sibling consumers broke silently.

Licence: Released under CC BY 4.0 — share and adapt for any purpose with credit. Full text: LICENSE at the repository root.

Feedback & Support: If a rule here proves wrong or needs sharpening, open an issue on the repository or contact the author at the profile link above. If the problem is the agent not following a rule below rather than the rule itself, that's an execution failure — acknowledge and correct it.

The core rule

Verification scope follows the contract, not the diff. When you change something shared, the OLD name (the field you renamed, the enum member you removed, the flag you retired) is the most complete index of its consumers that exists. Grep for it across the ENTIRE workspace — source, tests, e2e scripts, other apps, generated code, docs that assert behaviour — before you call the change done, and run every suite that crosses the changed boundary. A green suite in the package you edited proves nothing about the package that imports it.

Checks

• Grep the retired name across everything, then delete it last. Before removing or renaming a shared symbol, grep -r the old name over the whole repo (not just src/ of the current package). Each hit is a consumer you must update or consciously leave. Do the rename everywhere, THEN delete the old definition — deleting first turns the compiler/grep index you need into a pile of unrelated errors. (A shared union gained a member; an exhaustive switch and a Record<Union, ...> in a sibling package silently lost exhaustiveness, and the editing package's tests never touched them.)
• Run the suites that cross the boundary, not the one you touched. A contract change is verified by the consumers' tests, not the definer's. If the shared thing is used by three apps and an e2e script, a passing unit test in the shared library is the least informative signal available. Run the cross-boundary suites, or state explicitly which you could not run. (Illustrative: A shared function's failure mode changed from throwing to returning null; the library's own suite passed, but the one consumer app's e2e suite, which depended on the throw, was never run before merge, and the null passed through unnoticed.)
• Mirrored and duplicated encodings count as consumers. If the same intent is written in more than one place — an array whose order mirrors an enum, a hardcoded list that must match a DB column set, a client copy of a server type — the grep must find all copies. A contract with N copies has N consumers even when only one is imported. (An endpoint's field list was mirrored in a hand-maintained client array; adding a field server-side left the client array one short, with no type error to catch it.)

Pre-flight check — before you call a shared change done

• You grepped the retired/old name across the WHOLE workspace (src + tests + e2e + other apps + generated), not just the edited package.
• Every consumer the grep found is updated, or consciously left with a reason.
• You ran the suites of the CONSUMERS that cross the changed boundary, or named the ones you couldn't run.
• Any mirrored/duplicated encoding of the same intent was found and reconciled.

If any box is unchecked, the blast radius is unmeasured — go grep it.