Playbook: change code safely
The question, in the user's words: "I want to change KeycloakModelUtils.findUserByNameOrEmail so it stops falling back to a username lookup. What depends on it?"
What you get at the end: how big the change is, every caller up to three levels, the places to check, and which callers are tests. This is the check to run before an edit; Playbook: "it broke after my change" is the same check after one.
Words used on this page:
- the blast radius of a change is everything it can affect: what calls the changed code (upstream) and what it calls (downstream);
- an overload is one of several methods with the same name and different parameters;
- a static import lets a Java file call another class's static method with no class name in front, as
findUserByNameOrEmail(...).
In recorded agent sessions, this was the second most common use of Niro: 144 of 794 calls (18%) mapped callers before an edit (these recordings are mostly Niro's own development, labelled by hand by one agent, about plus or minus 10%).
The steps
1. How big is it?
niro ask get_blast_radius method_fqn=org.keycloak.models.utils.KeycloakModelUtils.findUserByNameOrEmail answer=count
Blast radius for KeycloakModelUtils.findUserByNameOrEmail — 163 affected functions, risk: high (+4 in tests, not counted in risk) (upstream 30, downstream 137)
Upstream (what calls it) is what your change can break: 30 entries. Downstream (what it calls) is 137, but a change to this method's own behaviour does not change what those callees do.
2. The callers, by name and depth
niro ask get_blast_radius method_fqn=org.keycloak.models.utils.KeycloakModelUtils.findUserByNameOrEmail direction=upstream answer=names
upstream:
AbstractUsernameFormAuthenticator.getUserFromForm (depth 1)
AbstractUsernameFormAuthenticator.getUser (depth 2)
...
ValidateUsername.authenticate (depth 1)
OrganizationAuthenticator.resolveUser (depth 1)
DefaultCIBALoginUserResolver.getUserFromLoginHint (depth 1)
BackchannelAuthenticationEndpoint.authorizeClient (depth 3)
AuthenticationManager.lookupUserForBruteForceLog (depth 1)
ResourceOwnerPasswordCredentialsGrantType.process (depth 3)
PassThroughAuthenticator.authenticate [test] (depth 1)
UsernameOnlyAuthenticator.authenticate [test] (depth 1)
[shown all 30 entries; ask without answer= for signatures and code]
So the change reaches the browser login form, direct grant (password) logins, X.509 logins, organization logins and CIBA (backchannel) logins. Those are the flows to test.
3. The places, to open one by one
answer=locations gives file:line and the exact id of each caller, which get_source_code takes as it is. For the direct callers only, use get_reverse_call_chain (it lists direct callers and, with depth, the levels above).
4. Overloads are answered one by one
A short name that matches several methods is answered once per match when you give answer:
niro ask get_reverse_call_chain method_fqn=ErrorResponse.error answer=count
## ErrorResponse.error(String, Response.Status) (overload 1 of 2)
ErrorResponse.error has 100 callers.
## ErrorResponse.error(String, Object[], Response.Status) (overload 2 of 2)
ErrorResponse.error has 3 callers.
Why the answer is complete, and where it is not
- All direct callers are listed, including a bare call through a static import.
OrganizationAuthenticator.resolveUsercallsfindUserByNameOrEmail(session, realm, username)with no class name in front. - "confidence: PARTIAL" on step 1 means the walk stopped at depth 3 with more callers beyond; it says how many entries were cut there. Ask
depth=4ordepth=5if the far end matters. - Known gap: methods declared on a parent interface. Asking about an implementation, or the declaring interface, can answer "0 callers" when callers use a child interface's name. Ask the name the callers use. See FAQ: wrong or missing answers.
What grep would do instead
- Level 1 works:
grep -rn "findUserByNameOrEmail("gives 10 lines in 9 files: the declaration, 7 production calls and 2 test-provider calls. Butgrep "KeycloakModelUtils.findUserByNameOrEmail", the obvious search, findsOrganizationAuthenticatoronly through itsimport staticline (68), not the call itself (353), which has no class name in front. - Level 2 and 3 do not scale. The level-1 callers include
authenticate,getUserandaction. In Keycloak,grep -F "getUser("matches 560 lines in 237 files, andgrep -F "action("827 lines in 205 files, most of them unrelated methods of the same name. - Overloads look the same to grep.
grep "ErrorResponse.error("gives 184 lines in 47 files with no way to split them by overload. The graph's caller files for the two overloads together are the same 47 files, so the lists agree, and the graph adds which overload each one calls.
Cost
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: "it broke after my change", Playbook: test a change, Plan and design with Niro.