Merge pull request #135 from carlocorradini/bin

feat: configure shellcheck binary via env variable

.vscode/settings.json

@@ -1,9 +1,15 @@
 {
   "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "typescript.tsdk": "./node_modules/typescript/lib",
   "typescript.enablePromptUseWorkspaceTsdk": true,
   "[jsonc]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[markdown]": {
+    "editor.wordWrap": "off"
   }
 }

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v3.1.0](https://github.com/gunar/shellcheck/releases/tag/v3.1.0) - 2025-01-31
+
+### Added
+
+- Configure binary path via environment variable `SHELLCHECKJS_BIN`
+
+### Removed
+
+- `binDir` configuration option. Configuration `bin` now contains the complete path to the ShellCheck executable binary (including both binary directory and binary name)
+
 ## [v3.0.0](https://github.com/gunar/shellcheck/releases/tag/v3.0.0) - 2024-06-06
 
 ### Added

README.md

@@ -1,3 +1,5 @@
+<!-- markdownlint-disable MD033 -->
+
 # shellcheck
 
 [![ci](https://github.com/gunar/shellcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/gunar/shellcheck/actions/workflows/ci.yml)
@@ -37,10 +39,11 @@ Execute `shellcheck` directly from your npm scripts:
 
 ### Environment Variables
 
-| **Name**                    | **Values**                                                 | **Default** | **Description**                                                        |
-| :-------------------------- | :--------------------------------------------------------- | :---------- | :--------------------------------------------------------------------- |
-| `SHELLCHECKJS_RELEASE`      | `latest` \| `v(0\|[1-9]\d*)\.(0\|[1-9]\d*)\.(0\|[1-9]\d*)` | `latest`    | Release version. See <https://github.com/koalaman/shellcheck/releases> |
-| `SHELLCHECKJS_LOGGER_LEVEL` | `off` \| `debug` \| `info` \| `warn` \| `error`            | `info`      | Logger level                                                           |
+| **Name**                    | **Values**                                                 | **Default**                                                                   | **Description**                                                        |
+| :-------------------------- | :--------------------------------------------------------- | :---------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
+| `SHELLCHECKJS_RELEASE`      | `latest` \| `v(0\|[1-9]\d*)\.(0\|[1-9]\d*)\.(0\|[1-9]\d*)` | `latest`                                                                      | Release version. See <https://github.com/koalaman/shellcheck/releases> |
+| `SHELLCHECK_BIN`            | Any valid path to an executable binary file                | _linux_ or _darwin_: `./bin/shellcheck` <br/> _win32_: `.\bin\shellcheck.exe` | ShellCheck executable binary path                                      |
+| `SHELLCHECKJS_LOGGER_LEVEL` | `off` \| `debug` \| `info` \| `warn` \| `error`            | `info`                                                                        | Logger level                                                           |
 
 ### Programmatic
 
@@ -79,7 +82,7 @@ await shellcheck({
  */
 await download({
   destination: `path/to/destination/shellcheck`
-  // destination: `path/to/destination/${config.bin}` // Platform-dependent name (add .exe on Windows)
+  // destination: `path\\to\\destination\\shellcheck.exe` // Windows
   // Options...
 });
 ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellcheck",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "private": false,
   "description": "Wrapper to download shellcheck",
   "keywords": [

src/configs/config.ts

@@ -1,6 +1,5 @@
 import type fs from 'node:fs';
 import url from 'node:url';
-import path from 'node:path';
 import type {
   NonEmptyArray,
   Release,
@@ -15,13 +14,9 @@ import { env } from './env';
  */
 export type Config = {
   /**
-   * Binary name.
+   * Binary path.
    */
   bin: string;
-  /**
-   * Binary directory.
-   */
-  binDir: string;
   /**
    * Access permissions.
    */
@@ -73,8 +68,7 @@ export type Config = {
  * Configuration.
  */
 export const config: Config = {
-  bin: `shellcheck${process.platform === 'win32' ? '.exe' : ''}`,
-  binDir: path.normalize(`${__dirname}/../../bin`),
+  bin: env.SHELLCHECKJS_BIN,
   mode: 0o755,
   downloadURL: new url.URL(
     `https://github.com/vscode-shellcheck/shellcheck-binaries/releases/download`

src/configs/env.ts

@@ -1,4 +1,6 @@
 import * as envalid from 'envalid';
+import path from 'node:path';
+import fs from 'node:fs';
 import type { Release } from '~/types';
 import { LoggerLevel } from '~/logger/LoggerLevel';
 import { arrayOfAll } from '~/utils/arrayOfAll';
@@ -17,13 +19,39 @@ const releaseValidator = envalid.makeValidator<Release>((input: string) => {
   return input;
 });
 
+const binValidator = envalid.makeValidator<string>((input: string) => {
+  try {
+    fs.accessSync(
+      input,
+      // eslint-disable-next-line no-bitwise
+      fs.constants.F_OK | fs.constants.W_OK | fs.constants.X_OK
+    );
+  } catch (err: unknown) {
+    throw new envalid.EnvError(
+      `Invalid ShellCheck binary: ${err instanceof Error ? err.message : err}`
+    );
+  }
+
+  return input;
+});
+
 export const env = envalid.cleanEnv(process.env, {
-  [`${ENV_PREFIX}_RELEASE`]: releaseValidator<Release>({
+  [`${ENV_PREFIX}_RELEASE`]: releaseValidator({
     default: 'latest',
     desc: 'Release version or latest',
     example: '`latest` or `v0.10.0`',
     docs: 'https://github.com/koalaman/shellcheck/releases'
   }),
+  [`${ENV_PREFIX}_BIN`]: binValidator({
+    default: path.normalize(
+      path.resolve(
+        `${__dirname}/../../bin`,
+        `shellcheck${process.platform === 'win32' ? '.exe' : ''}`
+      )
+    ),
+    desc: 'ShellCheck binary path',
+    example: '`/path/to/shellcheck` or `C:\\path\\to\\shellcheck.exe`'
+  }),
   [`${ENV_PREFIX}_LOGGER_LEVEL`]: envalid.str<LoggerLevel>({
     default: LoggerLevel.INFO,
     choices: arrayOfAll<LoggerLevel>()([

src/shellcheck.ts

@@ -1,5 +1,4 @@
 import fs from 'node:fs/promises';
-import path from 'node:path';
 import process from 'node:process';
 import child_process from 'node:child_process';
 import { config } from '~/configs';
@@ -39,7 +38,7 @@ export async function shellcheck(
   args?: ShellCheckArgs
 ): Promise<child_process.SpawnSyncReturns<Buffer>> {
   const opts: Required<Omit<ShellCheckArgs, 'token'>> & { token?: string } = {
-    bin: args?.bin ?? path.normalize(`${config.binDir}/${config.bin}`),
+    bin: args?.bin ?? config.bin,
     args: args?.args ?? process.argv.slice(2),
     stdio: args?.stdio ?? 'pipe',
     token: args?.token ?? process.env.GITHUB_TOKEN