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;