@blumintinc/eslint-plugin-blumint 1.19.7 → 1.19.9

package/lib/index.js

@@ -222,7 +222,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.19.7',
+        version: '1.19.9',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/no-harness-coupled-disables.js

@@ -43,6 +43,29 @@ const SESSION_MATCHER = {
 function isDirectiveComment(comment) {
     return DIRECTIVE_PREFIX.test(comment.value.trim());
 }
+/**
+ * Pointer phrasing by which a directive DEFERS its rationale to an adjacent
+ * comment: "see above", "per the note below", "as noted in the comment".
+ * Up to two intervening words ("the note", "the preceding") are tolerated so
+ * natural phrasings still register as deferrals.
+ */
+const DEFERRAL_PATTERN = /\b(?:see|per|as)\s+(?:\w+\s+){0,2}(?:above|below|note|comment|preceding)\b/i;
+/**
+ * A directive defers to its preceding comment only when its own `--` text is a
+ * mere pointer to that comment ("see above") or carries no substantive words at
+ * all (a bare "^" gesture). This is the discriminating signal for #1296's
+ * split-justification support: a directive that already states a substantive,
+ * self-contained reason owns its rationale outright, so an unrelated docblock or
+ * line comment that merely sits above it — documenting the declaration, not the
+ * suppression — must never contribute its incidental harness keywords (#1312).
+ */
+function defersToPreceding(justification) {
+    const text = justification.trim();
+    if (DEFERRAL_PATTERN.test(text)) {
+        return true;
+    }
+    return text.replace(/[^a-z]/gi, '') === '';
+}
 /**
  * Isolates the justification text of a directive comment: everything after the
  * first `--` separator, spanning every line of a multi-line block body. The
@@ -109,12 +132,16 @@ exports.noHarnessCoupledDisables = (0, createRule_1.createRule)({
                     }
                     // Split-justification style: an immediately-adjacent preceding
                     // non-directive comment (no intervening blank line or code) is part
-                    // of the directive's rationale when the directive defers to it.
+                    // of the directive's rationale ONLY when the directive defers to it.
+                    // Without the deferral gate, an unrelated docblock above the
+                    // declaration bleeds its incidental harness words into a directive
+                    // that already carries a self-contained code-level reason (#1312).
                     let scanned = justification;
                     const previous = comments[index - 1];
                     if (previous &&
                         !isDirectiveComment(previous) &&
-                        comment.loc.start.line - previous.loc.end.line <= 1) {
+                        comment.loc.start.line - previous.loc.end.line <= 1 &&
+                        defersToPreceding(justification)) {
                         scanned = `${previous.value}\n${scanned}`;
                     }
                     const matchedTerm = findHarnessTerm(scanned);

package/lib/rules/prefer-utility-function-own-file.js

@@ -31,6 +31,20 @@ const ASTHelpers_1 = require("../utils/ASTHelpers");
 const DEFAULT_MIN_STATEMENTS = 8;
 const DEFAULT_MIN_LINES = 12;
 const DEFAULT_IGNORE_CLOSURES = true;
+/**
+ * Next.js framework-reserved page exports. Next.js only recognizes these when
+ * they are exported from the page file itself, so they categorically cannot be
+ * moved to a `util/` file and re-imported — the rule's suggested remediation is
+ * impossible to follow for them. Mirrors the exemption precedent set in
+ * `semantic-function-prefixes` (issue #333).
+ */
+const NEXTJS_RESERVED_PAGE_EXPORTS = new Set([
+    'getServerSideProps',
+    'getStaticProps',
+    'getStaticPaths',
+    'middleware',
+    'config',
+]);
 /**
  * Collects all identifiers referenced in a node body (for closure detection).
  * Returns the set of identifier names referenced anywhere inside the node,
@@ -289,6 +303,23 @@ function isExemptFile(filename) {
         return true;
     return false;
 }
+/**
+ * Returns true if the candidate is a Next.js framework-reserved page export
+ * (`getServerSideProps`, `getStaticProps`, `getStaticPaths`, `middleware`,
+ * `config`) living in a file under a `pages/` directory. Keying off the
+ * `pages/` path segment covers both the `src/pages/**` and bare `pages/**`
+ * Pages Router layouts. These exports must stay in the page file — Next.js only
+ * recognizes them there — so they can never be extracted to their own util
+ * file, regardless of size or closure geometry.
+ */
+function isNextReservedPageExport(name, filename) {
+    if (!NEXTJS_RESERVED_PAGE_EXPORTS.has(name))
+        return false;
+    if (!filename)
+        return false;
+    const normalized = filename.replace(/\\/g, '/');
+    return /(^|\/)pages\//.test(normalized);
+}
 /**
  * Returns true if the module top-level self-invokes one of its own functions,
  * e.g. `void autoRunIfMain();` or `main();`. This is the signature of a CLI
@@ -538,7 +569,15 @@ exports.preferUtilityFunctionOwnFile = (0, createRule_1.createRule)({
                     return;
                 // For each candidate, determine whether to flag
                 for (const info of topLevelFunctions) {
-                    const { node, name, fn, isDefaultExport } = info;
+                    const { node, name, fn, isDefaultExport, isNamedExport } = info;
+                    // --- Exclusion: Next.js reserved page export ---
+                    // `getServerSideProps`/`getStaticProps`/`getStaticPaths`/`middleware`/
+                    // `config` are framework-reserved: Next.js only recognizes them when
+                    // exported from the page file itself, so they can never move to a
+                    // util/ file. Scoped to named exports under a `pages/` directory so it
+                    // does not over-broaden to same-named functions elsewhere.
+                    if (isNamedExport && isNextReservedPageExport(name, filename))
+                        continue;
                     // --- Exclusion: is a hook ---
                     if (isHookName(name))
                         continue;

package/lib/rules/vertically-group-related-functions.js

@@ -323,9 +323,19 @@ function computeExpectedOrder(functions, options) {
 }
 function getStatementRangeWithComments(statement, sourceCode, consumedComments, nextStatement) {
     const filterComments = (comments) => (comments || []).filter((comment) => !consumedComments || !consumedComments.has(comment));
-    const commentsBefore = filterComments(sourceCode.getCommentsBefore(statement) || []);
+    // A comment sharing a line with the code token immediately before it is a
+    // trailing comment of that preceding statement (e.g. `const x = 2; // note`),
+    // not a leading comment of the node beneath it. Attributing it to the node
+    // below would drag an interleaved statement's own end-of-line comment along
+    // when the following function is relocated. Only own-line comments count as
+    // leading comments.
+    const leadingCommentsOf = (target) => filterComments(sourceCode.getCommentsBefore(target) || []).filter((comment) => {
+        const tokenBefore = sourceCode.getTokenBefore(comment);
+        return (!tokenBefore || tokenBefore.loc.end.line !== comment.loc.start.line);
+    });
+    const commentsBefore = leadingCommentsOf(statement);
     const nextLeadingComments = nextStatement
-        ? new Set(filterComments(sourceCode.getCommentsBefore(nextStatement) || []))
+        ? new Set(leadingCommentsOf(nextStatement))
         : new Set();
     const trailingCandidates = filterComments(sourceCode.getCommentsAfter(statement) || []).filter((comment) => !nextLeadingComments.has(comment));
     const start = commentsBefore.length > 0
@@ -457,9 +467,15 @@ exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
                     .sort((a, b) => a.originalIndex - b.originalIndex);
                 const consumedComments = new Set();
                 const statementRanges = new Map();
-                sourceOrderedInfos.forEach((info, idx) => {
-                    const nextInfo = sourceOrderedInfos[idx + 1];
-                    const [rangeStart, rangeEnd] = getStatementRangeWithComments(info.statementNode, sourceCode, consumedComments, nextInfo?.statementNode);
+                sourceOrderedInfos.forEach((info) => {
+                    // Bound each function's trailing comments by the statement that
+                    // physically follows it in the block — which may be an interleaved
+                    // non-function statement, not the next function — so an interleaved
+                    // statement's own leading comment is never swallowed into the
+                    // function above it.
+                    const bodyIndex = node.body.indexOf(info.statementNode);
+                    const nextStatement = bodyIndex >= 0 ? node.body[bodyIndex + 1] : undefined;
+                    const [rangeStart, rangeEnd] = getStatementRangeWithComments(info.statementNode, sourceCode, consumedComments, nextStatement);
                     statementRanges.set(info.statementNode, [rangeStart, rangeEnd]);
                 });
                 const firstFunctionIndex = node.body.findIndex((statement) => functionStatements.has(statement));
@@ -488,12 +504,22 @@ exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
                             // Real modules interleave type aliases, consts, and top-level
                             // calls (e.g. `void autoRunIfMain();`) between functions. Rather
                             // than bail, reorder only the function statements among their own
-                            // slots, leaving every other statement exactly where it is. Plain
-                            // node ranges keep the edits disjoint (no comment-span overlap
-                            // with the interleaved statements).
+                            // slots, leaving every other statement exactly where it is. Both
+                            // the destination slot and the source text use the same
+                            // comment-inclusive ranges Path A relies on, so each function's
+                            // leading JSDoc travels with it instead of being left orphaned in
+                            // its old slot. The precomputed `statementRanges` already exclude
+                            // each interleaved statement's own leading comments (they are
+                            // treated as the next function's leading comments), so the widened
+                            // edits stay disjoint from one another and from the interleaved
+                            // statements — no comment-span overlap.
                             return sourceOrderedInfos.map((info, idx) => {
                                 const target = expectedOrderInfos[idx];
-                                return fixer.replaceTextRange(info.statementNode.range, sourceCode.getText(target.statementNode));
+                                const destRange = statementRanges.get(info.statementNode) ||
+                                    getStatementRangeWithComments(info.statementNode, sourceCode);
+                                const [targetStart, targetEnd] = statementRanges.get(target.statementNode) ||
+                                    getStatementRangeWithComments(target.statementNode, sourceCode);
+                                return fixer.replaceTextRange(destRange, sourceCode.text.slice(targetStart, targetEnd));
                             });
                         }
                         const [start] = statementRanges.get(node.body[firstFunctionIndex]) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.19.7",
+  "version": "1.19.9",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "1.19.9",
+    "date": "2026-07-17T01:27:12.035Z",
+    "rules": [
+      {
+        "name": "no-harness-coupled-disables",
+        "changeType": "fix",
+        "issues": [
+          1312
+        ],
+        "summary": "only merge preceding comment when directive defers to it (closes #1312)"
+      }
+    ]
+  },
+  {
+    "version": "1.19.8",
+    "date": "2026-07-17T00:25:07.461Z",
+    "rules": [
+      {
+        "name": "prefer-utility-function-own-file",
+        "changeType": "fix",
+        "issues": [
+          1311
+        ],
+        "summary": "exempt Next.js reserved page exports (closes #1311)"
+      },
+      {
+        "name": "vertically-group-related-functions",
+        "changeType": "fix",
+        "issues": [
+          1310
+        ],
+        "summary": "keep interleaved statements' own comments in place when reordering (refs #1310); carry leading JSDoc with reordered functions across interleaved statements (closes #1310)"
+      }
+    ]
+  },
   {
     "version": "1.19.7",
     "date": "2026-07-16T01:36:53.555Z",