@sarj/eslint-plugin 15.17.6 → 15.17.7

package/dist/index.cjs

@@ -6869,22 +6869,23 @@ var no_restated_comment_default = createRule({
 // src/rules/no-restated-jsdoc.ts
 var import_utils39 = require("@typescript-eslint/utils");
 var NO_RESTATED_JSDOC_DOCUMENTATION = {
-  summary: "Flag a JSDoc block whose description and tags only re-spell the signature they document.",
+  summary: "Flag JSDoc prose that appears to repeat declaration names without adding behavioral information.",
   rationale: "Signature-only JSDoc duplicates type information and drifts without helping callers.",
   remediation: "Delete the block or document behavior, constraints, failures, or context the signature cannot express.",
   category: "maintainability",
   aliases: ["jsdoc-restates-signature"],
   autofix: "suggestion",
-  limitations: ["Generated files, detached blocks, unknown tags, empty blocks, and JSDoc with information absent from the signature are excluded."],
+  limitations: ["Generated files, detached blocks, intervening comments, unknown tags, explicit JSDoc type payloads, empty blocks, and JSDoc with information absent from the signature are excluded.", "Negation, conditions, constraints, sentinel values, numeric details, and quoted text conservatively preserve the block, even when a declaration name contains the same words."],
   examples: [
     { id: "behavioral-jsdoc", title: "Document behavior absent from the signature", outcome: "no-match", files: [{ path: "src/users.ts", source: "/** Get the user while bypassing the read replica. */\nexport function getUser(id: string) { return id; }" }], focusPath: "src/users.ts", expectedCount: 0, public: true },
-    { id: "signature-jsdoc", title: "Remove JSDoc that only repeats the signature", outcome: "match", files: [{ path: "src/users.ts", source: "/** Get the user by id. */\nexport function getUserById(id: string) { return id; }" }], focusPath: "src/users.ts", expectedCount: 1, public: true }
+    { id: "signature-jsdoc", title: "Remove JSDoc that only repeats the signature", outcome: "match", files: [{ path: "src/users.ts", source: "/** Get the user by id. */\nexport function getUserById(id: string) { return id; }" }], focusPath: "src/users.ts", expectedCount: 1, public: true },
+    { id: "negated-behavior", scenarioId: "negation", title: "Keep behavior even when its words resemble the declaration", outcome: "no-match", files: [{ path: "src/users.ts", source: "/** Does not cache the user. */\nexport function cacheUser(user: unknown) { return user; }" }], focusPath: "src/users.ts", expectedCount: 0, public: true },
+    { id: "repeated-behavior-name", scenarioId: "negation", title: "Review prose that merely repeats the declaration name", outcome: "match", files: [{ path: "src/users.ts", source: "/** Cache the user. */\nexport function cacheUser(user: unknown) { return user; }" }], focusPath: "src/users.ts", expectedCount: 1, public: true }
   ]
 };
 var MODELLED_TAGS = /* @__PURE__ */ new Set([
   "arg",
   "argument",
-  "async",
   "description",
   "param",
   "return",
@@ -6903,7 +6904,8 @@ var STOPWORDS2 = new Set(
    returns returning result optional required default true false null undefined
    string number boolean array list promise`.split(/\s+/)
 );
-var WORD_RE2 = /[A-Za-z]+/g;
+var WORD_RE2 = new RegExp("\\p{L}+", "gu");
+var BEHAVIORAL_PROSE_RE = /\b(?:not|no|never|if|when|unless|must|should|may|can|could|would|optional|required|default|true|false|null|undefined|before|after|until|once|again|only|always)\b|\d|["'`<>=+*/%&|!~^-]/i;
 function parseJsDoc(value) {
   const lines = value.replace(/^\*/, "").split("\n").map((line) => line.replace(/^\s*\*?\s?/, ""));
   const description = [];
@@ -6923,12 +6925,13 @@ function parseJsDoc(value) {
   return { description: description.join("\n").trim(), tags };
 }
 function covered(text, known) {
+  if (BEHAVIORAL_PROSE_RE.test(text)) return false;
   const stems = /* @__PURE__ */ new Set();
   for (const token of known) stems.add(stem(token));
   return proseTokens(text).every((word) => known.has(word) || stems.has(stem(word)));
 }
 function proseTokens(text) {
-  return (text.match(WORD_RE2) ?? []).map((word) => word.toLowerCase()).filter((word) => word.length > 1 && !STOPWORDS2.has(word));
+  return (text.match(WORD_RE2) ?? []).map((word) => word.toLowerCase()).filter((word) => !STOPWORDS2.has(word));
 }
 function declarationNames(node) {
   switch (node.type) {
@@ -6985,11 +6988,11 @@ var no_restated_jsdoc_default = createRule({
     type: "suggestion",
     hasSuggestions: true,
     docs: {
-      description: "Flag a JSDoc block whose description and tags only re-spell the signature they document."
+      description: "Flag JSDoc prose that appears to repeat declaration names without adding behavioral information."
     },
     schema: [],
     messages: {
-      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.",
+      restatesSignature: "JSDoc appears to repeat declaration names \u2014 consider removing repetition. Keep type contracts, constraints, failures, and rationale.",
       deleteBlock: "Delete the JSDoc block."
     }
   },
@@ -7012,8 +7015,9 @@ var no_restated_jsdoc_default = createRule({
           const tagNames = new Set(tags.map((tag) => tag.name));
           if ([...tagNames].some((name) => !MODELLED_TAGS.has(name))) continue;
           if (isProtected(describedText)) continue;
-          const token = sourceCode.getTokenAfter(comment, { includeComments: false });
+          const token = sourceCode.getTokenAfter(comment, { includeComments: true });
           if (token === null || token.loc.start.line !== comment.loc.end.line + 1) continue;
+          if (token.type === "Line" || token.type === "Block") continue;
           let node = sourceCode.getNodeByRangeIndex(token.range[0]);
           let declaration = null;
           while (node != null && node.type !== import_utils39.AST_NODE_TYPES.Program) {
@@ -7024,6 +7028,8 @@ var no_restated_jsdoc_default = createRule({
           if (declaration === null) continue;
           const paramTags = tags.filter((tag) => PARAM_TAGS.has(tag.name));
           const returnTags = tags.filter((tag) => RETURN_TAGS.has(tag.name));
+          if ([...paramTags, ...returnTags].some((tag) => /^\s*\{/.test(tag.text))) continue;
+          if (paramTags.some((tag) => /^\s*(?:\[|[A-Za-z_$][\w$]*\.)/.test(tag.text))) continue;
           if (describedText.length === 0 && paramTags.length === 0 && returnTags.length === 0) {
             continue;
           }
@@ -19752,7 +19758,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.17.6"
+  version: "15.17.7"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {
@@ -19763,6 +19769,7 @@ var ADVISORY_RULES = [
   "@sarj/excessive-commentary",
   "@sarj/no-bespoke-api-case-conversion",
   "@sarj/no-restated-comment",
+  "@sarj/no-restated-jsdoc",
   "@sarj/prefer-millisecond-control-duration-schema",
   "@sarj/prefer-module-level-refined-schema",
   "@sarj/prefer-multi-value-zod-literal",
@@ -19811,7 +19818,7 @@ var RECOMMENDED_RULES = {
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
   "@sarj/no-restated-comment": "warn",
-  "@sarj/no-restated-jsdoc": "error",
+  "@sarj/no-restated-jsdoc": "warn",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",
   "@sarj/no-select-star": "error",
@@ -19907,7 +19914,7 @@ var STRICT_RULES = {
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
   "@sarj/no-restated-comment": "warn",
-  "@sarj/no-restated-jsdoc": "error",
+  "@sarj/no-restated-jsdoc": "warn",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",
   "@sarj/no-select-star": "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/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 ADVISORY_RULES: readonly ["@sarj/excessive-commentary", "@sarj/no-bespoke-api-case-conversion", "@sarj/no-restated-comment", "@sarj/no-restated-jsdoc", "@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: {
@@ -538,7 +538,7 @@ declare const RECOMMENDED_RULES: {
     readonly "@sarj/no-repeated-string-literal": "error";
     readonly "@sarj/no-router-refresh-polling": "error";
     readonly "@sarj/no-restated-comment": "warn";
-    readonly "@sarj/no-restated-jsdoc": "error";
+    readonly "@sarj/no-restated-jsdoc": "warn";
     readonly "@sarj/no-secret-in-log": "error";
     readonly "@sarj/no-server-env-in-client-component": "error";
     readonly "@sarj/no-select-star": "error";
@@ -821,7 +821,7 @@ declare const STRICT_RULES: {
     readonly "@sarj/no-repeated-string-literal": "error";
     readonly "@sarj/no-router-refresh-polling": "error";
     readonly "@sarj/no-restated-comment": "warn";
-    readonly "@sarj/no-restated-jsdoc": "error";
+    readonly "@sarj/no-restated-jsdoc": "warn";
     readonly "@sarj/no-secret-in-log": "error";
     readonly "@sarj/no-server-env-in-client-component": "error";
     readonly "@sarj/no-select-star": "error";
@@ -893,7 +893,7 @@ type FlatPreset = {
 declare const PLUGIN: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.17.6";
+        readonly version: "15.17.7";
     };
     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/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 ADVISORY_RULES: readonly ["@sarj/excessive-commentary", "@sarj/no-bespoke-api-case-conversion", "@sarj/no-restated-comment", "@sarj/no-restated-jsdoc", "@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: {
@@ -538,7 +538,7 @@ declare const RECOMMENDED_RULES: {
     readonly "@sarj/no-repeated-string-literal": "error";
     readonly "@sarj/no-router-refresh-polling": "error";
     readonly "@sarj/no-restated-comment": "warn";
-    readonly "@sarj/no-restated-jsdoc": "error";
+    readonly "@sarj/no-restated-jsdoc": "warn";
     readonly "@sarj/no-secret-in-log": "error";
     readonly "@sarj/no-server-env-in-client-component": "error";
     readonly "@sarj/no-select-star": "error";
@@ -821,7 +821,7 @@ declare const STRICT_RULES: {
     readonly "@sarj/no-repeated-string-literal": "error";
     readonly "@sarj/no-router-refresh-polling": "error";
     readonly "@sarj/no-restated-comment": "warn";
-    readonly "@sarj/no-restated-jsdoc": "error";
+    readonly "@sarj/no-restated-jsdoc": "warn";
     readonly "@sarj/no-secret-in-log": "error";
     readonly "@sarj/no-server-env-in-client-component": "error";
     readonly "@sarj/no-select-star": "error";
@@ -893,7 +893,7 @@ type FlatPreset = {
 declare const PLUGIN: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.17.6";
+        readonly version: "15.17.7";
     };
     readonly rules: {
         readonly "excessive-commentary": DocumentedRule<readonly [], "excessive">;

package/dist/index.js

@@ -6828,22 +6828,23 @@ var no_restated_comment_default = createRule({
 // src/rules/no-restated-jsdoc.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES29 } from "@typescript-eslint/utils";
 var NO_RESTATED_JSDOC_DOCUMENTATION = {
-  summary: "Flag a JSDoc block whose description and tags only re-spell the signature they document.",
+  summary: "Flag JSDoc prose that appears to repeat declaration names without adding behavioral information.",
   rationale: "Signature-only JSDoc duplicates type information and drifts without helping callers.",
   remediation: "Delete the block or document behavior, constraints, failures, or context the signature cannot express.",
   category: "maintainability",
   aliases: ["jsdoc-restates-signature"],
   autofix: "suggestion",
-  limitations: ["Generated files, detached blocks, unknown tags, empty blocks, and JSDoc with information absent from the signature are excluded."],
+  limitations: ["Generated files, detached blocks, intervening comments, unknown tags, explicit JSDoc type payloads, empty blocks, and JSDoc with information absent from the signature are excluded.", "Negation, conditions, constraints, sentinel values, numeric details, and quoted text conservatively preserve the block, even when a declaration name contains the same words."],
   examples: [
     { id: "behavioral-jsdoc", title: "Document behavior absent from the signature", outcome: "no-match", files: [{ path: "src/users.ts", source: "/** Get the user while bypassing the read replica. */\nexport function getUser(id: string) { return id; }" }], focusPath: "src/users.ts", expectedCount: 0, public: true },
-    { id: "signature-jsdoc", title: "Remove JSDoc that only repeats the signature", outcome: "match", files: [{ path: "src/users.ts", source: "/** Get the user by id. */\nexport function getUserById(id: string) { return id; }" }], focusPath: "src/users.ts", expectedCount: 1, public: true }
+    { id: "signature-jsdoc", title: "Remove JSDoc that only repeats the signature", outcome: "match", files: [{ path: "src/users.ts", source: "/** Get the user by id. */\nexport function getUserById(id: string) { return id; }" }], focusPath: "src/users.ts", expectedCount: 1, public: true },
+    { id: "negated-behavior", scenarioId: "negation", title: "Keep behavior even when its words resemble the declaration", outcome: "no-match", files: [{ path: "src/users.ts", source: "/** Does not cache the user. */\nexport function cacheUser(user: unknown) { return user; }" }], focusPath: "src/users.ts", expectedCount: 0, public: true },
+    { id: "repeated-behavior-name", scenarioId: "negation", title: "Review prose that merely repeats the declaration name", outcome: "match", files: [{ path: "src/users.ts", source: "/** Cache the user. */\nexport function cacheUser(user: unknown) { return user; }" }], focusPath: "src/users.ts", expectedCount: 1, public: true }
   ]
 };
 var MODELLED_TAGS = /* @__PURE__ */ new Set([
   "arg",
   "argument",
-  "async",
   "description",
   "param",
   "return",
@@ -6862,7 +6863,8 @@ var STOPWORDS2 = new Set(
    returns returning result optional required default true false null undefined
    string number boolean array list promise`.split(/\s+/)
 );
-var WORD_RE2 = /[A-Za-z]+/g;
+var WORD_RE2 = new RegExp("\\p{L}+", "gu");
+var BEHAVIORAL_PROSE_RE = /\b(?:not|no|never|if|when|unless|must|should|may|can|could|would|optional|required|default|true|false|null|undefined|before|after|until|once|again|only|always)\b|\d|["'`<>=+*/%&|!~^-]/i;
 function parseJsDoc(value) {
   const lines = value.replace(/^\*/, "").split("\n").map((line) => line.replace(/^\s*\*?\s?/, ""));
   const description = [];
@@ -6882,12 +6884,13 @@ function parseJsDoc(value) {
   return { description: description.join("\n").trim(), tags };
 }
 function covered(text, known) {
+  if (BEHAVIORAL_PROSE_RE.test(text)) return false;
   const stems = /* @__PURE__ */ new Set();
   for (const token of known) stems.add(stem(token));
   return proseTokens(text).every((word) => known.has(word) || stems.has(stem(word)));
 }
 function proseTokens(text) {
-  return (text.match(WORD_RE2) ?? []).map((word) => word.toLowerCase()).filter((word) => word.length > 1 && !STOPWORDS2.has(word));
+  return (text.match(WORD_RE2) ?? []).map((word) => word.toLowerCase()).filter((word) => !STOPWORDS2.has(word));
 }
 function declarationNames(node) {
   switch (node.type) {
@@ -6944,11 +6947,11 @@ var no_restated_jsdoc_default = createRule({
     type: "suggestion",
     hasSuggestions: true,
     docs: {
-      description: "Flag a JSDoc block whose description and tags only re-spell the signature they document."
+      description: "Flag JSDoc prose that appears to repeat declaration names without adding behavioral information."
     },
     schema: [],
     messages: {
-      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.",
+      restatesSignature: "JSDoc appears to repeat declaration names \u2014 consider removing repetition. Keep type contracts, constraints, failures, and rationale.",
       deleteBlock: "Delete the JSDoc block."
     }
   },
@@ -6971,8 +6974,9 @@ var no_restated_jsdoc_default = createRule({
           const tagNames = new Set(tags.map((tag) => tag.name));
           if ([...tagNames].some((name) => !MODELLED_TAGS.has(name))) continue;
           if (isProtected(describedText)) continue;
-          const token = sourceCode.getTokenAfter(comment, { includeComments: false });
+          const token = sourceCode.getTokenAfter(comment, { includeComments: true });
           if (token === null || token.loc.start.line !== comment.loc.end.line + 1) continue;
+          if (token.type === "Line" || token.type === "Block") continue;
           let node = sourceCode.getNodeByRangeIndex(token.range[0]);
           let declaration = null;
           while (node != null && node.type !== AST_NODE_TYPES29.Program) {
@@ -6983,6 +6987,8 @@ var no_restated_jsdoc_default = createRule({
           if (declaration === null) continue;
           const paramTags = tags.filter((tag) => PARAM_TAGS.has(tag.name));
           const returnTags = tags.filter((tag) => RETURN_TAGS.has(tag.name));
+          if ([...paramTags, ...returnTags].some((tag) => /^\s*\{/.test(tag.text))) continue;
+          if (paramTags.some((tag) => /^\s*(?:\[|[A-Za-z_$][\w$]*\.)/.test(tag.text))) continue;
           if (describedText.length === 0 && paramTags.length === 0 && returnTags.length === 0) {
             continue;
           }
@@ -19747,7 +19753,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.17.6"
+  version: "15.17.7"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {
@@ -19758,6 +19764,7 @@ var ADVISORY_RULES = [
   "@sarj/excessive-commentary",
   "@sarj/no-bespoke-api-case-conversion",
   "@sarj/no-restated-comment",
+  "@sarj/no-restated-jsdoc",
   "@sarj/prefer-millisecond-control-duration-schema",
   "@sarj/prefer-module-level-refined-schema",
   "@sarj/prefer-multi-value-zod-literal",
@@ -19806,7 +19813,7 @@ var RECOMMENDED_RULES = {
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
   "@sarj/no-restated-comment": "warn",
-  "@sarj/no-restated-jsdoc": "error",
+  "@sarj/no-restated-jsdoc": "warn",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",
   "@sarj/no-select-star": "error",
@@ -19902,7 +19909,7 @@ var STRICT_RULES = {
   "@sarj/no-repeated-string-literal": "error",
   "@sarj/no-router-refresh-polling": "error",
   "@sarj/no-restated-comment": "warn",
-  "@sarj/no-restated-jsdoc": "error",
+  "@sarj/no-restated-jsdoc": "warn",
   "@sarj/no-secret-in-log": "error",
   "@sarj/no-server-env-in-client-component": "error",
   "@sarj/no-select-star": "error",

package/package.json

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