docs: add source-backed reference gate by flyingrobots · Pull Request #679 · git-stunts/git-warp

flyingrobots · 2026-06-25T20:18:24Z

Summary

add a generated source-backed reference topic for package entrypoints, root API exports, CLI commands, structured CLI error payloads, and public error classes
add scripts/check-source-backed-reference.ts and wire it into npm run lint:docs-topology
link the generated reference from README and the topics index

Issue

Fixes #670

Test plan

npm run lint:source-backed-reference
npm run lint:docs-topology
npm run lint:md -- README.md CHANGELOG.md docs/topics/README.md docs/topics/reference.md
npm run lint:md:code
npm run lint -- --no-warn-ignored scripts/check-source-backed-reference.ts
npm run typecheck
npm run typecheck:policy
npm run test:local
npm run release:guard -- --stage prep-pr --tag v18.1.1
pre-push IRONCLAD M9 gates: link check, static gates, stable unit-test shards

ADR checks

This PR does not implement ADR 2 without satisfying ADR 3
This PR does not touch persisted op formats; no ADR 3 readiness issue is required
This PR does not touch wire compatibility; canonical-only wire behavior is unchanged
This PR does not touch schema constants; patch and checkpoint namespaces are unchanged

Summary by CodeRabbit

New Features
- Added a generated, source-backed reference page covering package entrypoints/exports, public API exports, CLI commands, and public error payloads/classes.
- Added automated tooling to generate and verify the reference stays in sync.
Documentation
- Updated README and the topics “Operate” shelf to point to the generated reference.
- Expanded the changelog with an entry describing the new reference coverage.
Chores
- Added linting plus documentation topology and release gates that fail if the reference page is missing or out of date.

coderabbitai · 2026-06-25T20:18:37Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f318f9f1-c6ea-4b82-b432-a666d930fd9f

📥 Commits

Reviewing files that changed from the base of the PR and between 23e2f78 and 28048b3.

📒 Files selected for processing (2)

docs/topics/reference.md
scripts/check-source-backed-reference.ts

💤 Files with no reviewable changes (2)

scripts/check-source-backed-reference.ts
docs/topics/reference.md

📝 Walkthrough

Walkthrough

Adds a generated docs/topics/reference.md page sourced from package exports, CLI commands, and public error classes. It also adds a checker script and lint entry to regenerate or validate the page, and updates docs and release scripts to require it.

Changes

Source-backed reference docs

Layer / File(s)	Summary
Source readers and inventory capture `scripts/check-source-backed-reference.ts`	The script loads source files and parses package entrypoints, root exports, CLI commands, and public error classes into inventory items.
Markdown generation and lint wiring `scripts/check-source-backed-reference.ts`, `package.json`	The script renders inventories into markdown, supports write-versus-stale-file behavior, and package.json adds a lint entry to run it.
Reference page content `docs/topics/reference.md`	The generated page adds the title, regeneration note, package entrypoints, root API export modules, root value exports, root type exports, the CLI command registry, the CLI error payload shape, and public error classes.
Docs links and release gates `CHANGELOG.md`, `README.md`, `docs/topics/README.md`, `scripts/check-docs-topology.sh`, `scripts/release-guard.sh`	The changelog, README, and topic index link the new reference page, and the docs-topology and release-guard scripts require it.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

git-stunts/git-warp#675 — Shares the release-gating path in scripts/release-guard.sh by updating the required-docs list.

Poem

A rabbit found a paper trail,
from exports down to CLI rail.
The burrow checks what source has said,
and regenerates the doc ahead.
Hop, hop — the reference stays well fed 🐰

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the new source-backed docs gate.
Description check	✅ Passed	The description includes a summary, linked issue, test plan, and ADR checklist in the required template.
Linked Issues check	✅ Passed	The changes satisfy `#670` by adding a source-backed generator, cited reference output, docs-topology integration, and drift detection.
Out of Scope Changes check	✅ Passed	The modified files all support the new reference doc and its gates, with no clear unrelated code changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/source-backed-reference

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-06-25T20:24:34Z

Release Preflight

package version: 18.1.1
prerelease: false
npm dist-tag on release: latest
npm pack dry-run: passed
jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Release Autotag will run final preflight and create v18.1.1. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/check-source-backed-reference.ts`:
- Line 227: The hardcoded CLI source reference in
SourceText('bin/warp-graph.ts') should not rely on a fixed line number for
cliSource.ref(129), since it can drift from the actual error payload. Update the
lookup in check-source-backed-reference.ts to derive the citation from the
expected payload text or verify the line content before creating the reference,
using the cliSource symbol so the docs always point to the correct error block.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5b5a71c5-0309-490d-9a7d-fc33f08df8ab

📥 Commits

Reviewing files that changed from the base of the PR and between 615b974 and f508570.

📒 Files selected for processing (8)

CHANGELOG.md
README.md
docs/topics/README.md
docs/topics/reference.md
package.json
scripts/check-docs-topology.sh
scripts/check-source-backed-reference.ts
scripts/release-guard.sh

github-actions · 2026-06-25T20:48:24Z

Release Preflight

package version: 18.1.1
prerelease: false
npm dist-tag on release: latest
npm pack dry-run: passed
jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Release Autotag will run final preflight and create v18.1.1. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

flyingrobots · 2026-06-25T20:54:22Z

Code Lawyer Self-Audit Finding

@codex please confirm this assessment while I apply the fix.

ID	Severity	Source	File	Lines	Issue	Mitigation
CL-001	P5 Nit	Self	`docs/topics/reference.md`	EOF / line 316	`git diff --check origin/main...HEAD` reports `new blank line at EOF`; the generated reference currently emits an extra empty final line.	Update `scripts/check-source-backed-reference.ts` so generated Markdown ends with exactly one trailing newline, regenerate `docs/topics/reference.md`, and verify `git diff --check origin/main...HEAD` plus docs/source-backed-reference lint gates.

flyingrobots · 2026-06-25T20:57:53Z

Code Lawyer Activity Summary

ID	Severity	Source	File	Commit	Outcome
CL-001	P5 Nit	Self	`docs/topics/reference.md`, `scripts/check-source-backed-reference.ts`	`28048b3c`	Fixed generated Markdown EOF whitespace; generator now emits exactly one final newline; local diff check, reference lint, docs topology, script lint/source-size, Markdown lint, and pre-push stable test gates passed.

No unresolved PR review threads remain at the time of this summary. Proceeding to merge-gate verification.

github-actions · 2026-06-25T21:03:56Z

Release Preflight

package version: 18.1.1
prerelease: false
npm dist-tag on release: latest
npm pack dry-run: passed
jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Release Autotag will run final preflight and create v18.1.1. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

docs: add source-backed reference gate

f508570

coderabbitai Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread scripts/check-source-backed-reference.ts

flyingrobots added 2 commits June 25, 2026 13:29

fix: derive CLI error reference citation

61f8adf

docs: cite exact API export lines

23e2f78

fix: trim generated reference EOF

28048b3

flyingrobots merged commit 19c2066 into main Jun 25, 2026
18 checks passed

flyingrobots deleted the docs/source-backed-reference branch June 25, 2026 21:04

flyingrobots mentioned this pull request Jun 26, 2026

Release retrospective: v18.1.2 #697

Closed

coderabbitai Bot mentioned this pull request Jun 27, 2026

Fix: make release guards consume release profile #698

Merged

This was referenced Jul 5, 2026

Move graph exports behind v19 public API boundary #726

Merged

Add openWarp timeline facade #728

Merged

Add v19 timeline intents, readings, and drafts #729

Merged

coderabbitai Bot mentioned this pull request Jul 13, 2026

Fix: anchor state-cache payloads against Git GC #732

Merged

This was referenced Jul 26, 2026

Publish v19 charts and testing surfaces #789

Merged

Enforce one generated v19 vocabulary contract #791

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add source-backed reference gate - #679

docs: add source-backed reference gate#679
flyingrobots merged 4 commits into
mainfrom
docs/source-backed-reference

flyingrobots commented Jun 25, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 25, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

flyingrobots commented Jun 25, 2026

Uh oh!

flyingrobots commented Jun 25, 2026

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

flyingrobots commented Jun 25, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Issue

Test plan

ADR checks

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Jun 25, 2026

Release Preflight

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 25, 2026

Release Preflight

Uh oh!

flyingrobots commented Jun 25, 2026

Code Lawyer Self-Audit Finding

Uh oh!

flyingrobots commented Jun 25, 2026

Code Lawyer Activity Summary

Uh oh!

github-actions Bot commented Jun 25, 2026

Release Preflight

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

flyingrobots commented Jun 25, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 25, 2026 •

edited

Loading