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([]); + }); +});