@sarj/eslint-plugin 2.15.0 → 2.16.0

package/dist/index.cjs

@@ -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;
@@ -7495,6 +7515,204 @@ var prefer_non_nullable_collection_default = import_utils52.ESLintUtils.RuleCrea
   }
 });
 
+// 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,
@@ -7523,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,
@@ -7543,12 +7762,13 @@ var rules = {
   "trailing-value-narration": trailing_value_narration_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
+  "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.15.0"
+    version: "2.16.0"
   },
   rules,
   configs: {
@@ -7583,6 +7803,7 @@ var plugin = {
         "@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",
@@ -7632,7 +7853,8 @@ var plugin = {
         // 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/prefer-non-nullable-collection": "warn",
+        "@sarj/no-implicit-attribute-access": "warn"
       }
     },
     strict: {
@@ -7670,6 +7892,7 @@ var plugin = {
         "@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).
@@ -7710,7 +7933,8 @@ var plugin = {
         // / `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/prefer-non-nullable-collection": "error",
+        "@sarj/no-implicit-attribute-access": "error"
       }
     }
   }