changes¶
repo-wiki changes maps a git diff to the symbols whose line ranges it touches
and lists each symbol's direct callers. Run it before you commit, to confirm the
change touches only what you meant and that nothing still calls a symbol you
removed.
Changes (worktree vs HEAD, a0fa1a8b16f4): 1 file(s), 2 changed symbol(s)
modified python:pkg/core.py::leaf pkg/core.py:L4-L6
d=1 callers: 3 confident, 0 possible
python:pkg/core.py::Store._write pkg/core.py:L19-L20 [CONFIDENT local]
python:pkg/service.py::via_module pkg/service.py:L16-L17 [CONFIDENT import]
python:tests/test_core.py::test_leaf tests/test_core.py:L4-L5 [CONFIDENT import] (test)
deleted python:pkg/core.py::middle pkg/core.py:L9-L10
d=1 callers: 1 confident, 1 possible
python:pkg/service.py::run pkg/service.py:L7-L8 [CONFIDENT dangling]
? python:other/helpers.py::stray other/helpers.py:L13-L14 [HEURISTIC dangling]
Summary: 2 changed symbol(s) (1 deleted, 1 modified); affected callers: 4 confident, 1 possible; risk HIGH (counting possible links: HIGH)
3 direct non-test dependent(s); 1 other module(s); 1 caller(s) still reference a deleted or moved symbol
Flows touched: 3
pkg.service.via_module [root; 2 steps; depth 1] at d=1 flow:81e076513602
pkg.cli.main [root; 5 steps; depth 4] through 2 of the symbols flow:67984a14e9db
pkg.service.persist [root; 5 steps; depth 3] at d=3 flow:0bc38b6af8b6
Flows touched lists the execution flows of the graph as it is stored,
normally built before the change, that contain a changed symbol, or the old ID of a
moved one. A symbol the diff adds is in no stored flow; pass --refresh to see it.
Flags¶
| Flag | Meaning |
|---|---|
--worktree |
The default. The worktree, staged and unstaged, plus untracked files that git does not ignore, against HEAD. |
--staged |
The index against HEAD: what git commit would record. The new side of each file is read from the index, not the worktree. |
--base REF |
The worktree, plus untracked files, against the merge base of REF and HEAD: everything your branch changed. |
--refresh |
Run the incremental build first (build --changed-only --no-summaries --no-index, about 1 s on the AKMS repository), under the build lock, then report. The flows are then those of the refreshed graph, and the flows of the graph before the refresh are reported beside them. See Refreshing first. |
--json |
Print a repo-wiki/changes/v1 object instead of text. |
--allow-stale |
Use the graph even when files outside the diff changed since it was built. |
The three modes are mutually exclusive. In a repository without commits the base is the empty tree.
How changes become symbols¶
- git lists the changed files (renames detected) and the
-U0hunks with their old and new line ranges. Paths under.repo_wiki/are ignored. - Each changed file is parsed with the extractor
builduses: the new side from the worktree (or the index for--staged), the old side from the base revision. A Python symbol's range is extended upward over its decorators. - Every changed line is assigned to the innermost symbol that contains it. Lines
on the new side give
addedandmodifiedsymbols; lines on the old side givemodifiedanddeletedones, with the base revision's line numbers. Symbols are matched across the two sides by qualname. - In a renamed file every symbol gets a new ID. Symbols the hunks did not touch
are reported as
moved, withold_id. - Non-blank, non-comment lines outside every symbol (imports, module-level
statements) are listed under
module_level_changes.
Callers come from the symbol graph with the new side of every changed file swapped in, so a call added in this change is seen without a rebuild, and callers reflect the tree being committed whether the graph was built before or after the edits.
For a deleted or moved symbol, the callers are the code that still names it.
They carry the basis dangling: confident when the caller imports the old path or
calls the name in the same file, possible when only the name matches. Any
confident dangling caller raises the risk to at least HIGH.
A caller that is itself part of the change is marked changed and is not counted
among the affected callers. The summary risk applies the
impact risk rule to the union of the remaining direct
callers.
What is not mapped¶
| File | Reported as |
|---|---|
| No extractor (Markdown, YAML, ...) or a language that is not enabled | symbols_supported: false |
| Does not parse, on either side | parse_error with the first error; no symbols |
| Binary | binary: true |
Refreshing first¶
Without --refresh, changes reads the stored graph and flows as they are and
writes nothing. With it, the command first rebuilds the changed files' graph entries
and flows.json, waiting (and saying so on stderr) while another build holds the
lock, then maps the diff on the refreshed graph. The text output starts with
Refreshed the graph first: N file(s) re-parsed in T s and the flows line becomes:
Flows touched: 1 in the refreshed graph (before the refresh: 0; only before: 0, only after: 1)
pkg.core.added [root; 2 steps; depth 1] at d=0 flow:7db2a7cca409
The JSON gains these keys, and only these, with --refresh:
| Key | Content |
|---|---|
refresh |
seconds, parsed (files re-parsed), errors (files that failed to parse). |
flows_before |
Flow participation in the stored graph when the command started, or null when there was no graph. |
flows_after |
Flow participation in the refreshed graph. Equal to flows, which always describes the graph the command read. |
summary.flows_touched_before, summary.flows_touched_after |
Flows with a changed symbol in each graph (before is null without a prior graph). |
summary.flows_only_before, summary.flows_only_after |
Flows touched in one graph and not the other. |
summary.flows_touched counts the distinct flows that contain a changed symbol in
any graph the command read: the stored graph without --refresh, both graphs with
it. Without --refresh the output has the same shape as before.
Run --refresh after editing and before reporting the impact of new code. With the
git hooks installed the stored graph is usually current after a commit,
but only --refresh guarantees it matches the working tree.
Staleness¶
The files in the diff, and any file with uncommitted changes, are expected to
differ from the graph and are not checked. Any other source that differs from
what the graph was built from, for example after a git pull without a rebuild,
makes the command exit 3. Rebuild with
repo-wiki build --changed-only --no-summaries --no-index.
JSON¶
{
"schema": "repo-wiki/changes/v1",
"mode": "worktree", "base": null, "base_commit": "a0fa1a8b...",
"files": [{"path": "pkg/core.py", "old_path": null, "status": "modified",
"binary": false, "symbols_supported": true, "parse_error": null,
"hunks": [{"old_start": 6, "old_lines": 1, "new_start": 6, "new_lines": 1}]}],
"changed_symbols": [
{"id": "python:pkg/core.py::middle", "old_id": null, "status": "deleted",
"kind": "function", "name": "middle", "qualname": "middle",
"path": "pkg/core.py", "start_line": 9, "end_line": 10,
"is_test": false, "public_entry": null,
"callers": {"confident": [{"id": "python:pkg/service.py::run", "changed": false,
"edge": {"type": "calls", "resolution": "CONFIDENT",
"basis": "dangling", "name": "middle"},
"...": "..."}],
"possible": [...]}}
],
"module_level_changes": [],
"summary": {"files": 1, "changed_symbols": 2,
"by_status": {"deleted": 1, "modified": 1},
"affected_callers": {"confident": 4, "possible": 1},
"dangling_references": 1, "modules_reached": 1,
"public_entry_points": [], "risk": "HIGH", "risk_with_possible": "HIGH",
"risk_reasons": ["..."], "flows_touched": 3},
"graph": {"path": "...", "built_commit": "...", "stale": false,
"changed": [], "added": [], "removed": []},
"flows": {"count": 3, "source": "file", "reason": null, "flows": [...]}
}
File status is added, modified, deleted or renamed. Symbol status is
added, modified, deleted or moved.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | Success, whatever the risk level. |
| 1 | git failed (not a work tree, an unknown --base ref), or --refresh found the build lock held for 600 s (build_lock). |
| 3 | The symbol graph is missing, unreadable, or stale outside the diff. |