@sarj/eslint-plugin 15.6.8 → 15.6.9

package/dist/index.cjs

@@ -4292,6 +4292,87 @@ var no_long_comment_default = createRule({
   }
 });
 
+// src/rules/no-vague-suppression-description.ts
+var DIRECTIVE_RE3 = /(?:eslint-(?:disable|disable-next-line|disable-line)|@ts-(?:expect-error|ignore))\b/iu;
+var DESCRIPTION_RE = /(?::|--)\s*(.+?)\s*$/u;
+var VAGUE_RE = /^(?:needed|required|intentional(?:ly)?|ignore(?:d)?|false positive|type error|typescript|to satisfy (?:the )?(?:linter|typescript|type checker))\.?$/iu;
+var noVagueSuppressionDescriptionDocumentation = {
+  summary: "Require suppression descriptions to name the concrete mismatch or invariant instead of a generic non-reason.",
+  rationale: "Generic phrases satisfy require-description mechanically while leaving reviewers unable to audit the risk or remove stale debt.",
+  remediation: "Name the exact type/runtime mismatch, external contract, or safety invariant that makes this suppression acceptable.",
+  category: "maintainability",
+  limitations: [
+    "Only ESLint disable comments and TypeScript expect-error/ignore directives are checked.",
+    "The rule uses a small anchored vocabulary and does not score prose quality generally.",
+    "Generated files and descriptions containing any concrete context are excluded."
+  ],
+  examples: [
+    {
+      id: "concrete-runtime-mismatch",
+      title: "Explain the concrete runtime contract",
+      outcome: "no-match",
+      files: [
+        {
+          path: "src/adapter.ts",
+          source: "// @ts-expect-error -- vendor types omit the runtime requestId field\nreturn response.requestId;"
+        }
+      ],
+      focusPath: "src/adapter.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "generic-suppression-reason",
+      title: "Reject a suppression with no auditable reason",
+      outcome: "match",
+      files: [
+        {
+          path: "src/adapter.ts",
+          source: "// @ts-expect-error -- false positive\nreturn response.requestId;"
+        }
+      ],
+      focusPath: "src/adapter.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
+var no_vague_suppression_description_default = createRule({
+  name: "no-vague-suppression-description",
+  documentation: noVagueSuppressionDescriptionDocumentation,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require suppression descriptions to name the concrete mismatch or invariant instead of a generic non-reason."
+    },
+    schema: [],
+    messages: {
+      vagueDescription: "Suppression description `{{description}}` does not explain why the suppressed diagnostic is safe here. Name the concrete type/runtime mismatch, external contract, or invariant."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    if (isGeneratedFile(context.filename, context.sourceCode.text)) {
+      return {};
+    }
+    return {
+      Program() {
+        for (const comment of context.sourceCode.getAllComments()) {
+          const text = comment.value.trim();
+          if (!DIRECTIVE_RE3.test(text)) continue;
+          const description = DESCRIPTION_RE.exec(text)?.[1]?.trim();
+          if (description === void 0 || !VAGUE_RE.test(description)) continue;
+          context.report({
+            loc: comment.loc,
+            messageId: "vagueDescription",
+            data: { description }
+          });
+        }
+      }
+    };
+  }
+});
+
 // src/rules/no-generic-single-export-module.ts
 var import_utils21 = require("@typescript-eslint/utils");
 var noGenericSingleExportModuleDocumentation = {
@@ -5431,7 +5512,7 @@ var no_repeated_string_literal_default = createRule({
 var import_utils28 = require("@typescript-eslint/utils");
 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;
+var DIRECTIVE_RE4 = /^(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;
 var CODEY_RE = /^[\w.$[\]'"]+\s*[:=]\s*\S|^[\w.$]+\s*\(|^(?:return|throw|await|import|export|const|let|var)\b.*[=()[\]{}]/;
 var BANNERISH_RE = /[=\-─-╿*#~_.]{3,}|^[A-Z0-9 _:-]+$/;
 var MODALITY_RE = /\b(?:can|could|should|shall|may|might|must|will|would|cannot)\b/i;
@@ -5530,7 +5611,7 @@ var no_restated_comment_default = createRule({
           }
           const body2 = comment.value.replace(/^\/*/, "").trim();
           if (body2.length === 0 || body2.endsWith("?")) continue;
-          if (DIRECTIVE_RE3.test(body2) || CODEY_RE.test(body2) || BANNERISH_RE.test(body2)) continue;
+          if (DIRECTIVE_RE4.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;
@@ -5578,7 +5659,7 @@ var MODELLED_TAGS = /* @__PURE__ */ new Set([
 ]);
 var PARAM_TAGS = /* @__PURE__ */ new Set(["arg", "argument", "param"]);
 var RETURN_TAGS = /* @__PURE__ */ new Set(["return", "returns"]);
-var DIRECTIVE_RE4 = /^\s*(?:eslint\b|eslint-|@ts-|prettier|biome-|c8\b|v8\b|istanbul\b|@vite|webpack|@jsx|@jest-environment|@vitest-environment|#__)/i;
+var DIRECTIVE_RE5 = /^\s*(?:eslint\b|eslint-|@ts-|prettier|biome-|c8\b|v8\b|istanbul\b|@vite|webpack|@jsx|@jest-environment|@vitest-environment|#__)/i;
 var STOPWORDS2 = new Set(
   `the a an of to for in on with and or as at by is are was be been being
    this that it its if whether when where which what will would can could should
@@ -5694,7 +5775,7 @@ var no_restated_jsdoc_default = createRule({
             description,
             ...tags.filter((tag) => tag.name === "description").map((tag) => tag.text)
           ].filter((text) => text.length > 0).join("\n");
-          if (DIRECTIVE_RE4.test(describedText)) continue;
+          if (DIRECTIVE_RE5.test(describedText)) continue;
           const tagNames = new Set(tags.map((tag) => tag.name));
           if ([...tagNames].some((name) => !MODELLED_TAGS.has(name))) continue;
           if (isProtected(describedText)) continue;
@@ -7656,10 +7737,10 @@ var STOPWORDS3 = /* @__PURE__ */ new Set([
   "we",
   "with"
 ]);
-var DIRECTIVE_RE5 = /^\s*(?:eslint\b|eslint-|sarj-noqa\b|@ts-|prettier|biome-|c8\b|v8\b|istanbul\b|todo\b|fixme\b|hack\b|xxx\b)/i;
+var DIRECTIVE_RE6 = /^\s*(?:eslint\b|eslint-|sarj-noqa\b|@ts-|prettier|biome-|c8\b|v8\b|istanbul\b|todo\b|fixme\b|hack\b|xxx\b)/i;
 var UNIT_NAME_SUFFIX_RE = /(?:_(?:NS|US|MS|S|SEC|SECS|SECOND|SECONDS|MIN|MINS|MINUTE|MINUTES|HOUR|HOURS|DAY|DAYS|BYTE|BYTES|KB|MB|GB|HZ|KHZ|MHZ|PX)|(?:Ns|Us|Ms|Sec|Secs|Second|Seconds|Min|Mins|Minute|Minutes|Hour|Hours|Day|Days|Byte|Bytes|Kb|Mb|Gb|Hz|Khz|Mhz|Px))$/u;
 function narratesValue(body2, code) {
-  if (body2.length === 0 || DIRECTIVE_RE5.test(body2) || hasExternalReference(body2)) return false;
+  if (body2.length === 0 || DIRECTIVE_RE6.test(body2) || hasExternalReference(body2)) return false;
   const codeNumbers = numbersIn(code);
   if (codeNumbers.size === 0) return false;
   const words2 = (body2.match(WORD_RE3) ?? []).map((word) => word.toLowerCase());
@@ -15305,6 +15386,7 @@ var rules = {
   "no-impossible-zod-literal-bounds": no_impossible_zod_literal_bounds_default,
   "no-log-only-catch": no_log_only_catch_default,
   "no-long-comment": no_long_comment_default,
+  "no-vague-suppression-description": no_vague_suppression_description_default,
   "no-generic-single-export-module": no_generic_single_export_module_default,
   "no-offset-pagination": no_offset_pagination_default,
   "no-positional-tuple-return": no_positional_tuple_return_default,
@@ -15358,14 +15440,14 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.6.8"
+  version: "15.6.9"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",
   "prefer-native-random-uuid",
   "prefer-shadcn-primitives"
 ];
-var advisoryRules = ["source-coupled-test"];
+var advisoryRules = ["no-vague-suppression-description", "source-coupled-test"];
 var recommendedRules = {
   "@sarj/duplicate-test-body": "error",
   "@sarj/enforce-file-structure": "error",
@@ -15381,6 +15463,7 @@ var recommendedRules = {
   "@sarj/no-impossible-zod-literal-bounds": "error",
   "@sarj/no-log-only-catch": "error",
   "@sarj/no-long-comment": "error",
+  "@sarj/no-vague-suppression-description": "warn",
   "@sarj/no-generic-single-export-module": "error",
   "@sarj/no-offset-pagination": "error",
   "@sarj/no-positional-tuple-return": "error",
@@ -15442,6 +15525,7 @@ var strictRules = {
   "@sarj/no-impossible-zod-literal-bounds": "error",
   "@sarj/no-log-only-catch": "error",
   "@sarj/no-long-comment": "error",
+  "@sarj/no-vague-suppression-description": "warn",
   "@sarj/no-generic-single-export-module": "error",
   "@sarj/no-offset-pagination": "error",
   "@sarj/no-positional-tuple-return": "error",

package/dist/index.d.cts

@@ -208,6 +208,7 @@ declare const rules: {
     readonly "no-impossible-zod-literal-bounds": DocumentedRule<readonly [], "impossibleBounds">;
     readonly "no-log-only-catch": DocumentedRule<readonly [LoggingOptions?], "noLogOnlyCatch" | "emptyCatch">;
     readonly "no-long-comment": DocumentedRule<readonly [], "tooLong">;
+    readonly "no-vague-suppression-description": DocumentedRule<readonly [], "vagueDescription">;
     readonly "no-generic-single-export-module": DocumentedRule<[], "genericSingleExport">;
     readonly "no-offset-pagination": DocumentedRule<readonly [], "noOffsetPagination">;
     readonly "no-positional-tuple-return": DocumentedRule<readonly [], "noPositionalTupleReturn">;
@@ -282,7 +283,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 ["source-coupled-test"];
+declare const advisoryRules: readonly ["no-vague-suppression-description", "source-coupled-test"];
 declare const recommendedRules: {
     readonly "@sarj/duplicate-test-body": "error";
     readonly "@sarj/enforce-file-structure": "error";
@@ -300,6 +301,7 @@ declare const recommendedRules: {
     readonly "@sarj/no-impossible-zod-literal-bounds": "error";
     readonly "@sarj/no-log-only-catch": "error";
     readonly "@sarj/no-long-comment": "error";
+    readonly "@sarj/no-vague-suppression-description": "warn";
     readonly "@sarj/no-generic-single-export-module": "error";
     readonly "@sarj/no-offset-pagination": "error";
     readonly "@sarj/no-positional-tuple-return": "error";
@@ -365,6 +367,7 @@ declare const strictRules: {
     readonly "@sarj/no-impossible-zod-literal-bounds": "error";
     readonly "@sarj/no-log-only-catch": "error";
     readonly "@sarj/no-long-comment": "error";
+    readonly "@sarj/no-vague-suppression-description": "warn";
     readonly "@sarj/no-generic-single-export-module": "error";
     readonly "@sarj/no-offset-pagination": "error";
     readonly "@sarj/no-positional-tuple-return": "error";
@@ -423,7 +426,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.6.8";
+        readonly version: "15.6.9";
     };
     readonly rules: {
         readonly "duplicate-test-body": DocumentedRule<readonly [], "duplicateTestBody">;
@@ -446,6 +449,7 @@ declare const plugin: {
         readonly "no-impossible-zod-literal-bounds": DocumentedRule<readonly [], "impossibleBounds">;
         readonly "no-log-only-catch": DocumentedRule<readonly [LoggingOptions?], "noLogOnlyCatch" | "emptyCatch">;
         readonly "no-long-comment": DocumentedRule<readonly [], "tooLong">;
+        readonly "no-vague-suppression-description": DocumentedRule<readonly [], "vagueDescription">;
         readonly "no-generic-single-export-module": DocumentedRule<[], "genericSingleExport">;
         readonly "no-offset-pagination": DocumentedRule<readonly [], "noOffsetPagination">;
         readonly "no-positional-tuple-return": DocumentedRule<readonly [], "noPositionalTupleReturn">;

package/dist/index.d.ts

@@ -208,6 +208,7 @@ declare const rules: {
     readonly "no-impossible-zod-literal-bounds": DocumentedRule<readonly [], "impossibleBounds">;
     readonly "no-log-only-catch": DocumentedRule<readonly [LoggingOptions?], "noLogOnlyCatch" | "emptyCatch">;
     readonly "no-long-comment": DocumentedRule<readonly [], "tooLong">;
+    readonly "no-vague-suppression-description": DocumentedRule<readonly [], "vagueDescription">;
     readonly "no-generic-single-export-module": DocumentedRule<[], "genericSingleExport">;
     readonly "no-offset-pagination": DocumentedRule<readonly [], "noOffsetPagination">;
     readonly "no-positional-tuple-return": DocumentedRule<readonly [], "noPositionalTupleReturn">;
@@ -282,7 +283,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 ["source-coupled-test"];
+declare const advisoryRules: readonly ["no-vague-suppression-description", "source-coupled-test"];
 declare const recommendedRules: {
     readonly "@sarj/duplicate-test-body": "error";
     readonly "@sarj/enforce-file-structure": "error";
@@ -300,6 +301,7 @@ declare const recommendedRules: {
     readonly "@sarj/no-impossible-zod-literal-bounds": "error";
     readonly "@sarj/no-log-only-catch": "error";
     readonly "@sarj/no-long-comment": "error";
+    readonly "@sarj/no-vague-suppression-description": "warn";
     readonly "@sarj/no-generic-single-export-module": "error";
     readonly "@sarj/no-offset-pagination": "error";
     readonly "@sarj/no-positional-tuple-return": "error";
@@ -365,6 +367,7 @@ declare const strictRules: {
     readonly "@sarj/no-impossible-zod-literal-bounds": "error";
     readonly "@sarj/no-log-only-catch": "error";
     readonly "@sarj/no-long-comment": "error";
+    readonly "@sarj/no-vague-suppression-description": "warn";
     readonly "@sarj/no-generic-single-export-module": "error";
     readonly "@sarj/no-offset-pagination": "error";
     readonly "@sarj/no-positional-tuple-return": "error";
@@ -423,7 +426,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.6.8";
+        readonly version: "15.6.9";
     };
     readonly rules: {
         readonly "duplicate-test-body": DocumentedRule<readonly [], "duplicateTestBody">;
@@ -446,6 +449,7 @@ declare const plugin: {
         readonly "no-impossible-zod-literal-bounds": DocumentedRule<readonly [], "impossibleBounds">;
         readonly "no-log-only-catch": DocumentedRule<readonly [LoggingOptions?], "noLogOnlyCatch" | "emptyCatch">;
         readonly "no-long-comment": DocumentedRule<readonly [], "tooLong">;
+        readonly "no-vague-suppression-description": DocumentedRule<readonly [], "vagueDescription">;
         readonly "no-generic-single-export-module": DocumentedRule<[], "genericSingleExport">;
         readonly "no-offset-pagination": DocumentedRule<readonly [], "noOffsetPagination">;
         readonly "no-positional-tuple-return": DocumentedRule<readonly [], "noPositionalTupleReturn">;

package/dist/index.js

@@ -4253,6 +4253,87 @@ var no_long_comment_default = createRule({
   }
 });
 
+// src/rules/no-vague-suppression-description.ts
+var DIRECTIVE_RE3 = /(?:eslint-(?:disable|disable-next-line|disable-line)|@ts-(?:expect-error|ignore))\b/iu;
+var DESCRIPTION_RE = /(?::|--)\s*(.+?)\s*$/u;
+var VAGUE_RE = /^(?:needed|required|intentional(?:ly)?|ignore(?:d)?|false positive|type error|typescript|to satisfy (?:the )?(?:linter|typescript|type checker))\.?$/iu;
+var noVagueSuppressionDescriptionDocumentation = {
+  summary: "Require suppression descriptions to name the concrete mismatch or invariant instead of a generic non-reason.",
+  rationale: "Generic phrases satisfy require-description mechanically while leaving reviewers unable to audit the risk or remove stale debt.",
+  remediation: "Name the exact type/runtime mismatch, external contract, or safety invariant that makes this suppression acceptable.",
+  category: "maintainability",
+  limitations: [
+    "Only ESLint disable comments and TypeScript expect-error/ignore directives are checked.",
+    "The rule uses a small anchored vocabulary and does not score prose quality generally.",
+    "Generated files and descriptions containing any concrete context are excluded."
+  ],
+  examples: [
+    {
+      id: "concrete-runtime-mismatch",
+      title: "Explain the concrete runtime contract",
+      outcome: "no-match",
+      files: [
+        {
+          path: "src/adapter.ts",
+          source: "// @ts-expect-error -- vendor types omit the runtime requestId field\nreturn response.requestId;"
+        }
+      ],
+      focusPath: "src/adapter.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "generic-suppression-reason",
+      title: "Reject a suppression with no auditable reason",
+      outcome: "match",
+      files: [
+        {
+          path: "src/adapter.ts",
+          source: "// @ts-expect-error -- false positive\nreturn response.requestId;"
+        }
+      ],
+      focusPath: "src/adapter.ts",
+      expectedCount: 1,
+      public: true
+    }
+  ]
+};
+var no_vague_suppression_description_default = createRule({
+  name: "no-vague-suppression-description",
+  documentation: noVagueSuppressionDescriptionDocumentation,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require suppression descriptions to name the concrete mismatch or invariant instead of a generic non-reason."
+    },
+    schema: [],
+    messages: {
+      vagueDescription: "Suppression description `{{description}}` does not explain why the suppressed diagnostic is safe here. Name the concrete type/runtime mismatch, external contract, or invariant."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    if (isGeneratedFile(context.filename, context.sourceCode.text)) {
+      return {};
+    }
+    return {
+      Program() {
+        for (const comment of context.sourceCode.getAllComments()) {
+          const text = comment.value.trim();
+          if (!DIRECTIVE_RE3.test(text)) continue;
+          const description = DESCRIPTION_RE.exec(text)?.[1]?.trim();
+          if (description === void 0 || !VAGUE_RE.test(description)) continue;
+          context.report({
+            loc: comment.loc,
+            messageId: "vagueDescription",
+            data: { description }
+          });
+        }
+      }
+    };
+  }
+});
+
 // src/rules/no-generic-single-export-module.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES16, ASTUtils as ASTUtils4 } from "@typescript-eslint/utils";
 var noGenericSingleExportModuleDocumentation = {
@@ -5392,7 +5473,7 @@ var no_repeated_string_literal_default = createRule({
 import { AST_NODE_TYPES as AST_NODE_TYPES21 } from "@typescript-eslint/utils";
 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;
+var DIRECTIVE_RE4 = /^(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;
 var CODEY_RE = /^[\w.$[\]'"]+\s*[:=]\s*\S|^[\w.$]+\s*\(|^(?:return|throw|await|import|export|const|let|var)\b.*[=()[\]{}]/;
 var BANNERISH_RE = /[=\-─-╿*#~_.]{3,}|^[A-Z0-9 _:-]+$/;
 var MODALITY_RE = /\b(?:can|could|should|shall|may|might|must|will|would|cannot)\b/i;
@@ -5491,7 +5572,7 @@ var no_restated_comment_default = createRule({
           }
           const body2 = comment.value.replace(/^\/*/, "").trim();
           if (body2.length === 0 || body2.endsWith("?")) continue;
-          if (DIRECTIVE_RE3.test(body2) || CODEY_RE.test(body2) || BANNERISH_RE.test(body2)) continue;
+          if (DIRECTIVE_RE4.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;
@@ -5539,7 +5620,7 @@ var MODELLED_TAGS = /* @__PURE__ */ new Set([
 ]);
 var PARAM_TAGS = /* @__PURE__ */ new Set(["arg", "argument", "param"]);
 var RETURN_TAGS = /* @__PURE__ */ new Set(["return", "returns"]);
-var DIRECTIVE_RE4 = /^\s*(?:eslint\b|eslint-|@ts-|prettier|biome-|c8\b|v8\b|istanbul\b|@vite|webpack|@jsx|@jest-environment|@vitest-environment|#__)/i;
+var DIRECTIVE_RE5 = /^\s*(?:eslint\b|eslint-|@ts-|prettier|biome-|c8\b|v8\b|istanbul\b|@vite|webpack|@jsx|@jest-environment|@vitest-environment|#__)/i;
 var STOPWORDS2 = new Set(
   `the a an of to for in on with and or as at by is are was be been being
    this that it its if whether when where which what will would can could should
@@ -5655,7 +5736,7 @@ var no_restated_jsdoc_default = createRule({
             description,
             ...tags.filter((tag) => tag.name === "description").map((tag) => tag.text)
           ].filter((text) => text.length > 0).join("\n");
-          if (DIRECTIVE_RE4.test(describedText)) continue;
+          if (DIRECTIVE_RE5.test(describedText)) continue;
           const tagNames = new Set(tags.map((tag) => tag.name));
           if ([...tagNames].some((name) => !MODELLED_TAGS.has(name))) continue;
           if (isProtected(describedText)) continue;
@@ -7617,10 +7698,10 @@ var STOPWORDS3 = /* @__PURE__ */ new Set([
   "we",
   "with"
 ]);
-var DIRECTIVE_RE5 = /^\s*(?:eslint\b|eslint-|sarj-noqa\b|@ts-|prettier|biome-|c8\b|v8\b|istanbul\b|todo\b|fixme\b|hack\b|xxx\b)/i;
+var DIRECTIVE_RE6 = /^\s*(?:eslint\b|eslint-|sarj-noqa\b|@ts-|prettier|biome-|c8\b|v8\b|istanbul\b|todo\b|fixme\b|hack\b|xxx\b)/i;
 var UNIT_NAME_SUFFIX_RE = /(?:_(?:NS|US|MS|S|SEC|SECS|SECOND|SECONDS|MIN|MINS|MINUTE|MINUTES|HOUR|HOURS|DAY|DAYS|BYTE|BYTES|KB|MB|GB|HZ|KHZ|MHZ|PX)|(?:Ns|Us|Ms|Sec|Secs|Second|Seconds|Min|Mins|Minute|Minutes|Hour|Hours|Day|Days|Byte|Bytes|Kb|Mb|Gb|Hz|Khz|Mhz|Px))$/u;
 function narratesValue(body2, code) {
-  if (body2.length === 0 || DIRECTIVE_RE5.test(body2) || hasExternalReference(body2)) return false;
+  if (body2.length === 0 || DIRECTIVE_RE6.test(body2) || hasExternalReference(body2)) return false;
   const codeNumbers = numbersIn(code);
   if (codeNumbers.size === 0) return false;
   const words2 = (body2.match(WORD_RE3) ?? []).map((word) => word.toLowerCase());
@@ -15285,6 +15366,7 @@ var rules = {
   "no-impossible-zod-literal-bounds": no_impossible_zod_literal_bounds_default,
   "no-log-only-catch": no_log_only_catch_default,
   "no-long-comment": no_long_comment_default,
+  "no-vague-suppression-description": no_vague_suppression_description_default,
   "no-generic-single-export-module": no_generic_single_export_module_default,
   "no-offset-pagination": no_offset_pagination_default,
   "no-positional-tuple-return": no_positional_tuple_return_default,
@@ -15338,14 +15420,14 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.6.8"
+  version: "15.6.9"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",
   "prefer-native-random-uuid",
   "prefer-shadcn-primitives"
 ];
-var advisoryRules = ["source-coupled-test"];
+var advisoryRules = ["no-vague-suppression-description", "source-coupled-test"];
 var recommendedRules = {
   "@sarj/duplicate-test-body": "error",
   "@sarj/enforce-file-structure": "error",
@@ -15361,6 +15443,7 @@ var recommendedRules = {
   "@sarj/no-impossible-zod-literal-bounds": "error",
   "@sarj/no-log-only-catch": "error",
   "@sarj/no-long-comment": "error",
+  "@sarj/no-vague-suppression-description": "warn",
   "@sarj/no-generic-single-export-module": "error",
   "@sarj/no-offset-pagination": "error",
   "@sarj/no-positional-tuple-return": "error",
@@ -15422,6 +15505,7 @@ var strictRules = {
   "@sarj/no-impossible-zod-literal-bounds": "error",
   "@sarj/no-log-only-catch": "error",
   "@sarj/no-long-comment": "error",
+  "@sarj/no-vague-suppression-description": "warn",
   "@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.6.8",
+  "version": "15.6.9",
   "packageManager": "npm@12.0.2",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",