fix(docs): 문서 검사가 짝 백엔드 참조를 pin 커밋의 트리에서 찾는다

문제
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 <pin>`으로 그 커밋의
  트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 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
This commit is contained in:
DongHyeonka
2026-11-05 22:29:19 +09:00
parent a793b83e82
commit fc95672ad5
5 changed files with 225 additions and 41 deletions
+5 -2
View File
@@ -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`다.
+3 -1
View File
@@ -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 밖에
있으므로 이 항목은 구조가 바뀌어도 통과한다
+3 -2
View File
@@ -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),
+71 -18
View File
@@ -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 (`<name>/docs/…`) or
// link (`../../../<name>/…`). 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
// (`<name>/docs/…`) or link (`../../../<name>/…`) 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<string, string>();
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<string> }> | Readonly<{ unverified: string }>;
const pairedTrees = new Map<string, PairedTree>();
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` (`../<name>/<path>`) 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: `../<paired repository>/<path at its pin>`.
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");
+143 -18
View File
@@ -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<Record<string, (text: string) => 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<Record<string, (text: string) => string>>,
changes: Changes,
removed: readonly string[] = [],
siblings: Readonly<Record<string, string>> = {},
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<Record<string, string | null>>[],
uncommitted: Readonly<Record<string, string>> = {},
): string[] {
const root = path.join(parent, PAIRED_BACKEND);
const write = (files: Readonly<Record<string, string | null>>) => {
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<ReturnType<typeof verify>>) =>
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.