@sarj/eslint-plugin 6.0.0 → 6.1.0

package/dist/index.d.cts

@@ -437,6 +437,13 @@ declare const rules: {
     "no-async-callback-in-waitfor": _typescript_eslint_utils_ts_eslint.RuleModule<"noAsyncCallbackInWaitFor", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "prefer-module-level-schema": _typescript_eslint_utils_ts_eslint.RuleModule<"hoistSchema", readonly [{
+        factories?: readonly string[];
+        ignoreTestFiles?: boolean;
+        minProperties?: number;
+    }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 declare const recommendedRules: {
     readonly "@sarj/zod-naming-convention": "warn";
@@ -486,6 +493,7 @@ declare const recommendedRules: {
     readonly "@sarj/require-interface-for-injected-service": "warn";
     readonly "@sarj/prefer-non-nullable-collection": "warn";
     readonly "@sarj/no-async-callback-in-waitfor": "warn";
+    readonly "@sarj/prefer-module-level-schema": "warn";
     readonly "@sarj/strict-test-assertions": "warn";
 };
 declare const strictRules: {
@@ -540,6 +548,7 @@ declare const strictRules: {
     readonly "@sarj/require-interface-for-injected-service": "error";
     readonly "@sarj/prefer-non-nullable-collection": "error";
     readonly "@sarj/no-async-callback-in-waitfor": "error";
+    readonly "@sarj/prefer-module-level-schema": "error";
     readonly "@sarj/strict-test-assertions": "error";
 };
 type FlatPreset = {
@@ -572,7 +581,7 @@ type FlatPreset = {
 declare const plugin: {
     meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "6.0.0";
+        readonly version: "6.1.0";
     };
     rules: {
         "enforce-file-structure": _typescript_eslint_utils_ts_eslint.RuleModule<"importsFirst" | "useServerDirective", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -745,6 +754,13 @@ declare const plugin: {
         "no-async-callback-in-waitfor": _typescript_eslint_utils_ts_eslint.RuleModule<"noAsyncCallbackInWaitFor", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "prefer-module-level-schema": _typescript_eslint_utils_ts_eslint.RuleModule<"hoistSchema", readonly [{
+            factories?: readonly string[];
+            ignoreTestFiles?: boolean;
+            minProperties?: number;
+        }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
     configs: {
         recommended: FlatPreset;

package/dist/index.d.ts

@@ -437,6 +437,13 @@ declare const rules: {
     "no-async-callback-in-waitfor": _typescript_eslint_utils_ts_eslint.RuleModule<"noAsyncCallbackInWaitFor", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "prefer-module-level-schema": _typescript_eslint_utils_ts_eslint.RuleModule<"hoistSchema", readonly [{
+        factories?: readonly string[];
+        ignoreTestFiles?: boolean;
+        minProperties?: number;
+    }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 declare const recommendedRules: {
     readonly "@sarj/zod-naming-convention": "warn";
@@ -486,6 +493,7 @@ declare const recommendedRules: {
     readonly "@sarj/require-interface-for-injected-service": "warn";
     readonly "@sarj/prefer-non-nullable-collection": "warn";
     readonly "@sarj/no-async-callback-in-waitfor": "warn";
+    readonly "@sarj/prefer-module-level-schema": "warn";
     readonly "@sarj/strict-test-assertions": "warn";
 };
 declare const strictRules: {
@@ -540,6 +548,7 @@ declare const strictRules: {
     readonly "@sarj/require-interface-for-injected-service": "error";
     readonly "@sarj/prefer-non-nullable-collection": "error";
     readonly "@sarj/no-async-callback-in-waitfor": "error";
+    readonly "@sarj/prefer-module-level-schema": "error";
     readonly "@sarj/strict-test-assertions": "error";
 };
 type FlatPreset = {
@@ -572,7 +581,7 @@ type FlatPreset = {
 declare const plugin: {
     meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "6.0.0";
+        readonly version: "6.1.0";
     };
     rules: {
         "enforce-file-structure": _typescript_eslint_utils_ts_eslint.RuleModule<"importsFirst" | "useServerDirective", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -745,6 +754,13 @@ declare const plugin: {
         "no-async-callback-in-waitfor": _typescript_eslint_utils_ts_eslint.RuleModule<"noAsyncCallbackInWaitFor", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "prefer-module-level-schema": _typescript_eslint_utils_ts_eslint.RuleModule<"hoistSchema", readonly [{
+            factories?: readonly string[];
+            ignoreTestFiles?: boolean;
+            minProperties?: number;
+        }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
     configs: {
         recommended: FlatPreset;

package/dist/index.js

@@ -8645,6 +8645,261 @@ var no_hand_rolled_sleep_default = ESLintUtils50.RuleCreator(
   }
 });
 
+// src/rules/prefer-module-level-schema.ts
+import {
+  AST_NODE_TYPES as AST_NODE_TYPES41,
+  ESLintUtils as ESLintUtils51
+} from "@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([
+  AST_NODE_TYPES41.ArrowFunctionExpression,
+  AST_NODE_TYPES41.FunctionDeclaration,
+  AST_NODE_TYPES41.FunctionExpression
+]);
+function schemaExpression(node) {
+  let current = node;
+  for (; ; ) {
+    const parent = current.parent ?? void 0;
+    if (parent === void 0) {
+      return current;
+    }
+    if (parent.type === AST_NODE_TYPES41.MemberExpression && parent.object === current && !parent.computed && parent.property.type === AST_NODE_TYPES41.Identifier && TERMINAL_METHODS.has(parent.property.name)) {
+      return current;
+    }
+    if (parent.type === AST_NODE_TYPES41.MemberExpression && parent.object === current || parent.type === AST_NODE_TYPES41.CallExpression && parent.callee === current || parent.type === AST_NODE_TYPES41.TSAsExpression && parent.expression === current || parent.type === AST_NODE_TYPES41.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 === AST_NODE_TYPES41.ThisExpression || candidate.type === AST_NODE_TYPES41.Super || candidate.type === AST_NODE_TYPES41.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 = ESLintUtils51.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 === AST_NODE_TYPES41.CallExpression && node.callee.type === AST_NODE_TYPES41.MemberExpression && !node.callee.computed && node.callee.object.type === AST_NODE_TYPES41.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 === AST_NODE_TYPES41.MemberExpression && current.callee.property.type === AST_NODE_TYPES41.Identifier && factories.has(current.callee.property.name)) {
+          return true;
+        }
+        if (current.type === AST_NODE_TYPES41.CallExpression && (current.callee.type === AST_NODE_TYPES41.Identifier && MEMO_CALLEES.has(current.callee.name) || current.callee.type === AST_NODE_TYPES41.MemberExpression && !current.callee.computed && current.callee.property.type === AST_NODE_TYPES41.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 === AST_NODE_TYPES41.FunctionDeclaration && enclosing.id !== null) {
+        return enclosing.id.name;
+      }
+      if (parent !== void 0 && parent.type === AST_NODE_TYPES41.VariableDeclarator && parent.id.type === AST_NODE_TYPES41.Identifier) {
+        return parent.id.name;
+      }
+      if (parent !== void 0 && (parent.type === AST_NODE_TYPES41.MethodDefinition || parent.type === AST_NODE_TYPES41.Property) && parent.key.type === AST_NODE_TYPES41.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 === AST_NODE_TYPES41.ImportNamespaceSpecifier || specifier.type === AST_NODE_TYPES41.ImportDefaultSpecifier || specifier.type === AST_NODE_TYPES41.ImportSpecifier && specifier.imported.type === AST_NODE_TYPES41.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 !== AST_NODE_TYPES41.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 === AST_NODE_TYPES41.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,
@@ -8696,11 +8951,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",
@@ -8799,6 +9055,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`
@@ -8885,6 +9149,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"
 };