@comity-dev/eslint-plugin 0.1.2 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ Reusable ESLint rules for Comity-wide source-code policy. This package owns the
 
 ## Scope
 
-Six rules, each addressing a Comity-wide concern:
+Seven rules, each addressing a Comity-wide concern:
 
 | Rule                          | Concern                                                                                                                                       |
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -16,6 +16,7 @@ Six rules, each addressing a Comity-wide concern:
 | `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.                                                                                    |
+| `require-internal-marker`     | Require an `@internal` JSDoc tag on production sources under `src/internal/` and `src/lazy/` (owner-approved Contract B).                     |
 
 ## Ownership
 

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,29 @@
+/**
+ * @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 type { ESLint } from "eslint";
+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: ESLint.Plugin;
+/** Stable list of rule identifiers exported by this plugin. */
+export declare const RULE_IDS: string[];

package/dist/plugin.js

@@ -0,0 +1,25 @@
+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";
+import requireInternalMarker from "./rules/require-internal-marker.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 },
+    { name: "require-internal-marker", rule: requireInternalMarker },
+];
+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,11 @@
+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",
+        "@comity-dev/require-internal-marker": "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,122 @@
+/**
+ * @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) {
+                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,21 @@
+/**
+ * @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): `Date`
+ *   use under `packages/primitives/src/time/` is the sanctioned clock
+ *   boundary of the framework.
+ *
+ * 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,200 @@
+/**
+ * @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): `Date`
+ *   use under `packages/primitives/src/time/` is the sanctioned clock
+ *   boundary of the framework.
+ *
+ * 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 normalizeFilename(filename) {
+    return filename.replace(/\\/g, "/");
+}
+function isInCoreOrKernelPackage(filename) {
+    const normalized = normalizeFilename(filename);
+    return (normalized.includes("/packages/") &&
+        (normalized.includes("/primitives/") ||
+            normalized.includes("/kernel/") ||
+            normalized.includes("/composition/") ||
+            normalized.includes("/http/") ||
+            normalized.includes("/router/") ||
+            normalized.includes("/html/") ||
+            normalized.includes("/hydration/") ||
+            normalized.includes("/seo/") ||
+            normalized.includes("/content/") ||
+            normalized.includes("/media/") ||
+            normalized.includes("/search/")));
+}
+function isTelemetryAllowedPackage(filename) {
+    const normalized = normalizeFilename(filename);
+    return Array.from(TELEMETRY_ALLOWLIST).some((pkg) => normalized.includes(`/packages/${pkg.replace("@comity/", "")}/`) ||
+        normalized.includes(`/community/packages/${pkg.replace("@comity/", "")}/`));
+}
+/**
+ * Returns whether the file is one of the sanctioned time primitives that
+ * own the framework's `Date` clock boundary.
+ *
+ * The exemption is deliberately path-narrow: only files under
+ * `packages/primitives/src/time/` qualify. `Date` use anywhere else in
+ * Core — including elsewhere inside `@comity/primitives` — remains
+ * forbidden.
+ *
+ * @param filename - The file under lint, in platform-native form.
+ *
+ * @returns `true` when the file is a sanctioned time primitive.
+ */
+function isTimePrimitiveFile(filename) {
+    return normalizeFilename(filename).includes("/packages/primitives/src/time/");
+}
+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;
+        const filename = context.filename ?? context.getFilename();
+        // 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(filename);
+        // 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(filename);
+        // Sanctioned clock boundary: time primitives own `Date` usage.
+        const isTimePrimitive = isTimePrimitiveFile(filename);
+        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")) {
+                    // Time primitives own the `Date` clock boundary: `Date.now()` as
+                    // the clock source and `new Date(ms)` for deterministic rendering
+                    // are legitimate exactly here and nowhere else in Core.
+                    if (node.name === "Date" && isTimePrimitive) {
+                        return;
+                    }
+                    // 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,193 @@
+/**
+ * @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/dist/rules/require-internal-marker.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @comity-dev/require-internal-marker
+ *
+ * Contract B: production TypeScript sources under `packages/<name>/src/internal/`
+ * or `packages/<name>/src/lazy/` MUST declare an `@internal` JSDoc tag.
+ *
+ * Both accepted marker forms are equivalent: the inline form (the tag on the
+ * same line as the JSDoc opener) and the conventional multiline form (the tag
+ * on its own line inside the block).
+ *
+ * The marker must be an actual JSDoc tag, so it must occupy a JSDoc tag
+ * position — immediately after the block opener, or at the start of a line
+ * inside the block after the optional leading asterisk. Consequences:
+ *
+ *   - A prose mention of `@internal` inside a JSDoc description is not a tag.
+ *   - `@internalOnly` and `@internal-extra` are different tag names.
+ *   - Line comments, ordinary block comments, and marker-like text inside
+ *     strings, template literals, tagged templates, or regular-expression
+ *     literals never satisfy the rule, because the parser only produces
+ *     comment tokens for real comments.
+ *
+ * The requirement is file-level: a file satisfies it when it contains a valid
+ * `@internal` JSDoc block followed by code, since the marker annotates the
+ * file's declarations. A marker attached to any declaration — top-level,
+ * class member, or nested — satisfies it, and a trailing marker with no
+ * following code does not. The repository's internal sources attach the
+ * docblock to the declaration it documents, which is the narrowest reading
+ * consistent with the approved contract.
+ *
+ * Scope: production TypeScript sources under the two internal directories
+ * only. Test files, mocks, fixtures, declaration/generated output, build and
+ * coverage output, and dependency directories are excluded, matching the
+ * repository's established ESLint conventions.
+ *
+ * Traceability: the marker policy is an owner-approved contract decision. It
+ * is NOT defined by public-api.md §3.2, which forbids public `/internal` and
+ * `/lazy` sub-entrypoints. This rule replaces the retired Semgrep rule
+ * `comity-module-must-have-internal-marker`, which could not inspect real
+ * JSDoc syntax (Semgrep strips comments from structural patterns).
+ */
+type Rule = unknown;
+declare const rule: Rule;
+export default rule;

package/dist/rules/require-internal-marker.js

@@ -0,0 +1,154 @@
+/**
+ * @comity-dev/require-internal-marker
+ *
+ * Contract B: production TypeScript sources under `packages/<name>/src/internal/`
+ * or `packages/<name>/src/lazy/` MUST declare an `@internal` JSDoc tag.
+ *
+ * Both accepted marker forms are equivalent: the inline form (the tag on the
+ * same line as the JSDoc opener) and the conventional multiline form (the tag
+ * on its own line inside the block).
+ *
+ * The marker must be an actual JSDoc tag, so it must occupy a JSDoc tag
+ * position — immediately after the block opener, or at the start of a line
+ * inside the block after the optional leading asterisk. Consequences:
+ *
+ *   - A prose mention of `@internal` inside a JSDoc description is not a tag.
+ *   - `@internalOnly` and `@internal-extra` are different tag names.
+ *   - Line comments, ordinary block comments, and marker-like text inside
+ *     strings, template literals, tagged templates, or regular-expression
+ *     literals never satisfy the rule, because the parser only produces
+ *     comment tokens for real comments.
+ *
+ * The requirement is file-level: a file satisfies it when it contains a valid
+ * `@internal` JSDoc block followed by code, since the marker annotates the
+ * file's declarations. A marker attached to any declaration — top-level,
+ * class member, or nested — satisfies it, and a trailing marker with no
+ * following code does not. The repository's internal sources attach the
+ * docblock to the declaration it documents, which is the narrowest reading
+ * consistent with the approved contract.
+ *
+ * Scope: production TypeScript sources under the two internal directories
+ * only. Test files, mocks, fixtures, declaration/generated output, build and
+ * coverage output, and dependency directories are excluded, matching the
+ * repository's established ESLint conventions.
+ *
+ * Traceability: the marker policy is an owner-approved contract decision. It
+ * is NOT defined by public-api.md §3.2, which forbids public `/internal` and
+ * `/lazy` sub-entrypoints. This rule replaces the retired Semgrep rule
+ * `comity-module-must-have-internal-marker`, which could not inspect real
+ * JSDoc syntax (Semgrep strips comments from structural patterns).
+ */
+const messages = {
+    missing: "Production sources under `src/internal/` or `src/lazy/` MUST declare an `@internal` JSDoc tag (inline or multiline).",
+};
+/** File extensions treated as production TypeScript sources. */
+const TYPESCRIPT_FILE = /\.(?:ts|tsx|mts|cts)$/;
+/** Test files: excluded by the validator ESLint engine and the consumer config. */
+const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+/** Declaration output is generated by `tsc`; the consumer config ignores it. */
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+/** Generated sources are excluded by the consumer's ESLint ignore list. */
+const GENERATED_FILE = /\.generated\./;
+/**
+ * Path segments excluded by repository convention: dependency directories,
+ * build/coverage output, and test/mock/fixture trees (the consumer keeps real
+ * `src/__mocks__` directories, and the retired Semgrep rule excluded
+ * `__fixtures__`).
+ */
+const EXCLUDED_SEGMENTS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "__tests__",
+    "__fixtures__",
+    "__mocks__",
+]);
+/** `packages/<name>/src/internal/` or `packages/<name>/src/lazy/` */
+const SCOPED_PATH = /(?:^|\/)packages\/[^/]+\/src\/(?:internal|lazy)\//;
+function normalizeFilename(filename) {
+    return filename.replace(/\\/g, "/");
+}
+function isScopedProductionFile(filename) {
+    if (!filename)
+        return false;
+    const normalized = normalizeFilename(filename);
+    if (!TYPESCRIPT_FILE.test(normalized))
+        return false;
+    if (TEST_FILE.test(normalized))
+        return false;
+    if (DECLARATION_FILE.test(normalized))
+        return false;
+    if (GENERATED_FILE.test(normalized))
+        return false;
+    if (normalized.split("/").some((segment) => EXCLUDED_SEGMENTS.has(segment))) {
+        return false;
+    }
+    return SCOPED_PATH.test(normalized);
+}
+/** A JSDoc tag must not be followed by more tag-name characters. */
+const INTERNAL_TAG = /^[ \t]*@internal(?![A-Za-z0-9_-])/;
+/**
+ * Whether a JSDoc block comment body declares the `@internal` tag.
+ *
+ * @param value - The comment value. A JSDoc block starts with `*`.
+ *
+ * @remarks
+ * The tag must begin a line inside the block (after the optional leading
+ * asterisk) or immediately follow the block opener, which is where JSDoc
+ * allows tags. Prose that merely mentions `@internal` is therefore not a tag.
+ */
+function declaresInternalTag(value) {
+    const lines = value.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
+        const raw = lines[index] ?? "";
+        const content = index === 0 ? raw.slice(1) : raw.replace(/^[ \t]*/, "");
+        if (index > 0 && content.startsWith("*")) {
+            if (INTERNAL_TAG.test(content.slice(1)))
+                return true;
+            continue;
+        }
+        if (INTERNAL_TAG.test(content))
+            return true;
+    }
+    return false;
+}
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require an `@internal` JSDoc marker on production sources under `src/internal/` and `src/lazy/`.",
+            category: "Comity Architecture",
+            recommended: true,
+        },
+        schema: [],
+        messages,
+    },
+    create(context) {
+        const filename = context.filename ?? context.getFilename();
+        if (!isScopedProductionFile(String(filename ?? "")))
+            return {};
+        return {
+            Program(node) {
+                const sourceCode = context.sourceCode ?? context.getSourceCode();
+                const lastToken = sourceCode.getLastToken(node);
+                for (const comment of sourceCode.getAllComments()) {
+                    if (comment.type !== "Block")
+                        continue;
+                    const value = String(comment.value ?? "");
+                    // JSDoc block comments start with `*`; `/* ... */` does not.
+                    if (!value.startsWith("*"))
+                        continue;
+                    if (!declaresInternalTag(value))
+                        continue;
+                    // The marker must annotate following code, not trail the file.
+                    if (lastToken && lastToken.range[0] > comment.range[1])
+                        return;
+                }
+                context.report({ node, messageId: "missing" });
+            },
+        };
+    },
+};
+export default rule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comity-dev/eslint-plugin",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Reusable ESLint rules for Comity source-code policy. Development tooling.",
   "type": "module",
   "private": false,