@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/dist/rules/resolve-declaration-convention.js

@@ -0,0 +1,109 @@
+/**
+ * The key a convention is bound under, both in a consuming rule's options
+ * object and in the plugin's `settings.sh` namespace.
+ */
+const DECLARATION_CONVENTION_KEY = 'declarationConvention';
+/** `value` is an object (not `null`) whose properties can be read. */
+function isObjectLike(value) {
+    return (typeof value === 'object' || typeof value === 'function') && value !== null;
+}
+/** A short description of a value that is not a convention, for an error message. */
+function describeValue(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    if (isObjectLike(value)) {
+        return typeof value.declaredCommands === 'undefined'
+            ? 'an object with no `declaredCommands` method'
+            : `an object whose \`declaredCommands\` is ${typeof value.declaredCommands}, not a function`;
+    }
+    switch (typeof value) {
+        case 'string':
+            return `string ${JSON.stringify(value)}`;
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+        case 'symbol':
+            return `${typeof value} ${String(value)}`;
+        default:
+            return typeof value;
+    }
+}
+/**
+ * Checks that `value`, configured at `setting`, implements
+ * {@link DeclarationConvention}: a `declaredCommands` function, and, when a
+ * `removeDeclaration` or `declarationHint` hook is present at all, a function
+ * there too. Throws an
+ * error naming `setting` otherwise.
+ */
+function assertDeclarationConvention(value, setting) {
+    const expected = 'expected a declaration convention: an object with a `declaredCommands(sourceCode)` method';
+    if (!isObjectLike(value) || typeof value.declaredCommands !== 'function') {
+        throw new Error(`Invalid ${setting}: ${expected}, but got ${describeValue(value)}.`);
+    }
+    for (const hook of ['removeDeclaration', 'declarationHint']) {
+        if (value[hook] !== undefined && typeof value[hook] !== 'function') {
+            throw new Error(`Invalid ${setting}: its optional \`${hook}\` hook must be a function when present, but got ${typeof value[hook]}.`);
+        }
+    }
+}
+/**
+ * Resolves the declaration convention bound for the rule running in
+ * `context`: the rule's `declarationConvention` option, else
+ * `settings.sh.declarationConvention`, else `null` (the rule is inert).
+ *
+ * Throws an `Error` naming the offending setting when the configured value is
+ * present but does not implement `declaredCommands` (or has a non-function
+ * `removeDeclaration`). The message names where the value came from and what
+ * it was, for example one beginning
+ * `Invalid settings.sh.declarationConvention: expected a declaration convention`
+ * and ending `but got string "jq".` Call it from `create()`, so the error
+ * surfaces as ESLint's
+ * configuration message for the file being linted.
+ *
+ * A rule that receives `null` should register no listeners: with no
+ * convention bound, a convention consumer has nothing to check.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   defineShellRule,
+ *   readDeclaredCommands,
+ *   resolveDeclarationConvention,
+ * } from '@eslint-sh/eslint-plugin';
+ *
+ * export const maxDeclaredCommands = defineShellRule({
+ *   meta: { schema: [], messages: { tooMany: 'Declare at most 5 commands.' } },
+ *   create(context) {
+ *     const convention = resolveDeclarationConvention(context);
+ *     if (convention === null) return {};
+ *     return {
+ *       File(node) {
+ *         // Validated declarations for the file `context` is linting.
+ *         if (readDeclaredCommands(convention, context).length > 5) {
+ *           context.report({ node, messageId: 'tooMany' });
+ *         }
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export function resolveDeclarationConvention(context) {
+    const ruleOptions = context.options[0];
+    if (isObjectLike(ruleOptions) && ruleOptions[DECLARATION_CONVENTION_KEY] !== undefined) {
+        const fromOption = ruleOptions[DECLARATION_CONVENTION_KEY];
+        assertDeclarationConvention(fromOption, `option \`${DECLARATION_CONVENTION_KEY}\` of rule "${context.id}"`);
+        return fromOption;
+    }
+    const shSettings = context.settings.sh;
+    if (isObjectLike(shSettings) && shSettings[DECLARATION_CONVENTION_KEY] !== undefined) {
+        const fromSettings = shSettings[DECLARATION_CONVENTION_KEY];
+        assertDeclarationConvention(fromSettings, `settings.sh.${DECLARATION_CONVENTION_KEY}`);
+        return fromSettings;
+    }
+    return null;
+}

package/dist/rules/resolve-network-wrapper.d.ts

@@ -0,0 +1,19 @@
+import type { WrapperSpec } from 'sh-ast/analyze';
+/**
+ * Reads `settings.sh.networkWrapper`: the configured name or `WrapperSpec`,
+ * or `undefined` when it is not set. Throws an error that starts
+ * `Invalid settings.sh.networkWrapper:` when the value is malformed. Call it
+ * from `create()`, so the error surfaces as ESLint's configuration message.
+ *
+ * @internal
+ */
+export declare function readNetworkWrapperSetting(settings: Readonly<Record<string, unknown>>): string | WrapperSpec | undefined;
+/**
+ * The `WrapperSpec` for the network wrapper set in `settings.sh.networkWrapper`,
+ * for a rule that looks through wrappers, or `null` when none is set. A name
+ * that is one of `sh-ast/analyze`'s default wrappers (`timeout`) keeps that
+ * entry's known options; any other name is a wrapper with no options.
+ *
+ * @internal
+ */
+export declare function networkWrapperSpec(settings: Readonly<Record<string, unknown>>): WrapperSpec | null;

package/dist/rules/resolve-network-wrapper.js

@@ -0,0 +1,116 @@
+/**
+ * The shared `settings.sh.networkWrapper` binding: the one place a project
+ * names the wrapper its network commands must run through, so every rule
+ * whose findings depend on that wrapper reads the same declaration.
+ *
+ * Two different statements are involved, and this setting makes only one of
+ * them:
+ *
+ * - **Policy:** network commands must run through this wrapper. That is what
+ *   `sh/require-network-wrapper` enforces, and this setting states it.
+ * - **Fact:** this wrapper runs the command named after it. The policy implies
+ *   the fact (a wrapper that encloses `curl` runs `curl`), so
+ *   `sh/no-undeclared-commands` and `sh/no-unused-declarations` look through
+ *   the network wrapper when it is set here. The converse does not hold: a
+ *   transparent wrapper such as `with-lock` is not the network wrapper, and
+ *   stays in those rules' `transparentWrappers` option.
+ *
+ * ESLint gives a rule no way to read another rule's options, so a wrapper set
+ * only as `require-network-wrapper`'s `wrapper` option is invisible to the
+ * declaration rules. Shared settings are visible to every rule; that is why
+ * the one declaration lives here.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+/** The setting's dotted path, as error messages name it. */
+const SETTING = 'settings.sh.networkWrapper';
+/**
+ * The `WrapperSpec` fields the setting accepts: the JSON-expressible ones,
+ * the same set `sh/require-network-wrapper`'s `wrapper` option schema allows.
+ */
+const STRING_LIST_FIELDS = ['noArgFlags', 'argFlags', 'unresolvableFlags', 'stopsChainFlags'];
+const ASSIGNMENT_OPERANDS = ['shell-identifier', 'env', 'sudo'];
+const KNOWN_FIELDS = new Set([
+    'names',
+    ...STRING_LIST_FIELDS,
+    'positionalOperandsBeforeCommand',
+    'assignmentOperands',
+]);
+/** `true` when `value` is an array of non-empty strings. */
+function isStringList(value) {
+    return (Array.isArray(value) &&
+        value.every((item) => typeof item === 'string' && item.length > 0));
+}
+/** Throws the setting's configuration error with `detail`. */
+function invalid(detail) {
+    throw new Error(`Invalid ${SETTING}: ${detail}`);
+}
+/**
+ * Checks a configured value and returns it typed: a non-empty command name,
+ * or a `WrapperSpec` object made of the JSON-expressible fields.
+ */
+function validate(value) {
+    if (typeof value === 'string') {
+        if (value.length === 0)
+            invalid('expected a command name or a wrapper spec, but got "".');
+        return value;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        const got = value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
+        invalid(`expected a command name or a wrapper spec ({ names: [...] }), but got ${got}.`);
+    }
+    const spec = value;
+    for (const key of Object.keys(spec)) {
+        if (!KNOWN_FIELDS.has(key))
+            invalid(`unknown wrapper spec field \`${key}\`.`);
+    }
+    if (!isStringList(spec.names) || spec.names.length === 0) {
+        invalid('`names` must be a non-empty array of non-empty strings.');
+    }
+    for (const field of STRING_LIST_FIELDS) {
+        if (spec[field] !== undefined && !isStringList(spec[field])) {
+            invalid(`\`${field}\` must be an array of non-empty strings.`);
+        }
+    }
+    const positional = spec.positionalOperandsBeforeCommand;
+    if (positional !== undefined && !(Number.isInteger(positional) && positional >= 0)) {
+        invalid('`positionalOperandsBeforeCommand` must be a non-negative integer.');
+    }
+    const assignment = spec.assignmentOperands;
+    if (assignment !== undefined && !ASSIGNMENT_OPERANDS.includes(assignment)) {
+        invalid(`\`assignmentOperands\` must be one of ${ASSIGNMENT_OPERANDS.join(', ')}.`);
+    }
+    return spec;
+}
+/**
+ * Reads `settings.sh.networkWrapper`: the configured name or `WrapperSpec`,
+ * or `undefined` when it is not set. Throws an error that starts
+ * `Invalid settings.sh.networkWrapper:` when the value is malformed. Call it
+ * from `create()`, so the error surfaces as ESLint's configuration message.
+ *
+ * @internal
+ */
+export function readNetworkWrapperSetting(settings) {
+    const sh = settings.sh;
+    if (typeof sh !== 'object' || sh === null)
+        return undefined;
+    const value = sh.networkWrapper;
+    return value === undefined ? undefined : validate(value);
+}
+/**
+ * The `WrapperSpec` for the network wrapper set in `settings.sh.networkWrapper`,
+ * for a rule that looks through wrappers, or `null` when none is set. A name
+ * that is one of `sh-ast/analyze`'s default wrappers (`timeout`) keeps that
+ * entry's known options; any other name is a wrapper with no options.
+ *
+ * @internal
+ */
+export function networkWrapperSpec(settings) {
+    const wrapper = readNetworkWrapperSetting(settings);
+    if (wrapper === undefined)
+        return null;
+    if (typeof wrapper !== 'string')
+        return wrapper;
+    return (DEFAULT_TRANSPARENT_WRAPPERS.find((spec) => spec.names.includes(wrapper)) ?? {
+        names: [wrapper],
+    });
+}

package/dist/rules/set-options.d.ts

@@ -0,0 +1,109 @@
+/**
+ * A model of the shell's `set` option-flag syntax, shared by rules that ask
+ * "which shell options does this `set` command (or this shell invocation)
+ * turn on or off?".
+ *
+ * It knows two things and nothing else:
+ *
+ * - the option names `set -o` accepts in bash and POSIX sh, and the
+ *   single-letter flag each one has (if any);
+ * - how `set` reads its arguments: `-abc` / `+abc` flag clusters, where each
+ *   `o` in a cluster consumes the next argument as a long option name;
+ *   `--` and a lone `-` end option processing; and the first argument that is
+ *   not a flag cluster starts the positional parameters.
+ *
+ * It does not resolve words. Callers pass each argument's static text, or
+ * `null` for an argument whose text is not statically known; resolution is
+ * the `ShellSourceCode` helpers' job.
+ *
+ * @see https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
+ * @see https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#set
+ */
+/** The long option names in {@link SET_OPTION_FLAGS}, in table order. @internal */
+export declare const SET_OPTION_NAMES: readonly string[];
+/**
+ * One option change a `set`-style argument list asks for: turn the named
+ * option on (`enable: true`, from `-x` / `-o name`) or off (`enable: false`,
+ * from `+x` / `+o name`).
+ *
+ * @internal
+ */
+export interface SetOptionChange {
+    /** The long option name, e.g. `errexit`. */
+    readonly option: string;
+    /** `true` for a `-` flag, `false` for a `+` flag. */
+    readonly enable: boolean;
+}
+/**
+ * What {@link parseSetArguments} read from an argument list.
+ *
+ * @internal
+ */
+export interface ParsedSetArguments {
+    /** The option changes, in the order the shell applies them. */
+    readonly changes: readonly SetOptionChange[];
+    /**
+     * Why option processing stopped before the end of the list, or `undefined`
+     * when every argument was an option flag (or an option name an `o` consumed):
+     *
+     * - `operand`: an argument that is not a flag cluster (or `--`, or a lone
+     *   `-`) starts the positional parameters;
+     * - `unknown`: an argument's text is not statically known, so neither it nor
+     *   anything after it can be read;
+     * - `malformed`: a cluster names a letter `set` does not have, or an `o` has
+     *   no option name after it, or names an option `set` does not have.
+     */
+    readonly stoppedBy: 'operand' | 'unknown' | 'malformed' | undefined;
+}
+/**
+ * Reads a `set`-style argument list (the arguments after the command word, so
+ * `["-euo", "pipefail"]` for `set -euo pipefail`) into the option changes it
+ * makes, without applying them.
+ *
+ * Changes found before processing stops are kept: `set -e "$x"` still enables
+ * `errexit`, then stops (`unknown`) at `"$x"`, whose expansion could be
+ * anything. A lone `-` turns off `xtrace` and `verbose` (POSIX) and ends option
+ * processing, as `--` does. A lone `+` changes nothing and does not end
+ * option processing: bash and dash both read `set + -e` as `set -e`.
+ *
+ * @param args - Each argument's static text, or `null` when it is not static.
+ * @internal
+ */
+export declare function parseSetArguments(args: readonly (string | null)[]): ParsedSetArguments;
+/**
+ * Applies `changes` to `enabled` in order, so a later `+e` undoes an earlier
+ * `-e`. Mutates and returns `enabled`.
+ *
+ * @internal
+ */
+export declare function applySetOptionChanges(enabled: Set<string>, changes: readonly SetOptionChange[]): Set<string>;
+/**
+ * Spells a `set` command that enables exactly `options`, preferring each
+ * option's single-letter flag: the letters form one cluster (in the given
+ * order), the first letterless option is attached to that cluster through a
+ * trailing `o`, and any further letterless options follow as `-o <name>`.
+ * So `["errexit", "nounset", "pipefail"]` is `set -euo pipefail`.
+ *
+ * @param options - Long option names from {@link SET_OPTION_NAMES}; at least one.
+ * @internal
+ */
+export declare function formatSetCommand(options: readonly string[]): string;
+/**
+ * The option changes the shebang line passes to the shell (read by
+ * `require-strict-mode`'s `allowShebangOnly` and by
+ * `compat/no-nounset-empty-array`). Only spellings the kernel hands to the shell as written
+ * are read:
+ *
+ * - `#!/path/to/shell <word>`: the kernel passes everything after the
+ *   interpreter as one argument, so exactly one flag word is read
+ *   (`#!/bin/bash -eu`); more than one word (`#!/bin/bash -e -u`) arrives as a
+ *   single argument the shell rejects, and counts as nothing.
+ * - `#!/usr/bin/env -S <shell> <words…>`: `env -S` splits the rest into words,
+ *   so every word after the shell name is read.
+ *
+ * Plain `#!/usr/bin/env <shell> <flags>` counts as nothing: without `-S`,
+ * Linux passes `<shell> <flags>` to `env` as one command name.
+ *
+ * @internal
+ */
+export declare function shebangOptionChanges(text: string): readonly SetOptionChange[];

package/dist/rules/set-options.js

@@ -0,0 +1,201 @@
+/**
+ * A model of the shell's `set` option-flag syntax, shared by rules that ask
+ * "which shell options does this `set` command (or this shell invocation)
+ * turn on or off?".
+ *
+ * It knows two things and nothing else:
+ *
+ * - the option names `set -o` accepts in bash and POSIX sh, and the
+ *   single-letter flag each one has (if any);
+ * - how `set` reads its arguments: `-abc` / `+abc` flag clusters, where each
+ *   `o` in a cluster consumes the next argument as a long option name;
+ *   `--` and a lone `-` end option processing; and the first argument that is
+ *   not a flag cluster starts the positional parameters.
+ *
+ * It does not resolve words. Callers pass each argument's static text, or
+ * `null` for an argument whose text is not statically known; resolution is
+ * the `ShellSourceCode` helpers' job.
+ *
+ * @see https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
+ * @see https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#set
+ */
+/**
+ * Every long option name `set -o` accepts in bash or POSIX sh, mapped to the
+ * single-letter flag that toggles the same option, or `undefined` when the
+ * option has no letter (and can only be spelled `-o <name>`).
+ *
+ * @internal
+ */
+const SET_OPTION_FLAGS = Object.freeze({
+    allexport: 'a',
+    braceexpand: 'B',
+    emacs: undefined,
+    errexit: 'e',
+    errtrace: 'E',
+    functrace: 'T',
+    hashall: 'h',
+    histexpand: 'H',
+    history: undefined,
+    ignoreeof: undefined,
+    'interactive-comments': undefined,
+    keyword: 'k',
+    monitor: 'm',
+    noclobber: 'C',
+    noexec: 'n',
+    noglob: 'f',
+    nolog: undefined,
+    notify: 'b',
+    nounset: 'u',
+    onecmd: 't',
+    physical: 'P',
+    pipefail: undefined,
+    posix: undefined,
+    privileged: 'p',
+    verbose: 'v',
+    vi: undefined,
+    xtrace: 'x',
+});
+/** The long option names in {@link SET_OPTION_FLAGS}, in table order. @internal */
+export const SET_OPTION_NAMES = Object.freeze(Object.keys(SET_OPTION_FLAGS));
+/** Single-letter flag → the long option name it toggles (the inverse of {@link SET_OPTION_FLAGS}). */
+const OPTION_NAME_BY_FLAG = new Map(Object.entries(SET_OPTION_FLAGS).flatMap(([name, flag]) => flag === undefined ? [] : [[flag, name]]));
+/**
+ * Reads a `set`-style argument list (the arguments after the command word, so
+ * `["-euo", "pipefail"]` for `set -euo pipefail`) into the option changes it
+ * makes, without applying them.
+ *
+ * Changes found before processing stops are kept: `set -e "$x"` still enables
+ * `errexit`, then stops (`unknown`) at `"$x"`, whose expansion could be
+ * anything. A lone `-` turns off `xtrace` and `verbose` (POSIX) and ends option
+ * processing, as `--` does. A lone `+` changes nothing and does not end
+ * option processing: bash and dash both read `set + -e` as `set -e`.
+ *
+ * @param args - Each argument's static text, or `null` when it is not static.
+ * @internal
+ */
+export function parseSetArguments(args) {
+    const changes = [];
+    let index = 0;
+    while (index < args.length) {
+        const arg = args[index];
+        index += 1;
+        if (arg === null)
+            return { changes, stoppedBy: 'unknown' };
+        if (arg === '--')
+            return { changes, stoppedBy: undefined };
+        if (arg === '-') {
+            changes.push({ option: 'xtrace', enable: false }, { option: 'verbose', enable: false });
+            return { changes, stoppedBy: undefined };
+        }
+        if (arg === '+')
+            continue;
+        const sign = arg[0];
+        if ((sign !== '-' && sign !== '+') || arg.length < 2)
+            return { changes, stoppedBy: 'operand' };
+        const enable = sign === '-';
+        for (const flag of arg.slice(1)) {
+            if (flag === 'o') {
+                const name = index < args.length ? args[index] : undefined;
+                index += 1;
+                if (name === null)
+                    return { changes, stoppedBy: 'unknown' };
+                if (name === undefined || !Object.hasOwn(SET_OPTION_FLAGS, name)) {
+                    return { changes, stoppedBy: 'malformed' };
+                }
+                changes.push({ option: name, enable });
+                continue;
+            }
+            const option = OPTION_NAME_BY_FLAG.get(flag);
+            if (option === undefined)
+                return { changes, stoppedBy: 'malformed' };
+            changes.push({ option, enable });
+        }
+    }
+    return { changes, stoppedBy: undefined };
+}
+/**
+ * Applies `changes` to `enabled` in order, so a later `+e` undoes an earlier
+ * `-e`. Mutates and returns `enabled`.
+ *
+ * @internal
+ */
+export function applySetOptionChanges(enabled, changes) {
+    for (const { option, enable } of changes) {
+        if (enable)
+            enabled.add(option);
+        else
+            enabled.delete(option);
+    }
+    return enabled;
+}
+/**
+ * Spells a `set` command that enables exactly `options`, preferring each
+ * option's single-letter flag: the letters form one cluster (in the given
+ * order), the first letterless option is attached to that cluster through a
+ * trailing `o`, and any further letterless options follow as `-o <name>`.
+ * So `["errexit", "nounset", "pipefail"]` is `set -euo pipefail`.
+ *
+ * @param options - Long option names from {@link SET_OPTION_NAMES}; at least one.
+ * @internal
+ */
+export function formatSetCommand(options) {
+    const letters = options.flatMap((option) => SET_OPTION_FLAGS[option] ?? []).join('');
+    const longOnly = options.filter((option) => SET_OPTION_FLAGS[option] === undefined);
+    const words = ['set'];
+    let remaining = longOnly;
+    if (letters.length > 0) {
+        if (longOnly.length === 0) {
+            words.push(`-${letters}`);
+        }
+        else {
+            const [first, ...rest] = longOnly;
+            words.push(`-${letters}o`, first);
+            remaining = rest;
+        }
+    }
+    for (const option of remaining)
+        words.push('-o', option);
+    return words.join(' ');
+}
+/**
+ * The option changes the shebang line passes to the shell (read by
+ * `require-strict-mode`'s `allowShebangOnly` and by
+ * `compat/no-nounset-empty-array`). Only spellings the kernel hands to the shell as written
+ * are read:
+ *
+ * - `#!/path/to/shell <word>`: the kernel passes everything after the
+ *   interpreter as one argument, so exactly one flag word is read
+ *   (`#!/bin/bash -eu`); more than one word (`#!/bin/bash -e -u`) arrives as a
+ *   single argument the shell rejects, and counts as nothing.
+ * - `#!/usr/bin/env -S <shell> <words…>`: `env -S` splits the rest into words,
+ *   so every word after the shell name is read.
+ *
+ * Plain `#!/usr/bin/env <shell> <flags>` counts as nothing: without `-S`,
+ * Linux passes `<shell> <flags>` to `env` as one command name.
+ *
+ * @internal
+ */
+export function shebangOptionChanges(text) {
+    if (!text.startsWith('#!'))
+        return [];
+    const lineEnd = text.search(/\r?\n|\r/u);
+    const words = text
+        .slice(2, lineEnd === -1 ? undefined : lineEnd)
+        .trim()
+        .split(/\s+/u);
+    const [interpreter = '', ...rest] = words;
+    const isEnv = interpreter === 'env' || interpreter.endsWith('/env');
+    let flagWords;
+    if (isEnv) {
+        const [split, , ...shellArgs] = rest;
+        if (split !== '-S' && split !== '--split-string')
+            return [];
+        flagWords = shellArgs;
+    }
+    else {
+        if (rest.length !== 1)
+            return [];
+        flagWords = rest;
+    }
+    return parseSetArguments(flagWords).changes;
+}

package/dist/rules/shebang-interpreter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared reading of a shebang line's interpreter, so every rule that asks
+ * "which shell does this file name?" gets one answer instead of re-deriving it.
+ */
+/**
+ * The shell basename a shebang's interpreter part (everything after `#!`)
+ * runs, or `undefined` when it names no usable interpreter: either an absolute
+ * path (`/usr/local/bin/bash` → `bash`), or an absolute path to `env` whose
+ * command is the shell (`/usr/bin/env bash`, `/usr/bin/env -S bash -e` →
+ * `bash`). A relative interpreter (`#!bash`) yields `undefined`: the kernel
+ * would resolve it against the caller's working directory, not `PATH`.
+ *
+ * Which names count as a shell, and whether one agrees with the configured
+ * dialect, are the callers' questions; this only answers "what runs".
+ *
+ * @internal
+ */
+export declare function shebangShell(interpreterSpec: string): string | undefined;

package/dist/rules/shebang-interpreter.js

@@ -0,0 +1,81 @@
+/**
+ * Shared reading of a shebang line's interpreter, so every rule that asks
+ * "which shell does this file name?" gets one answer instead of re-deriving it.
+ */
+/**
+ * `env` options that consume the following word as their argument
+ * (GNU coreutils and BSD spellings). Skipping that word keeps it from being
+ * mistaken for the command `env` runs.
+ */
+const ENV_OPTIONS_WITH_ARGUMENT = new Set([
+    '-u',
+    '--unset',
+    '-C',
+    '--chdir',
+    '-P',
+]);
+/** A `NAME=value` word, which `env` treats as an environment assignment. */
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/u;
+/** The final path segment of `path` (`/usr/local/bin/bash` → `bash`). */
+function basename(path) {
+    return path.slice(path.lastIndexOf('/') + 1);
+}
+/**
+ * The command an `env` shebang runs, given the words after `env`, or
+ * `undefined` when there is none. Options, their arguments, and `NAME=value`
+ * assignments are skipped; `--` ends the options, but assignments after it
+ * still apply (GNU `env -- FOO=1 sh` runs `sh`). `-S` (split string) is transparent here because
+ * the shebang's words are already split on whitespace, so `env -S bash -e`
+ * runs `bash`.
+ */
+function envCommand(words) {
+    for (let index = 0; index < words.length; index++) {
+        const word = words[index];
+        if (word === '--') {
+            return words.slice(index + 1).find((operand) => !ENV_ASSIGNMENT.test(operand));
+        }
+        if (word === '-S' || word === '--split-string') {
+            continue;
+        }
+        if (word.startsWith('--split-string=')) {
+            return word.slice('--split-string='.length) || words[index + 1];
+        }
+        if (word.startsWith('-S')) {
+            return word.slice('-S'.length);
+        }
+        if (ENV_OPTIONS_WITH_ARGUMENT.has(word)) {
+            index++;
+            continue;
+        }
+        if (word.startsWith('-') || ENV_ASSIGNMENT.test(word)) {
+            continue;
+        }
+        return word;
+    }
+    return undefined;
+}
+/**
+ * The shell basename a shebang's interpreter part (everything after `#!`)
+ * runs, or `undefined` when it names no usable interpreter: either an absolute
+ * path (`/usr/local/bin/bash` → `bash`), or an absolute path to `env` whose
+ * command is the shell (`/usr/bin/env bash`, `/usr/bin/env -S bash -e` →
+ * `bash`). A relative interpreter (`#!bash`) yields `undefined`: the kernel
+ * would resolve it against the caller's working directory, not `PATH`.
+ *
+ * Which names count as a shell, and whether one agrees with the configured
+ * dialect, are the callers' questions; this only answers "what runs".
+ *
+ * @internal
+ */
+export function shebangShell(interpreterSpec) {
+    const [interpreter, ...args] = interpreterSpec.trim().split(/\s+/u);
+    if (!interpreter.startsWith('/')) {
+        return undefined;
+    }
+    const name = basename(interpreter);
+    if (name !== 'env') {
+        return name;
+    }
+    const command = envCommand(args);
+    return command === undefined ? undefined : basename(command);
+}

package/dist/rules/shebang-matches-dialect.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The rule's report kinds, one per direction of the bash/POSIX mismatch.
+ *
+ * @internal
+ */
+export type ShebangMatchesDialectMessageIds = 'posixShebangBashDialect' | 'bashShebangPosixDialect';
+/**
+ * The rule module registered as `shebang-matches-dialect`.
+ *
+ * @internal
+ */
+export declare const shebangMatchesDialect: import("./define-shell-rule.js").ShellRule<[], ShebangMatchesDialectMessageIds>;