@sarj/eslint-plugin 2.14.0 → 2.15.0

package/README.md

@@ -12,7 +12,7 @@ import sarj from "@sarj/eslint-plugin";
 export default [...sarj.configs.recommended];
 ```
 
-45 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.
+46 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).
 
@@ -68,6 +68,7 @@ Both distilled from two years of PR-review comments across ~1,065 PRs.
 |---|---|---|
 | `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 |
+| `prefer-non-nullable-collection` | An array type explicitly combined with `null`/`undefined`, creating two equivalent empty states. | warn / error |
 
 ## Options
 

package/dist/index.cjs

@@ -46,7 +46,7 @@ var GENERATED_MARKER_RE = /(?:@generated\b|generated (?:with|by)|generated (?:gr
 function isTestFile(filename) {
   const normalized = filename.replaceAll("\\", "/");
   const base = normalized.slice(normalized.lastIndexOf("/") + 1);
-  if (/\.(test|spec|e2e|integration)\.[cm]?[jt]sx?$/.test(base)) {
+  if (/[.\-_](test|spec|e2e)\.[cm]?[jt]sx?$/.test(base) || /\.integration\.[cm]?[jt]sx?$/.test(base)) {
     return true;
   }
   return /(^|\/)(tests?|__tests__|__mocks__|fixtures|e2e|integration)\//.test(normalized);
@@ -5143,8 +5143,8 @@ var single_public_export_default = import_utils33.ESLintUtils.RuleCreator(
     if (base.endsWith(".d.ts")) return {};
     if (TEST_FILE_RE.test(base)) return {};
     if (isTestFile(context.filename)) return {};
-    const stem2 = stemOf(base);
-    if (!JUNK_DRAWER_STEMS.has(stem2.toLowerCase())) return {};
+    const stem3 = stemOf(base);
+    if (!JUNK_DRAWER_STEMS.has(stem3.toLowerCase())) return {};
     return {
       Program(node) {
         const { names, hasReExport, candidate } = summarizeExports(node.body);
@@ -5152,11 +5152,11 @@ var single_public_export_default = import_utils33.ESLintUtils.RuleCreator(
         if (names !== 1 || candidate === null) return;
         if (CONVENTIONAL_BUCKET_EXPORTS.has(candidate.name)) return;
         const expected = kebabCase2(candidate.name);
-        if (stem2 === expected) return;
+        if (stem3 === expected) return;
         context.report({
           node: candidate.node,
           messageId: "renameJunkDrawer",
-          data: { stem: stem2, name: candidate.name, expected }
+          data: { stem: stem3, name: candidate.name, expected }
         });
       }
     };
@@ -5310,7 +5310,7 @@ function createSqlListener(handler) {
 }
 
 // src/rules/no-offset-pagination.ts
-var OFFSET_PAGINATION = /\bOFFSET\s+(?:\?\d*|:\w+|@\w+|\$\d+|\d+)/i;
+var OFFSET_PAGINATION = /\bOFFSET\s+(?:%s|%\(\w+\)s|\?\d*|:\w+|@\w+|\$\d+|\d+)/i;
 var OFFSET_GATE = /offset/i;
 var no_offset_pagination_default = import_utils35.ESLintUtils.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
@@ -5502,7 +5502,6 @@ var no_positional_tuple_return_default = import_utils36.ESLintUtils.RuleCreator(
 // src/rules/no-repeated-string-literal.ts
 var import_utils37 = require("@typescript-eslint/utils");
 var MIN_LENGTH = 40;
-var MIN_OCCURRENCES = 3;
 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/;
@@ -5584,9 +5583,6 @@ var no_repeated_string_literal_default = import_utils37.ESLintUtils.RuleCreator(
       },
       "Program:exit": () => {
         for (const [value, nodes] of occurrences) {
-          if (nodes.length < MIN_OCCURRENCES) {
-            continue;
-          }
           const distinctScopes = new Set(
             nodes.map((node) => scopes.get(node)).filter((scope) => scope != null)
           );
@@ -7261,6 +7257,244 @@ var no_tautological_expect_default = import_utils50.ESLintUtils.RuleCreator(
   }
 });
 
+// src/rules/require-interface-for-injected-service.ts
+var import_utils51 = require("@typescript-eslint/utils");
+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)$/;
+var TRANSPORT_WRAPPER_NAME_RE = /Client$/;
+var ROUTER_FACTORY_NAME = "Router";
+var FRAMEWORK_HTTP_TYPES = /* @__PURE__ */ new Set(["Request", "Response", "NextFunction"]);
+var isExportedClass = (node) => node.parent.type === import_utils51.AST_NODE_TYPES.ExportNamedDeclaration || node.parent.type === import_utils51.AST_NODE_TYPES.ExportDefaultDeclaration;
+var qualifiedName = (name) => name.type === import_utils51.AST_NODE_TYPES.Identifier ? name.name : name.type === import_utils51.AST_NODE_TYPES.TSQualifiedName ? `${qualifiedName(name.left)}.${name.right.name}` : "";
+var typeReferenceName = (annotated) => {
+  let target = annotated;
+  if (target.type === import_utils51.AST_NODE_TYPES.TSParameterProperty) target = target.parameter;
+  if (target.type === import_utils51.AST_NODE_TYPES.AssignmentPattern) target = target.left;
+  if (target.type !== import_utils51.AST_NODE_TYPES.Identifier) return null;
+  const annotation = target.typeAnnotation?.typeAnnotation;
+  if (annotation === void 0 || annotation.type !== import_utils51.AST_NODE_TYPES.TSTypeReference) {
+    return null;
+  }
+  const { typeName } = annotation;
+  const rightmost = typeName.type === import_utils51.AST_NODE_TYPES.Identifier ? typeName.name : typeName.type === import_utils51.AST_NODE_TYPES.TSQualifiedName ? typeName.right.name : null;
+  if (rightmost === null) return null;
+  return { name: target.name, typeName: rightmost, display: qualifiedName(typeName) };
+};
+var readConstructor = (ctor) => {
+  const body = ctor.value.body;
+  const storedFrom = /* @__PURE__ */ new Set();
+  let constructedFields = 0;
+  if (body !== null && body !== void 0) {
+    for (const statement of body.body) {
+      if (statement.type !== import_utils51.AST_NODE_TYPES.ExpressionStatement) continue;
+      const expression = statement.expression;
+      if (expression.type !== import_utils51.AST_NODE_TYPES.AssignmentExpression || expression.operator !== "=" || expression.left.type !== import_utils51.AST_NODE_TYPES.MemberExpression || expression.left.object.type !== import_utils51.AST_NODE_TYPES.ThisExpression) {
+        continue;
+      }
+      const source = expression.right;
+      if (source.type === import_utils51.AST_NODE_TYPES.NewExpression) {
+        constructedFields += 1;
+      } else if (source.type === import_utils51.AST_NODE_TYPES.Identifier) {
+        storedFrom.add(source.name);
+      } else if (source.type === import_utils51.AST_NODE_TYPES.MemberExpression && source.object.type === import_utils51.AST_NODE_TYPES.Identifier) {
+        storedFrom.add(source.object.name);
+      }
+    }
+  }
+  const collaborators = [];
+  for (const parameter of ctor.value.params) {
+    const reference = typeReferenceName(parameter);
+    if (reference === null) continue;
+    const stored = parameter.type === import_utils51.AST_NODE_TYPES.TSParameterProperty || storedFrom.has(reference.name);
+    if (!stored) continue;
+    if (CONFIGISH_TYPE_RE.test(reference.typeName)) continue;
+    if (CONFIGISH_NAME_RE.test(reference.name)) continue;
+    collaborators.push(reference);
+  }
+  return { collaborators, constructedFields };
+};
+var subtreeHas = (root, found) => {
+  let hit = false;
+  const visit = (current) => {
+    if (hit) return;
+    if (found(current)) {
+      hit = true;
+      return;
+    }
+    for (const key of Object.keys(current)) {
+      if (key === "parent") continue;
+      const value = current[key];
+      for (const child of Array.isArray(value) ? value : [value]) {
+        if (child !== null && typeof child === "object" && typeof child.type === "string") {
+          visit(child);
+        }
+      }
+    }
+  };
+  visit(root);
+  return hit;
+};
+var isFrameworkWiring = (body) => subtreeHas(body, (node) => {
+  if (node.type === import_utils51.AST_NODE_TYPES.CallExpression) {
+    const { callee } = node;
+    if (callee.type === import_utils51.AST_NODE_TYPES.Identifier) return callee.name === ROUTER_FACTORY_NAME;
+    return callee.type === import_utils51.AST_NODE_TYPES.MemberExpression && !callee.computed && callee.property.type === import_utils51.AST_NODE_TYPES.Identifier && callee.property.name === ROUTER_FACTORY_NAME;
+  }
+  return node.type === import_utils51.AST_NODE_TYPES.TSTypeReference && node.typeName.type === import_utils51.AST_NODE_TYPES.TSQualifiedName && FRAMEWORK_HTTP_TYPES.has(node.typeName.right.name);
+});
+var stem2 = (name) => name.replace(/^I(?=[A-Z])/, "").replace(/Impl$/, "");
+var fileInterfaceNames = (program) => {
+  const names = [];
+  for (const statement of program.body) {
+    const declaration = statement.type === import_utils51.AST_NODE_TYPES.ExportNamedDeclaration ? statement.declaration : statement;
+    if (declaration?.type === import_utils51.AST_NODE_TYPES.TSInterfaceDeclaration) names.push(declaration.id.name);
+  }
+  return names;
+};
+var isTransportWrapper = (className, collaborators, program) => {
+  const [only] = collaborators;
+  if (collaborators.length !== 1 || only === void 0) return false;
+  if (!HTTP_TRANSPORT_TYPE_RE.test(only.typeName)) return false;
+  if (!TRANSPORT_WRAPPER_NAME_RE.test(className)) return false;
+  const target = stem2(className);
+  return !fileInterfaceNames(program).some((name) => {
+    const other = stem2(name);
+    return target.endsWith(other) || other.endsWith(target);
+  });
+};
+var publicMethodNames = (body) => {
+  const names = [];
+  for (const member of body.body) {
+    if (member.type !== import_utils51.AST_NODE_TYPES.MethodDefinition) continue;
+    if (member.kind !== "method" || member.static) continue;
+    if (member.accessibility === "private" || member.accessibility === "protected") continue;
+    if (member.key.type === import_utils51.AST_NODE_TYPES.PrivateIdentifier) continue;
+    if (member.key.type === import_utils51.AST_NODE_TYPES.Identifier) names.push(member.key.name);
+    else names.push("\u2026");
+  }
+  return names;
+};
+var require_interface_for_injected_service_default = import_utils51.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
+)({
+  name: "require-interface-for-injected-service",
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "An exported service class with constructor-injected collaborators must implement an interface, so consumers depend on a port they can substitute instead of mocking the class."
+    },
+    schema: [],
+    messages: {
+      requireInterface: "`{{name}}` stores injected collaborator(s) ({{deps}}) but implements no interface, so every consumer depends on this concrete class and can only be tested by mocking it. Declare an interface with its public method signature(s) ({{methods}}) and `class {{name}} implements <Interface>`."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    const { filename } = context;
+    if (isTestFile(filename) || isStoryFile(filename) || isScriptFile(filename)) return {};
+    if (isGeneratedFile(filename, context.sourceCode.getText())) return {};
+    return {
+      ClassDeclaration(node) {
+        if (node.id === null) return;
+        if (!isExportedClass(node)) return;
+        if (node.abstract === true) return;
+        if (node.superClass !== null) return;
+        if (node.implements.length > 0) return;
+        if (node.decorators.length > 0) return;
+        const ctor = node.body.body.find(
+          (member) => member.type === import_utils51.AST_NODE_TYPES.MethodDefinition && member.kind === "constructor"
+        );
+        if (ctor === void 0) return;
+        const { collaborators, constructedFields } = readConstructor(ctor);
+        if (collaborators.length === 0) return;
+        if (constructedFields > collaborators.length) return;
+        if (isFrameworkWiring(node.body)) return;
+        if (isTransportWrapper(node.id.name, collaborators, context.sourceCode.ast)) return;
+        const methods = publicMethodNames(node.body);
+        if (methods.length === 0) return;
+        context.report({
+          node: node.id,
+          messageId: "requireInterface",
+          data: {
+            name: node.id.name,
+            deps: collaborators.map((c) => `${c.name}: ${c.display}`).join(", "),
+            methods: methods.join(", ")
+          }
+        });
+      }
+    };
+  }
+});
+
+// src/rules/prefer-non-nullable-collection.ts
+var import_utils52 = require("@typescript-eslint/utils");
+var ARRAY_TYPE_NAMES = /* @__PURE__ */ new Set(["Array", "ReadonlyArray"]);
+function propertyName(node) {
+  const key = node.key;
+  if (key.type === import_utils52.AST_NODE_TYPES.Identifier) return key.name;
+  if (key.type === import_utils52.AST_NODE_TYPES.Literal) return String(key.value);
+  return "collection";
+}
+function isArrayType(node) {
+  if (node.type === import_utils52.AST_NODE_TYPES.TSArrayType) return true;
+  return node.type === import_utils52.AST_NODE_TYPES.TSTypeReference && node.typeName.type === import_utils52.AST_NODE_TYPES.Identifier && ARRAY_TYPE_NAMES.has(node.typeName.name);
+}
+function isNullishType(node) {
+  return node.type === import_utils52.AST_NODE_TYPES.TSNullKeyword || node.type === import_utils52.AST_NODE_TYPES.TSUndefinedKeyword;
+}
+function isNullableArrayOnly(node) {
+  const values = node.types.filter((member) => !isNullishType(member));
+  return values.length > 0 && values.length < node.types.length && values.every(isArrayType);
+}
+var prefer_non_nullable_collection_default = import_utils52.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/standards/tree/main/packages/typescript#${name}`
+)({
+  name: "prefer-non-nullable-collection",
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require array types to use an empty array instead of explicit nullish unions with two equivalent empty states."
+    },
+    schema: [],
+    messages: {
+      preferNonNullableCollection: "`{{name}}` is a nullable array, so nullish and `[]` represent the same empty collection. Use a non-null array and default omitted values to `[]`."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    const normalizedFilename = context.filename.replaceAll("\\", "/");
+    if (isTestFile(context.filename) || isGeneratedFile(context.filename, context.sourceCode.text) || /\/(?:vendor|vendored)\//u.test(normalizedFilename)) {
+      return {};
+    }
+    function checkOptionalProperty(node) {
+      const annotation = node.typeAnnotation?.typeAnnotation;
+      if (annotation === void 0) return;
+      if (annotation.type !== import_utils52.AST_NODE_TYPES.TSUnionType || !isNullableArrayOnly(annotation)) {
+        return;
+      }
+      context.report({
+        node,
+        messageId: "preferNonNullableCollection",
+        data: { name: propertyName(node) }
+      });
+    }
+    return {
+      TSPropertySignature: checkOptionalProperty,
+      PropertyDefinition: checkOptionalProperty,
+      TSTypeAliasDeclaration(node) {
+        if (node.typeAnnotation.type !== import_utils52.AST_NODE_TYPES.TSUnionType) return;
+        if (!isNullableArrayOnly(node.typeAnnotation)) return;
+        context.report({
+          node,
+          messageId: "preferNonNullableCollection",
+          data: { name: node.id.name }
+        });
+      }
+    };
+  }
+});
+
 // src/index.ts
 var rules = {
   "enforce-file-structure": enforce_file_structure_default,
@@ -7307,12 +7541,14 @@ var rules = {
   "jsdoc-restates-signature": jsdoc_restates_signature_default,
   "no-restated-comment": no_restated_comment_default,
   "trailing-value-narration": trailing_value_narration_default,
-  "no-tautological-expect": no_tautological_expect_default
+  "no-tautological-expect": no_tautological_expect_default,
+  "require-interface-for-injected-service": require_interface_for_injected_service_default,
+  "prefer-non-nullable-collection": prefer_non_nullable_collection_default
 };
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "2.14.0"
+    version: "2.15.0"
   },
   rules,
   configs: {
@@ -7337,7 +7573,10 @@ var plugin = {
         "@sarj/prefer-discriminated-union": "warn",
         "@sarj/no-comment-cruft": "warn",
         // Frontend / styling — distilled from frontend PR-review mining.
-        "@sarj/prefer-semantic-colors": ["warn", { requireSemanticTokens: true }],
+        "@sarj/prefer-semantic-colors": [
+          "warn",
+          { requireSemanticTokens: true }
+        ],
         // Ported from sarj-python-lint (SARJ), corpus-validated FP~0.
         "@sarj/no-fat-try-blocks": "warn",
         "@sarj/no-cors-wildcard-with-credentials": "warn",
@@ -7387,7 +7626,13 @@ var plugin = {
         // Measured across 5,819 .ts/.tsx files (1,003 of them test files) in
         // six internal repos plus got / hono / swr / trpc: 3 hits, 3 true
         // positives, 0 false positives.
-        "@sarj/no-tautological-expect": "warn"
+        "@sarj/no-tautological-expect": "warn",
+        // Substitutability: an exported service class with injected
+        // collaborators and no interface above it can only be tested by
+        // mocking. 11-repo sweep: 229 exported classes, 82% already carry a
+        // port, 29 fire, 28 of them true positives.
+        "@sarj/require-interface-for-injected-service": "warn",
+        "@sarj/prefer-non-nullable-collection": "warn"
       }
     },
     strict: {
@@ -7415,7 +7660,10 @@ var plugin = {
         "@sarj/no-comment-cruft": "error",
         // Frontend / styling — distilled from frontend PR-review mining. Stylistic,
         // no autofix → warn (rollout should prove the FP rate before raising it).
-        "@sarj/prefer-semantic-colors": ["error", { requireSemanticTokens: true }],
+        "@sarj/prefer-semantic-colors": [
+          "error",
+          { requireSemanticTokens: true }
+        ],
         // Ported from sarj-python-lint (SARJ), corpus-validated FP~0.
         "@sarj/no-fat-try-blocks": "error",
         "@sarj/no-cors-wildcard-with-credentials": "error",
@@ -7457,7 +7705,12 @@ var plugin = {
         "@sarj/jsdoc-restates-signature": "error",
         "@sarj/trailing-value-narration": "error",
         // TS half of SARJ057 — see the `recommended` block for the measurement.
-        "@sarj/no-tautological-expect": "error"
+        "@sarj/no-tautological-expect": "error",
+        // Substitutability: the TS sibling of the Python `prefer-real-store-in-tests`
+        // / `prefer-library-fake` wave. The convention already exists in the
+        // corpus (175 `implements` clauses vs 29 hits), so strict enforces it.
+        "@sarj/require-interface-for-injected-service": "error",
+        "@sarj/prefer-non-nullable-collection": "error"
       }
     }
   }