@blumintinc/eslint-plugin-blumint 1.19.17 → 1.19.18

package/lib/index.js

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

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

@@ -348,6 +348,179 @@ function getStatementRangeWithComments(statement, sourceCode, consumedComments,
     trailingCandidates.forEach((comment) => consumedComments?.add(comment));
     return [start, end];
 }
+// Collect every identifier a statement references anywhere in its subtree,
+// including type-annotation positions (e.g. `WidgetProps` inside
+// `FC<WidgetProps>`) and default-parameter values (e.g. `DEFAULT_LABEL` in
+// `{ label = DEFAULT_LABEL }`). Identifiers that are member-access properties or
+// object/type member keys are skipped: `obj.OFFSET` is not a reference to a
+// top-level `OFFSET` binding, so counting it would spuriously constrain the
+// reorder.
+function collectReferencedNames(node) {
+    const names = new Set();
+    const visit = (current, parent) => {
+        if (!current || !ASTHelpers_1.ASTHelpers.isNode(current)) {
+            return;
+        }
+        if (current.type === 'Identifier') {
+            const isMemberProperty = parent?.type === 'MemberExpression' &&
+                parent.property === current &&
+                !parent.computed;
+            const isObjectKey = parent?.type === 'Property' &&
+                parent.key === current &&
+                !parent.computed;
+            const isMemberKey = (parent?.type === 'TSPropertySignature' ||
+                parent?.type === 'TSMethodSignature') &&
+                parent.key === current &&
+                !parent.computed;
+            if (!isMemberProperty && !isObjectKey && !isMemberKey) {
+                names.add(current.name);
+            }
+        }
+        Object.values(current).forEach((value) => {
+            if (!value || value === current || current.parent === value) {
+                return;
+            }
+            if (Array.isArray(value)) {
+                value.forEach((child) => {
+                    if (ASTHelpers_1.ASTHelpers.isNode(child)) {
+                        visit(child, current);
+                    }
+                });
+            }
+            else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+                visit(value, current);
+            }
+        });
+    };
+    visit(node, null);
+    return names;
+}
+// Names bound by an interleaved VALUE declaration (const/let/var) — but not by a
+// reorderable function. Hoisting a function above a value binding it references
+// is a genuine runtime declare-before-use. Type aliases are tracked separately
+// (interleavedTypeAliasNamesOf), because their hoist hazard is not runtime — it
+// is the companion prefer-type-alias-over-typeof-constant rule, which fires only
+// for a const declarator whose own type annotation names a later alias.
+function interleavedValueNamesOf(regionStatements, functionStatements) {
+    const names = new Set();
+    regionStatements.forEach((statement) => {
+        if (functionStatements.has(statement)) {
+            return;
+        }
+        if (statement.type === 'VariableDeclaration') {
+            statement.declarations.forEach((declarator) => {
+                if (declarator.id.type === 'Identifier') {
+                    names.add(declarator.id.name);
+                }
+            });
+        }
+    });
+    return names;
+}
+// Names bound by an interleaved `type` alias in the reordered region.
+function interleavedTypeAliasNamesOf(regionStatements, functionStatements) {
+    const names = new Set();
+    regionStatements.forEach((statement) => {
+        if (functionStatements.has(statement)) {
+            return;
+        }
+        if (statement.type === 'TSTypeAliasDeclaration') {
+            names.add(statement.id.name);
+        }
+        else if (statement.type === 'ExportNamedDeclaration' &&
+            statement.declaration?.type === 'TSTypeAliasDeclaration') {
+            names.add(statement.declaration.id.name);
+        }
+    });
+    return names;
+}
+// Type names referenced in the annotation of a function-holding const's own
+// binding identifier (e.g. `WidgetProps` in `const W: FC<WidgetProps> = ...`).
+// This mirrors exactly what prefer-type-alias-over-typeof-constant's
+// defineTypeBeforeConstant keys on: only a const declarator's `id` annotation.
+// A function *declaration*'s return type (`function f(): Marker`) and an arrow
+// parameter's annotation (`const f = (p: Props) => ...`) are deliberately NOT
+// counted — neither trips the companion rule, so constraining them would decline
+// safe reorders.
+function constAnnotationTypeNamesOf(statementNode) {
+    const names = new Set();
+    const declaration = statementNode.type === 'ExportNamedDeclaration'
+        ? statementNode.declaration
+        : statementNode;
+    if (declaration?.type === 'VariableDeclaration') {
+        declaration.declarations.forEach((declarator) => {
+            if (declarator.id.type === 'Identifier' && declarator.id.typeAnnotation) {
+                collectReferencedNames(declarator.id.typeAnnotation).forEach((name) => names.add(name));
+            }
+        });
+    }
+    return names;
+}
+// Decline (return true) any reorder that would place a function ABOVE an
+// interleaved declaration it depends on. The fixer pins interleaved statements in
+// place and only swaps functions between their own slots, so such a reorder
+// produces a fresh declare-before-use — trading one violation for another instead
+// of converging. Two hazards are guarded:
+//   * value binding (const/let/var): a runtime declare-before-use if a function
+//     references it and is hoisted above it.
+//   * `type` alias: hoisting a function-holding const whose OWN binding
+//     annotation names the alias above that alias trips the companion
+//     prefer-type-alias-over-typeof-constant rule (defineTypeBeforeConstant).
+// Walks the post-reorder sequence front-to-back: each function slot is filled
+// with the next expected function; interleaved statements keep their slot. A
+// function that references a not-yet-declared interleaved dependency is being
+// hoisted above it.
+function reorderHoistsFunctionAboveDependency(regionStatements, functionStatements, expectedOrderInfos) {
+    const interleavedValueNames = interleavedValueNamesOf(regionStatements, functionStatements);
+    const interleavedTypeNames = interleavedTypeAliasNamesOf(regionStatements, functionStatements);
+    if (interleavedValueNames.size === 0 && interleavedTypeNames.size === 0) {
+        return false;
+    }
+    const declaredValueNames = new Set();
+    const declaredTypeNames = new Set();
+    let slotCursor = 0;
+    for (const statement of regionStatements) {
+        if (functionStatements.has(statement)) {
+            const occupant = expectedOrderInfos[slotCursor];
+            slotCursor += 1;
+            if (!occupant) {
+                continue;
+            }
+            if (interleavedValueNames.size > 0) {
+                const referenced = collectReferencedNames(occupant.statementNode);
+                for (const name of referenced) {
+                    if (interleavedValueNames.has(name) &&
+                        !declaredValueNames.has(name)) {
+                        return true;
+                    }
+                }
+            }
+            if (interleavedTypeNames.size > 0) {
+                const annotationTypes = constAnnotationTypeNamesOf(occupant.statementNode);
+                for (const name of annotationTypes) {
+                    if (interleavedTypeNames.has(name) && !declaredTypeNames.has(name)) {
+                        return true;
+                    }
+                }
+            }
+        }
+        else if (statement.type === 'VariableDeclaration') {
+            statement.declarations.forEach((declarator) => {
+                if (declarator.id.type === 'Identifier') {
+                    declaredValueNames.add(declarator.id.name);
+                }
+            });
+        }
+        else if (statement.type === 'TSTypeAliasDeclaration') {
+            declaredTypeNames.add(statement.id.name);
+        }
+        else if (statement.type === 'ExportNamedDeclaration' &&
+            statement.declaration?.type === 'TSTypeAliasDeclaration') {
+            declaredTypeNames.add(statement.declaration.id.name);
+        }
+    }
+    return false;
+}
 exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
     name: 'vertically-group-related-functions',
     meta: {
@@ -500,6 +673,16 @@ exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
                         }
                         const slice = node.body.slice(firstFunctionIndex, lastFunctionIndex + 1);
                         const blockContainsOnlyFunctions = slice.every((statement) => functionStatements.has(statement));
+                        // Decline a reorder that would hoist a function above an interleaved
+                        // declaration it depends on (a value binding it references, or the
+                        // `type` alias named in its own const annotation). Applies to both
+                        // paths, though it can only trigger in the interleaved-statement
+                        // branch below (Path A reorders a block with no interleaved
+                        // declarations). The misorderedFunction report still fires; only the
+                        // harmful, non-converging autofix is suppressed.
+                        if (reorderHoistsFunctionAboveDependency(slice, functionStatements, expectedOrderInfos)) {
+                            return null;
+                        }
                         if (!blockContainsOnlyFunctions) {
                             // Real modules interleave type aliases, consts, and top-level
                             // calls (e.g. `void autoRunIfMain();`) between functions. Rather

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "1.19.18",
+    "date": "2026-07-18T13:43:27.635Z",
+    "rules": [
+      {
+        "name": "vertically-group-related-functions",
+        "changeType": "fix",
+        "issues": [
+          1320
+        ],
+        "summary": "decline reorder that hoists a function above its interleaved type/const dependency (closes #1320)"
+      }
+    ]
+  },
   {
     "version": "1.19.17",
     "date": "2026-07-18T07:27:36.853Z",