@sarj/eslint-plugin 2.8.0 → 2.9.0

package/README.md

@@ -12,10 +12,19 @@ import sarj from "@sarj/eslint-plugin";
 export default [...sarj.configs.recommended];
 ```
 
-Each rule's source under `src/rules/` carries its own `@fileoverview` rationale plus `meta.docs.description` + `meta.messages` — read the file for the full reasoning, including the false positives it deliberately does not fire on.
+41 rules. Each rule's source under `src/rules/` carries its own `@fileoverview` rationale plus `meta.docs.description` + `meta.messages` — read the file for the full reasoning, including the false positives it deliberately does not fire on.
 
 Presets: `recommended` (warn-first), `strict` (every rule at error), `style-guide` (formatting/naming subset).
 
+## New in 2.9.0
+
+Both distilled from two years of PR-review comments across ~1,065 PRs.
+
+| Rule | What it catches | Preset |
+|---|---|---|
+| `no-zod-native-enum` | `z.nativeEnum(...)` and `z.enum(SomeTsEnum)` — the schema-layer back door around `no-enum`. Autofixes an inline string-literal object to `z.enum([...])`. | warn / error |
+| `prefer-module-level-constant` | A literal-only `const` collection (array, object, `Set`, `Map`, `Object.freeze`) or non-global regex declared inside a function body, never mutated and never escaping — hoist it to module scope. Options: `minElements` (default 3), `checkRegex`, `ignoreTestFiles`. | warn / error |
+
 ## Options
 
 ### Declare your logger (`loggerNames` / `logFunctions`)

package/dist/index.cjs

@@ -5322,6 +5322,484 @@ var no_storage_in_stateless_modules_default = import_utils43.ESLintUtils.RuleCre
   }
 });
 
+// src/rules/no-zod-native-enum.ts
+var import_utils44 = require("@typescript-eslint/utils");
+var ts2 = __toESM(require("typescript"), 1);
+var IGNORE_PATTERNS2 = [
+  /[\\/]generated[\\/]/,
+  /\.gen\.tsx?$/,
+  /\.generated\.tsx?$/,
+  /\.d\.ts$/
+];
+function isIgnoredFile2(filename, sourceText) {
+  if (IGNORE_PATTERNS2.some((re) => re.test(filename))) {
+    return true;
+  }
+  return /@generated\b/.test(sourceText.slice(0, 1024));
+}
+function isZodModule(source) {
+  return /(^|[/@-])zod([/-]|$)/.test(source);
+}
+function unwrap3(node) {
+  if (node.type === import_utils44.AST_NODE_TYPES.TSAsExpression || node.type === import_utils44.AST_NODE_TYPES.TSSatisfiesExpression) {
+    return unwrap3(node.expression);
+  }
+  return node;
+}
+function stringValueTexts(node, sourceCode) {
+  const texts = [];
+  for (const prop of node.properties) {
+    if (prop.type !== import_utils44.AST_NODE_TYPES.Property) {
+      return null;
+    }
+    if (prop.computed || prop.shorthand || prop.method || prop.kind !== "init") {
+      return null;
+    }
+    const value = prop.value;
+    if (value.type !== import_utils44.AST_NODE_TYPES.Literal || typeof value.value !== "string") {
+      return null;
+    }
+    const text = sourceCode.getText(value);
+    if (!texts.includes(text)) {
+      texts.push(text);
+    }
+  }
+  return texts.length > 0 ? texts : null;
+}
+function resolvesToLocalEnum(node, scope) {
+  let current = scope;
+  while (current !== null) {
+    const variable = current.variables.find((v) => v.name === node.name);
+    if (variable !== void 0) {
+      return variable.defs.some(
+        (def) => def.node.type === import_utils44.AST_NODE_TYPES.TSEnumDeclaration
+      );
+    }
+    current = current.upper;
+  }
+  return false;
+}
+var ENUM_SYMBOL_FLAGS = ts2.SymbolFlags.RegularEnum | ts2.SymbolFlags.ConstEnum | ts2.SymbolFlags.Enum;
+function resolvesToImportedEnum(node, services) {
+  const checker = services.program.getTypeChecker();
+  const tsNode = services.esTreeNodeToTSNodeMap.get(node);
+  let symbol = checker.getSymbolAtLocation(tsNode);
+  if (symbol === void 0) {
+    return false;
+  }
+  if ((symbol.flags & ts2.SymbolFlags.Alias) !== 0) {
+    symbol = checker.getAliasedSymbol(symbol);
+  }
+  return (symbol.flags & ENUM_SYMBOL_FLAGS) !== 0;
+}
+var no_zod_native_enum_default = import_utils44.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/linting/blob/main/packages/typescript/src/rules/${name}.ts`
+)({
+  name: "no-zod-native-enum",
+  meta: {
+    type: "suggestion",
+    fixable: "code",
+    docs: {
+      description: 'Disallow `z.nativeEnum()` (and `z.enum()` over a TypeScript enum); use `z.enum(["a", "b"])` with a string-literal union instead.'
+    },
+    schema: [],
+    messages: {
+      nativeEnum: '`z.nativeEnum()` exists to wrap a TypeScript `enum`, which `no-enum` bans. Use `z.enum(["a", "b"])` and derive the union with `z.infer<typeof Schema>`.',
+      enumOfTsEnum: '`z.enum()` is being passed the TypeScript enum `{{name}}`, which `no-enum` bans. Pass a string-literal array instead: `z.enum(["a", "b"])`.'
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    const sourceCode = context.sourceCode;
+    if (isIgnoredFile2(context.filename, sourceCode.getText())) {
+      return {};
+    }
+    let services;
+    try {
+      services = import_utils44.ESLintUtils.getParserServices(context);
+    } catch {
+      services = null;
+    }
+    const zodImportedNames = /* @__PURE__ */ new Map();
+    function isZodMemberCall(node, api) {
+      const callee = node.callee;
+      if (callee.type === import_utils44.AST_NODE_TYPES.MemberExpression && !callee.computed && callee.property.type === import_utils44.AST_NODE_TYPES.Identifier) {
+        return callee.property.name === api;
+      }
+      if (callee.type === import_utils44.AST_NODE_TYPES.Identifier) {
+        return zodImportedNames.get(callee.name) === api;
+      }
+      return false;
+    }
+    function buildFix(node) {
+      const callee = node.callee;
+      if (callee.type !== import_utils44.AST_NODE_TYPES.MemberExpression || callee.property.type !== import_utils44.AST_NODE_TYPES.Identifier) {
+        return null;
+      }
+      const arg = node.arguments[0];
+      if (arg === void 0 || node.arguments.length !== 1 || arg.type === import_utils44.AST_NODE_TYPES.SpreadElement) {
+        return null;
+      }
+      const inner = unwrap3(arg);
+      if (inner.type !== import_utils44.AST_NODE_TYPES.ObjectExpression) {
+        return null;
+      }
+      const values = stringValueTexts(inner, sourceCode);
+      if (values === null) {
+        return null;
+      }
+      const property = callee.property;
+      const replacementArg = `[${values.join(", ")}]`;
+      return (fixer) => [
+        fixer.replaceText(property, "enum"),
+        fixer.replaceText(arg, replacementArg)
+      ];
+    }
+    return {
+      ImportDeclaration(node) {
+        if (!isZodModule(node.source.value)) {
+          return;
+        }
+        for (const spec of node.specifiers) {
+          if (spec.type === import_utils44.AST_NODE_TYPES.ImportSpecifier && spec.imported.type === import_utils44.AST_NODE_TYPES.Identifier) {
+            zodImportedNames.set(spec.local.name, spec.imported.name);
+          }
+        }
+      },
+      CallExpression(node) {
+        if (isZodMemberCall(node, "nativeEnum")) {
+          const fix = buildFix(node);
+          context.report({
+            node,
+            messageId: "nativeEnum",
+            ...fix === null ? {} : { fix }
+          });
+          return;
+        }
+        if (!isZodMemberCall(node, "enum")) {
+          return;
+        }
+        const arg = node.arguments[0];
+        if (arg === void 0 || arg.type !== import_utils44.AST_NODE_TYPES.Identifier) {
+          return;
+        }
+        const isEnum = resolvesToLocalEnum(arg, sourceCode.getScope(arg)) || services !== null && resolvesToImportedEnum(arg, services);
+        if (isEnum) {
+          context.report({
+            node,
+            messageId: "enumOfTsEnum",
+            data: { name: arg.name }
+          });
+        }
+      }
+    };
+  }
+});
+
+// src/rules/prefer-module-level-constant.ts
+var import_utils45 = require("@typescript-eslint/utils");
+var DEFAULT_MIN_ELEMENTS = 3;
+var MAX_LITERAL_DEPTH = 4;
+var IGNORE_PATTERNS3 = [
+  /[\\/]generated[\\/]/,
+  /\.gen\.tsx?$/,
+  /\.generated\.tsx?$/,
+  /\.d\.ts$/
+];
+var TEST_FILE_PATTERNS = [
+  /\.(?:test|spec)\.[cm]?[jt]sx?$/,
+  /[\\/]__tests__[\\/]/,
+  /[\\/]__mocks__[\\/]/,
+  /[\\/]tests?[\\/]/,
+  /\.stories\.[cm]?[jt]sx?$/
+];
+var MUTATING_METHODS = /* @__PURE__ */ new Set([
+  // Array
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "sort",
+  "reverse",
+  "fill",
+  "copyWithin",
+  // Set / Map
+  "add",
+  "set",
+  "delete",
+  "clear",
+  // Object-ish escape hatches
+  "assign"
+]);
+var FUNCTION_TYPES3 = /* @__PURE__ */ new Set([
+  import_utils45.AST_NODE_TYPES.FunctionDeclaration,
+  import_utils45.AST_NODE_TYPES.FunctionExpression,
+  import_utils45.AST_NODE_TYPES.ArrowFunctionExpression
+]);
+var COLLECTION_CONSTRUCTORS = /* @__PURE__ */ new Set(["Set", "Map"]);
+function isIgnoredFile3(filename, sourceText) {
+  if (IGNORE_PATTERNS3.some((re) => re.test(filename))) {
+    return true;
+  }
+  return /@generated\b/.test(sourceText.slice(0, 1024));
+}
+function isTestFile2(filename) {
+  return TEST_FILE_PATTERNS.some((re) => re.test(filename));
+}
+function unwrap4(node) {
+  if (node.type === import_utils45.AST_NODE_TYPES.TSAsExpression || node.type === import_utils45.AST_NODE_TYPES.TSSatisfiesExpression || node.type === import_utils45.AST_NODE_TYPES.TSNonNullExpression) {
+    return unwrap4(node.expression);
+  }
+  return node;
+}
+function isRegexLiteral(node) {
+  return node.type === import_utils45.AST_NODE_TYPES.Literal && "regex" in node && node.regex !== void 0;
+}
+function isLiteralOnly(node, depth) {
+  if (depth > MAX_LITERAL_DEPTH) {
+    return false;
+  }
+  const inner = unwrap4(node);
+  switch (inner.type) {
+    case import_utils45.AST_NODE_TYPES.Literal: {
+      return true;
+    }
+    case import_utils45.AST_NODE_TYPES.TemplateLiteral: {
+      return inner.expressions.length === 0;
+    }
+    case import_utils45.AST_NODE_TYPES.UnaryExpression: {
+      return (inner.operator === "-" || inner.operator === "+") && inner.argument.type === import_utils45.AST_NODE_TYPES.Literal && typeof inner.argument.value === "number";
+    }
+    case import_utils45.AST_NODE_TYPES.ArrayExpression: {
+      return inner.elements.every(
+        (el) => el !== null && el.type !== import_utils45.AST_NODE_TYPES.SpreadElement && isLiteralOnly(el, depth + 1)
+      );
+    }
+    case import_utils45.AST_NODE_TYPES.ObjectExpression: {
+      return inner.properties.every((prop) => {
+        if (prop.type !== import_utils45.AST_NODE_TYPES.Property) {
+          return false;
+        }
+        if (prop.shorthand || prop.method || prop.kind !== "init") {
+          return false;
+        }
+        if (prop.computed && prop.key.type !== import_utils45.AST_NODE_TYPES.Literal) {
+          return false;
+        }
+        return isLiteralOnly(prop.value, depth + 1);
+      });
+    }
+    default: {
+      return false;
+    }
+  }
+}
+function unwrapObjectFreeze(node) {
+  const inner = unwrap4(node);
+  if (inner.type === import_utils45.AST_NODE_TYPES.CallExpression && inner.callee.type === import_utils45.AST_NODE_TYPES.MemberExpression && !inner.callee.computed && inner.callee.object.type === import_utils45.AST_NODE_TYPES.Identifier && inner.callee.object.name === "Object" && inner.callee.property.type === import_utils45.AST_NODE_TYPES.Identifier && inner.callee.property.name === "freeze" && inner.arguments.length === 1 && inner.arguments[0] !== void 0 && inner.arguments[0].type !== import_utils45.AST_NODE_TYPES.SpreadElement) {
+    return unwrap4(inner.arguments[0]);
+  }
+  return inner;
+}
+function classify(init, checkRegex) {
+  const node = unwrapObjectFreeze(init);
+  if (isRegexLiteral(node)) {
+    if (!checkRegex) {
+      return null;
+    }
+    if (/[gy]/.test(node.regex.flags)) {
+      return null;
+    }
+    return { kind: "regex", size: 1 };
+  }
+  if (node.type === import_utils45.AST_NODE_TYPES.ArrayExpression) {
+    return isLiteralOnly(node, 0) ? { kind: "array", size: node.elements.length } : null;
+  }
+  if (node.type === import_utils45.AST_NODE_TYPES.ObjectExpression) {
+    return isLiteralOnly(node, 0) ? { kind: "object", size: node.properties.length } : null;
+  }
+  if (node.type === import_utils45.AST_NODE_TYPES.NewExpression && node.callee.type === import_utils45.AST_NODE_TYPES.Identifier && COLLECTION_CONSTRUCTORS.has(node.callee.name)) {
+    const arg = node.arguments[0];
+    if (node.arguments.length !== 1 || arg === void 0 || arg.type === import_utils45.AST_NODE_TYPES.SpreadElement) {
+      return null;
+    }
+    const entries = unwrap4(arg);
+    if (entries.type !== import_utils45.AST_NODE_TYPES.ArrayExpression) {
+      return null;
+    }
+    return isLiteralOnly(entries, 0) ? { kind: node.callee.name === "Set" ? "Set" : "Map", size: entries.elements.length } : null;
+  }
+  return null;
+}
+function enclosingFunction2(node) {
+  let current = node.parent;
+  while (current !== void 0 && current !== null) {
+    if (FUNCTION_TYPES3.has(current.type)) {
+      return current;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+var NON_RETAINING_BUILTINS = /* @__PURE__ */ new Map(
+  [
+    [
+      "Object",
+      /* @__PURE__ */ new Set(["keys", "values", "entries", "freeze", "fromEntries", "assign"])
+    ],
+    ["Array", /* @__PURE__ */ new Set(["from", "isArray"])],
+    ["JSON", /* @__PURE__ */ new Set(["stringify"])]
+  ]
+);
+function isNonRetainingBuiltinCall(node, argument) {
+  const callee = node.callee;
+  if (callee.type === import_utils45.AST_NODE_TYPES.Identifier && callee.name === "structuredClone") {
+    return true;
+  }
+  if (callee.type !== import_utils45.AST_NODE_TYPES.MemberExpression || callee.computed || callee.object.type !== import_utils45.AST_NODE_TYPES.Identifier || callee.property.type !== import_utils45.AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+  const members = NON_RETAINING_BUILTINS.get(callee.object.name);
+  if (members === void 0 || !members.has(callee.property.name)) {
+    return false;
+  }
+  if (callee.object.name === "Object" && callee.property.name === "assign") {
+    return node.arguments[0] !== argument;
+  }
+  return true;
+}
+function isSafeRead(identifier) {
+  const parent = identifier.parent;
+  if (parent.type === import_utils45.AST_NODE_TYPES.MemberExpression) {
+    if (parent.object !== identifier) {
+      return true;
+    }
+    const grandparent = parent.parent;
+    if (grandparent.type === import_utils45.AST_NODE_TYPES.AssignmentExpression && grandparent.left === parent) {
+      return false;
+    }
+    if (grandparent.type === import_utils45.AST_NODE_TYPES.UpdateExpression) {
+      return false;
+    }
+    if (grandparent.type === import_utils45.AST_NODE_TYPES.UnaryExpression && grandparent.operator === "delete") {
+      return false;
+    }
+    if (!parent.computed && parent.property.type === import_utils45.AST_NODE_TYPES.Identifier && MUTATING_METHODS.has(parent.property.name) && grandparent.type === import_utils45.AST_NODE_TYPES.CallExpression && grandparent.callee === parent) {
+      return false;
+    }
+    return true;
+  }
+  if (parent.type === import_utils45.AST_NODE_TYPES.ForOfStatement && parent.right === identifier) {
+    return true;
+  }
+  if (parent.type === import_utils45.AST_NODE_TYPES.SpreadElement) {
+    return true;
+  }
+  if (parent.type === import_utils45.AST_NODE_TYPES.BinaryExpression) {
+    return true;
+  }
+  if (parent.type === import_utils45.AST_NODE_TYPES.CallExpression && parent.arguments.includes(identifier) && isNonRetainingBuiltinCall(parent, identifier)) {
+    return true;
+  }
+  if (parent.type === import_utils45.AST_NODE_TYPES.UnaryExpression && parent.operator !== "delete") {
+    return true;
+  }
+  return false;
+}
+var prefer_module_level_constant_default = import_utils45.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/linting/blob/main/packages/typescript/src/rules/${name}.ts`
+)({
+  name: "prefer-module-level-constant",
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Hoist literal-only constant collections and regexes out of function bodies to module scope so they are allocated once."
+    },
+    schema: [
+      {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          minElements: { type: "number", minimum: 1 },
+          checkRegex: { type: "boolean" },
+          ignoreTestFiles: { type: "boolean" }
+        }
+      }
+    ],
+    messages: {
+      hoistCollection: "`{{name}}` is a literal-only {{kind}} rebuilt on every call. Hoist it to module scope so it is allocated once and can be reused, exported, and tested.",
+      hoistRegex: "`{{name}}` is a constant regex recompiled on every call. Hoist it to module scope."
+    }
+  },
+  defaultOptions: [{}],
+  create(context, [optionsArg]) {
+    const options = optionsArg ?? {};
+    const minElements = options.minElements ?? DEFAULT_MIN_ELEMENTS;
+    const checkRegex = options.checkRegex ?? true;
+    const ignoreTestFiles = options.ignoreTestFiles ?? true;
+    const sourceCode = context.sourceCode;
+    const filename = context.filename;
+    if (isIgnoredFile3(filename, sourceCode.getText())) {
+      return {};
+    }
+    if (ignoreTestFiles && isTestFile2(filename)) {
+      return {};
+    }
+    function allReferencesAreSafeReads(declarator) {
+      const variables = sourceCode.getDeclaredVariables(declarator);
+      const variable = variables[0];
+      if (variable === void 0) {
+        return false;
+      }
+      for (const reference of variable.references) {
+        if (reference.init === true) {
+          continue;
+        }
+        if (reference.isWrite()) {
+          return false;
+        }
+        if (reference.identifier.type !== import_utils45.AST_NODE_TYPES.Identifier) {
+          return false;
+        }
+        if (!isSafeRead(reference.identifier)) {
+          return false;
+        }
+      }
+      return true;
+    }
+    return {
+      VariableDeclarator(node) {
+        const declaration = node.parent;
+        if (declaration.type !== import_utils45.AST_NODE_TYPES.VariableDeclaration || declaration.kind !== "const" || declaration.declare === true) {
+          return;
+        }
+        if (node.id.type !== import_utils45.AST_NODE_TYPES.Identifier || node.init === null) {
+          return;
+        }
+        if (enclosingFunction2(node) === null) {
+          return;
+        }
+        const candidate = classify(node.init, checkRegex);
+        if (candidate === null) {
+          return;
+        }
+        if (candidate.kind !== "regex" && candidate.size < minElements) {
+          return;
+        }
+        if (!allReferencesAreSafeReads(node)) {
+          return;
+        }
+        context.report({
+          node: node.id,
+          messageId: candidate.kind === "regex" ? "hoistRegex" : "hoistCollection",
+          data: { name: node.id.name, kind: candidate.kind }
+        });
+      }
+    };
+  }
+});
+
 // src/index.ts
 var rules = {
   "enforce-file-structure": enforce_file_structure_default,
@@ -5362,12 +5840,14 @@ var rules = {
   "store-insert-requires-on-conflict": store_insert_requires_on_conflict_default,
   "no-dynamic-sql": no_dynamic_sql_default,
   "no-raw-fetch-outside-clients": no_raw_fetch_outside_clients_default,
-  "no-storage-in-stateless-modules": no_storage_in_stateless_modules_default
+  "no-storage-in-stateless-modules": no_storage_in_stateless_modules_default,
+  "no-zod-native-enum": no_zod_native_enum_default,
+  "prefer-module-level-constant": prefer_module_level_constant_default
 };
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "2.8.0"
+    version: "2.9.0"
   },
   rules,
   configs: {
@@ -5416,7 +5896,14 @@ var plugin = {
         "@sarj/no-repeated-string-literal": "warn",
         "@sarj/no-positional-tuple-return": "warn",
         // Injection guard — low FP, applies to any repo touching SQL.
-        "@sarj/no-dynamic-sql": "warn"
+        "@sarj/no-dynamic-sql": "warn",
+        // Mined from two years of PR review (SARJ-928). Schema-layer sibling of
+        // `no-enum`; autofixable for inline string-literal objects.
+        "@sarj/no-zod-native-enum": "warn",
+        // Mined from two years of PR review — the single most frequent uncovered
+        // theme (~37 PRs). Measured 17 hits / 1085 real TS files, all true
+        // positives, so it is safe to run everywhere.
+        "@sarj/prefer-module-level-constant": "warn"
       }
     },
     strict: {
@@ -5476,7 +5963,10 @@ var plugin = {
         // and takes an `allow` list for repos that lay their client layer out
         // differently.
         "@sarj/no-raw-fetch-outside-clients": "error",
-        "@sarj/no-storage-in-stateless-modules": "error"
+        "@sarj/no-storage-in-stateless-modules": "error",
+        // Mined from two years of PR review (SARJ-928).
+        "@sarj/no-zod-native-enum": "error",
+        "@sarj/prefer-module-level-constant": "error"
       }
     }
   }