Files
clean-architecture-frontend…/scripts/check-adapter-inventory.ts
T
DongHyeonka d3e4ab7ab4 fix(inventory): abort ratchet에 여유를 두지 않고 지운 선택 그룹을 건너뛴다
문제: 손수 짠 abort 배선 상한이 13인데 실제는 12다. http/client.ts를 지울 때 상수를 내리지 않아 래칫이 한 번은 막지 못한다. 머리 주석은 지금은 커널을 쓰는 두 파일을 사본이라 적고 23개라 한다(1112/02-04). 필수 abort 소비자 넷은 선택 그룹 browser-transfer 파일이라, 제품이 그 그룹을 지우면 원인 없이 실패한다(0929/01-04).

고른 방법: 상한을 12로 내리고 개수가 상한과 다르면 줄어도 실패하게 한다(어느 상수를 몇으로 내리라고 말한다). 낡은 주석을 고친다. 없는 필수 소비자는 건너뛴다. 남은 파일이 공용 primitive를 안 쓰는 것만 막는다.

위험·한계: release-artifacts.ts가 레시피 ID를 말하게 하는 0929/01-04 둘째 반은 그룹 C가 고치는 파일이라 이 커밋에 없다.

검증: desktop 결과는 PR 본문.

Refs: 1112/02-04, 0929/01-04
2026-11-13 20:17:04 +09:00

283 lines
12 KiB
TypeScript

import { readFile } from "node:fs/promises";
import { existsSync, readFileSync } from "node:fs";
import path from "node:path";
import { spawnSync } from "node:child_process";
import { CACHEABLE_ASSET_CONTENT_TYPES } from "../src/contracts/service-worker-static-manifest.ts";
import { selectRepositoryPaths } from "./lib/repository-layout.ts";
/**
* GOV-01 / SW-RR-03. Structural gates for facts that a hand-maintained document
* cannot keep true.
*
* The adapter review inventory claimed 118/118 while the tree held 119 files,
* so a whole adapter was outside every review's coverage without anything
* failing. And the Service Worker asset generator and the shared manifest
* decoder each carried their own extension table, so a build could emit an
* asset the runtime contract then refused. Both are now equalities this script
* checks rather than numbers someone has to remember to update.
*/
const INVENTORY_PATH = "docs/reviews/adapters/INVENTORY.md";
const GENERATOR_PATH = "scripts/generate-service-worker-assets.ts";
function trackedAdapterFiles(): readonly string[] {
const listed = spawnSync("git", ["ls-files", "src/adapters"], {
encoding: "utf8",
});
if (listed.status !== 0) {
throw new Error(`git ls-files failed: ${listed.stderr}`);
}
return listed.stdout.split("\n").filter(Boolean).sort();
}
function inventoryRows(markdown: string): readonly string[] {
const rows: string[] = [];
for (const line of markdown.split("\n")) {
const match = /^\|\s*\d+\s*\|\s*`([^`]+)`\s*\|/u.exec(line);
if (match?.[1]) rows.push(match[1]);
}
return rows;
}
function reportDifference(
label: string,
expected: readonly string[],
actual: readonly string[],
): readonly string[] {
const missing = expected.filter((value) => !actual.includes(value));
const extra = actual.filter((value) => !expected.includes(value));
const problems: string[] = [];
for (const value of missing) problems.push(`${label}: missing ${value}`);
for (const value of extra) problems.push(`${label}: unexpected ${value}`);
return problems;
}
async function main(): Promise<void> {
const problems: string[] = [];
const tracked = trackedAdapterFiles();
const markdown = await readFile(INVENTORY_PATH, "utf8");
const listed = inventoryRows(markdown);
problems.push(...reportDifference("adapter inventory", tracked, listed));
if (listed.length !== new Set(listed).size) {
problems.push("adapter inventory: duplicate row");
}
const total = /합계: \*\*(\d+)\/(\d+)\*\*/u.exec(markdown);
if (
!total ||
Number(total[1]) !== tracked.length ||
Number(total[2]) !== tracked.length
) {
problems.push(
`adapter inventory: total does not equal ${tracked.length} tracked files`,
);
}
// SW-RR-03. The generator must read the shared table rather than declare one.
const generator = await readFile(GENERATOR_PATH, "utf8");
if (!generator.includes("CACHEABLE_ASSET_CONTENT_TYPES")) {
problems.push(
"service worker assets: generator does not use the shared extension table",
);
}
if (/const CACHEABLE_EXTENSIONS[^=]*=\s*Object\.freeze\(\{/u.test(generator)) {
problems.push(
"service worker assets: generator declares its own extension table",
);
}
for (const [extension, contentType] of Object.entries(
CACHEABLE_ASSET_CONTENT_TYPES,
)) {
if (!extension.startsWith(".") || contentType.length === 0) {
problems.push(`service worker assets: invalid table row ${extension}`);
}
}
// A fixture that links the repository's node_modules with a single directory
// symlink is destructive: pnpm running inside that fixture purges the modules
// directory it does not recognise, follows the link, and deletes the real
// dependencies mid-run. `linkFixtureNodeModules` is the only sanctioned form.
const sources = spawnSync(
"git",
["grep", "-n", "-e", 'symlink(', "--", ...selectRepositoryPaths("fixture-code")],
{ encoding: "utf8" },
);
if (sources.status === 0) {
for (const line of sources.stdout.split("\n").filter(Boolean)) {
if (!line.includes("node_modules")) continue;
if (line.startsWith("scripts/lib/fixture-node-modules.ts:")) continue;
problems.push(
`fixture node_modules: use linkFixtureNodeModules instead — ${line}`,
);
}
}
const linkedFixtures = spawnSync(
"git",
["grep", "-l", "linkFixtureNodeModules", "--", ...selectRepositoryPaths("fixture-code")],
{ encoding: "utf8" },
);
if (
linkedFixtures.status !== 0 ||
linkedFixtures.stdout.split("\n").filter(Boolean).length < 2
) {
problems.push(
"fixture node_modules: the shared linker has no callers, so it is not the sanctioned path",
);
}
// TR-RR-05 / GOV-04. Every consumer the re-review named must use the shared
// primitive, not merely one file somewhere. Checking `importers.length > 0`
// let an unrelated production import satisfy the gate while Image and
// Resumable kept their own diverging copies of the same mechanics — which is
// exactly how the four hand-written versions drifted apart in the first place.
//
// 이 목록은 재검토가 이름으로 지목한 네 파일만 덮는다. 나머지 어댑터의
// 손수 짠 abort 배선은 아래 래칫이 센다.
//
// 0929/01-04. 넷 다 선택 adapter 그룹(`browser-transfer`) 파일이다. 제품이
// 그 그룹을 통째로 지우면 소비자가 없는 것이 맞으니 건너뛴다. 그룹이
// 남았는데 목록의 파일이 없으면(이름을 바꿨다) 목록을 고치라고 실패한다.
// 그렇지 않으면 바뀐 이름의 파일이 검사에서 조용히 빠진다.
const REQUIRED_ABORT_CONSUMERS: readonly string[] = [
"src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts",
"src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts",
"src/adapters/browser-transfer/image-cdn/browser-image-probe.ts",
"src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts",
];
const primitiveImporters = spawnSync(
"git",
["grep", "-l", "platform/abortable-operation.ts", "--", "src"],
{ encoding: "utf8" },
);
const importers = (
primitiveImporters.status === 0 ? primitiveImporters.stdout : ""
)
.split("\n")
.filter(Boolean)
.filter((file) => !file.endsWith("platform/abortable-operation.ts"))
.sort();
const importerSet = new Set(importers);
const transferGroupRemoved = !existsSync("src/adapters/browser-transfer");
const presentConsumers = transferGroupRemoved ? [] : REQUIRED_ABORT_CONSUMERS;
const renamedConsumers = presentConsumers.filter((consumer) => !existsSync(consumer));
if (renamedConsumers.length > 0) {
problems.push(
`abortable-operation: REQUIRED_ABORT_CONSUMERS in scripts/check-adapter-inventory.ts names files that do not exist while src/adapters/browser-transfer does: ${renamedConsumers.join(", ")}. Point it at the renamed files.`,
);
}
const missingConsumers = presentConsumers.filter(
(consumer) => existsSync(consumer) && !importerSet.has(consumer),
);
if (missingConsumers.length > 0) {
problems.push(
`abortable-operation: required consumers do not import the shared primitive: ${missingConsumers.join(
", ",
)}`,
);
}
// The importer must reach the primitive by a specifier that resolves to the
// primitive itself, so a same-named local helper cannot satisfy the gate.
const PRIMITIVE_PATH = path.resolve(
"src/adapters/platform/abortable-operation.ts",
);
const PRIMITIVE_SPECIFIER = "platform/abortable-operation.ts";
for (const consumer of presentConsumers) {
if (!importerSet.has(consumer)) continue;
const source = readFileSync(consumer, "utf8");
const specifiers = [
...source.matchAll(/from\s+"([^"]*platform\/abortable-operation\.ts)"/gu),
].map((match) => match[1] ?? "");
const resolved = specifiers.some(
(specifier) =>
path.resolve(path.dirname(consumer), specifier) === PRIMITIVE_PATH,
);
if (!resolved) {
problems.push(
`abortable-operation: ${consumer} does not resolve its import to the shared primitive`,
);
}
}
// 손수 짠 abort 배선은 줄어들기만 해야 한다.
//
// 커널 `platform/abortable-operation.ts`가 있는데도 일부 어댑터 파일이
// `addEventListener("abort")`로 같은 race/cleanup을 각자 짠다(개수는 아래
// 상수). 그 전수 이행은 동작이 바뀌는 큰 작업이라 한 번에 하지 않는다. 대신
// 개수를 여기 고정해 되돌아가지 못하게 한다. 이행으로 숫자가 내려가면 이
// 상수도 같이 내려야 검사가 통과한다.
// `platform/`은 커널 자신이므로 세지 않는다.
//
// 24 → 23: `browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts`가
// IndexedDB 커널로 옮겨가면서 자기 abort 리스너를 지웠다.
// 23 → 22: `storage/indexeddb/indexeddb-maintenance.ts`가 같은 이유로 지웠다.
// 22 → 21: `storage/indexeddb/indexeddb-runtime.ts`가 같은 이유로 지웠다.
// 이것으로 IndexedDB 어댑터 4벌이 모두 커널을 쓴다.
// 21 → 19: `browser-files/download-delivery-adapter.ts`와
// `browser-files/browser-file-vault.ts`가 커널 race로 옮겨갔다(Q-6.2-7).
// 19 → 18: `browser-file-storage/storage-manager-adapter.ts`의 inspection
// 대기가 커널 race로 옮겨갔다(Q-B).
// 17 → 16: `browser-transfer/image-cdn/image-cdn-runtime.ts`의 검증 deadline과
// probe 대기가 커널 operation으로 옮겨갔다(R3-2).
// 16 → 15: `browser-files/browser-file-picker.ts`의 native input 대기와
// system picker 대기가 커널 operation으로 옮겨갔다(R3-2).
// 15 → 13: `storage/opfs/opfs-worker-client.ts`가 커널 abort primitive를 쓰고,
// `storage/indexeddb/indexeddb-governance.ts`의 binding 검증이 커널
// 트랜잭션으로 옮겨갔다(05-07, 05-12).
// 13 → 12: V2 HTTP 경로 `http/client.ts`를 지웠다(2026-11-03). 그때 상수를
// 내리지 않아 래칫이 한 번은 막지 못했다(1112/02-04). 그래서 이제는 개수가
// 상수와 다르면 줄어도 실패한다.
const HAND_ROLLED_ABORT_CEILING = 12;
const handRolledScan = spawnSync(
"git",
["grep", "-l", 'addEventListener("abort"', "--", "src/adapters"],
{ encoding: "utf8" },
);
const handRolledFiles = (
handRolledScan.status === 0 ? handRolledScan.stdout : ""
)
.split("\n")
.filter(Boolean)
.filter((file) => !file.startsWith("src/adapters/platform/"))
.filter((file) => !readFileSync(file, "utf8").includes(PRIMITIVE_SPECIFIER))
.sort();
if (handRolledFiles.length > HAND_ROLLED_ABORT_CEILING) {
problems.push(
`abortable-operation: hand-rolled abort wiring grew to ` +
`${handRolledFiles.length} files (ceiling ${HAND_ROLLED_ABORT_CEILING}). ` +
`Use platform/abortable-operation.ts instead of a new listener pair. ` +
`Current offenders (the new one is whichever this change added): ` +
`${handRolledFiles.join(", ")}`,
);
} else if (handRolledFiles.length < HAND_ROLLED_ABORT_CEILING) {
problems.push(
`abortable-operation: hand-rolled abort wiring fell to ` +
`${handRolledFiles.length} files: lower HAND_ROLLED_ABORT_CEILING ` +
`(${HAND_ROLLED_ABORT_CEILING}) in scripts/check-adapter-inventory.ts to ` +
`${handRolledFiles.length} with a line saying which file moved, so the ` +
`ratchet keeps no slack. Files: ${handRolledFiles.join(", ")}`,
);
}
if (problems.length > 0) {
for (const problem of problems) console.error(problem);
process.exitCode = 1;
return;
}
// GOV-04. The exact importer set is part of the receipt, so a reviewer can
// see which consumers the gate actually verified rather than a bare count.
console.log(
`Adapter inventory: ${tracked.length} files PASS; ` +
`service worker asset table: ${
Object.keys(CACHEABLE_ASSET_CONTENT_TYPES).length
} shared extensions PASS; ` +
`fixture node_modules linking PASS; ` +
`shared abort primitive: ${importers.length} importers ` +
`(${importers.join(", ")}) PASS; ` +
`hand-rolled abort wiring: ${handRolledFiles.length}/` +
`${HAND_ROLLED_ABORT_CEILING} files (ratchet) PASS`,
);
}
await main();