@comity-dev/eslint-plugin 0.2.0 → 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/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/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.0",
   "description": "Reusable ESLint rules for Comity source-code policy. Development tooling.",
   "type": "module",
   "private": false,