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
+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) {