Skip to content

test: move docs inventory snapshot next to its test - #54

Merged
dasiths merged 1 commit into
mainfrom
refactor/docs-inventory-snapshot
Oct 1, 2026
Merged

dasiths merged 1 commit into
mainfrom
refactor/docs-inventory-snapshot

Conversation

@dasiths

@dasiths dasiths commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator

Problem

SnippetCompilationTests.Documentation_FrozenSurface saves its generated docs inventory (a SHA-256 hash for every inventoried Markdown file and code block) inside a dated plan document: .agent/plans/2026-09-11-aauth-v11-spec-migration/docs-surface-map.md. As a result:

Change

  • New: tests/AAuth.Tests/Api/DocumentationInventory.snapshot.md holds the generated inventory, with a header explaining how to regenerate it. It is three levels below the repo root, like the old file, so the generated ../../../ links still resolve. tests/ isn't inventoried, so the snapshot doesn't hash itself.
  • Test: now reads and writes the snapshot, and the stale failure names the file and the AAUTH_UPDATE_DOCS_INVENTORY=1 step.
  • Plan doc: the hand-written draft-11 analysis stays in docs-surface-map.md. Only the generated appendix was removed, and a dated update note points to the new location.

The test's behavior is unchanged: same inventory, same checks, same opt-in regeneration.

Validation

  • After regenerating, the snapshot's generated section is byte-identical to the appendix it replaces.
  • dotnet test tests/AAuth.Tests --filter "FullyQualifiedName~SnippetCompilationTests|FullyQualifiedName~DocumentationLinkTests": 108 passed.
  • Negative check: appending a blank line to docs/glossary.md makes the test fail with the new message (Documentation inventory snapshot tests/AAuth.Tests/Api/DocumentationInventory.snapshot.md is stale…).

Documentation_FrozenSurface wrote its generated inventory into the
draft-11 plan folder (.agent/plans/2026-09-11-.../docs-surface-map.md),
so every docs change had to edit a historical plan document, and a
stale-inventory failure gave no hint where the file lived.

- Move the generated inventory to
  tests/AAuth.Tests/Api/DocumentationInventory.snapshot.md, with a header
  explaining how to regenerate it. Generated content is unchanged.
- Make the stale-snapshot failure name the file and the
  AAUTH_UPDATE_DOCS_INVENTORY=1 regeneration step.
- Keep the hand-written draft-11 analysis in docs-surface-map.md and add
  a dated update callout pointing to the new location.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@dasiths
dasiths merged commit a664362 into main Oct 1, 2026
2 checks passed
@dasiths
dasiths deleted the refactor/docs-inventory-snapshot branch October 1, 2026 16:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant