From fc95672ad5eeb2520dda06a97064da34dcc55c0b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:29:19 +0900 Subject: [PATCH] =?UTF-8?q?fix(docs):=20=EB=AC=B8=EC=84=9C=20=EA=B2=80?= =?UTF-8?q?=EC=82=AC=EA=B0=80=20=EC=A7=9D=20=EB=B0=B1=EC=97=94=EB=93=9C=20?= =?UTF-8?q?=EC=B0=B8=EC=A1=B0=EB=A5=BC=20pin=20=EC=BB=A4=EB=B0=8B=EC=9D=98?= =?UTF-8?q?=20=ED=8A=B8=EB=A6=AC=EC=97=90=EC=84=9C=20=EC=B0=BE=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의 작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은 옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1, 짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면 pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는 "확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지 않았다. 고른 방법 - 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이 작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서). - 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t `으로 그 커밋의 트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다. hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다. - checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신 unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다. - `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다. 실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다. - 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만 pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다 `git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다. 위험·한계 - pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부 "not verified"다. 실패하지 않는 대신 확인도 하지 않는다. - 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터 바꿔야 한다. - pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다. - 보고서 schema는 그대로다(unverifiedLinks 주석만 고침). 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED + not verified 기대). - RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or the working tree", "reports the references as not verified when the checkout does not have the pinned commit", "fails a link out of the repository into a repository that is not paired". Refs: 1105/12-02 --- docs/README.md | 7 +- docs/operations/ci-quality-gates.md | 4 +- scripts/contracts/release-artifacts.ts | 5 +- scripts/verify-documentation-readiness.ts | 89 +++++++++--- tests/unit/documentation-readiness.test.ts | 161 ++++++++++++++++++--- 5 files changed, 225 insertions(+), 41 deletions(-) diff --git a/docs/README.md b/docs/README.md index 6435d08c..f2f541aa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,8 +43,11 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어 `verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에 적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와 셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의 -경로와 링크는 그 checkout이 이 checkout 옆에 있을 때만 확인하고, 없으면 실패 대신 확인하지 -못한 것으로 출력과 `artifacts/quality/documentation-review.json`에 남긴다. `CHANGELOG.md`는 +경로와 링크는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다. +이 checkout 옆에 있는 짝 checkout의 git 기록을 읽고, 그 작업 트리와 HEAD는 보지 않는다. 짝 +checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 것으로 출력과 +`artifacts/quality/documentation-review.json`에 남긴다. repo 밖으로 나가는 링크가 짝 저장소를 +가리키지 않으면(저장소 이름 오타 포함) 실패한다. `CHANGELOG.md`는 지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은 없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은 `scripts/verify-documentation-readiness.ts`다. diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 511689b1..6aed2f98 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -132,7 +132,9 @@ DOCUMENTATION_READY (off-chain) - 입구 문서가 실제 `src` 최상위 폴더와 `.dependency-cruiser.json` 규칙 이름을 적는지 - `docs/README.md` 1절의 현재 계약 문서에 적힌 repo 경로·링크·package script· - FE-GATE ID가 실제로 있는지 + FE-GATE ID가 실제로 있는지. 짝 백엔드 경로는 옆 checkout의 작업 트리가 아니라 + `config/contracts/backend-contract-pin.json`이 고정한 커밋에서 찾고, 그 커밋을 + 읽을 수 없으면 확인하지 못한 것으로 남긴다 - 2026-07-18 diagram 리뷰 기록의 두 사본(`docs/architecture/review-ledger.json`, `review-evidence.md`)이 같은 해시·점수를 담는지. 원본 diagram은 repo 밖에 있으므로 이 항목은 구조가 바뀌어도 통과한다 diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index a40de465..27653330 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -1442,8 +1442,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. + // 1103/12-05, 1105/12-02. References into a paired repository + // whose pinned commit cannot be read beside this checkout (no + // checkout, or one without that commit). 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 18fbcd9a..7fda24b5 100644 --- a/scripts/verify-documentation-readiness.ts +++ b/scripts/verify-documentation-readiness.ts @@ -1,3 +1,4 @@ +import { spawnSync } from "node:child_process"; import { existsSync } from "node:fs"; import { mkdir, readdir, readFile } from "node:fs/promises"; import { dirname, join, matchesGlob, normalize, resolve } from "node:path/posix"; @@ -207,12 +208,58 @@ const deletedHistory = [ .flatMap(([, cell = ""]) => [...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, ""))) .filter((entry) => !exists(entry)); -// 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"]); +// 1103/12-05, 1105/12-02. The paired templates a document may name +// (`/docs/…`) or link (`../../..//…`) are the ones +// config/contracts/backend-contract-pin.json pins. It is read with the +// documents, since it says which commit they describe. A reference is looked +// up in the tree of the pinned commit, read from the object store of the +// checkout beside the documents, never from that checkout's working tree or +// HEAD: those differ per machine, and the same commit failed on one whose +// sibling was months behind with uncommitted changes and passed elsewhere. +// Where the checkout or the pinned commit is missing (CI, a nested worktree, a +// stale clone) the reference is reported as not verified. A link that leaves +// the repository for anything else is broken (a misspelled repository too). +const PAIRED_PIN = "config/contracts/backend-contract-pin.json"; +const pairedPins = new Map(); +const pairedPin = await readFile(PAIRED_PIN, "utf8").catch(() => null); +if (pairedPin !== null) { + const { backend } = JSON.parse(pairedPin) as { backend: { repository: string; commit: string } }; + pairedPins.set(backend.repository, backend.commit); +} const siblingsRoot = resolve(process.cwd(), ".."); +type PairedTree = Readonly<{ paths: ReadonlySet }> | Readonly<{ unverified: string }>; +const pairedTrees = new Map(); +function readPairedTree(repository: string, commit: string): PairedTree { + const checkout = resolve(siblingsRoot, repository); + if (!existsSync(join(checkout, ".git"))) return { unverified: `no checkout at ${checkout}` }; + // The checkout's own repository only: a GIT_DIR set by a hook would point + // git at another one. + const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_"))); + const git = (...args: string[]) => + spawnSync("git", ["-C", checkout, ...args], { encoding: "utf8", env, maxBuffer: 64 * 1024 * 1024 }); + if (git("cat-file", "-e", `${commit}^{commit}`).status !== 0) { + const head = git("rev-parse", "--short=12", "HEAD"); + return { + unverified: `${checkout} at HEAD ${head.status === 0 ? head.stdout.trim() : "(unreadable)"} does not have the pinned commit; fetch it to check these`, + }; + } + const listing = git("ls-tree", "-r", "-t", "-z", "--name-only", commit); + if (listing.status !== 0) return { unverified: `git ls-tree failed in ${checkout}: ${listing.stderr.trim()}` }; + return { paths: new Set(listing.stdout.split("\0").filter((entry) => entry !== "")) }; +} +/** Whether `reference` (`..//`) is in the pinned tree, or null when it cannot be checked here. */ +function pairedReferenceExists(reference: string): boolean | null { + const [, repository = "", ...inside] = reference.split("/"); + const commit = pairedPins.get(repository); + if (commit === undefined) return false; + let tree = pairedTrees.get(repository); + if (tree === undefined) { + tree = readPairedTree(repository, commit); + pairedTrees.set(repository, tree); + } + if ("unverified" in tree) return null; + return inside.length === 0 || tree.paths.has(inside.join("/")); +} // 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 @@ -223,13 +270,13 @@ function namedPath(token: string, document: string): string | null { 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}`; + if (pairedPins.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. +// in the paired repositories. function linkedPath(target: string, document: string): string | null { if (/^(?:[a-z][a-z+.-]*:|#)/iu.test(target)) return null; return normalize(join(dirname(document), target.replace(/#.*$/u, ""))); @@ -304,16 +351,10 @@ for (const document of contractDocuments) { 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); - } + // Outside this repository: `..//`. + const found = pairedReferenceExists(trimmed); + if (found === null) unverifiedLinks.add(trimmed); + else if (!found) missingPaths.add(trimmed); continue; } if ( @@ -416,6 +457,15 @@ if (!passed) { ); } } + if (documentReferences.some((entry) => entry.missingPaths.some((file) => file.startsWith("../")))) { + const checked = [...pairedTrees] + .filter(([, tree]) => "paths" in tree) + .map(([repository]) => `${repository} ${pairedPins.get(repository)?.slice(0, 12)}`); + process.stderr.write( + `A path outside this repository must be in a repository ${PAIRED_PIN} pins, at the pinned commit` + + `${checked.length > 0 ? ` (looked up in ${checked.join(", ")})` : ""}\n`, + ); + } if (!reportDigestValid) { process.stderr.write( `${ledger.evidenceReport.repoPath} does not contain the ledger's canonicalSha256\n`, @@ -438,9 +488,12 @@ if (!passed) { } const unverified = documentReferences.flatMap((entry) => entry.unverifiedLinks); if (unverified.length > 0) { + const reasons = [...pairedTrees].flatMap(([repository, tree]) => + "unverified" in tree ? [`${repository} pinned at ${pairedPins.get(repository)?.slice(0, 12)}: ${tree.unverified}`] : [], + ); process.stdout.write( `Documentation readiness: ${unverified.length} reference(s) into paired repositories not verified ` + - `(no checkout beside ${process.cwd()}): ${[...new Set(unverified)].join(", ")}\n`, + `(${reasons.join("; ")}): ${[...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 1163684a..ea9a5dd2 100644 --- a/tests/unit/documentation-readiness.test.ts +++ b/tests/unit/documentation-readiness.test.ts @@ -1,33 +1,36 @@ import { spawnSync } from "node:child_process"; -import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; -import { tmpdir } from "node:os"; +import { mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { devNull, tmpdir } from "node:os"; import path from "node:path"; import { describe, expect, it } from "vitest"; -const INPUTS = ["README.md", "docs", "artifacts/tests/a11y-manual"]; +// The pin says which commit of the paired backend the documents describe. +const INPUTS = ["README.md", "docs", "artifacts/tests/a11y-manual", "config/contracts/backend-contract-pin.json"]; +const PAIRED_BACKEND = "clean-architecture-backend-template"; + +type Changes = Readonly string>>; /** * 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. The - * copy is a `frontend` folder; `siblings` are files written beside it, where a - * checkout of the paired repositories would be. + * copy is a `frontend` folder; `paired` builds what sits beside it, where a + * checkout of the paired repositories would be, and returns more changes (a + * pin to its commit). */ async function verify( - changes: Readonly string>>, + changes: Changes, removed: readonly string[] = [], - siblings: Readonly> = {}, + paired: (parent: string) => Changes = () => ({}), ) { 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); - } + const pairedChanges = paired(parent); for (const input of INPUTS) await cp(input, path.join(root, input), { recursive: true }); - for (const [document, mutate] of Object.entries(changes)) { + for (const [document, mutate] of Object.entries({ ...changes, ...pairedChanges })) { const target = path.join(root, document); await writeFile(target, mutate(await readFile(target, "utf8"))); } @@ -51,6 +54,63 @@ function verifyWithReadme(mutate: (readme: string) => string, document = "README return verify({ [document]: mutate }); } +const gitEnvironment = { + ...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_"))), + GIT_CONFIG_GLOBAL: devNull, + GIT_CONFIG_NOSYSTEM: "1", +}; +function git(cwd: string, ...args: string[]): string { + const result = spawnSync( + "git", + ["-c", "user.name=fixture", "-c", "user.email=fixture@example.invalid", "-c", "commit.gpgsign=false", ...args], + { cwd, encoding: "utf8", env: gitEnvironment }, + ); + if (result.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${result.stderr}`); + return result.stdout.trim(); +} + +/** + * A git checkout of the paired backend beside the copy: one commit per + * `history` entry (a file set to null is deleted), then `uncommitted` written + * to its working tree. Returns the commit ids. + */ +function pairedCheckout( + parent: string, + history: readonly Readonly>[], + uncommitted: Readonly> = {}, +): string[] { + const root = path.join(parent, PAIRED_BACKEND); + const write = (files: Readonly>) => { + for (const [file, content] of Object.entries(files)) { + const target = path.join(root, file); + if (content === null) { + rmSync(target); + } else { + mkdirSync(path.dirname(target), { recursive: true }); + writeFileSync(target, content); + } + } + }; + mkdirSync(root, { recursive: true }); + git(root, "init", "-q"); + const commits: string[] = []; + for (const files of history) { + write(files); + git(root, "add", "-A"); + git(root, "commit", "-q", "--allow-empty", "-m", `fixture ${commits.length}`); + commits.push(git(root, "rev-parse", "HEAD")); + } + write(uncommitted); + return commits; +} + +function pinnedTo(commit: string): Changes { + return { + "config/contracts/backend-contract-pin.json": (pin) => + pin.replace(/"commit": "[0-9a-f]+"/u, `"commit": "${commit}"`), + }; +} + // 1101/14-06. A route missing from a scope document used to fail with only // "canonical scoped-review evidence is incomplete", which points at the // diagram review instead of the file to fix. @@ -171,11 +231,10 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => { 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" }, - ); + // 1105/12-02. The checkout is looked up at the pinned commit. + const pinnedBackend = (parent: string) => + pinnedTo(pairedCheckout(parent, [{ "docs/web/http-contract.md": "# contract\n" }])[0]!); + const present = await verify({ [CI_DOC]: naming(BACKEND) }, [], pinnedBackend); // Only this document is under test: other documents name paired-backend // paths the stub checkout does not have. expect(present.stderr).not.toContain(`${CI_DOC} names paths that do not exist`); @@ -186,7 +245,7 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => { const broken = await verify( { [CI_DOC]: naming("clean-architecture-backend-template/docs/web/no-such.md") }, [], - { [BACKEND]: "# contract\n" }, + pinnedBackend, ); expect(broken.status).toBe(1); expect(broken.stderr).toContain( @@ -205,6 +264,72 @@ describe("verify:documentation commands and sibling links (1103/12-05)", () => { }); }); +// 1105/12-02. Paired references were looked up in the working tree of the +// checkout beside this one, so the same commit failed on the desktop (a +// sibling months behind with uncommitted changes), passed with 17 references +// unverified where no sibling was, and a misspelled repository passed as +// unverified. They are looked up at the commit the pin names. +describe("verify:documentation paired references at the pinned commit (1105/12-02)", () => { + const CI_DOC = "docs/operations/ci-quality-gates.md"; + const naming = (...targets: string[]) => (text: string) => + `${text}\n${targets.map((target) => `[link](../../../${target}) and \`${target}\``).join("\n")}\n`; + const entryOf = (result: Awaited>) => + result.report?.documentReferences.find((entry) => entry.path === CI_DOC); + + it("looks a reference up in the pinned commit, not in a later HEAD or the working tree", async () => { + const result = await verify( + { + [CI_DOC]: naming( + `${PAIRED_BACKEND}/docs/web/http-contract.md`, + `${PAIRED_BACKEND}/docs/web/after-pin.md`, + `${PAIRED_BACKEND}/docs/web/uncommitted.md`, + ), + }, + [], + (parent) => { + const [pinned] = pairedCheckout( + parent, + [ + { "docs/web/http-contract.md": "# contract\n" }, + { "docs/web/http-contract.md": null, "docs/web/after-pin.md": "# later\n" }, + ], + { "docs/web/uncommitted.md": "# draft\n" }, + ); + return pinnedTo(pinned!); + }, + ); + // Other documents name paired paths the stub does not have, so only this + // document's entry is compared. + expect(entryOf(result)?.missingPaths).toEqual([ + `../${PAIRED_BACKEND}/docs/web/after-pin.md`, + `../${PAIRED_BACKEND}/docs/web/uncommitted.md`, + ]); + expect(entryOf(result)?.unverifiedLinks).toEqual([]); + expect(result.stderr).toContain("at the pinned commit (looked up in clean-architecture-backend-template "); + }); + + it("reports the references as not verified when the checkout does not have the pinned commit", async () => { + // The desktop case: a sibling whose history stops before the pin, with + // none of the files the documents name. + const result = await verify({ [CI_DOC]: naming(`${PAIRED_BACKEND}/docs/web/no-such.md`) }, [], (parent) => { + pairedCheckout(parent, [{ "README.md": "# an older backend\n" }]); + return {}; + }); + expect(result.status, result.stderr).toBe(0); + expect(entryOf(result)?.missingPaths).toEqual([]); + expect(entryOf(result)?.unverifiedLinks).toEqual([`../${PAIRED_BACKEND}/docs/web/no-such.md`]); + expect(result.stdout).toContain("not verified"); + expect(result.stdout).toContain("does not have the pinned commit"); + }); + + it("fails a link out of the repository into a repository that is not paired", async () => { + const misspelled = "clean-architecture-backend-templat/docs/web/http-contract.md"; + const result = await verify({ [CI_DOC]: (text) => `${text}\n[contract](../../../${misspelled})\n` }); + expect(result.status).toBe(1); + expect(result.stderr).toContain(`${CI_DOC} names paths that do not exist: ../${misspelled}`); + }); +}); + // 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.