Skip to content

feat: docs-kit 0.1 — check, index, move and hazard tests - #2

Merged
jisujit merged 4 commits into
mainfrom
dev
Nov 12, 2026
Merged

jisujit merged 4 commits into
mainfrom
dev

Conversation

@jisujit

@jisujit jisujit commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

Rollout step 0.1 (DESIGN §10): the layout rule, docs-kit.json, check (including how-tos by role, §4.1), index, move, and a test for every hazard guard.

What is in it

  • docs-kit check: root entries, subject READMEs, no exports/ tree, doc maps, snapshot folders and freshness (by file name), how-to staleness, print copies, archive shape, and how-tos by role. Every check that scans a set fails when the set is empty (H10). --json, --today.
  • docs-kit index: writes the "How-tos by role" section of docs/README.md from each how-to's roles: front matter. check fails when it is missing or out of date.
  • docs-kit move: moves file by file with git mv, rewrites relative Markdown links and repo-root path strings (including .gitignore, scripts, workflows), refuses protected and immutable paths, lists pieced-together paths for review, checks that moved ignored files stay ignored, ends with git status --porcelain and the layout check. --dry-run.
  • A fixture repo for an invented project (example-app) that reproduces H1 to H10, with a test per guard in test/hazards.test.mjs. Each guard was also broken on purpose to confirm its test then fails.
  • Examples: docs-kit.json, and the check wrapped as a vitest and a pytest test.

Decisions recorded

  • §4.1 details, answered in the build session: the front-matter key is roles, and the section is generated by docs-kit index and verified by check.
  • snapshotStaleDays (default 30) added to the config keys in §5.

Notes for review

  • H1's archive-helper refusal arrives with the snapshot library in 0.3; in 0.1 the check guards H1 (a snapshots/<topic>/ folder may hold only dated snapshots).
  • docs-kit print is reserved and exits 2 until 0.2.
  • Known limits are listed in the README (rename detection for small, heavily rewritten files; no \-style paths; no chained moves in one call).

Test

npm test (Node 22+, git; no dependencies).

🤖 Generated with Claude Code

jisujit and others added 4 commits November 12, 2026 09:37
- docs-kit.json loader (JSON with comments)
- check: layout rule, doc maps, snapshots, how-tos, print copies;
  every scanning check fails on an empty set (H10)
- move: file-by-file git mv, relative link and repo-root path
  rewriting, protected and immutable guards, pieced-path review list,
  ignored-file visibility check, git status report
- fixture repo reproducing H1-H10 with one test per guard
- examples: docs-kit.json, vitest and pytest wrappers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- roles list in docs-kit.json; roles: in each how-to's front matter
- docs-kit index writes the "How-tos by role" section of docs/README.md
- check fails on missing or unknown roles, and on a missing or
  out-of-date section; no how-tos with roles configured fails (H10)
- pieced-path review names a moved folder once

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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