@sarj/eslint-plugin 2.14.0 → 2.16.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);
@@ -467,9 +467,9 @@ function restatesStatementHead(body, statement) {
 
 // src/rules/no-comment-cruft.ts
 var LEADING_PREAMBLE_MIN = 4;
-var STEP_NARRATION_RE = /^(?:first(?:ly)?|second(?:ly)?|third(?:ly)?|then|next|after(?:wards| that)?|finally|lastly|now)\s*[,:]\s*\S|^step\s+\d+\b/i;
+var STEP_NARRATION_RE = /^(?:first(?:ly)?|second(?:ly)?|third(?:ly)?|then|next|after(?:wards| that)?|finally|lastly|now)\s*[,:]\s*\S/i;
 var META_COMMENTARY_RE = /\b(?:for now|keeping (?:it|this) simple|could be (?:refactored|improved|cleaned up|simplified)|refactor(?:ed|ing)? (?:later|this)|not sure (?:if|whether|why|how)|quick[- ](?:and[- ]dirty|fix)|(?:a |bit of a )?hacky|is a hack|temporary (?:solution|workaround|fix|hack)|revisit (?:this|later|below)|clean (?:this|it) up|not ideal|placeholder for now)\b/i;
-var DIRECTIVE_RE = /^(eslint\b|eslint-|sarj-noqa\b|@ts-|prettier-ignore|prettier\b|biome-|c8\b|v8\b|istanbul\b|@type\b|@vite|webpack|<reference|<amd|global\b|noinspection|todo\b|fixme\b|hack\b|xxx\b)/i;
+var DIRECTIVE_RE = /^(eslint\b|eslint-|sarj-noqa\b|@ts-|prettier-ignore|prettier\b|biome-|c8\b|v8\b|istanbul\b|@type\b|@vite|webpack|<reference|<amd|global\b|noinspection|hack\b|xxx\b)/i;
 var LICENSE_RE = /copyright|licen[cs]ed?|spdx|permission is hereby granted|all rights reserved/i;
 var ENUMERATED_ITEM_RE = /^(?:\d+[.):]|[-*•])\s+\S/;
 var ENUMERATED_ITEM_MIN_WORDS = 3;
@@ -535,7 +535,8 @@ function isSectionLabel(text) {
 }
 var HELPER_OPENER_RE = /^(?:a\s+)?helper\s+(?:function|method|component|hook|class|type|util(?:ity)?)\b/i;
 var LETS_RE = /^let'?s\s+(?:not\s+|just\s+|now\s+|first\s+)?(?:add|append|assign|await|build|calculate|call|check|clear|close|compute|convert|copy|count|create|declare|decrement|define|delete|extract|fetch|filter|find|format|generate|get|handle|increment|init|initialise|initialize|insert|iterate|join|load|log|loop|map|merge|open|parse|print|process|push|read|remove|render|reset|return|save|send|set|setup|sort|split|start|stop|store|update|validate|wrap|write)(?:s|es|ed|ing)?\b/i;
-var ENUMERATION_RE = /^(?:\d+[.)]\s+\S|phase\s+\d+\b)/i;
+var ENUMERATION_RE = /^(?:\d+[.)]\s+\S|(?:phase|step)\s+\d+\b)/i;
+var DUMMY_TRANSLATION_RE = /^(?:increment|return|returns|get|gets|set\b(?! up\b)|sets\b(?! up\b)|function to|method to)\b/i;
 var DIAGRAM_ARROW_RE = /[-=~]{2,}>|<[-=~]{2,}/;
 var CODE_KEYWORD_RE = /^(import |export |const |let |var |function\b|class |interface |type \w|enum |return\b|throw |await |async |if\s*\(|for\s*\(|while\s*\(|switch\s*\(|new |console\.)/;
 var CODE_TAIL_RE = /[;{}()]\s*$|=>\s*$|,\s*$/;
@@ -583,6 +584,14 @@ function isRedundantNarration(body, statementBelow, standalone, isolatedEnumerat
     if (STEP_NARRATION_RE.test(t)) return true;
     if (META_COMMENTARY_RE.test(t) && !JUSTIFICATION_RE.test(t)) return true;
     if (HELPER_OPENER_RE.test(t) || LETS_RE.test(t)) return true;
+    const words = t.split(/\s+/);
+    if (words.length <= 4 && DUMMY_TRANSLATION_RE.test(t) && !/[():=]/.test(t)) {
+      const lowerT = t.toLowerCase();
+      const rationaleWords = ["when", "because", "if", "so that", "due to", "for", "instead of", "to prevent", "to avoid", "only"];
+      if (!rationaleWords.some((w) => lowerT.includes(w))) {
+        if (words.length > 1) return true;
+      }
+    }
     if (!nested && isSectionLabel(t)) return true;
     if (isolatedEnumeration && ENUMERATION_RE.test(t)) return true;
   }
@@ -650,7 +659,8 @@ var no_comment_cruft_default = import_utils4.ESLintUtils.RuleCreator(
       commentedOutCode: "Commented-out code \u2014 delete it; git history remembers.",
       sectionBanner: "Section-banner / region comment \u2014 structure code with functions, not ASCII rules.",
       fileHeaderPreamble: "File-header comment preamble \u2014 use a brief doc comment for the why, not a block of `//` lines.",
-      redundantNarration: "Comment narrates the code \u2014 delete it or say *why*, not *what*. Code is self-documenting."
+      redundantNarration: "Comment narrates the code \u2014 delete it or say *why*, not *what*. Code is self-documenting.",
+      untrackedTodo: "Untracked TODO/FIXME marker \u2014 add an issue ticket or context link."
     }
   },
   defaultOptions: [],
@@ -704,6 +714,16 @@ var no_comment_cruft_default = import_utils4.ESLintUtils.RuleCreator(
           if (isJsDoc(comment) || !isStandalone(comment)) continue;
           if (LICENSE_RE.test(comment.value)) continue;
           const texts = comment.value.split("\n").map(stripCommentMarker).filter((l) => l.length > 0 && !isDirective(l));
+          const firstText = texts[0];
+          if (firstText !== void 0 && /^(?:todo|fixme)\b/i.test(firstText)) {
+            if (!runCitesAReference(comments, i)) {
+              context.report({
+                node: comment,
+                messageId: "untrackedTodo"
+              });
+            }
+            continue;
+          }
           if (texts.some(isBanner)) {
             context.report({ node: comment, messageId: "sectionBanner" });
             continue;
@@ -5143,8 +5163,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 +5172,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 +5330,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 +5522,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 +5603,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 +7277,442 @@ 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/rules/primary-export-file-name.ts
+var import_utils53 = require("@typescript-eslint/utils");
+var CONVENTIONAL_BUCKET_EXPORTS2 = /* @__PURE__ */ new Set(["cn"]);
+var GENERIC_ENTRYPOINTS = /* @__PURE__ */ new Set(["main", "run", "cli", "setup", "teardown", "execute"]);
+var ACRONYM_OVERRIDES2 = [
+  [/OAuth/g, "Oauth"],
+  [/GraphQL/g, "Graphql"],
+  [/gRPC/g, "Grpc"]
+];
+var CAMEL_BOUNDARY_RE2 = /(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g;
+var basename2 = (filename) => filename.split(/[/\\]/).pop() ?? filename;
+var stemOf2 = (base) => base.replace(/\.(test|spec|config|d|stories)\.[cm]?[jt]sx?$/i, "").replace(/\.[cm]?[jt]sx?$/i, "");
+var kebabCase3 = (name) => {
+  let normalized = name;
+  for (const [pattern, replacement] of ACRONYM_OVERRIDES2) {
+    normalized = normalized.replace(pattern, replacement);
+  }
+  return normalized.replace(CAMEL_BOUNDARY_RE2, "-").toLowerCase();
+};
+var isFunctionOrClass = (node) => node.type === import_utils53.AST_NODE_TYPES.ArrowFunctionExpression || node.type === import_utils53.AST_NODE_TYPES.FunctionExpression;
+var findPrimaryExport = (body) => {
+  let exportCount = 0;
+  let primaryCandidate = null;
+  for (const statement of body) {
+    if (statement.type === import_utils53.AST_NODE_TYPES.ExportAllDeclaration) {
+      return null;
+    }
+    if (statement.type === import_utils53.AST_NODE_TYPES.ExportDefaultDeclaration) {
+      exportCount += 1;
+      const decl = statement.declaration;
+      if ((decl.type === import_utils53.AST_NODE_TYPES.FunctionDeclaration || decl.type === import_utils53.AST_NODE_TYPES.ClassDeclaration) && decl.id !== null) {
+        primaryCandidate = { name: decl.id.name, node: statement, isDefault: true };
+      } else if (decl.type === import_utils53.AST_NODE_TYPES.Identifier) {
+        primaryCandidate = { name: decl.name, node: statement, isDefault: true };
+      }
+    } else if (statement.type === import_utils53.AST_NODE_TYPES.ExportNamedDeclaration) {
+      if (statement.source !== null) {
+        return null;
+      }
+      const decl = statement.declaration;
+      if (decl === null) {
+        exportCount += statement.specifiers.length;
+        if (statement.specifiers.length === 1 && primaryCandidate === null) {
+          const spec = statement.specifiers[0];
+          if (spec && spec.exported.type === import_utils53.AST_NODE_TYPES.Identifier) {
+            primaryCandidate = { name: spec.exported.name, node: statement, isDefault: false };
+          }
+        }
+      } else if (decl.type === import_utils53.AST_NODE_TYPES.FunctionDeclaration || decl.type === import_utils53.AST_NODE_TYPES.ClassDeclaration) {
+        if (decl.id !== null) {
+          exportCount += 1;
+          if (primaryCandidate === null) {
+            primaryCandidate = { name: decl.id.name, node: statement, isDefault: false };
+          }
+        }
+      } else if (decl.type === import_utils53.AST_NODE_TYPES.VariableDeclaration) {
+        for (const declarator of decl.declarations) {
+          if (declarator.id.type === import_utils53.AST_NODE_TYPES.Identifier) {
+            exportCount += 1;
+            if (primaryCandidate === null && declarator.init && isFunctionOrClass(declarator.init)) {
+              primaryCandidate = { name: declarator.id.name, node: statement, isDefault: false };
+            }
+          }
+        }
+      } else if (decl.type === import_utils53.AST_NODE_TYPES.TSTypeAliasDeclaration || decl.type === import_utils53.AST_NODE_TYPES.TSInterfaceDeclaration) {
+        exportCount += 1;
+        if (primaryCandidate === null) {
+          primaryCandidate = { name: decl.id.name, node: statement, isDefault: false };
+        }
+      }
+    }
+  }
+  if (primaryCandidate === null || exportCount > 2) {
+    return null;
+  }
+  return { ...primaryCandidate, count: exportCount };
+};
+var primary_export_file_name_default = import_utils53.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
+)({
+  name: "primary-export-file-name",
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Enforce semantic naming alignment: a file with a single primary export must be named after that export."
+    },
+    schema: [],
+    messages: {
+      primaryExportMismatch: "Module stem '{{stem}}' does not match its primary export '{{name}}' \u2014 rename the file to '{{expected}}{{ext}}' to describe its responsibility."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    const base = basename2(context.filename);
+    if (base.endsWith(".d.ts") || base.startsWith("index.") || base.startsWith("_")) return {};
+    if (isTestFile(context.filename) || isGeneratedFile(context.filename, context.sourceCode.text)) return {};
+    const stem3 = stemOf2(base);
+    if (stem3 === "page" || stem3 === "layout" || stem3 === "loading" || stem3 === "error" || stem3 === "not-found" || stem3 === "route" || stem3 === "__root" || stem3 === "config" || stem3 === "constants" || stem3 === "types" || stem3.startsWith("$") || stem3.startsWith("[")) {
+      return {};
+    }
+    return {
+      Program(node) {
+        const primary = findPrimaryExport(node.body);
+        if (primary === null) return;
+        if (CONVENTIONAL_BUCKET_EXPORTS2.has(primary.name) || GENERIC_ENTRYPOINTS.has(primary.name)) return;
+        const expectedStem = kebabCase3(primary.name);
+        if (stem3 === expectedStem) return;
+        const ext = base.endsWith(".tsx") ? ".tsx" : ".ts";
+        context.report({
+          node: primary.node,
+          messageId: "primaryExportMismatch",
+          data: { stem: stem3, name: primary.name, expected: expectedStem, ext }
+        });
+      }
+    };
+  }
+});
+
+// src/rules/no-implicit-attribute-access.ts
+var import_utils54 = require("@typescript-eslint/utils");
+var EXCLUDED_BASES = /* @__PURE__ */ new Set([
+  "environ",
+  "headers",
+  "cookies",
+  "session",
+  "redis",
+  "cache",
+  "state",
+  "config",
+  "env",
+  "process",
+  "localStorage",
+  "sessionStorage"
+]);
+function getBaseName(node) {
+  if (node.type === import_utils54.AST_NODE_TYPES.Identifier) {
+    return node.name;
+  }
+  if (node.type === import_utils54.AST_NODE_TYPES.MemberExpression && node.property.type === import_utils54.AST_NODE_TYPES.Identifier) {
+    return node.property.name;
+  }
+  return null;
+}
+var no_implicit_attribute_access_default = import_utils54.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
+)({
+  name: "no-implicit-attribute-access",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow imperative dictionary access with string literals; use declarative Zod schemas."
+    },
+    schema: [],
+    messages: {
+      noImplicitAttributeAccess: "Imperative lookup for '{{key}}' \u2014 if the key is known, parse the object declaratively with a Zod schema instead."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (!node.computed) {
+          return;
+        }
+        if (node.property.type === import_utils54.AST_NODE_TYPES.Literal && typeof node.property.value === "string") {
+          const baseName = getBaseName(node.object);
+          if (!baseName || !EXCLUDED_BASES.has(baseName)) {
+            context.report({
+              node,
+              messageId: "noImplicitAttributeAccess",
+              data: { key: node.property.value }
+            });
+          }
+        }
+      },
+      CallExpression(node) {
+        const callee = node.callee;
+        if (callee.type === import_utils54.AST_NODE_TYPES.MemberExpression) {
+          const method = callee.property.type === import_utils54.AST_NODE_TYPES.Identifier ? callee.property.name : null;
+          if (method === "get") {
+            const arg = node.arguments[0];
+            if (arg && arg.type === import_utils54.AST_NODE_TYPES.Literal && typeof arg.value === "string") {
+              const baseName = getBaseName(callee.object);
+              if (!baseName || !EXCLUDED_BASES.has(baseName)) {
+                context.report({
+                  node,
+                  messageId: "noImplicitAttributeAccess",
+                  data: { key: arg.value }
+                });
+              }
+            }
+          }
+        }
+      }
+    };
+  }
+});
+
 // src/index.ts
 var rules = {
   "enforce-file-structure": enforce_file_structure_default,
@@ -7289,6 +7741,7 @@ var rules = {
   "no-unsafe-cast": no_unsafe_cast_default,
   "prefer-string-literal-union": prefer_string_literal_union_default,
   "single-public-export": single_public_export_default,
+  "primary-export-file-name": primary_export_file_name_default,
   "no-silent-promise-catch": no_silent_promise_catch_default,
   "require-fetch-timeout": require_fetch_timeout_default,
   "require-schema-validate-search": require_schema_validate_search_default,
@@ -7307,12 +7760,15 @@ 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,
+  "no-implicit-attribute-access": no_implicit_attribute_access_default
 };
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "2.14.0"
+    version: "2.16.0"
   },
   rules,
   configs: {
@@ -7337,13 +7793,17 @@ 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",
         "@sarj/no-secret-in-log": "warn",
         "@sarj/no-unsafe-cast": "warn",
         "@sarj/single-public-export": "warn",
+        "@sarj/primary-export-file-name": "warn",
         "@sarj/prefer-string-literal-union": "warn",
         // Mined from 2y of PR review feedback + 5-repo code-smell audit (2026-07).
         "@sarj/require-fetch-timeout": "warn",
@@ -7387,7 +7847,14 @@ 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",
+        "@sarj/no-implicit-attribute-access": "warn"
       }
     },
     strict: {
@@ -7415,13 +7882,17 @@ 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",
         "@sarj/no-secret-in-log": "error",
         "@sarj/no-unsafe-cast": "error",
         "@sarj/single-public-export": "error",
+        "@sarj/primary-export-file-name": "error",
         // Promoted to error 2026-07-25 — strict means strict (user directive).
         "@sarj/prefer-string-literal-union": "error",
         // Mined from 2y of PR review feedback + 5-repo code-smell audit (2026-07).
@@ -7457,7 +7928,13 @@ 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",
+        "@sarj/no-implicit-attribute-access": "error"
       }
     }
   }