A PR changes API docs. Tests pass.
But during review, there is still an awkward question: which code path is
supposed to back this doc claim?
I built AnchorMap, an open-source CLI for TypeScript repositories, for that gap.
AnchorMap makes that link explicit.
A documented claim can start with an anchor:
### DOC.ROUTING.REQUEST_CONTEXT Request context propagation
You map that anchor to one or more TypeScript seed files:
mappings:
'DOC.ROUTING.REQUEST_CONTEXT':
seed_files:
- 'src/router.ts'
From src/router.ts, AnchorMap walks the parts of the local TypeScript
import/export graph it can currently analyze and publishes a Markdown report.
In the public demo PRs, the report result is summarized directly in the PR body
so you can judge the signal before opening GitHub Actions details.
For example, if a session-security claim is added without a mapping, the PR
report says so:
- {"kind":"unmapped_anchor","anchor_id":"UTILS.SESSION.COOKIE_SECURITY"}
The result is a review trail, not a verdict: reviewers can inspect whether a
documented claim still points to the TypeScript files expected to support it.
The review gap
In TypeScript projects, docs and implementation can drift during normal
maintenance:
- a new API behavior is documented before the implementation lands;
- a refactor moves code that used to satisfy a documented behavior;
- a stale spec-like statement stays in Markdown after code changes;
- reviewers know the code, but not every requirement captured in Markdown.
Tests, docs linters, PR templates, and CODEOWNERS can all help. They usually do
not show the doc-to-code link reviewers need to inspect.
AnchorMap makes that gap visible in the PR workflow output.
What the report shows
The small example above is the failure shape. A full report also shows summary
counts, policy decisions, change impact, and suggested actions.
Here is a trimmed report from the unmapped-anchor demo PR, with the anchor used
in that demo:
# AnchorMap traceability report
## Summary
- Analysis health: clean
- Observed anchors: 4
- Usable mappings: 3
- Covered product files: 31/58 (53%)
- Findings: 1
## Policy violations
Decision: FAIL
- {"kind":"finding_kind_present","finding_kind":"unmapped_anchor","count":1}
## Change impact
- Comparability: same_scope
- Findings added: 1
## Findings
- {"kind":"unmapped_anchor","anchor_id":"PREVIEW.UNMAPPED_ANCHOR"}
## Suggested actions
- Add a mapping for "PREVIEW.UNMAPPED_ANCHOR".
In this report, "product files" means TypeScript files inside the configured
review scope. A file can be inside that scope but no longer traced from any
mapped anchor.
The report can also flag untraced_product_file when a TypeScript file is
inside the configured scope but no longer reached from any mapped anchor. That
is a review prompt, not dead-code proof.
The demo uses the normal CI gate mode, fail-on-policy: "true", so policy
failures should make the preview PR checks turn red after the report is
available. For this demo, read the PR body summary first; Checks, job
summaries, and artifacts are verification context, not the main path.
If you want to explore AnchorMap without blocking a workflow, set
fail-on-policy: "false" and read policy_exit plus the job summary as
advisory signal.
What AnchorMap checks
AnchorMap reads explicit local inputs:
- Markdown heading anchors or YAML root
idanchors; - a local
anchormap.yamlconfig; - explicit mappings from anchors to TypeScript seed files;
- for diff-style reports, an explicit baseline scan artifact.
For YAML sources, the anchor can be the root id value:
id: DOC.ROUTING.REQUEST_CONTEXT
title: Request context propagation
It then writes local artifacts that show the scan result, check result, diff,
and review report.
Mappings are explicit. Someone has to write them down, which adds maintenance
cost. The upside is auditability: reviewers can see exactly what was mapped and
why a report changed.
From those inputs, AnchorMap reports findings such as:
- unmapped anchors, where a doc or spec anchor exists without a code mapping;
- stale mappings, where a mapping points to an anchor that is no longer observed;
- degraded analysis, where the report still renders but warns that part of the TypeScript graph could not be trusted or followed.
The output is meant to be readable in the PR context, not in a separate
dashboard. The generated workflow summary and artifact remain available for
deeper verification.
What the h3 demo shows
The public demo does not cover all of h3, the TypeScript HTTP framework. It
focuses on a small slice and gives readers four no-install PR scenarios: clean,
unmapped anchor, stale mapping, and degraded analysis.
Full setup details: anchormap-h3-demo
The demo PRs are:
Start with the unmapped-anchor demo PR. Read the AnchorMap report summary
block near the top of the PR body. It shows the direct review signal: a
spec-like anchor was added without a mapping.
If you want the clean comparison after that, open the passing baseline. It
shows the preview path where the supplied policy passes.
Design boundaries
AnchorMap is intentionally narrow.
It reports traceability, not correctness: reviewers still decide whether the
behavior is implemented correctly or safe to delete.
It reads repository files and explicit local artifacts; it does not upload
source code to an AnchorMap service, require a SaaS account, or use AI to guess
mappings.
The preview GitHub Action does not create PR comments by default. It uses
workflow artifacts and job summaries, so the first demo does not need PR comment
permissions.
What I need feedback on
Generating the report is the easy part. The real question is whether maintainers
of TypeScript repositories find explicit mappings useful enough to maintain.
That is why the demo is no-install: read the PR body report summary first, then
decide whether the mapping cost makes sense.
If you maintain a TypeScript repo with docs, API references, or spec-like
Markdown, I am mostly interested in what would block a real trial: mapping
overhead, noisy reports, bad CI fit, or simply not worth maintaining.