Skip to content

fix(5227): resolve ADR/RFC citation stubs to the decision document - #5346

Open
Deepjyoti-Sarmah wants to merge 8 commits into
Graphify-Labs:v8from
Deepjyoti-Sarmah:fix/5227-adr-citation-resolution
Open

Deepjyoti-Sarmah wants to merge 8 commits into
Graphify-Labs:v8from
Deepjyoti-Sarmah:fix/5227-adr-citation-resolution

Conversation

@Deepjyoti-Sarmah

Copy link
Copy Markdown
Contributor

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 .ts file.

The extractor turns the comment into a cites edge to docref_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:

  • its title (first heading) starts with it: # ADR-0007: Example, # ADR 7 - Use Postgres, # RFC-12: Thing; or
  • its file name starts with the number and it sits directly in an adr, adrs, decisions, rfc or rfcs folder (the adr-tools layout, doc/adr/0007-use-postgres.md).

When exactly one document claims the id, the cites edge 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 stays cites, 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 update sequences showed three ways an incremental rebuild disagreed with a full build:

Step Before Cause Fix
edit a.ts link lost, back to stub watch.py and cli.py copy only a whitelist of node fields into the resolver context; node_kind was not one forward node_kind and source_location for document nodes
add 0008-b.md, a.ts untouched ADR-0008 stays a stub a.ts is not re-extracted, so its edge never resolves when a Markdown file changes or is deleted, also re-extract the code files that have a cites edge in the stored graph
delete 0007-a.md, a.ts untouched the cites edge disappears the edge pointed at a page that no longer exists same re-extract; the edge falls back to the stub
edit a.ts orphan docref_adr_0007 node left behind resolvers run on a scratch node list there, so a removal never reaches the graph the resolver flags the stub, and extract() drops flagged stubs after both resolver branches

Each row now gives the same result as a full build.

Options I tried

  • A, redirect the edge (this PR). One hop from code to doc, no stub left.
  • B, keep the stub and add stub -> doc references. The doc stays two hops away and the stub stays attributed to the .ts file. 6 of the 10 first tests fail with it.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Tests or CI
  • Refactor
  • Security fix

Verification & Invariants

Invariant: a cites edge 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.

  • Read the CONTRIBUTING.md guide.
  • Reproduced the issue and identified the invariant.
  • Made the smallest fix necessary.
  • Added a regression test (if bug fix) or isolated boundary test.
  • Kept the PR description synchronized with the final implementation.
  • Documented any limitations / unsupported cases explicitly.

Merge Danger

Door: two-way. A new module graphify/doc_ref_resolution.py, one resolver registration, and small additions in watch.py and cli.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 cites edges 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

  • Only JS/TS comments create citation stubs today, so only they resolve.
  • A document whose title does not start with the id and whose file is not in a decision-record folder is not found.
  • Front-matter titles are not read.

How was this tested?

The issue's script, on 0.9.112 340268a7 and on this branch:

before  example.ts cites ADR-0007  src/example.ts
after   example.ts cites 0007-example.md  docs/decisions/0007-example.md

New tests in tests/test_doc_ref_resolution.py (14):

resolves:      title heading | adr-tools file name | "ADR 7 - x" | RFC-12 | two .ts files, one doc
stays a stub:  two claimants | no doc | body-only mention | number outside a record folder
               | checkout under .../adr/ | title that only mentions the id
other:         relation stays cites, never implements | resolved stub dropped
incremental:   _rebuild_code full build -> edit code -> add doc -> delete doc

Each fix commit is pinned: with graphify/ checked out at the commit before it, a test fails.

graphify/ at failing
0.9.112 340268a7 8 (link cases, stub drop, incremental)
resolver only own-folder, incremental (code edit)
+ incremental context own-folder, incremental
+ own-folder rule incremental (orphan stub)
+ stub drop incremental (doc added)
+ re-extract on doc change none, 14 passed

Full suite, same venv:

failed passed
0.9.112 0 11591
this branch 0 11605

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.

ruff check graphify/doc_ref_resolution.py graphify/watch.py graphify/cli.py graphify/extract.py tests/test_doc_ref_resolution.py  -> All checks passed

Graphify-specific checklist

  • I updated generated skill artifacts (uv run python -m tools.skillgen --bless) when changing their source fragments. (N/A: no skill change.)
  • I confirmed that AST/structural extraction remains deterministic (no ambient state dependencies like ENV variables).
  • I reviewed changes for security implications (no unsafe interpolation into shell/Python). (N/A: matches labels and paths.)
  • I confirmed no API keys or local-only graph data are included.
  • (If applicable) I disclosed AI authorship in my commit messages. (No trailer in the commit messages.)

@github-actions

Copy link
Copy Markdown

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.

@github-actions github-actions Bot added the contributor Pull request from a returning community contributor label Nov 19, 2026

@graphify-labs graphify-labs Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graphify code review View in Graphify

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 — raise minCoveringTests to run the full suite instead when coverage is this thin.

  • tests/test_4874_jvm_resolution.py — impact
  • tests/test_4978_reconcile_cost.py — impact
  • tests/test_4992_ts_import_types.py — impact
  • tests/test_affected_cli.py — impact
  • tests/test_affected_overrides.py — impact
  • tests/test_affected_seed_reference_forms.py — impact
  • tests/test_agents_platform.py — impact
  • tests/test_alias_folding.py — impact
  • tests/test_analyze.py — impact
  • tests/test_astro_extraction.py — impact
  • tests/test_astro_import_ids.py — impact
  • tests/test_blade_extractor.py — impact
  • tests/test_build.py — impact
  • tests/test_build_located_semantic_identity.py — impact
  • tests/test_build_merge_dedup_scope.py — impact
  • tests/test_build_merge_ghost_fold_4955.py — impact
  • tests/test_build_merge_hyperedges_and_prune.py — impact
  • tests/test_build_merge_shrink_guard.py — impact
  • tests/test_builtin_global_type_refs.py — impact
  • tests/test_c_include_resolution.py — impact
  • tests/test_cache.py — impact
  • tests/test_cache_stale_import_target.py — impact
  • tests/test_carried_hyperedge_remap.py — impact
  • tests/test_case_only_decl_ids_4904.py — impact
  • tests/test_case_sensitive_resolution.py — impact
  • tests/test_chunking.py — impact
  • tests/test_cjs_module_extension.py — impact
  • tests/test_cli_export.py — impact
  • tests/test_cloud_cta.py — impact
  • tests/test_cluster.py — impact
  • tests/test_cobol_extractor.py — impact
  • tests/test_code_only_scope_4923.py — impact
  • tests/test_codebuddy.py — impact
  • tests/test_compact_graph_json.py — impact
  • tests/test_confidence.py — impact
  • tests/test_confidence_score_output.py — impact
  • tests/test_corrupt_graph_json.py — impact
  • tests/test_cpp_alias_member_resolution.py — impact
  • tests/test_cpp_anonymous_namespace_receivers.py — impact
  • tests/test_cpp_conditional_initializers.py — impact
  • tests/test_cpp_forward_declarations.py — impact
  • tests/test_cpp_forward_receiver_completion.py — impact
  • tests/test_cpp_incremental_type_resolution.py — impact
  • tests/test_cpp_inherited_member_resolution.py — impact
  • tests/test_cpp_local_callable_shadowing.py — impact
  • tests/test_cpp_member_call_by_receiver_type.py — impact
  • tests/test_cpp_member_declaration_identity.py — impact
  • tests/test_cpp_method_declarations.py — impact
  • tests/test_cpp_nested_and_cli.py — impact
  • tests/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() in graphify/extract.py:11748 · 1284 callers, 78 callees: fans out to 78 callees (efferent coupling); 1284 callers depend on it (afferent coupling)
  • build_from_json() in graphify/build.py:1649 · 326 callers, 26 callees: fans out to 26 callees (efferent coupling); 326 callers depend on it (afferent coupling)
  • collect_files() in graphify/extract.py:13900 · 24 callers, 7 callees: fans out to 7 callees (efferent coupling); 24 callers depend on it (afferent coupling)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

contributor Pull request from a returning community contributor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Resolve unambiguous ADR citation stubs to scanned decision documents

1 participant