@sarj/eslint-plugin 6.0.0 → 6.1.0

package/README.md

@@ -108,6 +108,7 @@ Both distilled from two years of PR-review comments across ~1,065 PRs.
 | `prefer-zod-enum` | `z.union([z.literal("a"), z.literal("b")])` — autofixes closed string choices to the shorter, equivalent `z.enum(["a", "b"])`. | warn / error |
 | `prefer-zod-infer` | An `interface`/`type` that restates a Zod schema declared in the same module instead of deriving it with `z.infer`. Options: `ignoreTypeNames`, `requireIdenticalShape` (default `true`). | 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 |
+| `prefer-module-level-schema` | A Zod schema built inside a function body that closes over nothing the function owns — hoist it to module scope instead of rebuilding it per call, per request, per render. Silent when it references a parameter, local, type parameter, local type, or `this` (that is a schema FACTORY), when it is already memoized, and inside `z.lazy`. Options: `factories` (default: the object-like composites), `minProperties` (default 1), `ignoreTestFiles`. | warn / error |
 | `prefer-non-nullable-collection` | An array type explicitly combined with `null`/`undefined`, creating two equivalent empty states. | warn / error |
 
 ## Options

package/dist/index.cjs

@@ -8647,6 +8647,258 @@ var no_hand_rolled_sleep_default = import_utils55.ESLintUtils.RuleCreator(
   }
 });
 
+// src/rules/prefer-module-level-schema.ts
+var import_utils56 = require("@typescript-eslint/utils");
+var DEFAULT_FACTORIES = [
+  "discriminatedUnion",
+  "intersection",
+  "looseObject",
+  "object",
+  "record",
+  "strictObject",
+  "tuple",
+  "union"
+];
+var DEFAULT_MIN_PROPERTIES = 1;
+var MEMO_CALLEES = /* @__PURE__ */ new Set([
+  "lazy",
+  "memo",
+  "once",
+  "useMemo"
+]);
+var TERMINAL_METHODS = /* @__PURE__ */ new Set([
+  "isNullable",
+  "isOptional",
+  "parse",
+  "parseAsync",
+  "safeParse",
+  "safeParseAsync",
+  "spa"
+]);
+var FUNCTION_TYPES6 = /* @__PURE__ */ new Set([
+  import_utils56.AST_NODE_TYPES.ArrowFunctionExpression,
+  import_utils56.AST_NODE_TYPES.FunctionDeclaration,
+  import_utils56.AST_NODE_TYPES.FunctionExpression
+]);
+function schemaExpression(node) {
+  let current = node;
+  for (; ; ) {
+    const parent = current.parent ?? void 0;
+    if (parent === void 0) {
+      return current;
+    }
+    if (parent.type === import_utils56.AST_NODE_TYPES.MemberExpression && parent.object === current && !parent.computed && parent.property.type === import_utils56.AST_NODE_TYPES.Identifier && TERMINAL_METHODS.has(parent.property.name)) {
+      return current;
+    }
+    if (parent.type === import_utils56.AST_NODE_TYPES.MemberExpression && parent.object === current || parent.type === import_utils56.AST_NODE_TYPES.CallExpression && parent.callee === current || parent.type === import_utils56.AST_NODE_TYPES.TSAsExpression && parent.expression === current || parent.type === import_utils56.AST_NODE_TYPES.TSNonNullExpression && parent.expression === current) {
+      current = parent;
+      continue;
+    }
+    return current;
+  }
+}
+function outermostEnclosingFunction(node) {
+  let outermost;
+  let current = node.parent ?? void 0;
+  while (current !== void 0) {
+    if (FUNCTION_TYPES6.has(current.type)) {
+      outermost = current;
+    }
+    current = current.parent ?? void 0;
+  }
+  return outermost;
+}
+function readsReceiver(node) {
+  let found = false;
+  const visit = (value) => {
+    if (found || value === null || typeof value !== "object") {
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        visit(item);
+      }
+      return;
+    }
+    const candidate = value;
+    if (typeof candidate.type !== "string") {
+      return;
+    }
+    if (candidate.type === import_utils56.AST_NODE_TYPES.ThisExpression || candidate.type === import_utils56.AST_NODE_TYPES.Super || candidate.type === import_utils56.AST_NODE_TYPES.Identifier && candidate.name === "arguments") {
+      found = true;
+      return;
+    }
+    for (const key of Object.keys(candidate)) {
+      if (key === "parent" || key === "loc" || key === "range") {
+        continue;
+      }
+      visit(candidate[key]);
+    }
+  };
+  visit(node);
+  return found;
+}
+function collectReferences(scope, out) {
+  out.push(...scope.references);
+  for (const child of scope.childScopes) {
+    collectReferences(child, out);
+  }
+}
+var prefer_module_level_schema_default = import_utils56.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/standards/tree/main/packages/typescript#${name}`
+)({
+  name: "prefer-module-level-schema",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Declare a Zod schema at module scope when it closes over nothing in the enclosing function"
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          factories: {
+            type: "array",
+            items: { type: "string" },
+            description: "Zod factory names to check. Defaults to the object-like composites; add `array` / `enum` to widen."
+          },
+          ignoreTestFiles: {
+            type: "boolean",
+            description: "Skip test files, where a fixture schema belongs next to its assertion."
+          },
+          minProperties: {
+            type: "number",
+            minimum: 0,
+            description: "Minimum key count before an object-like schema is reported."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      hoistSchema: "Move this `{{factory}}` schema to module scope. It uses nothing from `{{owner}}`, so it is rebuilt on every call for no benefit and cannot be exported, reused, or `z.infer`-ed from where it is."
+    }
+  },
+  defaultOptions: [{}],
+  create(context, [options]) {
+    const factories = new Set(options?.factories ?? DEFAULT_FACTORIES);
+    const ignoreTestFiles = options?.ignoreTestFiles ?? true;
+    const minProperties = options?.minProperties ?? DEFAULT_MIN_PROPERTIES;
+    const sourceCode = context.sourceCode;
+    const filename = context.filename;
+    if (isGeneratedFile(filename, sourceCode.getText())) {
+      return {};
+    }
+    if (ignoreTestFiles && isTestFile(filename)) {
+      return {};
+    }
+    const zodNamespaces = /* @__PURE__ */ new Set();
+    function isZodCall(node) {
+      return node.type === import_utils56.AST_NODE_TYPES.CallExpression && node.callee.type === import_utils56.AST_NODE_TYPES.MemberExpression && !node.callee.computed && node.callee.object.type === import_utils56.AST_NODE_TYPES.Identifier && zodNamespaces.has(node.callee.object.name);
+    }
+    function isCovered(node) {
+      let current = node.parent ?? void 0;
+      while (current !== void 0) {
+        if (current !== node && isZodCall(current) && current.callee.type === import_utils56.AST_NODE_TYPES.MemberExpression && current.callee.property.type === import_utils56.AST_NODE_TYPES.Identifier && factories.has(current.callee.property.name)) {
+          return true;
+        }
+        if (current.type === import_utils56.AST_NODE_TYPES.CallExpression && (current.callee.type === import_utils56.AST_NODE_TYPES.Identifier && MEMO_CALLEES.has(current.callee.name) || current.callee.type === import_utils56.AST_NODE_TYPES.MemberExpression && !current.callee.computed && current.callee.property.type === import_utils56.AST_NODE_TYPES.Identifier && MEMO_CALLEES.has(current.callee.property.name))) {
+          return true;
+        }
+        current = current.parent ?? void 0;
+      }
+      return false;
+    }
+    function closesOverNothing(node, enclosing) {
+      const references = [];
+      collectReferences(sourceCode.getScope(node), references);
+      const [schemaStart, schemaEnd] = node.range;
+      const [functionStart, functionEnd] = enclosing.range;
+      for (const reference of references) {
+        const [identifierStart] = reference.identifier.range;
+        if (identifierStart < schemaStart || identifierStart >= schemaEnd) {
+          continue;
+        }
+        const resolved = reference.resolved;
+        if (resolved === null) {
+          continue;
+        }
+        for (const definition of resolved.defs) {
+          if (definition.type === "ImportBinding") {
+            continue;
+          }
+          const [defStart, defEnd] = definition.node.range;
+          if (defStart >= functionStart && defEnd <= functionEnd) {
+            return false;
+          }
+        }
+      }
+      return true;
+    }
+    function ownerName(enclosing) {
+      const parent = enclosing.parent ?? void 0;
+      if (enclosing.type === import_utils56.AST_NODE_TYPES.FunctionDeclaration && enclosing.id !== null) {
+        return enclosing.id.name;
+      }
+      if (parent !== void 0 && parent.type === import_utils56.AST_NODE_TYPES.VariableDeclarator && parent.id.type === import_utils56.AST_NODE_TYPES.Identifier) {
+        return parent.id.name;
+      }
+      if (parent !== void 0 && (parent.type === import_utils56.AST_NODE_TYPES.MethodDefinition || parent.type === import_utils56.AST_NODE_TYPES.Property) && parent.key.type === import_utils56.AST_NODE_TYPES.Identifier) {
+        return parent.key.name;
+      }
+      return "this function";
+    }
+    return {
+      ImportDeclaration(node) {
+        if (!isZodModule(node.source.value)) {
+          return;
+        }
+        for (const specifier of node.specifiers) {
+          if (specifier.type === import_utils56.AST_NODE_TYPES.ImportNamespaceSpecifier || specifier.type === import_utils56.AST_NODE_TYPES.ImportDefaultSpecifier || specifier.type === import_utils56.AST_NODE_TYPES.ImportSpecifier && specifier.imported.type === import_utils56.AST_NODE_TYPES.Identifier && specifier.imported.name === "z") {
+            zodNamespaces.add(specifier.local.name);
+          }
+        }
+      },
+      CallExpression(node) {
+        if (zodNamespaces.size === 0 || !isZodCall(node)) {
+          return;
+        }
+        const callee = node.callee;
+        if (callee.property.type !== import_utils56.AST_NODE_TYPES.Identifier) {
+          return;
+        }
+        const factory = callee.property.name;
+        if (!factories.has(factory)) {
+          return;
+        }
+        const enclosing = outermostEnclosingFunction(node);
+        if (enclosing === void 0) {
+          return;
+        }
+        if (isCovered(node)) {
+          return;
+        }
+        const shape = node.arguments[0];
+        if (shape !== void 0 && shape.type === import_utils56.AST_NODE_TYPES.ObjectExpression && shape.properties.length < minProperties) {
+          return;
+        }
+        const expression = schemaExpression(node);
+        if (readsReceiver(expression)) {
+          return;
+        }
+        if (!closesOverNothing(expression, enclosing)) {
+          return;
+        }
+        context.report({
+          node,
+          messageId: "hoistSchema",
+          data: { factory: `z.${factory}`, owner: ownerName(enclosing) }
+        });
+      }
+    };
+  }
+});
+
 // src/index.ts
 var rules = {
   "enforce-file-structure": enforce_file_structure_default,
@@ -8698,11 +8950,12 @@ var rules = {
   "require-interface-for-injected-service": require_interface_for_injected_service_default,
   "strict-test-assertions": strict_test_assertions_default,
   "prefer-non-nullable-collection": prefer_non_nullable_collection_default,
-  "no-async-callback-in-waitfor": no_async_callback_in_waitfor_default
+  "no-async-callback-in-waitfor": no_async_callback_in_waitfor_default,
+  "prefer-module-level-schema": prefer_module_level_schema_default
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "6.0.0"
+  version: "6.1.0"
 };
 var recommendedRules = {
   "@sarj/zod-naming-convention": "warn",
@@ -8801,6 +9054,14 @@ var recommendedRules = {
   "@sarj/require-interface-for-injected-service": "warn",
   "@sarj/prefer-non-nullable-collection": "warn",
   "@sarj/no-async-callback-in-waitfor": "warn",
+  // A Zod schema built inside a function is rebuilt on every call, every
+  // request, every render. Zod sibling of `prefer-module-level-constant`,
+  // which cannot reach it: that rule's hoist gate requires literal leaves and
+  // `z.object({...})` is a call. 378 reports over 30,546 .ts/.tsx files in 17
+  // repos; the free-variable, chain and `this` gates are what keep the schema
+  // FACTORY case (closes over a parameter, a type parameter, or a local type)
+  // silent.
+  "@sarj/prefer-module-level-schema": "warn",
   // `strict-test-assertions` shipped in `rules` but in NEITHER preset, so a
   // consumer using `configs.recommended`/`configs.strict` instead of the shared
   // `eslint.strict.mjs` had silently never run it. `flat-presets.test.ts`
@@ -8887,6 +9148,8 @@ var strictRules = {
   "@sarj/require-interface-for-injected-service": "error",
   "@sarj/prefer-non-nullable-collection": "error",
   "@sarj/no-async-callback-in-waitfor": "error",
+  // Zod sibling of `prefer-module-level-constant` -- see `recommended`.
+  "@sarj/prefer-module-level-schema": "error",
   // See the `recommended` block.
   "@sarj/strict-test-assertions": "error"
 };