feat(shebang): Add options to ignore unpublished files (#172)

* feat: Add shebangs to all ignored executable files

* chore: Add names to shebang tests

* fix: Ignore shebangs for all files not published

* feat(shebang): Add "ignoreUnpublished" option

* chore: Actually ignore test fixtures

* chore: Remove import-maps module disable

* feat(shebang): Add "additionalExecutables" option

* docs(shebang): Add two new options to docs

* chore(shebang): Only report the first line #85

Author: scagood

docs/rules/shebang.md

@@ -61,7 +61,11 @@ console.log("hello");
 
 ```json
 {
-    "n/shebang": ["error", {"convertPath": null}]
+    "n/shebang": ["error", {
+        "convertPath": null,
+        "ignoreUnpublished": false,
+        "additionalExecutables": [],
+    }]
 }
 ```
 
@@ -70,6 +74,14 @@ console.log("hello");
 This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath).
 Please see the shared settings documentation for more information.
 
+#### ignoreUnpublished
+
+Allow for files that are not published to npm to be ignored by this rule.
+
+#### additionalExecutables
+
+Mark files as executable that are not referenced by the package.json#bin property
+
 ## 🔎 Implementation
 
 - [Rule source](../../lib/rules/shebang.js)

eslint.config.js

@@ -13,17 +13,14 @@ module.exports = [
     {
         languageOptions: { globals: globals.mocha },
         linterOptions: { reportUnusedDisableDirectives: true },
-        settings: {
-            n: { allowModules: ["#eslint-rule-tester"] }, // the plugin does not support import-maps yet.
-        },
     },
     {
         ignores: [
             ".nyc_output/",
             "coverage/",
             "docs/",
             "lib/converted-esm/",
-            "test/fixtures/",
+            "tests/fixtures/",
         ],
     },
     js.configs.recommended,

lib/rules/shebang.js

@@ -5,8 +5,11 @@
 "use strict"
 
 const path = require("path")
+const matcher = require("ignore")
+
 const getConvertPath = require("../util/get-convert-path")
 const getPackageJson = require("../util/get-package-json")
+const getNpmignore = require("../util/get-npmignore")
 
 const NODE_SHEBANG = "#!/usr/bin/env node\n"
 const SHEBANG_PATTERN = /^(#!.+?)?(\r)?\n/u
@@ -66,6 +69,7 @@ function getShebangInfo(sourceCode) {
     }
 }
 
+/** @type {import('eslint').Rule.RuleModule} */
 module.exports = {
     meta: {
         docs: {
@@ -79,8 +83,12 @@ module.exports = {
             {
                 type: "object",
                 properties: {
-                    //
                     convertPath: getConvertPath.schema,
+                    ignoreUnpublished: { type: "boolean" },
+                    additionalExecutables: {
+                        type: "array",
+                        items: { type: "string" },
+                    },
                 },
                 additionalProperties: false,
             },
@@ -95,30 +103,60 @@ module.exports = {
     },
     create(context) {
         const sourceCode = context.sourceCode ?? context.getSourceCode() // TODO: just use context.sourceCode when dropping eslint < v9
-        let filePath = context.filename ?? context.getFilename()
+        const filePath = context.filename ?? context.getFilename()
         if (filePath === "<input>") {
             return {}
         }
-        filePath = path.resolve(filePath)
 
         const p = getPackageJson(filePath)
         if (!p) {
             return {}
         }
 
-        const basedir = path.dirname(p.filePath)
-        filePath = path.join(
-            basedir,
-            getConvertPath(context)(
-                path.relative(basedir, filePath).replace(/\\/gu, "/")
-            )
+        const packageDirectory = path.dirname(p.filePath)
+
+        const originalAbsolutePath = path.resolve(filePath)
+        const originalRelativePath = path
+            .relative(packageDirectory, originalAbsolutePath)
+            .replace(/\\/gu, "/")
+
+        const convertedRelativePath =
+            getConvertPath(context)(originalRelativePath)
+        const convertedAbsolutePath = path.resolve(
+            packageDirectory,
+            convertedRelativePath
         )
 
-        const needsShebang = isBinFile(filePath, p.bin, basedir)
+        const { additionalExecutables = [] } = context.options?.[0] ?? {}
+
+        const executable = matcher()
+        executable.add(additionalExecutables)
+        const isExecutable = executable.test(convertedRelativePath)
+
+        if (
+            (additionalExecutables.length === 0 ||
+                isExecutable.ignored === false) &&
+            context.options?.[0]?.ignoreUnpublished === true
+        ) {
+            const npmignore = getNpmignore(convertedAbsolutePath)
+
+            if (npmignore.match(convertedRelativePath)) {
+                return {}
+            }
+        }
+
+        const needsShebang =
+            isExecutable.ignored === true ||
+            isBinFile(convertedAbsolutePath, p.bin, packageDirectory)
         const info = getShebangInfo(sourceCode)
 
         return {
-            Program(node) {
+            Program() {
+                const loc = {
+                    start: { line: 1, column: 0 },
+                    end: { line: 1, column: sourceCode.lines.at(0).length },
+                }
+
                 if (
                     needsShebang
                         ? NODE_SHEBANG_PATTERN.test(info.shebang)
@@ -128,7 +166,7 @@ module.exports = {
                     // Checks BOM and \r.
                     if (needsShebang && info.bom) {
                         context.report({
-                            node,
+                            loc,
                             messageId: "unexpectedBOM",
                             fix(fixer) {
                                 return fixer.removeRange([-1, 0])
@@ -137,7 +175,7 @@ module.exports = {
                     }
                     if (needsShebang && info.cr) {
                         context.report({
-                            node,
+                            loc,
                             messageId: "expectedLF",
                             fix(fixer) {
                                 const index = sourceCode.text.indexOf("\r")
@@ -148,7 +186,7 @@ module.exports = {
                 } else if (needsShebang) {
                     // Shebang is lacking.
                     context.report({
-                        node,
+                        loc,
                         messageId: "expectedHashbangNode",
                         fix(fixer) {
                             return fixer.replaceTextRange(
@@ -160,7 +198,7 @@ module.exports = {
                 } else {
                     // Shebang is extra.
                     context.report({
-                        node,
+                        loc,
                         messageId: "expectedHashbang",
                         fix(fixer) {
                             return fixer.removeRange([0, info.length])

tests/fixtures/shebang/unpublished/package.json

@@ -0,0 +1,7 @@
+{
+    "name": "test",
+    "version": "0.0.0",
+    "files": [
+        "./published.js"
+    ]
+}