@sarj/eslint-plugin 15.17.4 → 15.17.6

package/dist/index.cjs

@@ -49,6 +49,214 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/library-policy.ts
+var LIBRARY_POLICY = [
+  {
+    "id": "LIB101",
+    "module": "request",
+    "note": "Standards standardizes HTTP clients on Ky; review errors, retries, hooks, and response parsing.",
+    "replacement": "ky"
+  },
+  {
+    "id": "LIB101",
+    "module": "node-fetch",
+    "note": "Standards standardizes HTTP clients on Ky; review errors, retries, hooks, and response parsing.",
+    "replacement": "ky"
+  },
+  {
+    "id": "LIB101",
+    "module": "cross-fetch",
+    "note": "Standards standardizes HTTP clients on Ky; review errors, retries, hooks, and response parsing.",
+    "replacement": "ky"
+  },
+  {
+    "id": "LIB101",
+    "module": "isomorphic-fetch",
+    "note": "Standards standardizes HTTP clients on Ky; review errors, retries, hooks, and response parsing.",
+    "replacement": "ky"
+  },
+  {
+    "id": "LIB101",
+    "module": "axios",
+    "note": "Standards standardizes HTTP clients on Ky; review errors, retries, hooks, and response parsing.",
+    "replacement": "ky"
+  },
+  {
+    "id": "LIB102",
+    "module": "moment",
+    "note": "Standards standardizes date utilities on date-fns; migration is not API-compatible.",
+    "replacement": "date-fns"
+  },
+  {
+    "id": "LIB102",
+    "module": "dayjs",
+    "note": "Standards standardizes date utilities on date-fns; migration is not API-compatible.",
+    "replacement": "date-fns"
+  },
+  {
+    "id": "LIB103",
+    "module": "lodash",
+    "note": "Standards standardizes collection utilities on Remeda and native APIs.",
+    "replacement": "remeda"
+  },
+  {
+    "id": "LIB103",
+    "module": "lodash-es",
+    "note": "Standards standardizes collection utilities on Remeda and native APIs.",
+    "replacement": "remeda"
+  },
+  {
+    "id": "LIB103",
+    "module": "underscore",
+    "note": "Standards standardizes collection utilities on Remeda and native APIs.",
+    "replacement": "remeda"
+  },
+  {
+    "id": "LIB104",
+    "module": "classnames",
+    "note": "Use clsx for conditional class-name composition.",
+    "replacement": "clsx"
+  },
+  {
+    "id": "LIB105",
+    "module": "joi",
+    "note": "Standards standardizes runtime validation on Zod; schemas are not drop-in compatible.",
+    "replacement": "zod"
+  },
+  {
+    "id": "LIB105",
+    "module": "yup",
+    "note": "Standards standardizes runtime validation on Zod; schemas are not drop-in compatible.",
+    "replacement": "zod"
+  },
+  {
+    "id": "LIB105",
+    "module": "superstruct",
+    "note": "Standards standardizes runtime validation on Zod; schemas are not drop-in compatible.",
+    "replacement": "zod"
+  },
+  {
+    "id": "LIB105",
+    "module": "io-ts",
+    "note": "Standards standardizes runtime validation on Zod; schemas are not drop-in compatible.",
+    "replacement": "zod"
+  },
+  {
+    "id": "LIB105",
+    "module": "runtypes",
+    "note": "Standards standardizes runtime validation on Zod; schemas are not drop-in compatible.",
+    "replacement": "zod"
+  },
+  {
+    "id": "LIB106",
+    "module": "jsonwebtoken",
+    "note": "Use jose; review key formats and async signing and verification APIs.",
+    "replacement": "jose"
+  },
+  {
+    "id": "LIB107",
+    "module": "express",
+    "note": "Standards standardizes servers on Hono; Node deployments also need @hono/node-server.",
+    "replacement": "hono"
+  },
+  {
+    "id": "LIB107",
+    "module": "koa",
+    "note": "Standards standardizes servers on Hono; Node deployments also need @hono/node-server.",
+    "replacement": "hono"
+  },
+  {
+    "id": "LIB108",
+    "module": "jest",
+    "note": "Standards standardizes tests on Vitest; review globals, timers, mocks, and environment setup.",
+    "replacement": "vitest"
+  },
+  {
+    "id": "LIB108",
+    "module": "mocha",
+    "note": "Standards standardizes tests on Vitest; review globals, timers, mocks, and environment setup.",
+    "replacement": "vitest"
+  },
+  {
+    "id": "LIB109",
+    "module": "sinon",
+    "note": "Use Vitest spies, mocks, and fake timers instead of Sinon.",
+    "replacement": "Vitest mocks"
+  },
+  {
+    "id": "LIB110",
+    "module": "commander",
+    "note": "Standards standardizes command-line interfaces on citty.",
+    "replacement": "citty"
+  },
+  {
+    "id": "LIB110",
+    "module": "yargs",
+    "note": "Standards standardizes command-line interfaces on citty.",
+    "replacement": "citty"
+  },
+  {
+    "id": "LIB111",
+    "module": "bluebird",
+    "note": "Use native Promise, adding p-limit or p-map only for the extensions actually needed.",
+    "replacement": "native Promise"
+  },
+  {
+    "id": "LIB112",
+    "module": "rimraf",
+    "note": "Prefer node:fs/promises; verify recursive removal, copy, path, and error semantics.",
+    "replacement": "node:fs/promises"
+  },
+  {
+    "id": "LIB112",
+    "module": "fs-extra",
+    "note": "Prefer node:fs/promises; verify recursive removal, copy, path, and error semantics.",
+    "replacement": "node:fs/promises"
+  },
+  {
+    "id": "LIB113",
+    "module": "abort-controller",
+    "note": "Node 22 provides global AbortController.",
+    "replacement": "AbortController"
+  },
+  {
+    "id": "LIB114",
+    "module": "querystring",
+    "note": "Use URLSearchParams and explicitly review repeated keys, escaping, arrays, and object coercion.",
+    "replacement": "URLSearchParams"
+  },
+  {
+    "id": "LIB115",
+    "module": "dotenv",
+    "note": "Standards standardizes environment loading on @dotenvx/dotenvx.",
+    "replacement": "@dotenvx/dotenvx"
+  },
+  {
+    "id": "LIB116",
+    "module": "chalk",
+    "note": "Use picocolors for terminal colors.",
+    "replacement": "picocolors"
+  },
+  {
+    "id": "LIB117",
+    "module": "faker",
+    "note": "The original faker package is abandoned; use @faker-js/faker.",
+    "replacement": "@faker-js/faker"
+  },
+  {
+    "id": "LIB118",
+    "module": "node-sass",
+    "note": "node-sass is end-of-life; use Dart Sass.",
+    "replacement": "sass"
+  },
+  {
+    "id": "LIB119",
+    "module": "tslint",
+    "note": "TSLint is deprecated; use ESLint with typescript-eslint.",
+    "replacement": "eslint"
+  }
+];
+
 // src/rules/enforce-file-structure.ts
 var import_utils2 = require("@typescript-eslint/utils");
 
@@ -1240,6 +1448,10 @@ function normalizeToken(word) {
   return lower.length > TOKEN_PLURAL_MIN && lower.endsWith("s") && !lower.endsWith("ss") ? lower.slice(0, -1) : lower;
 }
 function restatableStatementBelow(comment, sourceCode) {
+  const node = restatableStatementNodeBelow(comment, sourceCode);
+  return node === null ? null : sourceCode.getText(node);
+}
+function restatableStatementNodeBelow(comment, sourceCode) {
   const token = sourceCode.getTokenAfter(comment, { includeComments: false });
   if (token === null || token.loc.start.line !== comment.loc.end.line + 1) return null;
   for (let node = sourceCode.getNodeByRangeIndex(token.range[0]); node != null && node.type !== import_utils7.AST_NODE_TYPES.Program; node = node.parent) {
@@ -1250,7 +1462,7 @@ function restatableStatementBelow(comment, sourceCode) {
     if (node.type === import_utils7.AST_NODE_TYPES.VariableDeclaration && isTrivialInitializer(node)) {
       return null;
     }
-    return sourceCode.getText(node);
+    return node;
   }
   return null;
 }
@@ -6508,25 +6720,31 @@ var MODALITY_RE = /\b(?:can|could|should|shall|may|might|must|will|would|cannot)
 var LEAD_IN_RE = /:$/;
 var EMPHASIS_RE = /\*\w[^*]*\*|`[^`]+`/;
 var NEGATION_WORD_RE = /\b(?:no|not|never|neither|nor|without|none|non)\b/i;
+var SEMANTIC_RELATION_RE = /\b(?:only|if|unless|when|while|except|each|every|any|all|before|after|until|since|again|once|twice|already|still|from|to|into|onto|back|versus|rather|instead)\b/i;
 var ACTION_STMT_RE = /[\w.$\])]\s*\(|^\s*(?:return|throw|await|yield)\b/;
 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 NO_RESTATED_COMMENT_DOCUMENTATION = {
-  summary: "Flag a single-line comment whose every word already appears on the statement below it.",
+  summary: "Flag short standalone comments that repeat the adjacent statement's identifiers.",
   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.",
+  remediation: "Remove a genuine restatement; retain conditions, constraints, rationale, and information absent from the statement.",
   category: "maintainability",
   autofix: "suggestion",
-  limitations: ["Directives, protected references, questions, multi-line prose, comments with novel content, and generated files are excluded."],
+  limitations: [
+    "Only standalone line comments of two to eight words with at least two content tokens directly above a supported single-line statement are inspected; one-word headings and sentence-ending punctuation are excluded.",
+    "Evidence comes from that statement's identifier tokens, not strings, template text, comments, or neighboring statements. Stopwords and inflection folding are heuristic, not proof of semantic equivalence.",
+    "Directives, protected references, conditions, restrictions, ordering, repetition, direction, questions, prose paragraphs, sibling-group labels, novel content, and generated files are excluded. Deletion is an optional suggestion, never an automatic fix.",
+    "The conservative sibling-group exemption includes enclosing sibling groups and declaration/type-query pairs; it can miss genuine restatements inside those groups."
+  ],
   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: "reason-comment", title: "Keep a condition the statement does not establish", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// Serialize key only after validation.\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;
+function areAdjacentLineComments2(a, b, isStandalone) {
+  return a !== void 0 && b !== void 0 && a.type === "Line" && b.type === "Line" && isStandalone(a) && isStandalone(b) && b.loc.start.line === a.loc.end.line + 1;
 }
 function headsSiblingRun(node) {
   const parent = node.parent;
@@ -6544,12 +6762,12 @@ var no_restated_comment_default = createRule({
     type: "suggestion",
     hasSuggestions: true,
     docs: {
-      description: "Flag a single-line comment whose every word already appears on the statement below it."
+      description: NO_RESTATED_COMMENT_DOCUMENTATION.summary
     },
     schema: [],
     messages: {
       deleteComment: "Delete the redundant comment.",
-      restatesLineBelow: "Comment restates the statement below it \u2014 delete it, or replace it with the *why*; the code already carries the *what*."
+      restatesLineBelow: "Comment repeats the adjacent statement's identifiers \u2014 consider removing it; retain any condition, constraint, or rationale absent from the code."
     }
   },
   defaultOptions: [],
@@ -6558,19 +6776,30 @@ var no_restated_comment_default = createRule({
       return {};
     }
     const sourceCode = context.sourceCode;
-    const lines = sourceCode.lines;
     function isStandalone(comment) {
       const before = sourceCode.getTokenBefore(comment, { includeComments: false });
       return !before || before.loc.end.line < comment.loc.start.line;
     }
-    function labelsASiblingRun(comment) {
-      const token = sourceCode.getTokenAfter(comment, { includeComments: false });
-      if (token === null) return false;
-      for (let node = sourceCode.getNodeByRangeIndex(token.range[0]); node != null && node.type !== import_utils38.AST_NODE_TYPES.Program; node = node.parent) {
+    function labelsASiblingRun(statement) {
+      for (let node = statement; node !== void 0 && node.type !== import_utils38.AST_NODE_TYPES.Program; node = node.parent) {
         if (headsSiblingRun(node)) return true;
       }
       return false;
     }
+    function headsValueTypeGroup(statement) {
+      if (statement.type !== import_utils38.AST_NODE_TYPES.VariableDeclaration) return false;
+      const parent = statement.parent;
+      if (!("body" in parent) || !Array.isArray(parent.body)) return false;
+      const body2 = parent.body;
+      const next = body2[body2.indexOf(statement) + 1];
+      if (next?.type !== import_utils38.AST_NODE_TYPES.TSTypeAliasDeclaration) return false;
+      const names = new Set(statement.declarations.flatMap(({ id }) => id.type === import_utils38.AST_NODE_TYPES.Identifier ? [id.name] : []));
+      const tokens = sourceCode.getTokens(next);
+      return tokens.some((token, index) => {
+        const nextToken = tokens[index + 1];
+        return token.value === "typeof" && nextToken?.type === import_utils38.AST_TOKEN_TYPES.Identifier && names.has(nextToken.value);
+      });
+    }
     return {
       Program() {
         const comments = sourceCode.getAllComments();
@@ -6598,7 +6827,7 @@ var no_restated_comment_default = createRule({
           if (comment === void 0 || comment.type !== "Line") continue;
           if (wallMembers.has(comment)) continue;
           if (!isStandalone(comment)) continue;
-          if (areAdjacentLineComments2(comments[i - 1], comment) || areAdjacentLineComments2(comment, comments[i + 1])) {
+          if (areAdjacentLineComments2(comments[i - 1], comment, isStandalone) || areAdjacentLineComments2(comment, comments[i + 1], isStandalone)) {
             continue;
           }
           const body2 = comment.value.replace(/^\/*/, "").trim();
@@ -6606,17 +6835,19 @@ var no_restated_comment_default = createRule({
           if (DIRECTIVE_RE3.test(body2) || CODEY_RE.test(body2) || BANNERISH_RE.test(body2)) continue;
           if (NON_ASCII_LETTER_RE.test(body2) || isProtected(body2)) continue;
           if (MODALITY_RE.test(body2) || LEAD_IN_RE.test(body2) || EMPHASIS_RE.test(body2)) continue;
-          if (NEGATION_WORD_RE.test(body2)) continue;
-          if (body2.split(/\s+/).length > MAX_WORDS) continue;
+          if (NEGATION_WORD_RE.test(body2) || SEMANTIC_RELATION_RE.test(body2)) continue;
+          const wordCount2 = body2.split(/\s+/).length;
+          if (wordCount2 < 2 || wordCount2 > MAX_WORDS || /[.!?]$/.test(body2)) continue;
           const tokens = contentTokens(body2);
           if (tokens.length < MIN_CONTENT_TOKENS) continue;
-          const statement = restatableStatementBelow(comment, sourceCode);
-          if (statement === null) continue;
+          const statementNode = restatableStatementNodeBelow(comment, sourceCode);
+          if (statementNode === null) continue;
+          const statement = sourceCode.getText(statementNode);
           if (restatesStatementHead(body2, statement)) continue;
-          const line = lines[comment.loc.start.line] ?? "";
-          if (!ACTION_STMT_RE.test(line)) continue;
-          if (labelsASiblingRun(comment)) continue;
-          if (restates(tokens, codeTokens(line))) {
+          if (!ACTION_STMT_RE.test(statement)) continue;
+          if (labelsASiblingRun(statementNode) || headsValueTypeGroup(statementNode)) continue;
+          const identifiers = sourceCode.getTokens(statementNode).filter((token) => token.type === import_utils38.AST_TOKEN_TYPES.Identifier).map((token) => token.value).join(" ");
+          if (restates(tokens, codeTokens(identifiers))) {
             const removal = wholeLineRemovalRange(sourceCode.text, comment);
             context.report({
               node: comment,
@@ -19521,16 +19752,17 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.17.4"
+  version: "15.17.6"
 };
-var APPLICATION_ONLY_RULES = [
-  "no-restricted-library-load",
-  "prefer-native-random-uuid",
-  "prefer-shadcn-primitives"
-];
+var APPLICATION_ONLY_RULES = [];
+var LIBRARY_IMPORT_POLICY = ["error", {
+  paths: LIBRARY_POLICY.map(({ module: module2, note }) => ({ name: module2, message: note })),
+  patterns: LIBRARY_POLICY.map(({ module: module2, note }) => ({ group: [`${module2}/*`], message: note }))
+}];
 var ADVISORY_RULES = [
   "@sarj/excessive-commentary",
   "@sarj/no-bespoke-api-case-conversion",
+  "@sarj/no-restated-comment",
   "@sarj/prefer-millisecond-control-duration-schema",
   "@sarj/prefer-module-level-refined-schema",
   "@sarj/prefer-multi-value-zod-literal",
@@ -19546,6 +19778,10 @@ var ADVISORY_RULES = [
   "@sarj/sole-export-matches-filename"
 ];
 var RECOMMENDED_RULES = {
+  "no-restricted-imports": LIBRARY_IMPORT_POLICY,
+  "@sarj/no-restricted-library-load": ["error", { libraries: LIBRARY_POLICY }],
+  "@sarj/prefer-native-random-uuid": "error",
+  "@sarj/prefer-shadcn-primitives": "error",
   "@sarj/excessive-commentary": "warn",
   "@sarj/interface-contract-members-private": "error",
   "@sarj/iac-source-coupled-test": "error",
@@ -19574,7 +19810,7 @@ var RECOMMENDED_RULES = {
   "@sarj/no-production-browser-source-maps": "error",
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
-  "@sarj/no-restated-comment": "error",
+  "@sarj/no-restated-comment": "warn",
   "@sarj/no-restated-jsdoc": "error",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",
@@ -19635,6 +19871,10 @@ var RECOMMENDED_RULES = {
   "@sarj/require-pascal-case-zod-schema-name": "error"
 };
 var STRICT_RULES = {
+  "no-restricted-imports": LIBRARY_IMPORT_POLICY,
+  "@sarj/no-restricted-library-load": ["error", { libraries: LIBRARY_POLICY }],
+  "@sarj/prefer-native-random-uuid": "error",
+  "@sarj/prefer-shadcn-primitives": "error",
   "@sarj/excessive-commentary": "warn",
   "@sarj/interface-contract-members-private": "error",
   "@sarj/iac-source-coupled-test": "error",
@@ -19666,7 +19906,7 @@ var STRICT_RULES = {
   "@sarj/no-raw-fetch-outside-clients": "error",
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
-  "@sarj/no-restated-comment": "error",
+  "@sarj/no-restated-comment": "warn",
   "@sarj/no-restated-jsdoc": "error",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",