chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02 # Conflicts: # docs/manual/01-add-a-feature.md # docs/manual/02-decision-tables.md # docs/manual/reference/patterns.md
This commit is contained in:
@@ -1,11 +1,13 @@
|
||||
import { parseAsync } from "@babel/core";
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { mkdir, readFile, readdir } from "node:fs/promises";
|
||||
import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
import { createRequire } from "node:module";
|
||||
|
||||
import { ESLint } from "eslint";
|
||||
|
||||
import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { checkArchitectureLintFixtures } from "./lib/architecture-lint-fixtures.ts";
|
||||
import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
@@ -79,7 +81,6 @@ const architectureConfig = parseArchitectureConfig(
|
||||
const architectureRules = architectureConfig.forbidden;
|
||||
const sourceExtensionPattern = /\.(?:ts|tsx|mts|cts)$/u;
|
||||
const declarationExtensionPattern = /\.d\.(?:ts|mts|cts)$/u;
|
||||
const lintFixtureExtensionPattern = sourceExtensionPattern;
|
||||
const forbiddenJavaScriptExtensionPattern = /\.(?:js|jsx|mjs|cjs)$/u;
|
||||
const forbiddenLocalJavaScriptSpecifierPattern =
|
||||
/\.(?:js|jsx|mjs|cjs)(?:[?#]|$)/u;
|
||||
@@ -89,13 +90,6 @@ const relativeSpecifierPattern = /^\.{1,2}(?:\/|$)/u;
|
||||
|
||||
await mkdir(dirname(qualityArtifact), { recursive: true });
|
||||
|
||||
const configuredPnpmCli = process.env.npm_execpath;
|
||||
|
||||
if (!configuredPnpmCli) {
|
||||
throw new Error("check:architecture must run through the pnpm script");
|
||||
}
|
||||
const pnpmCli = configuredPnpmCli;
|
||||
|
||||
if (
|
||||
(architectureConfig.allowed?.length ?? 0) > 0 ||
|
||||
(architectureConfig.required?.length ?? 0) > 0
|
||||
@@ -106,12 +100,6 @@ if (
|
||||
}
|
||||
validateArchitectureRules(architectureRules);
|
||||
|
||||
function runPnpm(arguments_: string[]) {
|
||||
return spawnSync(process.execPath, [pnpmCli, ...arguments_], {
|
||||
encoding: "utf8",
|
||||
});
|
||||
}
|
||||
|
||||
// 12-05 (D-11): this graph is the only architecture checker. dependency-cruiser
|
||||
// 18 cannot parse TypeScript 7, so it cruised zero modules and still passed.
|
||||
// .dependency-cruiser.json keeps its name and is read here as the rule file.
|
||||
@@ -211,68 +199,22 @@ process.stdout.write(
|
||||
`TypeScript-only source policy: PASS (${typeScriptOnlyPolicy.checkedRoots.join(", ")}; no fixture exceptions)\n`,
|
||||
);
|
||||
|
||||
const allowed = runPnpm([
|
||||
"exec",
|
||||
"eslint",
|
||||
"tests/fixtures/architecture/allowed",
|
||||
"--no-ignore",
|
||||
"--max-warnings=0",
|
||||
]);
|
||||
|
||||
const forbidden = runPnpm([
|
||||
"exec",
|
||||
"eslint",
|
||||
"tests/fixtures/architecture/forbidden",
|
||||
"--no-ignore",
|
||||
"--max-warnings=0",
|
||||
]);
|
||||
|
||||
async function fixtureFiles(directory: string): Promise<string[]> {
|
||||
const entries = await readdir(directory, { withFileTypes: true });
|
||||
const files = await Promise.all(
|
||||
entries.map((entry) => {
|
||||
const target = `${directory}/${entry.name}`;
|
||||
return entry.isDirectory()
|
||||
? fixtureFiles(target)
|
||||
: lintFixtureExtensionPattern.test(entry.name)
|
||||
? [target]
|
||||
: [];
|
||||
}),
|
||||
);
|
||||
return files.flat();
|
||||
}
|
||||
|
||||
const forbiddenResults = await Promise.all(
|
||||
(await fixtureFiles("tests/fixtures/architecture/forbidden")).map((file) => ({
|
||||
file,
|
||||
result: runPnpm([
|
||||
"exec",
|
||||
"eslint",
|
||||
file,
|
||||
"--no-ignore",
|
||||
"--max-warnings=0",
|
||||
]),
|
||||
})),
|
||||
);
|
||||
const acceptedForbidden = forbiddenResults.filter(
|
||||
({ result }) => result.status === 0,
|
||||
);
|
||||
|
||||
if (
|
||||
allowed.status !== 0 ||
|
||||
forbidden.status === 0 ||
|
||||
acceptedForbidden.length > 0
|
||||
) {
|
||||
process.stderr.write(allowed.stderr || allowed.stdout);
|
||||
process.stderr.write(forbidden.stderr || forbidden.stdout);
|
||||
for (const { file } of acceptedForbidden) {
|
||||
process.stderr.write(`Forbidden fixture was accepted: ${file}\n`);
|
||||
// 1103/12-04. Each fixture is linted under the production configuration of
|
||||
// the path it stands for, and a forbidden one must be reported by the rule it
|
||||
// names (scripts/lib/architecture-lint-fixtures.ts).
|
||||
const lintFixtures = await checkArchitectureLintFixtures({
|
||||
root: projectRoot,
|
||||
linter: new ESLint({ cwd: projectRoot }),
|
||||
});
|
||||
if (lintFixtures.failures.length > 0) {
|
||||
for (const failure of lintFixtures.failures) {
|
||||
process.stderr.write(`Architecture lint fixture: ${failure}\n`);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
`Architecture fixtures: allowed PASS, ${forbiddenResults.length} forbidden rejected\n`,
|
||||
`Architecture fixtures: ${lintFixtures.allowed} allowed PASS, ${lintFixtures.forbidden} forbidden rejected by the production rule for their layer\n`,
|
||||
);
|
||||
|
||||
async function analyzeSourceGraph(
|
||||
|
||||
@@ -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),
|
||||
})
|
||||
|
||||
@@ -13,8 +13,11 @@ import {
|
||||
import { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts";
|
||||
|
||||
/**
|
||||
* U7. `pnpm create:feature <id>` writes the smallest feature that passes every
|
||||
* merge gate: one list route without params, one GET (SAFE, EXTERNAL_BEARER),
|
||||
* U7. `pnpm create:feature <id>` writes the smallest feature meant to pass
|
||||
* every merge gate. test:feature-scaffold runs the merge stage on it except the
|
||||
* commands SCAFFOLD_DRILL_EXCLUDED_SCRIPTS names (browser gates, test:system;
|
||||
* scripts/lib/feature-scaffold-drill.ts). The feature has one list route
|
||||
* without params, one GET (SAFE, EXTERNAL_BEARER),
|
||||
* one query, one invalidation topic, one CollectionPage with ko-KR and en-US
|
||||
* copy, and a router page test plus an input test. The templates live in this
|
||||
* file and import nothing from a sample feature, so the command keeps working
|
||||
@@ -1415,7 +1418,7 @@ function report(plan: FeaturePlan): string {
|
||||
"",
|
||||
"Next:",
|
||||
` 1. Before a release, have a person review and sign artifacts/tests/a11y-manual/${plan.routeId}.md (FE-GATE-028). The merge gates check only its format.`,
|
||||
" 2. Run the merge gates: corepack pnpm check:types, lint, check:architecture, check:registries, check:i18n, check:design-system, check:diagnostics, verify:documentation, test:unit, test:component, test:integration, test:coverage, check:ci, build.",
|
||||
" 2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage in config/ci/gates.json (README lists the loop). test:feature-scaffold runs them on a generated feature except the browser gates FE-GATE-008/009 and test:system.",
|
||||
` The feature's own tests: node scripts/run-vitest.ts run tests/features/${plan.id} (test:coverage runs them in CI)`,
|
||||
" The registry baseline does not change: new routes, operations, schemas and invalidation topics are additive.",
|
||||
];
|
||||
|
||||
@@ -0,0 +1,177 @@
|
||||
import { readdir, readFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
/**
|
||||
* 1103/12-04. The architecture lint fixtures are linted under the production
|
||||
* configuration of the layer they stand for.
|
||||
*
|
||||
* They used to be linted where they live, under tests/, by an ESLint entry of
|
||||
* their own that banned every layer's imports and globals at once, and a
|
||||
* fixture counted as rejected whenever ESLint exited non-zero. Deleting the
|
||||
* production rule for a layer therefore still left "9 forbidden rejected":
|
||||
* presentation code could call `fetch` and the fixtures said it could not.
|
||||
*
|
||||
* Each fixture is now linted as if it were the file at `lintAs`, so exactly
|
||||
* the production entries for that path apply, and a forbidden fixture passes
|
||||
* only when the rule named in `rejectedBy` reports it.
|
||||
*/
|
||||
export type ArchitectureLintRule = "no-restricted-imports" | "no-restricted-globals";
|
||||
|
||||
export type ArchitectureLintFixture = Readonly<{
|
||||
/** Relative to tests/fixtures/architecture. */
|
||||
file: string;
|
||||
/** The production path whose ESLint configuration the fixture is linted under. */
|
||||
lintAs: string;
|
||||
/** For a forbidden fixture: the production rule that must reject it. */
|
||||
rejectedBy?: ArchitectureLintRule;
|
||||
}>;
|
||||
|
||||
export const ARCHITECTURE_LINT_FIXTURE_ROOT = "tests/fixtures/architecture";
|
||||
|
||||
const LAYER_RULES: ReadonlySet<string> = new Set<ArchitectureLintRule>([
|
||||
"no-restricted-imports",
|
||||
"no-restricted-globals",
|
||||
]);
|
||||
|
||||
const at = (layer: string, file: string) =>
|
||||
`${layer}/__architecture_fixture__/${path.posix.basename(file)}`;
|
||||
|
||||
export const ARCHITECTURE_LINT_FIXTURES: readonly ArchitectureLintFixture[] = Object.freeze([
|
||||
...[
|
||||
"allowed/bootstrap-composes-adapter.ts",
|
||||
].map((file) => ({ file, lintAs: at("src/bootstrap", file) })),
|
||||
...[
|
||||
"allowed/presentation-facade.ts",
|
||||
"allowed/presentation-facade.tsx",
|
||||
].map((file) => ({ file, lintAs: at("src/presentation", file) })),
|
||||
...[
|
||||
"forbidden/application-imports-adapter.ts",
|
||||
"forbidden/application-imports-tanstack.ts",
|
||||
].map((file) => ({
|
||||
file,
|
||||
lintAs: at("src/application", file),
|
||||
rejectedBy: "no-restricted-imports" as const,
|
||||
})),
|
||||
// Domain code lives inside features; src/features/*/domain is the entry
|
||||
// that applies to it.
|
||||
{
|
||||
file: "forbidden/domain-imports-react.ts",
|
||||
lintAs: "src/features/__architecture_fixture__/domain/domain-imports-react.ts",
|
||||
rejectedBy: "no-restricted-imports",
|
||||
},
|
||||
{
|
||||
file: "forbidden/presentation-direct-fetch.tsx",
|
||||
lintAs: at("src/presentation", "presentation-direct-fetch.tsx"),
|
||||
rejectedBy: "no-restricted-globals",
|
||||
},
|
||||
...[
|
||||
"forbidden/presentation-imports-adapter.ts",
|
||||
"forbidden/presentation-imports-adapter.tsx",
|
||||
"forbidden/presentation-imports-output-port.tsx",
|
||||
"forbidden/presentation-imports-tanstack.tsx",
|
||||
].map((file) => ({
|
||||
file,
|
||||
lintAs: at("src/presentation", file),
|
||||
rejectedBy: "no-restricted-imports" as const,
|
||||
})),
|
||||
{
|
||||
file: "forbidden/template-imports-application.tsx",
|
||||
lintAs: at("src/presentation/templates", "template-imports-application.tsx"),
|
||||
rejectedBy: "no-restricted-imports",
|
||||
},
|
||||
]);
|
||||
|
||||
type LintMessage = Readonly<{
|
||||
ruleId: string | null;
|
||||
message: string;
|
||||
fatal?: boolean;
|
||||
line?: number;
|
||||
}>;
|
||||
|
||||
export type ArchitectureLinter = Readonly<{
|
||||
lintText(
|
||||
code: string,
|
||||
options: Readonly<{ filePath: string; warnIgnored: boolean }>,
|
||||
): Promise<readonly Readonly<{ messages: readonly LintMessage[] }>[]>;
|
||||
}>;
|
||||
|
||||
export type ArchitectureLintFixtureResult = Readonly<{
|
||||
allowed: number;
|
||||
forbidden: number;
|
||||
failures: readonly string[];
|
||||
}>;
|
||||
|
||||
const SOURCE_FILE = /\.(?:ts|tsx)$/u;
|
||||
|
||||
async function filesBelow(root: string, directory: string): Promise<string[]> {
|
||||
const entries = await readdir(path.join(root, directory), { withFileTypes: true });
|
||||
const files = await Promise.all(entries.map((entry) => {
|
||||
const relative = path.posix.join(directory, entry.name);
|
||||
if (entry.isDirectory()) return filesBelow(root, relative);
|
||||
return SOURCE_FILE.test(entry.name) ? [relative] : [];
|
||||
}));
|
||||
return files.flat();
|
||||
}
|
||||
|
||||
export async function checkArchitectureLintFixtures(input: Readonly<{
|
||||
root: string;
|
||||
linter: ArchitectureLinter;
|
||||
fixtures?: readonly ArchitectureLintFixture[];
|
||||
}>): Promise<ArchitectureLintFixtureResult> {
|
||||
const fixtures = input.fixtures ?? ARCHITECTURE_LINT_FIXTURES;
|
||||
const failures: string[] = [];
|
||||
const onDisk = new Set([
|
||||
...await filesBelow(input.root, path.posix.join(ARCHITECTURE_LINT_FIXTURE_ROOT, "allowed")),
|
||||
...await filesBelow(input.root, path.posix.join(ARCHITECTURE_LINT_FIXTURE_ROOT, "forbidden")),
|
||||
].map((file) => path.posix.relative(ARCHITECTURE_LINT_FIXTURE_ROOT, file)));
|
||||
const listed = new Set(fixtures.map(({ file }) => file));
|
||||
for (const file of [...onDisk].filter((candidate) => !listed.has(candidate)).sort()) {
|
||||
failures.push(`${file}: not listed in ARCHITECTURE_LINT_FIXTURES, so nothing says what must reject it`);
|
||||
}
|
||||
for (const fixture of fixtures) {
|
||||
const forbidden = fixture.file.startsWith("forbidden/");
|
||||
if (forbidden !== (fixture.rejectedBy !== undefined)) {
|
||||
failures.push(`${fixture.file}: a forbidden fixture names its rule and an allowed one names none`);
|
||||
continue;
|
||||
}
|
||||
if (!onDisk.has(fixture.file)) {
|
||||
failures.push(`${fixture.file}: listed fixture does not exist`);
|
||||
continue;
|
||||
}
|
||||
const code = await readFile(
|
||||
path.join(input.root, ARCHITECTURE_LINT_FIXTURE_ROOT, fixture.file),
|
||||
"utf8",
|
||||
);
|
||||
const [result] = await input.linter.lintText(code, {
|
||||
filePath: path.join(input.root, fixture.lintAs),
|
||||
warnIgnored: true,
|
||||
});
|
||||
const messages = result?.messages ?? [];
|
||||
const unlinted = messages.filter((message) => message.fatal || message.ruleId === null);
|
||||
if (unlinted.length > 0) {
|
||||
failures.push(
|
||||
`${fixture.file} (as ${fixture.lintAs}) was not linted: ${unlinted.map(({ message }) => message).join("; ")}`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
const layerMessages = messages.filter(({ ruleId }) => ruleId !== null && LAYER_RULES.has(ruleId));
|
||||
if (fixture.rejectedBy !== undefined) {
|
||||
if (!layerMessages.some(({ ruleId }) => ruleId === fixture.rejectedBy)) {
|
||||
failures.push(
|
||||
`${fixture.file} (as ${fixture.lintAs}) was accepted: the production ${fixture.rejectedBy} rule for that path no longer rejects it`,
|
||||
);
|
||||
}
|
||||
} else if (layerMessages.length > 0) {
|
||||
failures.push(
|
||||
`${fixture.file} (as ${fixture.lintAs}) was rejected: ${layerMessages
|
||||
.map(({ ruleId, line, message }) => `${ruleId} at line ${line ?? "?"}: ${message}`)
|
||||
.join("; ")}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
allowed: fixtures.filter(({ rejectedBy }) => rejectedBy === undefined).length,
|
||||
forbidden: fixtures.filter(({ rejectedBy }) => rejectedBy !== undefined).length,
|
||||
failures: Object.freeze(failures),
|
||||
});
|
||||
}
|
||||
@@ -9,6 +9,10 @@ import type {
|
||||
CiGateArtifactSchema,
|
||||
} from "../contracts/ci-gates.ts";
|
||||
import { ciContractReportSchema } from "./ci-contract-report.ts";
|
||||
import {
|
||||
COVERAGE_SUMMARY_METRICS,
|
||||
COVERAGE_SUMMARY_OPTIONAL_METRICS,
|
||||
} from "./coverage-summary-metrics.ts";
|
||||
import {
|
||||
architectureDependencyReportArtifactSchema,
|
||||
automatedA11yArtifactSchema,
|
||||
@@ -76,16 +80,17 @@ const coverageCounterSchema = z
|
||||
context.addIssue({ code: "custom", path: ["pct"], message: "coverage pct is not exact" });
|
||||
}
|
||||
});
|
||||
// 1103/12-09. The key list is shared with the risk coverage gate, which reads
|
||||
// the same file; this schema used to refuse the `branchesTrue` the reporter
|
||||
// always writes.
|
||||
const coverageSummarySchema = z
|
||||
.record(
|
||||
z.string(),
|
||||
z
|
||||
.object({
|
||||
lines: coverageCounterSchema,
|
||||
statements: coverageCounterSchema,
|
||||
functions: coverageCounterSchema,
|
||||
branches: coverageCounterSchema,
|
||||
})
|
||||
.object(Object.fromEntries([
|
||||
...COVERAGE_SUMMARY_METRICS.map((metric) => [metric, coverageCounterSchema]),
|
||||
...COVERAGE_SUMMARY_OPTIONAL_METRICS.map((metric) => [metric, coverageCounterSchema.optional()]),
|
||||
]))
|
||||
.strict(),
|
||||
)
|
||||
.refine((value) => "total" in value, "coverage summary lacks total");
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
/**
|
||||
* The keys of one entry in Vitest's `coverage-summary.json`. Two readers check
|
||||
* that file: the CI evidence validator (ci-artifact-validator.ts) and the risk
|
||||
* coverage gate (risk-coverage.ts). They kept separate lists, and the
|
||||
* validator refused `branchesTrue` while the gate accepted it, so FE-GATE-005
|
||||
* failed at its evidence step after every test had passed (1103/12-09).
|
||||
*/
|
||||
|
||||
/** The four metrics both readers evaluate. */
|
||||
export const COVERAGE_SUMMARY_METRICS = Object.freeze([
|
||||
"lines",
|
||||
"statements",
|
||||
"functions",
|
||||
"branches",
|
||||
] as const);
|
||||
|
||||
/**
|
||||
* Keys the reporter may add. istanbul-lib-coverage 3.2.2 puts `branchesTrue`
|
||||
* in every blank summary, so the total always carries it. Each is still
|
||||
* checked as a counter; neither reader evaluates it.
|
||||
*/
|
||||
export const COVERAGE_SUMMARY_OPTIONAL_METRICS = Object.freeze([
|
||||
"branchesTrue",
|
||||
] as const);
|
||||
@@ -0,0 +1,143 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
|
||||
import type { CiGateContract } from "../contracts/ci-gates.ts";
|
||||
import { classifyGateStepResult, type GateStepExpectation } from "./ci-step-result.ts";
|
||||
import { FIXTURE_PNPM_ENVIRONMENT } from "./fixture-node-modules.ts";
|
||||
import type { RemovalCheck } from "./removal-fixture.ts";
|
||||
|
||||
/**
|
||||
* 1103/12-02. test:feature-scaffold proves that a feature from
|
||||
* `create:feature` passes the merge gates. It ran a hand-kept list of 15
|
||||
* commands while the merge stage has 88, so a template change that broke a
|
||||
* generated feature in any other merge command passed FE-GATE-020.
|
||||
*
|
||||
* The drill now runs the merge stage of the copy's config/ci/gates.json, in
|
||||
* stage order, each command once. A command added to the merge stage runs here
|
||||
* unless this list names it, with the reason it cannot run in the drill.
|
||||
*/
|
||||
const BROWSER =
|
||||
"needs Playwright browsers. FE-GATE-020 runs in a merge job without them " +
|
||||
"(merge_gate matrix browser: false). The generated routes in the browser " +
|
||||
"gates are reviewed as 1103/12-01 and 12-03.";
|
||||
const DRILL =
|
||||
"a removal drill copies the repository again. The drill runs the generated " +
|
||||
"feature's own removal instead (feature-removal).";
|
||||
|
||||
export const SCAFFOLD_DRILL_EXCLUDED_SCRIPTS: Readonly<Record<string, string>> = Object.freeze({
|
||||
"verify:lockfile":
|
||||
"runs pnpm install, which writes into the node_modules the copy links from " +
|
||||
"the repository (scripts/lib/fixture-node-modules.ts).",
|
||||
"test:e2e": BROWSER,
|
||||
"test:browser-capabilities": BROWSER,
|
||||
"verify:browser-capability-evidence": `reads the test:browser-capabilities results; ${BROWSER}`,
|
||||
"test:storybook": BROWSER,
|
||||
"test:visual": BROWSER,
|
||||
"check:test-evidence:browser": `reads the browser gates' results; ${BROWSER}`,
|
||||
"test:a11y": BROWSER,
|
||||
"test:system":
|
||||
"needs the CI runner's bubblewrap, systemd and cgroup v2 " +
|
||||
"(scripts/check-system-test-prerequisites.ts). It tests the provider " +
|
||||
"sandbox, which a feature does not reach.",
|
||||
"test:sample-removal": DRILL,
|
||||
"test:feature-scaffold": "is this drill.",
|
||||
"test:optional-recipe-removal": DRILL,
|
||||
"test:browser-file-storage-removal": DRILL,
|
||||
"test:realtime-removal": DRILL,
|
||||
});
|
||||
|
||||
export type ScaffoldDrillCommand = Readonly<{
|
||||
/** `<gate>:<command id>`, the check's name in the drill report. */
|
||||
name: string;
|
||||
script: string;
|
||||
args: readonly string[];
|
||||
expectation: GateStepExpectation;
|
||||
}>;
|
||||
|
||||
type ContractShape = Pick<CiGateContract, "commands" | "gates" | "stages">;
|
||||
|
||||
export function scaffoldDrillCommands(
|
||||
contract: ContractShape,
|
||||
excluded: Readonly<Record<string, string>> = SCAFFOLD_DRILL_EXCLUDED_SCRIPTS,
|
||||
): readonly ScaffoldDrillCommand[] {
|
||||
const merge = contract.stages.find(({ id }) => id === "merge");
|
||||
if (!merge) throw new TypeError("the CI contract has no merge stage");
|
||||
const commands = new Map(contract.commands.map((command) => [command.id, command]));
|
||||
const mergeScripts = new Set<string>();
|
||||
const seen = new Set<string>();
|
||||
const selected: ScaffoldDrillCommand[] = [];
|
||||
for (const gateId of merge.gateIds) {
|
||||
const gate = contract.gates.find(({ id }) => id === gateId);
|
||||
if (!gate) throw new TypeError(`the merge stage names an undefined gate: ${gateId}`);
|
||||
for (const commandId of gate.commandIds) {
|
||||
const command = commands.get(commandId);
|
||||
if (!command) throw new TypeError(`${gateId} names an undefined command: ${commandId}`);
|
||||
mergeScripts.add(command.script);
|
||||
if (seen.has(commandId) || Object.hasOwn(excluded, command.script)) continue;
|
||||
seen.add(commandId);
|
||||
selected.push(Object.freeze({
|
||||
name: `${gateId}:${commandId}`,
|
||||
script: command.script,
|
||||
args: Object.freeze([...(command.args ?? [])]),
|
||||
expectation: command.expect === "pass"
|
||||
? Object.freeze({ kind: "pass" as const })
|
||||
: Object.freeze({
|
||||
kind: "fail" as const,
|
||||
expectedExitCode: command.expectedExitCode ?? 1,
|
||||
expectedDiagnosticId: command.expectedDiagnosticId ?? "",
|
||||
}),
|
||||
}));
|
||||
}
|
||||
}
|
||||
// An exclusion for a command that moved out of the merge stage would hide
|
||||
// nothing today and silently drop it if it came back. A command the contract
|
||||
// no longer has at all (a removal drill pruned its capability) is not stale.
|
||||
const contractScripts = new Set(contract.commands.map(({ script }) => script));
|
||||
const stale = Object.keys(excluded).filter(
|
||||
(script) => contractScripts.has(script) && !mergeScripts.has(script),
|
||||
);
|
||||
if (stale.length > 0) {
|
||||
throw new TypeError(
|
||||
`the scaffold drill excludes scripts the contract runs outside the merge stage: ${stale.join(", ")}`,
|
||||
);
|
||||
}
|
||||
return Object.freeze(selected);
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs one merge command in the fixture. A negative fixture command passes
|
||||
* only with its registered exit code and diagnostic, as in run-ci-gate.ts.
|
||||
*/
|
||||
export function runScaffoldDrillCommand(
|
||||
command: ScaffoldDrillCommand,
|
||||
root: string,
|
||||
pnpmCli: string,
|
||||
): RemovalCheck {
|
||||
const capture = command.expectation.kind === "fail";
|
||||
const result = spawnSync(process.execPath, [pnpmCli, command.script, ...command.args], {
|
||||
cwd: root,
|
||||
encoding: "utf8",
|
||||
stdio: capture ? "pipe" : "inherit",
|
||||
maxBuffer: 64 * 1024 * 1024,
|
||||
env: { ...process.env, ...FIXTURE_PNPM_ENVIRONMENT },
|
||||
});
|
||||
if (capture) {
|
||||
process.stdout.write(result.stdout ?? "");
|
||||
process.stderr.write(result.stderr ?? "");
|
||||
}
|
||||
const classification = classifyGateStepResult(command.expectation, {
|
||||
status: result.status,
|
||||
signal: result.signal,
|
||||
stdout: result.stdout ?? "",
|
||||
stderr: result.stderr ?? "",
|
||||
...(result.error ? { error: { code: (result.error as NodeJS.ErrnoException).code } } : {}),
|
||||
});
|
||||
if (classification.expectationMet) return { name: command.name, passed: true };
|
||||
const invocation = `corepack pnpm ${[command.script, ...command.args].join(" ")}`;
|
||||
return {
|
||||
name: command.name,
|
||||
passed: false,
|
||||
failure: command.expectation.kind === "fail"
|
||||
? `${invocation}: ${classification.kind}, expected exit ${command.expectation.expectedExitCode} with ${JSON.stringify(command.expectation.expectedDiagnosticId)}, got exit ${result.status ?? result.signal}`
|
||||
: `${invocation} exited ${result.status ?? result.signal ?? "on a spawn error"}`,
|
||||
};
|
||||
}
|
||||
@@ -46,6 +46,41 @@ export const REMOVAL_FIXTURE_COPY_TARGETS = Object.freeze([
|
||||
* provider suite down with it — twenty-odd failures with one cause.
|
||||
*/
|
||||
|
||||
/**
|
||||
* The repository's documents. A drill that adds or removes a feature copies
|
||||
* them as well (REMOVAL_FIXTURE_COPY_TARGETS plus these), because the change
|
||||
* must leave the documents valid (1103/14-04). The capability drills do not:
|
||||
* the documents describe the capability they delete, and what those drills
|
||||
* prove is that the code still builds and tests without it.
|
||||
*/
|
||||
export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = Object.freeze([
|
||||
"README.md",
|
||||
"CHANGELOG.md",
|
||||
"docs",
|
||||
] as const);
|
||||
|
||||
/**
|
||||
* 1103/02-06. Tests that read REMOVAL_FIXTURE_DOCUMENT_TARGETS. A fixture
|
||||
* copied without the documents cannot run them: every capability drill
|
||||
* (FE-GATE-020) failed its `test` check on ENOENT for README.md and
|
||||
* CHANGELOG.md, whatever the removal did. prepareRemovalFixture deletes them
|
||||
* from such a fixture, and the repository's own test:unit keeps running them.
|
||||
* This is the only list; the sample drill used to keep the exclusion to itself.
|
||||
*/
|
||||
export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([
|
||||
"tests/unit/changelog-review-ids.test.ts",
|
||||
"tests/unit/documentation-readiness.test.ts",
|
||||
] as const);
|
||||
|
||||
/** The tests a fixture copied from `copyTargets` cannot run. */
|
||||
export function removalFixtureExcludedTests(
|
||||
copyTargets: readonly string[],
|
||||
): readonly string[] {
|
||||
return REMOVAL_FIXTURE_DOCUMENT_TARGETS.every((target) => copyTargets.includes(target))
|
||||
? []
|
||||
: REMOVAL_FIXTURE_DOCUMENT_TESTS;
|
||||
}
|
||||
|
||||
/**
|
||||
* Regenerated result trees under `artifacts/`: traces, coverage HTML, recorded
|
||||
* videos and Storybook bundles. They are tens of megabytes and mean nothing to
|
||||
@@ -114,6 +149,9 @@ export async function prepareRemovalFixture(
|
||||
for (const target of copyTargets) {
|
||||
await cp(target, path.join(root, target), { recursive: true });
|
||||
}
|
||||
for (const test of removalFixtureExcludedTests(copyTargets)) {
|
||||
await rm(path.join(root, test), { force: true });
|
||||
}
|
||||
await copyReleaseEvidenceTree(process.cwd(), root);
|
||||
runFixtureGit(root, ["init", "--quiet", "--initial-branch=fixture"]);
|
||||
await linkFixtureNodeModules(root);
|
||||
@@ -465,8 +503,14 @@ export async function pruneRemovalFixtureCiContract(options: Readonly<{
|
||||
]);
|
||||
// D-13: the reduced contract is a new baseline, recorded the way a project
|
||||
// that removes the capability records it; canonical check:ci then applies.
|
||||
// 1103/16-02. A product feature owns no CI script; an empty list used to
|
||||
// leave a trailing blank that the baseline schema refuses.
|
||||
await updateCiContractBaseline(options.root, {
|
||||
owner: "removal-fixture",
|
||||
reason: `removal fixture pruned ${[...options.removedScripts].join(", ")}`,
|
||||
reason: `removal fixture pruned ${
|
||||
options.removedScripts.size === 0
|
||||
? "no CI scripts"
|
||||
: [...options.removedScripts].join(", ")
|
||||
}`,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -8,14 +8,12 @@ import {
|
||||
import path from "node:path";
|
||||
import babelParser from "@babel/eslint-parser";
|
||||
|
||||
import {
|
||||
COVERAGE_SUMMARY_METRICS as coverageMetrics,
|
||||
COVERAGE_SUMMARY_OPTIONAL_METRICS,
|
||||
} from "./coverage-summary-metrics.ts";
|
||||
import { normalizeRepositoryRelativePath } from "./repository-file-inventory.ts";
|
||||
|
||||
const coverageMetrics = [
|
||||
"lines",
|
||||
"statements",
|
||||
"functions",
|
||||
"branches",
|
||||
] as const;
|
||||
const teamIdPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
|
||||
const maximumWaiverDurationMs = 90 * 24 * 60 * 60 * 1_000;
|
||||
|
||||
@@ -641,16 +639,20 @@ function parseCoverageCounter(value: unknown, label: string): CoverageCounter {
|
||||
|
||||
function parseCoverageMetrics(value: unknown, label: string): CoverageMetrics {
|
||||
if (!isRecord(value)) throw new TypeError(`${label} must be an object`);
|
||||
const optionalMetrics: readonly string[] = COVERAGE_SUMMARY_OPTIONAL_METRICS;
|
||||
const unknownMetrics = Object.keys(value).filter(
|
||||
(metric) => metric !== "branchesTrue" && !coverageMetrics.includes(metric as CoverageMetric),
|
||||
(metric) =>
|
||||
!optionalMetrics.includes(metric) && !coverageMetrics.includes(metric as CoverageMetric),
|
||||
);
|
||||
if (unknownMetrics.length > 0) {
|
||||
throw new TypeError(
|
||||
`${label} has unknown coverage metric keys: ${unknownMetrics.sort().join(", ")}`,
|
||||
);
|
||||
}
|
||||
if (value.branchesTrue !== undefined) {
|
||||
parseCoverageCounter(value.branchesTrue, `${label}.branchesTrue`);
|
||||
for (const metric of optionalMetrics) {
|
||||
if (value[metric] !== undefined) {
|
||||
parseCoverageCounter(value[metric], `${label}.${metric}`);
|
||||
}
|
||||
}
|
||||
const parsed = {} as Record<CoverageMetric, CoverageCounter>;
|
||||
for (const metric of coverageMetrics) {
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import { spawn } from "node:child_process";
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { constants } from "node:fs";
|
||||
import { access, appendFile, lstat } from "node:fs/promises";
|
||||
import { access, appendFile, lstat, stat } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
@@ -274,12 +274,21 @@ async function runProviderInSandbox(
|
||||
bwrapArguments.push("--dir", directory);
|
||||
}
|
||||
bwrapArguments.push("--ro-bind", workspaceRoot, workspaceRoot);
|
||||
if (await exists(path.join(workspaceRoot, ".git"))) {
|
||||
const repositoryMetadata = path.join(workspaceRoot, ".git");
|
||||
const metadataKind = await entryKind(repositoryMetadata);
|
||||
if (metadataKind === "directory") {
|
||||
bwrapArguments.push(
|
||||
"--size", String(PROVIDER_MASK_BYTES),
|
||||
"--tmpfs", path.join(workspaceRoot, ".git"),
|
||||
"--remount-ro", path.join(workspaceRoot, ".git"),
|
||||
"--tmpfs", repositoryMetadata,
|
||||
"--remount-ro", repositoryMetadata,
|
||||
);
|
||||
} else if (metadataKind === "other") {
|
||||
// 1103/11-04. A linked worktree or a submodule checkout has a one-line
|
||||
// `gitdir:` file here, and a tmpfs cannot be mounted on a file. /dev/null
|
||||
// is bound over it instead. bubblewrap mounts binds nodev, so the provider
|
||||
// can neither read the line nor write the path; the directory it names
|
||||
// lies outside the workspace and is never bound into the sandbox.
|
||||
bwrapArguments.push("--ro-bind", "/dev/null", repositoryMetadata);
|
||||
}
|
||||
bwrapArguments.push(
|
||||
"--ro-bind", candidateRoot, "/candidate",
|
||||
@@ -597,6 +606,16 @@ function missingDestinationAncestors(target: string): string[] {
|
||||
return ancestors.reverse();
|
||||
}
|
||||
|
||||
/** What `target` is once symlinks are followed, as bubblewrap will see it. */
|
||||
async function entryKind(target: string): Promise<"directory" | "other" | null> {
|
||||
try {
|
||||
return (await stat(target)).isDirectory() ? "directory" : "other";
|
||||
} catch (error) {
|
||||
if (hasErrorCode(error, "ENOENT")) return null;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
async function exists(target: string): Promise<boolean> {
|
||||
try {
|
||||
await lstat(target);
|
||||
|
||||
@@ -1,9 +1,16 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { mkdir, rm, writeFile } from "node:fs/promises";
|
||||
|
||||
import { loadCiGateContract } from "./contracts/ci-gates.ts";
|
||||
import {
|
||||
runScaffoldDrillCommand,
|
||||
scaffoldDrillCommands,
|
||||
} from "./lib/feature-scaffold-drill.ts";
|
||||
import {
|
||||
createRemovalFixtureRoot,
|
||||
prepareRemovalFixture,
|
||||
REMOVAL_FIXTURE_COPY_TARGETS,
|
||||
REMOVAL_FIXTURE_DOCUMENT_TARGETS,
|
||||
renderRemovalJunit,
|
||||
requireRemovalFixtureEnvironment,
|
||||
runRemovalFixtureCheck,
|
||||
@@ -14,7 +21,16 @@ import {
|
||||
/**
|
||||
* U7. A feature from `create:feature` passes the merge gates without an edit
|
||||
* and breaks no other test. A copy of the repository, sample feature
|
||||
* included, gets one generated feature and then runs the gates.
|
||||
* included, gets one generated feature and then runs the merge stage of its
|
||||
* config/ci/gates.json: every command except those
|
||||
* SCAFFOLD_DRILL_EXCLUDED_SCRIPTS names with a reason (the browser gates,
|
||||
* test:system, the install check and the removal drills). 1103/12-02: this
|
||||
* used to be a hand-kept list of 15 commands.
|
||||
*
|
||||
* 1103/16-02. The generated feature is then removed again with
|
||||
* `test:sample-removal -- --feature=<id>`, the path the manual tells every
|
||||
* product feature to take and that no gate ran.
|
||||
*
|
||||
* test:sample-removal repeats the generation after deleting the sample
|
||||
* (decision 4), which proves the command needs nothing from it.
|
||||
*/
|
||||
@@ -24,6 +40,12 @@ const REPORT = "artifacts/tests/feature-scaffold.xml";
|
||||
const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath");
|
||||
const fixtureRoot = await createRemovalFixtureRoot("feature-scaffold");
|
||||
|
||||
function fixtureCommit(root: string): string {
|
||||
const head = spawnSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" });
|
||||
if (head.status !== 0) throw new Error(`feature scaffold fixture has no commit: ${head.stderr}`);
|
||||
return head.stdout.trim();
|
||||
}
|
||||
|
||||
function check(name: string, script: string, extra: readonly string[] = []): RemovalCheck {
|
||||
return runRemovalFixtureCheck(name, fixtureRoot, pnpmCli, script, extra);
|
||||
}
|
||||
@@ -32,9 +54,7 @@ try {
|
||||
// verify:documentation and the documentation tests read these.
|
||||
await prepareRemovalFixture(fixtureRoot, [
|
||||
...REMOVAL_FIXTURE_COPY_TARGETS,
|
||||
"README.md",
|
||||
"CHANGELOG.md",
|
||||
"docs",
|
||||
...REMOVAL_FIXTURE_DOCUMENT_TARGETS,
|
||||
]);
|
||||
const created = check("create-feature", "create:feature", [FEATURE_ID]);
|
||||
const checks: RemovalCheck[] = [created];
|
||||
@@ -42,23 +62,16 @@ try {
|
||||
// Commits the copy with the feature, as a project would: git-based
|
||||
// checks (git grep, git ls-files) then see the feature's files.
|
||||
sealRemovalFixtureRepository(fixtureRoot);
|
||||
checks.push(
|
||||
check("typecheck", "check:types"),
|
||||
check("lint", "lint"),
|
||||
check("architecture", "check:architecture"),
|
||||
check("registries", "check:registries"),
|
||||
check("i18n", "check:i18n"),
|
||||
check("design-system", "check:design-system"),
|
||||
check("diagnostics", "check:diagnostics"),
|
||||
check("documentation", "verify:documentation"),
|
||||
check("unit", "test:unit"),
|
||||
check("component", "test:component"),
|
||||
check("integration", "test:integration"),
|
||||
check("features", "exec", ["node", "scripts/run-vitest.ts", "run", "tests/features"]),
|
||||
check("coverage", "test:coverage"),
|
||||
check("ci-contract", "check:ci"),
|
||||
check("build", "build"),
|
||||
);
|
||||
// build:release-candidate records the build's commit and refuses one that
|
||||
// is not a commit ID. CI sets VITE_COMMIT_SHA for the whole workflow; a
|
||||
// local run gets the copy's own sealed commit instead of "local".
|
||||
if (!process.env["VITE_COMMIT_SHA"]?.trim()) {
|
||||
process.env["VITE_COMMIT_SHA"] = fixtureCommit(fixtureRoot);
|
||||
}
|
||||
for (const command of scaffoldDrillCommands(await loadCiGateContract(fixtureRoot))) {
|
||||
checks.push(runScaffoldDrillCommand(command, fixtureRoot, pnpmCli));
|
||||
}
|
||||
checks.push(check("feature-removal", "test:sample-removal", ["--", `--feature=${FEATURE_ID}`]));
|
||||
}
|
||||
const failed = checks.filter((entry) => !entry.passed);
|
||||
await mkdir("artifacts/tests", { recursive: true });
|
||||
|
||||
@@ -18,6 +18,8 @@ import {
|
||||
pruneRemovalFixtureCiContract,
|
||||
pruneScriptOrchestration,
|
||||
regenerateRemovalFixtureWorkflow,
|
||||
REMOVAL_FIXTURE_COPY_TARGETS,
|
||||
REMOVAL_FIXTURE_DOCUMENT_TARGETS,
|
||||
renderRemovalJunit,
|
||||
requireRemovalFixtureEnvironment,
|
||||
runRemovalFixtureCheck,
|
||||
@@ -201,16 +203,22 @@ function outcome(name: string, findings: readonly string[], label: string): Remo
|
||||
}
|
||||
|
||||
try {
|
||||
await prepareRemovalFixture(fixtureRoot);
|
||||
// 1103/14-04. The documents come too: removing a feature must leave them
|
||||
// valid, and the fixture used to leave them out with the tests that read
|
||||
// them, so a manual naming the sample's files passed here and then failed
|
||||
// FE-GATE-017 in the product that removed it.
|
||||
await prepareRemovalFixture(fixtureRoot, [
|
||||
...REMOVAL_FIXTURE_COPY_TARGETS,
|
||||
...REMOVAL_FIXTURE_DOCUMENT_TARGETS,
|
||||
]);
|
||||
// Fixture-only deletions: a project that removes the sample keeps these.
|
||||
// verify:documentation runs in this fixture, so a current contract document
|
||||
// must not name them as backtick paths (docs/manual/reference/patterns.md).
|
||||
for (const excludedFixtureTest of [
|
||||
"tests/unit/ci-workflow-generation.test.ts",
|
||||
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
|
||||
"tests/unit/removal-fixture.test.ts",
|
||||
"tests/unit/http-scenario-evidence.test.ts",
|
||||
// They check README.md and CHANGELOG.md, which the fixture does not copy
|
||||
// (REMOVAL_FIXTURE_COPY_TARGETS); removing a feature does not change them.
|
||||
"tests/unit/changelog-review-ids.test.ts",
|
||||
"tests/unit/documentation-readiness.test.ts",
|
||||
]) {
|
||||
await rm(path.join(fixtureRoot, excludedFixtureTest), { force: true });
|
||||
}
|
||||
@@ -399,6 +407,13 @@ try {
|
||||
}
|
||||
const gateChecks = (prefix: string): RemovalCheck[] => [
|
||||
check(`${prefix}typecheck`, "check:types"),
|
||||
// 1103/14-04 (FOLLOW-UP 09-07). Merge and documentation gates the drill
|
||||
// did not run: the documents, lint, screen text and design tokens can
|
||||
// name or use what the removal deleted.
|
||||
check(`${prefix}lint`, "lint"),
|
||||
check(`${prefix}documentation`, "verify:documentation"),
|
||||
check(`${prefix}i18n`, "check:i18n"),
|
||||
check(`${prefix}design-system`, "check:design-system"),
|
||||
check(`${prefix}architecture`, "check:architecture"),
|
||||
check(`${prefix}registries`, "check:registries"),
|
||||
check(`${prefix}unit-integration`, "test:all"),
|
||||
|
||||
@@ -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