@sarj/eslint-plugin 15.8.0 → 15.8.2

package/dist/index.d.cts

@@ -220,7 +220,7 @@ declare const rules: {
         libraries: readonly RestrictedLibrary[];
     }], "restrictedLibraryLoad">;
     readonly "no-repeated-string-literal": DocumentedRule<readonly [], "noRepeatedStringLiteral">;
-    readonly "no-restated-comment": DocumentedRule<readonly [], "restatesLineBelow">;
+    readonly "no-restated-comment": DocumentedRule<readonly [], "deleteComment" | "restatesLineBelow">;
     readonly "no-restated-jsdoc": DocumentedRule<readonly [], "restatesSignature" | "deleteBlock">;
     readonly "no-secret-in-log": DocumentedRule<readonly [LoggingOptions?], "noSecretInLog" | "noRawBodyInLog">;
     readonly "no-select-star": DocumentedRule<readonly [], "noSelectStar">;
@@ -231,7 +231,7 @@ declare const rules: {
     readonly "no-string-concat-in-loop": DocumentedRule<readonly [], "noStringConcatInLoop" | "noStringReduce">;
     readonly "no-tautological-expect": DocumentedRule<readonly [], "tautologicalComparison" | "tautologicalMatcher">;
     readonly "no-typed-doc-sections": DocumentedRule<readonly [], "typedSection">;
-    readonly "no-trailing-value-narration": DocumentedRule<readonly [], "deleteNarration" | "narratesValue">;
+    readonly "no-trailing-value-narration": DocumentedRule<readonly [], "deleteNarration" | "narratesValue" | "removeNarration">;
     readonly "no-declaration-comment-wall": DocumentedRule<readonly [Partial<WallOptions>?], "commentWall">;
     readonly "no-union-in-comment": DocumentedRule<readonly [], "unionInComment">;
     readonly "no-type-member-comment-wall": DocumentedRule<readonly [Partial<WallOptions>?], "commentWall">;
@@ -286,7 +286,7 @@ declare const rules: {
 /** Rules registered for application-profile configs but intentionally absent from general presets. */
 declare const applicationOnlyRules: readonly ["no-restricted-library-load", "prefer-native-random-uuid", "prefer-shadcn-primitives"];
 /** Calibrated rules that intentionally remain warnings until consumer-corpus precision is proven. */
-declare const advisoryRules: readonly ["no-bare-return-from-test-catch", "no-vague-suppression-description", "iac-source-coupled-test", "repeated-static-call-cases", "source-coupled-test"];
+declare const advisoryRules: readonly ["no-bare-return-from-test-catch", "iac-source-coupled-test", "repeated-static-call-cases", "source-coupled-test"];
 declare const recommendedRules: {
     readonly "@sarj/iac-source-coupled-test": "warn";
     readonly "@sarj/duplicate-test-body": "error";
@@ -306,7 +306,7 @@ declare const recommendedRules: {
     readonly "@sarj/no-log-only-catch": "error";
     readonly "@sarj/no-bare-return-from-test-catch": "warn";
     readonly "@sarj/no-long-comment": "error";
-    readonly "@sarj/no-vague-suppression-description": "warn";
+    readonly "@sarj/no-vague-suppression-description": "error";
     readonly "@sarj/no-generic-single-export-module": "error";
     readonly "@sarj/no-offset-pagination": "error";
     readonly "@sarj/no-positional-tuple-return": "error";
@@ -375,7 +375,7 @@ declare const strictRules: {
     readonly "@sarj/no-log-only-catch": "error";
     readonly "@sarj/no-bare-return-from-test-catch": "warn";
     readonly "@sarj/no-long-comment": "error";
-    readonly "@sarj/no-vague-suppression-description": "warn";
+    readonly "@sarj/no-vague-suppression-description": "error";
     readonly "@sarj/no-generic-single-export-module": "error";
     readonly "@sarj/no-offset-pagination": "error";
     readonly "@sarj/no-positional-tuple-return": "error";
@@ -435,7 +435,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.8.0";
+        readonly version: "15.8.2";
     };
     readonly rules: {
         readonly "iac-source-coupled-test": DocumentedRule<readonly [], "rawSourceOracle">;
@@ -470,7 +470,7 @@ declare const plugin: {
             libraries: readonly RestrictedLibrary[];
         }], "restrictedLibraryLoad">;
         readonly "no-repeated-string-literal": DocumentedRule<readonly [], "noRepeatedStringLiteral">;
-        readonly "no-restated-comment": DocumentedRule<readonly [], "restatesLineBelow">;
+        readonly "no-restated-comment": DocumentedRule<readonly [], "deleteComment" | "restatesLineBelow">;
         readonly "no-restated-jsdoc": DocumentedRule<readonly [], "restatesSignature" | "deleteBlock">;
         readonly "no-secret-in-log": DocumentedRule<readonly [LoggingOptions?], "noSecretInLog" | "noRawBodyInLog">;
         readonly "no-select-star": DocumentedRule<readonly [], "noSelectStar">;
@@ -481,7 +481,7 @@ declare const plugin: {
         readonly "no-string-concat-in-loop": DocumentedRule<readonly [], "noStringConcatInLoop" | "noStringReduce">;
         readonly "no-tautological-expect": DocumentedRule<readonly [], "tautologicalComparison" | "tautologicalMatcher">;
         readonly "no-typed-doc-sections": DocumentedRule<readonly [], "typedSection">;
-        readonly "no-trailing-value-narration": DocumentedRule<readonly [], "deleteNarration" | "narratesValue">;
+        readonly "no-trailing-value-narration": DocumentedRule<readonly [], "deleteNarration" | "narratesValue" | "removeNarration">;
         readonly "no-declaration-comment-wall": DocumentedRule<readonly [Partial<WallOptions>?], "commentWall">;
         readonly "no-union-in-comment": DocumentedRule<readonly [], "unionInComment">;
         readonly "no-type-member-comment-wall": DocumentedRule<readonly [Partial<WallOptions>?], "commentWall">;

package/dist/index.d.ts

@@ -220,7 +220,7 @@ declare const rules: {
         libraries: readonly RestrictedLibrary[];
     }], "restrictedLibraryLoad">;
     readonly "no-repeated-string-literal": DocumentedRule<readonly [], "noRepeatedStringLiteral">;
-    readonly "no-restated-comment": DocumentedRule<readonly [], "restatesLineBelow">;
+    readonly "no-restated-comment": DocumentedRule<readonly [], "deleteComment" | "restatesLineBelow">;
     readonly "no-restated-jsdoc": DocumentedRule<readonly [], "restatesSignature" | "deleteBlock">;
     readonly "no-secret-in-log": DocumentedRule<readonly [LoggingOptions?], "noSecretInLog" | "noRawBodyInLog">;
     readonly "no-select-star": DocumentedRule<readonly [], "noSelectStar">;
@@ -231,7 +231,7 @@ declare const rules: {
     readonly "no-string-concat-in-loop": DocumentedRule<readonly [], "noStringConcatInLoop" | "noStringReduce">;
     readonly "no-tautological-expect": DocumentedRule<readonly [], "tautologicalComparison" | "tautologicalMatcher">;
     readonly "no-typed-doc-sections": DocumentedRule<readonly [], "typedSection">;
-    readonly "no-trailing-value-narration": DocumentedRule<readonly [], "deleteNarration" | "narratesValue">;
+    readonly "no-trailing-value-narration": DocumentedRule<readonly [], "deleteNarration" | "narratesValue" | "removeNarration">;
     readonly "no-declaration-comment-wall": DocumentedRule<readonly [Partial<WallOptions>?], "commentWall">;
     readonly "no-union-in-comment": DocumentedRule<readonly [], "unionInComment">;
     readonly "no-type-member-comment-wall": DocumentedRule<readonly [Partial<WallOptions>?], "commentWall">;
@@ -286,7 +286,7 @@ declare const rules: {
 /** Rules registered for application-profile configs but intentionally absent from general presets. */
 declare const applicationOnlyRules: readonly ["no-restricted-library-load", "prefer-native-random-uuid", "prefer-shadcn-primitives"];
 /** Calibrated rules that intentionally remain warnings until consumer-corpus precision is proven. */
-declare const advisoryRules: readonly ["no-bare-return-from-test-catch", "no-vague-suppression-description", "iac-source-coupled-test", "repeated-static-call-cases", "source-coupled-test"];
+declare const advisoryRules: readonly ["no-bare-return-from-test-catch", "iac-source-coupled-test", "repeated-static-call-cases", "source-coupled-test"];
 declare const recommendedRules: {
     readonly "@sarj/iac-source-coupled-test": "warn";
     readonly "@sarj/duplicate-test-body": "error";
@@ -306,7 +306,7 @@ declare const recommendedRules: {
     readonly "@sarj/no-log-only-catch": "error";
     readonly "@sarj/no-bare-return-from-test-catch": "warn";
     readonly "@sarj/no-long-comment": "error";
-    readonly "@sarj/no-vague-suppression-description": "warn";
+    readonly "@sarj/no-vague-suppression-description": "error";
     readonly "@sarj/no-generic-single-export-module": "error";
     readonly "@sarj/no-offset-pagination": "error";
     readonly "@sarj/no-positional-tuple-return": "error";
@@ -375,7 +375,7 @@ declare const strictRules: {
     readonly "@sarj/no-log-only-catch": "error";
     readonly "@sarj/no-bare-return-from-test-catch": "warn";
     readonly "@sarj/no-long-comment": "error";
-    readonly "@sarj/no-vague-suppression-description": "warn";
+    readonly "@sarj/no-vague-suppression-description": "error";
     readonly "@sarj/no-generic-single-export-module": "error";
     readonly "@sarj/no-offset-pagination": "error";
     readonly "@sarj/no-positional-tuple-return": "error";
@@ -435,7 +435,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.8.0";
+        readonly version: "15.8.2";
     };
     readonly rules: {
         readonly "iac-source-coupled-test": DocumentedRule<readonly [], "rawSourceOracle">;
@@ -470,7 +470,7 @@ declare const plugin: {
             libraries: readonly RestrictedLibrary[];
         }], "restrictedLibraryLoad">;
         readonly "no-repeated-string-literal": DocumentedRule<readonly [], "noRepeatedStringLiteral">;
-        readonly "no-restated-comment": DocumentedRule<readonly [], "restatesLineBelow">;
+        readonly "no-restated-comment": DocumentedRule<readonly [], "deleteComment" | "restatesLineBelow">;
         readonly "no-restated-jsdoc": DocumentedRule<readonly [], "restatesSignature" | "deleteBlock">;
         readonly "no-secret-in-log": DocumentedRule<readonly [LoggingOptions?], "noSecretInLog" | "noRawBodyInLog">;
         readonly "no-select-star": DocumentedRule<readonly [], "noSelectStar">;
@@ -481,7 +481,7 @@ declare const plugin: {
         readonly "no-string-concat-in-loop": DocumentedRule<readonly [], "noStringConcatInLoop" | "noStringReduce">;
         readonly "no-tautological-expect": DocumentedRule<readonly [], "tautologicalComparison" | "tautologicalMatcher">;
         readonly "no-typed-doc-sections": DocumentedRule<readonly [], "typedSection">;
-        readonly "no-trailing-value-narration": DocumentedRule<readonly [], "deleteNarration" | "narratesValue">;
+        readonly "no-trailing-value-narration": DocumentedRule<readonly [], "deleteNarration" | "narratesValue" | "removeNarration">;
         readonly "no-declaration-comment-wall": DocumentedRule<readonly [Partial<WallOptions>?], "commentWall">;
         readonly "no-union-in-comment": DocumentedRule<readonly [], "unionInComment">;
         readonly "no-type-member-comment-wall": DocumentedRule<readonly [Partial<WallOptions>?], "commentWall">;

package/dist/index.js

@@ -5586,6 +5586,38 @@ var no_repeated_string_literal_default = createRule({
 
 // src/rules/no-restated-comment.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES22 } from "@typescript-eslint/utils";
+
+// src/rules/_comment-edits.ts
+import "@typescript-eslint/utils";
+function physicalLineEnd(text, offset) {
+  const newline = text.indexOf("\n", offset);
+  return newline < 0 ? text.length : newline;
+}
+function contentLineEnd(text, offset) {
+  const end = physicalLineEnd(text, offset);
+  return end > offset && text[end - 1] === "\r" ? end - 1 : end;
+}
+function wholeLineRemovalRange(text, comment) {
+  if (comment.loc.start.line !== comment.loc.end.line) return null;
+  const lineStart = text.lastIndexOf("\n", Math.max(0, comment.range[0] - 1)) + 1;
+  if (!/^[\t ]*$/u.test(text.slice(lineStart, comment.range[0]))) return null;
+  const contentEnd = contentLineEnd(text, comment.range[1]);
+  if (!/^[\t ]*$/u.test(text.slice(comment.range[1], contentEnd))) return null;
+  const physicalEnd = physicalLineEnd(text, comment.range[1]);
+  return { range: [lineStart, physicalEnd < text.length ? physicalEnd + 1 : physicalEnd] };
+}
+function trailingCommentRemovalRange(text, comment) {
+  if (comment.loc.start.line !== comment.loc.end.line) return null;
+  const contentEnd = contentLineEnd(text, comment.range[1]);
+  if (!/^[\t ]*$/u.test(text.slice(comment.range[1], contentEnd))) return null;
+  let start = comment.range[0];
+  while (start > 0 && (text[start - 1] === " " || text[start - 1] === "	")) {
+    start -= 1;
+  }
+  return { range: [start, contentEnd] };
+}
+
+// src/rules/no-restated-comment.ts
 var MAX_WORDS = 8;
 var MIN_CONTENT_TOKENS = 2;
 var DIRECTIVE_RE3 = /^(eslint\b|eslint-|sarj-noqa\b|@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;
@@ -5605,6 +5637,7 @@ var noRestatedCommentDocumentation = {
   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.",
   category: "maintainability",
+  autofix: "suggestion",
   limitations: ["Directives, protected references, questions, multi-line prose, comments with novel content, and generated files are excluded."],
   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 },
@@ -5628,11 +5661,13 @@ var no_restated_comment_default = createRule({
   documentation: noRestatedCommentDocumentation,
   meta: {
     type: "suggestion",
+    hasSuggestions: true,
     docs: {
       description: "Flag a single-line comment whose every word already appears on the statement below it."
     },
     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*."
     }
   },
@@ -5701,7 +5736,17 @@ var no_restated_comment_default = createRule({
           if (!ACTION_STMT_RE.test(line)) continue;
           if (labelsASiblingRun(comment)) continue;
           if (restates(tokens, codeTokens(line))) {
-            context.report({ node: comment, messageId: "restatesLineBelow" });
+            const removal = wholeLineRemovalRange(sourceCode.text, comment);
+            context.report({
+              node: comment,
+              messageId: "restatesLineBelow",
+              suggest: removal === null ? null : [
+                {
+                  messageId: "deleteComment",
+                  fix: (fixer) => fixer.removeRange(removal.range)
+                }
+              ]
+            });
           }
         }
       }
@@ -7729,6 +7774,7 @@ var noTrailingValueNarrationDocumentation = {
   rationale: "A repeated value can disagree with the expression after either the code or comment changes.",
   remediation: "Put the unit in the identifier and keep comments only when they explain a constraint or non-obvious conversion.",
   category: "maintainability",
+  autofix: "suggestion",
   aliases: ["trailing-value-narration"],
   limitations: ["Only trailing comments with numeric values and recognized unit words are inspected."],
   examples: [
@@ -7845,13 +7891,15 @@ var no_trailing_value_narration_default = createRule({
   documentation: noTrailingValueNarrationDocumentation,
   meta: {
     type: "suggestion",
+    hasSuggestions: true,
     docs: {
       description: "Flag a trailing comment that repeats the line's numeric value only to name its unit."
     },
     schema: [],
     messages: {
       deleteNarration: "Trailing comment restates the literal and the identifier already names its unit \u2014 delete the comment so it cannot drift.",
-      narratesValue: "Trailing comment restates the literal on this line \u2014 put the unit in the name (STALE_TIME_MS) so it cannot drift."
+      narratesValue: "Trailing comment restates the literal on this line \u2014 put the unit in the name (STALE_TIME_MS) so it cannot drift.",
+      removeNarration: "Delete the redundant trailing narration."
     }
   },
   defaultOptions: [],
@@ -7883,9 +7931,17 @@ var no_trailing_value_narration_default = createRule({
           const code = line.slice(0, comment.loc.start.column);
           const body2 = comment.value.replace(/^\*+/, "").replace(/\*+$/, "").trim();
           if (narratesValue(body2, code)) {
+            const canDelete = nameAlreadyCarriesUnit(code);
+            const removal = canDelete ? trailingCommentRemovalRange(sourceCode.text, comment) : null;
             context.report({
               node: comment,
-              messageId: nameAlreadyCarriesUnit(code) ? "deleteNarration" : "narratesValue"
+              messageId: canDelete ? "deleteNarration" : "narratesValue",
+              suggest: removal === null ? null : [
+                {
+                  messageId: "removeNarration",
+                  fix: (fixer) => fixer.removeRange(removal.range)
+                }
+              ]
             });
           }
         }
@@ -15768,7 +15824,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.8.0"
+  version: "15.8.2"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",
@@ -15777,7 +15833,6 @@ var applicationOnlyRules = [
 ];
 var advisoryRules = [
   "no-bare-return-from-test-catch",
-  "no-vague-suppression-description",
   "iac-source-coupled-test",
   "repeated-static-call-cases",
   "source-coupled-test"
@@ -15799,7 +15854,7 @@ var recommendedRules = {
   "@sarj/no-log-only-catch": "error",
   "@sarj/no-bare-return-from-test-catch": "warn",
   "@sarj/no-long-comment": "error",
-  "@sarj/no-vague-suppression-description": "warn",
+  "@sarj/no-vague-suppression-description": "error",
   "@sarj/no-generic-single-export-module": "error",
   "@sarj/no-offset-pagination": "error",
   "@sarj/no-positional-tuple-return": "error",
@@ -15864,7 +15919,7 @@ var strictRules = {
   "@sarj/no-log-only-catch": "error",
   "@sarj/no-bare-return-from-test-catch": "warn",
   "@sarj/no-long-comment": "error",
-  "@sarj/no-vague-suppression-description": "warn",
+  "@sarj/no-vague-suppression-description": "error",
   "@sarj/no-generic-single-export-module": "error",
   "@sarj/no-offset-pagination": "error",
   "@sarj/no-positional-tuple-return": "error",

package/package.json

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