From 7f2a1607f3174daf09f81b7fa2f65a9b0b081ab0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:33:14 +0900 Subject: [PATCH] refactor(architecture): move regex import rules into the import graph (12-10, 12-08) Icon vendor, design-system deep import and realtime composition were regular expressions beside graph rules, and the regex missed relative deep imports inside presentation. They are graph rules with fixtures now, with the components/ui facades and page-templates named. package-script-graph.ts stays; the reason is recorded. Co-Authored-By: Claude Opus 5.5 --- .dependency-cruiser.json | 25 +++++++++++++ .../decisions/VD-05-icon-and-headless-ui.md | 15 ++++++-- docs/operations/ci-quality-gates.md | 10 ++++++ scripts/check-architecture.ts | 35 +++++++++++++++++++ scripts/check-design-system.ts | 16 +++------ scripts/check-realtime-boundary-fixtures.ts | 1 - scripts/contracts/release-artifacts.ts | 1 - scripts/lib/package-script-graph.ts | 15 ++++++++ scripts/lib/realtime-boundaries.ts | 16 +++------ .../adapters/realtime/index.ts | 1 + .../bootstrap/compose-realtime.ts | 4 +++ .../presentation/components/ui/button.ts | 2 ++ .../presentation/design-system/index.ts | 1 + .../design-system/primitives/core.ts | 1 + .../presentation/pages/deep-import.ts | 4 +++ .../presentation/pages/direct-icon.ts} | 1 + .../presentation/pages/public-import.ts | 3 ++ .../design-system/forbidden/deep-import.tsx | 3 -- .../src/bootstrap/composed-realtime.ts | 3 -- 19 files changed, 122 insertions(+), 35 deletions(-) create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/adapters/realtime/index.ts create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/bootstrap/compose-realtime.ts create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/components/ui/button.ts create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/design-system/index.ts create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/design-system/primitives/core.ts create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/deep-import.ts rename tests/fixtures/{design-system/forbidden/direct-icon.tsx => architecture/dependency-graph/import-boundaries/presentation/pages/direct-icon.ts} (51%) create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/public-import.ts delete mode 100644 tests/fixtures/design-system/forbidden/deep-import.tsx delete mode 100644 tests/fixtures/realtime-boundaries/forbidden/src/bootstrap/composed-realtime.ts diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index a86cdf45..c48b20db 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -42,6 +42,7 @@ }, { "name": "icon-vendor-is-facade-only", + "comment": "VD-05. lucide-react is imported by the icon vendor facade only; product code uses the semantic icons from the design-system index, so replacing the vendor touches one file.", "severity": "error", "from": { "path": "^src", @@ -51,6 +52,19 @@ "path": "^lucide-react$" } }, + { + "name": "design-system-is-reached-through-its-index", + "comment": "VD-05, 12-08. Code outside src/presentation/design-system imports its public index.ts only, so the primitives can change behind it. Named facades: src/presentation/components/ui/*.ts re-export the canonical primitives under their pre-VD-05 paths (VD-05 Rollback). Exception: src/presentation/templates/page-templates.tsx reads PaginationLandmarkContext, which index.ts does not export. Owner: frontend-platform. Revisit: export it from index.ts or move the page templates into the design system.", + "severity": "error", + "from": { + "path": "^src/", + "pathNot": "^src/presentation/(design-system/|components/ui/[^/]+\\.ts$|templates/page-templates\\.tsx$)" + }, + "to": { + "path": "^src/presentation/design-system/", + "pathNot": "^src/presentation/design-system/index\\.ts$" + } + }, { "name": "adapters-do-not-know-presentation", "severity": "error", @@ -134,6 +148,17 @@ "path": "^src/adapters/(http|realtime|service-worker|web-worker|storage)" } }, + { + "name": "unselected-realtime-runtime-is-not-composed", + "comment": "§9.2 / 12-10. Realtime and Web Push are NOT_SELECTED in the template (src/features/installed-runtime-capabilities.ts), so the composition root and the installed-feature registries do not import their concrete adapters. A project that selects one replaces this rule when it wires the runtime. Owner: frontend-platform.", + "severity": "error", + "from": { + "path": "^src/(bootstrap/|features/installed-feature-)" + }, + "to": { + "path": "^src/adapters/(realtime|web-push)/" + } + }, { "name": "generic-worker-has-no-network-or-credentials", "comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth", diff --git a/docs/architecture/decisions/VD-05-icon-and-headless-ui.md b/docs/architecture/decisions/VD-05-icon-and-headless-ui.md index 9bda349f..46dc2499 100644 --- a/docs/architecture/decisions/VD-05-icon-and-headless-ui.md +++ b/docs/architecture/decisions/VD-05-icon-and-headless-ui.md @@ -38,9 +38,18 @@ ## 경계와 검증 -- 제품 코드는 `presentation/design-system/index`만 import한다. -- design-system 검사기는 direct icon/headless import, deep import, raw palette, - undefined token과 tooltip-only required information fixture를 거절한다. +- 제품 코드는 `presentation/design-system/index`만 import한다. 예외는 규칙에 + 이름으로 적는다. `presentation/components/ui/*.ts`는 아래 Rollback의 재수출 + facade이고, `presentation/templates/page-templates.tsx`는 index가 내보내지 + 않는 `PaginationLandmarkContext`를 읽는다. +- deep import와 direct icon import는 `check:architecture` 그래프 규칙 + `design-system-is-reached-through-its-index`, `icon-vendor-is-facade-only` + (`.dependency-cruiser.json`)가 거절한다. 경로 해석이 끝난 간선을 보므로 + presentation 안의 상대 경로 import도 잡는다(리뷰 12-08). 음성 fixture는 + `tests/fixtures/architecture/dependency-graph/import-boundaries`다. +- design-system 검사기(`scripts/check-design-system.ts`)는 headless vendor + import, raw palette, undefined token과 tooltip-only required information + fixture를 거절한다. - type negative fixture는 accessible name 없는 `IconButton`을 거절한다. - component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를 검증한다. diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index d8c5afa6..89239eed 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -94,6 +94,16 @@ The gate runner checks the same inherited environment names before loading the contract or entering the execution callback, so they cannot reach a child gate process. +이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 12-10에서 줄일 수 +있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와 +`pnpm-workspace.yaml`의 `allowBuilds`로는 막히지 않는 위험이 있기 때문이다. +첫째, 게이트 명령이 직접 설치를 돈다(`verify:lockfile`, 제거 fixture). +`allowBuilds`는 pnpm의 의존성 build script만 제한한다. 루트 프로젝트의 install +hook과 npm/yarn 설치는 `--ignore-scripts`가 없으면 그대로 돈다. 둘째, 게이트가 +부르는 이름이 다른 manifest의 script로 바뀌는 경로다(`--prefix`, `--filter`, +`-C`, npm pre/post hook, `npm_config_*`). 이것은 설치 옵션과 관계가 없다. 이유는 +파일 머리 주석에도 있다. + The dependency graph is: ```text diff --git a/scripts/check-architecture.ts b/scripts/check-architecture.ts index 5ae83ee8..0683b130 100644 --- a/scripts/check-architecture.ts +++ b/scripts/check-architecture.ts @@ -831,6 +831,7 @@ async function runGraphFixtureChecks(): Promise { cycleGraph, barrelGraph, crossBoundaryGraph, + importBoundaryGraph, ] = await Promise.all([ analyzeSourceGraph(allowedRoot, "src"), analyzeSourceGraph(resolve(fixtureRoot, "unresolved"), "src"), @@ -838,6 +839,7 @@ async function runGraphFixtureChecks(): Promise { analyzeSourceGraph(resolve(fixtureRoot, "cycle"), "src"), analyzeSourceGraph(resolve(fixtureRoot, "barrel"), "src"), analyzeSourceGraph(resolve(fixtureRoot, "cross-boundary"), "src"), + analyzeSourceGraph(resolve(fixtureRoot, "import-boundaries"), "src"), ]); const allowedFiles = new Set(await listFiles(allowedRoot)); const allowedSourceFile = resolve( @@ -903,6 +905,39 @@ async function runGraphFixtureChecks(): Promise { target === "src/contexts/customer/telemetry.ts", ), }, + // 12-08 / 12-10: these import rules used to be regular expressions in + // check-design-system.ts and realtime-boundaries.ts beside the graph. + { + name: "design-system deep import is rejected", + passed: blockingViolations(importBoundaryGraph).some( + ({ rule, source }) => + rule === "design-system-is-reached-through-its-index" && + source === "src/presentation/pages/deep-import.ts", + ), + }, + { + name: "design-system index and named facades are accepted", + passed: !blockingViolations(importBoundaryGraph).some(({ source }) => + ["src/presentation/pages/public-import.ts", "src/presentation/components/ui/button.ts"].includes(source), + ), + }, + { + name: "direct icon vendor import is rejected", + passed: blockingViolations(importBoundaryGraph).some( + ({ rule, source, target }) => + rule === "icon-vendor-is-facade-only" && + source === "src/presentation/pages/direct-icon.ts" && + target === "lucide-react", + ), + }, + { + name: "unselected realtime runtime composition is rejected", + passed: blockingViolations(importBoundaryGraph).some( + ({ rule, source }) => + rule === "unselected-realtime-runtime-is-not-composed" && + source === "src/bootstrap/compose-realtime.ts", + ), + }, { name: "deep adapter import from outside the group is rejected", passed: blockingViolations(barrelGraph).some( diff --git a/scripts/check-design-system.ts b/scripts/check-design-system.ts index f968faa9..b5f76f8f 100644 --- a/scripts/check-design-system.ts +++ b/scripts/check-design-system.ts @@ -97,22 +97,14 @@ const sources = fixtureMode : await listSourceFiles("src"); for (const file of sources) { const source = await readFile(file, "utf8"); - const vendorFacade = - file === "src/presentation/design-system/icons/vendors/lucide.tsx"; - if (!vendorFacade && /from\s+["']lucide-react["']/.test(source)) { - failures.push(`direct icon vendor import in ${file}`); - } + // Icon vendor and design-system deep imports are graph rules in + // .dependency-cruiser.json (check:architecture), which also sees relative, + // dynamic and type imports (12-08, 12-10). if ( /from\s+["'](?:react-aria-components|@radix-ui\/[^"']+)["']/.test(source) ) { failures.push(`direct headless vendor import in ${file}`); } - if ( - !file.includes("src/presentation/design-system/") && - /presentation\/design-system\/(?!index(?:\.tsx?)?["'])/.test(source) - ) { - failures.push(`design-system deep import in ${file}`); - } if ( !file.includes("src/presentation/design-system/tokens/") && /(?:#[0-9a-f]{3,8}\b|oklch\(|rgba?\()/i.test(source) @@ -151,5 +143,5 @@ if (failures.length > 0) { process.exit(1); } process.stdout.write( - `Design system contract: ${report.checkedTokenCount} tokens and vendor boundaries PASS\n`, + `Design system contract: ${report.checkedTokenCount} tokens and headless vendor boundary PASS\n`, ); diff --git a/scripts/check-realtime-boundary-fixtures.ts b/scripts/check-realtime-boundary-fixtures.ts index 68404833..858984b1 100644 --- a/scripts/check-realtime-boundary-fixtures.ts +++ b/scripts/check-realtime-boundary-fixtures.ts @@ -13,7 +13,6 @@ const forbiddenOutput = `${forbidden.stdout}${forbidden.stderr}`; const expectedRules = [ "NATIVE_REALTIME_API_OUTSIDE_ADAPTER", "PRESENTATION_INTERVAL_OWNER", - "UNSELECTED_REALTIME_RUNTIME_COMPOSED", ] as const; if ( diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index 2bfae290..63c6f425 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -1054,7 +1054,6 @@ export const realtimeBoundariesArtifactSchema = z ruleId: z.enum([ "NATIVE_REALTIME_API_OUTSIDE_ADAPTER", "PRESENTATION_INTERVAL_OWNER", - "UNSELECTED_REALTIME_RUNTIME_COMPOSED", ]), file: nonEmptyString, line: z.int().positive(), diff --git a/scripts/lib/package-script-graph.ts b/scripts/lib/package-script-graph.ts index e4242aef..bab18ab3 100644 --- a/scripts/lib/package-script-graph.ts +++ b/scripts/lib/package-script-graph.ts @@ -1,3 +1,18 @@ +/** + * Package-script graph for the CI contract (D-12, 12-10). Kept after checking + * whether `--ignore-scripts` on the workflow install and `allowBuilds` in + * pnpm-workspace.yaml already close the same risks. They do not: + * + * - Gate commands run installs themselves (`verify:lockfile`, removal + * fixtures). `allowBuilds` limits dependency build scripts under pnpm only; + * the root project's own install hooks and npm/yarn installs still run + * unless the command says `--ignore-scripts`. + * - A gate names a root package script. `--prefix`, `--filter`, `-C`, npm + * pre/post hooks and `npm_config_*` scope variables can make that name run a + * different manifest's script, which no install flag affects. + * - `reachablePackageScripts` is also how the ungated-test check (12-04) finds + * which Vitest paths a gate runs. + */ type PackageManager = "pnpm" | "npm" | "yarn"; type ManagerParseResult = Readonly<{ diff --git a/scripts/lib/realtime-boundaries.ts b/scripts/lib/realtime-boundaries.ts index 16730e77..c5474aa8 100644 --- a/scripts/lib/realtime-boundaries.ts +++ b/scripts/lib/realtime-boundaries.ts @@ -1,10 +1,12 @@ import { readFile, readdir } from "node:fs/promises"; import path from "node:path"; +// Importing the realtime or Web Push adapter from the composition root is the +// graph rule unselected-realtime-runtime-is-not-composed (12-10). This scan +// keeps what an import graph cannot see: native API calls and timers. export type RealtimeBoundaryRuleId = | "NATIVE_REALTIME_API_OUTSIDE_ADAPTER" - | "PRESENTATION_INTERVAL_OWNER" - | "UNSELECTED_REALTIME_RUNTIME_COMPOSED"; + | "PRESENTATION_INTERVAL_OWNER"; export type RealtimeBoundaryViolation = Readonly<{ ruleId: RealtimeBoundaryRuleId; @@ -17,8 +19,6 @@ const OWNED_NATIVE_ROOTS = [ "src/adapters/realtime/", "src/adapters/web-push/", ] as const; -const REALTIME_ADAPTER_IMPORT = - /(?:from\s*|import\s*\()\s*["'][^"']*\/adapters\/(?:realtime|web-push)(?:\/[^"']*)?["']/gu; const NATIVE_REALTIME_PATTERNS = [ /\bnew\s+(?:WebSocket|EventSource|Notification)\s*\(/gu, /\bNotification\s*\.\s*requestPermission\s*\(/gu, @@ -62,9 +62,6 @@ function inspectFile( const presentationOwned = logicalFile.startsWith("src/presentation/") || /^src\/features\/[^/]+\/presentation\//u.test(logicalFile); - const compositionBoundary = - logicalFile.startsWith("src/bootstrap/") || - /^src\/features\/installed-feature-/u.test(logicalFile); const report = ( ruleId: RealtimeBoundaryRuleId, @@ -92,11 +89,6 @@ function inspectFile( report("PRESENTATION_INTERVAL_OWNER", match.index); } } - if (compositionBoundary) { - for (const match of source.matchAll(REALTIME_ADAPTER_IMPORT)) { - report("UNSELECTED_REALTIME_RUNTIME_COMPOSED", match.index); - } - } } async function collectSourceFiles( diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/adapters/realtime/index.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/adapters/realtime/index.ts new file mode 100644 index 00000000..62ea4ce3 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/adapters/realtime/index.ts @@ -0,0 +1 @@ +export const connectRealtime = (): undefined => undefined; diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/bootstrap/compose-realtime.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/bootstrap/compose-realtime.ts new file mode 100644 index 00000000..5f926996 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/bootstrap/compose-realtime.ts @@ -0,0 +1,4 @@ +// The realtime runtime is not selected, so the composition root does not build it. +import { connectRealtime } from "../adapters/realtime/index.ts"; + +export const composedRealtime = connectRealtime; diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/components/ui/button.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/components/ui/button.ts new file mode 100644 index 00000000..d6f73a3c --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/components/ui/button.ts @@ -0,0 +1,2 @@ +// A named facade that re-exports a primitive under its pre-VD-05 path. +export { Button } from "../../design-system/primitives/core.ts"; diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/design-system/index.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/design-system/index.ts new file mode 100644 index 00000000..5ee47a8c --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/design-system/index.ts @@ -0,0 +1 @@ +export { Button } from "./primitives/core.ts"; diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/design-system/primitives/core.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/design-system/primitives/core.ts new file mode 100644 index 00000000..47893f15 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/design-system/primitives/core.ts @@ -0,0 +1 @@ +export const Button = "button"; diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/deep-import.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/deep-import.ts new file mode 100644 index 00000000..8f22bce4 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/deep-import.ts @@ -0,0 +1,4 @@ +// 12-08 P6: a deep import past the design-system index. +import { Button } from "../design-system/primitives/core.ts"; + +export const DeepImport = Button; diff --git a/tests/fixtures/design-system/forbidden/direct-icon.tsx b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/direct-icon.ts similarity index 51% rename from tests/fixtures/design-system/forbidden/direct-icon.tsx rename to tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/direct-icon.ts index ab3aa401..c3ee15d6 100644 --- a/tests/fixtures/design-system/forbidden/direct-icon.tsx +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/direct-icon.ts @@ -1,3 +1,4 @@ +// VD-05: lucide-react is imported only by the icon vendor facade. import { Menu } from "lucide-react"; export const DirectIcon = Menu; diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/public-import.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/public-import.ts new file mode 100644 index 00000000..0a2ef80c --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/public-import.ts @@ -0,0 +1,3 @@ +import { Button } from "../design-system/index.ts"; + +export const PublicImport = Button; diff --git a/tests/fixtures/design-system/forbidden/deep-import.tsx b/tests/fixtures/design-system/forbidden/deep-import.tsx deleted file mode 100644 index 0dbfb971..00000000 --- a/tests/fixtures/design-system/forbidden/deep-import.tsx +++ /dev/null @@ -1,3 +0,0 @@ -import { Button } from "../../../../src/presentation/design-system/primitives/core.tsx"; - -export const DeepImport = Button; diff --git a/tests/fixtures/realtime-boundaries/forbidden/src/bootstrap/composed-realtime.ts b/tests/fixtures/realtime-boundaries/forbidden/src/bootstrap/composed-realtime.ts deleted file mode 100644 index 6324dc05..00000000 --- a/tests/fixtures/realtime-boundaries/forbidden/src/bootstrap/composed-realtime.ts +++ /dev/null @@ -1,3 +0,0 @@ -import { createWebSocketConnection } from "../../../adapters/realtime/websocket/websocket-connection.ts"; - -export const incorrectlyComposed = createWebSocketConnection;