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:
@@ -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),
|
||||
|
||||
@@ -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");
|
||||
|
||||
Reference in New Issue
Block a user