@sarj/eslint-plugin 2.5.0 → 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 [{
@@ -94,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 [{

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 [{
@@ -94,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 [{

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);
@@ -3766,7 +3783,7 @@ var rules = {
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "2.5.0"
+    version: "2.6.0"
   },
   rules,
   configs: {