diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index 1bfd017d..fcc4754a 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -22,6 +22,7 @@ }, { "name": "presentation-does-not-know-adapters", + "comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.", "severity": "error", "from": { "path": "^src/presentation/(?!adapters/query)" @@ -127,7 +128,7 @@ }, { "name": "external-contract-package-single-import-path", - "comment": "§4.1: a generated service package may only be imported from src/features//contracts/*-contract-contribution.ts", + "comment": "§4.1: a generated service package may only be imported from src/features//contracts/*-contract-contribution.ts. Owner: frontend-platform.", "severity": "error", "from": { "path": "^src", @@ -205,7 +206,7 @@ }, { "name": "generic-presentation-does-not-compose-the-product", - "comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Generic presentation reads the installed registries directly today; the paths below are the exact set that does so, frozen so the coupling cannot spread while the assembly is lifted into bootstrap.", + "comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Exception: the generic presentation modules in pathNot read the installed registries today. The list names exact files, so a new module that reads a registry fails the gate. Owner: frontend-platform. Revisit when the assembly is lifted into bootstrap; remove each file from the list as it stops reading the registries.", "severity": "error", "from": { "path": "^src/presentation/", @@ -217,7 +218,7 @@ }, { "name": "adapters-do-not-know-other-concrete-adapters", - "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. Only the adapter kernel is shared — `src/adapters/platform` (clock, abort primitive, capacity guard) and the browser-data result helpers. `query-cache` still reads two collaborator types from `cross-context-invalidation`; that edge is named here rather than left silent, and closes when those types are lifted to a port.", + "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (clock, abort primitive, capacity guard), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.", "severity": "error", "from": { "path": "^src/adapters/([^/]+)/" @@ -229,7 +230,7 @@ }, { "name": "adapter-groups-are-reached-through-their-barrel", - "comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 도착점에서 1단계 중첩 index.ts를 허용한 이유는 storage/indexeddb와 storage/opfs가 각자 독립적으로 제거 가능한 런타임이고(scripts/test-browser-file-storage-runtime-removal.ts), 그래서 각자의 배럴이 곧 경계이기 때문이다.", + "comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 예외: 도착점에서 storage/indexeddb/index.ts와 storage/opfs/index.ts만 서브배럴로 허용한다. 두 폴더는 각자 독립적으로 제거 가능한 런타임이고(scripts/test-browser-file-storage-runtime-removal.ts), 그래서 각자의 배럴이 곧 경계다. 다른 2단계 index.ts는 공개 배럴이 아니다(리뷰 12-07). 담당: frontend-platform. 재검토: 새 런타임을 따로 제거할 수 있게 만들 때 그 서브배럴을 이 목록에 추가한다.", "severity": "error", "from": { "path": "^src/", @@ -237,7 +238,7 @@ }, "to": { "path": "^src/adapters/[^/]+/", - "pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/[^/]+/[^/]+/index\\.ts$" + "pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/storage/(indexeddb|opfs)/index\\.ts$" } }, { @@ -302,7 +303,7 @@ }, { "name": "platform-kernel-is-product-neutral", - "comment": "Spec §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Routing composes deployable-app descriptors by type and is the one named exception.", + "comment": "Spec §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Exception: src/platform/routing composes deployable-app descriptors by type. Owner: frontend-platform. Revisit if routing gains a product-specific import.", "severity": "error", "from": { "path": "^src/platform/", diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md index fdc25792..dbb26e58 100644 --- a/docs/architecture/layers.md +++ b/docs/architecture/layers.md @@ -44,14 +44,25 @@ purpose and is the only adapter code an adapter may reach across a group for: the bounded-capacity guard - `src/adapters/browser-file-storage/result.ts` — the browser-data result and failure constructors +- `src/adapters/cross-context-invalidation/index.ts` — the cross-context + invalidation transport and its types. Any adapter may import it; today + `query-cache` does Each rule above is enforced by `check:architecture`, including the kernel -carve-out, so this table and the executable rules cannot drift apart. Two edges -are still open and are named explicitly in `.dependency-cruiser.json` rather -than left silent: the generic presentation modules that read the installed -registries today, and the two collaborator types `query-cache` reads from -`cross-context-invalidation`. Both lists are frozen — a new edge of either kind -fails the gate. +carve-out, so this table and the executable rules cannot drift apart. + +Every exception is written in the rule itself (`.dependency-cruiser.json`): the +exempted path in `pathNot`, and the reason, owner and revisit condition in +`comment` (review 12-07). Besides the kernel, the exceptions are: + +- the generic presentation modules that read the installed registries today + (`generic-presentation-does-not-compose-the-product`). The list names exact + files, so a new module that reads a registry fails the gate +- `src/presentation/adapters/query`, the TanStack Query binding + (`presentation-does-not-know-adapters`) +- `src/presentation/routes/app-router.tsx` importing the app + (`presentation-does-not-import-apps-or-contexts`) +- the design-system facades (`design-system-is-reached-through-its-index`) ## 어댑터 그룹의 공개 경계 @@ -74,8 +85,9 @@ fails the gate. `storage`는 최상위 배럴이 `indexeddb/`·`opfs/` 서브배럴을 재수출하지 않는다. 두 런타임이 각자 독립적으로 제거 가능하고 (`test:browser-file-storage-removal`), 그래서 각 서브배럴이 곧 경계다. -규칙의 도착점 정규식이 1단계 중첩 `index.ts`를 배럴로 인정하는 이유가 -이것이다. +규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계 +`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서 +import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture). `service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에 들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 49bbf517..8a3cf49f 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,6 +1,11 @@ allowBuilds: esbuild: true msw: true +# 12-07. These exact pins were added on 2026-07-25 (946cf40, f3e105f) while +# they were younger than pnpm's minimum release age. An exclusion covers that +# exact version only, so a later version is checked again. Owner: +# frontend-platform. Revisit: remove an entry when its version is bumped or is +# older than the configured minimum release age. minimumReleaseAgeExclude: - '@playwright/test@1.62.0' - playwright-core@1.62.0 diff --git a/scripts/check-architecture.ts b/scripts/check-architecture.ts index cc9f897e..92b7e6a0 100644 --- a/scripts/check-architecture.ts +++ b/scripts/check-architecture.ts @@ -931,6 +931,21 @@ async function runGraphFixtureChecks(): Promise { target === "src/adapters/http/client.ts", ), }, + { + name: "second-level index import from outside the group is rejected", + passed: blockingViolations(barrelGraph).some( + ({ rule, source, target }) => + rule === "adapter-groups-are-reached-through-their-barrel" && + source === "src/bootstrap/compose-sub-barrel.ts" && + target === "src/adapters/http/internals/index.ts", + ), + }, + { + name: "storage runtime sub-barrel import is accepted", + passed: !blockingViolations(barrelGraph).some( + ({ source }) => source === "src/bootstrap/compose-storage-sub-barrel.ts", + ), + }, { name: "barrel import from outside the group is accepted", passed: !blockingViolations(barrelGraph).some( diff --git a/tests/fixtures/architecture/dependency-graph/barrel/adapters/http/internals/index.ts b/tests/fixtures/architecture/dependency-graph/barrel/adapters/http/internals/index.ts new file mode 100644 index 00000000..deebf36f --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/barrel/adapters/http/internals/index.ts @@ -0,0 +1 @@ +export { createFixtureHttpClient as createInternalClient } from "../client.ts"; diff --git a/tests/fixtures/architecture/dependency-graph/barrel/adapters/storage/indexeddb/index.ts b/tests/fixtures/architecture/dependency-graph/barrel/adapters/storage/indexeddb/index.ts new file mode 100644 index 00000000..bbeeb341 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/barrel/adapters/storage/indexeddb/index.ts @@ -0,0 +1 @@ +export const openFixtureDatabase = (): string => "indexeddb"; diff --git a/tests/fixtures/architecture/dependency-graph/barrel/bootstrap/compose-storage-sub-barrel.ts b/tests/fixtures/architecture/dependency-graph/barrel/bootstrap/compose-storage-sub-barrel.ts new file mode 100644 index 00000000..3d5641db --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/barrel/bootstrap/compose-storage-sub-barrel.ts @@ -0,0 +1,4 @@ +// storage/indexeddb is an independently removable runtime; its index.ts is the boundary. +import { openFixtureDatabase } from "../adapters/storage/indexeddb/index.ts"; + +export const storageComposition = openFixtureDatabase; diff --git a/tests/fixtures/architecture/dependency-graph/barrel/bootstrap/compose-sub-barrel.ts b/tests/fixtures/architecture/dependency-graph/barrel/bootstrap/compose-sub-barrel.ts new file mode 100644 index 00000000..3a2892f2 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/barrel/bootstrap/compose-sub-barrel.ts @@ -0,0 +1,4 @@ +// 12-07 P3b: a second-level index.ts is not a public barrel. +import { createInternalClient } from "../adapters/http/internals/index.ts"; + +export const subBarrelComposition = createInternalClient;