@sarj/eslint-plugin 2.14.0 → 2.15.0

package/dist/index.d.cts

@@ -346,6 +346,12 @@ declare const rules: {
     "no-tautological-expect": _typescript_eslint_utils_ts_eslint.RuleModule<"tautologicalComparison" | "tautologicalMatcher", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "require-interface-for-injected-service": _typescript_eslint_utils_ts_eslint.RuleModule<"requireInterface", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    "prefer-non-nullable-collection": _typescript_eslint_utils_ts_eslint.RuleModule<"preferNonNullableCollection", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 declare const plugin: {
     meta: {
@@ -502,6 +508,12 @@ declare const plugin: {
         "no-tautological-expect": _typescript_eslint_utils_ts_eslint.RuleModule<"tautologicalComparison" | "tautologicalMatcher", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "require-interface-for-injected-service": _typescript_eslint_utils_ts_eslint.RuleModule<"requireInterface", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        "prefer-non-nullable-collection": _typescript_eslint_utils_ts_eslint.RuleModule<"preferNonNullableCollection", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
     configs: {
         recommended: {
@@ -549,6 +561,8 @@ declare const plugin: {
                 "@sarj/jsdoc-restates-signature": string;
                 "@sarj/trailing-value-narration": string;
                 "@sarj/no-tautological-expect": string;
+                "@sarj/require-interface-for-injected-service": string;
+                "@sarj/prefer-non-nullable-collection": string;
             };
         };
         strict: {
@@ -601,6 +615,8 @@ declare const plugin: {
                 "@sarj/jsdoc-restates-signature": string;
                 "@sarj/trailing-value-narration": string;
                 "@sarj/no-tautological-expect": string;
+                "@sarj/require-interface-for-injected-service": string;
+                "@sarj/prefer-non-nullable-collection": string;
             };
         };
     };

package/dist/index.d.ts

@@ -346,6 +346,12 @@ declare const rules: {
     "no-tautological-expect": _typescript_eslint_utils_ts_eslint.RuleModule<"tautologicalComparison" | "tautologicalMatcher", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "require-interface-for-injected-service": _typescript_eslint_utils_ts_eslint.RuleModule<"requireInterface", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    "prefer-non-nullable-collection": _typescript_eslint_utils_ts_eslint.RuleModule<"preferNonNullableCollection", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 declare const plugin: {
     meta: {
@@ -502,6 +508,12 @@ declare const plugin: {
         "no-tautological-expect": _typescript_eslint_utils_ts_eslint.RuleModule<"tautologicalComparison" | "tautologicalMatcher", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "require-interface-for-injected-service": _typescript_eslint_utils_ts_eslint.RuleModule<"requireInterface", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        "prefer-non-nullable-collection": _typescript_eslint_utils_ts_eslint.RuleModule<"preferNonNullableCollection", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
     configs: {
         recommended: {
@@ -549,6 +561,8 @@ declare const plugin: {
                 "@sarj/jsdoc-restates-signature": string;
                 "@sarj/trailing-value-narration": string;
                 "@sarj/no-tautological-expect": string;
+                "@sarj/require-interface-for-injected-service": string;
+                "@sarj/prefer-non-nullable-collection": string;
             };
         };
         strict: {
@@ -601,6 +615,8 @@ declare const plugin: {
                 "@sarj/jsdoc-restates-signature": string;
                 "@sarj/trailing-value-narration": string;
                 "@sarj/no-tautological-expect": string;
+                "@sarj/require-interface-for-injected-service": string;
+                "@sarj/prefer-non-nullable-collection": string;
             };
         };
     };

package/dist/index.js

@@ -9,7 +9,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);
@@ -5134,8 +5134,8 @@ var single_public_export_default = ESLintUtils29.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);
@@ -5143,11 +5143,11 @@ var single_public_export_default = ESLintUtils29.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 }
         });
       }
     };
@@ -5301,7 +5301,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 = ESLintUtils30.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
@@ -5493,7 +5493,6 @@ var no_positional_tuple_return_default = ESLintUtils31.RuleCreator(
 // src/rules/no-repeated-string-literal.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES23, ESLintUtils as ESLintUtils32 } from "@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/;
@@ -5575,9 +5574,6 @@ var no_repeated_string_literal_default = ESLintUtils32.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)
           );
@@ -7258,6 +7254,244 @@ var no_tautological_expect_default = ESLintUtils45.RuleCreator(
   }
 });
 
+// src/rules/require-interface-for-injected-service.ts
+import { AST_NODE_TYPES as AST_NODE_TYPES33, ESLintUtils as ESLintUtils46 } from "@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 === AST_NODE_TYPES33.ExportNamedDeclaration || node.parent.type === AST_NODE_TYPES33.ExportDefaultDeclaration;
+var qualifiedName = (name) => name.type === AST_NODE_TYPES33.Identifier ? name.name : name.type === AST_NODE_TYPES33.TSQualifiedName ? `${qualifiedName(name.left)}.${name.right.name}` : "";
+var typeReferenceName = (annotated) => {
+  let target = annotated;
+  if (target.type === AST_NODE_TYPES33.TSParameterProperty) target = target.parameter;
+  if (target.type === AST_NODE_TYPES33.AssignmentPattern) target = target.left;
+  if (target.type !== AST_NODE_TYPES33.Identifier) return null;
+  const annotation = target.typeAnnotation?.typeAnnotation;
+  if (annotation === void 0 || annotation.type !== AST_NODE_TYPES33.TSTypeReference) {
+    return null;
+  }
+  const { typeName } = annotation;
+  const rightmost = typeName.type === AST_NODE_TYPES33.Identifier ? typeName.name : typeName.type === AST_NODE_TYPES33.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 !== AST_NODE_TYPES33.ExpressionStatement) continue;
+      const expression = statement.expression;
+      if (expression.type !== AST_NODE_TYPES33.AssignmentExpression || expression.operator !== "=" || expression.left.type !== AST_NODE_TYPES33.MemberExpression || expression.left.object.type !== AST_NODE_TYPES33.ThisExpression) {
+        continue;
+      }
+      const source = expression.right;
+      if (source.type === AST_NODE_TYPES33.NewExpression) {
+        constructedFields += 1;
+      } else if (source.type === AST_NODE_TYPES33.Identifier) {
+        storedFrom.add(source.name);
+      } else if (source.type === AST_NODE_TYPES33.MemberExpression && source.object.type === AST_NODE_TYPES33.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 === AST_NODE_TYPES33.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 === AST_NODE_TYPES33.CallExpression) {
+    const { callee } = node;
+    if (callee.type === AST_NODE_TYPES33.Identifier) return callee.name === ROUTER_FACTORY_NAME;
+    return callee.type === AST_NODE_TYPES33.MemberExpression && !callee.computed && callee.property.type === AST_NODE_TYPES33.Identifier && callee.property.name === ROUTER_FACTORY_NAME;
+  }
+  return node.type === AST_NODE_TYPES33.TSTypeReference && node.typeName.type === AST_NODE_TYPES33.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 === AST_NODE_TYPES33.ExportNamedDeclaration ? statement.declaration : statement;
+    if (declaration?.type === AST_NODE_TYPES33.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 !== AST_NODE_TYPES33.MethodDefinition) continue;
+    if (member.kind !== "method" || member.static) continue;
+    if (member.accessibility === "private" || member.accessibility === "protected") continue;
+    if (member.key.type === AST_NODE_TYPES33.PrivateIdentifier) continue;
+    if (member.key.type === AST_NODE_TYPES33.Identifier) names.push(member.key.name);
+    else names.push("\u2026");
+  }
+  return names;
+};
+var require_interface_for_injected_service_default = ESLintUtils46.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 === AST_NODE_TYPES33.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
+import { AST_NODE_TYPES as AST_NODE_TYPES34, ESLintUtils as ESLintUtils47 } from "@typescript-eslint/utils";
+var ARRAY_TYPE_NAMES = /* @__PURE__ */ new Set(["Array", "ReadonlyArray"]);
+function propertyName(node) {
+  const key = node.key;
+  if (key.type === AST_NODE_TYPES34.Identifier) return key.name;
+  if (key.type === AST_NODE_TYPES34.Literal) return String(key.value);
+  return "collection";
+}
+function isArrayType(node) {
+  if (node.type === AST_NODE_TYPES34.TSArrayType) return true;
+  return node.type === AST_NODE_TYPES34.TSTypeReference && node.typeName.type === AST_NODE_TYPES34.Identifier && ARRAY_TYPE_NAMES.has(node.typeName.name);
+}
+function isNullishType(node) {
+  return node.type === AST_NODE_TYPES34.TSNullKeyword || node.type === AST_NODE_TYPES34.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 = ESLintUtils47.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 !== AST_NODE_TYPES34.TSUnionType || !isNullableArrayOnly(annotation)) {
+        return;
+      }
+      context.report({
+        node,
+        messageId: "preferNonNullableCollection",
+        data: { name: propertyName(node) }
+      });
+    }
+    return {
+      TSPropertySignature: checkOptionalProperty,
+      PropertyDefinition: checkOptionalProperty,
+      TSTypeAliasDeclaration(node) {
+        if (node.typeAnnotation.type !== AST_NODE_TYPES34.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,
@@ -7304,12 +7538,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: {
@@ -7334,7 +7570,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",
@@ -7384,7 +7623,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: {
@@ -7412,7 +7657,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",
@@ -7454,7 +7702,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"
       }
     }
   }