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
+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");