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:
DongHyeonka
2026-11-04 23:08:05 +09:00
106 changed files with 1180 additions and 992 deletions
+14 -72
View File
@@ -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(
+3
View File
@@ -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),
})
+6 -3
View File
@@ -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.",
];
+177
View File
@@ -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),
});
}
+11 -6
View File
@@ -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");
+24
View File
@@ -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);
+143
View File
@@ -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"}`,
};
}
+45 -1
View File
@@ -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(", ")
}`,
});
}
+11 -9
View File
@@ -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) {
+23 -4
View File
@@ -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);
+34 -21
View File
@@ -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 });
+20 -5
View File
@@ -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"),
+80 -7
View File
@@ -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");