Playbook: learn a new codebase
The question, in the user's words: "I am new to this repository. What services are in it, how do they talk to each other, what routes do they serve, and what do they store?"
What you get at the end: the shape of the repository in a handful of answers, each small, before you open a file. Then the one or two areas to read, chosen from those answers.
In recorded agent sessions (these recordings are mostly Niro's own development, labelled by hand by one agent, about plus or minus 10%), understanding existing code was the most common use of Niro: 329 of 794 calls (41%), almost all of them code_grep (207) and get_source_code (93). The structure tools below were rarely used, although they answer the first questions with less reading.
The steps
1. How is the repository split?
niro modules
/home/niraj/projects/github/keycloak holds 51 modules:
0.6 dockerfile .
0.5 entrypoint authz/policy/common
0.9 depended_on_library authzen/services
...
Each line is a folder Niro treats as its own unit, and the kind of signal that made it one: here a Dockerfile, a runnable entry point, or a library other modules depend on.
2. Which service calls which?
niro ask get_service_topology
18 link(s) between parts of this project:
main -> armeria (3 route(s))
GET /api/prices/{param}
POST /api/prices/recalculate
POST /shop.pricing.v1.PricingDesk/Quote (grpc)
main -> helidon-se (2 route(s))
...
Keycloak is mostly one server, and its topology has one link, from a test. That is an answer too: there is little to learn here about calls between services.
3. What does it serve?
niro ask find_api_endpoints limit=10
Found 938 HTTP endpoints.
Narrow it with path_pattern=/admin or service_filter=<folder>. In Keycloak, 938 routes is too many to read: pick the area you will work on.
4. What does it store, and what messages does it send?
niro ask list_data_resources limit=15 # Keycloak: 67 stores, USER_ENTITY used 20 times, REALM 10, ...
niro ask list_events limit=12 # java-mono: 34 events, with how many publish and handle each
5. What types are there?
niro ask list_types limit=50
11220 type(s):
Use it to find a class by name. For one class, get_class_structure answer=count gives its size and how many subtypes it has.
6. See it in a browser
niro ui draws the graph on a page served only on this computer. See Learn a codebase with Niro.
Why the answer is trustworthy, and where it is not
- Modules, routes, stores and events come from the code and its build and deploy files, read by tables of known frameworks and libraries. A framework Niro has no table for is missing from these lists. See Supported languages.
- If services are joined wrongly, tell Niro where they live: Configure a folder.
What grep would do instead
grep can list files, but it has no idea of a service, a route declared by a folder name, or a store reached through an ORM. For example, in the TypeScript corpus find_api_endpoints path_pattern=/api/bookings finds 2 routes declared only by folder names, where grep -rn "api/bookings" finds 0 lines.
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
Learn a codebase with Niro, How the graph works, Playbook: data stores and events.