@comity-dev/eslint-plugin 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,46 @@
+# @comity-dev/eslint-plugin
+
+## Purpose
+
+Reusable ESLint rules for Comity-wide source-code policy. This package owns the source-code lint policy that every Comity repository MUST apply consistently.
+
+## Scope
+
+Six rules, each addressing a Comity-wide concern:
+
+| Rule                          | Concern                                                                                                                                       |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `no-forbidden-deep-import`    | Disallow deep imports into another package's internals (`@comity/x/src/foo`, `@comity/x/internal/*`, `@comity/x/dist/*`, `@comity/x/lazy/*`). |
+| `no-layer-violation`          | Forbid imports that violate Comity's canonical layering model.                                                                                |
+| `no-date-in-core`             | Forbid `Date` in Core Modules (domain must be deterministic).                                                                                 |
+| `no-crypto-in-core`           | Forbid `crypto` in Core Modules (domain must be deterministic).                                                                               |
+| `no-forbidden-subpath-import` | Disallow imports from forbidden package subpaths (`utils`, `helpers`, `shared`, `internal`, `lazy`).                                          |
+| `no-render-core-http-runtime` | Forbid render Core Modules from depending on HTTP runtime.                                                                                    |
+
+## Ownership
+
+Owned by `comity-development`. Consumed by Comity repositories (Community, Enterprise) via ESLint flat config.
+
+## Public API
+
+```ts
+// Default export: the ESLint plugin (loaded into flat-config)
+import comityPlugin from "@comity-dev/eslint-plugin";
+
+// Root exports: stable identifier list and the recommended rule set
+import { recommended, RULE_IDS } from "@comity-dev/eslint-plugin";
+```
+
+## Relationship to Comity Standards
+
+- `architecture-validation.md` §4 — source-code lint policy.
+- `public-api.md` §3.2 — forbidden subpath imports.
+- `layering-policy.md` §8 — rendering core MUST NOT depend on HTTP runtime.
+- `coding.md` — general style policy.
+
+## Development
+
+```bash
+pnpm build
+pnpm test
+```

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @comity-dev/eslint-plugin — Reusable ESLint rules for Comity source-code policy.
+ *
+ * This package owns the canonical ESLint rules for Comity. Repositories
+ * consume these rules via the shared orchestrator; they MUST NOT redefine
+ * source-code policy.
+ *
+ * Standard references:
+ *   - architecture-validation.md §4
+ *   - public-api.md §3.2 (forbidden subpath imports)
+ *   - layering-policy.md §8 (rendering core MUST NOT depend on HTTP runtime)
+ *   - coding.md (general style policy)
+ *
+ * Public surface (intentional):
+ *   - default export: the ESLint plugin (loaded into flat-config)
+ *   - `recommended`: the canonical Comity rule set
+ *   - `RULE_IDS`: stable list of rule identifiers
+ */
+export { plugin as default, RULE_IDS } from "./plugin.js";
+export { recommended } from "./recommended.js";

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @comity-dev/eslint-plugin — Reusable ESLint rules for Comity source-code policy.
+ *
+ * This package owns the canonical ESLint rules for Comity. Repositories
+ * consume these rules via the shared orchestrator; they MUST NOT redefine
+ * source-code policy.
+ *
+ * Standard references:
+ *   - architecture-validation.md §4
+ *   - public-api.md §3.2 (forbidden subpath imports)
+ *   - layering-policy.md §8 (rendering core MUST NOT depend on HTTP runtime)
+ *   - coding.md (general style policy)
+ *
+ * Public surface (intentional):
+ *   - default export: the ESLint plugin (loaded into flat-config)
+ *   - `recommended`: the canonical Comity rule set
+ *   - `RULE_IDS`: stable list of rule identifiers
+ */
+export { plugin as default, RULE_IDS } from "./plugin.js";
+export { recommended } from "./recommended.js";

package/dist/plugin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @comity-dev/eslint-plugin — Reusable ESLint rules for Comity source-code policy.
+ *
+ * This package owns the canonical ESLint rules for Comity. Repositories
+ * consume these rules via the shared orchestrator; they MUST NOT redefine
+ * source-code policy.
+ *
+ * Standard references:
+ *   - architecture-validation.md §4
+ *   - public-api.md §3.2 (forbidden subpath imports)
+ *   - layering-policy.md §8 (rendering core MUST NOT depend on HTTP runtime)
+ *   - coding.md (general style policy)
+ *
+ * Public surface (intentional):
+ *   - default export: the ESLint plugin (loaded into flat-config)
+ *   - `recommended`: the canonical Comity rule set
+ *   - `RULE_IDS`: stable list of rule identifiers
+ */
+export interface BuiltinRule {
+    /** The stable identifier of the rule */
+    name: string;
+    /** The rule implementation */
+    rule: unknown;
+}
+export declare const BUILTIN_RULES: BuiltinRule[];
+export declare const plugin: import("eslint").ESLint.Plugin;
+/** Stable list of rule identifiers exported by this plugin. */
+export declare const RULE_IDS: string[];

package/dist/plugin.js

@@ -0,0 +1,41 @@
+/**
+ * @comity-dev/eslint-plugin — Reusable ESLint rules for Comity source-code policy.
+ *
+ * This package owns the canonical ESLint rules for Comity. Repositories
+ * consume these rules via the shared orchestrator; they MUST NOT redefine
+ * source-code policy.
+ *
+ * Standard references:
+ *   - architecture-validation.md §4
+ *   - public-api.md §3.2 (forbidden subpath imports)
+ *   - layering-policy.md §8 (rendering core MUST NOT depend on HTTP runtime)
+ *   - coding.md (general style policy)
+ *
+ * Public surface (intentional):
+ *   - default export: the ESLint plugin (loaded into flat-config)
+ *   - `recommended`: the canonical Comity rule set
+ *   - `RULE_IDS`: stable list of rule identifiers
+ */
+import noCryptoInCore from "./rules/no-crypto-in-core.js";
+import noDateInCore from "./rules/no-date-in-core.js";
+import noForbiddenDeepImport from "./rules/no-forbidden-deep-import.js";
+import noForbiddenSubpathImport from "./rules/no-forbidden-subpath-import.js";
+import noLayerViolation from "./rules/no-layer-violation.js";
+import noRenderCoreHttpRuntime from "./rules/no-render-core-http-runtime.js";
+export const BUILTIN_RULES = [
+    { name: "no-forbidden-deep-import", rule: noForbiddenDeepImport },
+    { name: "no-layer-violation", rule: noLayerViolation },
+    { name: "no-date-in-core", rule: noDateInCore },
+    { name: "no-crypto-in-core", rule: noCryptoInCore },
+    { name: "no-forbidden-subpath-import", rule: noForbiddenSubpathImport },
+    { name: "no-render-core-http-runtime", rule: noRenderCoreHttpRuntime },
+];
+export const plugin = {
+    meta: {
+        name: "@comity-dev/eslint-plugin",
+        version: "0.1.0",
+    },
+    rules: Object.fromEntries(BUILTIN_RULES.map((r) => [r.name, r.rule])),
+};
+/** Stable list of rule identifiers exported by this plugin. */
+export const RULE_IDS = BUILTIN_RULES.map((r) => r.name);

package/dist/recommended.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Recommended Comity ESLint rule set.
+ *
+ * The "recommended" preset bundles the canonical Comity rules with their
+ * default severities. Repositories MAY override severities; they MUST NOT
+ * disable rules silently.
+ */
+import type { Linter } from "eslint";
+export declare const recommended: Linter.Config;

package/dist/recommended.js

@@ -0,0 +1,10 @@
+export const recommended = {
+    rules: {
+        "@comity-dev/no-forbidden-deep-import": "error",
+        "@comity-dev/no-layer-violation": "error",
+        "@comity-dev/no-date-in-core": "error",
+        "@comity-dev/no-crypto-in-core": "error",
+        "@comity-dev/no-forbidden-subpath-import": "error",
+        "@comity-dev/no-render-core-http-runtime": "error",
+    },
+};

package/dist/rules/no-crypto-in-core.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @comity-dev/no-crypto-in-core
+ *
+ * Forbid Node's `crypto` and WebCrypto (`globalThis.crypto`) modules in Core
+ * packages. Core must be deterministic and side-effect free; cryptography
+ * belongs in Adapters that own runtime concerns.
+ *
+ * Standard references:
+ *   - layering-policy.md §2.2 (Core boundaries)
+ *   - adapters.md
+ */
+type Rule = unknown;
+declare const rule: Rule;
+export default rule;

package/dist/rules/no-crypto-in-core.js

@@ -0,0 +1,123 @@
+/**
+ * @comity-dev/no-crypto-in-core
+ *
+ * Forbid Node's `crypto` and WebCrypto (`globalThis.crypto`) modules in Core
+ * packages. Core must be deterministic and side-effect free; cryptography
+ * belongs in Adapters that own runtime concerns.
+ *
+ * Standard references:
+ *   - layering-policy.md §2.2 (Core boundaries)
+ *   - adapters.md
+ */
+const FORBIDDEN_SPECIFIERS = new Set(["crypto", "node:crypto", "webcrypto"]);
+const messages = {
+    forbiddenImport: "Importing '{{specifier}}' is forbidden in Core (layering-policy.md §2.2). Use a Technology Adapter instead.",
+    forbiddenGlobal: "Accessing the `crypto` global is forbidden in Core (layering-policy.md §2.2). Use a Technology Adapter instead.",
+};
+function isInCorePackage(filename) {
+    return (filename.includes("/packages/") &&
+        (filename.includes("/primitives/") ||
+            filename.includes("/kernel/") ||
+            filename.includes("/composition/") ||
+            filename.includes("/http/") ||
+            filename.includes("/router/") ||
+            filename.includes("/html/") ||
+            filename.includes("/hydration/") ||
+            filename.includes("/seo/") ||
+            filename.includes("/content/") ||
+            filename.includes("/media/") ||
+            filename.includes("/search/") ||
+            filename.includes("/cache/") ||
+            filename.includes("/auth/") ||
+            filename.includes("/catalog/") ||
+            filename.includes("/customer/") ||
+            filename.includes("/inventory/") ||
+            filename.includes("/order/") ||
+            filename.includes("/payment/") ||
+            filename.includes("/pricing/") ||
+            filename.includes("/storefront/") ||
+            filename.includes("/taxonomy/") ||
+            filename.includes("/validation/") ||
+            filename.includes("/address/") ||
+            filename.includes("/geography/") ||
+            filename.includes("/identity/") ||
+            filename.includes("/organization/")));
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Forbid `crypto` imports in Core packages — cryptography belongs in Adapters.",
+            category: "Comity Architecture",
+            recommended: true,
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    sourceName: {
+                        type: "string",
+                        description: "Name of the source package (e.g., '@comity/auth'). Used to scope the rule.",
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages,
+    },
+    create(context) {
+        const opts = (context.options[0] ?? {});
+        const sourceName = opts.sourceName ?? null;
+        // If sourceName provided, use it for classification; otherwise fall back to filename
+        const inCore = sourceName
+            ? sourceName.startsWith("@comity/") &&
+                !["@comity/cli", "@comity/graphql-builder"].includes(sourceName)
+            : isInCorePackage(context.filename ?? context.getFilename());
+        // Disable this rule outside Core packages
+        if (!inCore) {
+            return {};
+        }
+        function checkSpecifier(value) {
+            if (!value)
+                return false;
+            return FORBIDDEN_SPECIFIERS.has(value);
+        }
+        return {
+            ImportDeclaration(node) {
+                if (checkSpecifier(node.source.value)) {
+                    context.report({
+                        node,
+                        messageId: "forbiddenImport",
+                        data: { specifier: node.source.value },
+                    });
+                }
+            },
+            ImportExpression(node) {
+                // dynamic import()
+                if (node.source.type === "Literal" &&
+                    typeof node.source.value === "string" &&
+                    checkSpecifier(node.source.value)) {
+                    context.report({
+                        node,
+                        messageId: "forbiddenImport",
+                        data: { specifier: node.source.value },
+                    });
+                }
+            },
+            Identifier(node) {
+                if (node.name !== "crypto")
+                    return;
+                // Top-level access of the `crypto` global
+                const parent = node.parent;
+                if (!parent)
+                    return;
+                if (parent.type === "ExpressionStatement" ||
+                    parent.type === "CallExpression" ||
+                    parent.type === "MemberExpression") {
+                    context.report({ node, messageId: "forbiddenGlobal" });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-date-in-core.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @comity-dev/no-date-in-core
+ *
+ * Forbid `Date`, `performance.now`, and `Math.random` access in Core and
+ * Kernel packages — they introduce non-deterministic behavior that breaks
+ * the Comity reproducibility contract.
+ *
+ * Legitimate exceptions:
+ * - Telemetry/timing measurements using `performance.now()` (observational, not domain logic)
+ * - Timestamp generation using `Date.now()` or `Date` constructor for logging/metadata
+ * - Time primitives in `@comity/primitives/time` (explicitly allowed)
+ *
+ * Standard references:
+ *   - layering-policy.md §6 (determinism)
+ *   - domain-modeling.md
+ */
+type Rule = unknown;
+declare const rule: Rule;
+export default rule;

package/dist/rules/no-date-in-core.js

@@ -0,0 +1,163 @@
+/**
+ * @comity-dev/no-date-in-core
+ *
+ * Forbid `Date`, `performance.now`, and `Math.random` access in Core and
+ * Kernel packages — they introduce non-deterministic behavior that breaks
+ * the Comity reproducibility contract.
+ *
+ * Legitimate exceptions:
+ * - Telemetry/timing measurements using `performance.now()` (observational, not domain logic)
+ * - Timestamp generation using `Date.now()` or `Date` constructor for logging/metadata
+ * - Time primitives in `@comity/primitives/time` (explicitly allowed)
+ *
+ * Standard references:
+ *   - layering-policy.md §6 (determinism)
+ *   - domain-modeling.md
+ */
+const FORBIDDEN_GLOBALS = new Set(["Date", "performance"]);
+const FORBIDDEN_PROPERTIES = {
+    Math: ["random"],
+};
+// Package names that are explicitly allowed to use Date/performance for telemetry
+const TELEMETRY_ALLOWLIST = new Set([
+    "@comity/primitives", // time/instant primitives
+    "@comity/http", // facade timing
+    "@comity/html", // renderer pipeline timing
+    "@comity/hydration", // browser capability implementations (createBrowserHydrationCapabilities, createNoopHydrationCapabilities)
+]);
+// Allowlist for specific property access patterns that are legitimate telemetry
+const TELEMETRY_PROPERTY_ALLOWLIST = new Set([
+    "performance.now",
+    "Date.now",
+]);
+const messages = {
+    forbiddenGlobal: "Non-deterministic global '{{name}}' is forbidden in Core / Kernel (layering-policy.md §6). Use telemetry allowlist or primitives/time for timing.",
+    forbiddenProperty: "Non-deterministic '{{object}}.{{property}}' is forbidden in Core / Kernel (layering-policy.md §6).",
+};
+function isInCoreOrKernelPackage(filename) {
+    return (filename.includes("/packages/") &&
+        (filename.includes("/primitives/") ||
+            filename.includes("/kernel/") ||
+            filename.includes("/composition/") ||
+            filename.includes("/http/") ||
+            filename.includes("/router/") ||
+            filename.includes("/html/") ||
+            filename.includes("/hydration/") ||
+            filename.includes("/seo/") ||
+            filename.includes("/content/") ||
+            filename.includes("/media/") ||
+            filename.includes("/search/")));
+}
+function isTelemetryAllowedPackage(filename) {
+    return Array.from(TELEMETRY_ALLOWLIST).some((pkg) => filename.includes(`/packages/${pkg.replace("@comity/", "")}/`) || filename.includes(`/community/packages/${pkg.replace("@comity/", "")}/`));
+}
+function isTelemetryPropertyAccess(objectName, propertyName) {
+    return TELEMETRY_PROPERTY_ALLOWLIST.has(`${objectName}.${propertyName}`);
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Forbid Date / performance.now / Math.random in Core and Kernel packages.",
+            category: "Comity Architecture",
+            recommended: true,
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    sourceName: {
+                        type: "string",
+                        description: "Name of the source package (e.g., '@comity/http'). Used to scope the rule.",
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages,
+    },
+    create(context) {
+        const opts = (context.options[0] ?? {});
+        const sourceName = opts.sourceName ?? null;
+        // If sourceName provided, use it for classification; otherwise fall back to filename
+        const inCoreOrKernel = sourceName
+            ? sourceName.startsWith("@comity/") &&
+                !["@comity/cli", "@comity/graphql-builder"].includes(sourceName) // these are not core/kernel
+            : isInCoreOrKernelPackage(context.filename ?? context.getFilename());
+        // Disable this rule outside Core/Kernel packages
+        if (!inCoreOrKernel) {
+            return {};
+        }
+        // Check if this package is allowed to use telemetry patterns
+        const allowTelemetry = sourceName
+            ? TELEMETRY_ALLOWLIST.has(sourceName)
+            : isTelemetryAllowedPackage(context.filename ?? context.getFilename());
+        return {
+            Identifier(node) {
+                // Detect globals like `Date` and `performance`
+                if ((node.name === "Date" || node.name === "performance") &&
+                    // Only top-level usage (not as property of another object)
+                    node.parent &&
+                    (node.parent.type === "ExpressionStatement" ||
+                        node.parent.type === "VariableDeclarator" ||
+                        node.parent.type === "CallExpression" ||
+                        node.parent.type === "NewExpression" ||
+                        node.parent.type === "MemberExpression")) {
+                    // Allow telemetry patterns in allowlisted packages
+                    if (allowTelemetry && isTelemetryPropertyAccess(node.parent.object?.name ?? "", node.name)) {
+                        return;
+                    }
+                    // Allow Date.now() and performance.now() in telemetry allowlisted packages
+                    if (allowTelemetry &&
+                        ((node.name === "Date" && node.parent.type === "MemberExpression" && node.parent.property?.name === "now") ||
+                            (node.name === "performance" && node.parent.type === "MemberExpression" && node.parent.property?.name === "now"))) {
+                        return;
+                    }
+                    // Also handle optional chaining: window?.performance?.now()
+                    // Walk up the ancestor chain to find a MemberExpression with property 'now'
+                    if (allowTelemetry && (node.name === "Date" || node.name === "performance")) {
+                        let current = node.parent;
+                        while (current) {
+                            if (current.type === "MemberExpression" && current.property?.name === "now") {
+                                return;
+                            }
+                            if (current.type === "ChainExpression") {
+                                current = current.expression;
+                                continue;
+                            }
+                            current = current.parent;
+                        }
+                    }
+                    if (FORBIDDEN_GLOBALS.has(node.name)) {
+                        context.report({
+                            node,
+                            messageId: "forbiddenGlobal",
+                            data: { name: node.name },
+                        });
+                    }
+                }
+                // Detect property access like Math.random
+                if (node.parent &&
+                    node.parent.type === "MemberExpression" &&
+                    node.parent.property === node) {
+                    const obj = node.parent.object;
+                    if (obj.type === "Identifier") {
+                        const allowed = FORBIDDEN_PROPERTIES[obj.name];
+                        if (allowed && allowed.includes(node.name)) {
+                            // Allow Math.random in primitives/time (explicit time primitive)
+                            if (allowTelemetry && sourceName === "@comity/primitives") {
+                                return;
+                            }
+                            context.report({
+                                node,
+                                messageId: "forbiddenProperty",
+                                data: { object: obj.name, property: node.name },
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-forbidden-deep-import.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @comity-dev/no-forbidden-deep-import
+ *
+ * Forbid deep imports into another `@comity/*` package's internals.
+ *
+ * Examples:
+ *   import { foo } from "@comity/pricing/src/foo"      // ❌
+ *   import { foo } from "@comity/pricing/dist/foo.js"   // ❌
+ *   import { foo } from "@comity/pricing/internal/x"    // ❌
+ *   import { foo } from "@comity/pricing/lazy/x"        // ❌
+ *   import { foo } from "@comity/pricing"               // ✅
+ *   import { foo } from "@comity/pricing/exports/foo"   // ✅
+ *
+ * Standard references:
+ *   - public-api.md §3.2
+ *   - architecture-validation.md §4.1
+ */
+type Rule = unknown;
+declare const rule: Rule;
+export default rule;

package/dist/rules/no-forbidden-deep-import.js

@@ -0,0 +1,72 @@
+/**
+ * @comity-dev/no-forbidden-deep-import
+ *
+ * Forbid deep imports into another `@comity/*` package's internals.
+ *
+ * Examples:
+ *   import { foo } from "@comity/pricing/src/foo"      // ❌
+ *   import { foo } from "@comity/pricing/dist/foo.js"   // ❌
+ *   import { foo } from "@comity/pricing/internal/x"    // ❌
+ *   import { foo } from "@comity/pricing/lazy/x"        // ❌
+ *   import { foo } from "@comity/pricing"               // ✅
+ *   import { foo } from "@comity/pricing/exports/foo"   // ✅
+ *
+ * Standard references:
+ *   - public-api.md §3.2
+ *   - architecture-validation.md §4.1
+ */
+const FORBIDDEN_PATTERNS = [
+    /^@comity\/[^/]+\/src\//,
+    /^@comity\/[^/]+\/dist\//,
+    /^@comity\/[^/]+\/internal/,
+    /^@comity\/[^/]+\/lazy/,
+];
+function isForbidden(specifier) {
+    return FORBIDDEN_PATTERNS.some((re) => re.test(specifier));
+}
+const messages = {
+    forbidden: "Deep imports into another package's internals are forbidden (public-api.md §3.2). Import only from declared public subpaths.",
+};
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Forbid deep imports into other `@comity/*` packages' internals (src/, dist/, internal/, lazy/).",
+            category: "Comity Architecture",
+            recommended: true,
+        },
+        schema: [],
+        messages,
+    },
+    create(context) {
+        return {
+            ImportDeclaration(node) {
+                const specifier = node.source.value;
+                if (!specifier || !specifier.startsWith("@comity/"))
+                    return;
+                if (isForbidden(specifier)) {
+                    context.report({ node, messageId: "forbidden" });
+                }
+            },
+            ExportNamedDeclaration(node) {
+                if (!node.source || !node.source.value)
+                    return;
+                const specifier = node.source.value;
+                if (!specifier.startsWith("@comity/"))
+                    return;
+                if (isForbidden(specifier)) {
+                    context.report({ node, messageId: "forbidden" });
+                }
+            },
+            ExportAllDeclaration(node) {
+                const specifier = node.source.value;
+                if (!specifier || !specifier.startsWith("@comity/"))
+                    return;
+                if (isForbidden(specifier)) {
+                    context.report({ node, messageId: "forbidden" });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-forbidden-subpath-import.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @comity-dev/no-forbidden-subpath-import
+ *
+ * Forbid exports to forbidden subpaths (`utils`, `helpers`, `shared`,
+ * `internal`, `lazy`) per `public-api.md §3.2`.
+ *
+ * Standard references:
+ *   - public-api.md §3.2
+ *   - architecture-validation.md §4.2
+ */
+type Rule = unknown;
+declare const rule: Rule;
+export default rule;

package/dist/rules/no-forbidden-subpath-import.js

@@ -0,0 +1,79 @@
+/**
+ * @comity-dev/no-forbidden-subpath-import
+ *
+ * Forbid exports to forbidden subpaths (`utils`, `helpers`, `shared`,
+ * `internal`, `lazy`) per `public-api.md §3.2`.
+ *
+ * Standard references:
+ *   - public-api.md §3.2
+ *   - architecture-validation.md §4.2
+ */
+const FORBIDDEN_SUBPATHS = new Set([
+    "utils",
+    "helpers",
+    "shared",
+    "internal",
+    "lazy",
+]);
+const messages = {
+    forbiddenSubpath: "Exports subpath './{{segment}}' is forbidden (public-api.md §3.2).",
+};
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Forbid exports subpaths `utils`, `helpers`, `shared`, `internal`, `lazy`.",
+            category: "Comity Architecture",
+            recommended: true,
+        },
+        schema: [],
+        messages,
+    },
+    create(context) {
+        function isComityPackage(pkgName) {
+            return pkgName.startsWith("@comity/");
+        }
+        return {
+            ExportNamedDeclaration(node) {
+                // No source = local export; not relevant
+                if (!node.source || !node.source.value)
+                    return;
+                const specifier = node.source.value;
+                if (!specifier.startsWith("@comity/"))
+                    return;
+                // Only check imports/exports OF other @comity packages
+                const pkgMatch = specifier.match(/^@comity\/[^/]+/);
+                if (!pkgMatch || !isComityPackage(pkgMatch[0]))
+                    return;
+                // Subpath after the package name
+                const subpath = specifier.slice(pkgMatch[0].length).replace(/^\//, "");
+                const segment = subpath.split("/")[0];
+                if (segment && FORBIDDEN_SUBPATHS.has(segment)) {
+                    context.report({
+                        node,
+                        messageId: "forbiddenSubpath",
+                        data: { segment },
+                    });
+                }
+            },
+            ImportDeclaration(node) {
+                const specifier = node.source.value;
+                if (!specifier || !specifier.startsWith("@comity/"))
+                    return;
+                const pkgMatch = specifier.match(/^@comity\/[^/]+/);
+                if (!pkgMatch || !isComityPackage(pkgMatch[0]))
+                    return;
+                const subpath = specifier.slice(pkgMatch[0].length).replace(/^\//, "");
+                const segment = subpath.split("/")[0];
+                if (segment && FORBIDDEN_SUBPATHS.has(segment)) {
+                    context.report({
+                        node,
+                        messageId: "forbiddenSubpath",
+                        data: { segment },
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-layer-violation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @comity-dev/no-layer-violation
+ *
+ * Forbid imports that violate Comity's canonical layering policy.
+ *
+ * Disallowed edges (default):
+ *   - primitives  → any @comity/*
+ *   - kernel      → anything except primitives
+ *   - composition → anything except primitives, kernel
+ *   - core        → adapters
+ *   - adapters    → adapters (except integration-adapter → technology-adapter)
+ *
+ * Technology adapters MAY import the core contract they implement
+ * (declared via `implements` metadata).
+ *
+ * Allowed Core-to-Core edges are gated by ADR-008; this rule does NOT
+ * evaluate that register (it is enforced separately by the dependency
+ * rules / orchestrator). Use this rule only to catch the obvious violations.
+ *
+ * Standard references:
+ *   - layering-policy.md §2 (canonical layering model)
+ *   - architecture-validation.md §7
+ *   - ADR-007 (adapter categories)
+ */
+type Rule = unknown;
+declare const rule: Rule;
+export default rule;

package/dist/rules/no-layer-violation.js

@@ -0,0 +1,154 @@
+/**
+ * @comity-dev/no-layer-violation
+ *
+ * Forbid imports that violate Comity's canonical layering policy.
+ *
+ * Disallowed edges (default):
+ *   - primitives  → any @comity/*
+ *   - kernel      → anything except primitives
+ *   - composition → anything except primitives, kernel
+ *   - core        → adapters
+ *   - adapters    → adapters (except integration-adapter → technology-adapter)
+ *
+ * Technology adapters MAY import the core contract they implement
+ * (declared via `implements` metadata).
+ *
+ * Allowed Core-to-Core edges are gated by ADR-008; this rule does NOT
+ * evaluate that register (it is enforced separately by the dependency
+ * rules / orchestrator). Use this rule only to catch the obvious violations.
+ *
+ * Standard references:
+ *   - layering-policy.md §2 (canonical layering model)
+ *   - architecture-validation.md §7
+ *   - ADR-007 (adapter categories)
+ */
+const messages = {
+    forbidden: "This import violates Comity's layering policy (layering-policy.md §2).",
+};
+const LAYER_PROFILES = {
+    primitives: { allowed: new Set() },
+    kernel: { allowed: new Set(["primitives"]) },
+    composition: { allowed: new Set(["primitives", "kernel"]) },
+    core: { allowed: new Set(["primitives", "kernel", "core"]) },
+    "technology-adapter": {
+        allowed: new Set(["primitives", "kernel"]),
+    },
+    "integration-adapter": {
+        allowed: new Set(["primitives", "kernel", "core", "technology-adapter"]),
+    },
+};
+function classifyTarget(specifier) {
+    const m = specifier.match(/^(@comity\/[^/]+)/);
+    if (!m || !m[1])
+        return null;
+    return m[1];
+}
+function inferLayerFromFilename(filename) {
+    if (!filename)
+        return null;
+    if (filename.includes("/primitives/"))
+        return "primitives";
+    if (filename.includes("/kernel/"))
+        return "kernel";
+    if (filename.includes("/composition/"))
+        return "composition";
+    if (filename.includes("/packages/")) {
+        // Check for core packages
+        const corePackages = [
+            "http", "router", "html", "hydration", "seo", "content", "media", "search",
+            "cache", "auth", "catalog", "customer", "inventory", "order", "payment",
+            "pricing", "storefront", "taxonomy", "validation", "address", "geography",
+            "identity", "organization", "acl", "auth-tokens", "graphql-builder",
+            "graphql-client", "i18n", "sql", "storage"
+        ];
+        for (const pkg of corePackages) {
+            if (filename.includes(`/packages/${pkg}/`))
+                return "core";
+        }
+        // Check for technology adapters
+        const adapterPackages = [
+            "html-preact", "html-react", "hydration-preact", "hydration-react",
+            "http-hono", "http-fetch", "router-path-to-regexp",
+            "acl-casl", "auth-jose", "cache-kv", "cache-redis",
+            "cli-commander", "graphql-client-fetch", "graphql-client-ws",
+            "i18n-typesafe", "sql-kysely", "validation-zod"
+        ];
+        for (const pkg of adapterPackages) {
+            if (filename.includes(`/packages/${pkg}/`))
+                return "technology-adapter";
+        }
+    }
+    return null;
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Forbid imports that violate Comity's canonical layering policy.",
+            category: "Comity Architecture",
+            recommended: true,
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    sourceName: {
+                        type: "string",
+                        description: "Name of the source package (e.g., '@comity/pricing'). Required.",
+                    },
+                    classification: {
+                        type: "object",
+                        description: "Map of package name → layer. The plugin receives this via configuration; it MUST NOT hardcode layers.",
+                    },
+                    implements: {
+                        type: "object",
+                        description: "Map of package name → implemented core package (for technology-adapter packages).",
+                    },
+                },
+                required: ["sourceName", "classification"],
+                additionalProperties: false,
+            },
+        ],
+        messages,
+    },
+    create(context) {
+        const opts = (context.options[0] ?? {});
+        const classification = opts.classification ?? {};
+        const implementsMap = opts.implements ?? {};
+        const sourceName = opts.sourceName ?? null;
+        // Fallback: infer source layer from filename if sourceName not provided
+        let sourceLayer = sourceName ? classification[sourceName] : inferLayerFromFilename(context.filename ?? context.getFilename());
+        if (!sourceLayer)
+            return {};
+        const profile = LAYER_PROFILES[sourceLayer];
+        if (!profile)
+            return {};
+        // If sourceName not provided, we can't check implementsMap, so skip that allowance
+        const effectiveSourceName = sourceName;
+        return {
+            ImportDeclaration(node) {
+                const specifier = node.source.value;
+                if (!specifier)
+                    return;
+                const target = classifyTarget(specifier);
+                if (!target)
+                    return;
+                // Look up the target package's layer
+                const targetLayer = classification[target];
+                if (!targetLayer)
+                    return; // unknown package — outside this rule's scope
+                // Allow technology-adapter to import its implemented core contract
+                if (effectiveSourceName &&
+                    sourceLayer === "technology-adapter" &&
+                    targetLayer === "core" &&
+                    implementsMap[effectiveSourceName] === target) {
+                    return; // Allowed: adapter implements this core contract
+                }
+                if (!profile.allowed.has(targetLayer)) {
+                    context.report({ node, messageId: "forbidden" });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-render-core-http-runtime.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @comity-dev/no-render-core-http-runtime
+ *
+ * Forbid Rendering Core Modules (html, hydration, search, seo, content)
+ * from importing HTTP runtime implementations (http-hono, http-fetch,
+ * html-preact, html-react, hydration-preact, hydration-react).
+ *
+ * The rule is scoped to only apply to files within the declared Rendering
+ * Core packages. Technology adapters and client entry points are permitted
+ * to import their respective runtimes.
+ *
+ * Standard references:
+ *   - layering-policy.md §8 (rendering core MUST NOT depend on HTTP runtime)
+ *   - architecture-validation.md §4.3
+ */
+type Rule = unknown;
+declare const rule: Rule;
+export default rule;

package/dist/rules/no-render-core-http-runtime.js

@@ -0,0 +1,100 @@
+/**
+ * @comity-dev/no-render-core-http-runtime
+ *
+ * Forbid Rendering Core Modules (html, hydration, search, seo, content)
+ * from importing HTTP runtime implementations (http-hono, http-fetch,
+ * html-preact, html-react, hydration-preact, hydration-react).
+ *
+ * The rule is scoped to only apply to files within the declared Rendering
+ * Core packages. Technology adapters and client entry points are permitted
+ * to import their respective runtimes.
+ *
+ * Standard references:
+ *   - layering-policy.md §8 (rendering core MUST NOT depend on HTTP runtime)
+ *   - architecture-validation.md §4.3
+ */
+const RENDERING_CORE_PACKAGES = new Set([
+    "@comity/html",
+    "@comity/hydration",
+    "@comity/search",
+    "@comity/seo",
+    "@comity/content",
+]);
+const FORBIDDEN_RUNTIME_PACKAGES = new Set([
+    "@comity/http-hono",
+    "@comity/http-fetch",
+    "@comity/html-preact",
+    "@comity/html-react",
+    "@comity/hydration-preact",
+    "@comity/hydration-react",
+]);
+const messages = {
+    forbiddenRuntime: "Rendering Core Module MUST NOT import HTTP/Rendering runtime '{{target}}' (layering-policy.md §8).",
+};
+function isInRenderingCorePackage(filename) {
+    return Array.from(RENDERING_CORE_PACKAGES).some((pkg) => filename.includes(`/packages/${pkg.replace("@comity/", "")}/`));
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Forbid Rendering Core Modules from importing HTTP / Rendering runtimes.",
+            category: "Comity Architecture",
+            recommended: true,
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    sourceName: {
+                        type: "string",
+                        description: "Name of the source package (e.g., '@comity/html'). Used to scope the rule.",
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages,
+    },
+    create(context) {
+        const opts = (context.options[0] ?? {});
+        const sourceName = opts.sourceName ?? null;
+        // If no sourceName provided, fall back to filename heuristic
+        const inRenderingCore = sourceName
+            ? RENDERING_CORE_PACKAGES.has(sourceName)
+            : isInRenderingCorePackage(context.filename ?? context.getFilename());
+        // Disable this rule outside rendering core packages
+        if (!inRenderingCore) {
+            return {};
+        }
+        function checkImport(specifier, node) {
+            if (!specifier.startsWith("@comity/"))
+                return;
+            if (FORBIDDEN_RUNTIME_PACKAGES.has(specifier)) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                context.report({
+                    node: node,
+                    messageId: "forbiddenRuntime",
+                    data: { target: specifier },
+                });
+            }
+        }
+        return {
+            ImportDeclaration(node) {
+                checkImport(node.source.value, node);
+            },
+            ImportExpression(node) {
+                if (node.source.type === "Literal" &&
+                    typeof node.source.value === "string") {
+                    checkImport(node.source.value, node);
+                }
+            },
+            ExportNamedDeclaration(node) {
+                if (node.source && node.source.value) {
+                    checkImport(node.source.value, node);
+                }
+            },
+        };
+    },
+};
+export default rule;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@comity-dev/eslint-plugin",
+  "version": "0.1.0",
+  "description": "Reusable ESLint rules for Comity source-code policy. 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"
+    },
+    "./recommended": {
+      "types": "./dist/recommended.d.ts",
+      "default": "./dist/recommended.js"
+    }
+  },
+  "files": [
+    "./dist"
+  ],
+  "peerDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.5",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}