@sarj/eslint-plugin 15.10.0 → 15.10.3

package/dist/index.cjs

@@ -1456,7 +1456,7 @@ var no_comment_cruft_default = createRule({
       sectionBanner: "Section-banner / region comment \u2014 remove the decoration or replace it with a named code boundary.",
       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.",
+      redundantNarration: "Comment narrates the code \u2014 delete it; if the code still needs explanation, use clearer names or extract a named helper. Keep only constraints or rationale.",
       placeholderImplementation: "Placeholder implementation comment \u2014 implement the behavior or use an explicit unsupported path.",
       untrackedTodo: "Untracked TODO/FIXME marker \u2014 add an issue ticket or context link."
     }
@@ -4212,6 +4212,7 @@ var DIRECTIVE_RE2 = /^(?:!|eslint\b|eslint-|@ts-|prettier|biome-|c8\b|v8\b|istan
 var LICENSE_RE2 = /\b(?:copyright|spdx-license-identifier|licensed under)\b/i;
 var TYPED_TAG_RE = /@(arg|argument|param|return|returns|yield|yields)\b/i;
 var VALUE_TAG_RE = /@(example|deprecated|see|remarks|throws|internal|public|alpha|beta|since|template|fileoverview)\b/i;
+var ANY_TAG_RE = /(?:^|\s)@[A-Za-z][\w-]*\b/u;
 var BOUNDARY_RE = /(?<=[.!?])["'`)\]]*\s+(?=[A-Z0-9`])/;
 var BULLET_RE = /^\s*(?:[-*+] |\d+[.)] )/;
 var HEADING_RE = /^[A-Za-z][A-Za-z ]+:$/;
@@ -4219,8 +4220,8 @@ var TECHNICAL_ANCHOR_RE = /https?:\/\/|`[^`\n]+`|:[a-z][a-z0-9_-]*:|(["'])[^"'\n
 function body(comment) {
   return comment.value.replace(/^\*/, "").split("\n").map((line) => line.replace(/^\s*\*?\s?/, "")).join("\n").trim();
 }
-function eligible(text, includeValueTags) {
-  return text.length > 0 && !DIRECTIVE_RE2.test(text) && !LICENSE_RE2.test(text) && (includeValueTags || !VALUE_TAG_RE.test(text));
+function eligible(text, includeValueTags, jsDoc = false) {
+  return text.length > 0 && !DIRECTIVE_RE2.test(text) && !LICENSE_RE2.test(text) && (includeValueTags || !VALUE_TAG_RE.test(text) && (!jsDoc || !ANY_TAG_RE.test(text)));
 }
 function sentenceUnits(text) {
   const cleaned = text.replace(/https?:\/\/\S+/g, "URL").replace(/`[^`\n]+`/g, "CODE").replace(/\b\d+\.\d+\b/g, "NUMBER").replace(/\b(?:e\.g\.|i\.e\.|vs\.|etc\.)/gi, "ABBREVIATION");
@@ -4260,7 +4261,9 @@ function proseGroups(filename, sourceCode, includeValueTags = false) {
     const text = body(comment);
     if (comment.type === "Block") {
       flush();
-      if (eligible(text, includeValueTags)) groups.push({ comment, text, hasTypedTags: TYPED_TAG_RE.test(text) });
+      if (eligible(text, includeValueTags, comment.value.startsWith("*"))) {
+        groups.push({ comment, text, hasTypedTags: TYPED_TAG_RE.test(text) });
+      }
       continue;
     }
     const ownLine = sourceCode.lines[comment.loc.start.line - 1]?.slice(0, comment.loc.start.column).trim() === "";
@@ -5956,7 +5959,7 @@ var no_restated_jsdoc_default = createRule({
     },
     schema: [],
     messages: {
-      restatesSignature: "JSDoc only re-spells the signature \u2014 delete it, or say what the caller cannot read off the name (what it throws, what it assumes, why it exists).",
+      restatesSignature: "JSDoc only re-spells the signature \u2014 delete it; if the signature still needs explanation, improve its names or types. Keep constraints, failures, and rationale.",
       deleteBlock: "Delete the JSDoc block."
     }
   },
@@ -7829,7 +7832,7 @@ var no_typed_doc_sections_default = createRule({
     docs: { description: "Reject typed-signature repetition while preserving behavior that types cannot express." },
     schema: [],
     messages: {
-      typedSection: "Typed JSDoc repeats parameters or returns \u2014 delete the tags and improve names or types instead."
+      typedSection: "Typed JSDoc repeats parameters or returns \u2014 delete the repeated tags; if the signature still needs explanation, improve its names or types. Keep constraints and rationale."
     }
   },
   defaultOptions: [],
@@ -8098,6 +8101,9 @@ function labelStems(body2) {
 function commentBody(comment) {
   return comment.value.replace(/^\*+/, "").replace(/^[ \t]*\*[ \t]?/gm, "").trim();
 }
+function hasJsDocTag(comment) {
+  return comment.type === import_utils41.AST_TOKEN_TYPES.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);
 }
@@ -8208,7 +8214,7 @@ var no_declaration_comment_wall_default = createRule({
     },
     schema: [WALL_SCHEMA],
     messages: {
-      commentWall: "{{restated}} of this declaration's {{commented}} member comments only re-spell the member's own name \u2014 delete them, and keep the rows that say what the name cannot."
+      commentWall: "{{restated}} of this declaration's {{commented}} member comments only re-spell member names \u2014 delete them; if a row still needs narration, give the member a clearer name. Keep constraints, lifecycle, and rationale."
     }
   },
   defaultOptions: [WALL_DEFAULTS],
@@ -8268,7 +8274,7 @@ var no_declaration_comment_wall_default = createRule({
         claimed.add(comment);
         commented += 1;
         const body2 = commentBody(comment);
-        if (body2.length === 0 || carriesValue(body2) || isTagsOnly(body2) || isLabel(body2)) {
+        if (body2.length === 0 || hasJsDocTag(comment) || carriesValue(body2) || isTagsOnly(body2) || isLabel(body2)) {
           continue;
         }
         const { end, start } = declarationRange(member.node);
@@ -8516,7 +8522,7 @@ var no_type_member_comment_wall_default = createRule({
     },
     schema: [WALL_SCHEMA],
     messages: {
-      commentWall: "{{restated}} of this type's {{commented}} member comments only re-spell the member's own name and type \u2014 delete them, and keep the rows that say what the name cannot."
+      commentWall: "{{restated}} of this type's {{commented}} member comments only re-spell names and types \u2014 delete them; if a row still needs narration, improve its name or type. Keep constraints and rationale."
     }
   },
   defaultOptions: [WALL_DEFAULTS],
@@ -8574,7 +8580,9 @@ var no_type_member_comment_wall_default = createRule({
         claimed.add(comment);
         commented += 1;
         const body2 = commentBody(comment);
-        if (body2.length === 0 || carriesValue(body2) || isTagsOnly(body2)) continue;
+        if (body2.length === 0 || hasJsDocTag(comment) || carriesValue(body2) || isTagsOnly(body2)) {
+          continue;
+        }
         if (novelWords(body2, knownTokens(sourceCode.getText(member))) <= options.maxNovelWords) {
           restated += 1;
         }
@@ -16048,7 +16056,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.10.0"
+  version: "15.10.3"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",

package/dist/index.d.cts

@@ -438,7 +438,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.10.0";
+        readonly version: "15.10.3";
     };
     readonly rules: {
         readonly "iac-source-coupled-test": DocumentedRule<readonly [], "rawSourceOracle">;

package/dist/index.d.ts

@@ -438,7 +438,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.10.0";
+        readonly version: "15.10.3";
     };
     readonly rules: {
         readonly "iac-source-coupled-test": DocumentedRule<readonly [], "rawSourceOracle">;

package/dist/index.js

@@ -1412,7 +1412,7 @@ var no_comment_cruft_default = createRule({
       sectionBanner: "Section-banner / region comment \u2014 remove the decoration or replace it with a named code boundary.",
       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.",
+      redundantNarration: "Comment narrates the code \u2014 delete it; if the code still needs explanation, use clearer names or extract a named helper. Keep only constraints or rationale.",
       placeholderImplementation: "Placeholder implementation comment \u2014 implement the behavior or use an explicit unsupported path.",
       untrackedTodo: "Untracked TODO/FIXME marker \u2014 add an issue ticket or context link."
     }
@@ -4173,6 +4173,7 @@ var DIRECTIVE_RE2 = /^(?:!|eslint\b|eslint-|@ts-|prettier|biome-|c8\b|v8\b|istan
 var LICENSE_RE2 = /\b(?:copyright|spdx-license-identifier|licensed under)\b/i;
 var TYPED_TAG_RE = /@(arg|argument|param|return|returns|yield|yields)\b/i;
 var VALUE_TAG_RE = /@(example|deprecated|see|remarks|throws|internal|public|alpha|beta|since|template|fileoverview)\b/i;
+var ANY_TAG_RE = /(?:^|\s)@[A-Za-z][\w-]*\b/u;
 var BOUNDARY_RE = /(?<=[.!?])["'`)\]]*\s+(?=[A-Z0-9`])/;
 var BULLET_RE = /^\s*(?:[-*+] |\d+[.)] )/;
 var HEADING_RE = /^[A-Za-z][A-Za-z ]+:$/;
@@ -4180,8 +4181,8 @@ var TECHNICAL_ANCHOR_RE = /https?:\/\/|`[^`\n]+`|:[a-z][a-z0-9_-]*:|(["'])[^"'\n
 function body(comment) {
   return comment.value.replace(/^\*/, "").split("\n").map((line) => line.replace(/^\s*\*?\s?/, "")).join("\n").trim();
 }
-function eligible(text, includeValueTags) {
-  return text.length > 0 && !DIRECTIVE_RE2.test(text) && !LICENSE_RE2.test(text) && (includeValueTags || !VALUE_TAG_RE.test(text));
+function eligible(text, includeValueTags, jsDoc = false) {
+  return text.length > 0 && !DIRECTIVE_RE2.test(text) && !LICENSE_RE2.test(text) && (includeValueTags || !VALUE_TAG_RE.test(text) && (!jsDoc || !ANY_TAG_RE.test(text)));
 }
 function sentenceUnits(text) {
   const cleaned = text.replace(/https?:\/\/\S+/g, "URL").replace(/`[^`\n]+`/g, "CODE").replace(/\b\d+\.\d+\b/g, "NUMBER").replace(/\b(?:e\.g\.|i\.e\.|vs\.|etc\.)/gi, "ABBREVIATION");
@@ -4221,7 +4222,9 @@ function proseGroups(filename, sourceCode, includeValueTags = false) {
     const text = body(comment);
     if (comment.type === "Block") {
       flush();
-      if (eligible(text, includeValueTags)) groups.push({ comment, text, hasTypedTags: TYPED_TAG_RE.test(text) });
+      if (eligible(text, includeValueTags, comment.value.startsWith("*"))) {
+        groups.push({ comment, text, hasTypedTags: TYPED_TAG_RE.test(text) });
+      }
       continue;
     }
     const ownLine = sourceCode.lines[comment.loc.start.line - 1]?.slice(0, comment.loc.start.column).trim() === "";
@@ -5917,7 +5920,7 @@ var no_restated_jsdoc_default = createRule({
     },
     schema: [],
     messages: {
-      restatesSignature: "JSDoc only re-spells the signature \u2014 delete it, or say what the caller cannot read off the name (what it throws, what it assumes, why it exists).",
+      restatesSignature: "JSDoc only re-spells the signature \u2014 delete it; if the signature still needs explanation, improve its names or types. Keep constraints, failures, and rationale.",
       deleteBlock: "Delete the JSDoc block."
     }
   },
@@ -7790,7 +7793,7 @@ var no_typed_doc_sections_default = createRule({
     docs: { description: "Reject typed-signature repetition while preserving behavior that types cannot express." },
     schema: [],
     messages: {
-      typedSection: "Typed JSDoc repeats parameters or returns \u2014 delete the tags and improve names or types instead."
+      typedSection: "Typed JSDoc repeats parameters or returns \u2014 delete the repeated tags; if the signature still needs explanation, improve its names or types. Keep constraints and rationale."
     }
   },
   defaultOptions: [],
@@ -7991,10 +7994,10 @@ var no_trailing_value_narration_default = createRule({
 });
 
 // src/rules/no-declaration-comment-wall.ts
-import { AST_NODE_TYPES as AST_NODE_TYPES30, AST_TOKEN_TYPES } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES30, AST_TOKEN_TYPES as AST_TOKEN_TYPES2 } from "@typescript-eslint/utils";
 
 // src/rules/_comment-wall.ts
-import { AST_NODE_TYPES as AST_NODE_TYPES29 } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES29, AST_TOKEN_TYPES } from "@typescript-eslint/utils";
 var WALL_DEFAULTS = {
   // Below three rows "a wall" is not a fair description of what the reader sees.
   minCommentedMembers: 3,
@@ -8059,6 +8062,9 @@ function labelStems(body2) {
 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));
+}
 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);
 }
@@ -8169,7 +8175,7 @@ var no_declaration_comment_wall_default = createRule({
     },
     schema: [WALL_SCHEMA],
     messages: {
-      commentWall: "{{restated}} of this declaration's {{commented}} member comments only re-spell the member's own name \u2014 delete them, and keep the rows that say what the name cannot."
+      commentWall: "{{restated}} of this declaration's {{commented}} member comments only re-spell member names \u2014 delete them; if a row still needs narration, give the member a clearer name. Keep constraints, lifecycle, and rationale."
     }
   },
   defaultOptions: [WALL_DEFAULTS],
@@ -8193,7 +8199,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_TYPES.Line && previousLine?.type === AST_TOKEN_TYPES.Line && previousLine.loc.start.column === lead.loc.start.column) {
+          if (lead.type === AST_TOKEN_TYPES2.Line && previousLine?.type === AST_TOKEN_TYPES2.Line && previousLine.loc.start.column === lead.loc.start.column) {
             return void 0;
           }
           return lead;
@@ -8229,7 +8235,7 @@ var no_declaration_comment_wall_default = createRule({
         claimed.add(comment);
         commented += 1;
         const body2 = commentBody(comment);
-        if (body2.length === 0 || carriesValue(body2) || isTagsOnly(body2) || isLabel(body2)) {
+        if (body2.length === 0 || hasJsDocTag(comment) || carriesValue(body2) || isTagsOnly(body2) || isLabel(body2)) {
           continue;
         }
         const { end, start } = declarationRange(member.node);
@@ -8436,7 +8442,7 @@ var no_union_in_comment_default = createRule({
 });
 
 // src/rules/no-type-member-comment-wall.ts
-import { AST_NODE_TYPES as AST_NODE_TYPES32, AST_TOKEN_TYPES as AST_TOKEN_TYPES2 } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES32, AST_TOKEN_TYPES as AST_TOKEN_TYPES3 } from "@typescript-eslint/utils";
 var noTypeMemberCommentWallDocumentation = {
   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.",
@@ -8477,7 +8483,7 @@ var no_type_member_comment_wall_default = createRule({
     },
     schema: [WALL_SCHEMA],
     messages: {
-      commentWall: "{{restated}} of this type's {{commented}} member comments only re-spell the member's own name and type \u2014 delete them, and keep the rows that say what the name cannot."
+      commentWall: "{{restated}} of this type's {{commented}} member comments only re-spell names and types \u2014 delete them; if a row still needs narration, improve its name or type. Keep constraints and rationale."
     }
   },
   defaultOptions: [WALL_DEFAULTS],
@@ -8501,7 +8507,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_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;
@@ -8535,7 +8541,9 @@ var no_type_member_comment_wall_default = createRule({
         claimed.add(comment);
         commented += 1;
         const body2 = commentBody(comment);
-        if (body2.length === 0 || carriesValue(body2) || isTagsOnly(body2)) continue;
+        if (body2.length === 0 || hasJsDocTag(comment) || carriesValue(body2) || isTagsOnly(body2)) {
+          continue;
+        }
         if (novelWords(body2, knownTokens(sourceCode.getText(member))) <= options.maxNovelWords) {
           restated += 1;
         }
@@ -16029,7 +16037,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.10.0"
+  version: "15.10.3"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/eslint-plugin",
-  "version": "15.10.0",
+  "version": "15.10.3",
   "packageManager": "npm@12.0.2",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",
@@ -59,10 +59,10 @@
     "@eslint-community/eslint-plugin-eslint-comments": "^4.7.2",
     "@eslint/compat": "^2.1.0",
     "@eslint/js": "10.0.1",
-    "@types/node": "latest",
-    "@typescript-eslint/parser": "latest",
-    "@typescript-eslint/rule-tester": "latest",
-    "@typescript-eslint/utils": "latest",
+    "@types/node": "26.2.0",
+    "@typescript-eslint/parser": "8.67.0",
+    "@typescript-eslint/rule-tester": "8.67.0",
+    "@typescript-eslint/utils": "8.67.0",
     "eslint": "^10.8.1",
     "eslint-plugin-better-tailwindcss": "^4.7.0",
     "eslint-plugin-perfectionist": "^5.10.1",
@@ -73,9 +73,9 @@
     "eslint-plugin-unicorn": "^73.0.0",
     "eslint-plugin-zod": "^4.9.1",
     "tsup": "latest",
-    "typescript": "latest",
+    "typescript": "6.0.3",
     "typescript-eslint": "^8.67.0",
-    "vitest": "latest"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
     "eslint": ">=9.39.4",
@@ -85,7 +85,7 @@
     "node": ">=22.13.0"
   },
   "allowScripts": {
-    "esbuild@0.28.1": true,
+    "esbuild@0.28.2": true,
     "fsevents@2.3.3": true
   },
   "peerDependenciesMeta": {
@@ -95,8 +95,8 @@
   },
   "overrides": {
     "brace-expansion@^5.0.0": "5.0.9",
-    "esbuild": "^0.28.1",
-    "nanoid@<3.3.17": "3.3.17",
+    "esbuild": "0.28.2",
+    "nanoid@<3.3.18": "3.3.18",
     "eslint-plugin-react": {
       "eslint": "$eslint"
     }