Catch docs-to-code drift in TypeScript PRs before merge

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 GitHub Actions workflow summary and artifacts.

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 intentionally sets fail-on-policy: "false", so readers can inspect
failure reports without making the preview PR checks turn red. GitHub may show a
green check while the AnchorMap report says Decision: FAIL in the job summary
or artifact. For this demo, the report is the thing to inspect.

What AnchorMap checks

AnchorMap reads explicit local inputs:

• Markdown heading anchors or YAML root id anchors;
• a local anchormap.yaml config;
• 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 read from the workflow summary or artifact, not in a
separate dashboard.

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:

• Clean demo PR
• New unmapped anchor
• Stale mapping
• Degraded analysis

Start with the clean demo PR. It shows the passing preview path without asking
you to interpret a failure first.

If you want the shortest failure case after that, open the unmapped-anchor PR:
it shows a spec-like anchor added without a mapping. The report excerpt above
comes from that PR.

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: inspect the report 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.

• Clean demo PR
• Shortest failure case
• Feedback issue