@sarj/eslint-plugin 2.4.1 → 2.6.0

package/dist/index.d.cts

@@ -7,7 +7,7 @@ declare const rules: {
     "no-client-side-data-fetching": _typescript_eslint_utils_ts_eslint.RuleModule<"noClientFetch", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
-    "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+    "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble" | "redundantNarration", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
     "no-enum": _typescript_eslint_utils_ts_eslint.RuleModule<"noEnum", readonly [{
@@ -72,6 +72,9 @@ declare const rules: {
     "no-secret-in-log": _typescript_eslint_utils_ts_eslint.RuleModule<"noSecretInLog", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "no-unsafe-cast": _typescript_eslint_utils_ts_eslint.RuleModule<"asAny" | "doubleCast", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
     "prefer-string-literal-union": _typescript_eslint_utils_ts_eslint.RuleModule<"bareChoiceField" | "comparisonCluster", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
@@ -91,7 +94,7 @@ declare const plugin: {
         "no-client-side-data-fetching": _typescript_eslint_utils_ts_eslint.RuleModule<"noClientFetch", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
-        "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble" | "redundantNarration", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
         "no-enum": _typescript_eslint_utils_ts_eslint.RuleModule<"noEnum", readonly [{
@@ -156,6 +159,9 @@ declare const plugin: {
         "no-secret-in-log": _typescript_eslint_utils_ts_eslint.RuleModule<"noSecretInLog", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "no-unsafe-cast": _typescript_eslint_utils_ts_eslint.RuleModule<"asAny" | "doubleCast", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
         "prefer-string-literal-union": _typescript_eslint_utils_ts_eslint.RuleModule<"bareChoiceField" | "comparisonCluster", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
@@ -187,6 +193,7 @@ declare const plugin: {
                 "@sarj/no-fat-try-blocks": string;
                 "@sarj/no-cors-wildcard-with-credentials": string;
                 "@sarj/no-secret-in-log": string;
+                "@sarj/no-unsafe-cast": string;
                 "@sarj/single-public-export": string;
                 "@sarj/prefer-string-literal-union": string;
             };
@@ -217,6 +224,7 @@ declare const plugin: {
                 "@sarj/no-fat-try-blocks": string;
                 "@sarj/no-cors-wildcard-with-credentials": string;
                 "@sarj/no-secret-in-log": string;
+                "@sarj/no-unsafe-cast": string;
                 "@sarj/single-public-export": string;
                 "@sarj/prefer-string-literal-union": string;
             };

package/dist/index.d.ts

@@ -7,7 +7,7 @@ declare const rules: {
     "no-client-side-data-fetching": _typescript_eslint_utils_ts_eslint.RuleModule<"noClientFetch", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
-    "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+    "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble" | "redundantNarration", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
     "no-enum": _typescript_eslint_utils_ts_eslint.RuleModule<"noEnum", readonly [{
@@ -72,6 +72,9 @@ declare const rules: {
     "no-secret-in-log": _typescript_eslint_utils_ts_eslint.RuleModule<"noSecretInLog", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "no-unsafe-cast": _typescript_eslint_utils_ts_eslint.RuleModule<"asAny" | "doubleCast", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
     "prefer-string-literal-union": _typescript_eslint_utils_ts_eslint.RuleModule<"bareChoiceField" | "comparisonCluster", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
@@ -91,7 +94,7 @@ declare const plugin: {
         "no-client-side-data-fetching": _typescript_eslint_utils_ts_eslint.RuleModule<"noClientFetch", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
-        "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble" | "redundantNarration", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
         "no-enum": _typescript_eslint_utils_ts_eslint.RuleModule<"noEnum", readonly [{
@@ -156,6 +159,9 @@ declare const plugin: {
         "no-secret-in-log": _typescript_eslint_utils_ts_eslint.RuleModule<"noSecretInLog", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "no-unsafe-cast": _typescript_eslint_utils_ts_eslint.RuleModule<"asAny" | "doubleCast", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
         "prefer-string-literal-union": _typescript_eslint_utils_ts_eslint.RuleModule<"bareChoiceField" | "comparisonCluster", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
@@ -187,6 +193,7 @@ declare const plugin: {
                 "@sarj/no-fat-try-blocks": string;
                 "@sarj/no-cors-wildcard-with-credentials": string;
                 "@sarj/no-secret-in-log": string;
+                "@sarj/no-unsafe-cast": string;
                 "@sarj/single-public-export": string;
                 "@sarj/prefer-string-literal-union": string;
             };
@@ -217,6 +224,7 @@ declare const plugin: {
                 "@sarj/no-fat-try-blocks": string;
                 "@sarj/no-cors-wildcard-with-credentials": string;
                 "@sarj/no-secret-in-log": string;
+                "@sarj/no-unsafe-cast": string;
                 "@sarj/single-public-export": string;
                 "@sarj/prefer-string-literal-union": string;
             };

package/dist/index.js

@@ -213,6 +213,8 @@ var no_client_side_data_fetching_default = ESLintUtils2.RuleCreator(
 // src/rules/no-comment-cruft.ts
 import { ESLintUtils as ESLintUtils3 } from "@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,}$/;
@@ -251,6 +253,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];
@@ -276,7 +285,8 @@ var no_comment_cruft_default = ESLintUtils3.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: [],
@@ -331,6 +341,13 @@ var no_comment_cruft_default = ESLintUtils3.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);
@@ -3230,10 +3247,56 @@ var no_secret_in_log_default = ESLintUtils23.RuleCreator(
   }
 });
 
+// src/rules/no-unsafe-cast.ts
+import { ESLintUtils as ESLintUtils24 } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES13 } from "@typescript-eslint/utils";
+function isAnyAnnotation(node) {
+  return node.type === AST_NODE_TYPES13.TSAnyKeyword;
+}
+function isConstAssertion(typeAnnotation) {
+  return typeAnnotation.type === AST_NODE_TYPES13.TSTypeReference && typeAnnotation.typeName.type === AST_NODE_TYPES13.Identifier && typeAnnotation.typeName.name === "const";
+}
+var no_unsafe_cast_default = ESLintUtils24.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 === AST_NODE_TYPES13.TSAsExpression || inner.type === AST_NODE_TYPES13.TSTypeAssertion) {
+        context.report({ node, messageId: "doubleCast" });
+      }
+    }
+    return {
+      TSAsExpression: checkAssertion,
+      TSTypeAssertion: checkAssertion
+    };
+  }
+});
+
 // src/rules/prefer-string-literal-union.ts
 import {
-  ESLintUtils as ESLintUtils24,
-  AST_NODE_TYPES as AST_NODE_TYPES13
+  ESLintUtils as ESLintUtils25,
+  AST_NODE_TYPES as AST_NODE_TYPES14
 } from "@typescript-eslint/utils";
 import * as ts from "typescript";
 var CHOICE_TOKENS = /* @__PURE__ */ new Set([
@@ -3277,19 +3340,19 @@ function isChoiceLikeName(name) {
   return CHOICE_TOKENS.has(lastWord(name));
 }
 function keyName(key) {
-  if (key.type === AST_NODE_TYPES13.Identifier) {
+  if (key.type === AST_NODE_TYPES14.Identifier) {
     return key.name;
   }
-  if (key.type === AST_NODE_TYPES13.Literal && typeof key.value === "string") {
+  if (key.type === AST_NODE_TYPES14.Literal && typeof key.value === "string") {
     return key.value;
   }
   return null;
 }
 function isStringLiteralMember(t) {
-  return t.type === AST_NODE_TYPES13.TSLiteralType && t.literal.type === AST_NODE_TYPES13.Literal && typeof t.literal.value === "string";
+  return t.type === AST_NODE_TYPES14.TSLiteralType && t.literal.type === AST_NODE_TYPES14.Literal && typeof t.literal.value === "string";
 }
 function isStringLiteralUnion(node) {
-  if (node?.type !== AST_NODE_TYPES13.TSUnionType) {
+  if (node?.type !== AST_NODE_TYPES14.TSUnionType) {
     return false;
   }
   return node.types.filter(isStringLiteralMember).length >= MIN_CLUSTER_SIZE;
@@ -3318,12 +3381,12 @@ function bindingSourceExpression(decl) {
   return ts.isForOfStatement(node) ? node.expression : node.initializer;
 }
 function refKey(node) {
-  if (node.type === AST_NODE_TYPES13.Identifier) {
+  if (node.type === AST_NODE_TYPES14.Identifier) {
     return node.name;
   }
-  if (node.type === AST_NODE_TYPES13.MemberExpression && !node.computed) {
+  if (node.type === AST_NODE_TYPES14.MemberExpression && !node.computed) {
     const inner = refKey(node.object);
-    if (inner === null || node.property.type !== AST_NODE_TYPES13.Identifier) {
+    if (inner === null || node.property.type !== AST_NODE_TYPES14.Identifier) {
       return null;
     }
     return `${inner}.${node.property.name}`;
@@ -3331,12 +3394,12 @@ function refKey(node) {
   return null;
 }
 function strLiteral(node) {
-  if (node.type === AST_NODE_TYPES13.Literal && typeof node.value === "string") {
+  if (node.type === AST_NODE_TYPES14.Literal && typeof node.value === "string") {
     return node.value;
   }
   return null;
 }
-var prefer_string_literal_union_default = ESLintUtils24.RuleCreator(
+var prefer_string_literal_union_default = ESLintUtils25.RuleCreator(
   (name) => `https://github.com/sarj-ai/linting/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
   name: "prefer-string-literal-union",
@@ -3360,7 +3423,7 @@ var prefer_string_literal_union_default = ESLintUtils24.RuleCreator(
     }
     let services;
     try {
-      services = ESLintUtils24.getParserServices(context);
+      services = ESLintUtils25.getParserServices(context);
     } catch {
       services = null;
     }
@@ -3444,7 +3507,7 @@ var prefer_string_literal_union_default = ESLintUtils24.RuleCreator(
         containersWithUnion.add(container);
         return;
       }
-      if (typeNode?.type !== AST_NODE_TYPES13.TSStringKeyword) {
+      if (typeNode?.type !== AST_NODE_TYPES14.TSStringKeyword) {
         return;
       }
       const name = keyName(key);
@@ -3532,10 +3595,10 @@ var prefer_string_literal_union_default = ESLintUtils24.RuleCreator(
       }
     };
     function refKeyText(node) {
-      if (node.type === AST_NODE_TYPES13.BinaryExpression) {
+      if (node.type === AST_NODE_TYPES14.BinaryExpression) {
         return refKey(node.left) ?? refKey(node.right) ?? "value";
       }
-      if (node.type === AST_NODE_TYPES13.SwitchStatement) {
+      if (node.type === AST_NODE_TYPES14.SwitchStatement) {
         return refKey(node.discriminant) ?? "value";
       }
       return "value";
@@ -3544,7 +3607,7 @@ var prefer_string_literal_union_default = ESLintUtils24.RuleCreator(
 });
 
 // src/rules/single-public-export.ts
-import { ESLintUtils as ESLintUtils25, AST_NODE_TYPES as AST_NODE_TYPES14 } from "@typescript-eslint/utils";
+import { ESLintUtils as ESLintUtils26, AST_NODE_TYPES as AST_NODE_TYPES15 } from "@typescript-eslint/utils";
 var JUNK_DRAWER_STEMS = /* @__PURE__ */ new Set([
   "util",
   "utils",
@@ -3578,12 +3641,12 @@ var kebabCase2 = (name) => {
   }
   return normalized.replace(CAMEL_BOUNDARY_RE, "-").toLowerCase();
 };
-var isFunctionExpression = (node) => node !== null && (node.type === AST_NODE_TYPES14.ArrowFunctionExpression || node.type === AST_NODE_TYPES14.FunctionExpression);
+var isFunctionExpression = (node) => node !== null && (node.type === AST_NODE_TYPES15.ArrowFunctionExpression || node.type === AST_NODE_TYPES15.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 !== AST_NODE_TYPES14.Identifier) return null;
+  if (declarator.id.type !== AST_NODE_TYPES15.Identifier) return null;
   if (!isFunctionExpression(declarator.init)) return null;
   return declarator.id.name;
 };
@@ -3597,20 +3660,20 @@ var summarizeExports = (body) => {
   };
   for (const statement of body) {
     switch (statement.type) {
-      case AST_NODE_TYPES14.ExportAllDeclaration:
+      case AST_NODE_TYPES15.ExportAllDeclaration:
         hasReExport = true;
         break;
-      case AST_NODE_TYPES14.ExportDefaultDeclaration: {
+      case AST_NODE_TYPES15.ExportDefaultDeclaration: {
         names += 1;
         const decl = statement.declaration;
-        if (decl.type === AST_NODE_TYPES14.FunctionDeclaration && decl.id !== null) {
+        if (decl.type === AST_NODE_TYPES15.FunctionDeclaration && decl.id !== null) {
           candidate = { name: decl.id.name, node: statement };
-        } else if (decl.type === AST_NODE_TYPES14.ClassDeclaration && decl.id !== null) {
+        } else if (decl.type === AST_NODE_TYPES15.ClassDeclaration && decl.id !== null) {
           candidate = { name: decl.id.name, node: statement };
         }
         break;
       }
-      case AST_NODE_TYPES14.ExportNamedDeclaration: {
+      case AST_NODE_TYPES15.ExportNamedDeclaration: {
         if (statement.source !== null) {
           hasReExport = true;
           break;
@@ -3621,15 +3684,15 @@ var summarizeExports = (body) => {
           break;
         }
         switch (decl.type) {
-          case AST_NODE_TYPES14.FunctionDeclaration:
+          case AST_NODE_TYPES15.FunctionDeclaration:
             if (decl.id !== null) addCandidate(decl.id.name, statement);
             else names += 1;
             break;
-          case AST_NODE_TYPES14.ClassDeclaration:
+          case AST_NODE_TYPES15.ClassDeclaration:
             if (decl.id !== null) addCandidate(decl.id.name, statement);
             else names += 1;
             break;
-          case AST_NODE_TYPES14.VariableDeclaration: {
+          case AST_NODE_TYPES15.VariableDeclaration: {
             const fnName = functionConstName(decl);
             if (fnName !== null && decl.declarations.length === 1) {
               addCandidate(fnName, statement);
@@ -3649,7 +3712,7 @@ var summarizeExports = (body) => {
   }
   return { names, hasReExport, candidate };
 };
-var single_public_export_default = ESLintUtils25.RuleCreator(
+var single_public_export_default = ESLintUtils26.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
   name: "single-public-export",
@@ -3713,13 +3776,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: {
@@ -3749,6 +3813,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"
       }
@@ -3783,6 +3848,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"