@blumintinc/eslint-plugin-blumint 1.20.110 → 1.20.111

package/lib/index.js

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

package/lib/rules/enforce-global-constants.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceGlobalConstants = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const shebang_1 = require("../utils/shebang");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 exports.enforceGlobalConstants = (0, createRule_1.createRule)({
     name: 'enforce-global-constants',
@@ -269,7 +270,10 @@ exports.enforceGlobalConstants = (0, createRule_1.createRule)({
                         }
                         else {
                             const body = program.body;
-                            let insertPos = 0;
+                            // A shebang has to stay at character 0 or the file stops parsing
+                            // (TS18026), so it bounds the insertion the same way the
+                            // directive prologue below does.
+                            let insertPos = (0, shebang_1.afterShebang)(text);
                             let afterDirectiveIdx = -1;
                             for (let i = 0; i < body.length; i++) {
                                 const stmt = body[i];

package/lib/rules/logical-top-to-bottom-grouping.js

@@ -4,6 +4,7 @@ exports.logicalTopToBottomGrouping = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const createRule_1 = require("../utils/createRule");
+const shebang_1 = require("../utils/shebang");
 const TYPE_EXPRESSION_WRAPPERS = new Set([
     utils_1.AST_NODE_TYPES.TSAsExpression,
     utils_1.AST_NODE_TYPES.TSTypeAssertion,
@@ -730,7 +731,12 @@ function findEarliestSafeIndex(body, startIndex, dependencies, { allowHooks, sto
  * comments directly above it reads as its preamble.
  */
 function getLeadingComments(statement, sourceCode) {
-    const comments = sourceCode.getCommentsBefore(statement);
+    // A shebang belongs to the file, not to the statement below it. Left in the
+    // preamble, relocating the first statement carries `#!` off character 0 and
+    // the output stops parsing.
+    const comments = sourceCode
+        .getCommentsBefore(statement)
+        .filter((comment) => !(0, shebang_1.isShebangComment)(sourceCode, comment));
     const ownLine = comments.findIndex((comment) => {
         const previous = sourceCode.getTokenBefore(comment, {
             includeComments: true,

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.verticallyGroupRelatedFunctions = void 0;
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const shebang_1 = require("../utils/shebang");
 const DEFAULT_OPTIONS = {
     exportPlacement: 'ignore',
     dependencyDirection: 'callers-first',
@@ -329,10 +330,15 @@ function getStatementRangeWithComments(statement, sourceCode, consumedComments,
     // 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 leadingCommentsOf = (target) => filterComments(sourceCode.getCommentsBefore(target) || [])
+        .filter((comment) => {
         const tokenBefore = sourceCode.getTokenBefore(comment);
         return (!tokenBefore || tokenBefore.loc.end.line !== comment.loc.start.line);
-    });
+    })
+        // A shebang belongs to the file, not to the statement below it. Left in
+        // the span, relocating the first statement carries `#!` off character 0
+        // and the output stops parsing.
+        .filter((comment) => !(0, shebang_1.isShebangComment)(sourceCode, comment));
     const commentsBefore = leadingCommentsOf(statement);
     const nextLeadingComments = nextStatement
         ? new Set(leadingCommentsOf(nextStatement))

package/lib/utils/shebang.d.ts

@@ -0,0 +1,19 @@
+import { TSESLint, TSESTree } from '@typescript-eslint/utils';
+/**
+ * A shebang is only a shebang at character 0. One byte in front of it and the
+ * file stops parsing outright (`TS18026: '#!' can only be used at the start of
+ * a file`) and stops being executable.
+ *
+ * ESLint hands it to rules as an ordinary leading comment of the first
+ * statement, which is what makes it easy to lose: a fixer that relocates a
+ * statement together with its leading comments carries the shebang into the
+ * middle of the file, and one that splices at offset 0 pushes it off line 1.
+ * `importInsertion` already encodes this for the rules that add an import;
+ * these are the same rule for the ones that reorder or hoist.
+ */
+export declare function isShebangComment(sourceCode: Pick<TSESLint.SourceCode, 'text'>, comment: TSESTree.Comment): boolean;
+/**
+ * The first offset at which text may be spliced without displacing a shebang.
+ * Zero for the overwhelmingly common file that has none.
+ */
+export declare function afterShebang(text: string): number;

package/lib/utils/shebang.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.afterShebang = exports.isShebangComment = void 0;
+/**
+ * A shebang is only a shebang at character 0. One byte in front of it and the
+ * file stops parsing outright (`TS18026: '#!' can only be used at the start of
+ * a file`) and stops being executable.
+ *
+ * ESLint hands it to rules as an ordinary leading comment of the first
+ * statement, which is what makes it easy to lose: a fixer that relocates a
+ * statement together with its leading comments carries the shebang into the
+ * middle of the file, and one that splices at offset 0 pushes it off line 1.
+ * `importInsertion` already encodes this for the rules that add an import;
+ * these are the same rule for the ones that reorder or hoist.
+ */
+function isShebangComment(sourceCode, comment) {
+    return comment.range[0] === 0 && sourceCode.text.startsWith('#!');
+}
+exports.isShebangComment = isShebangComment;
+/**
+ * The first offset at which text may be spliced without displacing a shebang.
+ * Zero for the overwhelmingly common file that has none.
+ */
+function afterShebang(text) {
+    if (!text.startsWith('#!')) {
+        return 0;
+    }
+    const lineEnd = text.indexOf('\n');
+    return lineEnd === -1 ? text.length : lineEnd + 1;
+}
+exports.afterShebang = afterShebang;
+//# sourceMappingURL=shebang.js.map

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "1.20.111",
+    "date": "2026-08-05T13:37:20.101Z",
+    "rules": [
+      {
+        "name": "enforce-global-constants",
+        "changeType": "fix",
+        "issues": [
+          1739
+        ],
+        "summary": "hoist below a shebang, not above it (closes #1739)"
+      },
+      {
+        "name": "logical-top-to-bottom-grouping",
+        "changeType": "fix",
+        "issues": [
+          1738
+        ],
+        "summary": "keep a shebang at character 0 when reordering (closes #1738)"
+      },
+      {
+        "name": "vertically-group-related-functions",
+        "changeType": "fix",
+        "issues": [
+          1737
+        ],
+        "summary": "keep a shebang at character 0 when reordering (closes #1737)"
+      }
+    ]
+  },
   {
     "version": "1.20.110",
     "date": "2026-08-05T11:59:59.800Z",