From abc4c2d6d5674afc2c8817bb8c2d7a41f2cae06e Mon Sep 17 00:00:00 2001 From: Sujit Gangadharan Date: Fri, 13 Nov 2026 07:50:20 -0500 Subject: [PATCH] feat: /docs-kit-reorg, docs-kit audit and docs-kit snapshot; release 0.4.0 - docs-kit audit: read-only inventory before a reorganisation. - docs-kit snapshot path|archive: snapshot routing any generator can call; archive refuses other folders (H1) and fails loudly when an ignored snapshot would become visible (H4). - check: a gitignored snapshot topic is local-only, not missing. - /docs-kit-reorg: audit, one proposal with the least-change defaults, roles and one approval, then slices. /docs-kit-init hands off to it. - How-to for generators, with Python and Node snippets the tests run. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Sujit Gangadharan --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- CHANGELOG.md | 14 ++ README.md | 14 +- docs/DESIGN.md | 19 ++- docs/FAQ.md | 4 + docs/README.md | 2 +- docs/guides/README.md | 1 + docs/guides/howto/HOWTO-adopt-docs-kit.md | 6 +- .../howto/HOWTO-reorganise-a-docs-folder.md | 29 ++-- .../howto/HOWTO-route-generated-docs.md | 91 +++++++++++ docs/guides/howto/HOWTO-upgrade-docs-kit.md | 2 +- docs/reference/COMMANDS.md | 37 +++++ package.json | 2 +- scripts/docs-kit.mjs | 48 +++++- scripts/lib/audit.mjs | 141 ++++++++++++++++++ scripts/lib/check.mjs | 13 +- scripts/lib/snapshots.mjs | 105 +++++++++++++ skills/docs-kit-help/SKILL.md | 4 +- skills/docs-kit-init/SKILL.md | 8 +- skills/docs-kit-reorg/SKILL.md | 90 +++++++++++ test/audit.test.mjs | 86 +++++++++++ test/docs.test.mjs | 23 +++ test/plugin.test.mjs | 15 ++ test/snapshots.test.mjs | 96 ++++++++++++ 25 files changed, 810 insertions(+), 44 deletions(-) create mode 100644 docs/guides/howto/HOWTO-route-generated-docs.md create mode 100644 scripts/lib/audit.mjs create mode 100644 scripts/lib/snapshots.mjs create mode 100644 skills/docs-kit-reorg/SKILL.md create mode 100644 test/audit.test.mjs create mode 100644 test/snapshots.test.mjs diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8c0e754..101cda0 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ { "name": "docs-kit", "description": "One layout for docs/ in any repo: a check that keeps it, a mover that keeps every link and path working, and notes and how-tos. Help: /docs-kit-help", - "version": "0.3.1", + "version": "0.4.0", "source": "./", "author": { "name": "Techsilon LLC", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index bbed029..bfc9dd0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "docs-kit", "description": "One layout for docs/ in any repo: a check that keeps it, a mover that keeps every link and path working, and notes and how-tos. Help: /docs-kit-help", - "version": "0.3.1", + "version": "0.4.0", "author": { "name": "Techsilon LLC", "email": "oss@techsilon.com", diff --git a/CHANGELOG.md b/CHANGELOG.md index defacf2..187b113 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,20 @@ All notable changes to docs-kit. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [semver](https://semver.org/). +## [0.4.0] - 2026-11-13 + +### Added + +- `/docs-kit-reorg`: the guided reorganisation (DESIGN §6.3). It audits the docs, writes one proposal that applies the least-change defaults, asks the owner only for the roles and one approval, then moves the docs in slices, routes generators through `docs-kit snapshot`, and adds the check to the tests. +- `docs-kit audit [--json]`: a read-only inventory before a reorganisation: the docs root and its folders, exports trees, code inside the docs folder, generators, ignored files and `.gitignore` rules, docs that immutable files name, agent instructions, how-to look-alikes, and every reference to a doc from outside the docs folder. +- `docs-kit snapshot path ` and `docs-kit snapshot archive ` (DESIGN §6.6): where a generator in any language writes today's snapshot, and archiving the older ones to `archive//snapshots//`. The archive refuses any other folder (hazard H1), and fails loudly when an ignored snapshot would become visible (hazard H4). +- How-to: [Route generated docs to snapshots](docs/guides/howto/HOWTO-route-generated-docs.md), with Python and Node examples that the tests run. + +### Changed + +- `check`: a snapshot topic whose folder git ignores is reported as local-only, instead of failing as "no dated snapshots". +- `/docs-kit-init` hands the reorganisation to `/docs-kit-reorg`. + ## [0.3.1] - 2026-11-13 docs-kit now follows the [techsilon-oss kit standard](https://github.com/techsilon-oss/.github/blob/main/KIT-STANDARD.md). See [Upgrading](docs/UPGRADING.md#031). diff --git a/README.md b/README.md index a1dc927..8df9a6e 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ docs-kit gives every repo the same `docs/` layout, a check that keeps it, and a - **Every doc has one place.** The front door, `docs/README.md`, lists one folder per subject, and each folder has a map. - **A test fails when a doc is in the wrong place**, when a folder has no map, or when a file another tool reads is missing. - **You move a doc and nothing breaks.** `docs-kit move` rewrites every link and every path to it: in other docs, scripts, config, CI workflows and agent instructions. It never edits a file that must not change, such as an applied migration. +- **Generated docs land in one known place.** A report script asks `docs-kit snapshot path` where to write, gets a dated name, and archives the older copies with `docs-kit snapshot archive`, in any language. - **Readers find the steps for their own role.** How-tos name who they are for, and the front door lists them by role. - **Notes and how-tos do not get lost in chats.** In Claude Code, `/docs-kit-pin` saves a discussion or a set of steps to its place, with `.docx` and `.pdf` copies if you ask. @@ -15,8 +16,8 @@ docs-kit gives every repo the same `docs/` layout, a check that keeps it, and a From the root of your repo, in a terminal: ```sh -npx github:techsilon-oss/docs-kit#v0.3.1 init --dry-run -npx github:techsilon-oss/docs-kit#v0.3.1 init +npx github:techsilon-oss/docs-kit#v0.4.0 init --dry-run +npx github:techsilon-oss/docs-kit#v0.4.0 init npm install ``` @@ -34,13 +35,13 @@ In Claude Code, install the plugin once, then run `/docs-kit-init` in any repo: | | | |---|---| | **Reads** | The files git tracks, and `docs-kit.json` at the repo root | -| **Writes** | `init`: `docs-kit.json`, `docs/README.md` if missing, two keys in `package.json`, and the test file you name. It never overwrites a file. `move`: moves files with `git mv`, and rewrites the links and paths that name them. `index`: one marked section of `docs/README.md`. `print`: `.docx` and `.pdf` copies beside the source | +| **Writes** | `init`: `docs-kit.json`, `docs/README.md` if missing, two keys in `package.json`, and the test file you name. It never overwrites a file. `move`: moves files with `git mv`, and rewrites the links and paths that name them. `index`: one marked section of `docs/README.md`. `print`: `.docx` and `.pdf` copies beside the source. `snapshot archive`: moves older snapshots to the archive folder. `audit` and `check` write nothing | | **Runs** | `git`. `print` runs `pandoc` when it is installed | | **Network** | docs-kit makes no network calls. `npx`, `npm install` and the plugin install download docs-kit from GitHub | | **Never** | Commits, pushes, sends data anywhere, or edits a file under `immutablePrefixes`. The Claude Code skills commit only after you say yes, and never push | | **Depends on** | Node 22 or later, and git. No runtime dependencies: Node built-ins only | -**Pin a release.** `init` pins the devDependency to the tag it ran from (`github:techsilon-oss/docs-kit#v0.3.1`). Release tags never move. For a stricter pin, use the commit: `github:techsilon-oss/docs-kit#`. To vendor it instead, copy `scripts/docs-kit.mjs` and `scripts/lib/` into your repo and keep the banner and `VERSION` in `docs-kit.mjs`. +**Pin a release.** `init` pins the devDependency to the tag it ran from (`github:techsilon-oss/docs-kit#v0.4.0`). Release tags never move. For a stricter pin, use the commit: `github:techsilon-oss/docs-kit#`. To vendor it instead, copy `scripts/docs-kit.mjs` and `scripts/lib/` into your repo and keep the banner and `VERSION` in `docs-kit.mjs`. ## Uninstall @@ -53,16 +54,19 @@ In Claude Code, install the plugin once, then run `/docs-kit-init` in any repo: | `docs-kit init` | Sets up a repo in one step: a `docs-kit.json` that describes the docs as they are, the front door, a pinned devDependency, the check as a test | [Commands](docs/reference/COMMANDS.md#docs-kit-init) | | `docs-kit check` | The layout check. Exit 0 when the layout holds, 1 with a list when it does not | [Commands](docs/reference/COMMANDS.md#docs-kit-check) | | `docs-kit move` | Moves docs and keeps every link and path working | [Commands](docs/reference/COMMANDS.md#docs-kit-move) | +| `docs-kit audit` | Read-only inventory before a reorganisation: what must move, generators, ignored files, every reference to a doc | [Commands](docs/reference/COMMANDS.md#docs-kit-audit) | +| `docs-kit snapshot` | Where a generator writes today's snapshot, and archiving the older ones | [Route generated docs](docs/guides/howto/HOWTO-route-generated-docs.md) | | `docs-kit index` | Writes the "How-tos by role" section of the front door | [Commands](docs/reference/COMMANDS.md#docs-kit-index) | | `docs-kit print` | Makes `.docx` and `.pdf` print copies with pandoc | [Commands](docs/reference/COMMANDS.md#docs-kit-print) | | `/docs-kit-init` | Claude Code: applies the setup defaults, explains what the check found, commits on your yes, and leads the reorganisation | [Adopt docs-kit](docs/guides/howto/HOWTO-adopt-docs-kit.md) | +| `/docs-kit-reorg` | Claude Code: audits the docs, writes one proposal, asks only for the roles and one approval, then moves the docs in slices | [Reorganise a docs folder](docs/guides/howto/HOWTO-reorganise-a-docs-folder.md) | | `/docs-kit-pin` | Claude Code: saves a discussion as a dated note, or steps as a how-to | [DESIGN §6.4](docs/DESIGN.md#64-pins-and-how-tos--docs-kit-pin-skill) | | `/docs-kit-help` | Claude Code: answers a question from the docs of the version you have | [FAQ](docs/FAQ.md) | ## Docs - [Front door](docs/README.md): every doc, by subject. -- [How-tos](docs/guides/README.md): adopt, reorganise, print, upgrade, remove. +- [How-tos](docs/guides/README.md): adopt, reorganise, route generated docs, print, upgrade, remove. - [Commands](docs/reference/COMMANDS.md): every command, option, finding and exit code. - [FAQ](docs/FAQ.md) and [Upgrading](docs/UPGRADING.md). - [Design](docs/DESIGN.md): the layout rule, and why each part works the way it does. diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 0d192fd..f2d8e42 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -1,6 +1,6 @@ # docs-kit — design spec -> **Status:** draft 2026-10-31; owner decisions added 2026-11-12 (§11 answered, §3, §4.1, §10). Rollout step 0.1 (`docs-kit.json`, `check` with how-tos by role, `index`, `move`, hazard tests) was released as v0.1.0 on 2026-11-12; see [CHANGELOG.md](../CHANGELOG.md). Step 0.2 (`init` and the plugin with `/docs-kit-init`, §6.7) was released as v0.2.0 on 2026-11-12, and v0.2.1 (setup in two answers) the same day. Trial 1 was completed on 2026-11-13. Step 0.3 (`/docs-kit-pin`, `print`, `init` protecting what immutable files name, `move` following renamed files) is v0.3.0. v0.3.1 (2026-11-13) brings docs-kit in line with the [techsilon-oss kit standard](https://github.com/techsilon-oss/.github/blob/main/KIT-STANDARD.md): skill names with the `docs-kit-` prefix, `/docs-kit-help`, pre-approval of the plugin's own scripts only, Apache-2.0, and docs that follow the layout. Later steps are not built yet. +> **Status:** draft 2026-10-31; owner decisions added 2026-11-12 (§11 answered, §3, §4.1, §10). Rollout step 0.1 (`docs-kit.json`, `check` with how-tos by role, `index`, `move`, hazard tests) was released as v0.1.0 on 2026-11-12; see [CHANGELOG.md](../CHANGELOG.md). Step 0.2 (`init` and the plugin with `/docs-kit-init`, §6.7) was released as v0.2.0 on 2026-11-12, and v0.2.1 (setup in two answers) the same day. Trial 1 was completed on 2026-11-13. Step 0.3 (`/docs-kit-pin`, `print`, `init` protecting what immutable files name, `move` following renamed files) is v0.3.0. v0.3.1 (2026-11-13) brings docs-kit in line with the [techsilon-oss kit standard](https://github.com/techsilon-oss/.github/blob/main/KIT-STANDARD.md): skill names with the `docs-kit-` prefix, `/docs-kit-help`, pre-approval of the plugin's own scripts only, Apache-2.0, and docs that follow the layout. Step 0.4 (`/docs-kit-reorg`, `docs-kit audit`, `docs-kit snapshot`) is v0.4.0; its done-when is Trial 2. Later steps are not built yet. > **Owner:** Techsilon LLC. **Decisions in this file:** marked **Decided**. Everything else is a proposal until the owner approves it. --- @@ -146,9 +146,9 @@ For each pair (file or folder): ### 6.3 Guided reorganisation — `/docs-kit-reorg` (skill) -For a repo that does not follow the rule. Never moves anything before the owner approves the proposal. +For a repo that does not follow the rule. Never moves anything before the owner approves the proposal. **Built in 0.4** as `/docs-kit-reorg`, with `docs-kit audit` for step 1. -1. **Audit** (read-only): inventory every file under `docs/` and every doc path referenced outside it; group by likely subject; find generators, gitignore rules, path-based keys and pieced-together paths (the hazard list is the checklist). +1. **Audit** (read-only, `docs-kit audit`): inventory every file under `docs/` and every doc path referenced outside it; group by likely subject; find generators, gitignore rules, path-based keys and pieced-together paths (the hazard list is the checklist). 2. **Proposal:** the subject list, the old → new table, the protected paths with reasons, the hazards found, and the slices. Written as a pin (`docs/notes/`) so it survives the session. It applies the least-change defaults below and lists each one it applied, so the owner can override any of them. 3. **Owner approves** the whole proposal once. The only question asked before that is the `roles` list, when the repo will have how-tos. Each slice's pull request is then merged by the owner as usual; a slice raises a new question only when the check, the tests or `move` show something the proposal did not foresee. 4. **Slices:** one pull request per slice (for example: front door and READMEs; one subject per slice; generators last). Each slice: `move --dry-run`, `move`, run the project's tests and `check`, stage everything changed, confirm a clean working tree, open the PR. @@ -194,11 +194,14 @@ Makes `.docx` and `.pdf` beside the source with the naming rule, and removes the For projects that generate docs: -- `snapshotDir(topic)` returns `docs//snapshots//` from `snapshotTopics`. **An unknown topic is an error**, never a default folder. +**Built in 0.4** as `scripts/lib/snapshots.mjs` and the `docs-kit snapshot` command, so a generator in any language uses it: `docs-kit snapshot path ` prints where today's snapshot goes, and `docs-kit snapshot archive ` archives the older ones. A Python port is not needed. + +- `topicDir(topic)` returns `docs//snapshots//` from `snapshotTopics`. **An unknown topic is an error**, never a default folder. - `archiveOlder(dir, keep)` moves older snapshots to `archive//snapshots//`. **It refuses any folder that is not a `snapshots//` folder** (hazard H1). -- File names carry the date: `_.md`. +- File names carry the date: `_.`. +- **Gitignored topics.** A generator may keep its snapshots out of git, made on demand. When git ignores a topic's folder, `check` reports the topic as local-only instead of failing H10, and `archive` fails loudly (exit 1) when it moves an ignored file to a place git does not ignore (H4). -Node first. A Python port is a later option, only if a trial project needs it. +Node only. Trial 2's generator is Python; it calls the command instead of a port. ### 6.7 Setup — `docs-kit init` and `/docs-kit-init` @@ -251,8 +254,8 @@ Each hazard below happened, or nearly happened, during a real reorganisation: H1 ## 8. Distribution -- **Plugin:** the skills (`/docs-kit-init`, `/docs-kit-pin` and `/docs-kit-help`, then `/docs-kit-reorg`) as a Claude Code plugin from this repo, which is also its marketplace (`.claude-plugin/`). The skills run the plugin's own copy of `scripts/docs-kit.mjs`. -- **Scripts:** `scripts/docs-kit.mjs` with subcommands `init`, `check`, `index`, `move`, `print`, plus `lib/snapshots.mjs`. Usable through `npx` from this repo, as a devDependency pinned to a tag, or vendored. +- **Plugin:** the skills (`/docs-kit-init`, `/docs-kit-reorg`, `/docs-kit-pin` and `/docs-kit-help`) as a Claude Code plugin from this repo, which is also its marketplace (`.claude-plugin/`). The skills run the plugin's own copy of `scripts/docs-kit.mjs`. +- **Scripts:** `scripts/docs-kit.mjs` with subcommands `init`, `check`, `audit`, `index`, `move`, `print` and `snapshot` (`lib/snapshots.mjs`). Usable through `npx` from this repo, as a devDependency pinned to a tag, or vendored. - **Versioning:** semver and a `CHANGELOG.md`. A vendored copy records its version. Release tags never move (a tag ruleset blocks it). - **License:** Apache License 2.0 with a `NOTICE`, from 0.3.1. Earlier releases stay MIT. - **The kit standard:** docs-kit follows the [techsilon-oss kit standard](https://github.com/techsilon-oss/.github/blob/main/KIT-STANDARD.md). Tests enforce its plugin rules (skill prefix, `allowed-tools`, help skill, license) and its documentation rules for docs-kit's own docs (the layout, the commands they show, the version they pin, their links). diff --git a/docs/FAQ.md b/docs/FAQ.md index 25b28ac..bdc5fc0 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -22,6 +22,10 @@ Because the check fails. A failing test would block every commit while you reorg A file that `move` never edits, such as an applied migration, names that doc by its path. Moving the doc would leave that file pointing at nothing, for good. If the reason no longer holds, remove the path from `protected`. See [DESIGN §6.3, default L3](DESIGN.md#63-guided-reorganisation--docs-kit-reorg-skill). +## Our generated docs are gitignored. Does the check fail on them? + +No. If git ignores a snapshot topic's folder, the check reports the topic as local-only, and does not ask for its snapshots. Keep the archive folder ignored too. See [Route generated docs to snapshots](guides/howto/HOWTO-route-generated-docs.md). + ## Can a release change after I pin it? No. Release tags never move: a bad release is fixed by a new release. For a stricter pin, use a commit instead of a tag. See [What it does on your machine](../README.md#what-it-does-on-your-machine). diff --git a/docs/README.md b/docs/README.md index 6432ce2..0adbec1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ Where to find things. Each subject folder has a `README.md` that maps it. -- [guides](guides/README.md): how-tos to adopt, reorganise, print, upgrade and remove docs-kit. +- [guides](guides/README.md): how-tos to adopt, reorganise, route generated docs, print, upgrade and remove docs-kit. - [reference](reference/README.md): every command, option, finding and exit code. At the docs root: diff --git a/docs/guides/README.md b/docs/guides/README.md index c373033..4ae1dd2 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -4,6 +4,7 @@ Step-by-step how-tos. Each one does one task, and says when its steps were last - [Adopt docs-kit in a repo](howto/HOWTO-adopt-docs-kit.md) - [Reorganise a docs folder](howto/HOWTO-reorganise-a-docs-folder.md) +- [Route generated docs to snapshots](howto/HOWTO-route-generated-docs.md) - [Print a doc as .docx and .pdf](howto/HOWTO-print-a-doc.md) - [Upgrade docs-kit](howto/HOWTO-upgrade-docs-kit.md) - [Remove docs-kit](howto/HOWTO-remove-docs-kit.md) diff --git a/docs/guides/howto/HOWTO-adopt-docs-kit.md b/docs/guides/howto/HOWTO-adopt-docs-kit.md index 6aa9640..bc5d757 100644 --- a/docs/guides/howto/HOWTO-adopt-docs-kit.md +++ b/docs/guides/howto/HOWTO-adopt-docs-kit.md @@ -30,13 +30,13 @@ Use the terminal you normally use for git, in the root folder of your repo. 1. See what `init` would write. It writes nothing: ```sh - npx github:techsilon-oss/docs-kit#v0.3.1 init --dry-run + npx github:techsilon-oss/docs-kit#v0.4.0 init --dry-run ``` 2. Set it up: ```sh - npx github:techsilon-oss/docs-kit#v0.3.1 init + npx github:techsilon-oss/docs-kit#v0.4.0 init ``` 3. If your repo has a `package.json`, fetch the devDependency that `init` added: @@ -49,7 +49,7 @@ Use the terminal you normally use for git, in the root folder of your repo. 5. Add to `docs-kit.json` what only you know: other `protected` paths (a doc path that a database, a URL or code uses as a key), each with its reason. 6. Commit the files `init` listed. -If your repo must not get a new dependency, add `--no-package` in step 2. Then run the check with `npx github:techsilon-oss/docs-kit#v0.3.1 check`. +If your repo must not get a new dependency, add `--no-package` in step 2. Then run the check with `npx github:techsilon-oss/docs-kit#v0.4.0 check`. ## Check diff --git a/docs/guides/howto/HOWTO-reorganise-a-docs-folder.md b/docs/guides/howto/HOWTO-reorganise-a-docs-folder.md index 4f12912..44ba563 100644 --- a/docs/guides/howto/HOWTO-reorganise-a-docs-folder.md +++ b/docs/guides/howto/HOWTO-reorganise-a-docs-folder.md @@ -13,6 +13,8 @@ last_checked: 2026-11-13 - A clean working tree (`git status` shows nothing). - A branch for this work, if your project's rules say so. +In Claude Code, `/docs-kit-reorg` does every step below with you: it runs the audit, writes the plan, asks you for the roles and one approval, and then moves the docs in slices. In a terminal, follow the steps yourself. + The least-change defaults ([DESIGN §6.3](../../DESIGN.md#63-guided-reorganisation--docs-kit-reorg-skill)) settle most choices: keep folder names and file names, protect what immutable files name, never edit historical folders. You decide the roles and approve the plan once. ## Steps @@ -23,26 +25,33 @@ The least-change defaults ([DESIGN §6.3](../../DESIGN.md#63-guided-reorganisati npm run docs:check ``` -2. Write the plan as a note in `docs/notes/`: the subjects, an old → new path for each file, the protected paths, the roles, and the slices. In Claude Code, `/docs-kit-init` writes this note for you after the read-only audit. -3. Add the note to `immutablePrefixes` in `docs-kit.json`, in the same commit. The note records the old paths, and `move` must not rewrite it. -4. Approve the plan. Nothing moves before that. -5. Slice 1: write a `README.md` map in each subject folder that has none. Move nothing. Commit. -6. Slice 2: see what the moves would change. It writes nothing: +2. List what is in the docs folder, and every place outside it that names a doc. It writes nothing: + + ```sh + npx docs-kit audit + ``` + +3. Write the plan as a note in `docs/notes/`: the subjects, an old → new path for each file, the protected paths, the roles, and the slices. In Claude Code, `/docs-kit-init` writes this note for you after the read-only audit. +4. Add the note to `immutablePrefixes` in `docs-kit.json`, in the same commit. The note records the old paths, and `move` must not rewrite it. +5. Approve the plan. Nothing moves before that. +6. Slice 1: write a `README.md` map in each subject folder that has none. Move nothing. Commit. +7. Slice 2: see what the moves would change. It writes nothing: ```sh npx docs-kit move docs/OLD.md docs/subject/OLD.md --dry-run # example: use your own paths ``` -7. If the dry run lists a file you did not expect, stop and find out why before you go on. -8. Make the moves. Name every pair in one command: +8. If the dry run lists a file you did not expect, stop and find out why before you go on. +9. Make the moves. Name every pair in one command: ```sh npx docs-kit move docs/OLD.md docs/subject/OLD.md # example: use your own paths ``` -9. Run your project's tests and `npm run docs:check`. -10. Stage every file that `git status` lists, not only the docs folders. Commit. -11. If the check passes, add it to your tests: +10. Run your project's tests and `npm run docs:check`. +11. Stage every file that `git status` lists, not only the docs folders. Commit. +12. If a script writes docs, route it through `docs-kit snapshot`: see [Route generated docs to snapshots](HOWTO-route-generated-docs.md). +13. If the check passes, add it to your tests: ```sh npx docs-kit init --test tests/docs-layout.test.mjs diff --git a/docs/guides/howto/HOWTO-route-generated-docs.md b/docs/guides/howto/HOWTO-route-generated-docs.md new file mode 100644 index 0000000..73cda75 --- /dev/null +++ b/docs/guides/howto/HOWTO-route-generated-docs.md @@ -0,0 +1,91 @@ +--- +title: Route generated docs to snapshots +last_checked: 2026-11-13 +--- + +# How to route generated docs to snapshots + +**Purpose:** make a script that writes docs (a status report, an export, a briefing) put each one in its snapshot folder with a dated name, and archive the older ones. + +## Before you start + +- docs-kit is set up in the repo, as a devDependency: see [Adopt docs-kit](HOWTO-adopt-docs-kit.md). +- You know the topics your script writes, for example `status` and `briefing`, and the subject each belongs to, for example `operations`. + +## Steps + +1. In `docs-kit.json`, add one entry per topic to `snapshotTopics`, from the topic to its subject: + + ```json + "snapshotTopics": { "status": "operations", "briefing": "operations" } + ``` + +2. If the script's code is inside the docs folder (for example `docs/exports/_scripts/`), move it out. A docs folder holds docs. Use `docs-kit move`, so every path to it follows: + + ```sh + npx docs-kit move docs/exports/_scripts scripts/docs-gen --dry-run # example: use your own paths + npx docs-kit move docs/exports/_scripts scripts/docs-gen # example: use your own paths + ``` + +3. In the script, ask docs-kit where to write, instead of building the path yourself. In Python: + + ```python + import subprocess + + def snapshot_path(topic: str, ext: str = "md") -> str: + """Where today's snapshot of a topic goes, from docs-kit.json.""" + out = subprocess.run( + ["node", "node_modules/docs-kit/scripts/docs-kit.mjs", "snapshot", "path", topic, "--ext", ext], + capture_output=True, text=True, check=True, + ) + return out.stdout.strip() + ``` + + In Node: + + ```js + import { execFileSync } from 'node:child_process'; + + const snapshotPath = (topic, ext = 'md') => execFileSync( + process.execPath, ['node_modules/docs-kit/scripts/docs-kit.mjs', 'snapshot', 'path', topic, '--ext', ext], + { encoding: 'utf8' }, + ).trim(); + ``` + + Run it from the repo root. The script still creates the folder (`os.makedirs`, `mkdirSync`) and writes the file. + +4. After the script writes a topic, archive the older snapshots of that topic. Remove the script's own archive step: + + ```sh + npx docs-kit snapshot archive status # example: use your own topic + ``` + +5. If your snapshots are not committed, keep them gitignored in the new place. Add a rule for the topic folder and one for its archive folder, for example: + + ```text + docs/operations/snapshots/status/ + docs/archive/operations/snapshots/status/ + ``` + +6. Run the script once. Then run the check: + + ```sh + npm run docs:check + ``` + +## Check + +- The new file is at the path `docs-kit snapshot path ` prints, and its name is `_.`. +- `npm run docs:check` passes. A gitignored topic shows under **Not checked … local-only**. + +## If it fails + +- **`unknown snapshot topic`:** add the topic to `snapshotTopics` (step 1). +- **`not a dated snapshot`:** a file in a `snapshots//` folder does not have a dated name. Only the script's own snapshots belong there. +- **`DANGER: … no longer ignored in the archive`:** add the archive rule from step 5, before you stage anything. +- **`refusing to archive`:** the folder is not a configured `snapshots//` folder. Archive by topic, as in step 4. + +## Sources + +- [Commands: `docs-kit snapshot`](../../reference/COMMANDS.md#docs-kit-snapshot) +- [DESIGN §6.6: Snapshot routing](../../DESIGN.md#66-snapshot-routing--a-small-library) diff --git a/docs/guides/howto/HOWTO-upgrade-docs-kit.md b/docs/guides/howto/HOWTO-upgrade-docs-kit.md index af0975a..ba84ab9 100644 --- a/docs/guides/howto/HOWTO-upgrade-docs-kit.md +++ b/docs/guides/howto/HOWTO-upgrade-docs-kit.md @@ -14,7 +14,7 @@ last_checked: 2026-11-13 ## Steps for a repo -1. In `package.json`, change the devDependency to the new tag, for example `github:techsilon-oss/docs-kit#v0.3.1`. +1. In `package.json`, change the devDependency to the new tag, for example `github:techsilon-oss/docs-kit#v0.4.0`. 2. In a terminal, in the root folder of your repo, run `npm install`. 3. Run the check: diff --git a/docs/reference/COMMANDS.md b/docs/reference/COMMANDS.md index 3d49779..7ce1ac1 100644 --- a/docs/reference/COMMANDS.md +++ b/docs/reference/COMMANDS.md @@ -6,9 +6,11 @@ How to run `docs-kit`: `npm run docs:check` and `npx docs-kit ` once it - [`docs-kit init`](#docs-kit-init) - [`docs-kit check`](#docs-kit-check) +- [`docs-kit audit`](#docs-kit-audit) - [`docs-kit index`](#docs-kit-index) - [`docs-kit move`](#docs-kit-move) - [`docs-kit print`](#docs-kit-print) +- [`docs-kit snapshot`](#docs-kit-snapshot) - [Hazards](#hazards) ## `docs-kit init` @@ -62,6 +64,26 @@ Options: `--json` for machine-readable output, `--today YYYY-MM-DD` to fix the d To run it in your tests, see [examples/vitest](../../examples/vitest/docs-layout.test.mjs) and [examples/pytest](../../examples/pytest/test_docs_layout.py). +## `docs-kit audit` + +```text +docs-kit audit [--json] +``` + +The read-only inventory a reorganisation starts from (DESIGN §6.3, step 1). It changes nothing. It works before `init` too, with the default settings. + +| It lists | Why | +|---|---| +| The docs root: the files the layout allows, the files that must move, each folder with its size, whether it is a subject, and whether it has a map | The work the reorganisation has to do | +| `exports/` trees, code inside the docs folder, and code outside it that names a doc and writes files | Generated docs, and the generators that make them | +| Files git ignores under the docs folder, by folder, and the `.gitignore` rules that name it | Generated or confidential files that must stay ignored (hazard H4) | +| Docs that immutable files name, and the protected paths | What must not move (default L3, hazard H2) | +| Agent instructions that name a doc | Starting points that stay in place (default L5) | +| Docs whose name looks like a how-to, outside a `howto/` folder | How-to candidates (default L6) | +| Every doc that a file outside the docs folder names by its repo-root path, with those files | What `move` will rewrite | + +`--json` prints the same report as JSON. Exit 0; 2 outside a git repository. + ## `docs-kit index` ```text @@ -122,6 +144,21 @@ Makes `.docx` and `.pdf` print copies beside the source, named `_v_ [--date YYYY-MM-DD] [--ext md] +docs-kit snapshot archive [--keep N] [--dry-run] +``` + +Routes generated docs (DESIGN §6.6). A generator in any language calls these, so every generator follows one rule: `//snapshots//_.`. The topics and their subjects are in `snapshotTopics` in `docs-kit.json`. + +- **`path`** prints where today's snapshot of a topic goes, for example `docs/operations/snapshots/status/STATUS_2026-11-13.md`. `--date` sets the date, `--ext` the file extension. It writes nothing; the generator creates the folder and the file. An unknown topic is an error, never a default folder. +- **`archive`** keeps the snapshots of the newest date (`--keep N` keeps the newest N dates) and moves the older ones to `/archive//snapshots//`. A tracked file moves with `git mv`. It leaves alone a file that is not a dated snapshot, and refuses any folder that is not a configured `snapshots//` folder (hazard H1). +- **Gitignored snapshots.** If git ignores the topic folder, its snapshots are made on demand and never committed. `check` then reports the topic as local-only instead of "no dated snapshots". When `archive` moves an ignored file to a place git does not ignore, it says `DANGER` and exits 1: add a `.gitignore` rule for the archive folder before you stage anything (hazard H4). + +Exit 0 when done; 1 when an ignored file is no longer ignored; 2 for an unknown topic, a refused folder or wrong arguments (nothing moved). + ## Hazards The tools guard against the hazards found in real reorganisations ([DESIGN §7](../DESIGN.md#7-hazards-found-in-a-real-reorganisation)). Each guard has a test in [test/hazards.test.mjs](../../test/hazards.test.mjs) that reproduces the hazard on a fixture repo. diff --git a/package.json b/package.json index ee95f7f..15d9449 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "docs-kit", - "version": "0.3.1", + "version": "0.4.0", "description": "One layout for docs/ in any repo: a check that keeps it, and a mover that keeps every link and path working.", "license": "Apache-2.0", "author": "Techsilon LLC ", diff --git a/scripts/docs-kit.mjs b/scripts/docs-kit.mjs index 2ef6fb6..2cde47e 100644 --- a/scripts/docs-kit.mjs +++ b/scripts/docs-kit.mjs @@ -12,9 +12,11 @@ import { InitError, formatInit, nextSteps, runInit } from './lib/init.mjs'; import { repoRootOf } from './lib/git.mjs'; import { MoveError, formatMove, move } from './lib/move.mjs'; import { PrintError, findPandoc, formatPrint, print } from './lib/print.mjs'; +import { audit, formatAudit } from './lib/audit.mjs'; +import { SnapshotError, archiveOlder, formatArchive, snapshotPath, topicDir } from './lib/snapshots.mjs'; import { writeIndex } from './lib/roles.mjs'; -export const VERSION = '0.3.1'; +export const VERSION = '0.4.0'; const USAGE = `docs-kit ${VERSION} @@ -22,8 +24,13 @@ Usage: docs-kit init [--dry-run] [--docs-root ] [--test ] [--no-package] set up this repo: docs-kit.json and more docs-kit check [--json] [--today YYYY-MM-DD] + docs-kit audit [--json] read-only inventory before a reorganisation docs-kit move [ ...] [--dry-run] docs-kit index write "How-tos by role" in docs/README.md + docs-kit snapshot path [--date YYYY-MM-DD] [--ext md] + where a generator writes today's snapshot + docs-kit snapshot archive [--keep N] [--dry-run] + move older snapshots to the archive docs-kit print [--version X.Y] [--today YYYY-MM-DD] .docx and .pdf print copies beside the source (pandoc) docs-kit --version | --help @@ -143,6 +150,41 @@ export function main(argv, { cwd = process.cwd(), out = console.log, err = conso return 0; } + if (cmd === 'audit') { + const json = takeFlag(args, '--json'); + if (args.length) throw new UsageError(`unexpected argument "${args[0]}"`); + if (!repoRootOf(cwd)) throw new UsageError('audit must run inside a git repository'); + const loaded = loadConfig(root); + const cfg = loaded ? { ...loaded, configured: true } : { ...DEFAULTS, configured: false }; + const report = audit(root, cfg); + out(json ? JSON.stringify(report, null, 2) : formatAudit(report)); + return 0; + } + + if (cmd === 'snapshot') { + const sub = args.shift(); + if (!['path', 'archive'].includes(sub)) throw new UsageError('snapshot needs "path" or "archive"'); + const cfg = loadConfig(root); + if (!cfg) throw new ConfigError(`${CONFIG_FILE} not found at the repo root (${root}); snapshot topics are configured there`); + if (sub === 'path') { + const date = takeValue(args, '--date'); + const ext = takeValue(args, '--ext'); + if (args.length !== 1) throw new UsageError('snapshot path needs one '); + const day = date ?? new Date().toISOString().slice(0, 10); + if (date !== undefined && parseDate(date) === null) throw new UsageError(`--date: "${date}" is not a YYYY-MM-DD date`); + out(snapshotPath(cfg, args[0], { date: day, ext: ext ?? 'md' })); + return 0; + } + const keepArg = takeValue(args, '--keep'); + const dryRun = takeFlag(args, '--dry-run'); + if (args.length !== 1) throw new UsageError('snapshot archive needs one '); + if (!repoRootOf(cwd)) throw new UsageError('snapshot archive must run inside a git repository'); + const keep = keepArg === undefined ? 1 : Number(keepArg); + const report = archiveOlder(root, cfg, topicDir(cfg, args[0]), { keep, dryRun }); + out(formatArchive(report)); + return report.newlyVisible.length ? 1 : 0; + } + if (cmd === 'print') { const version = takeValue(args, '--version'); const todayArg = takeValue(args, '--today'); @@ -176,6 +218,10 @@ export function main(argv, { cwd = process.cwd(), out = console.log, err = conso err(`docs-kit init: ${e.message}${e.partial ? '' : '\nNothing was written.'}`); return 2; } + if (e instanceof SnapshotError) { + err(`docs-kit snapshot: ${e.message}\nNothing was moved.`); + return 2; + } if (e instanceof PrintError) { err(`docs-kit print: ${e.message} Nothing was printed.`); diff --git a/scripts/lib/audit.mjs b/scripts/lib/audit.mjs new file mode 100644 index 0000000..c2410e4 --- /dev/null +++ b/scripts/lib/audit.mjs @@ -0,0 +1,141 @@ +// docs-kit — the read-only audit a reorganisation starts from (DESIGN §6.3 step 1). +// It lists what is in the docs folder, every place outside it that names a doc, +// and each hazard of DESIGN §7 it can find. It changes nothing. +import { readFileSync, statSync } from 'node:fs'; +import { join, posix } from 'node:path'; +import { listDocFiles } from './check.mjs'; +import { ignoredFiles, trackedFiles } from './git.mjs'; +import { protectNamedDocs } from './init.mjs'; + +const MAX_TEXT_BYTES = 8 * 1024 * 1024; +const CODE = /\.(py|js|mjs|cjs|ts|mts|cts|sh|ps1|rb|go|java|cs)$/i; +const AGENT_FILES = /(^|\/)(CLAUDE\.md|AGENTS\.md|GEMINI\.md|\.cursorrules|\.windsurfrules|copilot-instructions\.md)$/; +const WRITES = /\b(writeFile(Sync)?|write_text|write_bytes|mkdirSync|makedirs|createWriteStream|open\([^)]*['"][wa]b?['"])/; +const HOWTO_LIKE = /(^|\/)(RUNBOOK|HOWTO|HOW-TO|GUIDE|PLAYBOOK)[-_A-Za-z0-9]*\.md$|-(guide|runbook|how-?to)\.md$/i; +// Tests write fixtures; they are not generators. +const TEST = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[a-z]+$/i; +const HISTORICAL = /^(archive|archives|history|historical|status|old|legacy|deprecated|retired|past)$/i; +const escapeRe = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); + +function readText(root, f) { + let buf; + try { + const st = statSync(join(root, f)); + if (!st.isFile() || st.size > MAX_TEXT_BYTES) return null; + buf = readFileSync(join(root, f)); + } catch { return null; } + return buf.subarray(0, 8000).includes(0) ? null : buf.toString('utf8'); +} + +/** The inventory. `cfg` is docs-kit.json when there is one, else the defaults. */ +export function audit(root, cfg) { + const D = cfg.docsRoot; + const docFiles = listDocFiles(root, D); + const docSet = new Set(docFiles); + const rel = docFiles.map((f) => f.slice(D.length + 1)); + + // The docs root: which entries the layout allows, and each folder's size and map. + const rootFiles = rel.filter((r) => !r.includes('/')); + const folders = [...new Set(rel.filter((r) => r.includes('/')).map((r) => r.split('/')[0]))].sort().map((name) => ({ + name, + files: rel.filter((r) => r.startsWith(`${name}/`)).length, + subject: cfg.subjects.includes(name), + hasMap: docSet.has(`${D}/${name}/README.md`), + historical: HISTORICAL.test(name), + })); + const root_ = { + allowed: rootFiles.filter((f) => cfg.rootAllowed.includes(f)), + notAllowed: rootFiles.filter((f) => !cfg.rootAllowed.includes(f)), + folders, + }; + + // Every tracked file outside the docs root that names a doc by its repo-root path. + const pathRe = new RegExp(`(? d.startsWith(`${p.replace(/\/$/, '')}/`)) ? p.replace(/\/$/, '') + '/' : null; + if (!doc) continue; + hit = true; + if (!named.has(doc)) named.set(doc, new Set()); + named.get(doc).add(f); + } + if (hit && AGENT_FILES.test(f)) agentFiles.push(f); + if (hit && CODE.test(f) && !TEST.test(f) && WRITES.test(text)) generators.push(f); + } + const references = [...named.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([doc, by]) => ({ doc, files: [...by].sort() })); + + // .gitignore rules that name the docs root (hazard H4). + const gitignoreRules = []; + for (const f of trackedFiles(root).filter((x) => posix.basename(x) === '.gitignore')) { + (readText(root, f) || '').split(/\r?\n/).forEach((line, i) => { + if (line.trim() && !line.trim().startsWith('#') && line.includes(`${D}/`)) gitignoreRules.push({ file: f, line: i + 1, rule: line.trim() }); + }); + } + + // Files git ignores under the docs root: generated or confidential (hazard H4). + const ignored = ignoredFiles(root, [D]).filter((f) => !/(^|\/)__pycache__\/|\.pyc$/.test(f)); + const ignoredByFolder = {}; + for (const f of ignored) { + const dir = posix.dirname(f); + ignoredByFolder[dir] = (ignoredByFolder[dir] || 0) + 1; + } + + const report = { + docsRoot: D, + configured: !!cfg.configured, + docs: docFiles.length, + root: root_, + exportsTrees: [...new Set(rel.map((r) => r.split('/')).filter((p) => p.includes('exports')).map((p) => `${D}/${p.slice(0, p.indexOf('exports') + 1).join('/')}/`))].sort(), + codeInDocs: trackedFiles(root, [D]).filter((f) => CODE.test(f)).sort(), + generators: generators.sort(), + gitignoreRules, + ignoredUnderDocs: Object.entries(ignoredByFolder).sort().map(([dir, n]) => ({ dir, files: n })), + namedByImmutable: protectNamedDocs(root, D, cfg.immutablePrefixes, docFiles), + protected: cfg.protected, + references, + agentFiles: agentFiles.sort(), + howtoCandidates: rel.filter((r) => HOWTO_LIKE.test(r) && !r.includes('/howto/')).map((r) => `${D}/${r}`).sort(), + }; + return report; +} + +export function formatAudit(a) { + const L = []; + const D = a.docsRoot; + L.push(`docs-kit audit: ${a.docs} files under ${D}/. Read-only: nothing was changed.`); + L.push('', `Docs root (${D}/):`); + L.push(` ${a.root.allowed.length} file(s) the layout allows: ${a.root.allowed.join(', ') || 'none'}`); + L.push(` ${a.root.notAllowed.length} file(s) that must move into a subject${a.root.notAllowed.length ? ':' : ''}`); + for (const f of a.root.notAllowed) L.push(` ${D}/${f}`); + L.push(` ${a.root.folders.length} folder(s):`); + for (const f of a.root.folders) { + const tags = [f.subject ? 'subject' : 'NOT a subject', f.hasMap ? 'has a map' : 'NO README.md map', ...(f.historical ? ['name suggests history: check the project rules (L4)'] : [])]; + L.push(` ${f.name}/ ${f.files} file(s); ${tags.join('; ')}`); + } + const section = (title, items, line) => { + L.push('', `${title}${items.length ? ':' : ': none'}`); + for (const x of items) L.push(` ${line(x)}`); + }; + section(`exports/ trees (generated docs go to /snapshots//)`, a.exportsTrees, (x) => x); + section(`Code inside ${D}/ (move it out, for example to scripts/)`, a.codeInDocs, (x) => x); + section(`Code outside ${D}/ that names a doc and writes files (a generator? route it with docs-kit snapshot)`, a.generators, (x) => x); + section(`Files git ignores under ${D}/, by folder (generated or confidential: hazard H4)`, a.ignoredUnderDocs, (x) => `${x.dir}/ ${x.files} file(s)`); + section(`.gitignore rules that name ${D}/ (move rewrites them; check they still match: H4)`, a.gitignoreRules, (x) => `${x.file}:${x.line}: ${x.rule}`); + section('Docs that immutable files name (protect them: L3)', Object.entries(a.namedByImmutable), ([p, why]) => `${p} (${why})`); + section('Protected in docs-kit.json', Object.entries(a.protected), ([p, why]) => `${p} (${why})`); + section('Agent instructions that name a doc (move rewrites the paths; L5: keep their starting points in place)', a.agentFiles, (x) => x); + section('Docs whose name looks like a how-to, outside a howto/ folder (L6: only a doc that is one task in steps becomes a how-to)', a.howtoCandidates, (x) => x); + L.push('', `Docs named by a repo-root path outside ${D}/${a.references.length ? ` (${a.references.length}); move rewrites these:` : ': none'}`); + for (const r of a.references) L.push(` ${r.doc} <- ${r.files.length > 4 ? `${r.files.slice(0, 4).join(', ')} and ${r.files.length - 4} more` : r.files.join(', ')}`); + if (!a.configured) L.push('', `No docs-kit.json: the audit used the defaults. Run docs-kit init first.`); + return L.join('\n'); +} diff --git a/scripts/lib/check.mjs b/scripts/lib/check.mjs index dd2b71d..cc0718b 100644 --- a/scripts/lib/check.mjs +++ b/scripts/lib/check.mjs @@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'; import { join, posix } from 'node:path'; import { frontMatter } from './frontmatter.mjs'; -import { repoRootOf, trackedFiles, untrackedFiles } from './git.mjs'; +import { checkIgnored, repoRootOf, trackedFiles, untrackedFiles } from './git.mjs'; import { checkRoles } from './roles.mjs'; export const SNAPSHOT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*_(\d{4}-\d{2}-\d{2})\.[A-Za-z0-9]+$/; @@ -66,7 +66,7 @@ export function check(root, cfg, { today = new Date() } = {}) { const warnings = []; const todayMs = Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate()); const D = cfg.docsRoot; - const stats = { docs: 0, docMapEntries: 0, snapshots: 0, howtos: 0 }; + const stats = { docs: 0, docMapEntries: 0, snapshots: 0, howtos: 0, localOnlyTopics: [] }; if (!existsSync(join(root, D)) || !statSync(join(root, D)).isDirectory()) { errors.push(`docs root "${D}/" does not exist`); @@ -203,6 +203,13 @@ export function check(root, cfg, { today = new Date() } = {}) { } for (const [topic, subject] of Object.entries(cfg.snapshotTopics)) { const key = `${subject}/snapshots/${topic}`; + // A topic whose folder git ignores is made on demand and never committed: CI cannot see its + // snapshots, so it is reported as local-only instead of failing H10. + const probe = `${D}/${key}/PROBE_2000-01-01.md`; + if (repoRootOf(root) && checkIgnored(root, [probe]).has(probe)) { + stats.localOnlyTopics.push(topic); + continue; + } if (!snapshotGroups.has(key)) { // H10: a configured snapshot topic with no snapshots means a path changed or the generator stopped. errors.push(`${D}/${key}/: snapshot topic "${topic}" is configured but has no dated snapshots`); @@ -271,7 +278,7 @@ export function formatCheck(result, D = 'docs') { const s = result.stats; lines.push( result.ok - ? `docs-kit check: OK (${s.docs} files under ${D}/, ${s.docMapEntries} doc-map entries, ${s.snapshots} snapshots, ${s.howtos} how-tos; ${result.warnings.length} warning(s))` + ? `docs-kit check: OK (${s.docs} files under ${D}/, ${s.docMapEntries} doc-map entries, ${s.snapshots} snapshots, ${s.howtos} how-tos; ${result.warnings.length} warning(s))${s.localOnlyTopics?.length ? `\nNot checked: ${s.localOnlyTopics.length} snapshot topic(s) whose folder git ignores (made on demand, never committed): ${s.localOnlyTopics.join(', ')}` : ''}` : `docs-kit check: FAILED with ${result.errors.length} error(s), ${result.warnings.length} warning(s)`, ); return lines.join('\n'); diff --git a/scripts/lib/snapshots.mjs b/scripts/lib/snapshots.mjs new file mode 100644 index 0000000..7f76521 --- /dev/null +++ b/scripts/lib/snapshots.mjs @@ -0,0 +1,105 @@ +// docs-kit — snapshot routing (DESIGN §6.6). A generator asks where a new +// snapshot goes, and archives the older ones, through these functions or the +// `docs-kit snapshot` command, so every generator follows one rule: +// //snapshots//_. +import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from 'node:fs'; +import { join, posix } from 'node:path'; +import { SNAPSHOT_NAME } from './check.mjs'; +import { checkIgnored, gitMv, trackedFiles } from './git.mjs'; + +export class SnapshotError extends Error {} + +const TOPIC = /^[a-z0-9][a-z0-9-]*$/; + +/** The folder of a configured topic. An unknown topic is an error, never a default folder. */ +export function topicDir(cfg, topic) { + if (!TOPIC.test(topic || '')) throw new SnapshotError(`"${topic}": a topic is lower case letters, digits and hyphens, for example "launch-readiness"`); + const subject = cfg.snapshotTopics[topic]; + if (!subject) { + const known = Object.keys(cfg.snapshotTopics); + throw new SnapshotError(`unknown snapshot topic "${topic}"; add it to "snapshotTopics" in docs-kit.json (${known.length ? `known: ${known.join(', ')}` : 'none configured yet'})`); + } + return `${cfg.docsRoot}/${subject}/snapshots/${topic}`; +} + +/** _. */ +export function snapshotName(topic, date, ext = 'md') { + if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new SnapshotError(`--date: "${date}" is not a YYYY-MM-DD date`); + if (!/^[A-Za-z0-9]+$/.test(ext)) throw new SnapshotError(`--ext: "${ext}" is not a file extension, for example md or pdf`); + return `${topic.toUpperCase()}_${date}.${ext}`; +} + +/** Where today's snapshot of a topic goes, repo-root relative. */ +export function snapshotPath(cfg, topic, { date, ext = 'md' } = {}) { + return `${topicDir(cfg, topic)}/${snapshotName(topic, date, ext)}`; +} + +/** True when git ignores the topic folder: its snapshots are made on demand and never committed. */ +export function isLocalOnly(root, dir) { + const probe = `${dir}/PROBE_2000-01-01.md`; + return checkIgnored(root, [probe]).has(probe); +} + +/** + * Move every snapshot but the newest `keep` dates to + * /archive//snapshots//. It refuses any folder that is + * not a configured snapshots// folder (hazard H1), and leaves alone any + * file that is not a dated snapshot. An ignored file must still be ignored + * after the move (hazard H4); the report lists any that are not. + */ +export function archiveOlder(root, cfg, dir, { keep = 1, dryRun = false } = {}) { + const d = dir.replace(/\/+$/, ''); + const m = new RegExp(`^${cfg.docsRoot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/([^/]+)/snapshots/([^/]+)$`).exec(d); + if (!m || m[1] === 'archive' || cfg.snapshotTopics[m[2]] !== m[1]) { + throw new SnapshotError(`refusing to archive "${dir}": only a configured ${cfg.docsRoot}//snapshots// folder is archived (hazard H1)`); + } + if (!Number.isInteger(keep) || keep < 1) throw new SnapshotError(`--keep: "${keep}" must be a whole number, 1 or more`); + const [, subject, topic] = m; + const abs = join(root, d); + const files = existsSync(abs) ? readdirSync(abs).filter((n) => statSync(join(abs, n)).isFile()) : []; + const dated = []; + const skipped = []; + for (const name of files) { + const s = SNAPSHOT_NAME.exec(name); + if (s) dated.push({ name, date: s[1] }); + else skipped.push(`${d}/${name}`); + } + const keepDates = [...new Set(dated.map((x) => x.date))].sort().reverse().slice(0, keep); + const dest = `${cfg.docsRoot}/archive/${subject}/snapshots/${topic}`; + const tracked = new Set(trackedFiles(root, [d])); + const moves = dated + .filter((x) => !keepDates.includes(x.date)) + .sort((a, b) => a.name.localeCompare(b.name)) + .map((x) => ({ from: `${d}/${x.name}`, to: `${dest}/${x.name}` })) + .map((mv) => ({ ...mv, tracked: tracked.has(mv.from) })); + for (const mv of moves) { + if (existsSync(join(root, mv.to))) throw new SnapshotError(`"${mv.to}": already exists in the archive; nothing was moved`); + } + const wasIgnored = checkIgnored(root, moves.map((mv) => mv.from)); + const report = { dir: d, kept: dated.filter((x) => keepDates.includes(x.date)).map((x) => `${d}/${x.name}`), moves, skipped, newlyVisible: [], dryRun }; + if (dryRun) return report; + for (const mv of moves) { + mkdirSync(join(root, posix.dirname(mv.to)), { recursive: true }); + if (mv.tracked) gitMv(root, mv.from, mv.to); + else renameSync(join(root, mv.from), join(root, mv.to)); + } + const ignoredDests = moves.filter((mv) => wasIgnored.has(mv.from)).map((mv) => mv.to); + const stillIgnored = checkIgnored(root, ignoredDests); + report.newlyVisible = ignoredDests.filter((p) => !stillIgnored.has(p)); + return report; +} + +export function formatArchive(r) { + const would = r.dryRun ? 'would ' : ''; + const lines = [`${r.dryRun ? 'DRY RUN: ' : ''}${r.dir}: keeps ${r.kept.length} file(s) of the newest date(s); ${r.moves.length} older file(s) ${would}move to the archive:`]; + for (const mv of r.moves) lines.push(` ${mv.from} -> ${mv.to}${mv.tracked ? '' : ' (not tracked)'}`); + if (r.skipped.length) { + lines.push(`${r.skipped.length} file(s) left alone, because they are not dated snapshots (_.):`); + for (const f of r.skipped) lines.push(` ${f}`); + } + if (r.newlyVisible.length) { + lines.push(`DANGER: ${r.newlyVisible.length} file(s) that were ignored are no longer ignored in the archive. Add a .gitignore rule for them before you stage anything:`); + for (const f of r.newlyVisible) lines.push(` ${f}`); + } + return lines.join('\n'); +} diff --git a/skills/docs-kit-help/SKILL.md b/skills/docs-kit-help/SKILL.md index f69e8fa..76b3237 100644 --- a/skills/docs-kit-help/SKILL.md +++ b/skills/docs-kit-help/SKILL.md @@ -9,11 +9,11 @@ allowed-tools: Read Grep Glob Answer the user's question about docs-kit **only from the docs that ship in this plugin**, for the version they have installed. Those docs describe exactly what they run. The web, or your memory of docs-kit, may describe another version. -**This skill reads; it never runs anything.** No Bash, no edits, no network. If the answer is "run X", tell the user to run it, or point at the skill that does it (`/docs-kit-init`, `/docs-kit-pin`). +**This skill reads; it never runs anything.** No Bash, no edits, no network. If the answer is "run X", tell the user to run it, or point at the skill that does it (`/docs-kit-init`, `/docs-kit-reorg`, `/docs-kit-pin`). ## Steps -1. **The version.** Read `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`, key `version`. Say it in the answer ("in docs-kit 0.3.1, …"). +1. **The version.** Read `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`, key `version`. Say it in the answer ("in docs-kit 0.4.0, …"). 2. **Find the answer**, in this order, all under `${CLAUDE_PLUGIN_ROOT}`: 1. `docs/FAQ.md`: short answers, each pointing at its guide. 2. `docs/guides/howto/`: the steps to adopt, reorganise, print, upgrade and remove. diff --git a/skills/docs-kit-init/SKILL.md b/skills/docs-kit-init/SKILL.md index 67b59c9..67e934f 100644 --- a/skills/docs-kit-init/SKILL.md +++ b/skills/docs-kit-init/SKILL.md @@ -96,13 +96,7 @@ The setup is safe to commit while the check fails: `init` adds no failing test, If the check passed, the setup is done: say so, and stop. -If it failed, ask one question: "Start the reorganisation with a read-only audit?" (Recommended), or stop here. On a yes, follow DESIGN §6.3 of docs-kit (https://github.com/techsilon-oss/docs-kit/blob/main/docs/DESIGN.md): - -1. **Audit**, read-only: every file under the docs root, every doc path named outside it, generators, `.gitignore` rules, path-based keys, and paths built in pieces. -2. **Proposal**, saved as a dated note in `docs/notes/`: the subject list, an old → new table for every file, protected paths with reasons, the roles from step 2, the hazards found, and the slices (one pull request each). Apply the least-change defaults (DESIGN §6.3, L1 to L10) and list the ones you applied, so the owner can override any. Add the note itself to `immutablePrefixes` in the same commit (L10): it records the old paths, and `move` must not rewrite it. -3. **The owner approves** the proposal once. Ask about `roles` before that, if the repo will have how-tos; ask nothing else a default settles. Nothing moves before the approval. -4. **Each slice:** `DOCS_KIT move --dry-run`, then `move`, then the project's tests and `DOCS_KIT check`. Stage everything `git status` lists, not only the docs folders. Open the pull request. -5. **Close:** once the check passes, run `DOCS_KIT init --test ` with the path from step 2, so the check runs in the tests; add `roles` and run `DOCS_KIT index` if the how-tos exist. Record the decision in the project's decision log. +If it failed, ask one question: "Start the reorganisation with `/docs-kit-reorg`?" (Recommended), or stop here. On a yes, follow `/docs-kit-reorg` ([`../docs-kit-reorg/SKILL.md`](../docs-kit-reorg/SKILL.md)) from its step 1. It runs a read-only audit, writes one proposal, and asks the owner only for the roles and one approval before anything moves. Pass on what this skill found: the test path from step 2, and the roles you noted. ## If something fails diff --git a/skills/docs-kit-reorg/SKILL.md b/skills/docs-kit-reorg/SKILL.md new file mode 100644 index 0000000..1be1215 --- /dev/null +++ b/skills/docs-kit-reorg/SKILL.md @@ -0,0 +1,90 @@ +--- +name: docs-kit-reorg +description: Reorganise a repo's docs folder into the docs-kit layout. Runs a read-only audit, writes one proposal that applies the least-change defaults, asks only for the roles and one approval, then moves the docs in slices with docs-kit move, routes generators through docs-kit snapshot, and adds the check to the tests. Never moves a doc before the approval; commits only on a yes; never pushes. Use after /docs-kit-init, when docs-kit check fails. +argument-hint: "[status]" +allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/scripts/docs-kit.mjs" audit*) Bash(node "${CLAUDE_PLUGIN_ROOT}/scripts/docs-kit.mjs" check*) Bash(node "${CLAUDE_PLUGIN_ROOT}/scripts/docs-kit.mjs" --version) Read Glob Grep +--- + +# `/docs-kit-reorg` — reorganise a docs folder + +The CLI is the plugin's own copy: `node "${CLAUDE_PLUGIN_ROOT}/scripts/docs-kit.mjs"`. Below it is written as `DOCS_KIT`. Run it from the repo root. + +The owner answers **two things**: who the `roles` are, and one approval of the proposal. The least-change defaults (DESIGN §6.3, L1 to L10, https://github.com/techsilon-oss/docs-kit/blob/main/docs/DESIGN.md) settle everything else. Ask about anything else only when no default settles it, or when a slice shows something the proposal did not foresee. + +**Rules for the whole skill:** + +- Never move, rename or delete a doc before the owner approves the proposal. +- Follow the project's own agent instructions (`CLAUDE.md` or similar): branch rules, commit style, test commands, which folders are historical. Where they differ from this skill, they win. +- Commit only on the owner's yes, and only the files the step changed. Never push, except when the project's rules say the working branch is pushed. +- Never edit a file under `immutablePrefixes`. + +With the argument `status`: run `DOCS_KIT check`, find the proposal note (Grep `docs/notes/` for "docs-kit reorganisation"), and say which slices are done and which is next. Then stop. + +## Step 1 — Preflight + +- `docs-kit.json` exists at the repo root. If not, STOP and say: run `/docs-kit-init` first. +- The working tree is clean (`git status`). If not, say so, and ask whether to continue. +- The branch follows the project's rules. On the default or a shared branch, propose a new branch, for example `docs/reorganise`. + +## Step 2 — Audit (read-only) + +1. Run `DOCS_KIT audit --json`. It lists the docs root, each folder and its map, exports trees, code inside the docs folder, generators, ignored files, `.gitignore` rules, docs that immutable files name, agent instructions that name docs, how-to look-alikes, and every reference to a doc from outside the docs folder. +2. Read the project's agent instructions. Note: the folders they call historical or not to be edited (L4), the docs they name as a starting point (L5), and any rule about docs. +3. Read the title and the first lines of each doc at the docs root, so you can give each one a subject. +4. For each generator and each exports tree: read the code that writes the files. Note the topics, the file names, where it archives older copies, and whether its outputs are committed or gitignored. + +## Step 3 — The proposal + +Write it as a dated note, `docs/notes/-docs-kit-reorganisation.md`, with these sections: + +1. **Findings:** what the audit and the check found, in a few lines. +2. **Defaults applied:** one line per default from L1 to L10 that this proposal uses, with what it means here. +3. **Subjects:** keep every existing folder and its name (L1). Add a subject only for files that fit none of them; start from the starter list (DESIGN §4). Add `notes` for the proposal itself. +4. **Old → new:** one row per file that moves. The folder changes; the file name does not (L2). Docs that the agent instructions or the front door name as a starting point stay where they are (L5). Files another tool's manifest names stay at the root (L7). +5. **Protected and frozen:** the docs immutable files name (L3, already in `docs-kit.json` from `init`), any other protected path with its reason, and the historical folders that go in `immutablePrefixes` (L4). +6. **Generated docs:** for each exports tree or generator: + - one `snapshotTopics` entry per topic, to the subject it belongs to; + - its code moves out of the docs folder, for example to `scripts/docs-gen/`, with `DOCS_KIT move` (code inside a docs folder is not a doc); + - it asks `docs-kit snapshot path ` where to write, and calls `docs-kit snapshot archive ` instead of its own archive step; + - if its outputs are gitignored today, the `.gitignore` rule follows the new folder, and the archive folder gets a rule too, so they stay ignored (H4). The check then reports the topic as local-only. +7. **Roles:** who reads the how-tos, from the app's own roles and the docs. Ask the owner in step 4. +8. **How-tos:** only a doc that is already one task in steps becomes a how-to (L6). List the candidates the audit found, with a yes or no for each and the reason. +9. **For later:** overlapping docs, such as two guides for the same task. They are not merged in this reorganisation (L9). +10. **Hazards:** each one the audit found, and how the plan handles it. +11. **Slices** (L8), one pull request each: + 1. the folder maps (`README.md` in each subject), the new subjects in `docs-kit.json`, and this note. No moves; + 2. the moves; + 3. the generators and their snapshots, if there are any; + 4. the how-tos, `roles` and `DOCS_KIT index`; + 5. close: `init --test`, once the check passes. + +Add the note to `immutablePrefixes` in `docs-kit.json` (L10). It records the old paths, and `move` must not rewrite it. + +## Step 4 — Two questions + +1. **Roles**, when the plan makes how-tos: show the proposed list, and ask the owner to confirm or change it. +2. **Approve the proposal?** Show the note's path and a short summary: the subjects, how many files move, the slices. The answers: approve (Recommended), or change something. On a change, update the note and ask once more. + +On the approval: record it in the note (date, and what was approved), then commit the note and the `docs-kit.json` changes on a yes, as slice 1 starts. + +## Step 5 — Each slice + +1. For slice 1, write each missing folder map: one line per doc, with a link. Write nothing else. +2. For each move, run `DOCS_KIT move [ ...] --dry-run` first. Read the whole output. +3. If the dry run shows something the proposal did not foresee (a file you did not expect in the change list, a `REVIEW` line, an immutable file that names a moved path, a refusal), STOP. Tell the owner what it is, and propose what to do. +4. Run the move without `--dry-run`. Then run the project's tests and `DOCS_KIT check`. +5. Stage every file that `git status` lists, not only the docs folders. Ask: "Commit slice as ``?" Commit on a yes. Then say how the slice reaches the shared branch under the project's rules (for example, a pull request into `dev`). +6. For the generators slice: change the generator's code as the proposal says, run it once, and check the new snapshot sits at the path `docs-kit snapshot path` gives. Run `DOCS_KIT check`. + +## Step 6 — Close + +1. When the check passes, run `DOCS_KIT init --test ` with the test path from `/docs-kit-init`, so the check runs in the tests. +2. If the plan made how-tos: add `roles` to `docs-kit.json`, and run `DOCS_KIT index`. +3. Record the decision in the project's decision log, if it has one. +4. Mark the proposal note as done in the `notes` map. Do not edit the note itself: it is immutable. + +## If something fails + +- `move` exits 2: show its message. Nothing moved. A refusal names its reason (protected, immutable); follow the proposal, or ask the owner. +- `move` exits 1 (`DANGER … no longer ignored`): fix `.gitignore` before you stage anything. +- A docs-kit bug or a missing feature: say so plainly, and suggest an issue at https://github.com/techsilon-oss/docs-kit/issues. Describe it with invented names, not the project's own. diff --git a/test/audit.test.mjs b/test/audit.test.mjs new file mode 100644 index 0000000..408df34 --- /dev/null +++ b/test/audit.test.mjs @@ -0,0 +1,86 @@ +// docs-kit audit (DESIGN §6.3 step 1): a read-only inventory that finds each hazard it can. +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { writeFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { audit } from '../scripts/lib/audit.mjs'; +import { DEFAULTS } from '../scripts/lib/config.mjs'; +import { cleanup, git, makeFixture } from './helpers/fixture.mjs'; + +const CLI = fileURLToPath(new URL('../scripts/docs-kit.mjs', import.meta.url)); + +// An invented app before its reorganisation: loose root docs, a generator inside docs/, +// ignored outputs, a migration that cites a doc, agent instructions that name docs. +const MESSY = { + 'README.md': 'See docs/PRD.md and docs/support/. Everything else is under docs/.\n', + 'CLAUDE.md': 'Start at docs/ONBOARDING.md. History is in docs/status/.\n', + '.gitignore': 'docs/exports/**\n!docs/exports/\n!docs/exports/README.md\n!docs/exports/_scripts/\n!docs/exports/_scripts/**\n', + 'db/migrations/001.sql': "-- spec: docs/architecture/payments.md\n", + 'scripts/build-legal.mjs': "import { writeFileSync } from 'node:fs';\nwriteFileSync('docs/legal/TERMS.md', 'x');\n", + 'scripts/lint.mjs': "// reads docs/PRD.md, writes nothing\n", + 'test/docs.test.mjs': "import { writeFileSync } from 'node:fs';\nwriteFileSync('docs/PRD.md', 'fixture');\n", + 'docs/README.md': '# Docs\n', + 'docs/PRD.md': '# PRD\n', + 'docs/ONBOARDING.md': '# Onboarding\n', + 'docs/architecture/payments.md': '# Payments\n', + 'docs/legal/TERMS.md': '# Terms\n', + 'docs/support/README.md': '# Support\n', + 'docs/support/incident-runbook.md': '# Incidents\n', + 'docs/status/2026-07-01.md': '# Status\n', + 'docs/exports/README.md': '# Exports\n', + 'docs/exports/_scripts/generate.py': "open('docs/exports/status/x.md', 'w')\n", +}; + +const withRepo = (fn) => async () => { + const root = makeFixture({ files: MESSY, ignored: {} }); + writeFileSync(join(root, 'docs/exports/status-2026-07-13.md'), 'generated'); + try { await fn(root); } finally { cleanup(root); } +}; + +const CFG = { ...DEFAULTS, immutablePrefixes: ['db/migrations/'], configured: false }; + +test('audit: the docs root, its folders and their maps', withRepo((root) => { + const a = audit(root, CFG); + assert.deepEqual(a.root.allowed, ['README.md']); + assert.deepEqual(a.root.notAllowed, ['ONBOARDING.md', 'PRD.md']); + const f = Object.fromEntries(a.root.folders.map((x) => [x.name, x])); + assert.equal(f.support.hasMap, true); + assert.equal(f.legal.hasMap, false); + assert.equal(f.status.historical, true, 'a folder named status may be history (L4)'); + assert.equal(f.legal.subject, false, 'no docs-kit.json yet, so no subjects'); +})); + +test('audit: exports trees, code inside docs, generators outside, ignored outputs, gitignore rules (H4)', withRepo((root) => { + const a = audit(root, CFG); + assert.deepEqual(a.exportsTrees, ['docs/exports/']); + assert.deepEqual(a.codeInDocs, ['docs/exports/_scripts/generate.py']); + assert.deepEqual(a.generators, ['scripts/build-legal.mjs'], 'writes and names a doc; a reader or a test is not a generator'); + assert.deepEqual(a.ignoredUnderDocs, [{ dir: 'docs/exports', files: 1 }]); + assert.equal(a.gitignoreRules.length, 5); + assert.deepEqual(a.gitignoreRules[0], { file: '.gitignore', line: 1, rule: 'docs/exports/**' }); +})); + +test('audit: docs that immutable files name (L3), agent instructions (L5), how-to look-alikes (L6), and every reference', withRepo((root) => { + const a = audit(root, CFG); + assert.deepEqual(Object.keys(a.namedByImmutable), ['docs/architecture/payments.md']); + assert.deepEqual(a.agentFiles, ['CLAUDE.md']); + assert.deepEqual(a.howtoCandidates, ['docs/support/incident-runbook.md']); + const refs = Object.fromEntries(a.references.map((r) => [r.doc, r.files])); + assert.deepEqual(refs['docs/PRD.md'], ['README.md', 'scripts/lint.mjs', 'test/docs.test.mjs']); + assert.deepEqual(refs['docs/status/'], ['CLAUDE.md'], 'a folder named by path is a reference too'); + assert.ok(!('docs/' in refs), 'the docs root itself is not a reference'); +})); + +test('audit changes nothing, and --json is the same report', withRepo((root) => { + const before = git(root, 'status', '--porcelain', '--ignored'); + const r = spawnSync(process.execPath, [CLI, 'audit', '--json'], { cwd: root, encoding: 'utf8' }); + assert.equal(r.status, 0, r.stderr); + const j = JSON.parse(r.stdout); + assert.deepEqual(j.root.notAllowed, ['ONBOARDING.md', 'PRD.md']); + const text = spawnSync(process.execPath, [CLI, 'audit'], { cwd: root, encoding: 'utf8' }); + assert.match(text.stdout, /Read-only: nothing was changed/); + assert.match(text.stdout, /No docs-kit\.json: the audit used the defaults/); + assert.equal(git(root, 'status', '--porcelain', '--ignored'), before); +})); diff --git a/test/docs.test.mjs b/test/docs.test.mjs index fe7ac76..2a6070f 100644 --- a/test/docs.test.mjs +++ b/test/docs.test.mjs @@ -112,3 +112,26 @@ test('every relative link in the docs resolves, and so does every anchor', () => } assert.deepEqual(broken, []); }); + +test('the generator snippets in the how-to run, in Python and in Node', async (t) => { + const { cpSync, writeFileSync: write } = await import('node:fs'); + const body = read('docs/guides/howto/HOWTO-route-generated-docs.md'); + const block = (lang) => new RegExp('```' + lang + '\n([\\s\\S]*?)```').exec(body)[1].replace(/^ {3}/gm, ''); + const root = makeFixture(); + try { + cpSync(join(ROOT, 'scripts'), join(root, 'node_modules/docs-kit/scripts'), { recursive: true }); + const want = /^docs\/platform\/snapshots\/architecture\/ARCHITECTURE_\d{4}-\d{2}-\d{2}\.pdf$/; + + write(join(root, 'gen.mjs'), `${block('js')}\nconsole.log(snapshotPath('architecture', 'pdf'));\n`); + const node = spawnSync(process.execPath, ['gen.mjs'], { cwd: root, encoding: 'utf8' }); + assert.equal(node.status, 0, node.stderr); + assert.match(node.stdout.trim(), want); + + const py = ['python3', 'python'].find((p) => spawnSync(p, ['--version']).status === 0); + if (!py) { t.diagnostic('no Python on this machine: the Python snippet was not run'); return; } + write(join(root, 'gen.py'), `${block('python')}\nprint(snapshot_path("architecture", "pdf"))\n`); + const r = spawnSync(py, ['gen.py'], { cwd: root, encoding: 'utf8' }); + assert.equal(r.status, 0, r.stderr); + assert.match(r.stdout.trim(), want); + } finally { cleanup(root); } +}); diff --git a/test/plugin.test.mjs b/test/plugin.test.mjs index a4881fe..6212176 100644 --- a/test/plugin.test.mjs +++ b/test/plugin.test.mjs @@ -153,3 +153,18 @@ test('kit standard: Apache-2.0 with a NOTICE, in every manifest, and shipped wit test('kit standard: package.json names Techsilon LLC and the org email', () => { assert.equal(json('package.json').author, 'Techsilon LLC '); }); + +test('every skill runs only docs-kit commands and options the CLI has', () => { + const cli = text('scripts/docs-kit.mjs'); + const used = new Set(); + for (const s of skills) { + for (const m of s.body.matchAll(/DOCS_KIT ([a-z]+)((?: [^`\n]*)?)/g)) { + used.add(m[1]); + assert.ok(cli.includes(`cmd === '${m[1]}'`), `${s.dir}: docs-kit ${m[1]}`); + for (const opt of m[2].match(/--[a-z-]+/g) || []) { + assert.ok(cli.includes(`takeValue(args, '${opt}')`) || cli.includes(`takeFlag(args, '${opt}')`), `${s.dir}: docs-kit ${m[1]} ${opt}`); + } + } + } + for (const c of ['audit', 'check', 'move', 'init', 'index', 'print']) assert.ok(used.has(c), `a skill uses docs-kit ${c}`); +}); diff --git a/test/snapshots.test.mjs b/test/snapshots.test.mjs new file mode 100644 index 0000000..29a0b83 --- /dev/null +++ b/test/snapshots.test.mjs @@ -0,0 +1,96 @@ +// Snapshot routing (DESIGN §6.6): one place per topic, dated names, older ones archived, +// and topics git ignores are local-only, not missing. +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { check } from '../scripts/lib/check.mjs'; +import { loadConfig } from '../scripts/lib/config.mjs'; +import { SnapshotError, archiveOlder, snapshotName, snapshotPath, topicDir } from '../scripts/lib/snapshots.mjs'; +import { TODAY, cleanup, exists, git, makeFixture } from './helpers/fixture.mjs'; + +const CLI = fileURLToPath(new URL('../scripts/docs-kit.mjs', import.meta.url)); +const run = (cwd, ...args) => spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: 'utf8' }); + +const withFixture = (fn) => async () => { + const root = makeFixture(); + try { await fn(root, loadConfig(root)); } finally { cleanup(root); } +}; + +const SNAP = 'docs/platform/snapshots/architecture'; +const put = (root, rel, text = 'x\n') => { mkdirSync(join(root, rel, '..'), { recursive: true }); writeFileSync(join(root, rel), text); }; + +test('snapshot path: the configured topic folder and a dated name; an unknown topic is an error', withFixture((root, cfg) => { + assert.equal(topicDir(cfg, 'architecture'), SNAP); + assert.equal(snapshotName('launch-readiness', '2026-11-13'), 'LAUNCH-READINESS_2026-11-13.md'); + assert.equal(snapshotPath(cfg, 'architecture', { date: '2026-11-13', ext: 'pdf' }), `${SNAP}/ARCHITECTURE_2026-11-13.pdf`); + assert.throws(() => topicDir(cfg, 'status'), /unknown snapshot topic "status"; add it to "snapshotTopics"/); + assert.throws(() => topicDir(cfg, '../x'), SnapshotError); + const r = run(root, 'snapshot', 'path', 'architecture', '--date', '2026-11-13'); + assert.equal(r.status, 0, r.stderr); + assert.equal(r.stdout.trim(), `${SNAP}/ARCHITECTURE_2026-11-13.md`); + assert.equal(run(root, 'snapshot', 'path', 'nope').status, 2); + assert.equal(run(root, 'snapshot', 'path', 'architecture', '--date', '2026-13-01').status, 2); +})); + +test('snapshot archive: keeps the newest date, moves older ones to archive//snapshots//', withFixture((root, cfg) => { + put(root, `${SNAP}/ARCHITECTURE_2026-09-01.md`); + put(root, `${SNAP}/ARCHITECTURE_2026-11-13.md`); + put(root, `${SNAP}/ARCHITECTURE_2026-11-13.pdf`); + git(root, 'add', '-A'); + git(root, 'commit', '-q', '-m', 'snapshots'); + const before = run(root, 'snapshot', 'archive', 'architecture', '--dry-run'); + assert.equal(before.status, 0, before.stderr); + assert.match(before.stdout, /DRY RUN/); + const r = run(root, 'snapshot', 'archive', 'architecture'); + assert.equal(r.status, 0, r.stderr); + for (const f of ['ARCHITECTURE_2026-11-13.md', 'ARCHITECTURE_2026-11-13.pdf']) assert.ok(exists(root, `${SNAP}/${f}`), `keeps ${f}`); + assert.ok(!exists(root, `${SNAP}/ARCHITECTURE_2026-10-20.md`), 'the fixture\'s older snapshot left the topic folder'); + assert.ok(exists(root, 'docs/archive/platform/snapshots/architecture/ARCHITECTURE_2026-10-20.md'), 'and is in the archive'); + assert.ok(exists(root, 'docs/archive/platform/snapshots/architecture/ARCHITECTURE_2026-09-01.md')); + assert.match(git(root, 'status', '--porcelain'), /^R {2}docs\/platform\/snapshots\/architecture\/ARCHITECTURE_2026-09-01\.md -> docs\/archive\/platform/m, 'a tracked snapshot moves with git mv'); + assert.ok(check(root, cfg, { today: new Date('2026-11-14') }).ok, 'the layout still holds'); +})); + +test('H1: the archive helper refuses any folder that is not a configured snapshots// folder', withFixture((root, cfg) => { + for (const dir of ['docs/platform', 'docs/legal', 'docs/platform/snapshots', 'docs/archive/platform/snapshots/architecture', 'docs/legal/snapshots/architecture']) { + assert.throws(() => archiveOlder(root, cfg, dir), /refusing to archive .*hazard H1/, dir); + } + const canonical = 'docs/platform/ARCHITECTURE.md'; + assert.ok(exists(root, canonical)); + archiveOlder(root, cfg, SNAP); + assert.ok(exists(root, canonical), 'a canonical doc is never archived'); +})); + +test('snapshot archive leaves a file that is not a dated snapshot where it is', withFixture((root, cfg) => { + put(root, `${SNAP}/notes.txt`); + put(root, `${SNAP}/ARCHITECTURE_2026-01-01.md`); + const r = archiveOlder(root, cfg, SNAP); + assert.deepEqual(r.skipped, [`${SNAP}/notes.txt`]); + assert.ok(exists(root, `${SNAP}/notes.txt`)); + assert.ok(exists(root, 'docs/archive/platform/snapshots/architecture/ARCHITECTURE_2026-01-01.md')); +})); + +test('H4: an ignored snapshot that is visible after archiving is reported, and the command exits 1', withFixture((root, cfg) => { + // The topic folder is ignored; the archive folder is not. + appendFileSync(join(root, '.gitignore'), `\n${SNAP}/*.pdf\n`); + git(root, 'add', '.gitignore'); + git(root, 'commit', '-q', '-m', 'ignore pdfs'); + put(root, `${SNAP}/ARCHITECTURE_2026-01-01.pdf`, 'confidential'); + put(root, `${SNAP}/ARCHITECTURE_2026-11-13.pdf`, 'confidential'); + const r = run(root, 'snapshot', 'archive', 'architecture'); + assert.equal(r.status, 1, r.stdout + r.stderr); + assert.match(r.stdout, /DANGER: 1 file\(s\) that were ignored are no longer ignored in the archive/); + assert.match(r.stdout, /docs\/archive\/platform\/snapshots\/architecture\/ARCHITECTURE_2026-01-01\.pdf/); +})); + +test('a snapshot topic whose folder git ignores is local-only: the check does not fail it as missing (H10 still holds otherwise)', withFixture((root, cfg) => { + const cfg2 = { ...cfg, snapshotTopics: { ...cfg.snapshotTopics, status: 'operations', briefing: 'operations' } }; + appendFileSync(join(root, '.gitignore'), '\ndocs/operations/snapshots/status/\n'); + const r = check(root, cfg2, { today: TODAY }); + assert.ok(!r.errors.some((e) => e.includes('"status"')), r.errors.join('\n')); + assert.ok(r.errors.some((e) => e.includes('snapshot topic "briefing" is configured but has no dated snapshots')), 'a topic that is not ignored still fails when empty'); + assert.deepEqual(r.stats.localOnlyTopics, ['status']); +}));