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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:49:32 +09:00
co-authored by Claude Opus 5.5
parent 3e1c421871
commit b0f7944b41
5 changed files with 147 additions and 49 deletions
+12 -2
View File
@@ -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": {
+71 -43
View File
@@ -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",
+12 -4
View File
@@ -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;
}
@@ -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}`;
}
@@ -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([]);
});
});