Repository navigation
fix(5227): resolve ADR/RFC citation stubs to the decision document - #5346
Deepjyoti-Sarmah wants to merge 8 commits into
Conversation
|
Thanks for the pull request, @Deepjyoti-Sarmah. A maintainer will review it soon. Want to talk it through while it is in review? Come join us on our Discord server. For longer-form discussion there is also GitHub Discussions. A couple of things that speed up review: make sure the test suite passes on Python 3.11 and 3.13, and that the change keeps extraction deterministic. |
There was a problem hiding this comment.
Graphify code review 
Review completed · 1893db6aa1ee
Warning
Merge confidence: 3/5 · Review before merging · 🟠 High impact
1 P2 bugs, 1 unranked
The change adds a whole-corpus pass that redirects resolved ADR/RFC citation stubs to decision-document pages.
Full summary
The change adds a whole-corpus pass that redirects resolved ADR/RFC citation stubs to decision-document pages. It also carries document metadata into incremental resolver context and re-extracts citing files when Markdown files change.
Bugs (2)
P2 · Refresh citing files when a semantic-backed Markdown decision changes in _rebuild_code: otherwise their citation edges can still resolve to the decision named by its old heading. Inspect source
Detailed review · checked against the code
Editing a semantic-backed document can leave citation edges pointing to its old decision
When an existing semantic-backed Markdown document is edited incrementally, its citation edges may continue pointing to the decision it named before the edit.
Expected: Citing files are refreshed so citation resolution reflects the edited document.
Actually: The edited document is excluded from extract_targets and is not a deleted identity, so it does not trigger re-extraction of citing files; the preserved heading can remain stale for resolution.
Incremental selection excludes still-existing semantic-backed Markdown files from wanted, and the early return can skip the rebuild when such a file is the only change. If another change allows processing to continue, the citation refresh check still looks only at extract_targets and deleted identities. The resolver uses a document page and its first heading to determine which decision it claims, so preserving the old heading can leave citations resolved to the old decision.
-
Independent source review: Inspected the incremental citation tests: they cover code edits and adding or deleting ordinary decision documents, but not editing a semantic-backed document. The inspected selection and refresh paths contain no mitigation for that case.
-
This applies to incremental rebuilds of semantic-backed documents that are excluded from
extract_targets; other Markdown documents in the changed batch are handled by the new check. -
Also reported as: Edits to semantic-backed Markdown documents leave citations stale
Run citation resolution when decision documents change in dispatch_command, even if no JavaScript or TypeScript files are re-extracted; otherwise citations can remain stubs or point to the previous document. Inspect source
Detailed review · checked against the code
CLI incremental updates leave citations unchanged when a decision document changes
When an incremental CLI run adds, edits, or deletes a decision document without re-extracting a JavaScript or TypeScript file, citations are not resolved against the updated document set. They can remain stubs or point to the previous document.
The CLI incremental scan puts changed documents in the semantic-file list, while changed code files are selected separately. AST extraction runs only when code_files is nonempty, and the citation resolver is registered for JavaScript/TypeScript suffixes and invoked using the AST extraction paths. Thus, when only a decision document changes, the unchanged citing source does not activate the resolver; the updated document set is not used to refresh its citation edge. The new resolver is absent from base, where the citation-resolution feature did not exist; in head, full extraction can resolve citations, but this CLI incremental case does not.
- Independent source review: The watch rebuild path explicitly adds files with existing cites edges to its extraction targets when relevant documents change. The existing incremental integration test exercises that watch path, including document addition and deletion, not the CLI incremental path, so it does not mitigate this CLI gap.
What this review covered
- Some lookups asked for files or lines that do not exist; the review was told and carried on.
- 5 of 5 changed files inspected. This is scope, not a correctness guarantee.
Code graph and static checks · 5249 functions depend on this change
Impact & health
Impact — 5249 functions depend on the 654 functions this change touches.
Health — this change adds coupling hotspots:
- worse:
extract()— 1284 callers, 78 callees - worse:
build_from_json()— 326 callers, 26 callees - worse:
collect_files()— 24 callers, 7 callees
Formal checks — 5249 functions this change can affect weren't formally checked in this review. Formal checks are informational only.
Gate & verification
✅ PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.
Advisory (not blocking):
- verification_scope: 5078 function(s) in the blast radius were not formally verified this run
Test selection
398 of 594 test file(s) selected (67%) via static blast radius.
ℹ️ 1 changed file rests on a single covering test (
graphify/doc_ref_resolution.py). The selection is only as good as that one test — raiseminCoveringTeststo run the full suite instead when coverage is this thin.
tests/test_4874_jvm_resolution.py— impacttests/test_4978_reconcile_cost.py— impacttests/test_4992_ts_import_types.py— impacttests/test_affected_cli.py— impacttests/test_affected_overrides.py— impacttests/test_affected_seed_reference_forms.py— impacttests/test_agents_platform.py— impacttests/test_alias_folding.py— impacttests/test_analyze.py— impacttests/test_astro_extraction.py— impacttests/test_astro_import_ids.py— impacttests/test_blade_extractor.py— impacttests/test_build.py— impacttests/test_build_located_semantic_identity.py— impacttests/test_build_merge_dedup_scope.py— impacttests/test_build_merge_ghost_fold_4955.py— impacttests/test_build_merge_hyperedges_and_prune.py— impacttests/test_build_merge_shrink_guard.py— impacttests/test_builtin_global_type_refs.py— impacttests/test_c_include_resolution.py— impacttests/test_cache.py— impacttests/test_cache_stale_import_target.py— impacttests/test_carried_hyperedge_remap.py— impacttests/test_case_only_decl_ids_4904.py— impacttests/test_case_sensitive_resolution.py— impacttests/test_chunking.py— impacttests/test_cjs_module_extension.py— impacttests/test_cli_export.py— impacttests/test_cloud_cta.py— impacttests/test_cluster.py— impacttests/test_cobol_extractor.py— impacttests/test_code_only_scope_4923.py— impacttests/test_codebuddy.py— impacttests/test_compact_graph_json.py— impacttests/test_confidence.py— impacttests/test_confidence_score_output.py— impacttests/test_corrupt_graph_json.py— impacttests/test_cpp_alias_member_resolution.py— impacttests/test_cpp_anonymous_namespace_receivers.py— impacttests/test_cpp_conditional_initializers.py— impacttests/test_cpp_forward_declarations.py— impacttests/test_cpp_forward_receiver_completion.py— impacttests/test_cpp_incremental_type_resolution.py— impacttests/test_cpp_inherited_member_resolution.py— impacttests/test_cpp_local_callable_shadowing.py— impacttests/test_cpp_member_call_by_receiver_type.py— impacttests/test_cpp_member_declaration_identity.py— impacttests/test_cpp_method_declarations.py— impacttests/test_cpp_nested_and_cli.py— impacttests/test_cpp_objc_cross_file_calls.py— impact- … and 348 more
Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.
Every flagged function
extract()ingraphify/extract.py:11748· 1284 callers, 78 callees: fans out to 78 callees (efferent coupling); 1284 callers depend on it (afferent coupling)build_from_json()ingraphify/build.py:1649· 326 callers, 26 callees: fans out to 26 callees (efferent coupling); 326 callers depend on it (afferent coupling)collect_files()ingraphify/extract.py:13900· 24 callers, 7 callees: fans out to 7 callees (efferent coupling); 24 callers depend on it (afferent coupling)
What does this PR do?
Fixes #5227. A JS/TS comment like
// See ADR-0007.now links to the decision document that is ADR-0007, instead of to a stub node filed under the.tsfile.The extractor turns the comment into a
citesedge todocref_adr_0007, and nothing ever matched that stub to a document. This adds the missing pass:example.ts -cites-> ADR-0007 [stub, source_file src/example.ts] +example.ts -cites-> 0007-example.md [docs/decisions/0007-example.md, INFERRED 0.95]A document claims an id when:
# ADR-0007: Example,# ADR 7 - Use Postgres,# RFC-12: Thing; oradr,adrs,decisions,rfcorrfcsfolder (the adr-tools layout,doc/adr/0007-use-postgres.md).When exactly one document claims the id, the
citesedge moves to that document's page node and the stub is dropped. Zero or several claimants leave the stub as it is today. The edge stayscites, so a citation is never read as an implementation, and it becomes INFERRED because the document was matched, not named.Why the incremental path changed too
Running real
graphify updatesequences showed three ways an incremental rebuild disagreed with a full build:a.tswatch.pyandcli.pycopy only a whitelist of node fields into the resolver context;node_kindwas not onenode_kindandsource_locationfor document nodes0008-b.md,a.tsuntoucheda.tsis not re-extracted, so its edge never resolvescitesedge in the stored graph0007-a.md,a.tsuntouchedcitesedge disappearsa.tsdocref_adr_0007node left behindextract()drops flagged stubs after both resolver branchesEach row now gives the same result as a full build.
Options I tried
references. The doc stays two hops away and the stub stays attributed to the.tsfile. 6 of the 10 first tests fail with it.Type of change
Verification & Invariants
Invariant: a
citesedge from code points at a decision document exactly when one scanned document claims the cited id by its title or by its numbered file name in a decision-record folder; otherwise it points at the stub. A full build and any sequence of incremental updates give the same edges.Merge Danger
Door: two-way. A new module
graphify/doc_ref_resolution.py, one resolver registration, and small additions inwatch.pyandcli.py. No cache schema bump: the resolver runs after the AST cache on every build, and a fully cached rerun still resolves. Reverting the commits restores 0.9.112.Blast Radius: small. Only graphs with JS/TS ADR/RFC citations change: those
citesedges move from the stub to the document. On an incremental update that touches a Markdown file, code files that cite ADR/RFC ids are re-extracted as well (served from the AST cache when unchanged).Limitations
How was this tested?
The issue's script, on 0.9.112
340268a7and on this branch:New tests in
tests/test_doc_ref_resolution.py(14):Each fix commit is pinned: with
graphify/checked out at the commit before it, a test fails.graphify/at340268a7Full suite, same venv:
Profile of the resolver alone on a synthetic corpus (205k nodes, 200k edges, 5k docs, 20k citations): 0.35-0.46 s. The first version took about 0.7 s because it collected every edge endpoint; it now collects only stub ids. With no citations the pass returns after one scan of the nodes.
Graphify-specific checklist
uv run python -m tools.skillgen --bless) when changing their source fragments. (N/A: no skill change.)