From a37ebba39c10a167d93c8a7fe2c0f55495fd8af0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:36:23 +0900 Subject: [PATCH] =?UTF-8?q?fix(architecture):=20=EA=B8=B0=EB=8A=A5=20?= =?UTF-8?q?=EC=95=88=20=EA=B3=84=EC=B8=B5=20=EB=B0=96=20=ED=8F=B4=EB=8D=94?= =?UTF-8?q?=EA=B0=80=20src/adapters=EC=97=90=20=EB=8B=BF=EC=9C=BC=EB=A9=B4?= =?UTF-8?q?=20=EB=A7=89=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 feature-and-app-roots-do-not-reach-adapters는 기능 루트 파일 (src/features/*.ts, src/features//*.ts), src/contexts, src/apps만 본다. 그래프는 간선 하나씩 검사하므로, 기능 안에 계층이 아닌 폴더(support/ 등)를 만들어 그 파일이 http adapter 배럴을 import하고 기능 presentation이 그 파일을 import하면 presentation이 구체 adapter에 닿는다. 1105 리뷰 12-R3 변이에서 check:architecture와 ESLint가 둘 다 통과했다. 고른 방법 - 규칙의 from을 "src/features 아래 모든 파일, 기능의 adapters/ 폴더 밖"으로 바꾼다(`^src/(features/|contexts/|apps/)`, pathNot `^src/features/([^/]+/adapters/|feature-adapter-contribution\.ts$)`). 규칙 주석이 이미 "기능 안에서는 adapters/ 폴더만 src/adapters에 닿는다"고 적고 있었고, 그 문장을 경로로 옮긴 것이다. 파일 단위 예외는 기존 하나 (feature-adapter-contribution.ts, type only) 그대로고 새로 더하지 않았다. - domain·application·presentation은 자기 규칙이 이미 src/adapters를 막는다. 이제 그 파일들이 src/adapters를 import하면 이 규칙도 같이 걸린다(위반 두 줄). 더 엄격해질 뿐 허용이 바뀌지는 않는다. - 지금 src/features에서 src/adapters를 import하는 곳은 reference-feature의 adapters/ 두 파일과 feature-adapter-contribution.ts뿐이라 새 위반은 없다. create:feature가 만드는 adapter import도 adapters/ 안이다. - 그래프 회귀 fixture에 support/ 재수출(거절), 그것을 읽는 presentation, 기능 adapters/ import(허용)를 더하고 check:architecture에 두 단언을 더했다. 규칙 경로를 check:architecture와 같은 방식으로 읽는 vitest 테스트를 더했다. - layers.md 표와 매뉴얼 01의 설명을 고쳤다. - 버린 대안: 계층 밖 폴더 자체를 금지(폴더 이름 목록 검사). 제품이 contracts/ 같은 다른 이름을 쓰면 계속 목록을 고쳐야 한다. 규칙마다 support/ 패턴 추가: 다음 폴더 이름에서 같은 틈이 난다. 위험·한계 - 다운스트림이 기능 안 adapters/ 밖에서 src/adapters를 import하고 있었다면 이제 check:architecture가 실패한다. 그 파일을 adapters/로 옮기면 된다. - ESLint는 여전히 간선 하나만 보므로 이 경로를 잡지 않는다. 그래프가 잡는다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/architecture/feature-adapter-reach.test.ts, corepack pnpm check:architecture(그래프 fixture 단언 2개 추가 PASS, 저장소 위반 0 기대). - RED 기대: "rejects a concrete adapter import from a feature folder that is not a layer", "leaves a feature's adapters folder and the type-only contribution file to reach adapters"(support/adapters/ 경로 단언). Refs: 0929/12-03 --- .dependency-cruiser.json | 6 +- docs/architecture/layers.md | 2 +- docs/manual/01-add-a-feature.md | 2 +- scripts/check-architecture.ts | 18 ++++++ .../feature-adapter-reach.test.ts | 58 +++++++++++++++++++ .../features/alpha/adapters/telemetry-sink.ts | 2 + .../alpha/presentation/read-support.ts | 3 + .../features/alpha/support/telemetry.ts | 3 + 8 files changed, 89 insertions(+), 5 deletions(-) create mode 100644 tests/architecture/feature-adapter-reach.test.ts create mode 100644 tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/adapters/telemetry-sink.ts create mode 100644 tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/presentation/read-support.ts create mode 100644 tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/support/telemetry.ts diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index 5e19e4f3..e3dab6e9 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -300,11 +300,11 @@ }, { "name": "feature-and-app-roots-do-not-reach-adapters", - "comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers the files outside a feature's layer folders (src/features/*.ts, src/features//*.ts), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the InstalledHttpOperationExecutor type that bootstrap hands to feature adapters (type only). Owner: frontend-platform. Revisit when that type moves to an application port.", + "comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers every file under src/features outside a feature's adapters/ folder (the root files, and any folder that is not a layer, such as support/: 0929/12-03), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the InstalledHttpOperationExecutor type that bootstrap hands to feature adapters (type only). Owner: frontend-platform. Revisit when that type moves to an application port.", "severity": "error", "from": { - "path": "^src/(features/[^/]+\\.tsx?$|features/[^/]+/[^/]+\\.tsx?$|contexts/|apps/)", - "pathNot": "^src/features/feature-adapter-contribution\\.ts$" + "path": "^src/(features/|contexts/|apps/)", + "pathNot": "^src/features/([^/]+/adapters/|feature-adapter-contribution\\.ts$)" }, "to": { "path": "^src/adapters/" diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md index a57351d8..131b3bfc 100644 --- a/docs/architecture/layers.md +++ b/docs/architecture/layers.md @@ -63,7 +63,7 @@ Each row is one `forbidden` rule in `.dependency-cruiser.json`, by its `name`. | `adapter-groups-are-reached-through-their-barrel` | code outside `src/adapters` | adapter files other than a group's `index.ts` and the `storage/indexeddb` and `storage/opfs` sub-barrels | | `features-do-not-import-other-features` | each feature | another feature | | `contexts-do-not-import-other-contexts` | each context | another context | -| `feature-and-app-roots-do-not-reach-adapters` | `src/features/*.ts`, `src/features//*.ts`, `src/contexts`, `src/apps`, except the type-only `src/features/feature-adapter-contribution.ts` | `src/adapters` | +| `feature-and-app-roots-do-not-reach-adapters` | every file in `src/features` outside a feature's `adapters/` folder (the root files and any folder that is not a layer, such as `support/`), `src/contexts`, `src/apps`, except the type-only `src/features/feature-adapter-contribution.ts` | `src/adapters` | | `presentation-does-not-import-apps-or-contexts` | generic and feature presentation, except `src/presentation/routes/app-router.tsx`, which mounts the app's route tree | `src/apps`, `src/contexts` | | `observability-vendors-live-behind-adapters` | code outside `src/adapters` | vendor telemetry SDKs | | `platform-kernel-is-product-neutral` | `src/platform`, except `routing/`, which reads app descriptors by type | features, contexts, apps, adapters, bootstrap, presentation, application | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 6128b020..ca0d1c1e 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -377,7 +377,7 @@ projectRequest: (input) => Object.freeze({ - presentation이 기능 `adapters/`를 import하면 `feature-presentation-does-not-know-outbound-adapters`로 막는다. - adapters가 presentation을 import하면 `feature-adapters-do-not-know-presentation`으로 막는다. -- 기능 루트 파일(`feature-module.ts` 등)이 `src/adapters`에 닿으면 `feature-and-app-roots-do-not-reach-adapters`로 막는다. +- 기능 루트 파일(`feature-module.ts` 등)이나 계층이 아닌 폴더(`support/` 등)의 파일이 `src/adapters`에 닿으면 `feature-and-app-roots-do-not-reach-adapters`로 막는다. 기능 안에서 `src/adapters`에 닿을 수 있는 곳은 `adapters/` 폴더뿐이다. - operation ID·route ID·입력 타입을 틀리면 `check:types`가 막는다. 음성 fixture: `check:types:fixture:http-operation-id`, `check:types:fixture:http-route-id`, `check:types:fixture:http-operation-input`. - 호스트가 주지 않는 capability를 `needs`에 적으면 조립이 실패한다. - 메시지: `feature needs , which the host did not provide` diff --git a/scripts/check-architecture.ts b/scripts/check-architecture.ts index f4bcba5b..fbb07a33 100644 --- a/scripts/check-architecture.ts +++ b/scripts/check-architecture.ts @@ -820,6 +820,24 @@ async function runGraphFixtureChecks(): Promise { 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( diff --git a/tests/architecture/feature-adapter-reach.test.ts b/tests/architecture/feature-adapter-reach.test.ts new file mode 100644 index 00000000..6e4771f2 --- /dev/null +++ b/tests/architecture/feature-adapter-reach.test.ts @@ -0,0 +1,58 @@ +import { readFile } from "node:fs/promises"; + +import { describe, expect, it } from "vitest"; + +/** + * 0929/12-03. The graph checks one edge at a time, so a file that feature + * presentation may import must not reach a concrete adapter. The rule covered + * the feature root files only: a file in a feature folder that is not a layer + * (`support/`) imported the http adapter barrel, presentation imported it, + * and check:architecture and ESLint both passed (review 1105, 12-R3). This + * reads the rule as check:architecture does (`from.path`, `from.pathNot` and + * `to.path` as unicode regular expressions). + */ +type DependencyRule = Readonly<{ + name: string; + from: Readonly<{ path?: string; pathNot?: string }>; + to: Readonly<{ path?: string }>; +}>; + +async function rule(name: string): Promise<(source: string, target: string) => boolean> { + const { forbidden } = JSON.parse(await readFile(".dependency-cruiser.json", "utf8")) as { + forbidden: DependencyRule[]; + }; + const found = forbidden.find((candidate) => candidate.name === name); + if (!found) throw new Error(`no rule ${name}`); + const from = new RegExp(found.from.path ?? "", "u"); + const fromNot = found.from.pathNot === undefined ? null : new RegExp(found.from.pathNot, "u"); + const to = new RegExp(found.to.path ?? "", "u"); + return (source, target) => from.test(source) && !(fromNot?.test(source) ?? false) && to.test(target); +} + +const HTTP_BARREL = "src/adapters/http/index.ts"; + +describe("feature-and-app-roots-do-not-reach-adapters (0929/12-03)", () => { + it("rejects a concrete adapter import from a feature folder that is not a layer", async () => { + const applies = await rule("feature-and-app-roots-do-not-reach-adapters"); + expect(applies("src/features/catalog/support/direct-http.ts", HTTP_BARREL)).toBe(true); + expect(applies("src/features/catalog/support/nested/direct-http.tsx", HTTP_BARREL)).toBe(true); + }); + + it("still rejects the feature root files, contexts and apps", async () => { + const applies = await rule("feature-and-app-roots-do-not-reach-adapters"); + expect(applies("src/features/installed-feature-adapters.ts", HTTP_BARREL)).toBe(true); + expect(applies("src/features/catalog/feature-runtime.ts", HTTP_BARREL)).toBe(true); + expect(applies("src/contexts/commerce/context-module.ts", HTTP_BARREL)).toBe(true); + expect(applies("src/apps/template-app.ts", HTTP_BARREL)).toBe(true); + }); + + it("leaves a feature's adapters folder and the type-only contribution file to reach adapters", async () => { + const applies = await rule("feature-and-app-roots-do-not-reach-adapters"); + expect(applies("src/features/catalog/adapters/catalog-http-gateway.ts", HTTP_BARREL)).toBe(false); + expect(applies("src/features/feature-adapter-contribution.ts", HTTP_BARREL)).toBe(false); + // Only the adapters folder: a folder merely named like it elsewhere is not. + expect(applies("src/features/catalog/support/adapters/x.ts", HTTP_BARREL)).toBe(true); + // A feature's presentation-side query adapter is not a concrete adapter. + expect(applies("src/features/catalog/support/x.ts", "src/presentation/adapters/query/index.ts")).toBe(false); + }); +}); diff --git a/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/adapters/telemetry-sink.ts b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/adapters/telemetry-sink.ts new file mode 100644 index 00000000..48a192ae --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/adapters/telemetry-sink.ts @@ -0,0 +1,2 @@ +// A feature's adapters/ folder is where a feature reaches src/adapters. +export { telemetryAdapter as alphaTelemetrySink } from "../../../adapters/telemetry/index.ts"; diff --git a/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/presentation/read-support.ts b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/presentation/read-support.ts new file mode 100644 index 00000000..a4aaf102 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/presentation/read-support.ts @@ -0,0 +1,3 @@ +// 0929/12-03: every direct rule passes on this edge; the support file is where +// the adapter leaks in. +export { telemetryAdapter } from "../support/telemetry.ts"; diff --git a/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/support/telemetry.ts b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/support/telemetry.ts new file mode 100644 index 00000000..800384a7 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/support/telemetry.ts @@ -0,0 +1,3 @@ +// 0929/12-03: a file in a feature folder that is not a layer, re-exporting a +// concrete adapter. Feature presentation may import it. +export * from "../../../adapters/telemetry/index.ts";