@comity-dev/dependency-rules 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @comity-dev/dependency-rules
+
+## Purpose
+
+Canonical dependency-cruiser rule generator for Comity layering. This package produces the JSON configuration consumed by the validator; it does **not** invoke dependency-cruiser itself.
+
+## Scope
+
+- Builds a deterministic `dependency-cruiser` config from repository-supplied facts (a `Map<packageName, layer>`).
+- Encodes the canonical layering model:
+  - `primitives` MUST NOT depend on any internal package.
+  - `kernel` MAY only depend on `primitives`.
+  - `composition` MAY only depend on `kernel` and `primitives`.
+  - `core` MAY depend on `primitives`, `kernel`, and other `core` modules (gated by ADR-008).
+  - Adapters: cross-adapter edges forbidden except Integration Adapter → Technology Adapter (ADR-007).
+  - Primitives/Kernel/Composition MUST NOT depend on Core.
+
+## Ownership
+
+Owned by `comity-development`. Consumed by `@comity-dev/validate` which actually invokes dependency-cruiser.
+
+## Public API
+
+```ts
+import {
+  buildDependencyRules,
+  buildDependencyRulesForRoot,
+  classifyByLayer,
+  layerSetsFromPackages,
+  LAYER_PROFILES,
+  DEFAULT_REPOSITORY_FACTS,
+} from "@comity-dev/dependency-rules";
+```
+
+A dedicated subpath exposes the rule builder:
+
+```ts
+import { buildDependencyRules } from "@comity-dev/dependency-rules/build-config";
+```
+
+## Relationship to Comity Standards
+
+- `layering-policy.md` §2 — canonical layering model.
+- `ADR-007` — adapter categories.
+- `ADR-008` — Core-to-Core explicit exception register.
+- `architecture-validation.md` §7 — dependency validation.
+
+## Development
+
+```bash
+pnpm build
+pnpm test
+```

package/dist/build-config.d.ts

@@ -0,0 +1,63 @@
+import type { LayerName } from "./constants.js";
+export interface DependencyRule {
+    /** The name of the dependency rule */
+    name: string;
+    /** The severity of the dependency rule */
+    severity: "error" | "warn" | "info";
+    /** The comment associated with the dependency rule */
+    comment: string;
+    /** The source module of the dependency */
+    from: {
+        path: string;
+    };
+    /** The target module of the dependency */
+    to: {
+        path: string;
+    };
+}
+export interface DependencyCruiserConfig {
+    /** The list of forbidden dependency rules */
+    forbidden: DependencyRule[];
+    /** The options for the dependency-cruiser configuration */
+    options: {
+        /** The prefix for module paths */
+        prefix?: string;
+        /** The options for the dependency-cruiser configuration */
+        doNotFollow?: {
+            /** The path pattern for modules that should not be followed */
+            path?: string;
+            /** The dependency types that should not be followed */
+            dependencyTypes?: string[];
+        };
+        /** The TypeScript configuration file */
+        tsConfig?: {
+            fileName?: string;
+        };
+    };
+}
+export interface BuildOptions {
+    /** The path to the TypeScript configuration file */
+    tsConfigFileName?: string;
+    /** Additional dependency rules to be applied */
+    extraRules?: Array<{
+        /** The name of the extra rule */
+        name?: string;
+        /** The source layer of the extra rule */
+        fromLayer: LayerName;
+        /** The target layer of the extra rule */
+        toLayer: LayerName;
+        /** The severity of the extra rule */
+        severity?: "error" | "warn" | "info";
+        /** The comment associated with the extra rule */
+        comment?: string;
+    }>;
+    /** Explicitly registered Core-to-Core edges (ADR-008) */
+    registeredCoreEdges?: string[];
+}
+/**
+ * @param classification — Map<packageName, layer>
+ * @param options — repository-supplied facts
+ * @returns a dependency-cruiser config object
+ */
+export declare function buildDependencyRules(classification: Map<string, string>, options?: BuildOptions): DependencyCruiserConfig;
+export declare function buildDependencyRulesForRoot(classification: Map<string, string>, repoRoot: string, options?: Omit<BuildOptions, "tsConfigFileName">): DependencyCruiserConfig;

package/dist/build-config.js

@@ -0,0 +1,162 @@
+import { resolve } from "node:path";
+import { layerSetsFromPackages } from "./classify.js";
+import { DEFAULT_REPOSITORY_FACTS, LAYER_PROFILES } from "./constants.js";
+const escapeForRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * @param classification — Map<packageName, layer>
+ * @param options — repository-supplied facts
+ * @returns a dependency-cruiser config object
+ */
+export function buildDependencyRules(classification, options = {}) {
+    const { tsConfigFileName = DEFAULT_REPOSITORY_FACTS.tsConfigFileName, extraRules = [], registeredCoreEdges = [], } = options;
+    if (!(classification instanceof Map)) {
+        throw new TypeError("classification must be a Map<packageName, layer>");
+    }
+    const sets = layerSetsFromPackages(classification);
+    const primitives = [...sets.primitives];
+    const kernel = [...sets.kernel];
+    const composition = [...sets.composition];
+    const core = [...sets.core];
+    const techAdapter = [...sets["technology-adapter"]];
+    const integrationAdapter = [...sets["integration-adapter"]];
+    const adapters = [...techAdapter, ...integrationAdapter];
+    const forbidden = [];
+    // Build the forbidden rules based on the canonical layer profiles and the repository-supplied classification.
+    if (primitives.length > 0) {
+        forbidden.push({
+            name: "primitives-no-internal",
+            severity: "error",
+            comment: LAYER_PROFILES.primitives.comment,
+            from: { path: `^(${primitives.map(escapeForRegex).join("|")})$` },
+            to: { path: "^@comity/" },
+        });
+    }
+    // Kernel may depend on primitives, but nothing else.
+    if (kernel.length > 0) {
+        const allowedKernel = [...new Set([...primitives, ...kernel])];
+        forbidden.push({
+            name: "kernel-only-primitives",
+            severity: "error",
+            comment: LAYER_PROFILES.kernel.comment,
+            from: { path: `^(${kernel.map(escapeForRegex).join("|")})$` },
+            to: { path: `^(?!(${allowedKernel.map(escapeForRegex).join("|")})$).*$` },
+        });
+    }
+    // Composition may depend on kernel and primitives, but nothing else.
+    if (composition.length > 0) {
+        const allowedComposition = [
+            ...new Set([...primitives, ...kernel, ...composition]),
+        ];
+        forbidden.push({
+            name: "composition-only-kernel-primitives",
+            severity: "error",
+            comment: LAYER_PROFILES.composition.comment,
+            from: { path: `^(${composition.map(escapeForRegex).join("|")})$` },
+            to: {
+                path: `^(?!(${allowedComposition.map(escapeForRegex).join("|")})$).*$`,
+            },
+        });
+    }
+    // Core Modules may depend on primitives, kernel, and other Core Modules explicitly permitted via ADR-008.
+    if (core.length > 0) {
+        const allowedCorePeers = [...primitives, ...kernel, ...core];
+        forbidden.push({
+            name: "core-only-kernel-primitives-or-core-peer",
+            severity: "error",
+            comment: LAYER_PROFILES.core.comment,
+            from: { path: `^(${core.map(escapeForRegex).join("|")})$` },
+            to: {
+                path: `^(?!(${allowedCorePeers.map(escapeForRegex).join("|")})$).*$`,
+            },
+        });
+    }
+    // Technology Adapters may not depend on any other Adapters except Integration Adapter → Technology Adapter (ADR-007).
+    if (core.length > 0 && adapters.length > 0) {
+        forbidden.push({
+            name: "contracts-never-depend-on-adapters",
+            severity: "error",
+            comment: "Core Modules MUST NOT depend on Adapters (layering-policy.md §2.3, architecture-validation.md §7.3).",
+            from: { path: `^(${core.map(escapeForRegex).join("|")})$` },
+            to: { path: `^(${adapters.map(escapeForRegex).join("|")})$` },
+        });
+    }
+    // Adapter to Adapter dependencies are forbidden except Integration Adapter → Technology Adapter (ADR-007).
+    if (adapters.length > 0) {
+        forbidden.push({
+            name: "no-cross-adapter-deps",
+            severity: "error",
+            comment: "Adapter to Adapter dependencies are forbidden except Integration Adapter → Technology Adapter (ADR-007).",
+            from: { path: `^(${adapters.map(escapeForRegex).join("|")})$` },
+            to: { path: `^(${adapters.map(escapeForRegex).join("|")})$` },
+        });
+    }
+    // Primitives, Kernel, and Composition may not depend on Core Modules.
+    if ((primitives.length || kernel.length || composition.length) &&
+        core.length > 0) {
+        const inner = [...primitives, ...kernel, ...composition];
+        forbidden.push({
+            name: "kernel-no-core-deps",
+            severity: "error",
+            comment: "Primitives, Kernel, and Composition MUST NOT depend on Core Modules (layering-policy.md §2.1).",
+            from: { path: `^(${inner.map(escapeForRegex).join("|")})$` },
+            to: { path: `^(${core.map(escapeForRegex).join("|")})$` },
+        });
+    }
+    // Explicitly registered Core-to-Core edges (ADR-008) are allowed, so we need to add them to the forbidden list with a comment indicating that they are exceptions.
+    for (const edge of registeredCoreEdges) {
+        const [from, to] = edge.split(" -> ").map((s) => s.trim());
+        if (!from || !to)
+            continue;
+        forbidden.push({
+            name: `adr-008-edge-${from}-${to}`,
+            severity: "error",
+            comment: `ADR-008 explicit Core-to-Core exception: ${from} → ${to}.`,
+            from: { path: `^${escapeForRegex(from)}$` },
+            to: { path: `^${escapeForRegex(to)}$` },
+        });
+    }
+    // Apply any extra rules supplied by the repository. These are additional constraints that the repository wants to enforce, beyond the canonical layering policy.
+    for (const rule of extraRules) {
+        const fromSet = sets[rule.fromLayer];
+        const toSet = sets[rule.toLayer];
+        if (!fromSet || !toSet)
+            continue;
+        forbidden.push({
+            name: rule.name ?? `extra-${rule.fromLayer}-no-${rule.toLayer}`,
+            severity: rule.severity ?? "error",
+            comment: rule.comment ?? `Disallow ${rule.fromLayer} → ${rule.toLayer}`,
+            from: {
+                path: `^(${Array.from(fromSet).map(escapeForRegex).join("|")})$`,
+            },
+            to: {
+                path: `^(${Array.from(toSet).map(escapeForRegex).join("|")})$`,
+            },
+        });
+    }
+    return {
+        forbidden,
+        options: {
+            prefix: "^(@comity|@comity-dev)/",
+            doNotFollow: {
+                path: "node_modules",
+                dependencyTypes: [
+                    "npm",
+                    "npm-dev",
+                    "npm-optional",
+                    "npm-peer",
+                    "npm-bundled",
+                    "npm-no-pkg",
+                ],
+            },
+        },
+    };
+}
+// Re-export a helper that returns the config with an absolute tsconfig path
+// pinned to a specific repo root. Consumers call this when the engine's CWD
+// differs from the repo root.
+export function buildDependencyRulesForRoot(classification, repoRoot, options = {}) {
+    return buildDependencyRules(classification, {
+        ...options,
+        tsConfigFileName: resolve(repoRoot, "tsconfig.json"),
+    });
+}

package/dist/classify.d.ts

@@ -0,0 +1,25 @@
+import type { LayerSets } from "./constants.js";
+/**
+ * Pure helpers to classify packages and build layer sets from a parsed
+ * classification map. No I/O.
+ */
+export interface PackageRecord {
+    /** The name of the package */
+    name: string;
+    /** The layer of the package, if known */
+    layer?: string | null;
+}
+/**
+ * Returns a Map<name, layer> from an array of package records.
+ *
+ * @param packages — package records with optional layer
+ * @returns classification map
+ */
+export declare function classifyByLayer(packages: PackageRecord[]): Map<string, string>;
+/**
+ * Builds per-layer Sets from a classification map.
+ *
+ * @param classification — Map<packageName, layer>
+ * @returns layer sets
+ */
+export declare function layerSetsFromPackages(classification: Map<string, string>): LayerSets;

package/dist/classify.js

@@ -0,0 +1,43 @@
+/**
+ * Returns a Map<name, layer> from an array of package records.
+ *
+ * @param packages — package records with optional layer
+ * @returns classification map
+ */
+export function classifyByLayer(packages) {
+    const out = new Map();
+    for (const pkg of packages) {
+        if (pkg.layer)
+            out.set(pkg.name, pkg.layer);
+    }
+    return out;
+}
+/**
+ * Builds per-layer Sets from a classification map.
+ *
+ * @param classification — Map<packageName, layer>
+ * @returns layer sets
+ */
+export function layerSetsFromPackages(classification) {
+    const sets = {
+        primitives: new Set(),
+        kernel: new Set(),
+        composition: new Set(),
+        core: new Set(),
+        "technology-adapter": new Set(),
+        "integration-adapter": new Set(),
+        "dev-tooling": new Set(),
+    };
+    for (const [name, layer] of classification) {
+        if (layer === "primitives" ||
+            layer === "kernel" ||
+            layer === "composition" ||
+            layer === "core" ||
+            layer === "technology-adapter" ||
+            layer === "integration-adapter" ||
+            layer === "dev-tooling") {
+            sets[layer].add(name);
+        }
+    }
+    return sets;
+}

package/dist/constants.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Default repository facts used by the dependency-cruiser rule builder
+ * when no overrides are supplied.
+ *
+ * Repositories MAY override these in their `comity.config.json` or via
+ * the `buildDependencyRules` options. They MUST NOT alter layering policy
+ * through configuration.
+ */
+export declare const DEFAULT_REPOSITORY_FACTS: Readonly<{
+    packageRoots: string[];
+    tsConfigFileName: "tsconfig.json";
+}>;
+/**
+ * Canonical layer profile comments referenced by the dependency rule
+ * builder. Keeping the prose here makes rule generation deterministic and
+ * prevents duplication across repositories.
+ */
+export declare const LAYER_PROFILES: Readonly<{
+    readonly primitives: {
+        readonly comment: "Primitives MUST NOT depend on any internal package (layering-policy.md §2.1).";
+    };
+    readonly kernel: {
+        readonly comment: "Kernel MUST only depend on primitives (layering-policy.md §2.1).";
+    };
+    readonly composition: {
+        readonly comment: "Composition MUST only depend on kernel and primitives (layering-policy.md §2.1).";
+    };
+    readonly core: {
+        readonly comment: "Core Modules MAY depend on primitives, kernel, and other Core Modules explicitly permitted via ADR-008.";
+    };
+    readonly "technology-adapter": {
+        readonly comment: "Technology Adapters MUST NOT depend on Adapters except Integration Adapter → Technology Adapter (ADR-007).";
+    };
+    readonly "integration-adapter": {
+        readonly comment: "Integration Adapters may depend on primitives, kernel, core, and technology adapters (ADR-007).";
+    };
+}>;
+export type LayerName = "primitives" | "kernel" | "composition" | "core" | "technology-adapter" | "integration-adapter" | "dev-tooling";
+export interface LayerSets {
+    /** The set of package names in each layer */
+    primitives: Set<string>;
+    /** The set of package names in each layer */
+    kernel: Set<string>;
+    /** The set of package names in each layer */
+    composition: Set<string>;
+    /** The set of package names in each layer */
+    core: Set<string>;
+    /** The set of package names in each layer */
+    "technology-adapter": Set<string>;
+    /** The set of package names in each layer */
+    "integration-adapter": Set<string>;
+    /** The set of package names in each layer */
+    "dev-tooling": Set<string>;
+}

package/dist/constants.js

@@ -0,0 +1,37 @@
+/**
+ * Default repository facts used by the dependency-cruiser rule builder
+ * when no overrides are supplied.
+ *
+ * Repositories MAY override these in their `comity.config.json` or via
+ * the `buildDependencyRules` options. They MUST NOT alter layering policy
+ * through configuration.
+ */
+export const DEFAULT_REPOSITORY_FACTS = Object.freeze({
+    packageRoots: ["packages"],
+    tsConfigFileName: "tsconfig.json",
+});
+/**
+ * Canonical layer profile comments referenced by the dependency rule
+ * builder. Keeping the prose here makes rule generation deterministic and
+ * prevents duplication across repositories.
+ */
+export const LAYER_PROFILES = Object.freeze({
+    primitives: {
+        comment: "Primitives MUST NOT depend on any internal package (layering-policy.md §2.1).",
+    },
+    kernel: {
+        comment: "Kernel MUST only depend on primitives (layering-policy.md §2.1).",
+    },
+    composition: {
+        comment: "Composition MUST only depend on kernel and primitives (layering-policy.md §2.1).",
+    },
+    core: {
+        comment: "Core Modules MAY depend on primitives, kernel, and other Core Modules explicitly permitted via ADR-008.",
+    },
+    "technology-adapter": {
+        comment: "Technology Adapters MUST NOT depend on Adapters except Integration Adapter → Technology Adapter (ADR-007).",
+    },
+    "integration-adapter": {
+        comment: "Integration Adapters may depend on primitives, kernel, core, and technology adapters (ADR-007).",
+    },
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { BuildOptions, DependencyCruiserConfig, DependencyRule, } from "./build-config.js";
+export type { PackageRecord } from "./classify.js";
+export type { LayerName, LayerSets } from "./constants.js";
+export { buildDependencyRules, buildDependencyRulesForRoot, } from "./build-config.js";
+export { classifyByLayer, layerSetsFromPackages } from "./classify.js";
+export { DEFAULT_REPOSITORY_FACTS, LAYER_PROFILES } from "./constants.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { buildDependencyRules, buildDependencyRulesForRoot, } from "./build-config.js";
+export { classifyByLayer, layerSetsFromPackages } from "./classify.js";
+export { DEFAULT_REPOSITORY_FACTS, LAYER_PROFILES } from "./constants.js";

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@comity-dev/dependency-rules",
+  "version": "0.1.0",
+  "description": "Reusable dependency-cruiser rule generator for Comity layering. Development tooling.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "comity": {
+    "layer": "dev-tooling"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./build-config": {
+      "types": "./dist/build-config.d.ts",
+      "default": "./dist/build-config.js"
+    }
+  },
+  "files": [
+    "./dist"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "dependency-cruiser": "^16.10.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}