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