@sarj/eslint-plugin 9.15.0 → 9.16.0

package/README.md

@@ -23,7 +23,7 @@ pnpm add -D @sarj/eslint-plugin
 ```js
 // eslint.config.mjs
 import sarj from "@sarj/eslint-plugin";
-export default [...sarj.configs.recommended];
+export default [sarj.configs.recommended];
 ```
 
 67 rules. Each source under `src/rules/` states one concise claim and links to
@@ -308,7 +308,7 @@ declared stateless.
 import sarj from "@sarj/eslint-plugin";
 
 export default [
-  ...sarj.configs.strict,
+  sarj.configs.strict,
   {
     rules: {
       // This repo keeps its HTTP layer in `lib/api/`, not `clients/`.

package/dist/index.cjs

@@ -3560,6 +3560,23 @@ function runtimeExports(program) {
   const unique = new Map(exports2.map((entry) => [entry.key, entry]));
   return { exports: [...unique.values()], ambiguous };
 }
+function publicTypeExportCount(program) {
+  const names = /* @__PURE__ */ new Set();
+  const typeBindings = typeOnlyBindings(program);
+  for (const statement of program.body) {
+    if (statement.type !== import_utils21.AST_NODE_TYPES.ExportNamedDeclaration) continue;
+    const declaration = statement.declaration;
+    if (declaration?.type === import_utils21.AST_NODE_TYPES.TSInterfaceDeclaration || declaration?.type === import_utils21.AST_NODE_TYPES.TSTypeAliasDeclaration) names.add(declaration.id.name);
+    for (const specifier of statement.specifiers) {
+      const local = specifier.local.type === import_utils21.AST_NODE_TYPES.Identifier ? specifier.local.name : specifier.local.value;
+      if (statement.exportKind !== "type" && specifier.exportKind !== "type" && !typeBindings.has(local)) {
+        continue;
+      }
+      names.add(specifier.exported.type === import_utils21.AST_NODE_TYPES.Identifier ? specifier.exported.name : specifier.exported.value);
+    }
+  }
+  return names.size;
+}
 function kebabCase(name) {
   return name.replaceAll(/oauth/giu, "Oauth").replaceAll(/graphql/giu, "Graphql").replaceAll(/grpc/giu, "Grpc").replaceAll(/([a-z\d])([A-Z])/gu, "$1-$2").replaceAll(/([A-Z]+)([A-Z][a-z])/gu, "$1-$2").replaceAll(/[_\s]+/gu, "-").replaceAll(/-+/gu, "-").replaceAll(/^-|-$/gu, "").toLowerCase();
 }
@@ -3602,6 +3619,7 @@ var no_generic_single_export_module_default = createRule({
       },
       "Program:exit"(program) {
         if (hasCommonJsExport) return;
+        if ((stem3 === "type" || stem3 === "types") && publicTypeExportCount(program) >= 2) return;
         const exports2 = runtimeExports(program);
         if (exports2.ambiguous || exports2.exports.length !== 1) return;
         const onlyExport = exports2.exports[0];
@@ -3735,7 +3753,7 @@ function moduleScopeBindingName(node) {
   }
   if (topLevel.type === import_utils23.AST_NODE_TYPES.ClassDeclaration) {
     let owner = node.parent;
-    while (owner !== void 0 && owner.parent !== topLevel.body) owner = owner.parent;
+    while (owner != null && owner.parent !== topLevel.body) owner = owner.parent;
     return (owner?.type === import_utils23.AST_NODE_TYPES.MethodDefinition || owner?.type === import_utils23.AST_NODE_TYPES.TSAbstractMethodDefinition || owner?.type === import_utils23.AST_NODE_TYPES.PropertyDefinition) && owner.value === node ? topLevel.id?.name ?? (current.type === import_utils23.AST_NODE_TYPES.ExportDefaultDeclaration ? "default" : null) : null;
   }
   if (topLevel.type === import_utils23.AST_NODE_TYPES.VariableDeclaration) {
@@ -3746,7 +3764,7 @@ function moduleScopeBindingName(node) {
       if (declarator.id.type === import_utils23.AST_NODE_TYPES.Identifier && (initializer?.type === import_utils23.AST_NODE_TYPES.ClassExpression || initializer?.type === import_utils23.AST_NODE_TYPES.ObjectExpression)) {
         let owner = node.parent;
         const container = initializer.type === import_utils23.AST_NODE_TYPES.ClassExpression ? initializer.body : initializer;
-        while (owner !== void 0 && owner.parent !== container) owner = owner.parent;
+        while (owner != null && owner.parent !== container) owner = owner.parent;
         if ((owner?.type === import_utils23.AST_NODE_TYPES.MethodDefinition || owner?.type === import_utils23.AST_NODE_TYPES.PropertyDefinition || owner?.type === import_utils23.AST_NODE_TYPES.Property) && owner.value === node) return declarator.id.name;
       }
     }
@@ -3898,7 +3916,10 @@ var no_positional_tuple_return_default = createRule({
       const tuple = tupleReturnType(annotation, aliases);
       if (tuple === null || tuple.elementTypes.length < MIN_ELEMENTS) return;
       context.report({
-        node: tuple,
+        // Report the public boundary's annotation, not a shared alias declaration.
+        // Otherwise every exported function returning the same alias produces a
+        // stack of diagnostics at the alias's single source location.
+        node: annotation,
         messageId: "noPositionalTupleReturn",
         data: { name, count: String(tuple.elementTypes.length) }
       });
@@ -7539,6 +7560,7 @@ var prefer_input_group_search_default = createRule({
 // src/rules/prefer-immutable-module-constant.ts
 var import_utils52 = require("@typescript-eslint/utils");
 var CONSTANT_NAME = /^_?[A-Z][A-Z0-9_]*$/;
+var JAVASCRIPT_FILE_RE = /\.[cm]?jsx?$/i;
 var MUTATING_METHODS = /* @__PURE__ */ new Set([
   "add",
   "clear",
@@ -7662,7 +7684,7 @@ var prefer_immutable_module_constant_default = createRule({
       const variable = import_utils52.ASTUtils.findVariable(sourceCode.getScope(identifier), identifier.name);
       return variable === null || variable.defs.length === 0;
     };
-    if (isTestFile(context.filename) || isGeneratedFile(context.filename, sourceCode.getText())) {
+    if (JAVASCRIPT_FILE_RE.test(context.filename) || isTestFile(context.filename) || isGeneratedFile(context.filename, sourceCode.getText())) {
       return {};
     }
     const exportedNames2 = /* @__PURE__ */ new Set();
@@ -10772,6 +10794,9 @@ var HTTP_TRANSPORT_TYPE_RE = /^(?:KyInstance|AxiosInstance|Session)$/;
 var BUILTIN_CONTAINER_TYPE_RE = /^(?:Record|Map|WeakMap|Set|WeakSet|Array|ReadonlyArray|ReadonlyMap|ReadonlySet|Promise|Partial|Required|Readonly|Pick|Omit|Exclude|Extract|NonNullable|Awaited|Parameters|ReturnType|InstanceType)$/;
 var VALUE_TYPE_RE = /^(?:ArrayBuffer|Blob|Buffer|Date|RegExp|URL|URLSearchParams)$/;
 var TRANSPORT_WRAPPER_NAME_RE = /Client$/;
+var ERROR_VALUE_NAME_RE = /Error$/;
+var FLUENT_BUILDER_NAME_RE = /Builder$/;
+var FLUENT_RESULT_TYPE_RE = /(?:Builder|Base|Query|Without)(?:\W|$)/;
 var ROUTER_FACTORY_NAME = "Router";
 var FRAMEWORK_HTTP_TYPES = /* @__PURE__ */ new Set(["Request", "Response", "NextFunction"]);
 var STORAGE_ASSIGNMENT_OPERATORS = /* @__PURE__ */ new Set(["=", "&&=", "??=", "||="]);
@@ -11013,6 +11038,19 @@ var publicMethodNames = (body2, functionAliases) => {
   }
   return names;
 };
+var isFluentConstructionObject = (node, getText) => {
+  if (node.id === null) return false;
+  const methods = node.body.body.filter(
+    (member) => member.type === import_utils67.AST_NODE_TYPES.MethodDefinition && member.kind === "method" && !member.static && member.accessibility !== "private" && member.accessibility !== "protected" && member.value.body !== null
+  );
+  if (methods.length === 0) return false;
+  return methods.every((member) => {
+    const result = member.value.returnType?.typeAnnotation;
+    if (result === void 0) return false;
+    const returnsOwnType = result.type === import_utils67.AST_NODE_TYPES.TSTypeReference && result.typeName.type === import_utils67.AST_NODE_TYPES.Identifier && result.typeName.name === node.id?.name;
+    return returnsOwnType || FLUENT_BUILDER_NAME_RE.test(node.id?.name ?? "") && FLUENT_RESULT_TYPE_RE.test(getText(result));
+  });
+};
 function localClassAbstractness(program) {
   const classes = /* @__PURE__ */ new Map();
   const parents = /* @__PURE__ */ new Map();
@@ -11158,6 +11196,7 @@ var require_interface_for_injected_service_default = createRule({
       ClassDeclaration(node) {
         if (node.id === null) return;
         if (!isExportedClass2(node, detachedExports)) return;
+        if (ERROR_VALUE_NAME_RE.test(node.id.name)) return;
         if (node.abstract === true) return;
         if (node.decorators.length > 0) return;
         const ctor = node.body.body.find(
@@ -11173,6 +11212,7 @@ var require_interface_for_injected_service_default = createRule({
         if (constructedFields > collaborators.length) return;
         if (isFrameworkWiring(node.body)) return;
         if (isTransportWrapper(node.id.name, collaborators, context.sourceCode.ast)) return;
+        if (isFluentConstructionObject(node, (result) => context.sourceCode.getText(result))) return;
         const methods = publicMethodNames(node.body, objectTypes().functionAliases);
         if (methods.length === 0) return;
         if (hasServicePort(node, methods, localClasses, localInterfaces)) return;
@@ -12032,7 +12072,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "9.15.0"
+  version: "9.16.0"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",

package/dist/index.d.cts

@@ -466,7 +466,7 @@ type FlatPreset = {
 declare const plugin: {
     meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "9.15.0";
+        readonly version: "9.16.0";
     };
     rules: {
         "duplicate-test-body": _typescript_eslint_utils_ts_eslint.RuleModule<"duplicateTestBody", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {

package/dist/index.d.ts

@@ -466,7 +466,7 @@ type FlatPreset = {
 declare const plugin: {
     meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "9.15.0";
+        readonly version: "9.16.0";
     };
     rules: {
         "duplicate-test-body": _typescript_eslint_utils_ts_eslint.RuleModule<"duplicateTestBody", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {

package/dist/index.js

@@ -3518,6 +3518,23 @@ function runtimeExports(program) {
   const unique = new Map(exports.map((entry) => [entry.key, entry]));
   return { exports: [...unique.values()], ambiguous };
 }
+function publicTypeExportCount(program) {
+  const names = /* @__PURE__ */ new Set();
+  const typeBindings = typeOnlyBindings(program);
+  for (const statement of program.body) {
+    if (statement.type !== AST_NODE_TYPES15.ExportNamedDeclaration) continue;
+    const declaration = statement.declaration;
+    if (declaration?.type === AST_NODE_TYPES15.TSInterfaceDeclaration || declaration?.type === AST_NODE_TYPES15.TSTypeAliasDeclaration) names.add(declaration.id.name);
+    for (const specifier of statement.specifiers) {
+      const local = specifier.local.type === AST_NODE_TYPES15.Identifier ? specifier.local.name : specifier.local.value;
+      if (statement.exportKind !== "type" && specifier.exportKind !== "type" && !typeBindings.has(local)) {
+        continue;
+      }
+      names.add(specifier.exported.type === AST_NODE_TYPES15.Identifier ? specifier.exported.name : specifier.exported.value);
+    }
+  }
+  return names.size;
+}
 function kebabCase(name) {
   return name.replaceAll(/oauth/giu, "Oauth").replaceAll(/graphql/giu, "Graphql").replaceAll(/grpc/giu, "Grpc").replaceAll(/([a-z\d])([A-Z])/gu, "$1-$2").replaceAll(/([A-Z]+)([A-Z][a-z])/gu, "$1-$2").replaceAll(/[_\s]+/gu, "-").replaceAll(/-+/gu, "-").replaceAll(/^-|-$/gu, "").toLowerCase();
 }
@@ -3560,6 +3577,7 @@ var no_generic_single_export_module_default = createRule({
       },
       "Program:exit"(program) {
         if (hasCommonJsExport) return;
+        if ((stem3 === "type" || stem3 === "types") && publicTypeExportCount(program) >= 2) return;
         const exports = runtimeExports(program);
         if (exports.ambiguous || exports.exports.length !== 1) return;
         const onlyExport = exports.exports[0];
@@ -3693,7 +3711,7 @@ function moduleScopeBindingName(node) {
   }
   if (topLevel.type === AST_NODE_TYPES16.ClassDeclaration) {
     let owner = node.parent;
-    while (owner !== void 0 && owner.parent !== topLevel.body) owner = owner.parent;
+    while (owner != null && owner.parent !== topLevel.body) owner = owner.parent;
     return (owner?.type === AST_NODE_TYPES16.MethodDefinition || owner?.type === AST_NODE_TYPES16.TSAbstractMethodDefinition || owner?.type === AST_NODE_TYPES16.PropertyDefinition) && owner.value === node ? topLevel.id?.name ?? (current.type === AST_NODE_TYPES16.ExportDefaultDeclaration ? "default" : null) : null;
   }
   if (topLevel.type === AST_NODE_TYPES16.VariableDeclaration) {
@@ -3704,7 +3722,7 @@ function moduleScopeBindingName(node) {
       if (declarator.id.type === AST_NODE_TYPES16.Identifier && (initializer?.type === AST_NODE_TYPES16.ClassExpression || initializer?.type === AST_NODE_TYPES16.ObjectExpression)) {
         let owner = node.parent;
         const container = initializer.type === AST_NODE_TYPES16.ClassExpression ? initializer.body : initializer;
-        while (owner !== void 0 && owner.parent !== container) owner = owner.parent;
+        while (owner != null && owner.parent !== container) owner = owner.parent;
         if ((owner?.type === AST_NODE_TYPES16.MethodDefinition || owner?.type === AST_NODE_TYPES16.PropertyDefinition || owner?.type === AST_NODE_TYPES16.Property) && owner.value === node) return declarator.id.name;
       }
     }
@@ -3856,7 +3874,10 @@ var no_positional_tuple_return_default = createRule({
       const tuple = tupleReturnType(annotation, aliases);
       if (tuple === null || tuple.elementTypes.length < MIN_ELEMENTS) return;
       context.report({
-        node: tuple,
+        // Report the public boundary's annotation, not a shared alias declaration.
+        // Otherwise every exported function returning the same alias produces a
+        // stack of diagnostics at the alias's single source location.
+        node: annotation,
         messageId: "noPositionalTupleReturn",
         data: { name, count: String(tuple.elementTypes.length) }
       });
@@ -7500,6 +7521,7 @@ var prefer_input_group_search_default = createRule({
 // src/rules/prefer-immutable-module-constant.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES38, ASTUtils as ASTUtils6 } from "@typescript-eslint/utils";
 var CONSTANT_NAME = /^_?[A-Z][A-Z0-9_]*$/;
+var JAVASCRIPT_FILE_RE = /\.[cm]?jsx?$/i;
 var MUTATING_METHODS = /* @__PURE__ */ new Set([
   "add",
   "clear",
@@ -7623,7 +7645,7 @@ var prefer_immutable_module_constant_default = createRule({
       const variable = ASTUtils6.findVariable(sourceCode.getScope(identifier), identifier.name);
       return variable === null || variable.defs.length === 0;
     };
-    if (isTestFile(context.filename) || isGeneratedFile(context.filename, sourceCode.getText())) {
+    if (JAVASCRIPT_FILE_RE.test(context.filename) || isTestFile(context.filename) || isGeneratedFile(context.filename, sourceCode.getText())) {
       return {};
     }
     const exportedNames2 = /* @__PURE__ */ new Set();
@@ -10736,6 +10758,9 @@ var HTTP_TRANSPORT_TYPE_RE = /^(?:KyInstance|AxiosInstance|Session)$/;
 var BUILTIN_CONTAINER_TYPE_RE = /^(?:Record|Map|WeakMap|Set|WeakSet|Array|ReadonlyArray|ReadonlyMap|ReadonlySet|Promise|Partial|Required|Readonly|Pick|Omit|Exclude|Extract|NonNullable|Awaited|Parameters|ReturnType|InstanceType)$/;
 var VALUE_TYPE_RE = /^(?:ArrayBuffer|Blob|Buffer|Date|RegExp|URL|URLSearchParams)$/;
 var TRANSPORT_WRAPPER_NAME_RE = /Client$/;
+var ERROR_VALUE_NAME_RE = /Error$/;
+var FLUENT_BUILDER_NAME_RE = /Builder$/;
+var FLUENT_RESULT_TYPE_RE = /(?:Builder|Base|Query|Without)(?:\W|$)/;
 var ROUTER_FACTORY_NAME = "Router";
 var FRAMEWORK_HTTP_TYPES = /* @__PURE__ */ new Set(["Request", "Response", "NextFunction"]);
 var STORAGE_ASSIGNMENT_OPERATORS = /* @__PURE__ */ new Set(["=", "&&=", "??=", "||="]);
@@ -10977,6 +11002,19 @@ var publicMethodNames = (body2, functionAliases) => {
   }
   return names;
 };
+var isFluentConstructionObject = (node, getText) => {
+  if (node.id === null) return false;
+  const methods = node.body.body.filter(
+    (member) => member.type === AST_NODE_TYPES52.MethodDefinition && member.kind === "method" && !member.static && member.accessibility !== "private" && member.accessibility !== "protected" && member.value.body !== null
+  );
+  if (methods.length === 0) return false;
+  return methods.every((member) => {
+    const result = member.value.returnType?.typeAnnotation;
+    if (result === void 0) return false;
+    const returnsOwnType = result.type === AST_NODE_TYPES52.TSTypeReference && result.typeName.type === AST_NODE_TYPES52.Identifier && result.typeName.name === node.id?.name;
+    return returnsOwnType || FLUENT_BUILDER_NAME_RE.test(node.id?.name ?? "") && FLUENT_RESULT_TYPE_RE.test(getText(result));
+  });
+};
 function localClassAbstractness(program) {
   const classes = /* @__PURE__ */ new Map();
   const parents = /* @__PURE__ */ new Map();
@@ -11122,6 +11160,7 @@ var require_interface_for_injected_service_default = createRule({
       ClassDeclaration(node) {
         if (node.id === null) return;
         if (!isExportedClass2(node, detachedExports)) return;
+        if (ERROR_VALUE_NAME_RE.test(node.id.name)) return;
         if (node.abstract === true) return;
         if (node.decorators.length > 0) return;
         const ctor = node.body.body.find(
@@ -11137,6 +11176,7 @@ var require_interface_for_injected_service_default = createRule({
         if (constructedFields > collaborators.length) return;
         if (isFrameworkWiring(node.body)) return;
         if (isTransportWrapper(node.id.name, collaborators, context.sourceCode.ast)) return;
+        if (isFluentConstructionObject(node, (result) => context.sourceCode.getText(result))) return;
         const methods = publicMethodNames(node.body, objectTypes().functionAliases);
         if (methods.length === 0) return;
         if (hasServicePort(node, methods, localClasses, localInterfaces)) return;
@@ -11996,7 +12036,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "9.15.0"
+  version: "9.16.0"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/eslint-plugin",
-  "version": "9.15.0",
+  "version": "9.16.0",
   "packageManager": "npm@11.19.0",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",