Playbook: "it broke after my change"
The question, in the user's words: "I changed how credentials are created and removed, and now something else fails. What does my change reach?"
What you get at the end: everything that calls the changed methods (up to the depth you ask), which of those are tests, the routes and other services on the way, and what the changed methods call in turn.
Words used on this page: the blast radius of a change is everything it can affect: the methods that call the changed code (upstream) and the methods it calls (downstream).
The steps
1. Name every method you changed, in one call
method_fqns takes a list, and treats it as one change. Start with the count, to see how big it is:
niro ask get_blast_radius method_fqns='["org.keycloak.models.jpa.JpaUserCredentialStore.createCredentialEntity","org.keycloak.models.jpa.JpaUserCredentialStore.removeCredentialEntity"]' answer=count
Blast radius for 2 methods — 46 affected functions, risk: high (+6 in tests, not counted in risk) (upstream 27, downstream 25)
confidence: PARTIAL | has_more: true — ... What is cut is only the far end of the chain: 22 node(s) marked "[+N more beyond depth]" have callers further out that were not walked.
[counts only; ask without answer= for the list]
"PARTIAL" here means the walk stopped at the depth you asked (3 by default), not that something was missed inside it.
2. List the names, upstream only
niro ask get_blast_radius method_fqns='[...same two...]' direction=upstream answer=names
Blast radius for 2 methods — 21 affected functions, risk: high (+6 in tests, not counted in risk) (upstream 27)
upstream:
JpaUserCredentialStore.createCredential (depth 1)
UserCredentialManager.createStoredCredential (depth 2)
SubjectCredentialManagerCacheAdapter.createStoredCredential (depth 3)
PasswordCredentialProvider.createCredential (depth 3)
...
CredentialModelTest.testCredentialCRUD [test] (depth 3)
...
ResetOTP.authenticate (depth 3)
UserResource.removeCredential (depth 3)
JpaUserProvider.removeStoredCredential (depth 1)
[shown all 27 entries; ask without answer= for signatures and code]
This is the list to check against the failure. Entries marked [test] are the tests that already reach the change: run those first. UserResource.removeCredential is an admin REST method, so the change reaches the admin API.
3. When the changed code is a route, other services count too
From the synthetic java-mono corpus, after a change to the GET /api/shipments/{id} handler:
niro ask get_blast_radius method_fqn=com.example.shop.shipping.ShippingMain.shipment answer=names
Blast radius for ShippingMain.shipment — 3 affected functions, risk: low (upstream 3)
upstream:
ShippingMain.routing (depth 1)
ShippingMain.main (depth 2)
ApacheHttpClient5Calls.shipment over HTTP (depth 1)
"over HTTP" marks a caller in another service: here main, which calls the route by its address. get_impact_analysis http_path=/api/shipments/{param} gives the same list starting from the route.
4. Read only what the list points at
Each full entry carries file:start-end, so get_source_code or a ranged file read opens exactly that method. Ask for answer=locations when you want the places without the code.
Why the answer is complete, and where it is not
- Every direct caller is listed, and every caller up to the depth. The calls through an interface are followed:
SubjectCredentialManagerCacheAdapteris reached although the tests only namecredentialManager(), an interface. - Callers through a value whose type the code does not state are counted as "Not listed" and named, so you can read them.
- A method declared on a parent interface can show fewer callers than it has, in this release. See FAQ: wrong or missing answers.
What grep would do instead
- One level costs one search per name.
createCredentialEntityhas 2 direct callers; each of those has callers; at depth 3 there are 27 entries to find, so a grep route needs a search for each name it meets. - Common names explode. Level 3 here includes
authenticate,actionandcreateCredential. In Keycloak,grep -F "authenticate("matches 108 lines in 79 files andgrep -F "action("827 lines in 205 files. - Interface calls do not name the class that runs. In one of our Keycloak A/B sets, every item the shell-only agent missed was an implementation reached through an interface.
Cost
Full entries are much larger than names, so ask for names first and the full entries only where you need them. What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in Tokens, speed and accuracy.
Related
Playbook: change code safely (the same check before you edit), Playbook: test a change, Playbook: review a change.