@sarj/eslint-plugin 9.17.0 → 10.0.0

package/README.md

@@ -26,7 +26,7 @@ import sarj from "@sarj/eslint-plugin";
 export default [sarj.configs.recommended];
 ```
 
-67 rules. Each source under `src/rules/` states one concise claim and links to
+66 rules. Each source under `src/rules/` states one concise claim and links to
 its paired tests. The definition and named test cases are the complete rule
 specification, and `meta.docs.url` points directly to those executable examples.
 

package/dist/index.cjs

@@ -928,6 +928,8 @@ var CODE_TAIL_RE = /[;{}()]\s*$|=>\s*$|,\s*$/;
 var ASSIGN_RE = /^[A-Za-z_$][\w.$[\]]*\s*(?:=(?![=>])|\+=|-=|\*=)\s*\S.*[;)}\]]\s*$/;
 var CALL_RE = /^[A-Za-z_$][\w.$]*\([^)]*\)\s*;?\s*$/;
 var ASSERTION_CODE_RE = /^(?:await\s+)?(?:expect(?:TypeOf)?|assert(?:\.\w+)?)\s*\(/;
+var HTTP_CONTRACT_RE = /\b(?:GET|HEAD|OPTIONS|PATCH|POST|PUT|DELETE)\s+(?:https?:\/\/|\/|\{[A-Za-z_$])/;
+var PROSE_ASSIGNMENT_RE = /^[A-Za-z_$][\w.$[\]]*\s*=\s*[A-Za-z][A-Za-z '-]{2,}\s+\((?:how|what|when|where|which|who|why)\b[^)]*\)[.!]?$/i;
 var PSEUDOCODE_RE = /%\w+%|\[opt\]|(?:^|\s)<[A-Za-z]\w*>|…|\.\.\./;
 function isBanner(text) {
   const t = text.trim();
@@ -946,6 +948,7 @@ function isRegionMarker(text) {
 function looksLikeCode(text, allowCall = true) {
   const t = text.trim();
   if (!t) return false;
+  if (PROSE_ASSIGNMENT_RE.test(t)) return false;
   if (CODE_KEYWORD_RE.test(t) && CODE_TAIL_RE.test(t)) return true;
   if (ASSIGN_RE.test(t)) return true;
   if (ASSERTION_CODE_RE.test(t)) return true;
@@ -1084,6 +1087,21 @@ function runCitesAReference(comments, index) {
 function areAdjacentLineComments(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 lineRunStart(comments, index) {
+  let start = index;
+  while (start > 0 && areAdjacentLineComments(comments[start - 1], comments[start])) {
+    start -= 1;
+  }
+  return start;
+}
+function runDocumentsHttpContract(comments, index) {
+  const start = lineRunStart(comments, index);
+  for (let i = start; i < comments.length; i++) {
+    if (i > start && !areAdjacentLineComments(comments[i - 1], comments[i])) break;
+    if (HTTP_CONTRACT_RE.test(stripCommentMarker(comments[i]?.value ?? ""))) return true;
+  }
+  return false;
+}
 function isInsideCommentRun(comments, index) {
   const comment = comments[index];
   return areAdjacentLineComments(comments[index - 1], comment) || areAdjacentLineComments(comment, comments[index + 1]);
@@ -1119,7 +1137,7 @@ var no_comment_cruft_default = createRule({
     schema: [],
     messages: {
       commentedOutCode: "Commented-out code \u2014 delete it; git history remembers.",
-      sectionBanner: "Section-banner / region comment \u2014 structure code with functions, not ASCII rules.",
+      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.",
@@ -1142,6 +1160,17 @@ var no_comment_cruft_default = createRule({
     function isJsDoc(comment) {
       return comment.type === "Block" && /^\*/.test(comment.value);
     }
+    function isJsxOnlyComment(comment) {
+      for (let node = sourceCode.getNodeByRangeIndex(
+        comment.range[0]
+      ); node != null; node = node.parent) {
+        if (node.type === import_utils7.AST_NODE_TYPES.JSXExpressionContainer) {
+          return node.expression.type === import_utils7.AST_NODE_TYPES.JSXEmptyExpression;
+        }
+        if (node.type === import_utils7.AST_NODE_TYPES.Program) return false;
+      }
+      return false;
+    }
     function findCommentWalls(comments) {
       const attached = /* @__PURE__ */ new Map();
       for (const comment of comments) {
@@ -1223,6 +1252,8 @@ var no_comment_cruft_default = createRule({
         const enumerated = comments.filter(
           (c) => c.type === "Line" && ENUMERATION_RE.test(stripCommentMarker(c.value))
         );
+        const reportedBannerRuns = /* @__PURE__ */ new Set();
+        const reportedCodeRuns = /* @__PURE__ */ new Set();
         for (let i = 0; i < comments.length; i++) {
           const comment = comments[i];
           if (comment === void 0) continue;
@@ -1242,9 +1273,14 @@ var no_comment_cruft_default = createRule({
             }
             continue;
           }
-          if (!isStandalone(comment)) continue;
           if (LICENSE_RE.test(comment.value)) continue;
           const texts = comment.value.split("\n").map(stripCommentMarker).filter((l) => l.length > 0 && !isDirective(l));
+          if (!isStandalone(comment)) {
+            if (isJsxOnlyComment(comment) && texts.some(isBanner)) {
+              context.report({ node: comment, messageId: "sectionBanner" });
+            }
+            continue;
+          }
           const firstText = texts[0];
           if (firstText !== void 0 && /^(?:todo|fixme)\b/i.test(firstText)) {
             if (!runCitesAReference(comments, i)) {
@@ -1259,16 +1295,23 @@ var no_comment_cruft_default = createRule({
             context.report({ node: comment, messageId: "placeholderImplementation" });
             continue;
           }
+          const runStart = lineRunStart(comments, i);
           if (texts.some(isBanner)) {
-            context.report({ node: comment, messageId: "sectionBanner" });
+            if (!reportedBannerRuns.has(runStart)) {
+              context.report({ node: comment, messageId: "sectionBanner" });
+              reportedBannerRuns.add(runStart);
+            }
             continue;
           }
           const prev = comments[i - 1];
           const precedingProse = prev !== void 0 && prev.type === "Line" && prev.loc.end.line === comment.loc.start.line - 1 && isProse(stripCommentMarker(prev.value));
           const container = sourceCode.getNodeByRangeIndex(comment.range[0]);
           const inTypeMembers = container !== null && TYPE_MEMBER_CONTAINERS.has(container.type);
-          if (hasCommentedOutCode(texts, precedingProse, !inTypeMembers) && !hasIllustrationLeadInAbove(comments, i)) {
-            context.report({ node: comment, messageId: "commentedOutCode" });
+          if (hasCommentedOutCode(texts, precedingProse, !inTypeMembers) && !hasIllustrationLeadInAbove(comments, i) && !runDocumentsHttpContract(comments, i)) {
+            if (!reportedCodeRuns.has(runStart)) {
+              context.report({ node: comment, messageId: "commentedOutCode" });
+              reportedCodeRuns.add(runStart);
+            }
             continue;
           }
           if (comment.type === "Line" && texts.length === 1) {
@@ -3335,6 +3378,8 @@ 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 BOUNDARY_RE = /(?<=[.!?])["'`)\]]*\s+(?=[A-Z0-9`])/;
 var BULLET_RE = /^\s*(?:[-*+] |\d+[.)] )/;
+var HEADING_RE = /^[A-Za-z][A-Za-z ]+:$/;
+var TECHNICAL_ANCHOR_RE = /https?:\/\/|`[^`\n]+`|:[a-z][a-z0-9_-]*:|(["'])[^"'\n]+\1|\d|\b[a-z][a-z0-9]*[A-Z][A-Za-z0-9]*\b|\b[A-Za-z][A-Za-z0-9]*_[A-Za-z0-9_]+\b|(?:^|\s)(?:[\w.-]+\/)+[\w.-]+|\b[\w.-]+\.(?:py|pyi|js|jsx|ts|tsx|json|ya?ml|toml|csv|parquet|md)\b|->|=>|==|!=|<=|>=|\|/mu;
 function body(comment) {
   return comment.value.replace(/^\*/, "").split("\n").map((line) => line.replace(/^\s*\*?\s?/, "")).join("\n").trim();
 }
@@ -3354,6 +3399,17 @@ function sentenceUnits(text) {
   if (prose.length > 0) units += prose.join(" ").split(BOUNDARY_RE).length;
   return units;
 }
+function hasDocumentationStructure(text) {
+  const paragraphs = text.split(/\n\s*\n/u).filter((part) => part.trim().length > 0);
+  if (paragraphs.length >= 2) return true;
+  return text.split("\n").some((raw) => {
+    const line = raw.trim().replace(/^\*\s?/u, "").trim();
+    return line.length > 0 && (BULLET_RE.test(line) || HEADING_RE.test(line) || /(?:->|=>|\|)/u.test(line));
+  });
+}
+function hasTechnicalAnchor(text) {
+  return TECHNICAL_ANCHOR_RE.test(text);
+}
 function proseGroups(filename, sourceCode, includeValueTags = false) {
   if (isGeneratedFile(filename, sourceCode.text) || isStoryFile(filename) || isScriptFile(filename) || isTestFile(filename)) return [];
   const groups = [];
@@ -3420,10 +3476,8 @@ function typedFunction(node) {
 }
 
 // src/rules/no-long-comment.ts
-var LIST_ITEM_RE = /^\s*(?:[-*+] |\d+[.)] )/m;
-var DURABLE_RATIONALE_RE = /\b(?:adapter|algorithm|atomic|auth(?:entication|orization)?|backpressure|billing|cache|callback|cluster|commit|compatib|concurr|contract|credential|cross-node|csrf|definite-assignment|error|exception|external|failure|fallback|handshake|interop|invalid|invariant|legacy|migration|navigation|parse[rsd]?|payload|privacy|protocol|race|reject|reload|renderer|resume|retry|runtime|schema|security|selector|sentinel|serializ|socket|stage|third-party|token|transaction|upstream|wire|workaround)\b|\b(?:must|required|prevent|avoid)\b/iu;
-var VENDORED_BASENAME_RE = /(?:^|\/)(?:jquery(?:-ui)?(?:[.-]\d[^/]*)?|lodash(?:\.min)?|bootstrap(?:\.min)?|react(?:\.min)?)\.js$/iu;
 var EXCESSIVE_SENTENCE_COUNT = 8;
+var VERSIONED_DEPENDENCY_TREE_RE = /(?:^|\/)lib\/[^/]*-?v?\d+\.\d+(?:\.\d+)?[^/]*\//iu;
 function documentsTypeOrMember(sourceCode, comment) {
   const token = sourceCode.getTokenAfter(comment, { includeComments: false });
   if (token === null || token.loc.start.line !== comment.loc.end.line + 1) return false;
@@ -3447,11 +3501,11 @@ var no_long_comment_default = createRule({
   defaultOptions: [],
   create(context) {
     const normalizedFilename = context.filename.replaceAll("\\", "/");
-    if (VENDORED_BASENAME_RE.test(normalizedFilename)) return {};
+    if (VERSIONED_DEPENDENCY_TREE_RE.test(normalizedFilename)) return {};
     return {
       Program() {
         for (const group of proseGroups(context.filename, context.sourceCode)) {
-          if (group.comment.type !== "Block" || group.hasTypedTags || LIST_ITEM_RE.test(group.text) || DURABLE_RATIONALE_RE.test(group.text) || documentsTypedFunction(context.sourceCode, group.comment) || documentsTypeOrMember(context.sourceCode, group.comment) || sentenceUnits(group.text) < EXCESSIVE_SENTENCE_COUNT) continue;
+          if (group.comment.type !== "Block" || !group.comment.value.startsWith("*") || group.hasTypedTags || hasDocumentationStructure(group.text) || hasTechnicalAnchor(group.text) || documentsTypedFunction(context.sourceCode, group.comment) || documentsTypeOrMember(context.sourceCode, group.comment) || sentenceUnits(group.text) < EXCESSIVE_SENTENCE_COUNT) continue;
           context.report({ node: group.comment, messageId: "tooLong" });
         }
       }
@@ -9748,31 +9802,6 @@ var prefer_server_actions_default = createRule({
   }
 });
 
-// src/rules/prefer-single-sentence-comment.ts
-var prefer_single_sentence_comment_default = createRule({
-  name: "prefer-single-sentence-comment",
-  meta: {
-    type: "suggestion",
-    docs: { description: "Prefer one sentence and self-documenting code over a two-sentence comment." },
-    schema: [],
-    messages: {
-      preferOneSentence: "Two-sentence comment \u2014 prefer one sentence and self-documenting code."
-    }
-  },
-  defaultOptions: [],
-  create(context) {
-    return {
-      Program() {
-        for (const group of proseGroups(context.filename, context.sourceCode)) {
-          if (!group.hasTypedTags && sentenceUnits(group.text) === 2) {
-            context.report({ node: group.comment, messageId: "preferOneSentence" });
-          }
-        }
-      }
-    };
-  }
-});
-
 // src/rules/prefer-string-literal-union.ts
 var import_utils62 = require("@typescript-eslint/utils");
 var ts2 = __toESM(require("typescript"), 1);
@@ -12260,6 +12289,10 @@ var retiredRules = {
     removedIn: "3.0.0",
     reason: "Delete the retired entry; application-profile consumers can separately adopt `@sarj/prefer-shadcn-primitives`."
   },
+  "prefer-single-sentence-comment": {
+    removedIn: "10.0.0",
+    reason: "Delete the config entry and suppressions; use the narrower no-comment-cruft, no-restated-comment, and no-long-comment rules."
+  },
   "primary-export-file-name": {
     removedIn: "4.0.0",
     reason: "Delete the config entry and suppressions; there is no replacement."
@@ -12334,7 +12367,6 @@ var rules = {
   "prefer-schema-for-api-payload": prefer_schema_for_api_payload_default,
   "prefer-semantic-colors": prefer_semantic_colors_default,
   "prefer-server-actions": prefer_server_actions_default,
-  "prefer-single-sentence-comment": prefer_single_sentence_comment_default,
   "prefer-string-literal-union": prefer_string_literal_union_default,
   "prefer-whole-object-assertion": prefer_whole_object_assertion_default,
   "prefer-zod-enum": prefer_zod_enum_default,
@@ -12350,7 +12382,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "9.17.0"
+  version: "10.0.0"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",
@@ -12405,7 +12437,6 @@ var recommendedRules = {
   "@sarj/prefer-schema-for-api-payload": "warn",
   "@sarj/prefer-semantic-colors": ["warn", { requireSemanticTokens: true }],
   "@sarj/prefer-server-actions": "warn",
-  "@sarj/prefer-single-sentence-comment": "warn",
   "@sarj/prefer-string-literal-union": "warn",
   "@sarj/prefer-whole-object-assertion": "warn",
   "@sarj/prefer-zod-enum": "warn",
@@ -12471,7 +12502,6 @@ var strictRules = {
   "@sarj/prefer-schema-for-api-payload": "error",
   "@sarj/prefer-semantic-colors": ["error", { requireSemanticTokens: true }],
   "@sarj/prefer-server-actions": "error",
-  "@sarj/prefer-single-sentence-comment": "warn",
   "@sarj/prefer-string-literal-union": "error",
   "@sarj/prefer-whole-object-assertion": "error",
   "@sarj/prefer-zod-enum": "error",

package/dist/index.d.cts

@@ -267,9 +267,6 @@ declare const rules: {
     readonly "prefer-server-actions": _typescript_eslint_utils_ts_eslint.RuleModule<"preferServerAction", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
-    readonly "prefer-single-sentence-comment": _typescript_eslint_utils_ts_eslint.RuleModule<"preferOneSentence", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
-        name: string;
-    };
     readonly "prefer-string-literal-union": _typescript_eslint_utils_ts_eslint.RuleModule<"bareChoiceField" | "comparisonCluster", readonly [{
         ignoreFields?: readonly string[];
     }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -368,7 +365,6 @@ declare const recommendedRules: {
         readonly requireSemanticTokens: true;
     }];
     readonly "@sarj/prefer-server-actions": "warn";
-    readonly "@sarj/prefer-single-sentence-comment": "warn";
     readonly "@sarj/prefer-string-literal-union": "warn";
     readonly "@sarj/prefer-whole-object-assertion": "warn";
     readonly "@sarj/prefer-zod-enum": "warn";
@@ -436,7 +432,6 @@ declare const strictRules: {
         readonly requireSemanticTokens: true;
     }];
     readonly "@sarj/prefer-server-actions": "error";
-    readonly "@sarj/prefer-single-sentence-comment": "warn";
     readonly "@sarj/prefer-string-literal-union": "error";
     readonly "@sarj/prefer-whole-object-assertion": "error";
     readonly "@sarj/prefer-zod-enum": "error";
@@ -458,7 +453,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "9.17.0";
+        readonly version: "10.0.0";
     };
     readonly rules: {
         readonly "duplicate-test-body": _typescript_eslint_utils_ts_eslint.RuleModule<"duplicateTestBody", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -640,9 +635,6 @@ declare const plugin: {
         readonly "prefer-server-actions": _typescript_eslint_utils_ts_eslint.RuleModule<"preferServerAction", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
-        readonly "prefer-single-sentence-comment": _typescript_eslint_utils_ts_eslint.RuleModule<"preferOneSentence", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
-            name: string;
-        };
         readonly "prefer-string-literal-union": _typescript_eslint_utils_ts_eslint.RuleModule<"bareChoiceField" | "comparisonCluster", readonly [{
             ignoreFields?: readonly string[];
         }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {

package/dist/index.d.ts

@@ -267,9 +267,6 @@ declare const rules: {
     readonly "prefer-server-actions": _typescript_eslint_utils_ts_eslint.RuleModule<"preferServerAction", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
-    readonly "prefer-single-sentence-comment": _typescript_eslint_utils_ts_eslint.RuleModule<"preferOneSentence", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
-        name: string;
-    };
     readonly "prefer-string-literal-union": _typescript_eslint_utils_ts_eslint.RuleModule<"bareChoiceField" | "comparisonCluster", readonly [{
         ignoreFields?: readonly string[];
     }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -368,7 +365,6 @@ declare const recommendedRules: {
         readonly requireSemanticTokens: true;
     }];
     readonly "@sarj/prefer-server-actions": "warn";
-    readonly "@sarj/prefer-single-sentence-comment": "warn";
     readonly "@sarj/prefer-string-literal-union": "warn";
     readonly "@sarj/prefer-whole-object-assertion": "warn";
     readonly "@sarj/prefer-zod-enum": "warn";
@@ -436,7 +432,6 @@ declare const strictRules: {
         readonly requireSemanticTokens: true;
     }];
     readonly "@sarj/prefer-server-actions": "error";
-    readonly "@sarj/prefer-single-sentence-comment": "warn";
     readonly "@sarj/prefer-string-literal-union": "error";
     readonly "@sarj/prefer-whole-object-assertion": "error";
     readonly "@sarj/prefer-zod-enum": "error";
@@ -458,7 +453,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "9.17.0";
+        readonly version: "10.0.0";
     };
     readonly rules: {
         readonly "duplicate-test-body": _typescript_eslint_utils_ts_eslint.RuleModule<"duplicateTestBody", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -640,9 +635,6 @@ declare const plugin: {
         readonly "prefer-server-actions": _typescript_eslint_utils_ts_eslint.RuleModule<"preferServerAction", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
-        readonly "prefer-single-sentence-comment": _typescript_eslint_utils_ts_eslint.RuleModule<"preferOneSentence", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
-            name: string;
-        };
         readonly "prefer-string-literal-union": _typescript_eslint_utils_ts_eslint.RuleModule<"bareChoiceField" | "comparisonCluster", readonly [{
             ignoreFields?: readonly string[];
         }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {

package/dist/index.js

@@ -886,6 +886,8 @@ var CODE_TAIL_RE = /[;{}()]\s*$|=>\s*$|,\s*$/;
 var ASSIGN_RE = /^[A-Za-z_$][\w.$[\]]*\s*(?:=(?![=>])|\+=|-=|\*=)\s*\S.*[;)}\]]\s*$/;
 var CALL_RE = /^[A-Za-z_$][\w.$]*\([^)]*\)\s*;?\s*$/;
 var ASSERTION_CODE_RE = /^(?:await\s+)?(?:expect(?:TypeOf)?|assert(?:\.\w+)?)\s*\(/;
+var HTTP_CONTRACT_RE = /\b(?:GET|HEAD|OPTIONS|PATCH|POST|PUT|DELETE)\s+(?:https?:\/\/|\/|\{[A-Za-z_$])/;
+var PROSE_ASSIGNMENT_RE = /^[A-Za-z_$][\w.$[\]]*\s*=\s*[A-Za-z][A-Za-z '-]{2,}\s+\((?:how|what|when|where|which|who|why)\b[^)]*\)[.!]?$/i;
 var PSEUDOCODE_RE = /%\w+%|\[opt\]|(?:^|\s)<[A-Za-z]\w*>|…|\.\.\./;
 function isBanner(text) {
   const t = text.trim();
@@ -904,6 +906,7 @@ function isRegionMarker(text) {
 function looksLikeCode(text, allowCall = true) {
   const t = text.trim();
   if (!t) return false;
+  if (PROSE_ASSIGNMENT_RE.test(t)) return false;
   if (CODE_KEYWORD_RE.test(t) && CODE_TAIL_RE.test(t)) return true;
   if (ASSIGN_RE.test(t)) return true;
   if (ASSERTION_CODE_RE.test(t)) return true;
@@ -1042,6 +1045,21 @@ function runCitesAReference(comments, index) {
 function areAdjacentLineComments(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 lineRunStart(comments, index) {
+  let start = index;
+  while (start > 0 && areAdjacentLineComments(comments[start - 1], comments[start])) {
+    start -= 1;
+  }
+  return start;
+}
+function runDocumentsHttpContract(comments, index) {
+  const start = lineRunStart(comments, index);
+  for (let i = start; i < comments.length; i++) {
+    if (i > start && !areAdjacentLineComments(comments[i - 1], comments[i])) break;
+    if (HTTP_CONTRACT_RE.test(stripCommentMarker(comments[i]?.value ?? ""))) return true;
+  }
+  return false;
+}
 function isInsideCommentRun(comments, index) {
   const comment = comments[index];
   return areAdjacentLineComments(comments[index - 1], comment) || areAdjacentLineComments(comment, comments[index + 1]);
@@ -1077,7 +1095,7 @@ var no_comment_cruft_default = createRule({
     schema: [],
     messages: {
       commentedOutCode: "Commented-out code \u2014 delete it; git history remembers.",
-      sectionBanner: "Section-banner / region comment \u2014 structure code with functions, not ASCII rules.",
+      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.",
@@ -1100,6 +1118,17 @@ var no_comment_cruft_default = createRule({
     function isJsDoc(comment) {
       return comment.type === "Block" && /^\*/.test(comment.value);
     }
+    function isJsxOnlyComment(comment) {
+      for (let node = sourceCode.getNodeByRangeIndex(
+        comment.range[0]
+      ); node != null; node = node.parent) {
+        if (node.type === AST_NODE_TYPES6.JSXExpressionContainer) {
+          return node.expression.type === AST_NODE_TYPES6.JSXEmptyExpression;
+        }
+        if (node.type === AST_NODE_TYPES6.Program) return false;
+      }
+      return false;
+    }
     function findCommentWalls(comments) {
       const attached = /* @__PURE__ */ new Map();
       for (const comment of comments) {
@@ -1181,6 +1210,8 @@ var no_comment_cruft_default = createRule({
         const enumerated = comments.filter(
           (c) => c.type === "Line" && ENUMERATION_RE.test(stripCommentMarker(c.value))
         );
+        const reportedBannerRuns = /* @__PURE__ */ new Set();
+        const reportedCodeRuns = /* @__PURE__ */ new Set();
         for (let i = 0; i < comments.length; i++) {
           const comment = comments[i];
           if (comment === void 0) continue;
@@ -1200,9 +1231,14 @@ var no_comment_cruft_default = createRule({
             }
             continue;
           }
-          if (!isStandalone(comment)) continue;
           if (LICENSE_RE.test(comment.value)) continue;
           const texts = comment.value.split("\n").map(stripCommentMarker).filter((l) => l.length > 0 && !isDirective(l));
+          if (!isStandalone(comment)) {
+            if (isJsxOnlyComment(comment) && texts.some(isBanner)) {
+              context.report({ node: comment, messageId: "sectionBanner" });
+            }
+            continue;
+          }
           const firstText = texts[0];
           if (firstText !== void 0 && /^(?:todo|fixme)\b/i.test(firstText)) {
             if (!runCitesAReference(comments, i)) {
@@ -1217,16 +1253,23 @@ var no_comment_cruft_default = createRule({
             context.report({ node: comment, messageId: "placeholderImplementation" });
             continue;
           }
+          const runStart = lineRunStart(comments, i);
           if (texts.some(isBanner)) {
-            context.report({ node: comment, messageId: "sectionBanner" });
+            if (!reportedBannerRuns.has(runStart)) {
+              context.report({ node: comment, messageId: "sectionBanner" });
+              reportedBannerRuns.add(runStart);
+            }
             continue;
           }
           const prev = comments[i - 1];
           const precedingProse = prev !== void 0 && prev.type === "Line" && prev.loc.end.line === comment.loc.start.line - 1 && isProse(stripCommentMarker(prev.value));
           const container = sourceCode.getNodeByRangeIndex(comment.range[0]);
           const inTypeMembers = container !== null && TYPE_MEMBER_CONTAINERS.has(container.type);
-          if (hasCommentedOutCode(texts, precedingProse, !inTypeMembers) && !hasIllustrationLeadInAbove(comments, i)) {
-            context.report({ node: comment, messageId: "commentedOutCode" });
+          if (hasCommentedOutCode(texts, precedingProse, !inTypeMembers) && !hasIllustrationLeadInAbove(comments, i) && !runDocumentsHttpContract(comments, i)) {
+            if (!reportedCodeRuns.has(runStart)) {
+              context.report({ node: comment, messageId: "commentedOutCode" });
+              reportedCodeRuns.add(runStart);
+            }
             continue;
           }
           if (comment.type === "Line" && texts.length === 1) {
@@ -3293,6 +3336,8 @@ 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 BOUNDARY_RE = /(?<=[.!?])["'`)\]]*\s+(?=[A-Z0-9`])/;
 var BULLET_RE = /^\s*(?:[-*+] |\d+[.)] )/;
+var HEADING_RE = /^[A-Za-z][A-Za-z ]+:$/;
+var TECHNICAL_ANCHOR_RE = /https?:\/\/|`[^`\n]+`|:[a-z][a-z0-9_-]*:|(["'])[^"'\n]+\1|\d|\b[a-z][a-z0-9]*[A-Z][A-Za-z0-9]*\b|\b[A-Za-z][A-Za-z0-9]*_[A-Za-z0-9_]+\b|(?:^|\s)(?:[\w.-]+\/)+[\w.-]+|\b[\w.-]+\.(?:py|pyi|js|jsx|ts|tsx|json|ya?ml|toml|csv|parquet|md)\b|->|=>|==|!=|<=|>=|\|/mu;
 function body(comment) {
   return comment.value.replace(/^\*/, "").split("\n").map((line) => line.replace(/^\s*\*?\s?/, "")).join("\n").trim();
 }
@@ -3312,6 +3357,17 @@ function sentenceUnits(text) {
   if (prose.length > 0) units += prose.join(" ").split(BOUNDARY_RE).length;
   return units;
 }
+function hasDocumentationStructure(text) {
+  const paragraphs = text.split(/\n\s*\n/u).filter((part) => part.trim().length > 0);
+  if (paragraphs.length >= 2) return true;
+  return text.split("\n").some((raw) => {
+    const line = raw.trim().replace(/^\*\s?/u, "").trim();
+    return line.length > 0 && (BULLET_RE.test(line) || HEADING_RE.test(line) || /(?:->|=>|\|)/u.test(line));
+  });
+}
+function hasTechnicalAnchor(text) {
+  return TECHNICAL_ANCHOR_RE.test(text);
+}
 function proseGroups(filename, sourceCode, includeValueTags = false) {
   if (isGeneratedFile(filename, sourceCode.text) || isStoryFile(filename) || isScriptFile(filename) || isTestFile(filename)) return [];
   const groups = [];
@@ -3378,10 +3434,8 @@ function typedFunction(node) {
 }
 
 // src/rules/no-long-comment.ts
-var LIST_ITEM_RE = /^\s*(?:[-*+] |\d+[.)] )/m;
-var DURABLE_RATIONALE_RE = /\b(?:adapter|algorithm|atomic|auth(?:entication|orization)?|backpressure|billing|cache|callback|cluster|commit|compatib|concurr|contract|credential|cross-node|csrf|definite-assignment|error|exception|external|failure|fallback|handshake|interop|invalid|invariant|legacy|migration|navigation|parse[rsd]?|payload|privacy|protocol|race|reject|reload|renderer|resume|retry|runtime|schema|security|selector|sentinel|serializ|socket|stage|third-party|token|transaction|upstream|wire|workaround)\b|\b(?:must|required|prevent|avoid)\b/iu;
-var VENDORED_BASENAME_RE = /(?:^|\/)(?:jquery(?:-ui)?(?:[.-]\d[^/]*)?|lodash(?:\.min)?|bootstrap(?:\.min)?|react(?:\.min)?)\.js$/iu;
 var EXCESSIVE_SENTENCE_COUNT = 8;
+var VERSIONED_DEPENDENCY_TREE_RE = /(?:^|\/)lib\/[^/]*-?v?\d+\.\d+(?:\.\d+)?[^/]*\//iu;
 function documentsTypeOrMember(sourceCode, comment) {
   const token = sourceCode.getTokenAfter(comment, { includeComments: false });
   if (token === null || token.loc.start.line !== comment.loc.end.line + 1) return false;
@@ -3405,11 +3459,11 @@ var no_long_comment_default = createRule({
   defaultOptions: [],
   create(context) {
     const normalizedFilename = context.filename.replaceAll("\\", "/");
-    if (VENDORED_BASENAME_RE.test(normalizedFilename)) return {};
+    if (VERSIONED_DEPENDENCY_TREE_RE.test(normalizedFilename)) return {};
     return {
       Program() {
         for (const group of proseGroups(context.filename, context.sourceCode)) {
-          if (group.comment.type !== "Block" || group.hasTypedTags || LIST_ITEM_RE.test(group.text) || DURABLE_RATIONALE_RE.test(group.text) || documentsTypedFunction(context.sourceCode, group.comment) || documentsTypeOrMember(context.sourceCode, group.comment) || sentenceUnits(group.text) < EXCESSIVE_SENTENCE_COUNT) continue;
+          if (group.comment.type !== "Block" || !group.comment.value.startsWith("*") || group.hasTypedTags || hasDocumentationStructure(group.text) || hasTechnicalAnchor(group.text) || documentsTypedFunction(context.sourceCode, group.comment) || documentsTypeOrMember(context.sourceCode, group.comment) || sentenceUnits(group.text) < EXCESSIVE_SENTENCE_COUNT) continue;
           context.report({ node: group.comment, messageId: "tooLong" });
         }
       }
@@ -9709,31 +9763,6 @@ var prefer_server_actions_default = createRule({
   }
 });
 
-// src/rules/prefer-single-sentence-comment.ts
-var prefer_single_sentence_comment_default = createRule({
-  name: "prefer-single-sentence-comment",
-  meta: {
-    type: "suggestion",
-    docs: { description: "Prefer one sentence and self-documenting code over a two-sentence comment." },
-    schema: [],
-    messages: {
-      preferOneSentence: "Two-sentence comment \u2014 prefer one sentence and self-documenting code."
-    }
-  },
-  defaultOptions: [],
-  create(context) {
-    return {
-      Program() {
-        for (const group of proseGroups(context.filename, context.sourceCode)) {
-          if (!group.hasTypedTags && sentenceUnits(group.text) === 2) {
-            context.report({ node: group.comment, messageId: "preferOneSentence" });
-          }
-        }
-      }
-    };
-  }
-});
-
 // src/rules/prefer-string-literal-union.ts
 import {
   ESLintUtils as ESLintUtils3,
@@ -12224,6 +12253,10 @@ var retiredRules = {
     removedIn: "3.0.0",
     reason: "Delete the retired entry; application-profile consumers can separately adopt `@sarj/prefer-shadcn-primitives`."
   },
+  "prefer-single-sentence-comment": {
+    removedIn: "10.0.0",
+    reason: "Delete the config entry and suppressions; use the narrower no-comment-cruft, no-restated-comment, and no-long-comment rules."
+  },
   "primary-export-file-name": {
     removedIn: "4.0.0",
     reason: "Delete the config entry and suppressions; there is no replacement."
@@ -12298,7 +12331,6 @@ var rules = {
   "prefer-schema-for-api-payload": prefer_schema_for_api_payload_default,
   "prefer-semantic-colors": prefer_semantic_colors_default,
   "prefer-server-actions": prefer_server_actions_default,
-  "prefer-single-sentence-comment": prefer_single_sentence_comment_default,
   "prefer-string-literal-union": prefer_string_literal_union_default,
   "prefer-whole-object-assertion": prefer_whole_object_assertion_default,
   "prefer-zod-enum": prefer_zod_enum_default,
@@ -12314,7 +12346,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "9.17.0"
+  version: "10.0.0"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",
@@ -12369,7 +12401,6 @@ var recommendedRules = {
   "@sarj/prefer-schema-for-api-payload": "warn",
   "@sarj/prefer-semantic-colors": ["warn", { requireSemanticTokens: true }],
   "@sarj/prefer-server-actions": "warn",
-  "@sarj/prefer-single-sentence-comment": "warn",
   "@sarj/prefer-string-literal-union": "warn",
   "@sarj/prefer-whole-object-assertion": "warn",
   "@sarj/prefer-zod-enum": "warn",
@@ -12435,7 +12466,6 @@ var strictRules = {
   "@sarj/prefer-schema-for-api-payload": "error",
   "@sarj/prefer-semantic-colors": ["error", { requireSemanticTokens: true }],
   "@sarj/prefer-server-actions": "error",
-  "@sarj/prefer-single-sentence-comment": "warn",
   "@sarj/prefer-string-literal-union": "error",
   "@sarj/prefer-whole-object-assertion": "error",
   "@sarj/prefer-zod-enum": "error",

package/package.json

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