@sarj/eslint-plugin 12.0.0 → 13.1.0

package/dist/index.js

@@ -7,7 +7,193 @@ var REPO_BLOB = "https://github.com/sarj-ai/standards/blob/main";
 var TESTS_DIR = "packages/typescript/tests/rules";
 var examplesPath = (name) => `${TESTS_DIR}/${name}.test.ts`;
 var examplesUrl = (name) => `${REPO_BLOB}/${examplesPath(name)}`;
-var createRule = ESLintUtils.RuleCreator(examplesUrl);
+var KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+var MAX_SUMMARY_LENGTH = 160;
+var eslintCreateRule = ESLintUtils.RuleCreator(examplesUrl);
+function createRule(config) {
+  const { documentation, ...eslintConfig } = config;
+  const rule = eslintCreateRule(eslintConfig);
+  if (documentation !== void 0) {
+    Object.defineProperty(rule, "documentation", {
+      configurable: false,
+      enumerable: false,
+      value: nativeSpec(eslintConfig, documentation),
+      writable: false
+    });
+  }
+  return rule;
+}
+function documentationWarnings(rules2) {
+  return Object.entries(rules2).filter(([, rule]) => rule.documentation === void 0).map(([name]) => `${name}: source-owned documentation has not been migrated`).sort();
+}
+function publicDocumentation(rules2) {
+  const missing = documentationWarnings(rules2);
+  if (missing.length > 0) {
+    throw new TypeError(`cannot publish an incomplete rule catalog:
+${missing.join("\n")}`);
+  }
+  return Object.entries(rules2).sort(([left], [right]) => left.localeCompare(right)).map(([ruleId, rule]) => {
+    const spec = rule.documentation;
+    if (spec === void 0 || spec.ruleId !== ruleId) {
+      throw new TypeError(`${ruleId}: native documentation identity mismatch`);
+    }
+    return deepFreeze({
+      engine: spec.engine,
+      ruleId: spec.ruleId,
+      code: spec.code,
+      summary: spec.summary,
+      rationale: spec.rationale,
+      remediation: spec.remediation,
+      category: spec.category,
+      languages: spec.languages,
+      autofix: spec.autofix,
+      aliases: spec.aliases,
+      limitations: spec.limitations,
+      filePatterns: spec.filePatterns,
+      references: spec.references,
+      since: spec.since,
+      messageIds: spec.messageIds,
+      optionsSchema: spec.optionsSchema,
+      examples: spec.publicExamples.map(publicExample)
+    });
+  });
+}
+function publicExample(example) {
+  return {
+    id: example.id,
+    title: example.title,
+    outcome: example.outcome,
+    files: example.files.map(publicFile),
+    focusPath: example.focusPath,
+    expectedCount: example.expectedCount,
+    fixedFiles: (example.fixedFiles ?? []).map(publicFile)
+  };
+}
+function publicFile(file) {
+  return { path: file.path, source: file.source };
+}
+function nativeSpec(config, documentation) {
+  const { name, meta: meta2 } = config;
+  if (!KEBAB_CASE.test(name)) throw new TypeError("rule ID must be lowercase kebab-case");
+  for (const [label, value] of [
+    ["summary", documentation.summary],
+    ["rationale", documentation.rationale],
+    ["remediation", documentation.remediation]
+  ]) {
+    if (value.trim().length === 0) throw new TypeError(`rule ${label} must not be empty`);
+  }
+  if (documentation.summary.includes("\n") || documentation.summary.length > MAX_SUMMARY_LENGTH) {
+    throw new TypeError(`rule summary must be one line of at most ${MAX_SUMMARY_LENGTH} characters`);
+  }
+  if (documentation.summary !== meta2.docs?.description) {
+    throw new TypeError(`${name}: ESLint description must equal the authored documentation summary`);
+  }
+  const aliases = [...documentation.aliases ?? []];
+  assertUnique(aliases, "rule aliases");
+  if (aliases.some((alias) => !KEBAB_CASE.test(alias) || alias === name)) {
+    throw new TypeError("rule aliases must be historical lowercase kebab-case IDs");
+  }
+  const limitations = [...documentation.limitations ?? []];
+  const filePatterns = [...documentation.filePatterns ?? []];
+  if ([...limitations, ...filePatterns].some((value) => value.trim().length === 0)) {
+    throw new TypeError("rule limitations and file patterns must not be empty");
+  }
+  const references = [...documentation.references ?? []];
+  if (references.some((reference) => !reference.startsWith("https://"))) {
+    throw new TypeError("rule references must use https");
+  }
+  const examples = [...documentation.examples ?? []];
+  examples.forEach(validateExample);
+  assertUnique(examples.map((example) => example.id), "rule example IDs");
+  const publicOutcomes = new Set(examples.filter((example) => example.public === true).map((example) => example.outcome));
+  if (publicOutcomes.size > 0 && !(publicOutcomes.has("match") && publicOutcomes.has("no-match"))) {
+    throw new TypeError("published rule examples must include matching and non-matching cases");
+  }
+  const messageIds = Object.keys(meta2.messages).sort();
+  const schema = optionsSchema(meta2.schema);
+  const spec = {
+    engine: "eslint",
+    ruleId: name,
+    code: null,
+    key: `eslint:${name}`,
+    summary: documentation.summary,
+    rationale: documentation.rationale,
+    remediation: documentation.remediation,
+    category: documentation.category,
+    languages: [...documentation.languages ?? ["typescript"]],
+    autofix: documentation.autofix ?? "none",
+    aliases,
+    limitations,
+    filePatterns,
+    references,
+    since: documentation.since ?? null,
+    examples,
+    publicExamples: examples.filter((example) => example.public === true),
+    messageIds,
+    optionsSchema: schema
+  };
+  return deepFreeze(spec);
+}
+function optionsSchema(value) {
+  if (!Array.isArray(value)) return isObject(value) ? value : null;
+  const items = value;
+  if (items.length === 0) return null;
+  const [only] = items;
+  return items.length === 1 && isObject(only) ? only : { type: "array", items };
+}
+function isObject(value) {
+  return value !== null && typeof value === "object";
+}
+function validateExample(example) {
+  if (!KEBAB_CASE.test(example.id)) {
+    throw new TypeError("example ID must be lowercase kebab-case");
+  }
+  if (example.title.trim().length === 0) {
+    throw new TypeError("example title must not be empty");
+  }
+  if (!Number.isSafeInteger(example.expectedCount) || example.expectedCount < 0) {
+    throw new TypeError("example expected count must be a non-negative integer");
+  }
+  if (example.outcome === "match" && example.expectedCount < 1) {
+    throw new TypeError("matching examples must expect at least one diagnostic");
+  }
+  if (example.outcome === "no-match" && example.expectedCount !== 0) {
+    throw new TypeError("non-matching examples must expect zero diagnostics");
+  }
+  if (example.files.length === 0) {
+    throw new TypeError("example files must not be empty");
+  }
+  const paths = example.files.map((file) => file.path);
+  assertUnique(paths, "example file paths");
+  for (const file of [...example.files, ...example.fixedFiles ?? []]) {
+    assertSafeRelativePath(file.path, "example file path");
+    if (file.source.length === 0) {
+      throw new TypeError("example file source must not be empty");
+    }
+  }
+  assertSafeRelativePath(example.focusPath, "example focus path");
+  if (!paths.includes(example.focusPath)) {
+    throw new TypeError("example focus path must name one example file");
+  }
+  assertUnique((example.fixedFiles ?? []).map((file) => file.path), "fixed example file paths");
+}
+function assertSafeRelativePath(path, label) {
+  if (path.length === 0 || path.startsWith("/") || path.startsWith("\\") || /^[A-Za-z]:[\\/]/u.test(path) || path.split(/[\\/]/u).includes("..")) {
+    throw new TypeError(`${label} must be a safe relative path`);
+  }
+}
+function assertUnique(values, label) {
+  if (new Set(values).size !== values.length) {
+    throw new TypeError(`${label} must be unique`);
+  }
+}
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
 
 // src/rules/_paths.ts
 var SCRIPT_FILE_RE = /(?:^|[\\/])scripts[\\/]|\.mjs$/;
@@ -96,6 +282,35 @@ function isScriptFile(filename) {
 }
 
 // src/rules/enforce-file-structure.ts
+var enforceFileStructureDocumentation = {
+  summary: "Require imports before body statements and require `use server` to be the first statement.",
+  rationale: "Interleaved imports obscure module dependencies, while a displaced `use server` string is not an active directive.",
+  remediation: "Move `use server` to the first statement when present, then place imports before declarations and executable statements.",
+  category: "correctness",
+  limitations: [
+    "The rule skips tests and generated files, treats re-exports as neutral, and does not order body declarations."
+  ],
+  examples: [
+    {
+      id: "imports-first",
+      title: "Imports precede module declarations",
+      outcome: "no-match",
+      files: [{ path: "src/component.ts", source: "import { z } from 'zod';\nexport const schema = z.string();" }],
+      focusPath: "src/component.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "import-after-declaration",
+      title: "An import follows a module declaration",
+      outcome: "match",
+      files: [{ path: "src/component.ts", source: "export const x = 1;\nimport { z } from 'zod';" }],
+      focusPath: "src/component.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var classifyStatement = (statement) => {
   switch (statement.type) {
     case AST_NODE_TYPES.ImportDeclaration:
@@ -117,10 +332,11 @@ var isUseServerDirective = (statement) => {
 };
 var enforce_file_structure_default = createRule({
   name: "enforce-file-structure",
+  documentation: enforceFileStructureDocumentation,
   meta: {
     type: "suggestion",
     docs: {
-      description: "Require `import` statements to come first, then allow step-down ordering (public API first, private helpers below) for the rest of the file. Exported statements are classified by WHAT they export \u2014 an exported interface is a declaration, an exported function is a function \u2014 so a public exported function followed by a private helper, or an exported interface among declarations, is allowed. Re-exports (`export { \u2026 } from`, `export *`, `export { \u2026 }`) are a neutral group, so generated namespace barrels pass. When a module contains a `use server` directive, it must be the first statement in the file."
+      description: "Require imports before body statements and require `use server` to be the first statement."
     },
     schema: [],
     messages: {
@@ -191,6 +407,41 @@ var OMITTED_AST_KEYS = /* @__PURE__ */ new Set([
 var MIN_STATEMENTS = 3;
 var MAX_NORMALIZED_STRING_LENGTH = 64;
 var TEST_MODULES = /* @__PURE__ */ new Set(["@jest/globals", "@playwright/test", "bun:test", "node:test", "vitest"]);
+var duplicateTestBodyDocumentation = {
+  summary: "Disallow substantial sibling tests with the same body shape; express their differing inputs as a parameterized case table.",
+  rationale: "Copy-pasted test bodies hide the cases that differ and allow equivalent assertions to drift independently.",
+  remediation: "Move the varying inputs and expected values into a case table consumed by `test.each(...)` or `it.each(...)`.",
+  category: "testing",
+  limitations: [
+    "The rule compares substantial sibling tests within one suite and skips inline snapshots and materially different comments."
+  ],
+  examples: [
+    {
+      id: "parameterized-cases",
+      title: "A case table shares one test body",
+      outcome: "no-match",
+      files: [{
+        path: "src/user.test.ts",
+        source: "test.each(['a', 'b'])('parses %s', (value) => { const x = parse(value); expect(x.ok).toBe(true); expect(x.value).toBe(value); });"
+      }],
+      focusPath: "src/user.test.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "copied-sibling-tests",
+      title: "Sibling tests repeat the same body",
+      outcome: "match",
+      files: [{
+        path: "src/user.test.ts",
+        source: "test('accepts a', () => { const result = parse('a'); expect(result.ok).toBe(true); expect(result.value).toBe('a'); });\ntest('accepts b', () => { const result = parse('b'); expect(result.ok).toBe(true); expect(result.value).toBe('b'); });"
+      }],
+      focusPath: "src/user.test.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 function rootIdentifier(callee) {
   if (callee.type === AST_NODE_TYPES2.Identifier) return callee;
   if (callee.type === AST_NODE_TYPES2.MemberExpression) return rootIdentifier(callee.object);
@@ -306,6 +557,7 @@ function normalizedLiteral(node) {
 }
 var duplicate_test_body_default = createRule({
   name: "duplicate-test-body",
+  documentation: duplicateTestBodyDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -372,12 +624,43 @@ var duplicate_test_body_default = createRule({
 
 // src/rules/no-async-callback-in-wait-for.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES3 } from "@typescript-eslint/utils";
+var noAsyncCallbackInWaitForDocumentation = {
+  summary: "Disallow async callbacks in `waitFor` to prevent swallowed promise rejections.",
+  rationale: "`waitFor` retries synchronous assertions; an async callback changes that contract and can hide a rejected assertion promise.",
+  remediation: "Remove `async` and keep the assertions inside `waitFor` synchronous.",
+  category: "testing",
+  aliases: ["no-async-callback-in-waitfor"],
+  limitations: [
+    "The rule checks inline first-argument callbacks to bare or non-computed `.waitFor` calls in test files."
+  ],
+  examples: [
+    {
+      id: "synchronous-wait-for-callback",
+      title: "waitFor retries a synchronous assertion",
+      outcome: "no-match",
+      files: [{ path: "src/component.test.ts", source: "it('works', async () => { await waitFor(() => expect(foo).toBe(true)); });" }],
+      focusPath: "src/component.test.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "async-wait-for-callback",
+      title: "waitFor receives an async callback",
+      outcome: "match",
+      files: [{ path: "src/component.test.ts", source: "it('fails', async () => { await waitFor(async () => expect(foo).toBe(true)); });" }],
+      focusPath: "src/component.test.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var isWaitForCallee = (callee) => {
   if (callee.type === AST_NODE_TYPES3.Identifier) return callee.name === "waitFor";
   return callee.type === AST_NODE_TYPES3.MemberExpression && !callee.computed && callee.property.type === AST_NODE_TYPES3.Identifier && callee.property.name === "waitFor";
 };
 var no_async_callback_in_wait_for_default = createRule({
   name: "no-async-callback-in-wait-for",
+  documentation: noAsyncCallbackInWaitForDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -410,6 +693,35 @@ var no_async_callback_in_wait_for_default = createRule({
 
 // src/rules/no-client-side-data-fetching.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES4 } from "@typescript-eslint/utils";
+var noClientSideDataFetchingDocumentation = {
+  summary: "Disallow direct data fetching inside `useEffect` or `useLayoutEffect`.",
+  rationale: "Effect-driven reads begin after rendering and can create request waterfalls, duplicate fetches, and loading-state layout shifts.",
+  remediation: "Fetch in a React Server Component or Server Action, or use a client cache such as SWR or React Query.",
+  category: "performance",
+  limitations: [
+    "The rule recognizes common fetch clients syntactically and exempts analytics endpoints and non-GET `fetch` calls."
+  ],
+  examples: [
+    {
+      id: "effect-without-fetch",
+      title: "An effect performs no data request",
+      outcome: "no-match",
+      files: [{ path: "src/users.tsx", source: "import { useEffect } from 'react'; useEffect(() => { console.log('mounted'); }, []);" }],
+      focusPath: "src/users.tsx",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "fetch-inside-effect",
+      title: "An effect starts a data request",
+      outcome: "match",
+      files: [{ path: "src/users.tsx", source: "useEffect(() => { fetch('/api/users'); }, []);" }],
+      focusPath: "src/users.tsx",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var FETCH_LIBS = /* @__PURE__ */ new Set(["axios", "ky", "superagent"]);
 var HTTP_METHOD_NAMES = /* @__PURE__ */ new Set([
   "get",
@@ -508,10 +820,11 @@ function extractUrlString(node) {
 }
 var no_client_side_data_fetching_default = createRule({
   name: "no-client-side-data-fetching",
+  documentation: noClientSideDataFetchingDocumentation,
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow data fetching inside `useEffect` / `useLayoutEffect`; prefer React Server Components, Server Actions, or a client-side cache (SWR / React Query)."
+      description: "Disallow direct data fetching inside `useEffect` or `useLayoutEffect`."
     },
     schema: [],
     messages: {
@@ -732,6 +1045,35 @@ function headTokens(source) {
 }
 
 // src/rules/no-comment-cruft.ts
+var noCommentCruftDocumentation = {
+  summary: "Flag commented-out code, section-banner comments, and leading file-header comment preambles.",
+  rationale: "Decorative, narrated, or dead-code comments obscure the constraints and rationale that comments should preserve.",
+  remediation: "Delete dead code and narration; express boundaries with named code and retain only comments that explain constraints or intent.",
+  category: "maintainability",
+  limitations: [
+    "The rule skips generated files and conservatively preserves prose, issue references, licenses, examples, and tool directives."
+  ],
+  examples: [
+    {
+      id: "rationale-comment",
+      title: "A comment explains why retry is required",
+      outcome: "no-match",
+      files: [{ path: "src/retry.ts", source: "// retry because the upstream API is flaky\nconst x = retry();" }],
+      focusPath: "src/retry.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "region-banner",
+      title: "A region comment decorates a code boundary",
+      outcome: "match",
+      files: [{ path: "src/helpers.ts", source: "const x = 1;\n// region helpers\nconst y = 2;" }],
+      focusPath: "src/helpers.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var LEADING_PREAMBLE_MIN = 4;
 var WALL_MIN_STATEMENTS = 4;
 var WALL_MIN_COMMENTS = 3;
@@ -757,6 +1099,7 @@ var STEP_NARRATION_RE = /^(?:first(?:ly)?|second(?:ly)?|third(?:ly)?|then|next|a
 var META_COMMENTARY_RE = /\b(?:keeping (?:it|this) simple|could be (?:refactored|improved|cleaned up|simplified)|refactor(?:ed|ing)? (?:later|this)|not sure (?:if|whether|why|how)|quick[- ](?:and[- ]dirty|fix)|(?:a |bit of a )?hacky|is a hack|temporary (?:solution|workaround|fix|hack)|revisit (?:this|later|below)|clean (?:this|it) up|not ideal|placeholder for now)\b/i;
 var EDITORIAL_PLACEHOLDER_RE = /^(?:(?:implementation omitted|existing code here|your code here|rest of (?:the )?code (?:is )?unchanged|same as above|placeholder implementation)\s*[.!]?|in a real (?:app(?:lication)?|implementation),?\s+(?:this|we|you|it)\s+would\s+(?:call|fetch|generate|download|persist|save|send|store|write)\b[^,;]*[.!]?)$/i;
 var FOR_NOW_RE = /\bfor now\b/i;
+var JSDOC_DEBT_RE = /^@?(?:todo|fixme)\b/i;
 var DEFERRAL_STOPWORDS = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -885,6 +1228,7 @@ var DIAGRAM_ARROW_RE = /[-=~]{2,}>|<[-=~]{2,}/;
 var CODE_KEYWORD_RE = /^(import |export |const |let |var |function\b|class |interface |type \w|enum |return\b|throw |await |async |if\s*\(|for\s*\(|while\s*\(|switch\s*\(|new |console\.)/;
 var CODE_TAIL_RE = /[;{}()]\s*$|=>\s*$|,\s*$/;
 var ASSIGN_RE = /^[A-Za-z_$][\w.$[\]]*\s*(?:=(?![=>])|\+=|-=|\*=)\s*\S.*[;)}\]]\s*$/;
+var DECLARATION_RE = /^(?:export\s+)?(?:declare\s+)?(?:const|let|var)\s+[A-Za-z_$][\w$]*(?:\s*:\s*[^=]+)?\s*=\s*(?:[A-Za-z_$][\w.$]*(?:\s*\(|\s*$)|["'`]|\[|\{|\d|true\b|false\b|null\b|undefined\b|new\b|await\b|async\b|function\b|class\b)/;
 var CALL_RE = /^[A-Za-z_$][\w.$]*\([^)]*\)\s*;?\s*$/;
 var ASSERTION_CODE_RE = /^(?:await\s+)?(?:expect(?:TypeOf)?|assert(?:\.\w+)?)\s*\(/;
 var HTTP_CONTRACT_RE = /\b(?:GET|HEAD|OPTIONS|PATCH|POST|PUT|DELETE)\s+(?:https?:\/\/|\/|\{[A-Za-z_$])/;
@@ -912,6 +1256,7 @@ function looksLikeCode(text, allowCall = true) {
   if (!t) return false;
   if (PROSE_ASSIGNMENT_RE.test(t)) return false;
   if (CODE_KEYWORD_RE.test(t) && CODE_TAIL_RE.test(t)) return true;
+  if (DECLARATION_RE.test(t)) return true;
   if (ASSIGN_RE.test(t)) return true;
   if (ASSERTION_CODE_RE.test(t)) return true;
   return allowCall && CALL_RE.test(t);
@@ -1100,6 +1445,7 @@ function hasCommentedOutCode(texts, precedingProse, allowCall) {
 }
 var no_comment_cruft_default = createRule({
   name: "no-comment-cruft",
+  documentation: noCommentCruftDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -1240,6 +1586,11 @@ var no_comment_cruft_default = createRule({
           }
           if (wallMembers.has(comment)) continue;
           if (isJsDoc(comment)) {
+            const debt = comment.value.split("\n").map(stripCommentMarker).find((line) => JSDOC_DEBT_RE.test(line));
+            if (debt !== void 0 && !runCitesAReference(comments, i)) {
+              context.report({ node: comment, messageId: "untrackedTodo" });
+              continue;
+            }
             if (isStandalone(comment) && isSectionJsDoc(comment)) {
               context.report({ node: comment, messageId: "sectionBanner" });
             }
@@ -1306,6 +1657,35 @@ var no_comment_cruft_default = createRule({
 
 // src/rules/no-conditional-in-test.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES7 } from "@typescript-eslint/utils";
+var noConditionalInTestDocumentation = {
+  summary: "Disallow test conditionals that can skip a runtime assertion or exit the test before one runs.",
+  rationale: "A branch can skip the assertion that gives a test its meaning, allowing unexpected inputs to pass silently.",
+  remediation: "Split each path into a separate test or use a parameterized case table with unconditional assertions.",
+  category: "testing",
+  limitations: [
+    "The rule exempts lifecycle hooks, nested helpers, and narrow guards whose outcome is pinned by a preceding assertion."
+  ],
+  examples: [
+    {
+      id: "unconditional-assertion",
+      title: "A test always executes its assertion",
+      outcome: "no-match",
+      files: [{ path: "src/component.test.ts", source: "it('works', () => { expect(1).toBe(1); });" }],
+      focusPath: "src/component.test.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "conditional-assertion",
+      title: "A branch can skip the assertion",
+      outcome: "match",
+      files: [{ path: "src/component.test.ts", source: "it('fails with if', () => { if (ready) { expect(value).toBe(1); } });" }],
+      focusPath: "src/component.test.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var TEST_CALLERS2 = /* @__PURE__ */ new Set(["it", "test"]);
 var NON_TEST_MEMBERS = /* @__PURE__ */ new Set([
   "afterAll",
@@ -1586,6 +1966,7 @@ function isShortCircuitedAssertion(node) {
 }
 var no_conditional_in_test_default = createRule({
   name: "no-conditional-in-test",
+  documentation: noConditionalInTestDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -1633,6 +2014,35 @@ var no_conditional_in_test_default = createRule({
 
 // src/rules/no-cors-wildcard-with-credentials.ts
 import "@typescript-eslint/utils";
+var noCorsWildcardWithCredentialsDocumentation = {
+  summary: "Disallow wildcard CORS origins when credentials are enabled.",
+  rationale: "Reflecting every origin while allowing credentials can let an untrusted site read authenticated cross-origin responses.",
+  remediation: "Enumerate the trusted origins that may receive credentialed responses.",
+  category: "security",
+  limitations: [
+    "The rule detects literal CORS option and header combinations within the same syntactic scope; it does not resolve runtime configuration."
+  ],
+  examples: [
+    {
+      id: "trusted-origin-with-credentials",
+      title: "Credentials are limited to a trusted origin",
+      outcome: "no-match",
+      files: [{ path: "src/server.ts", source: "app.use(cors({ origin: 'https://app.example.com', credentials: true }));" }],
+      focusPath: "src/server.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "wildcard-origin-with-credentials",
+      title: "Credentials are enabled for every origin",
+      outcome: "match",
+      files: [{ path: "src/server.ts", source: "app.use(cors({ origin: '*', credentials: true }));" }],
+      focusPath: "src/server.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var ACAO_HEADER = "access-control-allow-origin";
 var ACAC_HEADER = "access-control-allow-credentials";
 var HEADER_SET_METHODS = /* @__PURE__ */ new Set(["setheader", "set", "append"]);
@@ -1776,10 +2186,11 @@ function enclosingScope(node) {
 }
 var no_cors_wildcard_with_credentials_default = createRule({
   name: "no-cors-wildcard-with-credentials",
+  documentation: noCorsWildcardWithCredentialsDocumentation,
   meta: {
     type: "problem",
     docs: {
-      description: 'Disallow CORS that reflects any Origin (`"*"`) while allowing credentials; any site could then read authenticated responses. Enumerate explicit trusted origins instead.'
+      description: "Disallow wildcard CORS origins when credentials are enabled."
     },
     schema: [],
     messages: {
@@ -1986,6 +2397,35 @@ function createSqlListener(handler) {
 }
 
 // src/rules/no-dynamic-sql.ts
+var noDynamicSqlDocumentation = {
+  summary: "Disallow runtime interpolation or concatenation in SQL passed to statement-execution methods.",
+  rationale: "Embedding runtime values in SQL bypasses driver parameterization and can introduce injection defects or unstable query plans.",
+  remediation: "Use SQL placeholders and pass runtime values through the driver's binding API.",
+  category: "security",
+  limitations: [
+    "The rule recognizes SQL by syntax and configured method names; static fragments and parameterizing tagged templates are exempt."
+  ],
+  examples: [
+    {
+      id: "bound-sql-parameter",
+      title: "A runtime value is bound separately",
+      outcome: "no-match",
+      files: [{ path: "src/users.ts", source: "db.prepare('select * from users where id = ?').bind(userId);" }],
+      focusPath: "src/users.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "interpolated-sql-value",
+      title: "A runtime value is interpolated into SQL",
+      outcome: "match",
+      files: [{ path: "src/users.ts", source: "db.prepare(`select * from users where id = '${userId}'`);" }],
+      focusPath: "src/users.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var DEFAULT_METHODS = ["prepare", "exec", "query"];
 var CONSTANT_CASE_RE = /^[A-Z][A-Z0-9_]*$/;
 function isStaticFragment(expression) {
@@ -2053,10 +2493,11 @@ function statementMethodName(node, methods) {
 }
 var no_dynamic_sql_default = createRule({
   name: "no-dynamic-sql",
+  documentation: noDynamicSqlDocumentation,
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow interpolating or concatenating a runtime value into a SQL statement passed to `prepare`/`exec`/`query`; use a placeholder and bind the value."
+      description: "Disallow runtime interpolation or concatenation in SQL passed to statement-execution methods."
     },
     schema: [
       {
@@ -2103,6 +2544,32 @@ var no_dynamic_sql_default = createRule({
 
 // src/rules/no-enum.ts
 import "@typescript-eslint/utils";
+var noEnumDocumentation = {
+  summary: "Disallow TypeScript `enum`; use string-literal unions or `as const` objects instead.",
+  rationale: "TypeScript enums emit runtime objects and numeric enums accept values outside their declared members, adding behavior where a type-only model is sufficient.",
+  remediation: "Replace the enum with a string-literal union or an `as const` object and derive its value type from that object.",
+  category: "maintainability",
+  examples: [
+    {
+      id: "string-literal-union",
+      title: "A string-literal union has no emitted runtime enum",
+      outcome: "no-match",
+      files: [{ path: "src/status.ts", source: 'type Status = "active" | "inactive";' }],
+      focusPath: "src/status.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "numeric-enum",
+      title: "A numeric enum emits a mutable runtime object",
+      outcome: "match",
+      files: [{ path: "src/status.ts", source: "enum Status { Active, Inactive }" }],
+      focusPath: "src/status.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 function matchesAnyPattern(filename, patterns) {
   for (const pattern of patterns) {
     const regexSource = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "::DOUBLESTAR::").replace(/\*/g, "[^/\\\\]*").replace(/::DOUBLESTAR::/g, ".*");
@@ -2114,6 +2581,7 @@ function matchesAnyPattern(filename, patterns) {
 }
 var no_enum_default = createRule({
   name: "no-enum",
+  documentation: noEnumDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -2159,6 +2627,41 @@ var no_enum_default = createRule({
 
 // src/rules/no-fat-try-blocks.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES10 } from "@typescript-eslint/utils";
+var noFatTryBlocksDocumentation = {
+  summary: "Disallow `try` blocks containing more than three top-level operations that can throw.",
+  rationale: "A broad `try` block obscures which operation failed and encourages one catch clause to recover from unrelated errors.",
+  remediation: "Keep only the operations that share one recovery policy inside the `try` block and move other work outside it.",
+  category: "correctness",
+  limitations: [
+    "The rule uses syntax to identify throwing operations and exempts generated files, finally blocks, rethrows, and terminal error boundaries."
+  ],
+  examples: [
+    {
+      id: "focused-try-block",
+      title: "A try block contains three throwing operations",
+      outcome: "no-match",
+      files: [{
+        path: "src/load.ts",
+        source: "function f() { try { const a = one(); const b = two(); const c = three(); } catch (error) { handle(error); } finish(); }"
+      }],
+      focusPath: "src/load.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "broad-try-block",
+      title: "A try block contains four throwing operations",
+      outcome: "match",
+      files: [{
+        path: "src/load.ts",
+        source: "function f() { try { const a = one(); const b = two(); const c = three(); const d = four(); } catch (error) { handle(error); } finish(); }"
+      }],
+      focusPath: "src/load.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var MAX_TRY_BODY_STATEMENTS = 3;
 var NESTED_FUNCTION_TYPES = /* @__PURE__ */ new Set([
   AST_NODE_TYPES10.FunctionDeclaration,
@@ -2494,10 +2997,11 @@ var handlerReturnsSuccessShaped = (handler) => subtreeMatches2(
 );
 var no_fat_try_blocks_default = createRule({
   name: "no-fat-try-blocks",
+  documentation: noFatTryBlocksDocumentation,
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow `try` blocks with more than three top-level statements that can throw \u2014 isolate the throwing statement and move non-throwing work outside."
+      description: "Disallow `try` blocks containing more than three top-level operations that can throw."
     },
     schema: [],
     messages: {
@@ -2538,6 +3042,38 @@ var no_fat_try_blocks_default = createRule({
 
 // src/rules/no-hand-rolled-sleep.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES11 } from "@typescript-eslint/utils";
+var noHandRolledSleepDocumentation = {
+  summary: "Disallow uncancellable promisified timers and timeout arms.",
+  rationale: "A timer that outlives an aborted operation or a lost promise race retains work and can keep the process alive until it fires.",
+  remediation: "Use `node:timers/promises` with an abort signal for delays, or pass `AbortSignal.timeout(...)` to the timed operation.",
+  category: "correctness",
+  limitations: [
+    "The rule skips tests, scripts, generated files, and client modules by default, and supports explicit path exemptions."
+  ],
+  examples: [
+    {
+      id: "cancellable-node-timer",
+      title: "A standard-library timer accepts an abort signal",
+      outcome: "no-match",
+      files: [{
+        path: "src/lib/queue.ts",
+        source: 'import { setTimeout as sleep } from "node:timers/promises";\nawait sleep(500, undefined, { signal });'
+      }],
+      focusPath: "src/lib/queue.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "uncancellable-sleep",
+      title: "A Promise wraps a timer without cancellation",
+      outcome: "match",
+      files: [{ path: "src/lib/queue.ts", source: "await new Promise((resolve) => setTimeout(resolve, 500));" }],
+      focusPath: "src/lib/queue.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var GLOBAL_OBJECTS = /* @__PURE__ */ new Set([
   "globalThis",
   "window",
@@ -2617,10 +3153,11 @@ function isRaceArm(node) {
 }
 var no_hand_rolled_sleep_default = createRule({
   name: "no-hand-rolled-sleep",
+  documentation: noHandRolledSleepDocumentation,
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow hand-rolled promisified timers (`new Promise((r) => setTimeout(r, ms))`) and hand-rolled `Promise.race` timeout arms; the stdlib forms are cancellable, these are not."
+      description: "Disallow uncancellable promisified timers and timeout arms."
     },
     schema: [
       {
@@ -2713,6 +3250,17 @@ var no_hand_rolled_sleep_default = createRule({
 
 // src/rules/no-hand-rolled-spinner.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES12 } from "@typescript-eslint/utils";
+var noHandRolledSpinnerDocumentation = {
+  summary: "Disallow intrinsic elements styled as Tailwind border-ring spinners outside the design-system implementation.",
+  rationale: "One-off loading indicators duplicate a shared primitive and let accessibility and styling diverge.",
+  remediation: "Render the design-system Spinner component instead.",
+  category: "maintainability",
+  limitations: ["Only static className values on div and span elements are inspected."],
+  examples: [
+    { id: "design-system-spinner", title: "Use the shared spinner", outcome: "no-match", files: [{ path: "src/loading-state.tsx", source: '<Spinner className="size-4" />' }], focusPath: "src/loading-state.tsx", expectedCount: 0, public: true },
+    { id: "border-ring-spinner", title: "Do not rebuild a spinner", outcome: "match", files: [{ path: "src/loading-state.tsx", source: '<div className="size-4 animate-spin rounded-full border-2 border-t-transparent" />' }], focusPath: "src/loading-state.tsx", expectedCount: 1, public: true }
+  ]
+};
 var DESIGN_SYSTEM_PATH = /(?:^|[/\\])components[/\\]ui[/\\]/u;
 var BORDER_WIDTH = /^border(?:-[0-9]+)?$/u;
 var TRANSPARENT_EDGE = /^border-[trbl]-transparent$/u;
@@ -2728,6 +3276,7 @@ function staticClassName(attribute) {
 }
 var no_hand_rolled_spinner_default = createRule({
   name: "no-hand-rolled-spinner",
+  documentation: noHandRolledSpinnerDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -2765,6 +3314,17 @@ var no_hand_rolled_spinner_default = createRule({
 
 // src/rules/no-insecure-random-id.ts
 import "@typescript-eslint/utils";
+var noInsecureRandomIdDocumentation = {
+  summary: "Disallow using `Math.random()` to generate identifiers, tokens, or secrets; use `crypto.randomUUID()` or `crypto.getRandomValues(...)` instead.",
+  rationale: "Math.random is predictable and lacks the entropy required for security-sensitive values.",
+  remediation: "Generate the value with crypto.randomUUID or crypto.getRandomValues.",
+  category: "security",
+  limitations: ["Ambiguous identifiers and test files are excluded to avoid flagging sampling and fixture data."],
+  examples: [
+    { id: "cryptographic-id", title: "Use the Web Crypto API", outcome: "no-match", files: [{ path: "src/session.ts", source: "const sessionToken = crypto.randomUUID();" }], focusPath: "src/session.ts", expectedCount: 0, public: true },
+    { id: "predictable-token", title: "Do not derive a token from Math.random", outcome: "match", files: [{ path: "src/session.ts", source: "const sessionToken = Math.random();" }], focusPath: "src/session.ts", expectedCount: 1, public: true }
+  ]
+};
 var STRONG_SECURITY_PATTERN = /token|secret|csrf|password|passwd|apikey|api[-_]?key|nonce|salt|uuid|authid/i;
 var NON_SECURITY_ID_PATTERN = /temp|tmp|cache|correlation|request|req|trace|execution|dev|hmr|mock|test|perf|marker/i;
 var PATH_OR_DOM_MARKER = /[\\/#]|\.[A-Za-z0-9]/;
@@ -2907,6 +3467,7 @@ function collectStaticStringParts(node, out) {
 }
 var no_insecure_random_id_default = createRule({
   name: "no-insecure-random-id",
+  documentation: noInsecureRandomIdDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -2948,6 +3509,17 @@ var no_insecure_random_id_default = createRule({
 
 // src/rules/no-json-stringify-error.ts
 import "@typescript-eslint/utils";
+var noJsonStringifyErrorDocumentation = {
+  summary: "Disallow `JSON.stringify` on an Error value; it yields `{}` because `message`/`stack` are non-enumerable.",
+  rationale: "Native Error details are non-enumerable, so generic JSON serialization discards diagnostic information.",
+  remediation: "Serialize explicit error fields or use an error-aware serializer.",
+  category: "correctness",
+  limitations: ["The rule uses local syntax and naming evidence rather than type information."],
+  examples: [
+    { id: "explicit-error-message", title: "Serialize an enumerable error field", outcome: "no-match", files: [{ path: "src/report.ts", source: "try { f(); } catch (err) { JSON.stringify({ error: err.message }); }" }], focusPath: "src/report.ts", expectedCount: 0, public: true },
+    { id: "stringified-error", title: "Do not stringify an Error object", outcome: "match", files: [{ path: "src/report.ts", source: "try { f(); } catch (err) { JSON.stringify({ error: err }); }" }], focusPath: "src/report.ts", expectedCount: 1, public: true }
+  ]
+};
 var ERROR_NAME_PATTERN = /^(e|err|error|ex|exc)$/i;
 var ERROR_PROP_PATTERN = /^(cause|lastError|error|err|exception|originalError|innerError)$/i;
 var SAFE_STRING_PROPS = /* @__PURE__ */ new Set(["message", "stack", "name"]);
@@ -3135,6 +3707,7 @@ function nestedExpressionSuggestsError(expression, scope) {
 }
 var no_json_stringify_error_default = createRule({
   name: "no-json-stringify-error",
+  documentation: noJsonStringifyErrorDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -3187,6 +3760,47 @@ function isZodModule(source) {
 }
 
 // src/rules/no-impossible-zod-literal-bounds.ts
+var noImpossibleZodLiteralBoundsDocumentation = {
+  summary: "Disallow same-chain literal Zod bounds whose accepted set is mathematically empty.",
+  rationale: "A schema with contradictory literal bounds rejects every input, turning validation into an unreachable contract that usually reflects a typo.",
+  remediation: "Choose compatible lower and upper bounds, or remove the constraint that does not express the intended domain.",
+  category: "correctness",
+  limitations: [
+    "Only finite numeric literals in a single number, string, or array schema chain are compared.",
+    "Chains with dynamic bounds, non-bound validators, transforms, pipes, or preprocessors are skipped.",
+    "Test and generated files are excluded."
+  ],
+  examples: [
+    {
+      id: "compatible-number-bounds",
+      title: "Allow a number admitted by both bounds",
+      outcome: "no-match",
+      files: [
+        {
+          path: "src/schema.ts",
+          source: 'import { z } from "zod"; const S = z.number().gte(3).lte(3);'
+        }
+      ],
+      focusPath: "src/schema.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "contradictory-number-bounds",
+      title: "Reject an empty numeric interval",
+      outcome: "match",
+      files: [
+        {
+          path: "src/schema.ts",
+          source: 'import { z } from "zod"; const S = z.number().min(5).max(4);'
+        }
+      ],
+      focusPath: "src/schema.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var KINDS = /* @__PURE__ */ new Set(["array", "number", "string"]);
 var NUMBER_METHODS = /* @__PURE__ */ new Set([
   "gt",
@@ -3246,6 +3860,7 @@ function isOutermostCall(node) {
 }
 var no_impossible_zod_literal_bounds_default = createRule({
   name: "no-impossible-zod-literal-bounds",
+  documentation: noImpossibleZodLiteralBoundsDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -3503,6 +4118,17 @@ function createLogMatcher(options = {}) {
 }
 
 // src/rules/no-log-only-catch.ts
+var noLogOnlyCatchDocumentation = {
+  summary: "Disallow `catch` clauses that only log (or silently do nothing) and then swallow the error; rethrow or handle it instead.",
+  rationale: "Swallowing an exception after logging lets execution continue as if the operation succeeded.",
+  remediation: "Rethrow the error, return an explicit fallback, or perform concrete recovery.",
+  category: "correctness",
+  limitations: ["Documented intentional ignores, tests, and catches with observable recovery are excluded."],
+  examples: [
+    { id: "rethrow-after-log", title: "Preserve failure after logging", outcome: "no-match", files: [{ path: "src/task.ts", source: "try { run(); } catch (error) { console.error(error); throw error; }" }], focusPath: "src/task.ts", expectedCount: 0, public: true },
+    { id: "log-and-swallow", title: "Do not only log a failure", outcome: "match", files: [{ path: "src/task.ts", source: "try { run(); } catch (error) { console.error(error); }" }], focusPath: "src/task.ts", expectedCount: 1, public: true }
+  ]
+};
 var BENCHMARK_DIR_RE = /(?:^|[\\/])benchmarks?[\\/]/;
 var SINGLE_STATEMENT_HOSTS = /* @__PURE__ */ new Set([
   AST_NODE_TYPES14.DoWhileStatement,
@@ -3590,6 +4216,7 @@ function isSeedValue(node) {
 }
 var no_log_only_catch_default = createRule({
   name: "no-log-only-catch",
+  documentation: noLogOnlyCatchDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -3771,6 +4398,17 @@ function typedFunction(node) {
 }
 
 // src/rules/no-long-comment.ts
+var noLongCommentDocumentation = {
+  summary: "Flag unusually large unstructured JSDoc blocks in implementation code.",
+  rationale: "Large narrative comments become stale and obscure the local facts that belong beside the code.",
+  remediation: "Keep only durable local constraints and express the remaining behavior in code.",
+  category: "maintainability",
+  limitations: ["Only JSDoc blocks are inspected; structured API docs, tests, scripts, generated files, and versioned dependencies are excluded."],
+  examples: [
+    { id: "local-fact", title: "Keep a concise local fact", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// The cache is process local.\nconst cache = new Map();" }], focusPath: "src/cache.ts", expectedCount: 0, public: true },
+    { id: "prose-wall", title: "Avoid an unstructured prose wall", outcome: "match", files: [{ path: "src/chart.ts", source: "/** One. Two. Three. Four. Five. Six. Seven. Eight. */\nconst chart = createChart();" }], focusPath: "src/chart.ts", expectedCount: 1, public: true }
+  ]
+};
 var EXCESSIVE_SENTENCE_COUNT = 8;
 var EXCESSIVE_WORD_COUNT = 120;
 var PROSE_WORD_RE = /[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu;
@@ -3790,9 +4428,10 @@ function wordUnits(text) {
 }
 var no_long_comment_default = createRule({
   name: "no-long-comment",
+  documentation: noLongCommentDocumentation,
   meta: {
     type: "suggestion",
-    docs: { description: "Flag unusually large unstructured prose blocks in implementation code." },
+    docs: { description: "Flag unusually large unstructured JSDoc blocks in implementation code." },
     schema: [],
     messages: {
       tooLong: "Comment is an unusually large prose block \u2014 keep the local facts and clarify the code itself."
@@ -3815,6 +4454,17 @@ var no_long_comment_default = createRule({
 
 // src/rules/no-generic-single-export-module.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES17, ASTUtils as ASTUtils3 } from "@typescript-eslint/utils";
+var noGenericSingleExportModuleDocumentation = {
+  summary: "Disallow generic module stems when one runtime export already names the responsibility.",
+  rationale: "A generic filename hides the sole exported responsibility and makes navigation less descriptive.",
+  remediation: "Rename the module after its single runtime export.",
+  category: "maintainability",
+  limitations: ["Only configured generic stems with exactly one public runtime export are reported."],
+  examples: [
+    { id: "responsibility-named-module", title: "Name the module after its export", outcome: "no-match", files: [{ path: "src/order-parser.ts", source: "export function parseOrder() { return {}; }" }], focusPath: "src/order-parser.ts", expectedCount: 0, public: true },
+    { id: "generic-module-name", title: "Do not hide one export in a generic module", outcome: "match", files: [{ path: "src/utils.ts", source: "export function parseOrder() { return {}; }" }], focusPath: "src/utils.ts", expectedCount: 1, public: true }
+  ]
+};
 var GENERIC_STEMS = /* @__PURE__ */ new Set([
   "base",
   "common",
@@ -3977,6 +4627,7 @@ function memberPropertyName(node) {
 }
 var no_generic_single_export_module_default = createRule({
   name: "no-generic-single-export-module",
+  documentation: noGenericSingleExportModuleDocumentation,
   meta: {
     type: "suggestion",
     docs: { description: "Disallow generic module stems when one runtime export already names the responsibility." },
@@ -4029,10 +4680,22 @@ var no_generic_single_export_module_default = createRule({
 
 // src/rules/no-offset-pagination.ts
 import "@typescript-eslint/utils";
+var noOffsetPaginationDocumentation = {
+  summary: "Disallow OFFSET pagination in embedded SQL; it is O(N) per page and drops or repeats rows under concurrent writes. Use a keyset cursor.",
+  rationale: "Offset pagination scans skipped rows and shifts page boundaries under concurrent writes.",
+  remediation: "Page with a stable ordered key and a cursor predicate.",
+  category: "performance",
+  limitations: ["Only embedded SQL is inspected; test files and non-pagination OFFSET syntax are excluded."],
+  examples: [
+    { id: "keyset-pagination", title: "Page from a stable cursor", outcome: "no-match", files: [{ path: "src/runs.ts", source: "db.prepare(`SELECT id FROM runs WHERE id > ? ORDER BY id LIMIT ?`).all();" }], focusPath: "src/runs.ts", expectedCount: 0, public: true },
+    { id: "offset-pagination", title: "Do not page by offset", outcome: "match", files: [{ path: "src/runs.ts", source: "db.query(`SELECT id FROM runs ORDER BY id LIMIT ? OFFSET ?`);" }], focusPath: "src/runs.ts", expectedCount: 1, public: true }
+  ]
+};
 var OFFSET_PAGINATION = /\bOFFSET\s+(?:%s|%\(\w+\)s|\?\d*|:\w+|@\w+|\$\d+|\d+)/i;
 var OFFSET_GATE = /offset/i;
 var no_offset_pagination_default = createRule({
   name: "no-offset-pagination",
+  documentation: noOffsetPaginationDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -4059,6 +4722,17 @@ var no_offset_pagination_default = createRule({
 
 // src/rules/no-positional-tuple-return.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES18 } from "@typescript-eslint/utils";
+var noPositionalTupleReturnDocumentation = {
+  summary: "Disallow returning a multi-field tuple from an exported function; return a named object so call sites cannot mismatch slots.",
+  rationale: "Public tuple fields are identified only by position, so reordering can preserve types while changing meaning.",
+  remediation: "Return an object whose property names describe each value.",
+  category: "maintainability",
+  limitations: ["Only declared multi-field tuple returns on public TypeScript surfaces are inspected."],
+  examples: [
+    { id: "named-object-return", title: "Return named fields", outcome: "no-match", files: [{ path: "src/download.ts", source: "export function download(): { body: string; status: number } { return impl(); }" }], focusPath: "src/download.ts", expectedCount: 0, public: true },
+    { id: "tuple-return", title: "Do not expose positional fields", outcome: "match", files: [{ path: "src/download.ts", source: "export function download(): [string, number] { return impl(); }" }], focusPath: "src/download.ts", expectedCount: 1, public: true }
+  ]
+};
 var MIN_ELEMENTS = 2;
 var AWAITABLE_TYPES = /* @__PURE__ */ new Set(["Promise", "PromiseLike", "Awaited", "Readonly"]);
 function staticMemberName2(key) {
@@ -4283,6 +4957,7 @@ function isExported(node, specifierExports) {
 }
 var no_positional_tuple_return_default = createRule({
   name: "no-positional-tuple-return",
+  documentation: noPositionalTupleReturnDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -4379,6 +5054,17 @@ var no_positional_tuple_return_default = createRule({
 
 // src/rules/no-raw-env.ts
 import "@typescript-eslint/utils";
+var noRawEnvDocumentation = {
+  summary: "Disallow direct `process.env` and `import.meta.env` reads outside validated boundaries.",
+  rationale: "Raw environment reads are untyped and defer invalid configuration failures until use.",
+  remediation: "Validate environment values at startup and import the typed configuration object.",
+  category: "correctness",
+  limitations: ["Host markers, assignment targets, tests, scripts, build config, and validated boundaries are excluded."],
+  examples: [
+    { id: "validated-environment", title: "Read validated configuration", outcome: "no-match", files: [{ path: "src/database.ts", source: "import { env } from './env.js'; const url = env.DATABASE_URL;" }], focusPath: "src/database.ts", expectedCount: 0, public: true },
+    { id: "raw-environment-read", title: "Do not read raw configuration", outcome: "match", files: [{ path: "src/database.ts", source: "const url = process.env.DATABASE_URL;" }], focusPath: "src/database.ts", expectedCount: 1, public: true }
+  ]
+};
 var CONFIG_FILE_RE = /(^|[\\/])[\w.-]+\.config\.[cm]?[jt]sx?$/;
 var ENV_BOUNDARY_FILE_RE = /(^|[\\/])(?:env|client-env|server-env|client-settings|server-settings)\.[cm]?[jt]sx?$/;
 var ENV_VALIDATION_MARKER_RE = /\bcreateEnv\s*\(|\bz\.object\s*\(|\.(?:safeParse|parse)\s*\(/;
@@ -4425,6 +5111,7 @@ function isWholeEnvSpread(node) {
 }
 var no_raw_env_default = createRule({
   name: "no-raw-env",
+  documentation: noRawEnvDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -4456,6 +5143,17 @@ var no_raw_env_default = createRule({
 
 // src/rules/no-raw-fetch-outside-clients.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES19 } from "@typescript-eslint/utils";
+var noRawFetchOutsideClientsDocumentation = {
+  summary: "Disallow calling the global `fetch` outside the client layer; route outbound HTTP through a client module that owns retry, timeout and status handling.",
+  rationale: "Scattered fetch calls bypass shared transport policy and are harder to stub and observe consistently.",
+  remediation: "Move the request into a client module and call that abstraction from application code.",
+  category: "architecture",
+  limitations: ["Tests, client-layer paths, constructed handoffs, and pre-signed URL transfers are excluded."],
+  examples: [
+    { id: "client-call", title: "Use a client abstraction", outcome: "no-match", files: [{ path: "src/routes/handler.ts", source: "const response = await billingClient.getInvoice(id);" }], focusPath: "src/routes/handler.ts", expectedCount: 0, public: true },
+    { id: "raw-fetch", title: "Do not call global fetch here", outcome: "match", files: [{ path: "src/routes/handler.ts", source: "const response = await fetch('/api/invoices');" }], focusPath: "src/routes/handler.ts", expectedCount: 1, public: true }
+  ]
+};
 var DEFAULT_ALLOW = [
   "[\\\\/]clients?[\\\\/]",
   "-client\\.[cm]?[jt]sx?$",
@@ -4519,6 +5217,7 @@ function compile(patterns) {
 }
 var no_raw_fetch_outside_clients_default = createRule({
   name: "no-raw-fetch-outside-clients",
+  documentation: noRawFetchOutsideClientsDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -4567,6 +5266,17 @@ var no_raw_fetch_outside_clients_default = createRule({
 
 // src/rules/no-restricted-library-load.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES20, ASTUtils as ASTUtils4 } from "@typescript-eslint/utils";
+var noRestrictedLibraryLoadDocumentation = {
+  summary: "Apply a configured library-replacement policy to literal dynamic imports, CommonJS loads, and TypeScript import-equals declarations.",
+  rationale: "Runtime module loads can bypass the replacement policy enforced for static imports.",
+  remediation: "Load the configured replacement library instead of the restricted module.",
+  category: "architecture",
+  limitations: ["Only literal dynamic imports, unshadowed CommonJS loads, and TypeScript import-equals declarations are checked."],
+  examples: [
+    { id: "static-import", title: "Static imports remain the static-import rule's responsibility", outcome: "no-match", files: [{ path: "src/client.ts", source: "import axios from 'axios';" }], focusPath: "src/client.ts", expectedCount: 0, public: true },
+    { id: "runtime-load", title: "Do not load a restricted library at runtime", outcome: "match", files: [{ path: "src/client.ts", source: "const client = require('axios');" }], focusPath: "src/client.ts", expectedCount: 1, public: true }
+  ]
+};
 function literalModule(node) {
   return node?.type === AST_NODE_TYPES20.Literal && typeof node.value === "string" ? node.value : null;
 }
@@ -4575,6 +5285,7 @@ function matchesModule(source, module) {
 }
 var no_restricted_library_load_default = createRule({
   name: "no-restricted-library-load",
+  documentation: noRestrictedLibraryLoadDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -4665,13 +5376,25 @@ var MIN_DISTINCT_SCOPES = 2;
 var PREVIEW_LENGTH = 40;
 var SQL_KEYWORD_RE = /\b(SELECT|INSERT|UPDATE|DELETE|FROM|WHERE|JOIN|VALUES|ON CONFLICT|RETURNING|GROUP BY|ORDER BY)\b/;
 var IDENTIFIER_RE = /^[a-z_][a-z0-9_.]*$/;
+var URL_PATH_RE = /^\/(?=[^\s]*[A-Za-z0-9])[A-Za-z0-9._~!$&'()*+,;=:@%/?#{}\u005B\u005D-]+$/;
 var FUNCTION_TYPES4 = /* @__PURE__ */ new Set([
   AST_NODE_TYPES21.FunctionDeclaration,
   AST_NODE_TYPES21.FunctionExpression,
   AST_NODE_TYPES21.ArrowFunctionExpression
 ]);
+var noRepeatedStringLiteralDocumentation = {
+  summary: "Disallow a long structured string literal repeated across functions; the copies drift when one is edited. Extract a module-level constant.",
+  rationale: "Independent copies of a query, route template, or identifier can diverge and silently change behavior.",
+  remediation: "Extract the repeated value to one module-level constant and reference it from each function.",
+  category: "maintainability",
+  limitations: ["Test files, short strings, prose, substitutions, module sources, JSX attributes, and repetition within one function are excluded."],
+  examples: [
+    { id: "shared-constant", title: "Share one structured value", outcome: "no-match", files: [{ path: "src/queries.ts", source: "const QUERY = 'SELECT id, status, created_at FROM candidates';\nfunction one() { return QUERY; }\nfunction two() { return QUERY; }" }], focusPath: "src/queries.ts", expectedCount: 0, public: true },
+    { id: "repeated-query", title: "Do not copy a structured value across functions", outcome: "match", files: [{ path: "src/queries.ts", source: "function one() { return 'SELECT id, status, created_at FROM candidates'; }\nfunction two() { return 'SELECT id, status, created_at FROM candidates'; }" }], focusPath: "src/queries.ts", expectedCount: 1, public: true }
+  ]
+};
 function isStructured(value) {
-  return value.includes("\n") || SQL_KEYWORD_RE.test(value) || IDENTIFIER_RE.test(value);
+  return value.includes("\n") || SQL_KEYWORD_RE.test(value) || IDENTIFIER_RE.test(value) || URL_PATH_RE.test(value);
 }
 function preview(value) {
   const oneLine = value.replaceAll("\n", " ").trim();
@@ -4690,11 +5413,13 @@ function isScaffolding(node) {
   if (parent === void 0) {
     return true;
   }
+  const isNonComputedPropertyKey = (parent.type === AST_NODE_TYPES21.Property || parent.type === AST_NODE_TYPES21.PropertyDefinition || parent.type === AST_NODE_TYPES21.MethodDefinition || parent.type === AST_NODE_TYPES21.AccessorProperty) && parent.key === node && !parent.computed;
   const isRequireSource = parent.type === AST_NODE_TYPES21.CallExpression && parent.callee.type === AST_NODE_TYPES21.Identifier && parent.callee.name === "require";
-  return parent.type === AST_NODE_TYPES21.ImportDeclaration || parent.type === AST_NODE_TYPES21.ImportExpression || parent.type === AST_NODE_TYPES21.ExportNamedDeclaration || parent.type === AST_NODE_TYPES21.ExportAllDeclaration || parent.type === AST_NODE_TYPES21.TSImportType || parent.type === AST_NODE_TYPES21.JSXAttribute || parent.type === AST_NODE_TYPES21.TSLiteralType || isRequireSource;
+  return parent.type === AST_NODE_TYPES21.ImportDeclaration || parent.type === AST_NODE_TYPES21.ImportExpression || parent.type === AST_NODE_TYPES21.ExportNamedDeclaration || parent.type === AST_NODE_TYPES21.ExportAllDeclaration || parent.type === AST_NODE_TYPES21.TSImportType || parent.type === AST_NODE_TYPES21.JSXAttribute || parent.type === AST_NODE_TYPES21.TSLiteralType || isNonComputedPropertyKey || isRequireSource;
 }
 var no_repeated_string_literal_default = createRule({
   name: "no-repeated-string-literal",
+  documentation: noRepeatedStringLiteralDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -4707,7 +5432,7 @@ var no_repeated_string_literal_default = createRule({
   },
   defaultOptions: [],
   create(context) {
-    if (isTestFile(context.filename)) {
+    if (isTestFile(context.filename) || isGeneratedFile(context.filename, context.sourceCode.text)) {
       return {};
     }
     const occurrences = /* @__PURE__ */ new Map();
@@ -4780,6 +5505,17 @@ var NON_ASCII_LETTER_RE = /[^\p{ASCII}\p{N}\p{P}\p{Z}]/u;
 var WALL_NARRATION_RE2 = /^(?:(?:\d+[.)]|(?:phase|step)\s+\d+\s*:?)\s*)?(?:add|build|call|check|compute|copy|count|create|fetch|filter|find|get|handle|load|map|merge|parse|process|read|remove|return|save|send|set|sort|store|update|validate|write)(?:s|es|d|ed|ing)?\b/i;
 var WALL_CLUSTER_MAX_LINE_GAP = 8;
 var WALL_CLUSTER_MIN_COMMENTS = 3;
+var noRestatedCommentDocumentation = {
+  summary: "Flag a single-line comment whose every word already appears on the statement below it.",
+  rationale: "A comment that only repeats code adds no context and can become stale independently.",
+  remediation: "Delete the comment or replace it with the reason, constraint, or consequence absent from the code.",
+  category: "maintainability",
+  limitations: ["Directives, protected references, questions, multi-line prose, comments with novel content, and generated files are excluded."],
+  examples: [
+    { id: "reason-comment", title: "Keep the reason the code cannot express", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// Serialize because the cache key is stable across deploys.\nconst key = serialize(input);" }], focusPath: "src/cache.ts", expectedCount: 0, public: true },
+    { id: "restated-comment", title: "Remove a comment that repeats the statement", outcome: "match", files: [{ path: "src/cache.ts", source: "// Serialize key\nconst key = serialize(input);" }], focusPath: "src/cache.ts", expectedCount: 1, public: true }
+  ]
+};
 function areAdjacentLineComments2(a, b) {
   return a !== void 0 && b !== void 0 && a.type === "Line" && b.type === "Line" && b.loc.start.line === a.loc.end.line + 1;
 }
@@ -4794,6 +5530,7 @@ function headsSiblingRun(node) {
 }
 var no_restated_comment_default = createRule({
   name: "no-restated-comment",
+  documentation: noRestatedCommentDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -4879,6 +5616,19 @@ var no_restated_comment_default = createRule({
 
 // src/rules/no-restated-jsdoc.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES23 } from "@typescript-eslint/utils";
+var noRestatedJsdocDocumentation = {
+  summary: "Flag a JSDoc block whose description and tags only re-spell the signature they document.",
+  rationale: "Signature-only JSDoc duplicates type information and drifts without helping callers.",
+  remediation: "Delete the block or document behavior, constraints, failures, or context the signature cannot express.",
+  category: "maintainability",
+  aliases: ["jsdoc-restates-signature"],
+  autofix: "suggestion",
+  limitations: ["Generated files, detached blocks, unknown tags, empty blocks, and JSDoc with information absent from the signature are excluded."],
+  examples: [
+    { id: "behavioral-jsdoc", title: "Document behavior absent from the signature", outcome: "no-match", files: [{ path: "src/users.ts", source: "/** Get the user while bypassing the read replica. */\nexport function getUser(id: string) { return id; }" }], focusPath: "src/users.ts", expectedCount: 0, public: true },
+    { id: "signature-jsdoc", title: "Remove JSDoc that only repeats the signature", outcome: "match", files: [{ path: "src/users.ts", source: "/** Get the user by id. */\nexport function getUserById(id: string) { return id; }" }], focusPath: "src/users.ts", expectedCount: 1, public: true }
+  ]
+};
 var MODELLED_TAGS = /* @__PURE__ */ new Set([
   "arg",
   "argument",
@@ -4978,6 +5728,7 @@ function tokensOf(names) {
 }
 var no_restated_jsdoc_default = createRule({
   name: "no-restated-jsdoc",
+  documentation: noRestatedJsdocDocumentation,
   meta: {
     type: "suggestion",
     hasSuggestions: true,
@@ -5001,10 +5752,14 @@ var no_restated_jsdoc_default = createRule({
         for (const comment of sourceCode.getAllComments()) {
           if (comment.type !== "Block" || !comment.value.startsWith("*")) continue;
           const { description, tags } = parseJsDoc(comment.value);
-          if (DIRECTIVE_RE4.test(description)) continue;
+          const describedText = [
+            description,
+            ...tags.filter((tag) => tag.name === "description").map((tag) => tag.text)
+          ].filter((text) => text.length > 0).join("\n");
+          if (DIRECTIVE_RE4.test(describedText)) continue;
           const tagNames = new Set(tags.map((tag) => tag.name));
           if ([...tagNames].some((name) => !MODELLED_TAGS.has(name))) continue;
-          if (isProtected(description)) continue;
+          if (isProtected(describedText)) continue;
           const token = sourceCode.getTokenAfter(comment, { includeComments: false });
           if (token === null || token.loc.start.line !== comment.loc.end.line + 1) continue;
           let node = sourceCode.getNodeByRangeIndex(token.range[0]);
@@ -5017,13 +5772,14 @@ var no_restated_jsdoc_default = createRule({
           if (declaration === null) continue;
           const paramTags = tags.filter((tag) => PARAM_TAGS.has(tag.name));
           const returnTags = tags.filter((tag) => RETURN_TAGS.has(tag.name));
-          if (description.length === 0 && paramTags.length === 0 && returnTags.length === 0) {
+          if (describedText.length === 0 && paramTags.length === 0 && returnTags.length === 0) {
             continue;
           }
+          if ((paramTags.length > 0 || returnTags.length > 0) && documentsTypedFunction(sourceCode, comment)) continue;
           const nameTokens = tokensOf([declaration.name]);
           const paramTokens = tokensOf(declaration.params);
           const known = /* @__PURE__ */ new Set([...nameTokens, ...paramTokens]);
-          let addsNothing = covered(description, known);
+          let addsNothing = covered(describedText, known);
           for (const tag of paramTags) {
             const text = tag.text.replace(/^\{[^}]*\}\s*/, "");
             const match = /^\[?([A-Za-z_$][\w.$]*)\]?\s*-?\s*([\s\S]*)$/.exec(text);
@@ -5031,7 +5787,13 @@ var no_restated_jsdoc_default = createRule({
               addsNothing = false;
               break;
             }
-            const own = /* @__PURE__ */ new Set([...splitIdentifier(match[1]?.split(".").pop() ?? ""), ...nameTokens]);
+            const path = match[1] ?? "";
+            const root = path.split(".")[0] ?? "";
+            if (!declaration.params.includes(root)) {
+              addsNothing = false;
+              break;
+            }
+            const own = /* @__PURE__ */ new Set([...splitIdentifier(path.split(".").pop() ?? ""), ...nameTokens]);
             if (!covered(match[2] ?? "", own)) {
               addsNothing = false;
               break;
@@ -5209,6 +5971,17 @@ function isAuthSecretName(identifier) {
 }
 
 // src/rules/no-secret-in-log.ts
+var noSecretInLogDocumentation = {
+  summary: "Disallow passing a secret-named value or a raw request/response blob to a logging call; both leak to log sinks. Redact or omit.",
+  rationale: "Logs are widely retained and distributed, so credentials and raw bodies can become durable data leaks.",
+  remediation: "Omit the value or log an explicitly redacted, truncated, or derived non-sensitive field.",
+  category: "security",
+  limitations: ["Detection uses configurable logger names and statically recognizable secret names, raw-body names, and redaction markers."],
+  examples: [
+    { id: "redacted-secret", title: "Log an explicitly redacted value", outcome: "no-match", files: [{ path: "src/auth.ts", source: "logger.info('auth', { tokenPrefix });" }], focusPath: "src/auth.ts", expectedCount: 0, public: true },
+    { id: "logged-secret", title: "Do not send a secret to logs", outcome: "match", files: [{ path: "src/auth.ts", source: "logger.error('auth failed', { token });" }], focusPath: "src/auth.ts", expectedCount: 1, public: true }
+  ]
+};
 var LOG_INNOCUOUS_WORDS = /* @__PURE__ */ new Set([
   ...INNOCUOUS_WORDS,
   "name",
@@ -5328,6 +6101,7 @@ function propertyKeyName2(prop) {
 }
 var no_secret_in_log_default = createRule({
   name: "no-secret-in-log",
+  documentation: noSecretInLogDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -5402,6 +6176,17 @@ var no_secret_in_log_default = createRule({
 
 // src/rules/no-select-star.ts
 import "@typescript-eslint/utils";
+var noSelectStarDocumentation = {
+  summary: "Disallow SELECT * in embedded SQL; it over-fetches and leaves the row contract implicit, so a schema change breaks row parsing silently.",
+  rationale: "Wildcard projections couple row shape and query cost to unrelated schema changes.",
+  remediation: "List every required column explicitly in the projection.",
+  category: "correctness",
+  limitations: ["Only statically visible embedded SQL is checked; function arguments such as COUNT(*) and stars inside EXISTS are excluded."],
+  examples: [
+    { id: "explicit-projection", title: "Select the required columns", outcome: "no-match", files: [{ path: "src/runs.ts", source: "db.prepare(`SELECT id, status FROM runs`).all();" }], focusPath: "src/runs.ts", expectedCount: 0, public: true },
+    { id: "wildcard-projection", title: "Do not select every column", outcome: "match", files: [{ path: "src/runs.ts", source: "db.prepare(`SELECT * FROM runs`).all();" }], focusPath: "src/runs.ts", expectedCount: 1, public: true }
+  ]
+};
 var QUERY_SHAPE = /\bSELECT\b[\s\S]*?\bFROM\b/i;
 var SELECT_KEYWORD = /\bSELECT\b/gi;
 var FROM_KEYWORD = /^FROM\b/i;
@@ -5443,6 +6228,7 @@ function isProjectionStar(sql, pos) {
 }
 var no_select_star_default = createRule({
   name: "no-select-star",
+  documentation: noSelectStarDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -5469,6 +6255,17 @@ var no_select_star_default = createRule({
 
 // src/rules/no-sentinel-return-on-catch.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES24 } from "@typescript-eslint/utils";
+var noSentinelReturnOnCatchDocumentation = {
+  summary: "Disallow swallowing a caught error by returning an empty sentinel unless the error is handled or the sentinel is part of the function contract.",
+  rationale: "An unreported fallback makes operational failure indistinguishable from a legitimate empty result.",
+  remediation: "Rethrow, report the error before returning, or model expected absence with an explicit predicate, safe-parse, or result contract.",
+  category: "correctness",
+  limitations: ["Recognized predicate, safe-parse, normal-path sentinel, deliberate parse, generated-client, and configured logging patterns are excluded."],
+  examples: [
+    { id: "reported-fallback", title: "Report an error before returning a fallback", outcome: "no-match", files: [{ path: "src/load.ts", source: "function load() { try { return read(); } catch (error) { logger.warn('load failed', error); return null; } }" }], focusPath: "src/load.ts", expectedCount: 0, public: true },
+    { id: "silent-fallback", title: "Do not turn an unreported error into absence", outcome: "match", files: [{ path: "src/load.ts", source: "function load() { try { return read(); } catch { return null; } }" }], focusPath: "src/load.ts", expectedCount: 1, public: true }
+  ]
+};
 function unwrapSentinelExpression(arg) {
   let current = arg;
   while (current?.type === AST_NODE_TYPES24.TSAsExpression || current?.type === AST_NODE_TYPES24.TSTypeAssertion || current?.type === AST_NODE_TYPES24.TSSatisfiesExpression) {
@@ -5792,10 +6589,11 @@ function isWithin(node, ancestor) {
 }
 var no_sentinel_return_on_catch_default = createRule({
   name: "no-sentinel-return-on-catch",
+  documentation: noSentinelReturnOnCatchDocumentation,
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow swallowing a caught error by returning an empty sentinel (`null`, `undefined`, `false`, `[]`, `{}`) as the final statement of a `catch` block, unless the error is logged/reported or the sentinel is the declared safe-parse/predicate contract."
+      description: "Disallow swallowing a caught error by returning an empty sentinel unless the error is handled or the sentinel is part of the function contract."
     },
     schema: [
       {
@@ -5820,10 +6618,10 @@ var no_sentinel_return_on_catch_default = createRule({
           return false;
         }
         if (matcher.isLoggingCall(current)) {
-          return true;
+          return caughtName === null || argsIncludeBinding(current.arguments, caughtName);
         }
         const name = calleeName2(current.callee);
-        return name !== null && REPORT_NAME_RE.test(name) && argsIncludeBinding(current.arguments, caughtName);
+        return name !== null && REPORT_NAME_RE.test(name) && (caughtName === null || argsIncludeBinding(current.arguments, caughtName));
       });
     }
     return {
@@ -5873,6 +6671,17 @@ var no_sentinel_return_on_catch_default = createRule({
 
 // src/rules/no-silent-promise-catch.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES25 } from "@typescript-eslint/utils";
+var noSilentPromiseCatchDocumentation = {
+  summary: "Disallow `.catch()` and second-argument `.then()` handlers that silently swallow a rejection; log, rethrow, or handle the error.",
+  rationale: "A swallowed rejection hides failures and gives callers an indistinguishable fallback value.",
+  remediation: "Log, rethrow, or explicitly recover from the rejection; explain intentional teardown suppression.",
+  category: "correctness",
+  limitations: ["Test files, teardown calls, explanatory comments, non-function handlers, and handlers that consume or report the error are excluded."],
+  examples: [
+    { id: "reported-rejection", title: "Report the rejection", outcome: "no-match", files: [{ path: "src/load.ts", source: "load().catch((error) => logger.error({ error }, 'load failed'));" }], focusPath: "src/load.ts", expectedCount: 0, public: true },
+    { id: "silent-rejection", title: "Do not swallow the rejection", outcome: "match", files: [{ path: "src/load.ts", source: "load().catch(() => null);" }], focusPath: "src/load.ts", expectedCount: 1, public: true }
+  ]
+};
 function isBodyParseCall(node) {
   return node.type === AST_NODE_TYPES25.CallExpression && node.arguments.length === 0 && node.callee.type === AST_NODE_TYPES25.MemberExpression && !node.callee.computed && node.callee.property.type === AST_NODE_TYPES25.Identifier && (node.callee.property.name === "json" || node.callee.property.name === "text");
 }
@@ -5927,6 +6736,7 @@ function isSilentExpression(node) {
 }
 var no_silent_promise_catch_default = createRule({
   name: "no-silent-promise-catch",
+  documentation: noSilentPromiseCatchDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -5996,6 +6806,18 @@ var no_silent_promise_catch_default = createRule({
 
 // src/rules/no-sleep-in-test-body.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES26 } from "@typescript-eslint/utils";
+var noSleepInTestBodyDocumentation = {
+  summary: "Disallow a fixed timed sleep directly in a test body; it flakes under CI load. Synchronize on the signal or use fake timers.",
+  rationale: "Wall-clock delays make test correctness depend on scheduler and machine speed.",
+  remediation: "Await the observable signal or advance deterministic fake timers.",
+  category: "testing",
+  filePatterns: ["**/*.test.*", "**/*.spec.*", "**/tests/**", "**/__tests__/**"],
+  limitations: ["Only fixed nonzero sleeps directly inside test and per-test hook callbacks are checked; nested fakes and parameterized delays are excluded."],
+  examples: [
+    { id: "fake-timer", title: "Advance time deterministically", outcome: "no-match", files: [{ path: "src/retry.test.ts", source: "it('retries', async () => { vi.useFakeTimers(); const result = retry(); await vi.advanceTimersByTimeAsync(50); await result; });" }], focusPath: "src/retry.test.ts", expectedCount: 0, public: true },
+    { id: "fixed-sleep", title: "Do not wait for wall-clock time", outcome: "match", files: [{ path: "src/retry.test.ts", source: "it('retries', async () => { await sleep(50); expect(done()).toBe(true); });" }], focusPath: "src/retry.test.ts", expectedCount: 1, public: true }
+  ]
+};
 var SLEEP_HELPERS = /* @__PURE__ */ new Set(["sleep", "delay", "wait", "pause"]);
 var TEST_CALLERS3 = /* @__PURE__ */ new Set([
   "it",
@@ -6071,6 +6893,7 @@ function testCallerName2(callee) {
 }
 var no_sleep_in_test_body_default = createRule({
   name: "no-sleep-in-test-body",
+  documentation: noSleepInTestBodyDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -6116,6 +6939,17 @@ var DEFAULT_METHODS2 = [
   "getWithMetadata"
 ];
 var MIN_ARGUMENTS = /* @__PURE__ */ new Map([["put", 2]]);
+var noStorageInStatelessModulesDocumentation = {
+  summary: "Disallow SQL or key/value access inside configured stateless modules; derive state from a system of record instead.",
+  rationale: "Private storage in a stateless workflow creates another source of truth that can silently diverge.",
+  remediation: "Read from the system of record or derive state from an artifact the workflow already produces.",
+  category: "architecture",
+  limitations: ["The rule is disabled until module path patterns are configured and recognizes only configured storage method names."],
+  examples: [
+    { id: "system-of-record", title: "Read from the system of record", outcome: "no-match", files: [{ path: "src/engineer-digest/post.ts", source: "const issues = await linear.listIssues();" }], focusPath: "src/engineer-digest/post.ts", expectedCount: 0, public: true },
+    { id: "private-storage", title: "Do not write private state in a stateless module", outcome: "match", files: [{ path: "src/engineer-digest/post.ts", source: "await kv.put('digest:last', timestamp);" }], focusPath: "src/engineer-digest/post.ts", expectedCount: 1, public: true }
+  ]
+};
 function compile2(patterns) {
   const compiled = [];
   for (const pattern of patterns) {
@@ -6142,10 +6976,11 @@ function storageMethodName(node, methods) {
 }
 var no_storage_in_stateless_modules_default = createRule({
   name: "no-storage-in-stateless-modules",
+  documentation: noStorageInStatelessModulesDocumentation,
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow SQL or key/value access inside modules a team has declared stateless; derive state from the systems of record instead. No-op until `modules` is configured."
+      description: "Disallow SQL or key/value access inside configured stateless modules; derive state from a system of record instead."
     },
     schema: [
       {
@@ -6197,6 +7032,35 @@ var no_storage_in_stateless_modules_default = createRule({
 
 // src/rules/no-string-concat-in-loop.ts
 import "@typescript-eslint/utils";
+var noStringConcatInLoopDocumentation = {
+  summary: "Disallow O(n^2) string building via `+=` on a string variable inside a loop; push parts to an array and `join` instead.",
+  rationale: "Repeatedly rebuilding a growing string can copy all prior content on each iteration, making total work grow quadratically.",
+  remediation: "Collect each fragment in an array, then join the fragments after the loop.",
+  category: "performance",
+  limitations: [
+    "Only local identifiers initialized with a string or template literal and accumulated in a loop body are inspected."
+  ],
+  examples: [
+    {
+      id: "join-fragments",
+      title: "Join collected fragments after the loop",
+      outcome: "no-match",
+      files: [{ path: "src/render.ts", source: 'const parts = []; for (const item of items) { parts.push(item); } const output = parts.join("");' }],
+      focusPath: "src/render.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "rebuild-string",
+      title: "Do not rebuild a growing string in a loop",
+      outcome: "match",
+      files: [{ path: "src/render.ts", source: "let output = ''; for (const item of items) { output = `${output}${item}`; }" }],
+      focusPath: "src/render.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var LOOP_NODE_TYPES = /* @__PURE__ */ new Set([
   "ForStatement",
   "ForOfStatement",
@@ -6288,6 +7152,7 @@ function enclosingLoop(node) {
 }
 var no_string_concat_in_loop_default = createRule({
   name: "no-string-concat-in-loop",
+  documentation: noStringConcatInLoopDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -6348,6 +7213,35 @@ var no_string_concat_in_loop_default = createRule({
 
 // src/rules/no-tautological-expect.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES28 } from "@typescript-eslint/utils";
+var noTautologicalExpectDocumentation = {
+  summary: "Disallow an assertion whose operands are all literals; its outcome is fixed before the code runs, so it can never fail.",
+  rationale: "An assertion determined entirely by literals does not observe the code under test and can keep passing after that code is removed.",
+  remediation: "Assert on a value produced by the behavior under test, or remove the assertion.",
+  category: "testing",
+  limitations: [
+    "Only direct supported `expect` matcher calls in recognized test files are inspected."
+  ],
+  examples: [
+    {
+      id: "produced-value",
+      title: "Assert on a produced value",
+      outcome: "no-match",
+      files: [{ path: "src/add.test.ts", source: "it('adds', () => { expect(add(1, 1)).toBe(2); });" }],
+      focusPath: "src/add.test.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "literal-only-assertion",
+      title: "Do not compare identical literals",
+      outcome: "match",
+      files: [{ path: "src/add.test.ts", source: "it('works', () => { expect(true).toBe(true); });" }],
+      focusPath: "src/add.test.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var EQUALITY_MATCHERS = /* @__PURE__ */ new Set(["toBe", "toEqual", "toStrictEqual"]);
 var ZERO_ARG_MATCHERS = /* @__PURE__ */ new Set([
   "toBeDefined",
@@ -6386,6 +7280,7 @@ function expectOperand(callee) {
 }
 var no_tautological_expect_default = createRule({
   name: "no-tautological-expect",
+  documentation: noTautologicalExpectDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -6446,8 +7341,36 @@ var no_tautological_expect_default = createRule({
 });
 
 // src/rules/no-typed-doc-sections.ts
+var noTypedDocSectionsDocumentation = {
+  summary: "Reject typed-signature repetition while preserving behavior that types cannot express.",
+  rationale: "Parameter and return tags repeat typed signatures and can drift without adding runtime behavior or constraints.",
+  remediation: "Remove repeated parameter and return tags; retain documentation for behavior, failures, and external contracts.",
+  category: "maintainability",
+  limitations: ["Parameter and return tags are reported only when the documented function has corresponding explicit TypeScript types."],
+  examples: [
+    {
+      id: "behavioral-documentation",
+      title: "Keep behavior that the signature cannot express",
+      outcome: "no-match",
+      files: [{ path: "src/client.ts", source: "/** Retries when the vendor returns 429. */\nexport function fetchValue(id: string): number { return 1; }" }],
+      focusPath: "src/client.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "repeated-typed-sections",
+      title: "Do not restate typed parameters and returns",
+      outcome: "match",
+      files: [{ path: "src/client.ts", source: "/** @param id external identifier\n * @returns the value\n */\nexport function fetchValue(id: string): number { return 1; }" }],
+      focusPath: "src/client.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var no_typed_doc_sections_default = createRule({
   name: "no-typed-doc-sections",
+  documentation: noTypedDocSectionsDocumentation,
   meta: {
     type: "suggestion",
     docs: { description: "Reject typed-signature repetition while preserving behavior that types cannot express." },
@@ -6472,6 +7395,34 @@ var no_typed_doc_sections_default = createRule({
 
 // src/rules/no-trailing-value-narration.ts
 import "@typescript-eslint/utils";
+var noTrailingValueNarrationDocumentation = {
+  summary: "Flag a trailing comment that repeats the line's numeric value only to name its unit.",
+  rationale: "A repeated value can disagree with the expression after either the code or comment changes.",
+  remediation: "Put the unit in the identifier and keep comments only when they explain a constraint or non-obvious conversion.",
+  category: "maintainability",
+  aliases: ["trailing-value-narration"],
+  limitations: ["Only trailing comments with numeric values and recognized unit words are inspected."],
+  examples: [
+    {
+      id: "explain-constraint",
+      title: "Explain a domain constraint",
+      outcome: "no-match",
+      files: [{ path: "src/timeouts.ts", source: "const timeout = 5 * 60; // 5 minutes for cold starts" }],
+      focusPath: "src/timeouts.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "repeat-duration",
+      title: "Do not narrate the numeric duration",
+      outcome: "match",
+      files: [{ path: "src/timeouts.ts", source: "const staleTime = 5 * 60 * 1000; // 5 minutes" }],
+      focusPath: "src/timeouts.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var NUMBER_RE = /(?<![\w.])(\d+(?:\.\d+)?)(?![\w.])/g;
 var WORD_RE3 = /[A-Za-z]+(?:'[a-z]+)?|\d+(?:\.\d+)?/g;
 var UNIT_WORDS = /* @__PURE__ */ new Set([
@@ -6558,6 +7509,7 @@ function numbersIn(text) {
 }
 var no_trailing_value_narration_default = createRule({
   name: "no-trailing-value-narration",
+  documentation: noTrailingValueNarrationDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -6734,6 +7686,33 @@ function bodyOf(member) {
 }
 
 // src/rules/no-declaration-comment-wall.ts
+var noDeclarationCommentWallDocumentation = {
+  summary: "Flag an enum body or class body whose member comments mostly re-spell the members' own names.",
+  rationale: "A dense block of repetitive member comments obscures the few comments that add information and drifts with renamed members.",
+  remediation: "Delete comments that restate member names and retain comments that explain constraints, lifecycle, or behavior.",
+  category: "maintainability",
+  limitations: ["Only enum and class bodies meeting the configured comment-count and restatement-ratio thresholds are reported."],
+  examples: [
+    {
+      id: "uncommented-members",
+      title: "Let clear member names stand alone",
+      outcome: "no-match",
+      files: [{ path: "src/status.ts", source: "enum Status { Pending = 'pending', Done = 'done', Failed = 'failed' }" }],
+      focusPath: "src/status.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "restated-enum-members",
+      title: "Do not restate every enum member",
+      outcome: "match",
+      files: [{ path: "src/status.ts", source: "enum Status {\n  /** The pending status. */\n  Pending = 'pending',\n  /** The finished status. */\n  Finished = 'finished',\n  /** The failed status. */\n  Failed = 'failed',\n}" }],
+      focusPath: "src/status.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 function named(node) {
   switch (node.type) {
     case AST_NODE_TYPES30.TSEnumMember:
@@ -6749,6 +7728,7 @@ function named(node) {
 }
 var no_declaration_comment_wall_default = createRule({
   name: "no-declaration-comment-wall",
+  documentation: noDeclarationCommentWallDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -6842,6 +7822,33 @@ var no_declaration_comment_wall_default = createRule({
 
 // src/rules/no-union-in-comment.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES31 } from "@typescript-eslint/utils";
+var noUnionInCommentDocumentation = {
+  summary: "Flag a comment that lists a `string` field's allowed values instead of the type listing them.",
+  rationale: "A comment cannot prevent callers from supplying strings outside the listed set, and the list can drift from runtime behavior.",
+  remediation: "Move the allowed values into a string-literal union and remove the redundant comment.",
+  category: "correctness",
+  limitations: ["Only bare quoted-value lists attached to supported string declarations and schema-builder fields are inspected."],
+  examples: [
+    {
+      id: "literal-union",
+      title: "Encode allowed values in the type",
+      outcome: "no-match",
+      files: [{ path: "src/record.ts", source: "interface R { kind: 'aa' | 'bb'; }" }],
+      focusPath: "src/record.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "comment-only-union",
+      title: "Do not leave allowed values in a comment",
+      outcome: "match",
+      files: [{ path: "src/record.ts", source: "interface R {\n  kind: string; // 'aa' | 'bb'\n}" }],
+      focusPath: "src/record.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var MAX_LITERAL_LENGTH = 28;
 var LITERAL = String.raw`(?:'[^'\n]*'|"[^"\n]*"|\`[^\`\n]*\`)`;
 var LEAD_IN_RE2 = /^(?:one of|either|values?|allowed(?: values)?|options?|possible(?: values)?)\s*[:=-]?\s*/i;
@@ -6930,6 +7937,7 @@ function unionLiterals(body2) {
 }
 var no_union_in_comment_default = createRule({
   name: "no-union-in-comment",
+  documentation: noUnionInCommentDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -6990,11 +7998,39 @@ var no_union_in_comment_default = createRule({
 
 // src/rules/no-type-member-comment-wall.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES32 } from "@typescript-eslint/utils";
+var noTypeMemberCommentWallDocumentation = {
+  summary: "Flag an object type whose member comments mostly re-spell the members' own names and types.",
+  rationale: "Repetitive member comments add scanning cost while hiding the comments that describe facts absent from the type.",
+  remediation: "Delete comments that restate member names or types and keep comments that add constraints or behavior.",
+  category: "maintainability",
+  limitations: ["Only interface and type-literal bodies meeting the configured comment-count and restatement-ratio thresholds are reported."],
+  examples: [
+    {
+      id: "uncommented-members",
+      title: "Let clear member names and types stand alone",
+      outcome: "no-match",
+      files: [{ path: "src/credentials.ts", source: "interface Credentials { host: string; port: number; username: string; }" }],
+      focusPath: "src/credentials.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "restated-type-members",
+      title: "Do not restate member names and types",
+      outcome: "match",
+      files: [{ path: "src/credentials.ts", source: "interface Credentials {\n  // Database host.\n  host?: string;\n  // Database host port.\n  port?: number;\n  // Database username.\n  username?: string;\n  // Database password.\n  password?: string;\n}" }],
+      focusPath: "src/credentials.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 function isNamedMember(node) {
   return (node.type === AST_NODE_TYPES32.TSPropertySignature || node.type === AST_NODE_TYPES32.TSMethodSignature) && !node.computed;
 }
 var no_type_member_comment_wall_default = createRule({
   name: "no-type-member-comment-wall",
+  documentation: noTypeMemberCommentWallDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -7054,7 +8090,7 @@ var no_type_member_comment_wall_default = createRule({
         claimed.add(comment);
         commented += 1;
         const body2 = commentBody(comment);
-        if (body2.length === 0 || carriesValue(body2)) continue;
+        if (body2.length === 0 || carriesValue(body2) || isTagsOnly(body2)) continue;
         if (novelWords(body2, knownTokens(sourceCode.getText(member))) <= options.maxNovelWords) {
           restated += 1;
         }
@@ -7079,6 +8115,33 @@ var no_type_member_comment_wall_default = createRule({
 
 // src/rules/no-unnecessary-use-client.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES33 } from "@typescript-eslint/utils";
+var noUnnecessaryUseClientDocumentation = {
+  summary: "Flag `'use client'` files with no hooks or event handlers \u2014 they could be RSC.",
+  rationale: "An unnecessary client boundary sends the component and its transitive dependencies to the browser without using client-only behavior.",
+  remediation: "Remove the directive, or keep it only when the module uses a supported client-side API or boundary dependency.",
+  category: "performance",
+  limitations: ["Client need is inferred from recognized hooks, handlers, browser globals, exports, classes, and known client-only imports."],
+  examples: [
+    {
+      id: "interactive-component",
+      title: "Keep the directive for interactive components",
+      outcome: "no-match",
+      files: [{ path: "src/counter.tsx", source: "'use client'; import { useState } from 'react'; export default function X() { const [n] = useState(0); return <div>{n}</div>; }" }],
+      focusPath: "src/counter.tsx",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "static-component",
+      title: "Remove the directive from static components",
+      outcome: "match",
+      files: [{ path: "src/banner.tsx", source: "'use client'; export default function X() { return <div>hello</div>; }" }],
+      focusPath: "src/banner.tsx",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var HOOK_REGEX = /^use([A-Z]|$)/;
 var EVENT_PROP_REGEX = /^on[A-Z]/;
 var ERROR_FILE_REGEX = /\b(?:global-)?error\.[jt]sx?$/;
@@ -7153,6 +8216,7 @@ var isGlobalReference = (node, context) => {
 };
 var no_unnecessary_use_client_default = createRule({
   name: "no-unnecessary-use-client",
+  documentation: noUnnecessaryUseClientDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -7286,8 +8350,36 @@ var MOCK_MODULES = /* @__PURE__ */ new Set([
   "jest-mock",
   "@jest/globals"
 ]);
+var noUnsafeMockCastingDocumentation = {
+  summary: "Disallow casting to mock types like `jest.Mock` or `vi.Mock`. Use `vi.mocked()` or `jest.mocked()` instead.",
+  rationale: "A type assertion can claim an unmocked value is a mock and bypass checking between the original callable and the mock API.",
+  remediation: "Use the test framework's `mocked` helper to obtain the typed mock reference.",
+  category: "testing",
+  limitations: ["Only mock types imported from Vitest or Jest modules are inspected."],
+  examples: [
+    {
+      id: "typed-mock-helper",
+      title: "Use the framework helper",
+      outcome: "no-match",
+      files: [{ path: "src/client.test.ts", source: "const m = vi.mocked(myFn);" }],
+      focusPath: "src/client.test.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "mock-type-assertion",
+      title: "Do not assert that a value is a mock",
+      outcome: "match",
+      files: [{ path: "src/client.test.ts", source: 'import type * as vi from "vitest"; const m = myFn as vi.Mock;' }],
+      focusPath: "src/client.test.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var no_unsafe_mock_casting_default = createRule({
   name: "no-unsafe-mock-casting",
+  documentation: noUnsafeMockCastingDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -7358,6 +8450,35 @@ import {
   AST_NODE_TYPES as AST_NODE_TYPES35
 } from "@typescript-eslint/utils";
 import * as ts from "typescript";
+var noZodNativeEnumDocumentation = {
+  summary: 'Disallow `z.nativeEnum()` (and `z.enum()` over a TypeScript enum); use `z.enum(["a", "b"])` with a string-literal union instead.',
+  rationale: "Wrapping a TypeScript enum preserves its emitted runtime object and duplicates the schema's value definition across two constructs.",
+  remediation: "Pass string literals directly to `z.enum` and derive the TypeScript type with `z.infer`.",
+  category: "maintainability",
+  autofix: "safe",
+  limitations: ["Automatic fixes are limited to inline object literals whose unique values are all string literals."],
+  examples: [
+    {
+      id: "zod-literal-enum",
+      title: "Declare string values directly in Zod",
+      outcome: "no-match",
+      files: [{ path: "src/status.ts", source: 'import { z } from "zod"; const S = z.enum(["active", "inactive"]);' }],
+      focusPath: "src/status.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "zod-native-enum",
+      title: "Do not wrap a TypeScript enum",
+      outcome: "match",
+      files: [{ path: "src/status.ts", source: 'import { z } from "zod"; const S = z.nativeEnum({ Active: "active", Inactive: "inactive" });' }],
+      focusPath: "src/status.ts",
+      expectedCount: 1,
+      public: true,
+      fixedFiles: [{ path: "src/status.ts", source: 'import { z } from "zod"; const S = z.enum(["active", "inactive"]);' }]
+    }
+  ]
+};
 var IGNORE_PATTERNS = [
   /[\\/]generated[\\/]/,
   /\.gen\.tsx?$/,
@@ -7427,6 +8548,7 @@ function resolvesToImportedEnum(node, services) {
 }
 var no_zod_native_enum_default = createRule({
   name: "no-zod-native-enum",
+  documentation: noZodNativeEnumDocumentation,
   meta: {
     type: "suggestion",
     fixable: "code",
@@ -7538,6 +8660,18 @@ var no_zod_native_enum_default = createRule({
 
 // src/rules/test-loops-over-literal-cases.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES36, ASTUtils as ASTUtils6 } from "@typescript-eslint/utils";
+var testLoopsOverLiteralCasesDocumentation = {
+  summary: "Disallow assertions over an inline literal case loop in a test; parameterization reports and names every case independently.",
+  rationale: "A loop is reported as one test, so failures hide the individual case name and may stop later cases from running.",
+  remediation: "Create one named parameterized test or runner-aware subtest for each literal case.",
+  category: "testing",
+  filePatterns: ["**/*.test.*", "**/*.spec.*", "**/tests/**"],
+  limitations: ["Only inline literal for-of cases containing framework assertions are reported."],
+  examples: [
+    { id: "parameterized-cases", title: "Use a parameterized test", outcome: "no-match", files: [{ path: "src/parser.test.ts", source: "test.each(['a', 'b'])('parses %s', (value) => { expect(parse(value)).toBe(value); });" }], focusPath: "src/parser.test.ts", expectedCount: 0, public: true },
+    { id: "looped-cases", title: "Do not hide cases in a loop", outcome: "match", files: [{ path: "src/parser.test.ts", source: "test('parses', () => { for (const value of ['a', 'b']) { expect(parse(value)).toBe(value); } });" }], focusPath: "src/parser.test.ts", expectedCount: 1, public: true }
+  ]
+};
 var TEST_CALLERS4 = /* @__PURE__ */ new Set(["it", "test"]);
 var TEST_MODIFIERS2 = /* @__PURE__ */ new Set(["concurrent", "fails", "only", "sequential", "skip"]);
 var ASSERTION_ROOTS2 = /* @__PURE__ */ new Set([
@@ -7671,6 +8805,7 @@ var LOOP_CARRIED_CONTROL = /* @__PURE__ */ new Set([
 ]);
 var test_loops_over_literal_cases_default = createRule({
   name: "test-loops-over-literal-cases",
+  documentation: testLoopsOverLiteralCasesDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -7730,6 +8865,17 @@ function unwrapExpression(node) {
 
 // src/rules/prefer-constant-time-secret-compare.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES37 } from "@typescript-eslint/utils";
+var preferConstantTimeSecretCompareDocumentation = {
+  summary: "Disallow `===`/`!==` on a secret-like value; short-circuiting comparison leaks the secret through timing. Use a constant-time compare.",
+  rationale: "Ordinary equality stops at the first differing byte, allowing repeated measurements to reveal secret material.",
+  remediation: "Compare equal-length cryptographic digests with a constant-time comparison primitive.",
+  category: "security",
+  limitations: ["Secret-like values are identified conservatively from their names; test files and public sentinel comparisons are excluded."],
+  examples: [
+    { id: "constant-time-compare", title: "Use a constant-time comparison", outcome: "no-match", files: [{ path: "src/auth.ts", source: "if (await constantTimeEqual(presentedToken, expectedToken)) { allow(); }" }], focusPath: "src/auth.ts", expectedCount: 0, public: true },
+    { id: "secret-equality", title: "Do not compare secrets with equality", outcome: "match", files: [{ path: "src/auth.ts", source: "if (presentedToken === expectedToken) { allow(); }" }], focusPath: "src/auth.ts", expectedCount: 1, public: true }
+  ]
+};
 var EQUALITY_OPERATORS = /* @__PURE__ */ new Set(["===", "!==", "==", "!="]);
 var SENTINEL_IDENTIFIERS = /* @__PURE__ */ new Set(["undefined", "NaN"]);
 var SENTINEL_WORDS = /(^|_)(SENTINEL|EMPTY|NONE|NULL|UNSET|MISSING|PLACEHOLDER|DUMMY|FAKE|EXAMPLE)(_|$)/;
@@ -7784,6 +8930,7 @@ function secretNameOf(node) {
 }
 var prefer_constant_time_secret_compare_default = createRule({
   name: "prefer-constant-time-secret-compare",
+  documentation: preferConstantTimeSecretCompareDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -7825,6 +8972,17 @@ var prefer_constant_time_secret_compare_default = createRule({
 // src/rules/prefer-discriminated-union.ts
 import "@typescript-eslint/utils";
 import { AST_NODE_TYPES as AST_NODE_TYPES38 } from "@typescript-eslint/utils";
+var preferDiscriminatedUnionDocumentation = {
+  summary: "Flag flat result objects with a required positive boolean status and optional success/failure payloads.",
+  rationale: "A boolean status plus optional branch data permits contradictory and incomplete states.",
+  remediation: "Represent each result branch as a discriminated union member with its required payload.",
+  category: "correctness",
+  limitations: ["Only local object shapes with recognized positive status and payload names are inspected."],
+  examples: [
+    { id: "explicit-result-branches", title: "Use explicit result branches", outcome: "no-match", files: [{ path: "src/result.ts", source: "type Result = { ok: true; data: string } | { ok: false; error: string };" }], focusPath: "src/result.ts", expectedCount: 0, public: true },
+    { id: "optional-result-payloads", title: "Do not make both result payloads optional", outcome: "match", files: [{ path: "src/result.ts", source: "type Result = { ok: boolean; data?: string; error?: string };" }], focusPath: "src/result.ts", expectedCount: 1, public: true }
+  ]
+};
 var STATUS_MEMBER_NAMES = /* @__PURE__ */ new Set([
   "success",
   "ok"
@@ -7906,6 +9064,7 @@ function inlineReturnTypeLiteral(node) {
 }
 var prefer_discriminated_union_default = createRule({
   name: "prefer-discriminated-union",
+  documentation: preferDiscriminatedUnionDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -7954,6 +9113,17 @@ var prefer_discriminated_union_default = createRule({
 
 // src/rules/prefer-input-group-search.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES39 } from "@typescript-eslint/utils";
+var preferInputGroupSearchDocumentation = {
+  summary: "Require search icons and shared Input controls in the same visual wrapper to use InputGroup.",
+  rationale: "The shared compound control provides consistent spacing, focus behavior, and accessible composition.",
+  remediation: "Compose the search icon and field with InputGroup, InputGroupAddon, and InputGroupInput.",
+  category: "style",
+  limitations: ["Only Search and Input bindings imported from the recognized shared modules are paired."],
+  examples: [
+    { id: "grouped-search", title: "Use the shared input group", outcome: "no-match", files: [{ path: "src/search.tsx", source: "import { Search } from 'lucide-react'; import { InputGroup, InputGroupAddon, InputGroupInput } from '@/components/ui/input-group'; const field = <InputGroup><InputGroupAddon><Search /></InputGroupAddon><InputGroupInput /></InputGroup>;" }], focusPath: "src/search.tsx", expectedCount: 0, public: true },
+    { id: "loose-search-input", title: "Do not pair loose search controls", outcome: "match", files: [{ path: "src/search.tsx", source: "import { Search } from 'lucide-react'; import { Input } from '@/components/ui/input'; const field = <div><Search /><Input /></div>;" }], focusPath: "src/search.tsx", expectedCount: 1, public: true }
+  ]
+};
 var INPUT_MODULE = /(?:^|\/)components\/ui\/input$/u;
 var INPUT_GROUP_MODULE = /(?:^|\/)components\/ui\/input-group$/u;
 var MAX_JSX_DISTANCE = 2;
@@ -7997,6 +9167,7 @@ function nearestEligibleCommonAncestor(search, input, inputGroupNames) {
 }
 var prefer_input_group_search_default = createRule({
   name: "prefer-input-group-search",
+  documentation: preferInputGroupSearchDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -8067,6 +9238,35 @@ var prefer_input_group_search_default = createRule({
 
 // src/rules/prefer-immutable-module-constant.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES40, ASTUtils as ASTUtils7 } from "@typescript-eslint/utils";
+var preferImmutableModuleConstantDocumentation = {
+  summary: "Require module-level constant collections to expose readonly state.",
+  rationale: "A const binding prevents reassignment but does not stop callers from mutating its array, object, Set, or Map contents.",
+  remediation: "Expose literals with `as const` or a readonly type, and expose Set or Map values through ReadonlySet or ReadonlyMap.",
+  category: "correctness",
+  limitations: [
+    "The rule skips generated files, test files, JavaScript files, and collections that are deliberately mutated in their declaring module."
+  ],
+  examples: [
+    {
+      id: "readonly-array-literal",
+      title: "A module constant exposes a readonly literal",
+      outcome: "no-match",
+      files: [{ path: "src/constants.ts", source: "const VALUES = [1, 2, 3] as const;" }],
+      focusPath: "src/constants.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "mutable-array-literal",
+      title: "A module constant exposes a mutable array",
+      outcome: "match",
+      files: [{ path: "src/constants.ts", source: "const VALUES = [1, 2, 3];" }],
+      focusPath: "src/constants.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
 var CONSTANT_NAME = /^_?[A-Z][A-Z0-9_]*$/;
 var JAVASCRIPT_FILE_RE = /\.[cm]?jsx?$/i;
 var MUTATING_METHODS = /* @__PURE__ */ new Set([
@@ -8174,6 +9374,7 @@ function referenceMutates(identifier, isUnshadowedGlobal) {
 }
 var prefer_immutable_module_constant_default = createRule({
   name: "prefer-immutable-module-constant",
+  documentation: preferImmutableModuleConstantDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -8260,6 +9461,17 @@ function unwrapTransparentExport(node) {
 
 // src/rules/prefer-shadcn-primitives.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES41 } from "@typescript-eslint/utils";
+var preferShadcnPrimitivesDocumentation = {
+  summary: "Require visible raw JSX controls to use the corresponding shared shadcn primitive.",
+  rationale: "Shared primitives centralize interaction, accessibility, and visual behavior across the product.",
+  remediation: "Replace the raw visible control with the corresponding shared shadcn component.",
+  category: "style",
+  limitations: ["Hidden and file inputs, unassociated labels, and non-control semantic elements are excluded."],
+  examples: [
+    { id: "shared-button", title: "Use a shared button", outcome: "no-match", files: [{ path: "src/form.tsx", source: "import { Button } from '@/components/ui/button'; const action = <Button>Save</Button>;" }], focusPath: "src/form.tsx", expectedCount: 0, public: true },
+    { id: "raw-button", title: "Do not use a raw button", outcome: "match", files: [{ path: "src/form.tsx", source: "const action = <button>Save</button>;" }], focusPath: "src/form.tsx", expectedCount: 1, public: true }
+  ]
+};
 var SHADCN_PRIMITIVES = {
   button: "Button",
   dialog: "Dialog or AlertDialog family",
@@ -8362,6 +9574,7 @@ function replacementFor(node, element) {
 }
 var prefer_shadcn_primitives_default = createRule({
   name: "prefer-shadcn-primitives",
+  documentation: preferShadcnPrimitivesDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -8393,6 +9606,17 @@ var prefer_shadcn_primitives_default = createRule({
 
 // src/rules/prefer-module-level-constant.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES42 } from "@typescript-eslint/utils";
+var preferModuleLevelConstantDocumentation = {
+  summary: "Hoist literal-only constant collections and regexes out of function bodies to module scope so they are allocated once.",
+  rationale: "Recreating immutable lookup data on every call wastes allocations and obscures its constant nature.",
+  remediation: "Declare immutable literal collections and non-stateful regular expressions once at module scope.",
+  category: "performance",
+  limitations: ["Collections that are small, mutated, escape the function, or depend on local values are not reported."],
+  examples: [
+    { id: "hoisted-collection", title: "Hoist a constant collection", outcome: "no-match", files: [{ path: "src/keys.ts", source: "const KEYS = ['a', 'b', 'c'] as const; function isAllowed(key: string) { return KEYS.includes(key); }" }], focusPath: "src/keys.ts", expectedCount: 0, public: true },
+    { id: "local-collection", title: "Do not recreate a constant collection", outcome: "match", files: [{ path: "src/keys.ts", source: "function isAllowed(key: string) { const KEYS = ['a', 'b', 'c']; return KEYS.includes(key); }" }], focusPath: "src/keys.ts", expectedCount: 1, public: true }
+  ]
+};
 var DEFAULT_MIN_ELEMENTS = 3;
 var MAX_LITERAL_DEPTH = 4;
 var IGNORE_PATTERNS2 = [
@@ -8598,6 +9822,7 @@ function isNonRetainingBuiltinCall(node, argument) {
 }
 var prefer_module_level_constant_default = createRule({
   name: "prefer-module-level-constant",
+  documentation: preferModuleLevelConstantDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -8689,6 +9914,17 @@ var prefer_module_level_constant_default = createRule({
 
 // src/rules/prefer-module-level-schema.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES43 } from "@typescript-eslint/utils";
+var preferModuleLevelSchemaDocumentation = {
+  summary: "Declare a Zod schema at module scope when it closes over nothing in the enclosing function",
+  rationale: "A closed schema created inside a function is rebuilt on every call and cannot be reused or exported for inference.",
+  remediation: "Move the closed schema declaration to module scope and reference it from the function.",
+  category: "performance",
+  limitations: ["Schemas that depend on local state or are wrapped in a recognized memoization helper are excluded."],
+  examples: [
+    { id: "module-schema", title: "Declare the schema once", outcome: "no-match", files: [{ path: "src/handler.ts", source: "import { z } from 'zod'; const ZBody = z.object({ id: z.string(), name: z.string() }); export function handle(raw: unknown) { return ZBody.parse(raw); }" }], focusPath: "src/handler.ts", expectedCount: 0, public: true },
+    { id: "local-schema", title: "Do not rebuild a closed schema", outcome: "match", files: [{ path: "src/handler.ts", source: "import { z } from 'zod'; export function handle(raw: unknown) { const ZBody = z.object({ id: z.string(), name: z.string() }); return ZBody.parse(raw); }" }], focusPath: "src/handler.ts", expectedCount: 1, public: true }
+  ]
+};
 var DEFAULT_FACTORIES = [
   "discriminatedUnion",
   "intersection",
@@ -8835,6 +10071,7 @@ function collectReferences(scope, out) {
 }
 var prefer_module_level_schema_default = createRule({
   name: "prefer-module-level-schema",
+  documentation: preferModuleLevelSchemaDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -9032,11 +10269,24 @@ var prefer_module_level_schema_default = createRule({
 
 // src/rules/prefer-native-random-uuid.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES44, ASTUtils as ASTUtils8 } from "@typescript-eslint/utils";
+var preferNativeRandomUuidDocumentation = {
+  summary: "Prefer `globalThis.crypto.randomUUID()` over resolved zero-argument UUID v4 bindings from the `uuid` package.",
+  rationale: "The platform implementation avoids an unnecessary dependency for standard random UUID generation.",
+  remediation: "Call `globalThis.crypto.randomUUID()` and remove the unused `uuid` v4 import when possible.",
+  category: "maintainability",
+  autofix: "suggestion",
+  limitations: ["Only resolved zero-argument UUID v4 calls are reported; customized and other UUID versions are excluded."],
+  examples: [
+    { id: "native-random-uuid", title: "Use the platform UUID generator", outcome: "no-match", files: [{ path: "src/id.ts", source: "const id = globalThis.crypto.randomUUID();" }], focusPath: "src/id.ts", expectedCount: 0, public: true },
+    { id: "uuid-v4-package", title: "Do not call uuid v4 without options", outcome: "match", files: [{ path: "src/id.ts", source: "import { v4 } from 'uuid'; const id = v4();" }], focusPath: "src/id.ts", expectedCount: 1, public: true }
+  ]
+};
 function requireUuid(node) {
   return node?.type === AST_NODE_TYPES44.CallExpression && node.callee.type === AST_NODE_TYPES44.Identifier && node.callee.name === "require" && node.arguments.length === 1 && node.arguments[0]?.type === AST_NODE_TYPES44.Literal && node.arguments[0].value === "uuid";
 }
 var prefer_native_random_uuid_default = createRule({
   name: "prefer-native-random-uuid",
+  documentation: preferNativeRandomUuidDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -9118,6 +10368,17 @@ var prefer_native_random_uuid_default = createRule({
 
 // src/rules/prefer-non-nullable-collection.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES45, ASTUtils as ASTUtils9 } from "@typescript-eslint/utils";
+var preferNonNullableCollectionDocumentation = {
+  summary: "Suggest non-null arrays only when local control flow proves the nullish state is equivalent to an empty collection.",
+  rationale: "A redundant nullish collection state spreads defaults and guards through consumers without carrying information.",
+  remediation: "Use a non-null collection type and normalize omitted input to an empty collection at the boundary.",
+  category: "maintainability",
+  limitations: ["The rule requires local evidence that nullish and empty values are treated identically and skips exported wire shapes."],
+  examples: [
+    { id: "non-null-array", title: "Model an always-present collection", outcome: "no-match", files: [{ path: "src/search.ts", source: "interface Input { items: string[] } function search({ items }: Input) { return items.length; }" }], focusPath: "src/search.ts", expectedCount: 0, public: true },
+    { id: "defaulted-nullish-array", title: "Do not retain a redundant nullish state", outcome: "match", files: [{ path: "src/search.ts", source: "interface Input { items: string[] | undefined } function search({ items = [] }: Input) { return items.length; }" }], focusPath: "src/search.ts", expectedCount: 1, public: true }
+  ]
+};
 var ARRAY_TYPE_NAMES = /* @__PURE__ */ new Set(["Array", "ReadonlyArray"]);
 function propertyName(node) {
   const key = node.key;
@@ -9255,6 +10516,7 @@ function memberIsOnlyCoalesced(context, object, property, fn) {
 }
 var prefer_non_nullable_collection_default = createRule({
   name: "prefer-non-nullable-collection",
+  documentation: preferNonNullableCollectionDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -9351,6 +10613,17 @@ var prefer_non_nullable_collection_default = createRule({
 
 // src/rules/prefer-schema-for-api-payload.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES46 } from "@typescript-eslint/utils";
+var preferSchemaForApiPayloadDocumentation = {
+  summary: "Require Zod (or similar) schema validation on `response.json()` / `JSON.parse()` results before property access.",
+  rationale: "External JSON is untrusted at runtime even when its expected TypeScript shape is known statically.",
+  remediation: "Parse the payload through a schema or establish a recognized runtime validation guard before reading fields.",
+  category: "correctness",
+  limitations: ["Test fixtures, generated clients, local JSON files, and recognized validation guards are excluded."],
+  examples: [
+    { id: "validated-payload", title: "Validate before property access", outcome: "no-match", files: [{ path: "src/client.ts", source: "async function load(response) { const body = UserSchema.parse(await response.json()); return body.id; }" }], focusPath: "src/client.ts", expectedCount: 0, public: true },
+    { id: "unvalidated-payload", title: "Do not trust response JSON directly", outcome: "match", files: [{ path: "src/client.ts", source: "async function load(response) { const body = await response.json(); return body.id; }" }], focusPath: "src/client.ts", expectedCount: 1, public: true }
+  ]
+};
 var unwrap4 = (node) => {
   let current = node;
   while (current !== null && current !== void 0) {
@@ -9592,6 +10865,7 @@ var unvalidatedVariableRef = (node, scope, tracked) => {
 };
 var prefer_schema_for_api_payload_default = createRule({
   name: "prefer-schema-for-api-payload",
+  documentation: preferSchemaForApiPayloadDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -9794,6 +11068,17 @@ var tailwindBase = (token) => token.replace(/^(?:[a-z0-9-]+:)+/i, "").replace(/^
 var classTokens = (value) => value.split(/\s+/).filter(Boolean);
 
 // src/rules/prefer-semantic-colors.ts
+var preferSemanticColorsDocumentation = {
+  summary: "Enforce semantic color tokens over raw Tailwind palette classes, arbitrary color values, and inline color literals.",
+  rationale: "Semantic tokens keep themes and product meaning consistent while raw colors couple components to a palette value.",
+  remediation: "Replace raw palette and literal colors with the closest semantic design-system token or CSS variable.",
+  category: "style",
+  limitations: ["Email, PDF, icon artwork, masks, gradients, stories, and explicitly configured non-token projects have targeted exclusions."],
+  examples: [
+    { id: "semantic-text-color", title: "Use a semantic color token", outcome: "no-match", files: [{ path: "src/notice.tsx", source: 'const notice = <div className="text-destructive" />;' }], focusPath: "src/notice.tsx", expectedCount: 0, public: true },
+    { id: "raw-text-color", title: "Do not use a raw palette color", outcome: "match", files: [{ path: "src/notice.tsx", source: 'const notice = <div className="text-red-500" />;' }], focusPath: "src/notice.tsx", expectedCount: 1, public: true }
+  ]
+};
 var COLOR_PREFIXES = "text|bg|border(?:-[trblxyse])?|ring(?:-offset)?|fill|stroke|from|via|to|divide|decoration|placeholder|accent|caret|shadow|outline";
 var PALETTE = "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone";
 var COLOR_FN = "rgba?|hsla?|hwb|oklch|oklab|lab|lch|color";
@@ -10072,10 +11357,11 @@ var staticallyImportsEmailOrPdfRenderer = (program) => program.body.some((statem
 });
 var prefer_semantic_colors_default = createRule({
   name: "prefer-semantic-colors",
+  documentation: preferSemanticColorsDocumentation,
   meta: {
     type: "suggestion",
     docs: {
-      description: "Enforce design-system semantic color tokens (bg-primary, text-destructive, \u2026) over raw Tailwind palette classes (text-red-500), arbitrary color values (bg-[#fff]), and inline color literals."
+      description: "Enforce semantic color tokens over raw Tailwind palette classes, arbitrary color values, and inline color literals."
     },
     schema: [
       {
@@ -10210,6 +11496,17 @@ var prefer_semantic_colors_default = createRule({
 
 // src/rules/prefer-server-actions.ts
 import "@typescript-eslint/utils";
+var preferServerActionsDocumentation = {
+  summary: "Prefer Next.js Server Actions over /api/* mutations.",
+  rationale: "Server Actions preserve typed application calls and avoid an internal JSON request-response boundary.",
+  remediation: "Move the mutation into a Server Action and invoke that action from the React client.",
+  category: "architecture",
+  limitations: ["Only statically recognizable /api/ mutations in applicable React modules are reported."],
+  examples: [
+    { id: "server-action-call", title: "Call a Server Action", outcome: "no-match", files: [{ path: "app/tasks/page.tsx", source: "import { createTask } from './actions'; await createTask(input);" }], focusPath: "app/tasks/page.tsx", expectedCount: 0, public: true },
+    { id: "api-mutation", title: "Do not mutate through an API route", outcome: "match", files: [{ path: "app/tasks/page.tsx", source: "await fetch('/api/tasks', { method: 'POST', body });" }], focusPath: "app/tasks/page.tsx", expectedCount: 1, public: true }
+  ]
+};
 var MUTATION_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "DELETE", "PATCH"]);
 var AXIOS_MUTATION_METHODS = /* @__PURE__ */ new Set(["post", "put", "delete", "patch"]);
 var SKIP_FILE_REGEX = /(?:\.test\.[jt]sx?$|\.spec\.[jt]sx?$|-(?:test|spec)\.[jt]sx?$|\/tests?\/|\/__tests__\/|\/__testfixtures__\/|\/scripts?\/|\/app\/api\/.*\/route\.[jt]sx?$|\/pages\/api\/)/;
@@ -10307,6 +11604,7 @@ function getPropertyNode(objNode, propName2) {
 }
 var prefer_server_actions_default = createRule({
   name: "prefer-server-actions",
+  documentation: preferServerActionsDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -10382,6 +11680,18 @@ var COLLECTION_PROPERTIES = /* @__PURE__ */ new Set(["length", "size"]);
 var LITERAL_KEY_HAZARDS = /* @__PURE__ */ new Set(["__proto__"]);
 var NUMERIC_SIGNS2 = /* @__PURE__ */ new Set(["-", "+"]);
 var MIN_RUN_LENGTH = 2;
+var preferWholeObjectAssertionDocumentation = {
+  summary: "Collapse consecutive assertions on one object into a whole-object assertion so related mismatches are reported together.",
+  rationale: "One whole-object assertion presents related expectations together and produces a complete structural diff.",
+  remediation: "Replace consecutive member assertions with one `toMatchObject` assertion.",
+  category: "testing",
+  aliases: ["strict-test-assertions"],
+  autofix: "safe",
+  examples: [
+    { id: "whole-object", title: "Assert the object once", outcome: "no-match", files: [{ path: "src/user.test.ts", source: "expect(user).toMatchObject({ id: 1, name: 'Ada' });" }], focusPath: "src/user.test.ts", expectedCount: 0, public: true },
+    { id: "member-run", title: "Do not split one object across assertions", outcome: "match", files: [{ path: "src/user.test.ts", source: "expect(user.id).toBe(1);\nexpect(user.name).toBe('Ada');" }], focusPath: "src/user.test.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/user.test.ts", source: "expect(user).toMatchObject({ id: 1, name: 'Ada' });\n" }] }
+  ]
+};
 function literalText(node, getText) {
   switch (node.type) {
     case AST_NODE_TYPES48.Literal:
@@ -10419,10 +11729,11 @@ function literalIndex(node) {
 }
 var prefer_whole_object_assertion_default = createRule({
   name: "prefer-whole-object-assertion",
+  documentation: preferWholeObjectAssertionDocumentation,
   meta: {
     type: "suggestion",
     docs: {
-      description: "Collapse a run of consecutive assertions on the same object into one assertion about the whole object, so every mismatch is reported and nothing outside the asserted keys goes unchecked."
+      description: "Collapse consecutive assertions on one object into a whole-object assertion so related mismatches are reported together."
     },
     fixable: "code",
     messages: {
@@ -10597,6 +11908,16 @@ var prefer_whole_object_assertion_default = createRule({
 
 // src/rules/prefer-zod-infer.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES49 } from "@typescript-eslint/utils";
+var preferZodInferDocumentation = {
+  summary: "Derive a type from its Zod schema with `z.infer` instead of hand-writing a twin declaration beside it.",
+  rationale: "A derived type stays synchronized when the runtime schema changes.",
+  remediation: "Replace the hand-written twin with `z.infer<typeof Schema>`.",
+  category: "correctness",
+  examples: [
+    { id: "inferred-type", title: "Infer the schema type", outcome: "no-match", files: [{ path: "src/user.ts", source: 'import { z } from "zod"; const UserSchema = z.object({ id: z.string() }); type User = z.infer<typeof UserSchema>;' }], focusPath: "src/user.ts", expectedCount: 0, public: true },
+    { id: "handwritten-twin", title: "Do not duplicate the schema shape", outcome: "match", files: [{ path: "src/user.ts", source: 'import { z } from "zod"; const UserSchema = z.object({ id: z.string() }); interface User { id: string }' }], focusPath: "src/user.ts", expectedCount: 1, public: true }
+  ]
+};
 var SHAPE_PRESERVING_METHODS = /* @__PURE__ */ new Set([
   "describe",
   "refine",
@@ -10722,6 +12043,7 @@ function leafAgrees(leaf, annotation) {
 }
 var prefer_zod_infer_default = createRule({
   name: "prefer-zod-infer",
+  documentation: preferZodInferDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -11010,6 +12332,16 @@ import {
   AST_NODE_TYPES as AST_NODE_TYPES50
 } from "@typescript-eslint/utils";
 import ts2 from "typescript";
+var requireAssertNeverDocumentation = {
+  summary: "Require an empty switch default to call `assertNever` so discriminated unions remain exhaustive at compile time.",
+  rationale: "An empty default silently accepts new union members instead of making the compiler identify the missing case.",
+  remediation: "Call `assertNever` with the discriminant in the exhaustive switch default.",
+  category: "correctness",
+  examples: [
+    { id: "assert-never-default", title: "Make the default exhaustive", outcome: "no-match", files: [{ path: "src/render.ts", source: "declare const kind: 'a' | 'b';\nswitch (kind) { case 'a': break; case 'b': break; default: assertNever(kind); }" }], focusPath: "src/render.ts", expectedCount: 0, public: true },
+    { id: "empty-default", title: "Do not leave an exhaustive default empty", outcome: "match", files: [{ path: "src/render.ts", source: "declare const kind: 'a' | 'b';\nswitch (kind) { case 'a': break; case 'b': break; default: }" }], focusPath: "src/render.ts", expectedCount: 1, public: true }
+  ]
+};
 var isRuntimeHandlingStatement = (statement) => {
   if (statement.type === AST_NODE_TYPES50.EmptyStatement) return false;
   if (statement.type === AST_NODE_TYPES50.TSTypeAliasDeclaration || statement.type === AST_NODE_TYPES50.TSInterfaceDeclaration) {
@@ -11067,10 +12399,11 @@ function finiteTypeKey(type, checker) {
 }
 var require_assert_never_default = createRule({
   name: "require-assert-never",
+  documentation: requireAssertNeverDocumentation,
   meta: {
     type: "problem",
     docs: {
-      description: "Require an exhaustive-style switch whose `default` case does no runtime work to call `assertNever(_)` so that discriminated unions are exhaustively checked at compile time. Switches with a legitimate runtime default (a reducer's `return state`, an HTTP-status `return fallback()`, a `break`, a `throw`, etc.) are left alone."
+      description: "Require an empty switch default to call `assertNever` so discriminated unions remain exhaustive at compile time."
     },
     schema: [],
     messages: {
@@ -11108,6 +12441,16 @@ var require_assert_never_default = createRule({
 
 // src/rules/require-fetch-timeout.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES51, ASTUtils as ASTUtils10 } from "@typescript-eslint/utils";
+var requireFetchTimeoutDocumentation = {
+  summary: "Require an abort `signal` (e.g. `AbortSignal.timeout(ms)`) on global `fetch()` calls so stalled upstreams cannot hang the caller forever.",
+  rationale: "An unbounded request can occupy work indefinitely when an upstream stalls.",
+  remediation: "Pass an abort signal, such as `AbortSignal.timeout(ms)`, in the fetch init.",
+  category: "correctness",
+  examples: [
+    { id: "bounded-fetch", title: "Bound the request", outcome: "no-match", files: [{ path: "src/client.ts", source: "await fetch(url, { signal: AbortSignal.timeout(5000) });" }], focusPath: "src/client.ts", expectedCount: 0, public: true },
+    { id: "unbounded-fetch", title: "Do not leave fetch unbounded", outcome: "match", files: [{ path: "src/client.ts", source: "await fetch('https://api.example.com/items');" }], focusPath: "src/client.ts", expectedCount: 1, public: true }
+  ]
+};
 var GLOBAL_OBJECTS2 = /* @__PURE__ */ new Set([
   "globalThis",
   "window",
@@ -11144,6 +12487,7 @@ function isInlineUrl(node, resolvesToGlobal) {
 }
 var require_fetch_timeout_default = createRule({
   name: "require-fetch-timeout",
+  documentation: requireFetchTimeoutDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -11203,8 +12547,19 @@ var require_fetch_timeout_default = createRule({
   }
 });
 
-// src/rules/require-interface-for-injected-service.ts
+// src/rules/require-port-for-service.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES52 } from "@typescript-eslint/utils";
+var requirePortForServiceDocumentation = {
+  summary: "Advise when an exported service with injected collaborators has public methods not covered by its declared ports.",
+  rationale: "A declared port keeps consumers coupled to the service capability instead of its concrete implementation.",
+  remediation: "Declare and implement an interface covering the service's public methods.",
+  category: "architecture",
+  aliases: ["require-interface-for-injected-service"],
+  examples: [
+    { id: "declared-service-port", title: "Implement the service port", outcome: "no-match", files: [{ path: "src/service.ts", source: "interface Handler { handle(): void }\nexport class RequestHandler implements Handler { constructor(private readonly store: TaskStore) {} handle(): void { this.store.handle(); } }" }], focusPath: "src/service.ts", expectedCount: 0, public: true },
+    { id: "concrete-injected-service", title: "Do not expose only the concrete service", outcome: "match", files: [{ path: "src/service.ts", source: "export class RequestHandler { constructor(private readonly store: TaskStore) {} handle(): void { this.store.handle(); } }" }], focusPath: "src/service.ts", expectedCount: 1, public: true }
+  ]
+};
 var CONFIGISH_TYPE_RE = /(?:Options|Opts|Config|Configuration|Settings|Params|Props|Args|Env|Environment|Callbacks|Flags)$/;
 var CONFIGISH_NAME_RE = /^(?:options|opts|config|configuration|settings|params|props|args|env|environment|callbacks|flags|logger|log|clock)$/i;
 var HTTP_TRANSPORT_TYPE_RE = /^(?:KyInstance|AxiosInstance|Session)$/;
@@ -11643,8 +12998,9 @@ function hasServicePort(node, methods, classes, interfaces) {
   }
   return methods.every((method) => combined.has(method));
 }
-var require_interface_for_injected_service_default = createRule({
-  name: "require-interface-for-injected-service",
+var require_port_for_service_default = createRule({
+  name: "require-port-for-service",
+  documentation: requirePortForServiceDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -11709,6 +13065,16 @@ var require_interface_for_injected_service_default = createRule({
 
 // src/rules/require-static-next-matcher.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES53 } from "@typescript-eslint/utils";
+var requireStaticNextMatcherDocumentation = {
+  summary: "Require Next.js middleware and proxy matcher configuration to contain only build-time literals.",
+  rationale: "Next.js must statically analyze matcher values at build time; computed values are ignored.",
+  remediation: "Write matcher strings, arrays, and object fields as literals in the exported config.",
+  category: "correctness",
+  examples: [
+    { id: "literal-matcher", title: "Use a literal matcher", outcome: "no-match", files: [{ path: "src/middleware.ts", source: 'export const config = { matcher: "/api/:path*" };' }], focusPath: "src/middleware.ts", expectedCount: 0, public: true },
+    { id: "computed-matcher", title: "Do not compute the matcher", outcome: "match", files: [{ path: "src/middleware.ts", source: 'const matcher = "/api/:path*"; export const config = { matcher };' }], focusPath: "src/middleware.ts", expectedCount: 1, public: true }
+  ]
+};
 var NEXT_ENTRY_FILE = /(?:^|[/\\])(?:middleware|proxy)\.[cm]?[jt]sx?$/u;
 function unwrapExpression3(node) {
   if (node.type === AST_NODE_TYPES53.TSAsExpression || node.type === AST_NODE_TYPES53.TSSatisfiesExpression || node.type === AST_NODE_TYPES53.TSNonNullExpression || node.type === AST_NODE_TYPES53.TSTypeAssertion) {
@@ -11743,6 +13109,7 @@ function propertyName2(property) {
 }
 var require_static_next_matcher_default = createRule({
   name: "require-static-next-matcher",
+  documentation: requireStaticNextMatcherDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -11787,6 +13154,16 @@ var require_static_next_matcher_default = createRule({
 
 // src/rules/require-zod-form-validation.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES54 } from "@typescript-eslint/utils";
+var requireZodFormValidationDocumentation = {
+  summary: "Require Zod validation (`Schema.parse(...)` / `Schema.safeParse(...)`) when reading values out of a `FormData` object.",
+  rationale: "FormData values are untrusted strings or files and need runtime validation before use.",
+  remediation: "Read the value inside a Zod schema's `parse` or `safeParse` input.",
+  category: "security",
+  examples: [
+    { id: "validated-form-value", title: "Validate the form value", outcome: "no-match", files: [{ path: "src/action.ts", source: "const input = UserSchema.parse({ name: formData.get('name') });" }], focusPath: "src/action.ts", expectedCount: 0, public: true },
+    { id: "raw-form-value", title: "Do not use a raw form value", outcome: "match", files: [{ path: "src/action.ts", source: "const name = formData.get('name');" }], focusPath: "src/action.ts", expectedCount: 1, public: true }
+  ]
+};
 var isZodParseCall = (node) => {
   if (node.type !== AST_NODE_TYPES54.CallExpression) return false;
   const callee = node.callee;
@@ -11827,6 +13204,7 @@ var isFormDataMethodCall = (node) => {
 };
 var require_zod_form_validation_default = createRule({
   name: "require-zod-form-validation",
+  documentation: requireZodFormValidationDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -11915,11 +13293,22 @@ var require_zod_form_validation_default = createRule({
 
 // src/rules/store-insert-requires-on-conflict.ts
 import "@typescript-eslint/utils";
+var storeInsertRequiresOnConflictDocumentation = {
+  summary: "Require an embedded SQL INSERT to carry ON CONFLICT; store writes replay under cron re-runs and queue redelivery and must be idempotent upserts.",
+  rationale: "A replayed bare insert can duplicate data or fail on a uniqueness constraint.",
+  remediation: "Add an appropriate `ON CONFLICT` action or supported replay-safe insert form.",
+  category: "correctness",
+  examples: [
+    { id: "conflict-safe-insert", title: "Handle a replayed insert", outcome: "no-match", files: [{ path: "src/store.ts", source: "db.prepare(`INSERT INTO runs (id) VALUES (?) ON CONFLICT(id) DO NOTHING`).run();" }], focusPath: "src/store.ts", expectedCount: 0, public: true },
+    { id: "bare-insert", title: "Do not issue a replay-unsafe insert", outcome: "match", files: [{ path: "src/store.ts", source: "db.prepare(`INSERT INTO runs (id) VALUES (?)`).run();" }], focusPath: "src/store.ts", expectedCount: 1, public: true }
+  ]
+};
 var INSERT_WRITE = /\bINSERT\s+(?:OR\s+\w+\s+)?INTO\s+[\w."'`?$:@-]+\s*(?:\([^)]*\)\s*)?(?:VALUES|SELECT|DEFAULT\s+VALUES)\b/i;
 var CONFLICT_HANDLED = /\bON\s+CONFLICT\b|\bON\s+DUPLICATE\s+KEY\b|\bINSERT\s+OR\s+(?:IGNORE|REPLACE)\b/i;
 var INSERT_GATE = /insert/i;
 var store_insert_requires_on_conflict_default = createRule({
   name: "store-insert-requires-on-conflict",
+  documentation: storeInsertRequiresOnConflictDocumentation,
   meta: {
     type: "problem",
     docs: {
@@ -11946,6 +13335,16 @@ var store_insert_requires_on_conflict_default = createRule({
 
 // src/rules/stepdown.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES55, ASTUtils as ASTUtils11 } from "@typescript-eslint/utils";
+var stepdownDocumentation = {
+  summary: "Place a private helper below its sole direct same-scope caller.",
+  rationale: "Caller-first ordering lets a reader follow the main flow before descending into implementation details.",
+  remediation: "Move the private helper immediately below its sole caller.",
+  category: "maintainability",
+  examples: [
+    { id: "caller-before-helper", title: "Place the caller first", outcome: "no-match", files: [{ path: "src/run.ts", source: "function run() { return load(); }\nfunction load() { return 1; }" }], focusPath: "src/run.ts", expectedCount: 0, public: true },
+    { id: "helper-before-caller", title: "Do not lead with a sole-caller helper", outcome: "match", files: [{ path: "src/run.ts", source: "function load() { return 1; }\nfunction run() { return load(); }" }], focusPath: "src/run.ts", expectedCount: 1, public: true }
+  ]
+};
 function isFunction(node) {
   return node.type === AST_NODE_TYPES55.ArrowFunctionExpression || node.type === AST_NODE_TYPES55.FunctionDeclaration || node.type === AST_NODE_TYPES55.FunctionExpression;
 }
@@ -12300,6 +13699,7 @@ function classScope(context, node, computedReferenceNames) {
 }
 var stepdown_default = createRule({
   name: "stepdown",
+  documentation: stepdownDocumentation,
   meta: {
     type: "suggestion",
     docs: { description: "Place a private helper below its sole direct same-scope caller." },
@@ -12336,6 +13736,16 @@ import {
   AST_NODE_TYPES as AST_NODE_TYPES56,
   ASTUtils as ASTUtils12
 } from "@typescript-eslint/utils";
+var zodNamingConventionDocumentation = {
+  summary: "Enforce a consistent Zod schema naming convention \u2014 a `Z` prefix (`ZUser`) or a `Schema` suffix (`userSchema`); both are accepted by default.",
+  rationale: "A recognizable schema name distinguishes runtime validators from ordinary values at each use site.",
+  remediation: "Rename the schema with a `Z` prefix or `Schema` suffix, according to the configured convention.",
+  category: "style",
+  examples: [
+    { id: "recognizable-schema-name", title: "Mark the value as a schema", outcome: "no-match", files: [{ path: "src/user.ts", source: "import { z } from 'zod';\nconst userSchema = z.object({ id: z.string() });" }], focusPath: "src/user.ts", expectedCount: 0, public: true },
+    { id: "unmarked-schema-name", title: "Do not hide the schema behind a value name", outcome: "match", files: [{ path: "src/user.ts", source: "import { z } from 'zod';\nconst user = z.object({ id: z.string() });" }], focusPath: "src/user.ts", expectedCount: 1, public: true }
+  ]
+};
 var CONVENTIONS = {
   prefix: { test: ZOD_PREFIX_RE, messageId: "zPrefix" },
   suffix: { test: ZOD_SUFFIX_RE, messageId: "schemaSuffix" },
@@ -12380,6 +13790,7 @@ var calleeChainRoot = (node) => {
 };
 var zod_naming_convention_default = createRule({
   name: "zod-naming-convention",
+  documentation: zodNamingConventionDocumentation,
   meta: {
     type: "suggestion",
     docs: {
@@ -12462,6 +13873,7 @@ var zod_naming_convention_default = createRule({
 var renamedRules = {
   "jsdoc-restates-signature": "no-restated-jsdoc",
   "no-async-callback-in-waitfor": "no-async-callback-in-wait-for",
+  "require-interface-for-injected-service": "require-port-for-service",
   "strict-test-assertions": "prefer-whole-object-assertion",
   "trailing-value-narration": "no-trailing-value-narration"
 };
@@ -12587,7 +13999,7 @@ var rules = {
   "prefer-zod-infer": prefer_zod_infer_default,
   "require-assert-never": require_assert_never_default,
   "require-fetch-timeout": require_fetch_timeout_default,
-  "require-interface-for-injected-service": require_interface_for_injected_service_default,
+  "require-port-for-service": require_port_for_service_default,
   "require-static-next-matcher": require_static_next_matcher_default,
   "require-zod-form-validation": require_zod_form_validation_default,
   "store-insert-requires-on-conflict": store_insert_requires_on_conflict_default,
@@ -12596,7 +14008,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "12.0.0"
+  version: "13.1.0"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",
@@ -12656,7 +14068,7 @@ var recommendedRules = {
   "@sarj/prefer-zod-infer": "error",
   "@sarj/require-assert-never": "error",
   "@sarj/require-fetch-timeout": "error",
-  "@sarj/require-interface-for-injected-service": "error",
+  "@sarj/require-port-for-service": "error",
   "@sarj/require-static-next-matcher": "error",
   "@sarj/require-zod-form-validation": "error",
   "@sarj/store-insert-requires-on-conflict": "error",
@@ -12720,7 +14132,7 @@ var strictRules = {
   "@sarj/prefer-zod-infer": "error",
   "@sarj/require-assert-never": "error",
   "@sarj/require-fetch-timeout": "error",
-  "@sarj/require-interface-for-injected-service": "error",
+  "@sarj/require-port-for-service": "error",
   "@sarj/require-static-next-matcher": "error",
   "@sarj/require-zod-form-validation": "error",
   "@sarj/store-insert-requires-on-conflict": "error",
@@ -12750,6 +14162,7 @@ var index_default = plugin;
 export {
   applicationOnlyRules,
   index_default as default,
+  publicDocumentation,
   recommendedRules,
   renamedRules,
   retiredRules,