@sarj/eslint-plugin 15.17.5 → 15.17.6

package/dist/index.cjs

@@ -1448,6 +1448,10 @@ function normalizeToken(word) {
   return lower.length > TOKEN_PLURAL_MIN && lower.endsWith("s") && !lower.endsWith("ss") ? lower.slice(0, -1) : lower;
 }
 function restatableStatementBelow(comment, sourceCode) {
+  const node = restatableStatementNodeBelow(comment, sourceCode);
+  return node === null ? null : sourceCode.getText(node);
+}
+function restatableStatementNodeBelow(comment, sourceCode) {
   const token = sourceCode.getTokenAfter(comment, { includeComments: false });
   if (token === null || token.loc.start.line !== comment.loc.end.line + 1) return null;
   for (let node = sourceCode.getNodeByRangeIndex(token.range[0]); node != null && node.type !== import_utils7.AST_NODE_TYPES.Program; node = node.parent) {
@@ -1458,7 +1462,7 @@ function restatableStatementBelow(comment, sourceCode) {
     if (node.type === import_utils7.AST_NODE_TYPES.VariableDeclaration && isTrivialInitializer(node)) {
       return null;
     }
-    return sourceCode.getText(node);
+    return node;
   }
   return null;
 }
@@ -6716,25 +6720,31 @@ var MODALITY_RE = /\b(?:can|could|should|shall|may|might|must|will|would|cannot)
 var LEAD_IN_RE = /:$/;
 var EMPHASIS_RE = /\*\w[^*]*\*|`[^`]+`/;
 var NEGATION_WORD_RE = /\b(?:no|not|never|neither|nor|without|none|non)\b/i;
+var SEMANTIC_RELATION_RE = /\b(?:only|if|unless|when|while|except|each|every|any|all|before|after|until|since|again|once|twice|already|still|from|to|into|onto|back|versus|rather|instead)\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;
 var NO_RESTATED_COMMENT_DOCUMENTATION = {
-  summary: "Flag a single-line comment whose every word already appears on the statement below it.",
+  summary: "Flag short standalone comments that repeat the adjacent statement's identifiers.",
   rationale: "A comment that only repeats code adds no context and can become stale independently.",
-  remediation: "Delete the comment or replace it with the reason, constraint, or consequence absent from the code.",
+  remediation: "Remove a genuine restatement; retain conditions, constraints, rationale, and information absent from the statement.",
   category: "maintainability",
   autofix: "suggestion",
-  limitations: ["Directives, protected references, questions, multi-line prose, comments with novel content, and generated files are excluded."],
+  limitations: [
+    "Only standalone line comments of two to eight words with at least two content tokens directly above a supported single-line statement are inspected; one-word headings and sentence-ending punctuation are excluded.",
+    "Evidence comes from that statement's identifier tokens, not strings, template text, comments, or neighboring statements. Stopwords and inflection folding are heuristic, not proof of semantic equivalence.",
+    "Directives, protected references, conditions, restrictions, ordering, repetition, direction, questions, prose paragraphs, sibling-group labels, novel content, and generated files are excluded. Deletion is an optional suggestion, never an automatic fix.",
+    "The conservative sibling-group exemption includes enclosing sibling groups and declaration/type-query pairs; it can miss genuine restatements inside those groups."
+  ],
   examples: [
-    { id: "reason-comment", title: "Keep the reason the code cannot express", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// Serialize because the cache key is stable across deploys.\nconst key = serialize(input);" }], focusPath: "src/cache.ts", expectedCount: 0, public: true },
+    { id: "reason-comment", title: "Keep a condition the statement does not establish", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// Serialize key only after validation.\nconst key = serialize(input);" }], focusPath: "src/cache.ts", expectedCount: 0, public: true },
     { id: "restated-comment", title: "Remove a comment that repeats the statement", outcome: "match", files: [{ path: "src/cache.ts", source: "// Serialize key\nconst key = serialize(input);" }], focusPath: "src/cache.ts", expectedCount: 1, public: true }
   ]
 };
-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;
+function areAdjacentLineComments2(a, b, isStandalone) {
+  return a !== void 0 && b !== void 0 && a.type === "Line" && b.type === "Line" && isStandalone(a) && isStandalone(b) && b.loc.start.line === a.loc.end.line + 1;
 }
 function headsSiblingRun(node) {
   const parent = node.parent;
@@ -6752,12 +6762,12 @@ var no_restated_comment_default = createRule({
     type: "suggestion",
     hasSuggestions: true,
     docs: {
-      description: "Flag a single-line comment whose every word already appears on the statement below it."
+      description: NO_RESTATED_COMMENT_DOCUMENTATION.summary
     },
     schema: [],
     messages: {
       deleteComment: "Delete the redundant comment.",
-      restatesLineBelow: "Comment restates the statement below it \u2014 delete it, or replace it with the *why*; the code already carries the *what*."
+      restatesLineBelow: "Comment repeats the adjacent statement's identifiers \u2014 consider removing it; retain any condition, constraint, or rationale absent from the code."
     }
   },
   defaultOptions: [],
@@ -6766,19 +6776,30 @@ var no_restated_comment_default = createRule({
       return {};
     }
     const sourceCode = context.sourceCode;
-    const lines = sourceCode.lines;
     function isStandalone(comment) {
       const before = sourceCode.getTokenBefore(comment, { includeComments: false });
       return !before || before.loc.end.line < comment.loc.start.line;
     }
-    function labelsASiblingRun(comment) {
-      const token = sourceCode.getTokenAfter(comment, { includeComments: false });
-      if (token === null) return false;
-      for (let node = sourceCode.getNodeByRangeIndex(token.range[0]); node != null && node.type !== import_utils38.AST_NODE_TYPES.Program; node = node.parent) {
+    function labelsASiblingRun(statement) {
+      for (let node = statement; node !== void 0 && node.type !== import_utils38.AST_NODE_TYPES.Program; node = node.parent) {
         if (headsSiblingRun(node)) return true;
       }
       return false;
     }
+    function headsValueTypeGroup(statement) {
+      if (statement.type !== import_utils38.AST_NODE_TYPES.VariableDeclaration) return false;
+      const parent = statement.parent;
+      if (!("body" in parent) || !Array.isArray(parent.body)) return false;
+      const body2 = parent.body;
+      const next = body2[body2.indexOf(statement) + 1];
+      if (next?.type !== import_utils38.AST_NODE_TYPES.TSTypeAliasDeclaration) return false;
+      const names = new Set(statement.declarations.flatMap(({ id }) => id.type === import_utils38.AST_NODE_TYPES.Identifier ? [id.name] : []));
+      const tokens = sourceCode.getTokens(next);
+      return tokens.some((token, index) => {
+        const nextToken = tokens[index + 1];
+        return token.value === "typeof" && nextToken?.type === import_utils38.AST_TOKEN_TYPES.Identifier && names.has(nextToken.value);
+      });
+    }
     return {
       Program() {
         const comments = sourceCode.getAllComments();
@@ -6806,7 +6827,7 @@ var no_restated_comment_default = createRule({
           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])) {
+          if (areAdjacentLineComments2(comments[i - 1], comment, isStandalone) || areAdjacentLineComments2(comment, comments[i + 1], isStandalone)) {
             continue;
           }
           const body2 = comment.value.replace(/^\/*/, "").trim();
@@ -6814,17 +6835,19 @@ var no_restated_comment_default = createRule({
           if (DIRECTIVE_RE3.test(body2) || CODEY_RE.test(body2) || BANNERISH_RE.test(body2)) continue;
           if (NON_ASCII_LETTER_RE.test(body2) || isProtected(body2)) continue;
           if (MODALITY_RE.test(body2) || LEAD_IN_RE.test(body2) || EMPHASIS_RE.test(body2)) continue;
-          if (NEGATION_WORD_RE.test(body2)) continue;
-          if (body2.split(/\s+/).length > MAX_WORDS) continue;
+          if (NEGATION_WORD_RE.test(body2) || SEMANTIC_RELATION_RE.test(body2)) continue;
+          const wordCount2 = body2.split(/\s+/).length;
+          if (wordCount2 < 2 || wordCount2 > MAX_WORDS || /[.!?]$/.test(body2)) continue;
           const tokens = contentTokens(body2);
           if (tokens.length < MIN_CONTENT_TOKENS) continue;
-          const statement = restatableStatementBelow(comment, sourceCode);
-          if (statement === null) continue;
+          const statementNode = restatableStatementNodeBelow(comment, sourceCode);
+          if (statementNode === null) continue;
+          const statement = sourceCode.getText(statementNode);
           if (restatesStatementHead(body2, statement)) continue;
-          const line = lines[comment.loc.start.line] ?? "";
-          if (!ACTION_STMT_RE.test(line)) continue;
-          if (labelsASiblingRun(comment)) continue;
-          if (restates(tokens, codeTokens(line))) {
+          if (!ACTION_STMT_RE.test(statement)) continue;
+          if (labelsASiblingRun(statementNode) || headsValueTypeGroup(statementNode)) continue;
+          const identifiers = sourceCode.getTokens(statementNode).filter((token) => token.type === import_utils38.AST_TOKEN_TYPES.Identifier).map((token) => token.value).join(" ");
+          if (restates(tokens, codeTokens(identifiers))) {
             const removal = wholeLineRemovalRange(sourceCode.text, comment);
             context.report({
               node: comment,
@@ -19729,7 +19752,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.17.5"
+  version: "15.17.6"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {
@@ -19739,6 +19762,7 @@ var LIBRARY_IMPORT_POLICY = ["error", {
 var ADVISORY_RULES = [
   "@sarj/excessive-commentary",
   "@sarj/no-bespoke-api-case-conversion",
+  "@sarj/no-restated-comment",
   "@sarj/prefer-millisecond-control-duration-schema",
   "@sarj/prefer-module-level-refined-schema",
   "@sarj/prefer-multi-value-zod-literal",
@@ -19786,7 +19810,7 @@ var RECOMMENDED_RULES = {
   "@sarj/no-production-browser-source-maps": "error",
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
-  "@sarj/no-restated-comment": "error",
+  "@sarj/no-restated-comment": "warn",
   "@sarj/no-restated-jsdoc": "error",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",
@@ -19882,7 +19906,7 @@ var STRICT_RULES = {
   "@sarj/no-raw-fetch-outside-clients": "error",
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
-  "@sarj/no-restated-comment": "error",
+  "@sarj/no-restated-comment": "warn",
   "@sarj/no-restated-jsdoc": "error",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",

package/dist/index.d.cts

@@ -320,7 +320,7 @@ declare const RULES: {
 /** @deprecated All repositories use one policy; retained for import compatibility. */
 declare const APPLICATION_ONLY_RULES: readonly [];
 /** Rules staged as non-blocking warnings while corpus adoption evidence accumulates. */
-declare const ADVISORY_RULES: readonly ["@sarj/excessive-commentary", "@sarj/no-bespoke-api-case-conversion", "@sarj/prefer-millisecond-control-duration-schema", "@sarj/prefer-module-level-refined-schema", "@sarj/prefer-multi-value-zod-literal", "@sarj/prefer-named-callback-domain", "@sarj/prefer-named-complex-return-type", "@sarj/prefer-node-crypto-hash", "@sarj/prefer-node-fs-promises", "@sarj/prefer-nullish-filter-predicate", "@sarj/prefer-shared-zod-enum", "@sarj/prefer-switch-for-repeated-equality", "@sarj/require-interface-for-exported-class", "@sarj/require-sql-access-class", "@sarj/sole-export-matches-filename"];
+declare const ADVISORY_RULES: readonly ["@sarj/excessive-commentary", "@sarj/no-bespoke-api-case-conversion", "@sarj/no-restated-comment", "@sarj/prefer-millisecond-control-duration-schema", "@sarj/prefer-module-level-refined-schema", "@sarj/prefer-multi-value-zod-literal", "@sarj/prefer-named-callback-domain", "@sarj/prefer-named-complex-return-type", "@sarj/prefer-node-crypto-hash", "@sarj/prefer-node-fs-promises", "@sarj/prefer-nullish-filter-predicate", "@sarj/prefer-shared-zod-enum", "@sarj/prefer-switch-for-repeated-equality", "@sarj/require-interface-for-exported-class", "@sarj/require-sql-access-class", "@sarj/sole-export-matches-filename"];
 declare const RECOMMENDED_RULES: {
     readonly "no-restricted-imports": readonly ["error", {
         readonly paths: {
@@ -537,7 +537,7 @@ declare const RECOMMENDED_RULES: {
     readonly "@sarj/no-production-browser-source-maps": "error";
     readonly "@sarj/no-repeated-string-literal": "error";
     readonly "@sarj/no-router-refresh-polling": "error";
-    readonly "@sarj/no-restated-comment": "error";
+    readonly "@sarj/no-restated-comment": "warn";
     readonly "@sarj/no-restated-jsdoc": "error";
     readonly "@sarj/no-secret-in-log": "error";
     readonly "@sarj/no-server-env-in-client-component": "error";
@@ -820,7 +820,7 @@ declare const STRICT_RULES: {
     readonly "@sarj/no-raw-fetch-outside-clients": "error";
     readonly "@sarj/no-repeated-string-literal": "error";
     readonly "@sarj/no-router-refresh-polling": "error";
-    readonly "@sarj/no-restated-comment": "error";
+    readonly "@sarj/no-restated-comment": "warn";
     readonly "@sarj/no-restated-jsdoc": "error";
     readonly "@sarj/no-secret-in-log": "error";
     readonly "@sarj/no-server-env-in-client-component": "error";
@@ -893,7 +893,7 @@ type FlatPreset = {
 declare const PLUGIN: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.17.5";
+        readonly version: "15.17.6";
     };
     readonly rules: {
         readonly "excessive-commentary": DocumentedRule<readonly [], "excessive">;

package/dist/index.d.ts

@@ -320,7 +320,7 @@ declare const RULES: {
 /** @deprecated All repositories use one policy; retained for import compatibility. */
 declare const APPLICATION_ONLY_RULES: readonly [];
 /** Rules staged as non-blocking warnings while corpus adoption evidence accumulates. */
-declare const ADVISORY_RULES: readonly ["@sarj/excessive-commentary", "@sarj/no-bespoke-api-case-conversion", "@sarj/prefer-millisecond-control-duration-schema", "@sarj/prefer-module-level-refined-schema", "@sarj/prefer-multi-value-zod-literal", "@sarj/prefer-named-callback-domain", "@sarj/prefer-named-complex-return-type", "@sarj/prefer-node-crypto-hash", "@sarj/prefer-node-fs-promises", "@sarj/prefer-nullish-filter-predicate", "@sarj/prefer-shared-zod-enum", "@sarj/prefer-switch-for-repeated-equality", "@sarj/require-interface-for-exported-class", "@sarj/require-sql-access-class", "@sarj/sole-export-matches-filename"];
+declare const ADVISORY_RULES: readonly ["@sarj/excessive-commentary", "@sarj/no-bespoke-api-case-conversion", "@sarj/no-restated-comment", "@sarj/prefer-millisecond-control-duration-schema", "@sarj/prefer-module-level-refined-schema", "@sarj/prefer-multi-value-zod-literal", "@sarj/prefer-named-callback-domain", "@sarj/prefer-named-complex-return-type", "@sarj/prefer-node-crypto-hash", "@sarj/prefer-node-fs-promises", "@sarj/prefer-nullish-filter-predicate", "@sarj/prefer-shared-zod-enum", "@sarj/prefer-switch-for-repeated-equality", "@sarj/require-interface-for-exported-class", "@sarj/require-sql-access-class", "@sarj/sole-export-matches-filename"];
 declare const RECOMMENDED_RULES: {
     readonly "no-restricted-imports": readonly ["error", {
         readonly paths: {
@@ -537,7 +537,7 @@ declare const RECOMMENDED_RULES: {
     readonly "@sarj/no-production-browser-source-maps": "error";
     readonly "@sarj/no-repeated-string-literal": "error";
     readonly "@sarj/no-router-refresh-polling": "error";
-    readonly "@sarj/no-restated-comment": "error";
+    readonly "@sarj/no-restated-comment": "warn";
     readonly "@sarj/no-restated-jsdoc": "error";
     readonly "@sarj/no-secret-in-log": "error";
     readonly "@sarj/no-server-env-in-client-component": "error";
@@ -820,7 +820,7 @@ declare const STRICT_RULES: {
     readonly "@sarj/no-raw-fetch-outside-clients": "error";
     readonly "@sarj/no-repeated-string-literal": "error";
     readonly "@sarj/no-router-refresh-polling": "error";
-    readonly "@sarj/no-restated-comment": "error";
+    readonly "@sarj/no-restated-comment": "warn";
     readonly "@sarj/no-restated-jsdoc": "error";
     readonly "@sarj/no-secret-in-log": "error";
     readonly "@sarj/no-server-env-in-client-component": "error";
@@ -893,7 +893,7 @@ type FlatPreset = {
 declare const PLUGIN: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.17.5";
+        readonly version: "15.17.6";
     };
     readonly rules: {
         readonly "excessive-commentary": DocumentedRule<readonly [], "excessive">;

package/dist/index.js

@@ -1397,6 +1397,10 @@ function normalizeToken(word) {
   return lower.length > TOKEN_PLURAL_MIN && lower.endsWith("s") && !lower.endsWith("ss") ? lower.slice(0, -1) : lower;
 }
 function restatableStatementBelow(comment, sourceCode) {
+  const node = restatableStatementNodeBelow(comment, sourceCode);
+  return node === null ? null : sourceCode.getText(node);
+}
+function restatableStatementNodeBelow(comment, sourceCode) {
   const token = sourceCode.getTokenAfter(comment, { includeComments: false });
   if (token === null || token.loc.start.line !== comment.loc.end.line + 1) return null;
   for (let node = sourceCode.getNodeByRangeIndex(token.range[0]); node != null && node.type !== AST_NODE_TYPES6.Program; node = node.parent) {
@@ -1407,7 +1411,7 @@ function restatableStatementBelow(comment, sourceCode) {
     if (node.type === AST_NODE_TYPES6.VariableDeclaration && isTrivialInitializer(node)) {
       return null;
     }
-    return sourceCode.getText(node);
+    return node;
   }
   return null;
 }
@@ -6633,7 +6637,7 @@ var no_repeated_string_literal_default = createRule({
 });
 
 // src/rules/no-restated-comment.ts
-import { AST_NODE_TYPES as AST_NODE_TYPES28 } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES28, AST_TOKEN_TYPES } from "@typescript-eslint/utils";
 
 // src/rules/_comment-edits.ts
 import "@typescript-eslint/utils";
@@ -6675,25 +6679,31 @@ var MODALITY_RE = /\b(?:can|could|should|shall|may|might|must|will|would|cannot)
 var LEAD_IN_RE = /:$/;
 var EMPHASIS_RE = /\*\w[^*]*\*|`[^`]+`/;
 var NEGATION_WORD_RE = /\b(?:no|not|never|neither|nor|without|none|non)\b/i;
+var SEMANTIC_RELATION_RE = /\b(?:only|if|unless|when|while|except|each|every|any|all|before|after|until|since|again|once|twice|already|still|from|to|into|onto|back|versus|rather|instead)\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;
 var NO_RESTATED_COMMENT_DOCUMENTATION = {
-  summary: "Flag a single-line comment whose every word already appears on the statement below it.",
+  summary: "Flag short standalone comments that repeat the adjacent statement's identifiers.",
   rationale: "A comment that only repeats code adds no context and can become stale independently.",
-  remediation: "Delete the comment or replace it with the reason, constraint, or consequence absent from the code.",
+  remediation: "Remove a genuine restatement; retain conditions, constraints, rationale, and information absent from the statement.",
   category: "maintainability",
   autofix: "suggestion",
-  limitations: ["Directives, protected references, questions, multi-line prose, comments with novel content, and generated files are excluded."],
+  limitations: [
+    "Only standalone line comments of two to eight words with at least two content tokens directly above a supported single-line statement are inspected; one-word headings and sentence-ending punctuation are excluded.",
+    "Evidence comes from that statement's identifier tokens, not strings, template text, comments, or neighboring statements. Stopwords and inflection folding are heuristic, not proof of semantic equivalence.",
+    "Directives, protected references, conditions, restrictions, ordering, repetition, direction, questions, prose paragraphs, sibling-group labels, novel content, and generated files are excluded. Deletion is an optional suggestion, never an automatic fix.",
+    "The conservative sibling-group exemption includes enclosing sibling groups and declaration/type-query pairs; it can miss genuine restatements inside those groups."
+  ],
   examples: [
-    { id: "reason-comment", title: "Keep the reason the code cannot express", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// Serialize because the cache key is stable across deploys.\nconst key = serialize(input);" }], focusPath: "src/cache.ts", expectedCount: 0, public: true },
+    { id: "reason-comment", title: "Keep a condition the statement does not establish", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// Serialize key only after validation.\nconst key = serialize(input);" }], focusPath: "src/cache.ts", expectedCount: 0, public: true },
     { id: "restated-comment", title: "Remove a comment that repeats the statement", outcome: "match", files: [{ path: "src/cache.ts", source: "// Serialize key\nconst key = serialize(input);" }], focusPath: "src/cache.ts", expectedCount: 1, public: true }
   ]
 };
-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;
+function areAdjacentLineComments2(a, b, isStandalone) {
+  return a !== void 0 && b !== void 0 && a.type === "Line" && b.type === "Line" && isStandalone(a) && isStandalone(b) && b.loc.start.line === a.loc.end.line + 1;
 }
 function headsSiblingRun(node) {
   const parent = node.parent;
@@ -6711,12 +6721,12 @@ var no_restated_comment_default = createRule({
     type: "suggestion",
     hasSuggestions: true,
     docs: {
-      description: "Flag a single-line comment whose every word already appears on the statement below it."
+      description: NO_RESTATED_COMMENT_DOCUMENTATION.summary
     },
     schema: [],
     messages: {
       deleteComment: "Delete the redundant comment.",
-      restatesLineBelow: "Comment restates the statement below it \u2014 delete it, or replace it with the *why*; the code already carries the *what*."
+      restatesLineBelow: "Comment repeats the adjacent statement's identifiers \u2014 consider removing it; retain any condition, constraint, or rationale absent from the code."
     }
   },
   defaultOptions: [],
@@ -6725,19 +6735,30 @@ var no_restated_comment_default = createRule({
       return {};
     }
     const sourceCode = context.sourceCode;
-    const lines = sourceCode.lines;
     function isStandalone(comment) {
       const before = sourceCode.getTokenBefore(comment, { includeComments: false });
       return !before || before.loc.end.line < comment.loc.start.line;
     }
-    function labelsASiblingRun(comment) {
-      const token = sourceCode.getTokenAfter(comment, { includeComments: false });
-      if (token === null) return false;
-      for (let node = sourceCode.getNodeByRangeIndex(token.range[0]); node != null && node.type !== AST_NODE_TYPES28.Program; node = node.parent) {
+    function labelsASiblingRun(statement) {
+      for (let node = statement; node !== void 0 && node.type !== AST_NODE_TYPES28.Program; node = node.parent) {
         if (headsSiblingRun(node)) return true;
       }
       return false;
     }
+    function headsValueTypeGroup(statement) {
+      if (statement.type !== AST_NODE_TYPES28.VariableDeclaration) return false;
+      const parent = statement.parent;
+      if (!("body" in parent) || !Array.isArray(parent.body)) return false;
+      const body2 = parent.body;
+      const next = body2[body2.indexOf(statement) + 1];
+      if (next?.type !== AST_NODE_TYPES28.TSTypeAliasDeclaration) return false;
+      const names = new Set(statement.declarations.flatMap(({ id }) => id.type === AST_NODE_TYPES28.Identifier ? [id.name] : []));
+      const tokens = sourceCode.getTokens(next);
+      return tokens.some((token, index) => {
+        const nextToken = tokens[index + 1];
+        return token.value === "typeof" && nextToken?.type === AST_TOKEN_TYPES.Identifier && names.has(nextToken.value);
+      });
+    }
     return {
       Program() {
         const comments = sourceCode.getAllComments();
@@ -6765,7 +6786,7 @@ var no_restated_comment_default = createRule({
           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])) {
+          if (areAdjacentLineComments2(comments[i - 1], comment, isStandalone) || areAdjacentLineComments2(comment, comments[i + 1], isStandalone)) {
             continue;
           }
           const body2 = comment.value.replace(/^\/*/, "").trim();
@@ -6773,17 +6794,19 @@ var no_restated_comment_default = createRule({
           if (DIRECTIVE_RE3.test(body2) || CODEY_RE.test(body2) || BANNERISH_RE.test(body2)) continue;
           if (NON_ASCII_LETTER_RE.test(body2) || isProtected(body2)) continue;
           if (MODALITY_RE.test(body2) || LEAD_IN_RE.test(body2) || EMPHASIS_RE.test(body2)) continue;
-          if (NEGATION_WORD_RE.test(body2)) continue;
-          if (body2.split(/\s+/).length > MAX_WORDS) continue;
+          if (NEGATION_WORD_RE.test(body2) || SEMANTIC_RELATION_RE.test(body2)) continue;
+          const wordCount2 = body2.split(/\s+/).length;
+          if (wordCount2 < 2 || wordCount2 > MAX_WORDS || /[.!?]$/.test(body2)) continue;
           const tokens = contentTokens(body2);
           if (tokens.length < MIN_CONTENT_TOKENS) continue;
-          const statement = restatableStatementBelow(comment, sourceCode);
-          if (statement === null) continue;
+          const statementNode = restatableStatementNodeBelow(comment, sourceCode);
+          if (statementNode === null) continue;
+          const statement = sourceCode.getText(statementNode);
           if (restatesStatementHead(body2, statement)) continue;
-          const line = lines[comment.loc.start.line] ?? "";
-          if (!ACTION_STMT_RE.test(line)) continue;
-          if (labelsASiblingRun(comment)) continue;
-          if (restates(tokens, codeTokens(line))) {
+          if (!ACTION_STMT_RE.test(statement)) continue;
+          if (labelsASiblingRun(statementNode) || headsValueTypeGroup(statementNode)) continue;
+          const identifiers = sourceCode.getTokens(statementNode).filter((token) => token.type === AST_TOKEN_TYPES.Identifier).map((token) => token.value).join(" ");
+          if (restates(tokens, codeTokens(identifiers))) {
             const removal = wholeLineRemovalRange(sourceCode.text, comment);
             context.report({
               node: comment,
@@ -9078,10 +9101,10 @@ var no_trailing_value_narration_default = createRule({
 });
 
 // src/rules/no-declaration-comment-wall.ts
-import { AST_NODE_TYPES as AST_NODE_TYPES36, AST_TOKEN_TYPES as AST_TOKEN_TYPES2 } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES36, AST_TOKEN_TYPES as AST_TOKEN_TYPES3 } from "@typescript-eslint/utils";
 
 // src/rules/_comment-wall.ts
-import { AST_NODE_TYPES as AST_NODE_TYPES35, AST_TOKEN_TYPES } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES35, AST_TOKEN_TYPES as AST_TOKEN_TYPES2 } from "@typescript-eslint/utils";
 var WALL_DEFAULTS = {
   // Below three rows "a wall" is not a fair description of what the reader sees.
   minCommentedMembers: 3,
@@ -9147,7 +9170,7 @@ function commentBody(comment) {
   return comment.value.replace(/^\*+/, "").replace(/^[ \t]*\*[ \t]?/gm, "").trim();
 }
 function hasJsDocTag(comment) {
-  return comment.type === AST_TOKEN_TYPES.Block && comment.value.startsWith("*") && /(?:^|\s)@[A-Za-z][\w-]*\b/u.test(commentBody(comment));
+  return comment.type === AST_TOKEN_TYPES2.Block && comment.value.startsWith("*") && /(?:^|\s)@[A-Za-z][\w-]*\b/u.test(commentBody(comment));
 }
 function carriesValue(body2) {
   return isProtected(body2) || VALUE_TAG_RE2.test(body2) || DEFAULT_RE.test(body2) || DIGIT_RE.test(body2) || UNIT_WORD_RE.test(body2) || EXAMPLE_RE.test(body2) || BANNER_RE.test(body2) || NON_ASCII_LETTER_RE2.test(body2);
@@ -9283,7 +9306,7 @@ var no_declaration_comment_wall_default = createRule({
         const before = sourceCode.getTokenBefore(lead, { includeComments: false });
         if (before === null || before.loc.end.line < lead.loc.start.line) {
           const previousLine = endingOn.get(lead.loc.start.line - 1);
-          if (lead.type === AST_TOKEN_TYPES2.Line && previousLine?.type === AST_TOKEN_TYPES2.Line && previousLine.loc.start.column === lead.loc.start.column) {
+          if (lead.type === AST_TOKEN_TYPES3.Line && previousLine?.type === AST_TOKEN_TYPES3.Line && previousLine.loc.start.column === lead.loc.start.column) {
             return void 0;
           }
           return lead;
@@ -9526,7 +9549,7 @@ var no_union_in_comment_default = createRule({
 });
 
 // src/rules/no-type-member-comment-wall.ts
-import { AST_NODE_TYPES as AST_NODE_TYPES38, AST_TOKEN_TYPES as AST_TOKEN_TYPES3 } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES38, AST_TOKEN_TYPES as AST_TOKEN_TYPES4 } from "@typescript-eslint/utils";
 var NO_TYPE_MEMBER_COMMENT_WALL_DOCUMENTATION = {
   summary: "Flag an object type whose member comments mostly re-spell the members' own names and types.",
   rationale: "Repetitive member comments add scanning cost while hiding the comments that describe facts absent from the type.",
@@ -9591,7 +9614,7 @@ var no_type_member_comment_wall_default = createRule({
         const before = sourceCode.getTokenBefore(lead, { includeComments: false });
         if (before === null || before.loc.end.line < lead.loc.start.line) {
           const previousLine = endingOn.get(lead.loc.start.line - 1);
-          if (lead.type === AST_TOKEN_TYPES3.Line && previousLine?.type === AST_TOKEN_TYPES3.Line && previousLine.loc.start.column === lead.loc.start.column) {
+          if (lead.type === AST_TOKEN_TYPES4.Line && previousLine?.type === AST_TOKEN_TYPES4.Line && previousLine.loc.start.column === lead.loc.start.column) {
             return void 0;
           }
           return lead;
@@ -19724,7 +19747,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.17.5"
+  version: "15.17.6"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {
@@ -19734,6 +19757,7 @@ var LIBRARY_IMPORT_POLICY = ["error", {
 var ADVISORY_RULES = [
   "@sarj/excessive-commentary",
   "@sarj/no-bespoke-api-case-conversion",
+  "@sarj/no-restated-comment",
   "@sarj/prefer-millisecond-control-duration-schema",
   "@sarj/prefer-module-level-refined-schema",
   "@sarj/prefer-multi-value-zod-literal",
@@ -19781,7 +19805,7 @@ var RECOMMENDED_RULES = {
   "@sarj/no-production-browser-source-maps": "error",
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
-  "@sarj/no-restated-comment": "error",
+  "@sarj/no-restated-comment": "warn",
   "@sarj/no-restated-jsdoc": "error",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",
@@ -19877,7 +19901,7 @@ var STRICT_RULES = {
   "@sarj/no-raw-fetch-outside-clients": "error",
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
-  "@sarj/no-restated-comment": "error",
+  "@sarj/no-restated-comment": "warn",
   "@sarj/no-restated-jsdoc": "error",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/eslint-plugin",
-  "version": "15.17.5",
+  "version": "15.17.6",
   "packageManager": "npm@12.0.2",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",