@reticlehq/eslint-plugin 2.14.0 → 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,6 +1,7 @@
 /** @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;
@@ -8,6 +9,9 @@ export declare const rules: {
     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;
+    };
 };
 declare const plugin: {
     meta: {
@@ -20,8 +24,11 @@ declare const plugin: {
         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

@@ -5,15 +5,8 @@
  * 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.
  *
- * Those four surfaces are the ones the project rule names, and the rule enforced two of them. A path
- * is the first thing a reader meets, before any comment, so `n5-ring-buffer.ts` is the shape this
- * exists to prevent stated in the loudest available place.
- *
- * 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;

package/dist/no-internal-tags.js

@@ -5,15 +5,8 @@
  * 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.
  *
- * Those four surfaces are the ones the project rule names, and the rule enforced two of them. A path
- * is the first thing a reader meets, before any comment, so `n5-ring-buffer.ts` is the shape this
- * exists to prevent stated in the loudest available place.
- *
- * 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;
@@ -28,39 +21,37 @@ 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.";
 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.";
-/** `(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;
 /**
- * `§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 a code that would read `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 fail them, because each needs a non-alphanumeric on both
- * sides of a letters-then-digits token.
+ * 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']);
 /**
@@ -86,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',
@@ -180,9 +169,8 @@ export const noInternalTags = createRule({
                 }
             },
             /**
-             * 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.14.0",
+  "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"