diff --git a/config/ci/ungated-scripts.json b/config/ci/ungated-scripts.json index 5abf98f9..ba1fa878 100644 --- a/config/ci/ungated-scripts.json +++ b/config/ci/ungated-scripts.json @@ -15,7 +15,7 @@ }, { "script": "check:remediation-ledger", - "reason": "Checks the prose ledger of the 2026-08-14 adapter re-review (docs/operations/adapter-remediation-ledger.md) against test-file markers and the file-transfer bundle budget. It passes at this commit, but it is a history record run by hand, not a current contract: it fails when a product removes the optional file-transfer recipe or when a test split moves a marked test to another file, and neither should block a merge. Run it after moving those tests or changing that budget, and point the ledger rows at the new files." + "reason": "Checks the prose ledger of the 2026-08-14 adapter re-review (docs/operations/adapter-remediation-ledger.md) against test-file markers and the file-transfer bundle budget. It is a history record run by hand, not a current contract: it fails when a product removes the optional file-transfer recipe or when a test split moves a marked test to another file, and neither should block a merge. Run it after moving those tests or changing that budget, and point the ledger rows at the new files." }, { "script": "check:scale:baseline", diff --git a/docs/README.md b/docs/README.md index 507dd42c..0f4e7499 100644 --- a/docs/README.md +++ b/docs/README.md @@ -40,7 +40,10 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어 - 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md) `verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에 -적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. `CHANGELOG.md`는 +적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와 +셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의 +경로와 링크는 그 checkout이 이 checkout 옆에 있을 때만 확인하고, 없으면 실패 대신 확인하지 +못한 것으로 출력과 `artifacts/quality/documentation-review.json`에 남긴다. `CHANGELOG.md`는 지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은 없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은 `scripts/verify-documentation-readiness.ts`다. diff --git a/docs/operations/adapter-remediation-ledger.md b/docs/operations/adapter-remediation-ledger.md index 9f20bab4..28ebfd81 100644 --- a/docs/operations/adapter-remediation-ledger.md +++ b/docs/operations/adapter-remediation-ledger.md @@ -88,9 +88,9 @@ Rollout state starts at `NOT_STARTED`; documented-unimplemented items start at | N-03 | Live V3 path | `corepack pnpm exec vitest run tests/unit/http-execution-v3.test.ts -t "retry-time fence"` | `fix: preserve command effect certainty across retries` | `FIXED_NOT_RELEASED` | command effect verdict regression | Red reproduced `SCOPE_FENCED` with `NOT_STARTED` after one dispatched attempt → green `MAYBE_APPLIED`; lattice table 9/9; `check:types` PASS; `lint` PASS | | N-04 | Live composition teardown | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts tests/unit/runtime-adapters.test.ts` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | telemetry delivery loss after teardown change | Red 10 failed (5 lifecycle + 5 capacity) → green 34/34; `check:diagnostics` PASS; `check:types` PASS; `check:architecture` PASS; `lint` PASS | | N-05 | Rollout blocker (sidecar not composed) | `corepack pnpm exec vitest run tests/unit/conditional-validator-store.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | persisted validator key incompatibility | Red collision case (two valid bindings sharing one delimiter-joined key) → green; key is now a bounded validated tuple encoded with `JSON.stringify` | -| N-06 | Legacy V2 rollback seam | `corepack pnpm exec vitest run tests/integration/http-client.test.ts` | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy keyed command rejection spike | Red 4 invalid-key cases → green; rejection happens before credentials and fetch (0 credential calls, 0 fetches) | -| N-07 | Legacy V2 rollback seam | `corepack pnpm exec vitest run tests/integration/http-client.test.ts tests/integration/auth-recovery.test.ts` | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy credential timeout regression | Red never-settling owner → green; credential wait races the existing attempt controller so no extra timer is added; ownership maps to REQUEST_TIMEOUT / REQUEST_ABORTED / AUTH_INTEGRATION_FAILURE with zero fetches | -| N-08 | Legacy V2 rollback seam | `corepack pnpm exec vitest run tests/unit/bounded-json-compatibility.test.ts` | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy JSON failure-code drift | Green 7/7 including throwing cancel/releaseLock; `readBoundedJson` now delegates to `bounded-body-reader` with the legacy codes preserved | +| N-06 | Legacy V2 rollback seam | The V2 client test tests/integration/http-client.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy keyed command rejection spike | Red 4 invalid-key cases → green; rejection happens before credentials and fetch (0 credential calls, 0 fetches) | +| N-07 | Legacy V2 rollback seam | The V2 client tests tests/integration/http-client.test.ts and tests/integration/auth-recovery.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy credential timeout regression | Red never-settling owner → green; credential wait races the existing attempt controller so no extra timer is added; ownership maps to REQUEST_TIMEOUT / REQUEST_ABORTED / AUTH_INTEGRATION_FAILURE with zero fetches | +| N-08 | Legacy V2 rollback seam | The V2 bounded JSON test tests/unit/bounded-json-compatibility.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy JSON failure-code drift | Green 7/7 including throwing cancel/releaseLock; `readBoundedJson` now delegates to `bounded-body-reader` with the legacy codes preserved | | N-09 | Live cross-context host | `corepack pnpm exec vitest run tests/unit/cross-tab-invalidation.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | cross-tab invalidation drop | Red foreign-area pulse accepted → green 13/13; localStorage captured once and `StorageEvent.storageArea` compared by object identity; pulse key registered as `CACHE_INVALIDATION_PULSE`; `check:registries` PASS | | N-10 | Cursor runtime `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/cursor-pagination-runtime.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | pagination abort semantics change | Red never-settling loader → green `PAGINATION_ABORTED` with the late page ignored | | N-11 | Live composition | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts -t capacity` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | capacity rejection on valid composition | Red 5/5 capacity cases → green; ceilings documented in VD-07 §7-4 | diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index d70ed79a..367140d3 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -1428,6 +1428,9 @@ export const documentationReviewArtifactSchema = z .object({ path: nonEmptyString, missingPaths: z.array(nonEmptyString), + // 1103/12-05. References into a paired repository that is not + // checked out beside this one. Reported, not failed. + unverifiedLinks: z.array(nonEmptyString), missingScripts: z.array(nonEmptyString), unknownGateIds: z.array(nonEmptyString), }) diff --git a/scripts/verify-documentation-readiness.ts b/scripts/verify-documentation-readiness.ts index 0165ec7e..18fbcd9a 100644 --- a/scripts/verify-documentation-readiness.ts +++ b/scripts/verify-documentation-readiness.ts @@ -1,6 +1,6 @@ import { existsSync } from "node:fs"; import { mkdir, readdir, readFile } from "node:fs/promises"; -import { dirname, join, matchesGlob, normalize } from "node:path/posix"; +import { dirname, join, matchesGlob, normalize, resolve } from "node:path/posix"; import { fileURLToPath } from "node:url"; import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts"; @@ -207,21 +207,62 @@ const deletedHistory = [ .flatMap(([, cell = ""]) => [...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, ""))) .filter((entry) => !exists(entry)); -// A backtick span is a path when it starts at a top-level entry or at an -// entry beside the document; line numbers and anchors are dropped. +// 1103/12-05. The paired templates a document may name (`/docs/…`) or +// link (`../../..//…`). They are looked up beside the checkout the +// documents are read from; where none is checked out (CI, a nested worktree) +// the reference is reported as not verified instead of passing silently. +const SIBLING_REPOSITORIES = new Set(["clean-architecture-backend-template"]); +const siblingsRoot = resolve(process.cwd(), ".."); + +// A backtick span is a path when it starts at a top-level entry, at an entry +// beside the document or at a paired repository; line numbers and anchors are +// dropped. A path into a paired repository is returned relative to this one +// (`..//…`). function namedPath(token: string, document: string): string | null { const candidate = token.replace(/#.*$/u, "").replace(/:\d[\d,:-]*$/u, ""); if (!candidate.includes("/") || candidate.startsWith("/") || /[\s*<>{}$()|]|\.\.\./u.test(candidate)) return null; const first = candidate.split("/")[0] ?? ""; if (topLevelEntries.has(first)) return candidate; + if (SIBLING_REPOSITORIES.has(first)) return `../${candidate}`; return first !== "." && first !== ".." && exists(join(dirname(document), first)) ? join(dirname(document), candidate) : null; } +// A link that leaves the repository is kept (`../…`); the caller looks it up +// beside the checkout. function linkedPath(target: string, document: string): string | null { if (/^(?:[a-z][a-z+.-]*:|#)/iu.test(target)) return null; - const resolved = normalize(join(dirname(document), target.replace(/#.*$/u, ""))); - return resolved.startsWith("../") ? null : resolved; + return normalize(join(dirname(document), target.replace(/#.*$/u, ""))); +} +// 1103/12-05. A command span is not a path, so the paths it takes as +// arguments (`corepack pnpm exec vitest run tests/…`, `node scripts/…`) were +// never looked up. Leading `NAME=value` assignments are skipped, a +// `--flag=value` argument is read as its value, and placeholders (``, +// globs, `$VAR`) are left alone by namedPath. +const COMMAND_HEADS = new Set(["corepack", "pnpm", "npx", "node", "vitest", "playwright", "tsc", "eslint", "bash", "sh"]); +function commandPaths(command: string, document: string): (string | null)[] { + const words = command.trim().replace(/^\$\s+/u, "").split(/\s+/u); + let head = 0; + while (/^[A-Z_][A-Z0-9_]*=/u.test(words[head] ?? "")) head += 1; + if (!COMMAND_HEADS.has(words[head] ?? "")) return []; + return words + .slice(head + 1) + .map((word) => namedPath(word.replace(/^--?[\w.-]+=/u, "").replace(/^["']|["']$/gu, ""), document)); +} +// Lines of fenced shell blocks (```bash, ```sh, ```shell, ```console or no +// language), which is where most documented commands are. +function fencedCommands(text: string): string[] { + const commands: string[] = []; + let fence: string | null = null; + for (const line of text.split("\n")) { + const marker = /^\s*```(\w*)/u.exec(line); + if (marker) { + fence = fence === null ? (marker[1] ?? "") : null; + continue; + } + if (fence !== null && /^(?:bash|sh|shell|console|zsh)?$/u.test(fence)) commands.push(line); + } + return commands; } const index = await readFile(DOCUMENT_INDEX, "utf8").catch(() => ""); @@ -239,18 +280,42 @@ for (const document of contractDocuments) { if (text === null) { // A linked document that is gone is reported as the index's broken link. if (document === DOCUMENT_INDEX) { - documentReferences.push({ path: document, missingPaths: [document], missingScripts: [], unknownGateIds: [] }); + documentReferences.push({ + path: document, + missingPaths: [document], + unverifiedLinks: [], + missingScripts: [], + unknownGateIds: [], + }); } continue; } const named = [ - ...[...text.matchAll(/`([^`\n]+)`/gu)].map(([, token = ""]) => namedPath(token, document)), + ...[...text.matchAll(/`([^`\n]+)`/gu)].flatMap(([, token = ""]) => [ + namedPath(token, document), + ...commandPaths(token, document), + ]), + ...fencedCommands(text).flatMap((command) => commandPaths(command, document)), ...[...text.matchAll(/\]\(([^)\s]+)\)/gu)].map(([, target = ""]) => linkedPath(target, document)), ]; const missingPaths = new Set(); + const unverifiedLinks = new Set(); for (const file of named) { if (file === null) continue; const trimmed = file.replace(/\/$/u, ""); + if (trimmed.startsWith("../")) { + // Outside this repository: the first folder past the `..` steps is the + // paired checkout. Without it the reference cannot be checked here. + const segments = trimmed.split("/"); + const checkout = segments.slice(0, segments.findIndex((segment) => segment !== "..") + 1).join("/"); + const relativeToSiblings = trimmed.replace(/^\.\.\//u, ""); + if (!existsSync(resolve(siblingsRoot, checkout.replace(/^\.\.\//u, "")))) { + unverifiedLinks.add(trimmed); + } else if (!existsSync(resolve(siblingsRoot, relativeToSiblings))) { + missingPaths.add(trimmed); + } + continue; + } if ( !exists(trimmed) && !NOT_CREATED.has(trimmed) && @@ -270,6 +335,7 @@ for (const document of contractDocuments) { documentReferences.push({ path: document, missingPaths: [...missingPaths].sort(), + unverifiedLinks: [...unverifiedLinks].sort(), missingScripts: [...missingScripts].sort(), unknownGateIds: [...new Set([...text.matchAll(/\bFE-GATE-\d+\b/gu)].map(([id]) => id))] .filter((id) => !gateIds.has(id)) @@ -370,4 +436,11 @@ if (!passed) { ); process.exit(1); } +const unverified = documentReferences.flatMap((entry) => entry.unverifiedLinks); +if (unverified.length > 0) { + process.stdout.write( + `Documentation readiness: ${unverified.length} reference(s) into paired repositories not verified ` + + `(no checkout beside ${process.cwd()}): ${[...new Set(unverified)].join(", ")}\n`, + ); +} process.stdout.write("Documentation readiness: PASS_SCOPED\n"); diff --git a/tests/unit/documentation-readiness.test.ts b/tests/unit/documentation-readiness.test.ts index f639b9aa..d5962b37 100644 --- a/tests/unit/documentation-readiness.test.ts +++ b/tests/unit/documentation-readiness.test.ts @@ -1,5 +1,5 @@ import { spawnSync } from "node:child_process"; -import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; @@ -10,26 +10,38 @@ const INPUTS = ["README.md", "docs", "artifacts/tests/a11y-manual"]; /** * Runs verify:documentation on a copy of its inputs, each `changes` entry * applied to its document and every `removed` file deleted. Code facts (src, - * package.json, gates.json) are read from this repository, not the copy. + * package.json, gates.json) are read from this repository, not the copy. The + * copy is a `frontend` folder; `siblings` are files written beside it, where a + * checkout of the paired repositories would be. */ async function verify( changes: Readonly string>>, removed: readonly string[] = [], + siblings: Readonly> = {}, ) { - const root = await mkdtemp(path.join(tmpdir(), "documentation-readiness-")); + const parent = await mkdtemp(path.join(tmpdir(), "documentation-readiness-")); + const root = path.join(parent, "frontend"); try { + for (const [file, content] of Object.entries(siblings)) { + await mkdir(path.dirname(path.join(parent, file)), { recursive: true }); + await writeFile(path.join(parent, file), content); + } for (const input of INPUTS) await cp(input, path.join(root, input), { recursive: true }); for (const [document, mutate] of Object.entries(changes)) { const target = path.join(root, document); await writeFile(target, mutate(await readFile(target, "utf8"))); } for (const file of removed) await rm(path.join(root, file)); - return spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], { + const result = spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], { cwd: root, encoding: "utf8", }); + const report = await readFile(path.join(root, "artifacts/quality/documentation-review.json"), "utf8") + .then((json) => JSON.parse(json) as { documentReferences: { path: string; unverifiedLinks?: string[] }[] }) + .catch(() => null); + return { ...result, report }; } finally { - await rm(root, { recursive: true, force: true }); + await rm(parent, { recursive: true, force: true }); } } @@ -128,6 +140,62 @@ describe("verify:documentation current contract documents (1101/14-05)", () => { }); }); +// 1103/12-05. Paths inside a command and links into the paired repositories +// were never looked up: a deleted V2 test stayed in a `vitest run` command, +// and a broken link to the backend template's contract passed. +describe("verify:documentation commands and sibling links (1103/12-05)", () => { + const CI_DOC = "docs/operations/ci-quality-gates.md"; + const BACKEND = "clean-architecture-backend-template/docs/web/http-contract.md"; + + it.each([ + ["an inline command", "`corepack pnpm exec vitest run tests/integration/no-such-client.test.ts`"], + ["a shell block", "```bash\nnode tests/integration/no-such-client.test.ts --flag\n```"], + ])("fails when %s names a path that does not exist", async (_shape, line) => { + const result = await verify({ [CI_DOC]: (text) => `${text}\n${line}\n` }); + expect(result.status).toBe(1); + expect(result.stderr).toContain(`${CI_DOC} names paths that do not exist: tests/integration/no-such-client.test.ts`); + }); + + it("looks up a command's existing arguments and leaves placeholders alone", async () => { + const result = await verify({ + [CI_DOC]: (text) => `${text}\n\`corepack pnpm exec vitest run tests/unit/documentation-readiness.test.ts -t "x"\`\n` + + "```bash\ncorepack pnpm drill:runbook -- FE-RB-005 --release-root \n```\n", + }); + expect(result.status, result.stderr).toBe(0); + }); + + it("checks a link or a path into a paired repository checked out beside this one", async () => { + const naming = (target: string) => (text: string) => + `${text}\n[contract](../../../${target}) and \`${target}\`\n`; + const present = await verify( + { [CI_DOC]: naming(BACKEND) }, + [], + { [BACKEND]: "# contract\n" }, + ); + expect(present.status, present.stderr).toBe(0); + + const broken = await verify( + { [CI_DOC]: naming("clean-architecture-backend-template/docs/web/no-such.md") }, + [], + { [BACKEND]: "# contract\n" }, + ); + expect(broken.status).toBe(1); + expect(broken.stderr).toContain( + `${CI_DOC} names paths that do not exist: ../clean-architecture-backend-template/docs/web/no-such.md`, + ); + }); + + it("reports a link into a paired repository that is not checked out as unverified", async () => { + const result = await verify({ + [CI_DOC]: (text) => `${text}\n[contract](../../../clean-architecture-backend-template/docs/web/no-such.md)\n`, + }); + expect(result.status, result.stderr).toBe(0); + expect(result.stdout).toContain("not verified"); + expect(result.report?.documentReferences.find((entry) => entry.path === CI_DOC)?.unverifiedLinks) + .toEqual(["../clean-architecture-backend-template/docs/web/no-such.md"]); + }); +}); + // 1101/14-03. The entry documents drew a top-level domain layer that does not // exist, left out three of the nine src folders, and layers.md named a // minority of the architecture rules while claiming it could not drift.