@sarj/eslint-plugin 2.4.1 → 2.6.0

package/dist/index.cjs

@@ -247,6 +247,8 @@ var no_client_side_data_fetching_default = import_utils2.ESLintUtils.RuleCreator
 // src/rules/no-comment-cruft.ts
 var import_utils3 = require("@typescript-eslint/utils");
 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 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-|@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 LICENSE_RE = /copyright|licen[cs]ed?|spdx|permission is hereby granted|all rights reserved/i;
 var BANNER_FULL_RE = /^[\s\-=*#~_+.]{4,}$/;
@@ -285,6 +287,13 @@ function isProse(text) {
   }
   return false;
 }
+function isRedundantNarration(body) {
+  const t = body.trim();
+  if (!t || looksLikeCode(t) || hasPseudocode(t)) return false;
+  if (STEP_NARRATION_RE.test(t)) return true;
+  if (META_COMMENTARY_RE.test(t)) return true;
+  return false;
+}
 function hasCommentedOutCode(texts, precedingProse) {
   for (let i = 0; i < texts.length; i++) {
     const line = texts[i];
@@ -310,7 +319,8 @@ var no_comment_cruft_default = import_utils3.ESLintUtils.RuleCreator(
     messages: {
       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."
+      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."
     }
   },
   defaultOptions: [],
@@ -365,6 +375,13 @@ var no_comment_cruft_default = import_utils3.ESLintUtils.RuleCreator(
           const precedingProse = prev !== void 0 && prev.type === "Line" && prev.loc.end.line === comment.loc.start.line - 1 && isProse(stripCommentMarker(prev.value));
           if (hasCommentedOutCode(texts, precedingProse)) {
             context.report({ node: comment, messageId: "commentedOutCode" });
+            continue;
+          }
+          if (comment.type === "Line" && texts.length === 1) {
+            const body = texts[0];
+            if (body !== void 0 && isRedundantNarration(body)) {
+              context.report({ node: comment, messageId: "redundantNarration" });
+            }
           }
         }
         reportLeadingPreamble(comments, firstCodeLine);
@@ -3246,8 +3263,54 @@ var no_secret_in_log_default = import_utils25.ESLintUtils.RuleCreator(
   }
 });
 
-// src/rules/prefer-string-literal-union.ts
+// src/rules/no-unsafe-cast.ts
 var import_utils26 = require("@typescript-eslint/utils");
+var import_utils27 = require("@typescript-eslint/utils");
+function isAnyAnnotation(node) {
+  return node.type === import_utils27.AST_NODE_TYPES.TSAnyKeyword;
+}
+function isConstAssertion(typeAnnotation) {
+  return typeAnnotation.type === import_utils27.AST_NODE_TYPES.TSTypeReference && typeAnnotation.typeName.type === import_utils27.AST_NODE_TYPES.Identifier && typeAnnotation.typeName.name === "const";
+}
+var no_unsafe_cast_default = import_utils26.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/linting/blob/main/packages/typescript/src/rules/${name}.ts`
+)({
+  name: "no-unsafe-cast",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow `as any`/`<any>` casts and `as unknown as T` double-casts, which fully disable type checking."
+    },
+    schema: [],
+    messages: {
+      asAny: "`as any` disables type checking on this value. Narrow with a type guard, model the shape, or cast to a specific type instead.",
+      doubleCast: "`as unknown as T` double-cast bypasses the compiler's structural check. Prefer a runtime validator (e.g. a zod schema) or an accurate type at the boundary."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    function checkAssertion(node) {
+      if (isConstAssertion(node.typeAnnotation)) {
+        return;
+      }
+      if (isAnyAnnotation(node.typeAnnotation)) {
+        context.report({ node, messageId: "asAny" });
+        return;
+      }
+      const inner = node.expression;
+      if (inner.type === import_utils27.AST_NODE_TYPES.TSAsExpression || inner.type === import_utils27.AST_NODE_TYPES.TSTypeAssertion) {
+        context.report({ node, messageId: "doubleCast" });
+      }
+    }
+    return {
+      TSAsExpression: checkAssertion,
+      TSTypeAssertion: checkAssertion
+    };
+  }
+});
+
+// src/rules/prefer-string-literal-union.ts
+var import_utils28 = require("@typescript-eslint/utils");
 var ts = __toESM(require("typescript"), 1);
 var CHOICE_TOKENS = /* @__PURE__ */ new Set([
   "status",
@@ -3290,19 +3353,19 @@ function isChoiceLikeName(name) {
   return CHOICE_TOKENS.has(lastWord(name));
 }
 function keyName(key) {
-  if (key.type === import_utils26.AST_NODE_TYPES.Identifier) {
+  if (key.type === import_utils28.AST_NODE_TYPES.Identifier) {
     return key.name;
   }
-  if (key.type === import_utils26.AST_NODE_TYPES.Literal && typeof key.value === "string") {
+  if (key.type === import_utils28.AST_NODE_TYPES.Literal && typeof key.value === "string") {
     return key.value;
   }
   return null;
 }
 function isStringLiteralMember(t) {
-  return t.type === import_utils26.AST_NODE_TYPES.TSLiteralType && t.literal.type === import_utils26.AST_NODE_TYPES.Literal && typeof t.literal.value === "string";
+  return t.type === import_utils28.AST_NODE_TYPES.TSLiteralType && t.literal.type === import_utils28.AST_NODE_TYPES.Literal && typeof t.literal.value === "string";
 }
 function isStringLiteralUnion(node) {
-  if (node?.type !== import_utils26.AST_NODE_TYPES.TSUnionType) {
+  if (node?.type !== import_utils28.AST_NODE_TYPES.TSUnionType) {
     return false;
   }
   return node.types.filter(isStringLiteralMember).length >= MIN_CLUSTER_SIZE;
@@ -3331,12 +3394,12 @@ function bindingSourceExpression(decl) {
   return ts.isForOfStatement(node) ? node.expression : node.initializer;
 }
 function refKey(node) {
-  if (node.type === import_utils26.AST_NODE_TYPES.Identifier) {
+  if (node.type === import_utils28.AST_NODE_TYPES.Identifier) {
     return node.name;
   }
-  if (node.type === import_utils26.AST_NODE_TYPES.MemberExpression && !node.computed) {
+  if (node.type === import_utils28.AST_NODE_TYPES.MemberExpression && !node.computed) {
     const inner = refKey(node.object);
-    if (inner === null || node.property.type !== import_utils26.AST_NODE_TYPES.Identifier) {
+    if (inner === null || node.property.type !== import_utils28.AST_NODE_TYPES.Identifier) {
       return null;
     }
     return `${inner}.${node.property.name}`;
@@ -3344,12 +3407,12 @@ function refKey(node) {
   return null;
 }
 function strLiteral(node) {
-  if (node.type === import_utils26.AST_NODE_TYPES.Literal && typeof node.value === "string") {
+  if (node.type === import_utils28.AST_NODE_TYPES.Literal && typeof node.value === "string") {
     return node.value;
   }
   return null;
 }
-var prefer_string_literal_union_default = import_utils26.ESLintUtils.RuleCreator(
+var prefer_string_literal_union_default = import_utils28.ESLintUtils.RuleCreator(
   (name) => `https://github.com/sarj-ai/linting/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
   name: "prefer-string-literal-union",
@@ -3373,7 +3436,7 @@ var prefer_string_literal_union_default = import_utils26.ESLintUtils.RuleCreator
     }
     let services;
     try {
-      services = import_utils26.ESLintUtils.getParserServices(context);
+      services = import_utils28.ESLintUtils.getParserServices(context);
     } catch {
       services = null;
     }
@@ -3457,7 +3520,7 @@ var prefer_string_literal_union_default = import_utils26.ESLintUtils.RuleCreator
         containersWithUnion.add(container);
         return;
       }
-      if (typeNode?.type !== import_utils26.AST_NODE_TYPES.TSStringKeyword) {
+      if (typeNode?.type !== import_utils28.AST_NODE_TYPES.TSStringKeyword) {
         return;
       }
       const name = keyName(key);
@@ -3545,10 +3608,10 @@ var prefer_string_literal_union_default = import_utils26.ESLintUtils.RuleCreator
       }
     };
     function refKeyText(node) {
-      if (node.type === import_utils26.AST_NODE_TYPES.BinaryExpression) {
+      if (node.type === import_utils28.AST_NODE_TYPES.BinaryExpression) {
         return refKey(node.left) ?? refKey(node.right) ?? "value";
       }
-      if (node.type === import_utils26.AST_NODE_TYPES.SwitchStatement) {
+      if (node.type === import_utils28.AST_NODE_TYPES.SwitchStatement) {
         return refKey(node.discriminant) ?? "value";
       }
       return "value";
@@ -3557,7 +3620,7 @@ var prefer_string_literal_union_default = import_utils26.ESLintUtils.RuleCreator
 });
 
 // src/rules/single-public-export.ts
-var import_utils27 = require("@typescript-eslint/utils");
+var import_utils29 = require("@typescript-eslint/utils");
 var JUNK_DRAWER_STEMS = /* @__PURE__ */ new Set([
   "util",
   "utils",
@@ -3591,12 +3654,12 @@ var kebabCase2 = (name) => {
   }
   return normalized.replace(CAMEL_BOUNDARY_RE, "-").toLowerCase();
 };
-var isFunctionExpression = (node) => node !== null && (node.type === import_utils27.AST_NODE_TYPES.ArrowFunctionExpression || node.type === import_utils27.AST_NODE_TYPES.FunctionExpression);
+var isFunctionExpression = (node) => node !== null && (node.type === import_utils29.AST_NODE_TYPES.ArrowFunctionExpression || node.type === import_utils29.AST_NODE_TYPES.FunctionExpression);
 var functionConstName = (decl) => {
   if (decl.declarations.length !== 1) return null;
   const [declarator] = decl.declarations;
   if (declarator === void 0) return null;
-  if (declarator.id.type !== import_utils27.AST_NODE_TYPES.Identifier) return null;
+  if (declarator.id.type !== import_utils29.AST_NODE_TYPES.Identifier) return null;
   if (!isFunctionExpression(declarator.init)) return null;
   return declarator.id.name;
 };
@@ -3610,20 +3673,20 @@ var summarizeExports = (body) => {
   };
   for (const statement of body) {
     switch (statement.type) {
-      case import_utils27.AST_NODE_TYPES.ExportAllDeclaration:
+      case import_utils29.AST_NODE_TYPES.ExportAllDeclaration:
         hasReExport = true;
         break;
-      case import_utils27.AST_NODE_TYPES.ExportDefaultDeclaration: {
+      case import_utils29.AST_NODE_TYPES.ExportDefaultDeclaration: {
         names += 1;
         const decl = statement.declaration;
-        if (decl.type === import_utils27.AST_NODE_TYPES.FunctionDeclaration && decl.id !== null) {
+        if (decl.type === import_utils29.AST_NODE_TYPES.FunctionDeclaration && decl.id !== null) {
           candidate = { name: decl.id.name, node: statement };
-        } else if (decl.type === import_utils27.AST_NODE_TYPES.ClassDeclaration && decl.id !== null) {
+        } else if (decl.type === import_utils29.AST_NODE_TYPES.ClassDeclaration && decl.id !== null) {
           candidate = { name: decl.id.name, node: statement };
         }
         break;
       }
-      case import_utils27.AST_NODE_TYPES.ExportNamedDeclaration: {
+      case import_utils29.AST_NODE_TYPES.ExportNamedDeclaration: {
         if (statement.source !== null) {
           hasReExport = true;
           break;
@@ -3634,15 +3697,15 @@ var summarizeExports = (body) => {
           break;
         }
         switch (decl.type) {
-          case import_utils27.AST_NODE_TYPES.FunctionDeclaration:
+          case import_utils29.AST_NODE_TYPES.FunctionDeclaration:
             if (decl.id !== null) addCandidate(decl.id.name, statement);
             else names += 1;
             break;
-          case import_utils27.AST_NODE_TYPES.ClassDeclaration:
+          case import_utils29.AST_NODE_TYPES.ClassDeclaration:
             if (decl.id !== null) addCandidate(decl.id.name, statement);
             else names += 1;
             break;
-          case import_utils27.AST_NODE_TYPES.VariableDeclaration: {
+          case import_utils29.AST_NODE_TYPES.VariableDeclaration: {
             const fnName = functionConstName(decl);
             if (fnName !== null && decl.declarations.length === 1) {
               addCandidate(fnName, statement);
@@ -3662,7 +3725,7 @@ var summarizeExports = (body) => {
   }
   return { names, hasReExport, candidate };
 };
-var single_public_export_default = import_utils27.ESLintUtils.RuleCreator(
+var single_public_export_default = import_utils29.ESLintUtils.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
   name: "single-public-export",
@@ -3726,13 +3789,14 @@ var rules = {
   "no-cors-wildcard-with-credentials": no_cors_wildcard_with_credentials_default,
   "no-fat-try-blocks": no_fat_try_blocks_default,
   "no-secret-in-log": no_secret_in_log_default,
+  "no-unsafe-cast": no_unsafe_cast_default,
   "prefer-string-literal-union": prefer_string_literal_union_default,
   "single-public-export": single_public_export_default
 };
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "2.4.1"
+    version: "2.6.0"
   },
   rules,
   configs: {
@@ -3762,6 +3826,7 @@ var plugin = {
         "@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/prefer-string-literal-union": "warn"
       }
@@ -3796,6 +3861,7 @@ var plugin = {
         "@sarj/no-fat-try-blocks": "error",
         "@sarj/no-cors-wildcard-with-credentials": "error",
         "@sarj/no-secret-in-log": "error",
+        "@sarj/no-unsafe-cast": "warn",
         "@sarj/single-public-export": "error",
         // High-volume/stylistic — warn until rollout proves FP rate.
         "@sarj/prefer-string-literal-union": "warn"