@sarj/eslint-plugin 15.6.3 → 15.6.4

package/dist/index.cjs

@@ -1054,20 +1054,20 @@ var noCommentCruftDocumentation = {
   ],
   examples: [
     {
-      id: "rationale-comment",
-      title: "A comment explains why retry is required",
+      id: "owned-context",
+      title: "A reference records why the counter changes",
       outcome: "no-match",
-      files: [{ path: "src/retry.ts", source: "// retry because the upstream API is flaky\nconst x = retry();" }],
-      focusPath: "src/retry.ts",
+      files: [{ path: "src/counter.ts", source: "// increment the counter for PLT-812\ncounter += 1;" }],
+      focusPath: "src/counter.ts",
       expectedCount: 0,
       public: true
     },
     {
-      id: "region-banner",
-      title: "A region comment decorates a code boundary",
+      id: "redundant-narration",
+      title: "A comment repeats the statement below",
       outcome: "match",
-      files: [{ path: "src/helpers.ts", source: "const x = 1;\n// region helpers\nconst y = 2;" }],
-      focusPath: "src/helpers.ts",
+      files: [{ path: "src/counter.ts", source: "// increment the counter\ncounter += 1;" }],
+      focusPath: "src/counter.ts",
       expectedCount: 1,
       public: true
     }
@@ -4201,8 +4201,51 @@ var noLongCommentDocumentation = {
   category: "maintainability",
   limitations: ["Only JSDoc blocks are inspected; structured API docs, tests, scripts, generated files, and versioned dependencies are excluded."],
   examples: [
-    { id: "local-fact", title: "Keep a concise local fact", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// The cache is process local.\nconst cache = new Map();" }], focusPath: "src/cache.ts", expectedCount: 0, public: true },
-    { id: "prose-wall", title: "Avoid an unstructured prose wall", outcome: "match", files: [{ path: "src/chart.ts", source: "/** One. Two. Three. Four. Five. Six. Seven. Eight. */\nconst chart = createChart();" }], focusPath: "src/chart.ts", expectedCount: 1, public: true }
+    {
+      id: "structured-jsdoc",
+      title: "Paragraphs separate a component's durable constraints",
+      outcome: "no-match",
+      files: [{
+        path: "src/composer.ts",
+        source: [
+          "/**",
+          " * Shared composer.",
+          " *",
+          " * It serves the room. It serves task comments. It stays visually calm. It accepts attachments.",
+          " *",
+          " * The `tone` prop supplies task styling. The `leadingTools` prop supplies controls.",
+          " * The parent owns uploads. The component owns focus.",
+          " */",
+          "",
+          "export const Composer = forwardRef(function Composer() { return null; });"
+        ].join("\n")
+      }],
+      focusPath: "src/composer.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "prose-wall",
+      title: "One paragraph narrates a chart's design history",
+      outcome: "match",
+      files: [{
+        path: "src/chart.ts",
+        source: `/**
+ * The ports chart shows arrivals and departures across the network.
+ * It was originally a line chart, but the lines crossed too often.
+ * Bars make adjacent ports easier to compare at a glance.
+ * The axis starts at zero so visual differences stay proportional.
+ * A single series uses the site navy for brand consistency.
+ * Empty ports use a neutral ink so missing traffic remains visible.
+ * Tooltip values repeat the units shown on the vertical axis.
+ * The chart intentionally keeps labels horizontal on wide screens.
+ */
+export function PortBars() { return null; }`
+      }],
+      focusPath: "src/chart.ts",
+      expectedCount: 1,
+      public: true
+    }
   ]
 };
 var EXCESSIVE_SENTENCE_COUNT = 8;
@@ -7486,10 +7529,10 @@ var noTypedDocSectionsDocumentation = {
       public: true
     },
     {
-      id: "repeated-typed-sections",
-      title: "Do not restate typed parameters and returns",
+      id: "restated-parameter",
+      title: "Do not expand a typed parameter's name",
       outcome: "match",
-      files: [{ path: "src/client.ts", source: "/** @param id external identifier\n * @returns the value\n */\nexport function fetchValue(id: string): number { return 1; }" }],
+      files: [{ path: "src/client.ts", source: "/** @param userId the user identifier */\nexport function fetchValue(userId: string): number { return 1; }" }],
       focusPath: "src/client.ts",
       expectedCount: 1,
       public: true
@@ -15031,7 +15074,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.6.3"
+  version: "15.6.4"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",

package/dist/index.d.cts

@@ -418,7 +418,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.6.3";
+        readonly version: "15.6.4";
     };
     readonly rules: {
         readonly "duplicate-test-body": DocumentedRule<readonly [], "duplicateTestBody">;

package/dist/index.d.ts

@@ -418,7 +418,7 @@ type FlatPreset = {
 declare const plugin: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.6.3";
+        readonly version: "15.6.4";
     };
     readonly rules: {
         readonly "duplicate-test-body": DocumentedRule<readonly [], "duplicateTestBody">;

package/dist/index.js

@@ -1011,20 +1011,20 @@ var noCommentCruftDocumentation = {
   ],
   examples: [
     {
-      id: "rationale-comment",
-      title: "A comment explains why retry is required",
+      id: "owned-context",
+      title: "A reference records why the counter changes",
       outcome: "no-match",
-      files: [{ path: "src/retry.ts", source: "// retry because the upstream API is flaky\nconst x = retry();" }],
-      focusPath: "src/retry.ts",
+      files: [{ path: "src/counter.ts", source: "// increment the counter for PLT-812\ncounter += 1;" }],
+      focusPath: "src/counter.ts",
       expectedCount: 0,
       public: true
     },
     {
-      id: "region-banner",
-      title: "A region comment decorates a code boundary",
+      id: "redundant-narration",
+      title: "A comment repeats the statement below",
       outcome: "match",
-      files: [{ path: "src/helpers.ts", source: "const x = 1;\n// region helpers\nconst y = 2;" }],
-      focusPath: "src/helpers.ts",
+      files: [{ path: "src/counter.ts", source: "// increment the counter\ncounter += 1;" }],
+      focusPath: "src/counter.ts",
       expectedCount: 1,
       public: true
     }
@@ -4163,8 +4163,51 @@ var noLongCommentDocumentation = {
   category: "maintainability",
   limitations: ["Only JSDoc blocks are inspected; structured API docs, tests, scripts, generated files, and versioned dependencies are excluded."],
   examples: [
-    { id: "local-fact", title: "Keep a concise local fact", outcome: "no-match", files: [{ path: "src/cache.ts", source: "// The cache is process local.\nconst cache = new Map();" }], focusPath: "src/cache.ts", expectedCount: 0, public: true },
-    { id: "prose-wall", title: "Avoid an unstructured prose wall", outcome: "match", files: [{ path: "src/chart.ts", source: "/** One. Two. Three. Four. Five. Six. Seven. Eight. */\nconst chart = createChart();" }], focusPath: "src/chart.ts", expectedCount: 1, public: true }
+    {
+      id: "structured-jsdoc",
+      title: "Paragraphs separate a component's durable constraints",
+      outcome: "no-match",
+      files: [{
+        path: "src/composer.ts",
+        source: [
+          "/**",
+          " * Shared composer.",
+          " *",
+          " * It serves the room. It serves task comments. It stays visually calm. It accepts attachments.",
+          " *",
+          " * The `tone` prop supplies task styling. The `leadingTools` prop supplies controls.",
+          " * The parent owns uploads. The component owns focus.",
+          " */",
+          "",
+          "export const Composer = forwardRef(function Composer() { return null; });"
+        ].join("\n")
+      }],
+      focusPath: "src/composer.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "prose-wall",
+      title: "One paragraph narrates a chart's design history",
+      outcome: "match",
+      files: [{
+        path: "src/chart.ts",
+        source: `/**
+ * The ports chart shows arrivals and departures across the network.
+ * It was originally a line chart, but the lines crossed too often.
+ * Bars make adjacent ports easier to compare at a glance.
+ * The axis starts at zero so visual differences stay proportional.
+ * A single series uses the site navy for brand consistency.
+ * Empty ports use a neutral ink so missing traffic remains visible.
+ * Tooltip values repeat the units shown on the vertical axis.
+ * The chart intentionally keeps labels horizontal on wide screens.
+ */
+export function PortBars() { return null; }`
+      }],
+      focusPath: "src/chart.ts",
+      expectedCount: 1,
+      public: true
+    }
   ]
 };
 var EXCESSIVE_SENTENCE_COUNT = 8;
@@ -7448,10 +7491,10 @@ var noTypedDocSectionsDocumentation = {
       public: true
     },
     {
-      id: "repeated-typed-sections",
-      title: "Do not restate typed parameters and returns",
+      id: "restated-parameter",
+      title: "Do not expand a typed parameter's name",
       outcome: "match",
-      files: [{ path: "src/client.ts", source: "/** @param id external identifier\n * @returns the value\n */\nexport function fetchValue(id: string): number { return 1; }" }],
+      files: [{ path: "src/client.ts", source: "/** @param userId the user identifier */\nexport function fetchValue(userId: string): number { return 1; }" }],
       focusPath: "src/client.ts",
       expectedCount: 1,
       public: true
@@ -15012,7 +15055,7 @@ var rules = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.6.3"
+  version: "15.6.4"
 };
 var applicationOnlyRules = [
   "no-restricted-library-load",

package/package.json

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