From b0f7944b417489232e2ac8128a4c1f91d07afd3d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:49:32 +0900 Subject: [PATCH] fix(architecture): print why an import is forbidden and where to go (12-11) Graph violations printed only the rule name and file pair, and ESLint only the pattern. The graph now prints the import specifier and the rule's comment, every rule has one, and ESLint pattern groups carry a message. Co-Authored-By: Claude Opus 5.5 --- .dependency-cruiser.json | 14 ++- eslint.config.ts | 114 +++++++++++------- scripts/check-architecture.ts | 16 ++- scripts/lib/architecture-violation-message.ts | 17 +++ .../architecture-violation-message.test.ts | 35 ++++++ 5 files changed, 147 insertions(+), 49 deletions(-) create mode 100644 scripts/lib/architecture-violation-message.ts create mode 100644 tests/unit/architecture-violation-message.test.ts diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index fcc4754a..7701f0d6 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -2,6 +2,7 @@ "forbidden": [ { "name": "domain-is-framework-neutral", + "comment": "domain holds framework-neutral models and pure policies. Keep the dependency out: move the code to application, or pass the value in from there.", "severity": "error", "from": { "path": "^src/domain" @@ -12,6 +13,7 @@ }, { "name": "application-does-not-know-concrete-runtime", + "comment": "application owns use cases and the ports they need. Declare a port under src/application/ports and let src/bootstrap pass the concrete adapter.", "severity": "error", "from": { "path": "^src/application" @@ -33,6 +35,7 @@ }, { "name": "page-templates-own-layout-only", + "comment": "Page templates own layout only. Take data and actions as props from the page that uses the template.", "severity": "error", "from": { "path": "^src/presentation/templates" @@ -68,6 +71,7 @@ }, { "name": "adapters-do-not-know-presentation", + "comment": "An adapter implements an application port. It never imports UI or the composition root; pass what it needs through the port or its factory arguments.", "severity": "error", "from": { "path": "^src/adapters" @@ -78,6 +82,7 @@ }, { "name": "feature-domain-is-framework-neutral", + "comment": "A feature's domain is framework-neutral, like src/domain. Move the code to the feature's application, or pass the value in from there.", "severity": "error", "from": { "path": "^src/features/[^/]+/domain" @@ -88,6 +93,7 @@ }, { "name": "feature-application-does-not-know-runtime", + "comment": "A feature's application declares the ports it needs. Put the port in the feature's application and implement it in the feature's adapters/; bootstrap wires the two.", "severity": "error", "from": { "path": "^src/features/[^/]+/application" @@ -98,6 +104,7 @@ }, { "name": "feature-presentation-does-not-know-outbound-adapters", + "comment": "Feature presentation calls its application API. The feature's adapters/ are wired by bootstrap, so import the application facade instead.", "severity": "error", "from": { "path": "^src/features/[^/]+/presentation" @@ -108,6 +115,7 @@ }, { "name": "feature-adapters-do-not-know-presentation", + "comment": "A feature adapter implements the feature's ports and never imports UI or the composition root. Pass what it needs through the port.", "severity": "error", "from": { "path": "^src/features/[^/]+/adapters" @@ -118,6 +126,7 @@ }, { "name": "concrete-adapters-compose-only-in-bootstrap", + "comment": "Only src/bootstrap constructs concrete adapters. Depend on the application port or facade; bootstrap composes the adapter behind it.", "severity": "error", "from": { "path": "^src/(domain|application|presentation|contracts)" @@ -140,7 +149,7 @@ }, { "name": "presentation-does-not-fetch-directly", - "comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself", + "comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself. Call the application API; bootstrap composes the adapter behind it.", "severity": "error", "from": { "path": "^src/(presentation|features/[^/]+/presentation)" @@ -162,7 +171,7 @@ }, { "name": "generic-worker-has-no-network-or-credentials", - "comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth", + "comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth. Do the network call on the page side and post the data to the worker.", "severity": "error", "from": { "path": "^src/adapters/web-worker" @@ -315,6 +324,7 @@ }, { "name": "no-circular-dependencies", + "comment": "A cycle makes the modules impossible to load or remove one at a time. Move the shared part into a lower module that both import.", "severity": "error", "from": {}, "to": { diff --git a/eslint.config.ts b/eslint.config.ts index 26eb6cc2..9ae435b6 100644 --- a/eslint.config.ts +++ b/eslint.config.ts @@ -37,8 +37,21 @@ const layerPatterns = { adapters: ["**/presentation/**", "**/bootstrap/**"], }; -function restrictedImports(patterns: readonly string[]) { - return ["error", { patterns }]; +// 12-11. Each pattern group carries the reason and the way out; the default +// message only named the pattern. +const layerMessages = { + domain: + "domain stays framework-neutral (.dependency-cruiser.json domain-is-framework-neutral). Move the code to application or pass the value in.", + application: + "application declares ports and never imports UI, adapters or bootstrap (application-does-not-know-concrete-runtime). Add a port under application/ports; bootstrap passes the adapter.", + presentation: + "presentation reaches the runtime through the application API (presentation-does-not-know-adapters). Use the application facade; bootstrap composes adapters.", + adapters: + "an adapter implements an application port and never imports UI or bootstrap (adapters-do-not-know-presentation). Pass what it needs through the port.", +} as const; + +function restrictedImports(patterns: readonly string[], message: string) { + return ["error", { patterns: [{ group: [...patterns], message }] }]; } const restrictedBrowserDataProperties = [ @@ -543,7 +556,7 @@ export default [ { files: [`src/domain/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports(layerPatterns.domain), + "no-restricted-imports": restrictedImports(layerPatterns.domain, layerMessages.domain), "no-restricted-properties": restrictedBrowserDataProperties, "no-restricted-globals": [ "error", @@ -568,7 +581,7 @@ export default [ { files: [`src/application/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports(layerPatterns.application), + "no-restricted-imports": restrictedImports(layerPatterns.application, layerMessages.application), "no-restricted-properties": restrictedBrowserDataProperties, "no-restricted-globals": [ "error", @@ -593,7 +606,7 @@ export default [ { files: [`src/presentation/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports(layerPatterns.presentation), + "no-restricted-imports": restrictedImports(layerPatterns.presentation, layerMessages.presentation), "no-restricted-properties": restrictedBrowserDataProperties, "no-restricted-globals": [ "error", @@ -617,24 +630,30 @@ export default [ `src/presentation/adapters/query/**/*.${sourceExtensions}`, ], rules: { - "no-restricted-imports": restrictedImports([ - "**/adapters/http/**", - "**/adapters/storage/**", - "**/adapters/auth/**", - "**/bootstrap/**", - "**/application/ports/out/**", - ]), + "no-restricted-imports": restrictedImports( + [ + "**/adapters/http/**", + "**/adapters/storage/**", + "**/adapters/auth/**", + "**/bootstrap/**", + "**/application/ports/out/**", + ], + "the TanStack Query binding may import @tanstack only; reach adapters through application ports (presentation-does-not-know-adapters).", + ), }, }, { files: [`src/presentation/templates/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports([ - "**/application/**", - "**/adapters/**", - "**/bootstrap/**", - "@tanstack/**", - ]), + "no-restricted-imports": restrictedImports( + [ + "**/application/**", + "**/adapters/**", + "**/bootstrap/**", + "@tanstack/**", + ], + "page templates own layout only (page-templates-own-layout-only). Take data and actions as props from the page.", + ), }, }, { @@ -663,7 +682,7 @@ export default [ { files: [`src/adapters/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports(layerPatterns.adapters), + "no-restricted-imports": restrictedImports(layerPatterns.adapters, layerMessages.adapters), "no-restricted-properties": restrictedBrowserDataProperties, "no-restricted-globals": [ "error", @@ -704,7 +723,7 @@ export default [ { files: [`src/features/*/domain/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports(layerPatterns.domain), + "no-restricted-imports": restrictedImports(layerPatterns.domain, layerMessages.domain), "no-restricted-properties": restrictedBrowserDataProperties, "no-restricted-globals": [ "error", @@ -729,7 +748,7 @@ export default [ { files: [`src/features/*/application/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports(layerPatterns.application), + "no-restricted-imports": restrictedImports(layerPatterns.application, layerMessages.application), "no-restricted-properties": restrictedBrowserDataProperties, "no-restricted-globals": [ "error", @@ -754,15 +773,18 @@ export default [ { files: [`src/features/*/presentation/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports([ - "**/features/*/adapters/**", - "**/adapters/http/**", - "**/adapters/storage/**", - "**/adapters/auth/**", - "**/bootstrap/**", - "**/application/ports/out/**", - "@tanstack/**", - ]), + "no-restricted-imports": restrictedImports( + [ + "**/features/*/adapters/**", + "**/adapters/http/**", + "**/adapters/storage/**", + "**/adapters/auth/**", + "**/bootstrap/**", + "**/application/ports/out/**", + "@tanstack/**", + ], + "feature presentation calls its application API (feature-presentation-does-not-know-outbound-adapters). Bootstrap wires the adapters.", + ), "no-restricted-properties": restrictedBrowserDataProperties, "no-restricted-globals": [ "error", @@ -784,11 +806,14 @@ export default [ { files: [`src/features/*/adapters/**/*.${sourceExtensions}`], rules: { - "no-restricted-imports": restrictedImports([ - "**/presentation/**", - "**/bootstrap/**", - "@tanstack/**", - ]), + "no-restricted-imports": restrictedImports( + [ + "**/presentation/**", + "**/bootstrap/**", + "@tanstack/**", + ], + "a feature adapter implements the feature's ports and never imports UI or bootstrap (feature-adapters-do-not-know-presentation).", + ), "no-restricted-properties": restrictedBrowserDataProperties, "no-restricted-globals": [ "error", @@ -827,14 +852,17 @@ export default [ `tests/fixtures/architecture/forbidden/**/*.${sourceExtensions}`, ], rules: { - "no-restricted-imports": restrictedImports([ - "**/adapters/**", - "**/application/ports/out/**", - "@tanstack/**", - "react", - "react-dom", - "**/application/**", - ]), + "no-restricted-imports": restrictedImports( + [ + "**/adapters/**", + "**/application/ports/out/**", + "@tanstack/**", + "react", + "react-dom", + "**/application/**", + ], + "forbidden architecture fixture: this import must be rejected.", + ), "no-restricted-globals": [ "error", "fetch", diff --git a/scripts/check-architecture.ts b/scripts/check-architecture.ts index 92b7e6a0..bcaad88c 100644 --- a/scripts/check-architecture.ts +++ b/scripts/check-architecture.ts @@ -6,11 +6,13 @@ import { fileURLToPath, pathToFileURL } from "node:url"; import { createRequire } from "node:module"; import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts"; +import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; type PathRule = Readonly<{ path?: string; pathNot?: string }>; type ArchitectureRule = Readonly<{ name: string; + comment?: string; severity?: string; from?: PathRule; to?: PathRule & Readonly<{ circular?: boolean }>; @@ -170,11 +172,16 @@ for (const dependency of sourceGraph.unresolved) { for (const violation of graphErrors) { architectureFailed = true; - const cycle = violation.cycle - ? ` (cycle group: ${violation.cycle.join(", ")})` - : ""; process.stderr.write( - `Architecture violation [${violation.rule}]: ${violation.source} -> ${violation.target}${cycle}\n`, + formatArchitectureViolation( + violation, + violation.cycle + ? [] + : sourceGraph.dependencies + .filter(({ source, target }) => source === violation.source && target === violation.target) + .map(({ specifier }) => specifier), + architectureRules.find(({ name }) => name === violation.rule)?.comment, + ), ); } @@ -1168,6 +1175,7 @@ function parseArchitectureConfig(value: unknown): ArchitectureConfig { function isArchitectureRule(value: unknown): value is ArchitectureRule { if (!isRecord(value) || typeof value.name !== "string") return false; + if (value.comment !== undefined && typeof value.comment !== "string") return false; if (value.severity !== undefined && typeof value.severity !== "string") { return false; } diff --git a/scripts/lib/architecture-violation-message.ts b/scripts/lib/architecture-violation-message.ts new file mode 100644 index 00000000..53190080 --- /dev/null +++ b/scripts/lib/architecture-violation-message.ts @@ -0,0 +1,17 @@ +/** + * 12-11. One violation line names the rule, the edge and the import specifier + * as written, then the rule's `comment` from .dependency-cruiser.json: why the + * edge is forbidden and where the code should go instead. + */ +export function formatArchitectureViolation( + violation: Readonly<{ rule: string; source: string; target: string; cycle?: readonly string[] }>, + specifiers: readonly string[], + comment: string | undefined, +): string { + const imports = specifiers.length > 0 + ? ` (import ${specifiers.map((specifier) => JSON.stringify(specifier)).join(", ")})` + : ""; + const cycle = violation.cycle ? ` (cycle group: ${violation.cycle.join(", ")})` : ""; + const why = comment ? ` why: ${comment}\n` : ""; + return `Architecture violation [${violation.rule}]: ${violation.source} -> ${violation.target}${imports}${cycle}\n${why}`; +} diff --git a/tests/unit/architecture-violation-message.test.ts b/tests/unit/architecture-violation-message.test.ts new file mode 100644 index 00000000..06b047fa --- /dev/null +++ b/tests/unit/architecture-violation-message.test.ts @@ -0,0 +1,35 @@ +import { readFile } from "node:fs/promises"; + +import { describe, expect, it } from "vitest"; + +import { formatArchitectureViolation } from "../../scripts/lib/architecture-violation-message.ts"; + +// 12-11. A violation used to print only the rule name and the file pair; the +// reason and the way out were in .dependency-cruiser.json. +describe("architecture violation message", () => { + it("names the import and says why and where to go", () => { + expect( + formatArchitectureViolation( + { + rule: "concrete-adapters-compose-only-in-bootstrap", + source: "src/presentation/pages/probe.tsx", + target: "src/adapters/http/index.ts", + }, + ["../../adapters/http/index.ts"], + "Only src/bootstrap constructs concrete adapters.", + ), + ).toBe( + "Architecture violation [concrete-adapters-compose-only-in-bootstrap]: " + + "src/presentation/pages/probe.tsx -> src/adapters/http/index.ts " + + '(import "../../adapters/http/index.ts")\n' + + " why: Only src/bootstrap constructs concrete adapters.\n", + ); + }); + + it("gives every rule a reason to print", async () => { + const config = JSON.parse(await readFile(".dependency-cruiser.json", "utf8")) as { + forbidden: { name: string; comment?: string }[]; + }; + expect(config.forbidden.filter(({ comment }) => !comment?.trim()).map(({ name }) => name)).toEqual([]); + }); +});