fix(docs): 문서 검사가 명령 안 경로와 짝 저장소 참조를 본다
문제 verify:documentation(FE-GATE-017)은 공백 없는 backtick 경로만 본다. 그래서 `corepack pnpm exec vitest run tests/…` 같은 명령 안의 경로, 셸 코드 블록의 명령, 저장소 밖(`../`) 링크는 확인하지 않았다. 실제로 원장 docs/operations/adapter-remediation-ledger.md의 N-06~N-08 행이 V2와 함께 지운 테스트 세 개를 실행하라고 적고 있었다. 짝 백엔드 정본 링크가 깨져도 알 수 없었다. config/ci/ungated-scripts.json의 check:remediation-ledger 사유는 "It passes at this commit"이라는 시점 문장을 담았다. 고른 방법 - 인라인 코드와 셸 코드 블록(```bash/sh/shell/console/zsh, 언어 없음)에서 명령(corepack, pnpm, npx, node, vitest, playwright, tsc, eslint, bash, sh)의 인자를 같은 경로 규칙으로 본다. 앞의 NAME=value는 건너뛰고, --flag=value는 값만 본다. 자리표시자(<id>, glob, $VAR)는 기존 규칙대로 경로로 보지 않는다. - 짝 백엔드 템플릿(clean-architecture-backend-template)을 가리키는 backtick 경로와 저장소 밖 링크는 문서를 읽는 checkout 옆에서 찾는다. 그 checkout이 있으면 없는 경로는 실패다. 없으면(CI, 중첩 worktree) 실패 대신 "not verified"로 출력하고 보고서 documentReferences[].unverifiedLinks에 남긴다. 보고서 schema에 그 칸을 더했다. - 원장 N-06~N-08 행의 명령을 LEG-01 행처럼 "V2와 함께 지움"으로 바꾸고, ungated 사유에서 시점 문장을 지웠다. docs/README.md 1절의 검사 범위 설명을 고쳤다. - 버린 대안: 지운 심볼 이름 검사. 지운 이름 목록을 따로 관리해야 하고 오탐이 많다(리뷰 5.2절). 1절 밖 문서로 대상 넓히기. 기록 문서가 일부러 옛 경로를 적어 예외가 늘어난다. 위험·한계 - 명령 머리 목록에 없는 명령(git, curl 등)의 인자는 여전히 보지 않는다. - 짝 저장소 참조는 CI에서 늘 "not verified"다. 실제 확인은 옆에 checkout이 있는 개발 환경에서만 된다. - 1절 밖 문서(testing strategy :765, VD-23)는 그대로 검사 밖이다. 검증 - RED: 새 테스트 4건(인라인 명령, 셸 블록, 짝 저장소 있음·깨짐, 짝 저장소 없음 보고) 실패. - 수정 뒤 documentation-readiness 19건 통과. 저장소에서 수정 전 원장 행 3개가 "names paths that do not exist"로 잡혔고, 행을 고친 뒤 verify:documentation PASS_SCOPED(worktree라 짝 저장소 참조 3건은 not verified). check:remediation-ledger PASS, check:ci PASS, check:types 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
This commit is contained in:
@@ -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),
|
||||
})
|
||||
|
||||
@@ -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 (`<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"]);
|
||||
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
|
||||
// (`../<name>/…`).
|
||||
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 (`<id>`,
|
||||
// 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<string>();
|
||||
const unverifiedLinks = new Set<string>();
|
||||
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");
|
||||
|
||||
Reference in New Issue
Block a user