@reticlehq/eslint-plugin 2.13.1 → 3.1.0

package/dist/constants.d.ts

@@ -15,6 +15,17 @@ export declare const DEFAULT_MUTATORS: readonly string[];
 /** Plugin meta name used in the flat-config export + RuleCreator url namespace. */
 export declare const PLUGIN_NAME = "reticle";
 /** Docs URL builder root for ESLintUtils.RuleCreator. */
-export declare const DOCS_URL_ROOT = "https://github.com/reticlehq/reticle/blob/main/packages/eslint-plugin/README.md";
+export declare const DOCS_URL_ROOT = "https://github.com/reticlehq/reticle/blob/main/eslint-plugin/README.md";
 /** Rule that keeps design-doc codes and internal version strings out of source comments. */
 export declare const INTERNAL_TAGS_RULE_NAME = "no-internal-tags";
+/** Rule that caps how long one block comment may be. */
+export declare const RUNAWAY_COMMENT_RULE_NAME = "no-runaway-comment";
+/**
+ * Longest permitted block comment, in lines.
+ *
+ * Set above the longest genuine comment in the repository (45) and far below the 423-line accident
+ * this rule exists to catch, so it reports a paste and never a paragraph.
+ */
+export declare const MAX_COMMENT_LINES = 60;
+/** The human-readable report text (the assertion in tests matches this verbatim). */
+export declare const RUNAWAY_COMMENT_MESSAGE = "block comment is {{lines}} lines (max {{max}}) \u2014 a comment this long is usually pasted output, not prose";

package/dist/constants.js

@@ -14,6 +14,17 @@ export const DEFAULT_MUTATORS = [];
 /** Plugin meta name used in the flat-config export + RuleCreator url namespace. */
 export const PLUGIN_NAME = 'reticle';
 /** Docs URL builder root for ESLintUtils.RuleCreator. */
-export const DOCS_URL_ROOT = 'https://github.com/reticlehq/reticle/blob/main/packages/eslint-plugin/README.md';
+export const DOCS_URL_ROOT = 'https://github.com/reticlehq/reticle/blob/main/eslint-plugin/README.md';
 /** Rule that keeps design-doc codes and internal version strings out of source comments. */
 export const INTERNAL_TAGS_RULE_NAME = 'no-internal-tags';
+/** Rule that caps how long one block comment may be. */
+export const RUNAWAY_COMMENT_RULE_NAME = 'no-runaway-comment';
+/**
+ * Longest permitted block comment, in lines.
+ *
+ * Set above the longest genuine comment in the repository (45) and far below the 423-line accident
+ * this rule exists to catch, so it reports a paste and never a paragraph.
+ */
+export const MAX_COMMENT_LINES = 60;
+/** The human-readable report text (the assertion in tests matches this verbatim). */
+export const RUNAWAY_COMMENT_MESSAGE = 'block comment is {{lines}} lines (max {{max}}) — a comment this long is usually pasted output, not prose';

package/dist/index.d.ts

@@ -1,11 +1,15 @@
 /** @reticlehq/eslint-plugin — flat-config plugin export. */
 import { requireSignalOnMutation } from './require-signal-on-mutation.js';
 import { noInternalTags } from './no-internal-tags.js';
+import { noRunawayComment } from './no-runaway-comment.js';
 export declare const rules: {
     readonly "require-signal-on-mutation": import("@typescript-eslint/utils/ts-eslint").RuleModule<"mutationWithoutSignal", [import("./options.js").RawRuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
         name: string;
     };
-    readonly "no-internal-tags": import("@typescript-eslint/utils/ts-eslint").RuleModule<"internalTag", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    readonly "no-internal-tags": import("@typescript-eslint/utils/ts-eslint").RuleModule<"internalTag" | "pathTag", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+        name: string;
+    };
+    readonly "no-runaway-comment": import("@typescript-eslint/utils/ts-eslint").RuleModule<"runawayComment", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
         name: string;
     };
 };
@@ -17,11 +21,14 @@ declare const plugin: {
         readonly "require-signal-on-mutation": import("@typescript-eslint/utils/ts-eslint").RuleModule<"mutationWithoutSignal", [import("./options.js").RawRuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;
         };
-        readonly "no-internal-tags": import("@typescript-eslint/utils/ts-eslint").RuleModule<"internalTag", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+        readonly "no-internal-tags": import("@typescript-eslint/utils/ts-eslint").RuleModule<"internalTag" | "pathTag", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        readonly "no-runaway-comment": import("@typescript-eslint/utils/ts-eslint").RuleModule<"runawayComment", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;
         };
     };
     configs: Record<string, unknown>;
 };
 export default plugin;
-export { requireSignalOnMutation, noInternalTags };
+export { requireSignalOnMutation, noInternalTags, noRunawayComment };

package/dist/index.js

@@ -1,10 +1,12 @@
 /** @reticlehq/eslint-plugin — flat-config plugin export. */
 import { requireSignalOnMutation } from './require-signal-on-mutation.js';
 import { noInternalTags } from './no-internal-tags.js';
-import { PLUGIN_NAME, RULE_NAME, INTERNAL_TAGS_RULE_NAME } from './constants.js';
+import { noRunawayComment } from './no-runaway-comment.js';
+import { PLUGIN_NAME, RULE_NAME, INTERNAL_TAGS_RULE_NAME, RUNAWAY_COMMENT_RULE_NAME, } from './constants.js';
 export const rules = {
     [RULE_NAME]: requireSignalOnMutation,
     [INTERNAL_TAGS_RULE_NAME]: noInternalTags,
+    [RUNAWAY_COMMENT_RULE_NAME]: noRunawayComment,
 };
 const plugin = {
     meta: { name: PLUGIN_NAME },
@@ -20,7 +22,8 @@ plugin.configs['recommended'] = {
     rules: {
         [`${PLUGIN_NAME}/${RULE_NAME}`]: 'warn',
         [`${PLUGIN_NAME}/${INTERNAL_TAGS_RULE_NAME}`]: 'error',
+        [`${PLUGIN_NAME}/${RUNAWAY_COMMENT_RULE_NAME}`]: 'error',
     },
 };
 export default plugin;
-export { requireSignalOnMutation, noInternalTags };
+export { requireSignalOnMutation, noInternalTags, noRunawayComment };

package/dist/no-internal-tags.d.ts

@@ -1,14 +1,12 @@
 /**
  * Rule: no-internal-tags.
  *
- * Bans design-doc reference codes and internal version strings from comments, so a reader of the source
- * never meets a token that only means something in a document they cannot see.
+ * Bans design-doc reference codes and internal version strings from comments, TEST DESCRIPTIONS and
+ * the FILE AND DIRECTORY NAMES of the module itself, so a reader of the source never meets a token
+ * that only means something in a document they cannot see.
  *
- * This rule exists because the prose version of it did not hold. An audit of the codebase found the
- * machine-checked rules at ~100% compliance and every prose-only rule violated — 59 tracking codes
- * across the library packages alone, including in the contract package and in test descriptions, plus
- * codes that leaked into user-facing docs. The gap was enforcement, not intent, so the rule is now a
- * lint error rather than a paragraph.
+ * A path is the first thing a reader meets, before any comment, so `n5-ring-buffer.ts` is the shape
+ * this bans in the loudest available place.
  *
  * Deliberately narrow, to avoid punishing legitimate prose:
  *   - a bare `W11`, `B37`, `N5`, `M8` style token (one or two capitals + digits) standing alone;
@@ -18,6 +16,6 @@
  * `H2`, `Welford M2` when part of a sentence) is matched only when it stands alone as a tag.
  */
 import { ESLintUtils } from '@typescript-eslint/utils';
-export declare const noInternalTags: ESLintUtils.RuleModule<"internalTag", [], unknown, ESLintUtils.RuleListener> & {
+export declare const noInternalTags: ESLintUtils.RuleModule<"internalTag" | "pathTag", [], unknown, ESLintUtils.RuleListener> & {
     name: string;
 };

package/dist/no-internal-tags.js

@@ -1,14 +1,12 @@
 /**
  * Rule: no-internal-tags.
  *
- * Bans design-doc reference codes and internal version strings from comments, so a reader of the source
- * never meets a token that only means something in a document they cannot see.
+ * Bans design-doc reference codes and internal version strings from comments, TEST DESCRIPTIONS and
+ * the FILE AND DIRECTORY NAMES of the module itself, so a reader of the source never meets a token
+ * that only means something in a document they cannot see.
  *
- * This rule exists because the prose version of it did not hold. An audit of the codebase found the
- * machine-checked rules at ~100% compliance and every prose-only rule violated — 59 tracking codes
- * across the library packages alone, including in the contract package and in test descriptions, plus
- * codes that leaked into user-facing docs. The gap was enforcement, not intent, so the rule is now a
- * lint error rather than a paragraph.
+ * A path is the first thing a reader meets, before any comment, so `n5-ring-buffer.ts` is the shape
+ * this bans in the loudest available place.
  *
  * Deliberately narrow, to avoid punishing legitimate prose:
  *   - a bare `W11`, `B37`, `N5`, `M8` style token (one or two capitals + digits) standing alone;
@@ -17,33 +15,43 @@
  * Ordinary technical prose that happens to contain a letter and digits inside a larger word (`UTF-8`,
  * `H2`, `Welford M2` when part of a sentence) is matched only when it stands alone as a tag.
  */
+import { relative, sep } from 'node:path';
 import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils';
 import { DOCS_URL_ROOT } from './constants.js';
 const createRule = ESLintUtils.RuleCreator((name) => `${DOCS_URL_ROOT}#${name}`);
 const INTERNAL_TAG_MESSAGE = "Internal reference '{{tag}}' does not belong in source. It means nothing to a reader without the design doc — describe the behaviour instead.";
-/** `(W11)`, `B37`, `W10.3`, `N5:` — a short capital-prefixed code used as a label. */
-const TRACKING_CODE = /(?<![A-Za-z0-9])[A-Z]{1,2}\d{1,2}(?:\.\d{1,2})?(?![A-Za-z0-9])/g;
+const PATH_TAG_MESSAGE = "Internal reference '{{tag}}' does not belong in a file or directory name. It means nothing to a reader without the design doc — name the module after what it does.";
 /**
- * `§4.3` — a design-doc section reference.
- *
- * Defaults to FLAGGING and exempts only a citation of a NAMED EXTERNAL spec. The first version did the
- * reverse — it exempted any § preceded by a word — which silently permitted `see PLAN §4.3`, the very
- * shape being banned. For a ban rule the default must be "flag", or the exemption swallows the rule.
+ * `(W11)`, `B37`, `W10.3`, `N5:`, `P5a` — a short capital-prefixed code used as a label. The optional
+ * trailing letter is how a design document tells sibling parts apart. Exactly ONE, and lower case:
+ * two would start matching ordinary identifiers, and an upper-case one would catch names like `UTF8B`.
+ * Exempted by `ALLOWED` below.
+ */
+const TRACKING_CODE = /(?<![A-Za-z0-9])[A-Z]{1,2}\d{1,2}(?:\.\d{1,2})?[a-z]?(?![A-Za-z0-9])/g;
+/**
+ * `§4.3` — a design-doc section reference. Flags by default and exempts only a citation of a NAMED
+ * EXTERNAL spec (`EXTERNAL_SPECS`); exempting any § preceded by a word would permit `see PLAN §4.3`,
+ * the very shape being banned.
  */
 const SECTION_REF = /§\s?\d+(?:\.\d+)*/g;
 /** Specs whose section numbers are real references a reader can follow. */
 const EXTERNAL_SPECS = /\b(RFC|WCAG|ECMA|ISO|IEEE|W3C|WHATWG|HTML|CSS|ARIA|HTTP|OAuth|JSON-LD)\b[^§]{0,20}$/i;
 /**
- * `v2.2.0` — an INTERNAL version string.
- *
- * Same inversion: flag by default, exempt only a version attributed to a NAMED third party. Exempting
- * "any capitalised preceding word" permitted `new in Reticle v2.2.0` — our own product name made the
- * banned string legal.
+ * `v2.2.0` — an INTERNAL version string. Flags by default and exempts only a version attributed to a
+ * NAMED third party (`THIRD_PARTY`); exempting any capitalised preceding word would make
+ * `new in Reticle v2.2.0` legal.
  */
 const VERSION_STRING = /(?<![A-Za-z0-9])v\d+\.\d+\.\d+(?![A-Za-z0-9])/g;
+/**
+ * The same two shapes over a PATH, case-insensitively: file names here are kebab-case, so `N5` in a
+ * sentence reads `n5` in a path and the upper-case patterns above cannot see it. The boundaries do the
+ * work that case was doing — `e2e`, `utf8`, `http2` and `base64` all need a non-alphanumeric on both
+ * sides of a letters-then-digits token, and so fail them.
+ */
+const PATH_TRACKING_CODE = /(?<![A-Za-z0-9])[A-Za-z]{1,2}\d{1,2}(?:\.\d{1,2})?(?![A-Za-z0-9])/g;
+const PATH_VERSION_STRING = /(?<![A-Za-z0-9])v\d+\.\d+\.\d+(?![A-Za-z0-9])/gi;
 /** Third-party names whose versions are legitimate prose. Reticle is deliberately NOT here. */
 const THIRD_PARTY = /\b(React|Vite|Node|TypeScript|Playwright|Chrome|Chromium|Firefox|Safari|Zod|Vitest|ESLint|pnpm|MCP)\b[^v]{0,12}$/i;
-/** Tokens that look like codes but are established technical terms. */
 /** Test-block callees whose first argument is a human-readable description. */
 const TEST_BLOCKS = new Set(['describe', 'it', 'test', 'suite', 'bench']);
 /**
@@ -69,13 +77,11 @@ const ALLOWED = new Set([
     'Q4', // quarters
     'L1',
     'L2', // cache levels
-    // The JavaScript engine. Omitting it made the rule fire on ordinary writing about heap growth and
-    // GC in a JavaScript codebase — the most likely place this rule runs, and the fastest way to get it
-    // switched off. Found by running the rule over directories the linter had never reached.
+    // The JavaScript engine — without it the rule fires on ordinary writing about heap growth and GC.
     'V8',
     'H4',
     'H5',
-    'H6', // heading levels — H1-H3 were already here; stopping at 3 was an oversight, not a rule
+    'H6', // heading levels
 ]);
 export const noInternalTags = createRule({
     name: 'no-internal-tags',
@@ -83,7 +89,7 @@ export const noInternalTags = createRule({
         type: 'problem',
         docs: { description: 'Ban design-doc codes and internal version strings from comments.' },
         schema: [],
-        messages: { internalTag: INTERNAL_TAG_MESSAGE },
+        messages: { internalTag: INTERNAL_TAG_MESSAGE, pathTag: PATH_TAG_MESSAGE },
     },
     defaultOptions: [],
     create(context) {
@@ -109,18 +115,62 @@ export const noInternalTags = createRule({
             }
             return found;
         };
+        /**
+         * Banned tokens in this module's own path, relative to the project root.
+         *
+         * Relative, never absolute: an absolute path runs through directories nobody chose as part of
+         * this codebase (a CI runner's workspace, a developer's home) and flagging those would report a
+         * violation the author cannot fix.
+         */
+        const pathTags = () => {
+            const found = new Set();
+            const filename = context.filename;
+            // `<input>` and `<text>` are what a linter reports for source with no file, e.g. a RuleTester
+            // case or a piped snippet. There is no path to judge.
+            if (filename.startsWith('<'))
+                return found;
+            const rel = relative(context.cwd, filename);
+            // Outside the project root entirely: `relative` climbs out with `..`, and the segments above
+            // the root are not this codebase's to answer for.
+            if (rel.startsWith('..'))
+                return found;
+            const path = rel.split(sep).join('/');
+            // Version FIRST, and its spans claimed, because the tracking-code shape is a prefix of it:
+            // `replay-v2.2.0.ts` matches `v2.2.0` as a version and `v2.2` as a code, and reporting both
+            // would name the same offence twice under two different explanations.
+            const claimed = [];
+            for (const pattern of [PATH_VERSION_STRING, PATH_TRACKING_CODE]) {
+                pattern.lastIndex = 0;
+                for (const match of path.matchAll(pattern)) {
+                    const start = match.index ?? 0;
+                    const end = start + match[0].length;
+                    if (claimed.some((c) => start < c.end && end > c.start))
+                        continue;
+                    const tag = match[0].trim();
+                    claimed.push({ start, end });
+                    if (ALLOWED.has(tag.replace(/[^A-Za-z0-9]/g, '').toUpperCase()))
+                        continue;
+                    found.add(tag);
+                }
+            }
+            return found;
+        };
         return {
-            Program() {
+            Program(node) {
                 for (const comment of context.sourceCode.getAllComments()) {
                     for (const tag of tagsIn(comment.value)) {
                         context.report({ node: comment, messageId: 'internalTag', data: { tag } });
                     }
                 }
+                // Reported on the Program node: the offence is the module's name, which has no node of its
+                // own, and the first line is where a reader will look for it.
+                for (const tag of pathTags()) {
+                    context.report({ node, messageId: 'pathTag', data: { tag } });
+                }
             },
             /**
-             * TEST DESCRIPTIONS are string literals, not comments, so a comment-only rule could not see them
-             * — and the project rule names them explicitly. Seven violations survived a repo-wide cleanup that
-             * claimed to have removed them, precisely because nothing mechanical was looking here.
+             * TEST DESCRIPTIONS are string literals, not comments, so a comment-only rule cannot see them —
+             * and the project rule names them explicitly.
              */
             CallExpression(node) {
                 const callee = node.callee;

package/dist/no-runaway-comment.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rule: no-runaway-comment.
+ *
+ * Caps a single block comment's length.
+ *
+ * Incident: commit `ab26e749` authored a doc comment through an unquoted heredoc, so the shell
+ * evaluated the backticked code spans inside it. `git ls-files` expanded into the file, pasting 407
+ * lines of a private repository's layout — a prod CA cert path, a licence-keypair script, a deploy
+ * secrets template — into `server/src/language/flows/flows.ts`, and deleting every other code span
+ * the comment named. It compiled, it typechecked, it passed every gate, and it reached the published
+ * tarball because `dist` retains comments.
+ *
+ * The cap is the cheapest check that catches it: the accident was 423 lines and the longest genuine
+ * comment in the repository is 45, so nothing legitimate is near the limit.
+ */
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const noRunawayComment: ESLintUtils.RuleModule<"runawayComment", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/no-runaway-comment.js

@@ -0,0 +1,46 @@
+/**
+ * Rule: no-runaway-comment.
+ *
+ * Caps a single block comment's length.
+ *
+ * Incident: commit `ab26e749` authored a doc comment through an unquoted heredoc, so the shell
+ * evaluated the backticked code spans inside it. `git ls-files` expanded into the file, pasting 407
+ * lines of a private repository's layout — a prod CA cert path, a licence-keypair script, a deploy
+ * secrets template — into `server/src/language/flows/flows.ts`, and deleting every other code span
+ * the comment named. It compiled, it typechecked, it passed every gate, and it reached the published
+ * tarball because `dist` retains comments.
+ *
+ * The cap is the cheapest check that catches it: the accident was 423 lines and the longest genuine
+ * comment in the repository is 45, so nothing legitimate is near the limit.
+ */
+import { AST_TOKEN_TYPES, ESLintUtils } from '@typescript-eslint/utils';
+import { DOCS_URL_ROOT, MAX_COMMENT_LINES, RUNAWAY_COMMENT_MESSAGE } from './constants.js';
+const createRule = ESLintUtils.RuleCreator((name) => `${DOCS_URL_ROOT}#${name}`);
+export const noRunawayComment = createRule({
+    name: 'no-runaway-comment',
+    meta: {
+        type: 'problem',
+        docs: { description: 'Cap the length of a single block comment.' },
+        schema: [],
+        messages: { runawayComment: RUNAWAY_COMMENT_MESSAGE },
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            Program() {
+                for (const comment of context.sourceCode.getAllComments()) {
+                    if (AST_TOKEN_TYPES.Block !== comment.type)
+                        continue;
+                    const lines = comment.loc.end.line - comment.loc.start.line + 1;
+                    if (lines <= MAX_COMMENT_LINES)
+                        continue;
+                    context.report({
+                        loc: comment.loc,
+                        messageId: 'runawayComment',
+                        data: { lines: String(lines), max: String(MAX_COMMENT_LINES) },
+                    });
+                }
+            },
+        };
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/eslint-plugin",
-  "version": "2.13.1",
+  "version": "3.1.0",
   "description": "Reticle ESLint plugin — keeps the signal layer self-enforcing (mutation-without-signal).",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reticlehq/reticle.git",
-    "directory": "packages/eslint-plugin"
+    "directory": "adapters/lint/eslint"
   },
   "homepage": "https://github.com/reticlehq/reticle#readme",
   "bugs": "https://github.com/reticlehq/reticle/issues",
@@ -49,7 +49,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsc -b",
+    "build": "tsc -b && tsc-alias",
     "typecheck": "tsc -b",
     "lint": "eslint src",
     "test:unit": "vitest run src --passWithNoTests"