chore(review): 1105 가드레일·CI 조치 브랜치를 합친다

This commit is contained in:
DongHyeonka
2026-11-06 02:59:02 +09:00
17 changed files with 401 additions and 62 deletions
+18
View File
@@ -820,6 +820,24 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
target === "src/adapters/telemetry/index.ts",
),
},
// 0929/12-03. A feature folder that is not a layer (support/) had no rule,
// so presentation reached the http adapter barrel through it with the
// graph and ESLint both passing.
{
name: "feature non-layer folder re-export of a concrete adapter is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "feature-and-app-roots-do-not-reach-adapters" &&
source === "src/features/alpha/support/telemetry.ts" &&
target === "src/adapters/telemetry/index.ts",
),
},
{
name: "feature adapters folder import of a concrete adapter is accepted",
passed: !blockingViolations(crossBoundaryGraph).some(
({ source }) => source === "src/features/alpha/adapters/telemetry-sink.ts",
),
},
{
name: "context re-export of a concrete adapter is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
+3 -2
View File
@@ -1463,8 +1463,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.
// 1103/12-05, 1105/12-02. References into a paired repository
// whose pinned commit cannot be read beside this checkout (no
// checkout, or one without that commit). Reported, not failed.
unverifiedLinks: z.array(nonEmptyString),
missingScripts: z.array(nonEmptyString),
unknownGateIds: z.array(nonEmptyString),
+35 -8
View File
@@ -65,6 +65,18 @@ const defaultFileSystem: CiWorkflowFileSystem = Object.freeze({
rm: async (target) => rm(target, { force: true }),
});
const PRODUCT_GATE_JOB = "product_merge_gate";
/**
* 1105/13-02. The job that waits for the product gates. A failing product
* gate stopped nothing but a PR merge: the same run went on to release, build,
* promote and deploy, and the fixed job graph left a product no way to link
* them. release_gate is the first release-stage job, and every later one
* depends on it as it depends on merge_gate. The link is rendered from the
* overlay, so the template contract's job graph (and its check) stays the
* template's, and without product gates the workflow bytes do not change.
*/
const PRODUCT_GATES_HOLD = "release_gate";
export function renderCiWorkflow(
contract: CiGateContract,
productGates: readonly ProductGate[] = [],
@@ -76,6 +88,8 @@ export function renderCiWorkflow(
if (step.kind === "upload") transfers.set(step.transferId, { name: step.name });
}
}
// 1105/13-02. With product gates, the release stage waits for them too.
const productNeeds = productGates.length > 0 ? [PRODUCT_GATE_JOB] : [];
const lines = [
"# GENERATED FILE — edit config/ci/gates.json and run `corepack pnpm generate:ci-workflow`.",
"name: frontend-quality-gates",
@@ -113,7 +127,7 @@ export function renderCiWorkflow(
];
for (const [jobIndex, job] of contract.jobs.entries()) {
if (jobIndex > 0) lines.push("");
lines.push(...renderJob(job, index, transfers));
lines.push(...renderJob(job, index, transfers, job.id === PRODUCT_GATES_HOLD ? productNeeds : []));
}
if (productGates.length > 0) lines.push("", ...renderProductGateJob(productGates));
return `${lines.join("\n").replace(/\n+$/u, "")}\n`;
@@ -123,12 +137,13 @@ export function renderCiWorkflow(
* 1103/12-07. The product's merge gates (config/ci/product-gates.json) run in
* a job after every template job, on the same merge condition. A product gate
* is one package script; it has no log artifact or evidence of the template
* gate contract and is not part of its readiness formula, so the product makes
* this job a required check where it wants it to block a merge.
* gate contract and is not part of its readiness formula. The release stage
* waits for this job (1105/13-02); the product makes it a required check where
* it wants it to block a merge.
*/
function renderProductGateJob(productGates: readonly ProductGate[]): string[] {
return [
" product_merge_gate:",
` ${PRODUCT_GATE_JOB}:`,
` name: ${yamlScalar("${{ matrix.gate }} / ${{ matrix.name }}")}`,
` if: ${renderCondition("merge")}`,
" runs-on: ubuntu-latest",
@@ -161,10 +176,12 @@ function renderJob(
job: CiWorkflowJob,
index: ReturnType<typeof indexCiGateContract>,
transfers: ReadonlyMap<string, Readonly<{ name: string }>>,
productNeeds: readonly string[],
): string[] {
const lines = [` ${yamlKey(job.id)}:`, ` name: ${yamlScalar(job.displayName)}`];
if (job.needs.length === 1) lines.push(` needs: ${yamlKey(job.needs[0]!)}`);
if (job.needs.length > 1) lines.push(` needs: [${job.needs.map(yamlKey).join(", ")}]`);
const needs = [...job.needs, ...productNeeds];
if (needs.length === 1) lines.push(` needs: ${yamlKey(needs[0]!)}`);
if (needs.length > 1) lines.push(` needs: [${needs.map(yamlKey).join(", ")}]`);
const condition = renderCondition(job.condition);
if (condition) lines.push(` if: ${condition}`);
lines.push(
@@ -480,7 +497,7 @@ export function workflowGateExecutionFailures(
): string[] {
const executed = new Set<string>();
const jobs = workflow.split(/^(?= {2}[a-z_]+:$)/mu);
const productJob = jobs.find((job) => job.startsWith(" product_merge_gate:\n")) ?? "";
const productJob = jobs.find((job) => job.startsWith(` ${PRODUCT_GATE_JOB}:\n`)) ?? "";
const productRuns = /^ {8}run: corepack pnpm \$\{\{ matrix\.script \}\}$/mu.test(productJob);
const productFailures = productGates
.filter(
@@ -490,7 +507,17 @@ export function workflowGateExecutionFailures(
` - { gate: ${gate.id}, name: ${gate.name}, script: ${yamlScalar(gate.script)} }\n`,
),
)
.map(({ id }) => `product gate is not executed by the product_merge_gate job: ${id}`);
.map(({ id }) => `product gate is not executed by the ${PRODUCT_GATE_JOB} job: ${id}`);
// 1105/13-02. Run is not enough: a failing product gate must also hold the
// release stage.
const holdingJob = jobs.find((job) => job.startsWith(` ${PRODUCT_GATES_HOLD}:\n`)) ?? "";
const heldBy = /^ {4}needs: (?:\[([^\]\n]*)\]|(\S+))$/mu.exec(holdingJob);
if (
productGates.length > 0 &&
!(heldBy?.[1] ?? heldBy?.[2] ?? "").split(", ").includes(PRODUCT_GATE_JOB)
) {
productFailures.push(`product gates do not hold the release stage: ${PRODUCT_GATES_HOLD} does not need ${PRODUCT_GATE_JOB}`);
}
for (const job of jobs) {
for (const match of job.matchAll(/^ +run: corepack pnpm ci:gate -- (FE-GATE-\d{3})$/gmu)) {
executed.add(match[1]!);
+71 -18
View File
@@ -1,3 +1,4 @@
import { spawnSync } from "node:child_process";
import { existsSync } from "node:fs";
import { mkdir, readdir, readFile } from "node:fs/promises";
import { dirname, join, matchesGlob, normalize, resolve } from "node:path/posix";
@@ -207,12 +208,58 @@ const deletedHistory = [
.flatMap(([, cell = ""]) => [...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, "")))
.filter((entry) => !exists(entry));
// 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"]);
// 1103/12-05, 1105/12-02. The paired templates a document may name
// (`<name>/docs/…`) or link (`../../../<name>/…`) are the ones
// config/contracts/backend-contract-pin.json pins. It is read with the
// documents, since it says which commit they describe. A reference is looked
// up in the tree of the pinned commit, read from the object store of the
// checkout beside the documents, never from that checkout's working tree or
// HEAD: those differ per machine, and the same commit failed on one whose
// sibling was months behind with uncommitted changes and passed elsewhere.
// Where the checkout or the pinned commit is missing (CI, a nested worktree, a
// stale clone) the reference is reported as not verified. A link that leaves
// the repository for anything else is broken (a misspelled repository too).
const PAIRED_PIN = "config/contracts/backend-contract-pin.json";
const pairedPins = new Map<string, string>();
const pairedPin = await readFile(PAIRED_PIN, "utf8").catch(() => null);
if (pairedPin !== null) {
const { backend } = JSON.parse(pairedPin) as { backend: { repository: string; commit: string } };
pairedPins.set(backend.repository, backend.commit);
}
const siblingsRoot = resolve(process.cwd(), "..");
type PairedTree = Readonly<{ paths: ReadonlySet<string> }> | Readonly<{ unverified: string }>;
const pairedTrees = new Map<string, PairedTree>();
function readPairedTree(repository: string, commit: string): PairedTree {
const checkout = resolve(siblingsRoot, repository);
if (!existsSync(join(checkout, ".git"))) return { unverified: `no checkout at ${checkout}` };
// The checkout's own repository only: a GIT_DIR set by a hook would point
// git at another one.
const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
const git = (...args: string[]) =>
spawnSync("git", ["-C", checkout, ...args], { encoding: "utf8", env, maxBuffer: 64 * 1024 * 1024 });
if (git("cat-file", "-e", `${commit}^{commit}`).status !== 0) {
const head = git("rev-parse", "--short=12", "HEAD");
return {
unverified: `${checkout} at HEAD ${head.status === 0 ? head.stdout.trim() : "(unreadable)"} does not have the pinned commit; fetch it to check these`,
};
}
const listing = git("ls-tree", "-r", "-t", "-z", "--name-only", commit);
if (listing.status !== 0) return { unverified: `git ls-tree failed in ${checkout}: ${listing.stderr.trim()}` };
return { paths: new Set(listing.stdout.split("\0").filter((entry) => entry !== "")) };
}
/** Whether `reference` (`../<name>/<path>`) is in the pinned tree, or null when it cannot be checked here. */
function pairedReferenceExists(reference: string): boolean | null {
const [, repository = "", ...inside] = reference.split("/");
const commit = pairedPins.get(repository);
if (commit === undefined) return false;
let tree = pairedTrees.get(repository);
if (tree === undefined) {
tree = readPairedTree(repository, commit);
pairedTrees.set(repository, tree);
}
if ("unverified" in tree) return null;
return inside.length === 0 || tree.paths.has(inside.join("/"));
}
// A backtick span is a path when it starts at a top-level entry, at an entry
// beside the document or at a paired repository; line numbers and anchors are
@@ -223,13 +270,13 @@ function namedPath(token: string, document: string): string | null {
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}`;
if (pairedPins.has(first)) return `../${candidate}`;
return first !== "." && first !== ".." && exists(join(dirname(document), first))
? join(dirname(document), candidate)
: null;
}
// A link that leaves the repository is kept (`../…`); the caller looks it up
// beside the checkout.
// in the paired repositories.
function linkedPath(target: string, document: string): string | null {
if (/^(?:[a-z][a-z+.-]*:|#)/iu.test(target)) return null;
return normalize(join(dirname(document), target.replace(/#.*$/u, "")));
@@ -304,16 +351,10 @@ for (const document of contractDocuments) {
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);
}
// Outside this repository: `../<paired repository>/<path at its pin>`.
const found = pairedReferenceExists(trimmed);
if (found === null) unverifiedLinks.add(trimmed);
else if (!found) missingPaths.add(trimmed);
continue;
}
if (
@@ -416,6 +457,15 @@ if (!passed) {
);
}
}
if (documentReferences.some((entry) => entry.missingPaths.some((file) => file.startsWith("../")))) {
const checked = [...pairedTrees]
.filter(([, tree]) => "paths" in tree)
.map(([repository]) => `${repository} ${pairedPins.get(repository)?.slice(0, 12)}`);
process.stderr.write(
`A path outside this repository must be in a repository ${PAIRED_PIN} pins, at the pinned commit` +
`${checked.length > 0 ? ` (looked up in ${checked.join(", ")})` : ""}\n`,
);
}
if (!reportDigestValid) {
process.stderr.write(
`${ledger.evidenceReport.repoPath} does not contain the ledger's canonicalSha256\n`,
@@ -438,9 +488,12 @@ if (!passed) {
}
const unverified = documentReferences.flatMap((entry) => entry.unverifiedLinks);
if (unverified.length > 0) {
const reasons = [...pairedTrees].flatMap(([repository, tree]) =>
"unverified" in tree ? [`${repository} pinned at ${pairedPins.get(repository)?.slice(0, 12)}: ${tree.unverified}`] : [],
);
process.stdout.write(
`Documentation readiness: ${unverified.length} reference(s) into paired repositories not verified ` +
`(no checkout beside ${process.cwd()}): ${[...new Set(unverified)].join(", ")}\n`,
`(${reasons.join("; ")}): ${[...new Set(unverified)].join(", ")}\n`,
);
}
process.stdout.write("Documentation readiness: PASS_SCOPED\n");