@comity-dev/eslint-plugin 0.2.0 → 0.3.1

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/plugin.js

@@ -4,6 +4,7 @@ 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 },
@@ -11,6 +12,7 @@ export const BUILTIN_RULES = [
     { 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: {

package/dist/recommended.js

@@ -6,5 +6,6 @@ export const recommended = {
         "@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-layer-violation.d.ts

@@ -3,23 +3,40 @@
  *
  * 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)
+ * The permitted edges per source layer are the table `LAYER_PROFILES` below. They follow
+ * ADR-025 §5 (formal package dependencies: Application → Technology Adapters → Core
+ * Modules → composition → kernel → primitives; every edge points downward), together with
+ * `layering-policy.md` §2 and `architecture-validation.md` §4.1:
  *
- * Technology adapters MAY import the core contract they implement
- * (declared via `implements` metadata).
+ *   - primitives          → no internal package
+ *   - kernel              → primitives
+ *                           (kernel → composition is forbidden, ADR-025 §5 "Forbidden")
+ *   - composition         → primitives, kernel
+ *                           (composition → any Core Module is forbidden, ADR-025 hard
+ *                           invariant)
+ *   - core                → primitives, kernel, composition, core
+ *                           (Core → Core is further gated by ADR-008, not by this rule)
+ *   - technology-adapter  → primitives, kernel, composition, and the Core Module it
+ *                           implements
+ *   - integration-adapter → primitives, kernel, core, technology-adapter
  *
- * 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.
+ * Technology Adapters MAY import the core contract they implement (declared via
+ * `implements` metadata).
+ *
+ * A source package whose layer has no profile (for example `dev-tooling`), and a target
+ * that is not in the supplied classification, are outside this rule's scope. The
+ * classification is data supplied by the consumer (ADR-026); this rule never exempts a
+ * layer: there is no option to remove one.
+ *
+ * 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). The
+ * sibling generator `@comity-dev/dependency-rules` expresses the same layer policy for
+ * dependency-cruiser; see `architecture-validation.md` §4.1 for how the two relate.
  *
  * Standard references:
+ *   - ADR-025 §5 (formal package dependencies)
  *   - layering-policy.md §2 (canonical layering model)
- *   - architecture-validation.md §7
+ *   - architecture-validation.md §4.1, §7
  *   - ADR-007 (adapter categories)
  */
 type Rule = unknown;

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

@@ -3,23 +3,40 @@
  *
  * 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)
+ * The permitted edges per source layer are the table `LAYER_PROFILES` below. They follow
+ * ADR-025 §5 (formal package dependencies: Application → Technology Adapters → Core
+ * Modules → composition → kernel → primitives; every edge points downward), together with
+ * `layering-policy.md` §2 and `architecture-validation.md` §4.1:
  *
- * Technology adapters MAY import the core contract they implement
- * (declared via `implements` metadata).
+ *   - primitives          → no internal package
+ *   - kernel              → primitives
+ *                           (kernel → composition is forbidden, ADR-025 §5 "Forbidden")
+ *   - composition         → primitives, kernel
+ *                           (composition → any Core Module is forbidden, ADR-025 hard
+ *                           invariant)
+ *   - core                → primitives, kernel, composition, core
+ *                           (Core → Core is further gated by ADR-008, not by this rule)
+ *   - technology-adapter  → primitives, kernel, composition, and the Core Module it
+ *                           implements
+ *   - integration-adapter → primitives, kernel, core, technology-adapter
  *
- * 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.
+ * Technology Adapters MAY import the core contract they implement (declared via
+ * `implements` metadata).
+ *
+ * A source package whose layer has no profile (for example `dev-tooling`), and a target
+ * that is not in the supplied classification, are outside this rule's scope. The
+ * classification is data supplied by the consumer (ADR-026); this rule never exempts a
+ * layer: there is no option to remove one.
+ *
+ * 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). The
+ * sibling generator `@comity-dev/dependency-rules` expresses the same layer policy for
+ * dependency-cruiser; see `architecture-validation.md` §4.1 for how the two relate.
  *
  * Standard references:
+ *   - ADR-025 §5 (formal package dependencies)
  *   - layering-policy.md §2 (canonical layering model)
- *   - architecture-validation.md §7
+ *   - architecture-validation.md §4.1, §7
  *   - ADR-007 (adapter categories)
  */
 const messages = {
@@ -29,9 +46,9 @@ 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"]) },
+    core: { allowed: new Set(["primitives", "kernel", "composition", "core"]) },
     "technology-adapter": {
-        allowed: new Set(["primitives", "kernel"]),
+        allowed: new Set(["primitives", "kernel", "composition"]),
     },
     "integration-adapter": {
         allowed: new Set(["primitives", "kernel", "core", "technology-adapter"]),

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.2.0",
+  "version": "0.3.1",
   "description": "Reusable ESLint rules for Comity source-code policy. Development tooling.",
   "type": "module",
   "private": false,
@@ -39,7 +39,7 @@
     "typescript": "^5.9.3"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "vitest run"
   }
 }