diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 101cda0..087e277 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.4.0", + "version": "0.4.1", "source": "./", "author": { "name": "Techsilon LLC", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index bfc9dd0..0fa75c8 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.4.0", + "version": "0.4.1", "author": { "name": "Techsilon LLC", "email": "oss@techsilon.com", diff --git a/CHANGELOG.md b/CHANGELOG.md index 187b113..6b59ed1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,18 @@ 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.1] - 2026-11-13 + +Fixes from Trial 2 (DESIGN §10). + +### Changed + +- `move` lists every link that names a moved doc by its full address, such as a GitHub URL to the repo's own file or a `file:///` link, under `REVIEW` (hazard H13). It does not rewrite them. +- `init` adds a protected doc at the docs root to `rootAllowed`, because it may not move, so the check can pass with it in place. +- `init` warns when the repo uses Biome, which rejects the comments in `docs-kit.json`, and names the fix. +- `check`: the exports error now says an `exports/` folder is not allowed, instead of reading as if the folder were missing. +- `/docs-kit-reorg`: the generator slice comes before the moves, and the largest move last; folders that hold a protected doc are kept; `archive` is never listed as a subject; each doc that stays gets one reason, "cannot move" or "kept by choice"; and the owner is told which code files changed only in a doc path, since a doc-sync gate may report them. + ## [0.4.0] - 2026-11-13 ### Added diff --git a/README.md b/README.md index 8df9a6e..0589d56 100644 --- a/README.md +++ b/README.md @@ -16,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.4.0 init --dry-run -npx github:techsilon-oss/docs-kit#v0.4.0 init +npx github:techsilon-oss/docs-kit#v0.4.1 init --dry-run +npx github:techsilon-oss/docs-kit#v0.4.1 init npm install ``` @@ -41,7 +41,7 @@ In Claude Code, install the plugin once, then run `/docs-kit-init` in any repo: | **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.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`. +**Pin a release.** `init` pins the devDependency to the tag it ran from (`github:techsilon-oss/docs-kit#v0.4.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`. ## Uninstall diff --git a/docs/DESIGN.md b/docs/DESIGN.md index f2d8e42..0f9df0b 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -143,6 +143,7 @@ For each pair (file or folder): 7. **Prints every file it changed,** and ends with `git status --porcelain`. The caller must stage all of them (hazard H9). 8. Runs `docs-kit check` at the end. 9. **Follows a renamed file by name** (hazard H12). When a move changes a file's name, not only its folder: a link label that is exactly the old file name, the old destination or the old repo path becomes the new one (`[OLD.md](OLD.md)` becomes `[NEW.md](NEW.md)`); every other line in a tracked text file that names the old file name alone, with no path, is listed for review and not rewritten, because a bare name in prose may mean something else. +10. **Lists links that spell out a full address** (hazard H13): a link to a moved doc by URL, such as a GitHub link to the repo's own file, or by `file:///`. It does not rewrite them, because it cannot tell this repo from another repo or machine. ### 6.3 Guided reorganisation — `/docs-kit-reorg` (skill) @@ -235,7 +236,7 @@ The project's own agent instructions (branch rules, commit style, dependency rul ## 7. Hazards found in a real reorganisation -Each hazard below happened, or nearly happened, during a real reorganisation: H1 to H10 in one large `docs/` tree, H11 and H12 in Trial 1. Each has a guard in the tools. The audit step checks for all of them. +Each hazard below happened, or nearly happened, during a real reorganisation: H1 to H10 in one large `docs/` tree, H11 and H12 in Trial 1, H13 in Trial 2. Each has a guard in the tools. The audit step checks for all of them. | # | Hazard | What goes wrong | Guard | |---|---|---|---| @@ -251,6 +252,7 @@ Each hazard below happened, or nearly happened, during a real reorganisation: H1 | H10 | A test scanner reads zero files after a move | The check passes vacuously | Every scanning check asserts a non-empty set | | H11 | The proposal that records the reorganisation names the old paths | `move` rewrites the record's "old" column, so the record shows every file moving to where it already is | The proposal note goes in `immutablePrefixes` when it is written (L10) | | H12 | A renamed file is named in a link label, or by its file name alone with no path | The link target follows the move, but the label still shows the old name, and the bare name is neither rewritten nor reported | `move` rewrites a label that is exactly the old name or path, and lists every other bare mention for review (§6.2 step 9) | +| H13 | A link names a moved doc by its full address: a URL to the repo's own file, or `file:///` | The link is not rewritten and not reported, so it breaks once the move reaches the branch the URL names | `move` lists every such link for review (§6.2 step 10) | ## 8. Distribution @@ -296,6 +298,16 @@ docs-kit stands alone. When a repo also uses govkit, a thin module in govkit (bu - `move` rewrote the proposal that recorded the move: H11, guarded by L10. - When a move **renames** a file, two references go stale that `move` neither rewrites nor reports: a link label that shows the old file name (`[OLD.md](OLD.md)`: the target is rewritten, the label is not), and the old file name written alone, with no path. **Planned for 0.3:** `move` rewrites a link label that is exactly the old file name or path, and lists every other line in a tracked text file that names the old file name, for review. A move that keeps the name (L2) has neither problem. +**Trial 2 result (2026-11-13).** Adopted with `/docs-kit-reorg` in five slices: setup, folder maps and proposal, generator to snapshots, the moves, roles and how-tos. The owner answered the roles and approved the proposal once, plus one choice no default settled (below). The generator, in Python, now asks `docs-kit snapshot path` where to write and calls `docs-kit snapshot archive`; its outputs stay gitignored, and the check reports the topic as local-only. 13 docs moved as renames, with links rewritten across 71 files; the check passes and runs in the tests. What it taught (fixed in 0.4.1 unless marked): + +- The exports error read as "the folder is missing". It now says an `exports/` folder is not allowed. +- A protected doc at the docs root could never pass the check, because it may not move. `init` now adds it to `rootAllowed`. The skill keeps folders that hold a protected doc, and never lists `archive` as a subject. +- The proposal mixed "cannot move" (protected) with "kept by choice" (a default), so the owner had to choose between them. The skill now gives each kept doc one of the two reasons. +- `docs-kit.json` has comments, and a linter that reads JSON strictly (Biome) rejected it. `init` now warns and names the fix. +- Links that spell out a full address (a GitHub URL to the repo's own file, `file:///`) were neither rewritten nor reported: H13, now reported. +- A move rewrites doc paths in code comments, so a doc-sync gate that maps code to docs reports them as code changes on the release pull request. The skill now tells the owner. **Not fixed here:** the lasting fix is in that gate (govkit), which can ignore a file whose only change is a doc path renamed in the same diff. +- The generator slice went before the moves, and the largest move last, so each problem showed on its own. The skill now orders the slices that way. + **Decided (2026-11-13):** the least-change defaults (§6.3, L1 to L9). In Trial 1 the owner was asked a dozen judgement calls (branch, dependency, test path, what to protect, folder and file renames, historical docs, new subjects, which docs become how-tos). Almost all had one safe answer. Defaults now settle those, so the owner answers `roles` and approves the proposal once. With that, 0.3's `protected` suggestions are written by `init` rather than only suggested, because protecting only adds safety. ## 11. Owner questions diff --git a/docs/guides/howto/HOWTO-adopt-docs-kit.md b/docs/guides/howto/HOWTO-adopt-docs-kit.md index bc5d757..ad560af 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.4.0 init --dry-run + npx github:techsilon-oss/docs-kit#v0.4.1 init --dry-run ``` 2. Set it up: ```sh - npx github:techsilon-oss/docs-kit#v0.4.0 init + npx github:techsilon-oss/docs-kit#v0.4.1 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.4.0 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.1 check`. ## Check diff --git a/docs/guides/howto/HOWTO-upgrade-docs-kit.md b/docs/guides/howto/HOWTO-upgrade-docs-kit.md index ba84ab9..b2d5d3a 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.4.0`. +1. In `package.json`, change the devDependency to the new tag, for example `github:techsilon-oss/docs-kit#v0.4.1`. 2. In a terminal, in the root folder of your repo, run `npm install`. 3. Run the check: diff --git a/package.json b/package.json index 15d9449..bb941b4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "docs-kit", - "version": "0.4.0", + "version": "0.4.1", "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 2cde47e..3f9ec28 100644 --- a/scripts/docs-kit.mjs +++ b/scripts/docs-kit.mjs @@ -16,7 +16,7 @@ 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.4.0'; +export const VERSION = '0.4.1'; const USAGE = `docs-kit ${VERSION} diff --git a/scripts/lib/check.mjs b/scripts/lib/check.mjs index cc0718b..39191fc 100644 --- a/scripts/lib/check.mjs +++ b/scripts/lib/check.mjs @@ -123,7 +123,7 @@ export function check(root, cfg, { today = new Date() } = {}) { const i = parts.indexOf('exports'); if (i !== -1 && i < parts.length - 1) exportDirs.add(parts.slice(0, i + 1).join('/')); } - for (const e of exportDirs) errors.push(`${D}/${e}/: no exports/ tree; generated docs go to /snapshots//`); + for (const e of exportDirs) errors.push(`${D}/${e}/: an exports/ folder is not allowed; move generated docs to /snapshots// (docs-kit snapshot)`); // Rule 6: archive mirrors the live tree. const archiveSubjects = new Set(); diff --git a/scripts/lib/init.mjs b/scripts/lib/init.mjs index 9272b32..3c8d335 100644 --- a/scripts/lib/init.mjs +++ b/scripts/lib/init.mjs @@ -111,6 +111,21 @@ export function detectConfig(root, docsRoot = DEFAULTS.docsRoot) { } const prot = protectNamedDocs(root, docsRoot, immutablePrefixes, listDocFiles(root, docsRoot), notes); + // A protected doc at the docs root cannot move, so the check must allow it there. + for (const p of Object.keys(prot)) { + const f = p.slice(docsRoot.length + 1); + if (f.includes('/') || rootAllowed.includes(f)) continue; + rootAllowed.push(f); + notes.push(`rootAllowed: ${p} stays at the docs root, because it is protected`); + } + + // docs-kit.json has comments; a linter that reads every .json file strictly rejects them. + for (const f of ['biome.json', 'biome.jsonc']) { + if (existsSync(join(root, f))) { + notes.push(`${f}: Biome reads docs-kit.json as strict JSON and rejects its comments; exclude docs-kit.json in ${f}, or allow comments in it`); + break; + } + } const config = { docsRoot, diff --git a/scripts/lib/move.mjs b/scripts/lib/move.mjs index 9d4d47d..cefab1a 100644 --- a/scripts/lib/move.mjs +++ b/scripts/lib/move.mjs @@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync import { join, posix } from 'node:path'; import { DEFAULTS, normalizeRel } from './config.mjs'; import { checkIgnored, gitMv, ignoredFiles, statusPorcelain, trackedFiles, untrackedFiles } from './git.mjs'; -import { PathMap, findOldNames, findPiecedPaths, rewriteMarkdown, replaceRootPaths, rootPathRegex } from './rewrite.mjs'; +import { PathMap, findAddressPaths, findOldNames, findPiecedPaths, rewriteMarkdown, replaceRootPaths, rootPathRegex } from './rewrite.mjs'; export class MoveError extends Error {} @@ -105,6 +105,7 @@ export function planRewrites(root, plan, cfg = DEFAULTS) { const immutableHits = []; const piecedHits = []; const nameHits = []; + const addressHits = []; // H12: the old names of files whose name changes, not only their folder. const oldNames = [...new Set(plan.filePairs.filter((p) => posix.basename(p.from) !== posix.basename(p.to)).map((p) => posix.basename(p.from)))]; const scanNames = (file, text) => { for (const h of findOldNames(text, oldNames)) nameHits.push({ file, ...h }); }; @@ -136,8 +137,9 @@ export function planRewrites(root, plan, cfg = DEFAULTS) { } if (next !== text) rewrites.push({ oldPath: file, newPath, content: next }); scanNames(newPath, next); + if (!inArchive) for (const h of findAddressPaths(next, keys)) addressHits.push({ file: newPath, ...h }); } - return { rewrites, immutableHits, piecedHits, nameHits }; + return { rewrites, immutableHits, piecedHits, nameHits, addressHits }; } function removeEmptyDirs(root, dir, stopAt, warnings) { @@ -162,7 +164,7 @@ function removeEmptyDirs(root, dir, stopAt, warnings) { */ export function move(root, pairs, { cfg = DEFAULTS, dryRun = false } = {}) { const plan = planMoves(root, pairs, cfg); - const { rewrites, immutableHits, piecedHits, nameHits } = planRewrites(root, plan, cfg); + const { rewrites, immutableHits, piecedHits, nameHits, addressHits } = planRewrites(root, plan, cfg); const report = { dryRun, moves: plan.filePairs, @@ -170,6 +172,7 @@ export function move(root, pairs, { cfg = DEFAULTS, dryRun = false } = {}) { immutableHits, piecedHits, nameHits, + addressHits, ignoredMoves: plan.ignoredMoves, newlyVisible: [], warnings: [], @@ -221,6 +224,10 @@ export function formatMove(r) { lines.push(`REVIEW: ${r.nameHits.length} line(s) name a renamed file by its old name alone; not rewritten, fix by hand:`); for (const h of r.nameHits) lines.push(` ${h.file}:${h.line}: ${h.text} [${h.names.join(', ')}]`); } + if (r.addressHits.length) { + lines.push(`REVIEW: ${r.addressHits.length} line(s) link to a moved path by a full address (a URL or file:///); not rewritten, fix by hand:`); + for (const h of r.addressHits) lines.push(` ${h.file}:${h.line}: ${h.text} [${h.paths.join(', ')}]`); + } for (const w of r.warnings) lines.push(`WARNING ${w}`); if (r.newlyVisible.length) { lines.push(`DANGER: ${r.newlyVisible.length} file(s) that were ignored are no longer ignored. Fix .gitignore before you stage anything:`); diff --git a/scripts/lib/rewrite.mjs b/scripts/lib/rewrite.mjs index 533c073..4678244 100644 --- a/scripts/lib/rewrite.mjs +++ b/scripts/lib/rewrite.mjs @@ -173,6 +173,25 @@ export function findOldNames(text, names) { return hits; } +/* + * Full-address links (a URL or an absolute path) that end in a moved path, + * such as https://host/org/repo/blob/main/docs/x/A.md in a link, or + * file:///c:/work/repo/docs/x/A.md. move cannot tell this repo from another + * repo or machine, so these are reported for review, never rewritten. + */ +export function findAddressPaths(text, keys) { + const hits = []; + if (!keys.length) return hits; + const re = new RegExp(`(?<=[${PATH_CHAR}]\\/)(${keys.map(escapeRe).join('|')})${AFTER}`, 'g'); + const lines = text.split(/\r?\n/); + for (let n = 0; n < lines.length; n++) { + if (!/[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(lines[n])) continue; + const found = [...new Set([...lines[n].matchAll(re)].map((m) => m[1]))]; + if (found.length) hits.push({ line: n + 1, text: lines[n].trim(), paths: found.sort() }); + } + return hits; +} + /* * Pieced-together paths (hazard H7): code that builds a moved path from * quoted segments, such as join(root, "docs", "exports", "legal"). These are diff --git a/skills/docs-kit-init/SKILL.md b/skills/docs-kit-init/SKILL.md index 67e934f..516c839 100644 --- a/skills/docs-kit-init/SKILL.md +++ b/skills/docs-kit-init/SKILL.md @@ -77,7 +77,7 @@ On the answers, in order: | `folder is not a configured subject` | A docs-root folder not in `subjects` | Adding it to `subjects`, or moving it | | `missing (every subject folder needs a map)` | A subject folder with no `README.md` | Writing that README (a short map of the folder) | | `missing (the front door)` | No `docs/README.md` | `init` writes one; if it is listed, re-run `init` | -| `no exports/ tree` | Generated docs in an `exports/` folder | Moving them to `/snapshots//` | +| `an exports/ folder is not allowed` | Generated docs in an `exports/` folder | Moving them to `/snapshots//` | | `doc map file not found`, or a doc map path that does not exist | A gate names a doc that is not there | Fixing the map, or the doc's path | | `how-tos are named HOWTO-.md`, `last_checked` | A how-to's name or its freshness date | Renaming it with `move`, or checking the steps and setting `last_checked` | | Role findings (`no roles:`, `How-tos by role`) | Only when `roles` is set | Adding `roles:` to each how-to, then `DOCS_KIT index` | diff --git a/skills/docs-kit-reorg/SKILL.md b/skills/docs-kit-reorg/SKILL.md index 1be1215..4cd2974 100644 --- a/skills/docs-kit-reorg/SKILL.md +++ b/skills/docs-kit-reorg/SKILL.md @@ -39,8 +39,8 @@ Write it as a dated note, `docs/notes/-docs-kit-reorganisation.md`, 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). +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. Keep every folder that holds a protected doc where it is, so that doc does not have to move. Never list `archive` as a subject: the check treats `archive/` as built in. +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). Give each doc that stays a reason, and keep two reasons apart: **cannot move** (protected, or named by an immutable file) and **kept by choice** (a default or the owner). Only the first is fixed; the owner may move the second. 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; @@ -53,8 +53,8 @@ Write it as a dated note, `docs/notes/-docs-kit-reorganisation.md`, 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; + 2. the generators and their snapshots, if there are any; + 3. the moves, largest last, so a problem in a big move is not mixed up with the others; 4. the how-tos, `roles` and `DOCS_KIT index`; 5. close: `init --test`, once the check passes. @@ -71,10 +71,11 @@ On the approval: record it in the note (date, and what was approved), then commi 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. +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 (pieced paths, old names, or a full-address link such as a GitHub URL or `file:///`), 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`. +5. Tell the owner which code files changed only because a doc path in them was rewritten. A doc-sync check that maps code to docs (for example govkit's) may report them as code changes on the next release pull request. The owner then approves that pull request with a short reason; do not edit mapped docs or loosen the map to quiet it. +6. 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`). +7. 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 diff --git a/test/check.test.mjs b/test/check.test.mjs index 4525463..6da4438 100644 --- a/test/check.test.mjs +++ b/test/check.test.mjs @@ -38,7 +38,7 @@ test('rule 4: no exports/ tree (archive excepted)', withFixture({ extra: { 'docs/legal/exports/LEGAL_2026-01-01.md': 'x', 'docs/archive/legal/exports/OLD.md': 'x' }, }, (root, cfg) => { const e = errorsOf(root, cfg); - assert.ok(has(e, 'docs/legal/exports/: no exports/ tree'), e.join('\n')); + assert.ok(has(e, 'docs/legal/exports/: an exports/ folder is not allowed'), e.join('\n')); assert.ok(!has(e, 'archive/legal/exports'), e.join('\n')); })); diff --git a/test/hazards.test.mjs b/test/hazards.test.mjs index 392bad5..1b944a8 100644 --- a/test/hazards.test.mjs +++ b/test/hazards.test.mjs @@ -107,6 +107,26 @@ test('H12: a move that keeps the file name lists no old names', withFixture({}, assert.deepEqual(r.nameHits, []); })); +test('H13: a link that spells out the full address of a moved doc is listed for review, not rewritten', withFixture({}, (root, cfg) => { + const doc = 'docs/platform/NOTES.md'; + writeFileSync(join(root, doc), [ + '# Notes', + '', + '[1]: https://github.com/example-org/example-app/blob/main/docs/legal/TERMS.md "Terms"', + 'See [the terms](file:///c:/work/example-app/docs/legal/TERMS.md).', + 'And [here](../legal/TERMS.md).', + '', + ].join('\n')); + git(root, 'add', doc); + git(root, 'commit', '-q', '-m', 'notes'); + const r = move(root, [['docs/legal/TERMS.md', 'docs/money/TERMS.md']], { cfg: { ...cfg, subjects: [...cfg.subjects, 'money'] } }); + const text = read(root, doc); + assert.match(text, /\(\.\.\/money\/TERMS\.md\)/, 'a relative link follows the move'); + assert.match(text, /blob\/main\/docs\/legal\/TERMS\.md/, 'a full address is not rewritten'); + const hits = r.addressHits.map((h) => `${h.file}:${h.line}`); + assert.deepEqual(hits, [`${doc}:3`, `${doc}:4`], JSON.stringify(r.addressHits)); +})); + test('H4: gitignore rules follow the move, so confidential files stay ignored', withFixture({}, (root, cfg) => { const r = move(root, [['docs/legal', 'docs/money/legal']], { cfg: { ...cfg, subjects: [...cfg.subjects, 'money'] } }); const gi = read(root, '.gitignore'); diff --git a/test/init.test.mjs b/test/init.test.mjs index b2625fd..4c086b7 100644 --- a/test/init.test.mjs +++ b/test/init.test.mjs @@ -79,6 +79,26 @@ test('L3: init protects a doc an immutable file names, and only docs that exist; assert.equal(read(root, 'docs-kit.json'), before); })); +test('L3: a protected doc at the docs root is allowed there, so the check can pass without moving it', withRepo({ + ...MESSY, + 'supabase/migrations/002_more.sql': "-- see docs/ONBOARDING.md\n", +}, (root) => { + const { config, notes } = detectConfig(root); + assert.ok('docs/ONBOARDING.md' in config.protected); + assert.deepEqual(config.rootAllowed, ['README.md', 'HUB.md', 'ROADMAP.md', 'ONBOARDING.md']); + assert.ok(notes.some((n) => n === 'rootAllowed: docs/ONBOARDING.md stays at the docs root, because it is protected'), notes.join('\n')); +})); + +test('init warns when Biome would reject the comments in docs-kit.json', withRepo({ ...MESSY, 'biome.json': '{}\n' }, (root) => { + const r = run(root, 'init', '--dry-run'); + assert.equal(r.status, 0, r.stderr); + assert.match(r.stdout, /biome\.json: Biome reads docs-kit\.json as strict JSON and rejects its comments/); +})); + +test('init says nothing about Biome when the repo does not use it', withRepo(MESSY, (root) => { + assert.ok(!detectConfig(root).notes.some((n) => n.includes('Biome'))); +})); + test('detect: a doc map that selects nothing is left out', withRepo({ ...MESSY, 'scripts/source-doc-map.json': '{"mappings": []}', }, (root) => {