문제: `verify:documentation`은 명령 머리가 corepack·pnpm·node 같은 낱말일 때만 인자 경로를 보았다. 이 repo 문서의 명령 대부분은 `scripts/verify.sh exec -- node <경로>`, `scripts/verify.sh script <이름>`, `python3 scripts/…` 꼴이라, 그 안의 낡은 경로·없는 script 이름이 검사를 통과했다. 고친 것: `python3`를 명령 머리에 더하고, `scripts/verify.sh`는 그 자신을 경로로 보며 `exec --` 뒤를 다시 명령으로 읽고 `script` 뒤 낱말을 package script 이름으로 대조한다. 자리표시자(`<이름>`)와 `--` 뒤 인자는 보지 않는다. 위험·한계: 살아 있는 문서 전부가 지금 이 검사를 통과하는지는 desktop `verify:documentation`으로 확인한다. 검증: desktop `node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts` 24건 통과(새 시험 포함). 검사기를 기준 커밋으로 되돌리면 새 시험이 실패한다. Refs: 1112/08-06
622 lines
28 KiB
TypeScript
622 lines
28 KiB
TypeScript
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";
|
|
import { fileURLToPath } from "node:url";
|
|
|
|
import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts";
|
|
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
|
|
import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts";
|
|
import { checkDocsSystem, checkedForDrift, deletableHistory, HISTORY_HOLDERS, livingDocuments } from "./lib/docs-system.ts";
|
|
import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts";
|
|
import {
|
|
REMOVABLE_TEMPLATE_FEATURES,
|
|
removableTemplateFeaturePaths,
|
|
} from "./lib/removable-template-features.ts";
|
|
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
|
|
|
/**
|
|
* The manual accessibility review scope is one record per installed route.
|
|
* README and the checklist used to list the route IDs and this script checked
|
|
* the lists (they had said six routes while ten were registered). That made
|
|
* every new feature edit two template-owned documents (1101/14-05), so the
|
|
* documents now name this folder and the record files are what is checked.
|
|
*/
|
|
const MANUAL_A11Y_RECORDS = "docs/accessibility/route-reviews/";
|
|
|
|
type DocumentationReview = Readonly<{
|
|
sourcePath: string;
|
|
sha256: string;
|
|
thresholdSatisfied: boolean;
|
|
verdict: string;
|
|
score: number;
|
|
}>;
|
|
|
|
type ReviewLedger = Readonly<{
|
|
evidenceReport: Readonly<{
|
|
repoPath: string;
|
|
upstreamCanonicalPath: string;
|
|
canonicalSha256: string;
|
|
}>;
|
|
reviews: Record<string, DocumentationReview>;
|
|
reviewer: string;
|
|
standard: string;
|
|
status: string;
|
|
}>;
|
|
|
|
const ledger = JSON.parse(
|
|
await readFile("docs/architecture/review-ledger.json", "utf8"),
|
|
) as ReviewLedger;
|
|
const evidence = await readFile(ledger.evidenceReport.repoPath, "utf8");
|
|
const results = [];
|
|
for (const [diagram, review] of Object.entries(ledger.reviews)) {
|
|
const sourceReferenced = evidence.includes(review.sourcePath);
|
|
const digestReferenced =
|
|
/^[0-9a-f]{64}$/.test(review.sha256) &&
|
|
evidence.includes(review.sha256);
|
|
const scorePass =
|
|
review.thresholdSatisfied === true &&
|
|
review.verdict === "PASS" &&
|
|
typeof review.score === "number" &&
|
|
evidence.includes(`| ${review.score} | PASS |`);
|
|
results.push({
|
|
diagram,
|
|
sourcePath: review.sourcePath,
|
|
sha256: review.sha256,
|
|
sourceReferenced,
|
|
digestReferenced,
|
|
reviewer: ledger.reviewer,
|
|
score: review.score,
|
|
scorePass,
|
|
passed:
|
|
sourceReferenced &&
|
|
digestReferenced &&
|
|
ledger.reviewer === "wiki-diagram-reviewer" &&
|
|
ledger.standard === "rules/diagram-standards.md v2" &&
|
|
scorePass &&
|
|
ledger.status === "PASS_SCOPED",
|
|
});
|
|
}
|
|
const reportDigestValid =
|
|
/^[0-9a-f]{64}$/.test(ledger.evidenceReport.canonicalSha256) &&
|
|
evidence.includes(ledger.evidenceReport.canonicalSha256);
|
|
|
|
const missingRouteIds = MANUAL_A11Y_ROUTE_IDS.filter(
|
|
(routeId) => !existsSync(`${MANUAL_A11Y_RECORDS}${routeId}.md`),
|
|
).sort();
|
|
const routeScope = [
|
|
{ path: MANUAL_A11Y_RECORDS, missingRouteIds, documented: missingRouteIds.length === 0 },
|
|
];
|
|
const routeScopeDocumented = missingRouteIds.length === 0;
|
|
|
|
// 13-15. README is where a project learns how to build for production. It
|
|
// named none of the variables the build and admission read, so each one is
|
|
// required here, taken from the code that reads it where possible.
|
|
const RUNTIME_VARIABLES = Object.freeze([
|
|
"APP_PROFILE",
|
|
"RELEASE_TARGET",
|
|
"VITE_BUILD_ID",
|
|
"RELEASE_ID",
|
|
...Object.values(RUNTIME_OVERRIDES),
|
|
]);
|
|
const readme = await readFile("README.md", "utf8").catch(() => "");
|
|
const missingRuntimeVariables = RUNTIME_VARIABLES.filter(
|
|
(variable) => !readme.includes(`\`${variable}\``),
|
|
);
|
|
|
|
// 1101/14-03. The entry documents drew a `src/domain` layer that does not
|
|
// exist and left out `src/platform`, `src/apps` and `src/contexts`; layers.md
|
|
// said its table "cannot drift" from the rules while most rule names were
|
|
// missing. The folder and rule lists come from the code. layers.md describes
|
|
// each folder in one table row, and the other entry documents repeat that
|
|
// description verbatim as "`src/<folder>` — <description>", so a new folder or
|
|
// rule must be documented, the descriptions cannot diverge, and no document
|
|
// may name a top-level folder that is gone.
|
|
const RULES_DOCUMENT = "docs/architecture/layers.md";
|
|
const STRUCTURE_DOCUMENTS = Object.freeze([
|
|
RULES_DOCUMENT,
|
|
"README.md",
|
|
"docs/architecture/overview.md",
|
|
"docs/architecture/frontend-application-foundation.md",
|
|
]);
|
|
const repositoryRoot = new URL("../", import.meta.url);
|
|
const sourceFolders = (await readdir(new URL("src/", repositoryRoot), { withFileTypes: true }))
|
|
.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
|
|
.map((entry) => entry.name)
|
|
.sort();
|
|
const architectureRules = (
|
|
JSON.parse(await readFile(new URL(".dependency-cruiser.json", repositoryRoot), "utf8")) as {
|
|
forbidden: readonly { name: string }[];
|
|
}
|
|
).forbidden.map((rule) => rule.name);
|
|
const rulesText = await readFile(RULES_DOCUMENT, "utf8").catch(() => "");
|
|
const folderDescriptions = new Map(
|
|
[...rulesText.matchAll(/^\| `src\/([\w-]+)` \| (.+) \|$/gmu)].map((match) => [match[1], match[2]]),
|
|
);
|
|
const sourceStructure = [];
|
|
for (const path of STRUCTURE_DOCUMENTS) {
|
|
const text = path === RULES_DOCUMENT ? rulesText : await readFile(path, "utf8").catch(() => "");
|
|
const namedFolders = new Set([...text.matchAll(/\bsrc\/([\w-]+)/gu)].map((match) => match[1] ?? ""));
|
|
sourceStructure.push({
|
|
path,
|
|
missingFolders: sourceFolders.filter((folder) => {
|
|
const description = folderDescriptions.get(folder);
|
|
if (description === undefined) return true;
|
|
return path !== RULES_DOCUMENT && !text.includes(`\`src/${folder}\` — ${description}`);
|
|
}),
|
|
unknownFolders: [...namedFolders].filter((folder) => !sourceFolders.includes(folder)).sort(),
|
|
missingRules:
|
|
path === RULES_DOCUMENT ? architectureRules.filter((rule) => !text.includes(`\`${rule}\``)) : [],
|
|
});
|
|
}
|
|
const sourceStructureDocumented = sourceStructure.every(
|
|
(entry) =>
|
|
entry.missingFolders.length === 0 &&
|
|
entry.unknownFolders.length === 0 &&
|
|
entry.missingRules.length === 0,
|
|
);
|
|
|
|
// 1101/14-05. docs/README.md §1 says the gates check the current contract
|
|
// documents, while only the checks above did. Every repo path, package script
|
|
// and FE-GATE ID that the index and the documents its §1 links name must
|
|
// exist. Documents are read from the working directory; what they name is
|
|
// looked up in this repository, as for the src structure above.
|
|
const DOCUMENT_INDEX = "docs/README.md";
|
|
// Past states are their subject: they name removed scripts and paths on purpose
|
|
// (HISTORY_HOLDERS in scripts/lib/docs-system.ts says which and why).
|
|
const UNCHECKED_DOCUMENTS = HISTORY_HOLDERS;
|
|
const NOT_CREATED = new Set([
|
|
// Reserved by generic-worker-has-no-network-or-credentials. The generic CPU
|
|
// worker is NOT_SELECTED; docs/manual/03-outside-feature-folder.md says how
|
|
// to add it with its own tsconfig.
|
|
"src/adapters/web-worker",
|
|
]);
|
|
// pnpm's own commands, which are not package scripts.
|
|
const PNPM_COMMANDS = new Set(["add", "dlx", "exec", "install", "list", "why"]);
|
|
|
|
const rootDirectory = fileURLToPath(repositoryRoot);
|
|
const exists = (file: string) => existsSync(join(rootDirectory, file));
|
|
const topLevelEntries = new Set(await readdir(rootDirectory));
|
|
const scripts = new Set(
|
|
Object.keys(
|
|
(JSON.parse(await readFile(join(rootDirectory, "package.json"), "utf8")) as { scripts: Record<string, string> })
|
|
.scripts,
|
|
),
|
|
);
|
|
const scriptPrefixes = new Set([...scripts].map((name) => name.split(":")[0]));
|
|
const gateIds = new Set([
|
|
...(
|
|
JSON.parse(await readFile(join(rootDirectory, "config/ci/gates.json"), "utf8")) as { gates: { id: string }[] }
|
|
).gates.map((gate) => gate.id),
|
|
...RETIRED_GATE_IDS,
|
|
]);
|
|
// 1105/14-01. A copy may delete the sample features listed in
|
|
// scripts/lib/removable-template-features.ts (the template lists none since
|
|
// 2026-11-07). The documents may name a sample's paths: while it is installed
|
|
// (its feature-module.ts exists), its paths and scripts are checked like any
|
|
// other; once it is not, they are not drift. A misspelt feature folder is not
|
|
// on the list and still fails.
|
|
const removedTemplateFeatures = REMOVABLE_TEMPLATE_FEATURES.filter(
|
|
(feature) => !exists(`src/features/${feature.featureId}/feature-module.ts`),
|
|
);
|
|
const removedTemplateFeaturePaths = removedTemplateFeatures.flatMap((feature) =>
|
|
removableTemplateFeaturePaths(feature),
|
|
);
|
|
const removedTemplateFeatureScripts = new Set(removedTemplateFeatures.flatMap((feature) => feature.scripts));
|
|
function missingScript(name: string): boolean {
|
|
return !scripts.has(name) && !removedTemplateFeatureScripts.has(name);
|
|
}
|
|
// Generated output is what git ignores, so a document may name it before a
|
|
// run has written it.
|
|
const ignorePatterns = (await readFile(join(rootDirectory, ".gitignore"), "utf8").catch(() => ""))
|
|
.split("\n")
|
|
.map((line) => line.trim())
|
|
.filter((line) => line !== "" && !line.startsWith("#"));
|
|
function generated(file: string): boolean {
|
|
let ignored = false;
|
|
for (const line of ignorePatterns) {
|
|
const pattern = line.replace(/^!/u, "").replace(/^\/|\/$/gu, "");
|
|
const glob = pattern.includes("/") ? pattern : `**/${pattern}`;
|
|
if (matchesGlob(file, glob) || matchesGlob(file, `${glob}/**`)) ignored = !line.startsWith("!");
|
|
}
|
|
return ignored;
|
|
}
|
|
// A copy may delete the history README lists under 「복사한 뒤 지워도 되는
|
|
// 것」. A path under an entry that is gone is not drift.
|
|
const deletedHistory = deletableHistory(readme).filter((entry) => !exists(entry));
|
|
|
|
// 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
|
|
// 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, "");
|
|
// An ellipsis, `...` or `…`, stands for any name, as in scripts/lib/docs-system.ts.
|
|
if (!candidate.includes("/") || candidate.startsWith("/") || /[\s*<>{}$()|…]|\.\.\./u.test(candidate)) return null;
|
|
const first = candidate.split("/")[0] ?? "";
|
|
if (topLevelEntries.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
|
|
// 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, "")));
|
|
}
|
|
// 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", "python3",
|
|
]);
|
|
// 1112/08-06. `scripts/verify.sh` is this repository's main entry and most
|
|
// documented commands go through it: the entry is itself a path, `exec --`
|
|
// runs a command whose paths are looked up like any other, and `script`
|
|
// names package scripts (verifyScripts).
|
|
const VERIFY_ENTRY = /^(?:\.\/)?scripts\/verify\.sh$/u;
|
|
function commandWords(command: string): Readonly<{ words: string[]; head: number }> {
|
|
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;
|
|
return { words, head };
|
|
}
|
|
function commandPaths(command: string, document: string): (string | null)[] {
|
|
const { words, head } = commandWords(command);
|
|
const first = words[head] ?? "";
|
|
if (VERIFY_ENTRY.test(first)) {
|
|
const separator = words.indexOf("--", head + 1);
|
|
const executed = words[head + 1] === "exec" && separator > head ? words.slice(separator + 1).join(" ") : "";
|
|
return [namedPath(first, document), ...(executed === "" ? [] : commandPaths(executed, document))];
|
|
}
|
|
if (!COMMAND_HEADS.has(first)) return [];
|
|
return words
|
|
.slice(head + 1)
|
|
.map((word) => namedPath(word.replace(/^--?[\w.-]+=/u, "").replace(/^["']|["']$/gu, ""), document));
|
|
}
|
|
/** The package scripts `scripts/verify.sh script <name>… [-- args]` runs; placeholders are left alone. */
|
|
function verifyScripts(command: string): string[] {
|
|
const { words, head } = commandWords(command);
|
|
if (!VERIFY_ENTRY.test(words[head] ?? "") || words[head + 1] !== "script") return [];
|
|
const names: string[] = [];
|
|
for (const word of words.slice(head + 2)) {
|
|
if (word.startsWith("-")) break;
|
|
names.push(word);
|
|
}
|
|
return names.filter((name) => /^[a-z](?:[\w:-]*\w)?$/u.test(name));
|
|
}
|
|
// 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(() => "");
|
|
const contractDocuments = new Set([DOCUMENT_INDEX]);
|
|
for (const [, target = ""] of (index.match(/^## 1\.[\s\S]*?(?=^## )/mu)?.[0] ?? "").matchAll(/\]\(([^)#\s]+)\)/gu)) {
|
|
const linked = normalize(join(dirname(DOCUMENT_INDEX), target));
|
|
const entries = await readdir(linked).catch(() => null);
|
|
const documents =
|
|
entries === null ? [linked] : entries.filter((name) => name.endsWith(".md")).map((name) => join(linked, name));
|
|
for (const document of documents) if (!UNCHECKED_DOCUMENTS.has(document)) contractDocuments.add(document);
|
|
}
|
|
// docs-system.md K3: every living document names only paths, scripts and
|
|
// gate IDs that exist, not only the ones the index links. Records keep the
|
|
// paths of the time they were written (scripts/lib/docs-system.ts).
|
|
for (const document of livingDocuments(process.cwd())) {
|
|
if (!UNCHECKED_DOCUMENTS.has(document)) contractDocuments.add(document);
|
|
}
|
|
const documentReferences = [];
|
|
for (const document of contractDocuments) {
|
|
const text = await readFile(document, "utf8").catch(() => null);
|
|
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],
|
|
unverifiedLinks: [],
|
|
missingScripts: [],
|
|
unknownGateIds: [],
|
|
});
|
|
}
|
|
continue;
|
|
}
|
|
const named = [
|
|
...[...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: `../<paired repository>/<path at its pin>`.
|
|
const found = pairedReferenceExists(trimmed);
|
|
if (found === null) unverifiedLinks.add(trimmed);
|
|
else if (!found) missingPaths.add(trimmed);
|
|
continue;
|
|
}
|
|
if (
|
|
!exists(trimmed) &&
|
|
!NOT_CREATED.has(trimmed) &&
|
|
!generated(trimmed) &&
|
|
!deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) &&
|
|
!removedTemplateFeaturePaths.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`))
|
|
) {
|
|
missingPaths.add(trimmed);
|
|
}
|
|
}
|
|
const missingScripts = new Set<string>();
|
|
for (const [, name = ""] of text.matchAll(/(?:corepack pnpm|`pnpm) (?:run )?([a-z](?:[\w:-]*\w)?)/gu)) {
|
|
if (!PNPM_COMMANDS.has(name) && missingScript(name)) missingScripts.add(name);
|
|
}
|
|
for (const [, name = ""] of text.matchAll(/`([a-z][\w-]*:[\w:-]*\w)(?=[` ])/gu)) {
|
|
if (scriptPrefixes.has(name.split(":")[0]) && missingScript(name)) missingScripts.add(name);
|
|
}
|
|
const commands = [...[...text.matchAll(/`([^`\n]+)`/gu)].map(([, token = ""]) => token), ...fencedCommands(text)];
|
|
for (const name of commands.flatMap(verifyScripts)) {
|
|
if (missingScript(name)) missingScripts.add(name);
|
|
}
|
|
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))
|
|
.sort(),
|
|
});
|
|
}
|
|
const documentReferencesValid = documentReferences.every(
|
|
(entry) => entry.missingPaths.length === 0 && entry.missingScripts.length === 0 && entry.unknownGateIds.length === 0,
|
|
);
|
|
|
|
// Repository layout rules of docs/manual/03-outside-feature-folder.md.
|
|
// R6: the manual's examples point at generator output or at code blocks in
|
|
// the manual, never at a sample feature a copy is meant to delete (the
|
|
// template's own sample took the manual's examples with it on 2026-11-07).
|
|
// R7: host, cluster and infrastructure configuration (nginx, Kubernetes,
|
|
// Helm, Terraform) lives in the infrastructure repository; a current document
|
|
// links to it and states the host contract (config/hosting/, FE-GATE-019)
|
|
// instead of carrying a copy. The history folders are records and keep what
|
|
// they recorded: the current documents are the living documents
|
|
// scripts/lib/docs-system.ts reads for drift (records and decision records out).
|
|
const INFRASTRUCTURE_FENCE = /^\s*```\s*(nginx|hcl|terraform|helm)\b/iu;
|
|
const INFRASTRUCTURE_MANIFEST =
|
|
/^\s*kind:\s*(Deployment|StatefulSet|DaemonSet|Ingress|Service|ConfigMap|CronJob|HelmRelease|Kustomization)\s*$/u;
|
|
const sampleFeaturePaths = REMOVABLE_TEMPLATE_FEATURES.flatMap((feature) => removableTemplateFeaturePaths(feature));
|
|
const currentDocuments = [
|
|
"README.md",
|
|
...((await readdir("docs", { recursive: true }).catch(() => [])) as string[])
|
|
.filter((name) => name.endsWith(".md"))
|
|
.map((name) => `docs/${name}`)
|
|
.filter(checkedForDrift),
|
|
].sort();
|
|
const layoutRuleViolations: { path: string; rule: "R6" | "R7"; detail: string }[] = [];
|
|
for (const document of currentDocuments) {
|
|
const text = await readFile(document, "utf8").catch(() => null);
|
|
if (text === null) continue;
|
|
let fenced = false;
|
|
text.split("\n").forEach((line, index) => {
|
|
if (/^\s*```/u.test(line)) fenced = !fenced;
|
|
if (INFRASTRUCTURE_FENCE.test(line) || (fenced && INFRASTRUCTURE_MANIFEST.test(line))) {
|
|
layoutRuleViolations.push({ path: document, rule: "R7", detail: `line ${index + 1}: ${line.trim()}` });
|
|
}
|
|
if (!document.startsWith("docs/manual/")) return;
|
|
for (const samplePath of sampleFeaturePaths) {
|
|
if (line.includes(samplePath)) {
|
|
layoutRuleViolations.push({ path: document, rule: "R6", detail: `line ${index + 1}: ${samplePath}` });
|
|
}
|
|
}
|
|
});
|
|
}
|
|
|
|
// docs-system.md K1, K2, K4-K6 and the polite-form rule: language, record
|
|
// head blocks, copied numbers, the documents map, README sections, style.
|
|
const documentsSystem = checkDocsSystem(process.cwd(), rootDirectory);
|
|
|
|
// 1101/14-06. Each failed check is named, so the stderr points at the file to
|
|
// fix rather than at the diagram review whatever failed. 1101/14-05: the last
|
|
// two only compare the two hand-kept copies of the 2026-07-18 diagram review;
|
|
// the diagrams are outside this repository, so they pass whatever the
|
|
// structure becomes, and their names say so.
|
|
const failedChecks = [
|
|
...(routeScopeDocumented ? [] : ["route scope"]),
|
|
...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]),
|
|
...(sourceStructureDocumented ? [] : ["source structure"]),
|
|
...(documentReferencesValid ? [] : ["document references"]),
|
|
...(layoutRuleViolations.length === 0 ? [] : ["repository layout rules"]),
|
|
...(reportDigestValid ? [] : ["2026-07-18 diagram review copy digest"]),
|
|
...(results.length === 2 && results.every((result) => result.passed)
|
|
? []
|
|
: ["2026-07-18 diagram review copies"]),
|
|
...(documentsSystem.failures.length === 0 ? [] : ["documents system"]),
|
|
];
|
|
const passed = failedChecks.length === 0;
|
|
await mkdir("artifacts/quality", { recursive: true });
|
|
await writeValidatedJsonArtifact({
|
|
path: "artifacts/quality/documentation-review.json",
|
|
schema: documentationReviewArtifactSchema,
|
|
value: {
|
|
schemaVersion: 1,
|
|
generatedAt: new Date().toISOString(),
|
|
status: ledger.status,
|
|
reviewer: ledger.reviewer,
|
|
standard: ledger.standard,
|
|
evidenceReport: ledger.evidenceReport,
|
|
reportDigestValid,
|
|
routeScope,
|
|
routeScopeDocumented,
|
|
missingRuntimeVariables,
|
|
sourceStructure,
|
|
documentReferences,
|
|
layoutRuleViolations,
|
|
results,
|
|
passed,
|
|
},
|
|
});
|
|
if (!passed) {
|
|
if (!routeScopeDocumented) {
|
|
process.stderr.write(`${MANUAL_A11Y_RECORDS} has no record for route IDs: ${missingRouteIds.join(", ")}\n`);
|
|
}
|
|
if (missingRuntimeVariables.length > 0) {
|
|
process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`);
|
|
}
|
|
for (const entry of sourceStructure) {
|
|
if (entry.missingFolders.length > 0) {
|
|
process.stderr.write(`${entry.path} does not describe src folders as the layers.md table does: ${entry.missingFolders.join(", ")}\n`);
|
|
}
|
|
if (entry.unknownFolders.length > 0) {
|
|
process.stderr.write(`${entry.path} names src folders that do not exist: ${entry.unknownFolders.join(", ")}\n`);
|
|
}
|
|
if (entry.missingRules.length > 0) {
|
|
process.stderr.write(
|
|
`${entry.path} does not name .dependency-cruiser.json rules: ${entry.missingRules.join(", ")}\n`,
|
|
);
|
|
}
|
|
}
|
|
for (const entry of documentReferences) {
|
|
if (entry.missingPaths.length > 0) {
|
|
process.stderr.write(`${entry.path} names paths that do not exist: ${entry.missingPaths.join(", ")}\n`);
|
|
}
|
|
if (entry.missingScripts.length > 0) {
|
|
process.stderr.write(`${entry.path} names package scripts that do not exist: ${entry.missingScripts.join(", ")}\n`);
|
|
}
|
|
if (entry.unknownGateIds.length > 0) {
|
|
process.stderr.write(
|
|
`${entry.path} names gate IDs that config/ci/gates.json does not define: ${entry.unknownGateIds.join(", ")}\n`,
|
|
);
|
|
}
|
|
}
|
|
for (const violation of layoutRuleViolations) {
|
|
process.stderr.write(
|
|
`${violation.path} breaks ${violation.rule} of docs/manual/03-outside-feature-folder.md: ${violation.detail}\n`,
|
|
);
|
|
}
|
|
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`,
|
|
);
|
|
}
|
|
for (const result of results) {
|
|
if (result.passed) continue;
|
|
process.stderr.write(
|
|
`diagram review ${result.diagram} (${result.sourcePath}) is not a recorded PASS in ` +
|
|
`${ledger.evidenceReport.repoPath} (docs/architecture/review-ledger.json)\n`,
|
|
);
|
|
}
|
|
if (results.length !== 2) {
|
|
process.stderr.write(`review ledger has ${results.length} diagram reviews; 2 are required\n`);
|
|
}
|
|
if (documentsSystem.failures.length > 0) {
|
|
process.stderr.write(
|
|
`Documents system (docs/README.md 「문서 검사」): ${documentsSystem.report.join("; ")}\n` +
|
|
documentsSystem.failures.map((failure) => ` ${failure}\n`).join(""),
|
|
);
|
|
}
|
|
process.stderr.write(
|
|
`Documentation readiness: FAIL_UNVERIFIED (failed: ${failedChecks.join(", ")})\n`,
|
|
);
|
|
process.exit(1);
|
|
}
|
|
if (removedTemplateFeatures.length > 0) {
|
|
process.stdout.write(
|
|
`Documentation readiness: paths and scripts of removed template features not required: ` +
|
|
`${removedTemplateFeatures.map((feature) => feature.featureId).join(", ")}\n`,
|
|
);
|
|
}
|
|
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 ` +
|
|
`(${reasons.join("; ")}): ${[...new Set(unverified)].join(", ")}\n`,
|
|
);
|
|
}
|
|
process.stdout.write(`Documents system: ${documentsSystem.report.join("; ")}\n`);
|
|
process.stdout.write("Documentation readiness: PASS_SCOPED\n");
|