@sarj/eslint-plugin 9.4.0 → 9.6.0

package/dist/index.d.cts

@@ -99,7 +99,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" | "redundantNarration" | "untrackedTodo", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+    "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble" | "commentWall" | "redundantNarration" | "untrackedTodo", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
     "no-conditional-in-test": _typescript_eslint_utils_ts_eslint.RuleModule<"noConditionalInTest", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -397,7 +397,7 @@ type FlatPreset = {
 declare const plugin: {
     meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "9.4.0";
+        readonly version: "9.6.0";
     };
     rules: {
         "enforce-file-structure": _typescript_eslint_utils_ts_eslint.RuleModule<"importsFirst" | "useServerDirective", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -409,7 +409,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" | "redundantNarration" | "untrackedTodo", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble" | "commentWall" | "redundantNarration" | "untrackedTodo", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
         "no-conditional-in-test": _typescript_eslint_utils_ts_eslint.RuleModule<"noConditionalInTest", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {

package/dist/index.d.ts

@@ -99,7 +99,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" | "redundantNarration" | "untrackedTodo", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+    "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble" | "commentWall" | "redundantNarration" | "untrackedTodo", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
     "no-conditional-in-test": _typescript_eslint_utils_ts_eslint.RuleModule<"noConditionalInTest", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -397,7 +397,7 @@ type FlatPreset = {
 declare const plugin: {
     meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "9.4.0";
+        readonly version: "9.6.0";
     };
     rules: {
         "enforce-file-structure": _typescript_eslint_utils_ts_eslint.RuleModule<"importsFirst" | "useServerDirective", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -409,7 +409,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" | "redundantNarration" | "untrackedTodo", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        "no-comment-cruft": _typescript_eslint_utils_ts_eslint.RuleModule<"commentedOutCode" | "sectionBanner" | "fileHeaderPreamble" | "commentWall" | "redundantNarration" | "untrackedTodo", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
         "no-conditional-in-test": _typescript_eslint_utils_ts_eslint.RuleModule<"noConditionalInTest", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {

package/dist/index.js

@@ -492,6 +492,14 @@ function restatesStatementHead(body, statement) {
 
 // src/rules/no-comment-cruft.ts
 var LEADING_PREAMBLE_MIN = 4;
+var WALL_MIN_STATEMENTS = 4;
+var WALL_MIN_COMMENTS = 3;
+var WALL_MIN_COMMENTED_RATIO = 0.6;
+var WALL_MIN_WEAK_RATIO = 0.75;
+var WALL_MAX_WORDS = 18;
+var WALL_MAX_NOVEL_WORDS = 2;
+var WALL_NARRATION_RE = /^(?:first(?:ly)?|second(?:ly)?|third(?:ly)?|then|next|now|finally|lastly|add|append|assign|await|build|calculate|call|check|clear|close|compute|convert|copy|count|create|declare|define|delete|extract|fetch|filter|find|format|generate|get|handle|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|d|ed|ing)?\b/i;
+var WALL_STEP_PREFIX_RE = /^(?:\d+[.)]|(?:phase|step)\s+\d+\s*:)\s*/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(?: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 FOR_NOW_RE = /\bfor now\b/i;
@@ -704,6 +712,63 @@ var STATEMENT_CONTAINERS = /* @__PURE__ */ new Set([
   AST_NODE_TYPES5.TSModuleBlock,
   AST_NODE_TYPES5.TSInterfaceBody
 ]);
+function directStatements(container) {
+  switch (container.type) {
+    case AST_NODE_TYPES5.Program:
+    case AST_NODE_TYPES5.BlockStatement:
+    case AST_NODE_TYPES5.ClassBody:
+    case AST_NODE_TYPES5.StaticBlock:
+    case AST_NODE_TYPES5.TSModuleBlock:
+      return container.body;
+    case AST_NODE_TYPES5.SwitchCase:
+      return container.consequent;
+    case AST_NODE_TYPES5.TSInterfaceBody:
+      return container.body;
+    default:
+      return [];
+  }
+}
+var WALL_STATEMENTS = /* @__PURE__ */ new Set([
+  AST_NODE_TYPES5.ExpressionStatement,
+  AST_NODE_TYPES5.ReturnStatement,
+  AST_NODE_TYPES5.ThrowStatement,
+  AST_NODE_TYPES5.VariableDeclaration,
+  AST_NODE_TYPES5.IfStatement,
+  AST_NODE_TYPES5.ForStatement,
+  AST_NODE_TYPES5.ForOfStatement,
+  AST_NODE_TYPES5.ForInStatement,
+  AST_NODE_TYPES5.WhileStatement,
+  AST_NODE_TYPES5.DoWhileStatement,
+  AST_NODE_TYPES5.SwitchStatement,
+  AST_NODE_TYPES5.TryStatement
+]);
+function statementAttachmentBelow(comment, sourceCode) {
+  const token = sourceCode.getTokenAfter(comment, { includeComments: false });
+  if (token === null || token.loc.start.line !== comment.loc.end.line + 1 || token.loc.start.column !== comment.loc.start.column) {
+    return null;
+  }
+  for (let node = sourceCode.getNodeByRangeIndex(token.range[0]); node?.parent != null; node = node.parent) {
+    if (!STATEMENT_CONTAINERS.has(node.parent.type) || !WALL_STATEMENTS.has(node.type)) {
+      continue;
+    }
+    const siblings = directStatements(node.parent);
+    const index = siblings.indexOf(node);
+    return index < 0 ? null : { container: node.parent, index, statement: sourceCode.getText(node) };
+  }
+  return null;
+}
+function isWeakWalkthroughComment(body, statement) {
+  const normalized = body.replace(WALL_STEP_PREFIX_RE, "");
+  if (normalized.length === 0 || normalized.endsWith("?") || normalized.split(/\s+/).length > WALL_MAX_WORDS || isDirective(normalized) || isProtected(normalized) || !WALL_NARRATION_RE.test(normalized)) {
+    return false;
+  }
+  const words = contentTokens(normalized);
+  const described = words.slice(1);
+  if (described.length === 0) return false;
+  const code = codeTokens(statement);
+  const matched = described.filter((word) => restates([word], code)).length;
+  return matched / described.length >= 0.5 && described.length - matched <= WALL_MAX_NOVEL_WORDS;
+}
 var TYPE_MEMBER_CONTAINERS = /* @__PURE__ */ new Set([
   AST_NODE_TYPES5.TSInterfaceBody,
   AST_NODE_TYPES5.TSTypeLiteral
@@ -759,6 +824,7 @@ var no_comment_cruft_default = createRule({
       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.",
+      commentWall: "Statement comment wall ({{count}} narrated steps) \u2014 delete the walkthrough and name the operations in code; keep only constraints or rationale.",
       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."
     }
@@ -778,6 +844,48 @@ var no_comment_cruft_default = createRule({
     function isJsDoc(comment) {
       return comment.type === "Block" && /^\*/.test(comment.value);
     }
+    function findCommentWalls(comments) {
+      const attached = /* @__PURE__ */ new Map();
+      for (const comment of comments) {
+        if (comment.type !== "Line" || !isStandalone(comment)) continue;
+        const attachment = statementAttachmentBelow(comment, sourceCode);
+        if (attachment === null) continue;
+        const body = stripCommentMarker(comment.value);
+        const entries = attached.get(attachment.container) ?? [];
+        entries.push({
+          comment,
+          index: attachment.index,
+          weak: isWeakWalkthroughComment(body, attachment.statement)
+        });
+        attached.set(attachment.container, entries);
+      }
+      const walls = [];
+      for (const entries of attached.values()) {
+        const sorted = entries.toSorted((left, right) => left.index - right.index);
+        const clusters = [];
+        for (const entry of sorted) {
+          const cluster = clusters.at(-1);
+          if (cluster !== void 0 && entry.index <= (cluster.at(-1)?.index ?? 0) + 2) {
+            cluster.push(entry);
+          } else {
+            clusters.push([entry]);
+          }
+        }
+        for (const cluster of clusters) {
+          const firstIndex = cluster[0]?.index;
+          const lastIndex = cluster.at(-1)?.index;
+          if (firstIndex === void 0 || lastIndex === void 0) continue;
+          const span = lastIndex - firstIndex + 1;
+          const weak = cluster.filter((entry) => entry.weak).map((entry) => entry.comment);
+          if (span < WALL_MIN_STATEMENTS || weak.length < WALL_MIN_COMMENTS || cluster.length / span < WALL_MIN_COMMENTED_RATIO || weak.length / cluster.length < WALL_MIN_WEAK_RATIO) {
+            continue;
+          }
+          const leader = weak[0];
+          if (leader !== void 0) walls.push({ leader, members: new Set(weak) });
+        }
+      }
+      return walls;
+    }
     function isSectionJsDoc(comment) {
       const texts = comment.value.split("\n").map(stripCommentMarker).filter((line) => line.length > 0 && !isDirective(line));
       return texts.length > 0 && texts.every(
@@ -810,6 +918,9 @@ var no_comment_cruft_default = createRule({
     return {
       Program() {
         const comments = sourceCode.getAllComments();
+        const walls = findCommentWalls(comments);
+        const wallByLeader = new Map(walls.map((wall) => [wall.leader, wall]));
+        const wallMembers = new Set(walls.flatMap((wall) => [...wall.members]));
         const firstCodeLine = sourceCode.ast.tokens[0]?.loc.start.line ?? Number.MAX_SAFE_INTEGER;
         const enumerated = comments.filter(
           (c) => c.type === "Line" && ENUMERATION_RE.test(stripCommentMarker(c.value))
@@ -817,6 +928,16 @@ var no_comment_cruft_default = createRule({
         for (let i = 0; i < comments.length; i++) {
           const comment = comments[i];
           if (comment === void 0) continue;
+          const wall = wallByLeader.get(comment);
+          if (wall !== void 0) {
+            context.report({
+              node: comment,
+              messageId: "commentWall",
+              data: { count: String(wall.members.size) }
+            });
+            continue;
+          }
+          if (wallMembers.has(comment)) continue;
           if (isJsDoc(comment)) {
             if (isStandalone(comment) && isSectionJsDoc(comment)) {
               context.report({ node: comment, messageId: "sectionBanner" });
@@ -3327,6 +3448,9 @@ var EMPHASIS_RE = /\*\w[^*]*\*|`[^`]+`/;
 var NEGATION_WORD_RE = /\b(?:no|not|never|neither|nor|without|none|non)\b/i;
 var ACTION_STMT_RE = /[\w.$\])]\s*\(|^\s*(?:return|throw|await|yield)\b/;
 var NON_ASCII_LETTER_RE = /[^\p{ASCII}\p{N}\p{P}\p{Z}]/u;
+var WALL_NARRATION_RE2 = /^(?:(?:\d+[.)]|(?:phase|step)\s+\d+\s*:?)\s*)?(?:add|build|call|check|compute|copy|count|create|fetch|filter|find|get|handle|load|map|merge|parse|process|read|remove|return|save|send|set|sort|store|update|validate|write)(?:s|es|d|ed|ing)?\b/i;
+var WALL_CLUSTER_MAX_LINE_GAP = 8;
+var WALL_CLUSTER_MIN_COMMENTS = 3;
 function areAdjacentLineComments2(a, b) {
   return a !== void 0 && b !== void 0 && a.type === "Line" && b.type === "Line" && b.loc.start.line === a.loc.end.line + 1;
 }
@@ -3373,9 +3497,29 @@ var no_restated_comment_default = createRule({
     return {
       Program() {
         const comments = sourceCode.getAllComments();
+        const wallMembers = /* @__PURE__ */ new Set();
+        let cluster = [];
+        for (const candidate of comments) {
+          const body = candidate.value.replace(/^\/*/, "").trim();
+          if (candidate.type !== "Line" || !isStandalone(candidate) || isProtected(body) || !WALL_NARRATION_RE2.test(body)) {
+            continue;
+          }
+          const previous = cluster.at(-1);
+          if (previous !== void 0 && candidate.loc.start.line - previous.loc.start.line > WALL_CLUSTER_MAX_LINE_GAP) {
+            if (cluster.length >= WALL_CLUSTER_MIN_COMMENTS) {
+              for (const member of cluster) wallMembers.add(member);
+            }
+            cluster = [];
+          }
+          cluster.push(candidate);
+        }
+        if (cluster.length >= WALL_CLUSTER_MIN_COMMENTS) {
+          for (const member of cluster) wallMembers.add(member);
+        }
         for (let i = 0; i < comments.length; i++) {
           const comment = comments[i];
           if (comment === void 0 || comment.type !== "Line") continue;
+          if (wallMembers.has(comment)) continue;
           if (!isStandalone(comment)) continue;
           if (areAdjacentLineComments2(comments[i - 1], comment) || areAdjacentLineComments2(comment, comments[i + 1])) {
             continue;
@@ -9512,7 +9656,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "9.4.0"
+  version: "9.6.0"
 };
 var recommendedRules = {
   "@sarj/enforce-file-structure": "warn",