@eslint-sh/eslint-plugin 0.7.0 → 0.8.0

package/dist/rules/no-unused-declarations.js

@@ -1,10 +1,9 @@
-import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { resolveTransparentWrappers } from './resolve-transparent-wrappers.js';
 import { harvestCommands } from '../command-harvest/harvest-commands.js';
 import { harvestWrapperTable } from '../command-harvest/wrapper-table.js';
 import { createRule } from './create-rule.js';
 import { readDeclaredCommands } from '../declaration-conventions/read-declared-commands.js';
 import { resolveDeclarationConvention } from './resolve-declaration-convention.js';
-import { networkWrapperSpec } from './resolve-network-wrapper.js';
 import { SHELL_WRAPPER } from './transparent-wrappers.js';
 /** The registry name of this rule (`sh/no-unused-declarations` in a user's config). */
 const RULE_NAME = 'no-unused-declarations';
@@ -54,29 +53,17 @@ function trapSetsCodeString(operands) {
 const SHELL_NAMES = new Set(SHELL_WRAPPER.names);
 /** The builtins that run another file's code in this shell: POSIX `.` and Bash's `source`. */
 const SOURCE_COMMANDS = new Set(['.', 'source']);
-/**
- * The wrappers whose path forms (`/bin/bash`, `/usr/bin/env`) the completeness
- * check also follows, by basename: shells invoked as commands and `env`,
- * the wrappers that can run an embedded command string. sh-ast matches
- * wrapper names exactly, so without this `/bin/bash -c '…'` would resolve to
- * the static command `/bin/bash`.
- */
-const PATH_FOLLOWED_WRAPPERS = [
-    SHELL_WRAPPER,
-    ...DEFAULT_TRANSPARENT_WRAPPERS.filter((spec) => spec.names.includes('env')),
-];
 /** The basename of `text` when it is a path (contains a slash), else `null`. */
 function pathBasename(text) {
     const slash = text.lastIndexOf('/');
     return slash === -1 ? null : text.slice(slash + 1);
 }
 /**
- * The effective command of `site` under `table`, also following a shell or
- * `env` named by path: while the effective command is a path whose basename
- * names one of {@link PATH_FOLLOWED_WRAPPERS}, that path is added as a
- * wrapper with the same spec and the site is resolved again. This mirrors how
- * `createWrapperRule` follows path-named wrappers. Each round adds a new
- * path, and a site has finitely many words, so the loop ends.
+ * The effective command of `site` under the resolved completeness `table`.
+ * Relative utility paths use only specs already in that table, including its
+ * shell-interpreter entries. Recreating a built-in spec here would undo a
+ * project's exact-name override and make completeness disagree with usage.
+ * Each round adds a new path from the finite argv, so the loop ends.
  */
 function resolveEffective(site, table) {
     let current = table;
@@ -89,7 +76,7 @@ function resolveEffective(site, table) {
         const base = pathBasename(path);
         if (base === null || current.some((spec) => spec.names.includes(path)))
             return resolution;
-        const spec = PATH_FOLLOWED_WRAPPERS.find((entry) => entry.names.includes(base));
+        const spec = current.find((entry) => entry.shellBuiltin !== true && entry.names.includes(base));
         if (spec === undefined)
             return resolution;
         current = [{ ...spec, names: [path] }, ...current];
@@ -177,19 +164,7 @@ export const noUnusedDeclarations = createRule({
             description: 'Disallow declaring external commands that a script never uses, per the configured declaration convention',
         },
         fixable: 'code',
-        schema: [
-            {
-                type: 'object',
-                properties: {
-                    transparentWrappers: {
-                        type: 'array',
-                        items: { type: 'string', minLength: 1 },
-                        uniqueItems: true,
-                    },
-                },
-                additionalProperties: false,
-            },
-        ],
+        schema: [],
         messages: {
             unusedDeclaration: "'{{command}}' is declared but never used. Remove the declaration so the script's stated dependencies match what it runs.",
             unusedFileDeclaration: "'{{command}}' is declared in {{source}} but this script never uses it. Remove it there so the script's stated dependencies match what it runs.",
@@ -202,7 +177,7 @@ export const noUnusedDeclarations = createRule({
             return {};
         }
         const { sourceCode } = context;
-        const transparentWrappers = harvestWrapperTable(sourceCode.dialect, context.options[0]?.transparentWrappers ?? [], networkWrapperSpec(context.settings));
+        const transparentWrappers = resolveTransparentWrappers(context, harvestWrapperTable(sourceCode.dialect));
         // The completeness check follows the harvest's table plus shells
         // invoked as commands, so `bash -c '…'` and `sh -c '…'` resolve to an
         // embedded command (as in `no-dynamic-invocation`) instead of stopping

package/dist/rules/prefer-local.js

@@ -165,12 +165,13 @@ export const preferLocal = createRule({
     },
     create(context) {
         const { sourceCode } = context;
-        // `local` is not POSIX: under `posix` there is nothing to declare with.
-        if (sourceCode.dialect === 'posix')
-            return {};
         const [options] = context.options;
         const allowed = new Set(options.allow ?? []);
         const allowPattern = compileUserPattern('sh/prefer-local', 'allowPattern', options.allowPattern ?? DEFAULT_ALLOW_PATTERN, 'u');
+        // Validate configuration in every dialect, even where the rule is inert.
+        // `local` is not POSIX: under `posix` there is nothing to declare with.
+        if (sourceCode.dialect === 'posix')
+            return {};
         const text = sourceCode.text;
         const lastpipe = enablesLastpipe(sourceCode.ast, sourceCode);
         // Names assigned or declared outside every function, with where each

package/dist/rules/quote-expansions.js

@@ -40,6 +40,7 @@
  */
 import { DashHdoc, Hdoc } from 'sh-ast/analyze';
 import { createRule } from './create-rule.js';
+import { isBashIntegerVariable } from './bash-variable-semantics.js';
 import { messageExcerpt } from '../language/line-breaks.js';
 /** The registry name of this rule (`sh/quote-expansions` in a user's config). */
 const RULE_NAME = 'quote-expansions';
@@ -50,33 +51,7 @@ const RULE_NAME = 'quote-expansions';
  * their values are arbitrary text.
  */
 const SINGLE_WORD_SPECIALS = new Set(['#', '?', '$', '!', '-']);
-/**
- * Bash variables that always expand to a decimal integer, so an unquoted
- * reference is one word with no glob characters, like the specials above.
- * Bash keeps them integers: assigning text to `RANDOM`, `SECONDS` or `OPTIND`
- * evaluates it arithmetically, `LINENO` and `BASH_SUBSHELL` ignore
- * assignments, and `PPID` is read-only; a hostile value in the environment is
- * ignored for each of them. Each exists in every Bash from 3.2, the oldest
- * target eslint-sh supports.
- *
- * Left out on purpose: `UID` and `EUID`, which Bash imports verbatim from the
- * environment (`env UID='a *' bash -c 'echo "[$UID]"'` prints `[a *]`), so
- * they can hold text that splits and globs; `BASHPID` (Bash 4.0), `EPOCHSECONDS` (5.0) and
- * `SRANDOM` (5.1), which an older Bash leaves unset, so an unquoted reference
- * there expands to no word at all; `EPOCHREALTIME`, whose decimal separator
- * follows the locale; and variables a script or the environment may set to
- * any text (`COLUMNS`, `SHLVL`). The list does not apply outside Bash: in a
- * POSIX shell such as dash these are ordinary variables.
- */
-const BASH_INTEGER_VARIABLES = new Set([
-    'RANDOM',
-    'SECONDS',
-    'LINENO',
-    'PPID',
-    'OPTIND',
-    'BASH_SUBSHELL',
-]);
-/** The dialects whose scripts run under Bash, where {@link BASH_INTEGER_VARIABLES} holds. */
+/** The dialects whose scripts run under Bash, where {@link isBashIntegerVariable} holds. */
 const BASH_DIALECTS = new Set(['bash', 'bats']);
 /** Redirection operators that introduce a here-document (`<<`, `<<-`). */
 const HEREDOC_OPERATORS = new Set([Hdoc, DashHdoc]);
@@ -94,7 +69,7 @@ function isSingleWordParamExp(node, bashIntegers) {
     }
     const name = node.param?.value;
     return (name !== undefined &&
-        (SINGLE_WORD_SPECIALS.has(name) || (bashIntegers && BASH_INTEGER_VARIABLES.has(name))) &&
+        (SINGLE_WORD_SPECIALS.has(name) || (bashIntegers && isBashIntegerVariable(name))) &&
         !node.excl &&
         node.exp === undefined &&
         node.repl === undefined &&

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

@@ -1,19 +1,3 @@
-/**
- * `sh/require-network-wrapper`: every network command must be run through the
- * project's configured wrapper (a retry, audit, or proxy helper).
- *
- * This is the built-in instance of `createWrapperRule`: the commands
- * default to common network clients, and the wrapper comes from the user's
- * rule's `wrapper` option, or else from the shared `settings.sh.networkWrapper`
- * (which the declaration rules also read). The wrapper has **no default**.
- * Which wrapper guards network calls is a project's policy, and a generic
- * linter must not invent it, so with neither set the rule is inert: it
- * registers no listeners, reports nothing, and never analyzes the file.
- *
- * `git` counts only for the subcommands that talk to a remote (`fetch`,
- * `clone`, `pull`, `push`), found after git's own global options
- * (`git -C dir fetch`).
- */
 import type { WrapperSpec } from 'sh-ast/analyze';
 /**
  * The options of `sh/require-network-wrapper`.
@@ -26,7 +10,8 @@ export interface RequireNetworkWrapperOptions {
     /**
      * The wrapper network commands must be run through: a name, or a
      * `WrapperSpec` declaring the wrapper's option shape. Unset falls back to
-     * `settings.sh.networkWrapper`; with neither, the rule is inert.
+     * `settings: { sh: { networkWrapper: 'with-retry' } }`; conflicting values
+     * throw instead of overriding the shared policy. With neither, the rule is inert.
      */
     readonly wrapper?: string | WrapperSpec;
     /** Commands checked in addition to `commands` (or its default). */

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

@@ -1,6 +1,23 @@
+/**
+ * `sh/require-network-wrapper`: every network command must be run through the
+ * project's configured wrapper (a retry, audit, or proxy helper).
+ *
+ * This is the built-in instance of `createWrapperRule`: the commands
+ * default to common network clients, and the wrapper comes from the user's
+ * shared `settings: { sh: { networkWrapper: 'with-retry' } }` or the local
+ * `wrapper` option. Conflicting values throw, so policies cannot silently disagree. The wrapper has **no default**.
+ * Which wrapper guards network calls is a project's policy, and a generic
+ * linter must not invent it, so with neither set the rule is inert: it
+ * registers no listeners, reports nothing, and never analyzes the file.
+ *
+ * `git` counts only for the subcommands that talk to a remote (`fetch`,
+ * `clone`, `pull`, `push`), found after git's own global options
+ * (`git -C dir fetch`).
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
 import { createRule } from './create-rule.js';
 import { WRAPPER_RULE_MESSAGES, buildWrapperRule } from './create-wrapper-rule.js';
-import { readNetworkWrapperSetting } from './resolve-network-wrapper.js';
+import { networkWrapperSpec, readNetworkWrapperSetting, sameWrapperSpec, } from './resolve-network-wrapper.js';
 /** The registry name of this rule (`sh/require-network-wrapper` in a user's config). */
 const RULE_NAME = 'require-network-wrapper';
 /**
@@ -182,6 +199,7 @@ const WRAPPER_SPEC_SCHEMA = {
         stopsChainFlags: STRING_LIST_SCHEMA,
         positionalOperandsBeforeCommand: { type: 'integer', minimum: 0 },
         assignmentOperands: { enum: ['shell-identifier', 'env', 'sudo'] },
+        shellBuiltin: { type: 'boolean' },
     },
     required: ['names'],
     additionalProperties: false,
@@ -191,9 +209,20 @@ const WRAPPER_SPEC_SCHEMA = {
  * `null` when no wrapper is configured.
  */
 function wrapperRuleConfig(options, settings) {
-    // The rule option wins; otherwise the shared setting, which the
-    // declaration rules read too (see `./resolve-network-wrapper.ts`).
-    const wrapper = options?.wrapper ?? readNetworkWrapperSetting(settings);
+    const shared = readNetworkWrapperSetting(settings);
+    if (options?.wrapper !== undefined && shared !== undefined) {
+        const configured = options.wrapper;
+        const option = typeof configured === 'string'
+            ? (DEFAULT_TRANSPARENT_WRAPPERS.find((spec) => spec.names.includes(configured)) ?? {
+                names: [configured],
+            })
+            : configured;
+        const network = networkWrapperSpec(settings);
+        if (network !== null && !sameWrapperSpec(option, network)) {
+            throw new Error('sh/require-network-wrapper: `wrapper` conflicts with the shared networkWrapper; configure one shared network policy.');
+        }
+    }
+    const wrapper = shared ?? options?.wrapper;
     if (wrapper === undefined)
         return null;
     return {

package/dist/rules/resolve-declaration-convention.d.ts

@@ -52,16 +52,15 @@ export interface DeclarationConventionBindingContext {
 /**
  * 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).
+ * `settings: { sh: { declarationConvention: convention } }`, 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.
+ * it was, including the expected convention shape and the received value.
+ * 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.

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

@@ -51,16 +51,15 @@ function assertDeclarationConvention(value, setting) {
 /**
  * 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).
+ * `settings: { sh: { declarationConvention: convention } }`, 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.
+ * it was, including the expected convention shape and the received value.
+ * 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.

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

@@ -1,4 +1,10 @@
 import type { WrapperSpec } from 'sh-ast/analyze';
+/**
+ * Checks a configured value and returns it typed: a non-empty command name,
+ * or a `WrapperSpec` object made of the JSON-expressible fields.
+ * @internal
+ */
+export declare function validateWrapperSetting(value: unknown, setting: string): string | WrapperSpec;
 /**
  * Reads `settings.sh.networkWrapper`: the configured name or `WrapperSpec`,
  * or `undefined` when it is not set. Throws an error that starts
@@ -17,3 +23,16 @@ export declare function readNetworkWrapperSetting(settings: Readonly<Record<stri
  * @internal
  */
 export declare function networkWrapperSpec(settings: Readonly<Record<string, unknown>>): WrapperSpec | null;
+/**
+ * Whether overlapping wrapper names receive the same effective matcher grammar.
+ * Extra aliases are independent facts, not a conflict for the shared names.
+ * @internal
+ */
+export declare function sameWrapperOptions(left: WrapperSpec, right: WrapperSpec): boolean;
+/**
+ * Whether both specs approve the same names with the same effective grammar.
+ * Network policy compares the full name set: a transparent alias alone must
+ * not become an approved network wrapper. Name and flag order do not matter.
+ * @internal
+ */
+export declare function sameWrapperSpec(left: WrapperSpec, right: WrapperSpec): boolean;

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

@@ -1,24 +1,6 @@
 /**
- * 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.
+ * Reads the shared network policy and validates JSON-expressible wrapper specs.
+ * A network wrapper also supplies a transparent-wrapper fact to every consumer.
  */
 import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
 /** The setting's dotted path, as error messages name it. */
@@ -34,21 +16,23 @@ const KNOWN_FIELDS = new Set([
     ...STRING_LIST_FIELDS,
     'positionalOperandsBeforeCommand',
     'assignmentOperands',
+    'shellBuiltin',
 ]);
 /** `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.
+ * @internal
  */
-function validate(value) {
+export function validateWrapperSetting(value, setting) {
+    /** Names the configuration binding instead of exposing an analysis failure. */
+    function invalid(detail) {
+        throw new Error(`Invalid ${setting}: ${detail}`);
+    }
     if (typeof value === 'string') {
         if (value.length === 0)
             invalid('expected a command name or a wrapper spec, but got "".');
@@ -71,6 +55,9 @@ function validate(value) {
             invalid(`\`${field}\` must be an array of non-empty strings.`);
         }
     }
+    if (spec.shellBuiltin !== undefined && typeof spec.shellBuiltin !== 'boolean') {
+        invalid('`shellBuiltin` must be a boolean.');
+    }
     const positional = spec.positionalOperandsBeforeCommand;
     if (positional !== undefined && !(Number.isInteger(positional) && positional >= 0)) {
         invalid('`positionalOperandsBeforeCommand` must be a non-negative integer.');
@@ -94,7 +81,7 @@ export function readNetworkWrapperSetting(settings) {
     if (typeof sh !== 'object' || sh === null)
         return undefined;
     const value = sh.networkWrapper;
-    return value === undefined ? undefined : validate(value);
+    return value === undefined ? undefined : validateWrapperSetting(value, SETTING);
 }
 /**
  * The `WrapperSpec` for the network wrapper set in `settings.sh.networkWrapper`,
@@ -114,3 +101,47 @@ export function networkWrapperSpec(settings) {
         names: [wrapper],
     });
 }
+/**
+ * Canonical effective grammar from sh-ast 0.9.0's WrapperSpec matcher, excluding
+ * the names that select it. Flags are membership sets; omitted lists are empty,
+ * shellBuiltin defaults to false (utility matching), and positional count
+ * defaults to zero. An explicit assignment grammar supersedes the legacy
+ * shell-identifier alias; otherwise there is no assignment grammar.
+ *
+ * Expanded built-ins may contain a flag pattern even though JSON settings may
+ * not. Compare its source and flags structurally, including absence, rather
+ * than attempting regex-language equivalence or inheriting omitted fields.
+ */
+function canonicalWrapperGrammar(spec) {
+    /** Stable membership representation for the matcher's four flag lists. */
+    const flags = (values) => [...new Set(values ?? [])].sort();
+    const pattern = spec.noArgFlagPattern;
+    return JSON.stringify({
+        noArgFlags: flags(spec.noArgFlags),
+        argFlags: flags(spec.argFlags),
+        unresolvableFlags: flags(spec.unresolvableFlags),
+        stopsChainFlags: flags(spec.stopsChainFlags),
+        shellBuiltin: spec.shellBuiltin ?? false,
+        positionalOperandsBeforeCommand: spec.positionalOperandsBeforeCommand ?? 0,
+        assignmentOperands: spec.assignmentOperands ?? (spec.skipAssignmentOperands === true ? 'shell-identifier' : null),
+        noArgFlagPattern: pattern === undefined ? null : { source: pattern.source, flags: pattern.flags },
+    });
+}
+/**
+ * Whether overlapping wrapper names receive the same effective matcher grammar.
+ * Extra aliases are independent facts, not a conflict for the shared names.
+ * @internal
+ */
+export function sameWrapperOptions(left, right) {
+    return canonicalWrapperGrammar(left) === canonicalWrapperGrammar(right);
+}
+/**
+ * Whether both specs approve the same names with the same effective grammar.
+ * Network policy compares the full name set: a transparent alias alone must
+ * not become an approved network wrapper. Name and flag order do not matter.
+ * @internal
+ */
+export function sameWrapperSpec(left, right) {
+    return (JSON.stringify([...left.names].sort()) === JSON.stringify([...right.names].sort()) &&
+        sameWrapperOptions(left, right));
+}

package/dist/rules/resolve-transparent-wrappers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Resolves project wrapper facts once per consuming rule. Shared facts precede
+ * the rule's built-in table, so an explicit option shape replaces the default
+ * for that name. Rules retain their distinct built-in scopes, but never their
+ * own interpretation of a configured project wrapper.
+ */
+import type { SettingsConfig } from '@eslint/core';
+import type { WrapperSpec } from 'sh-ast/analyze';
+import type { ShellSourceCode } from '../language/shell-source-code.js';
+/** The rule-context fields needed to resolve shared wrappers and their path spellings. @public */
+export interface TransparentWrappersBindingContext {
+    /** Shared ESLint configuration containing the project's shell facts. */
+    readonly settings: SettingsConfig;
+    /** The current file supplies path spellings without filesystem inspection or execution. */
+    readonly sourceCode: ShellSourceCode;
+}
+/**
+ * Returns the shared project wrappers followed by `builtIns` (defaults when
+ * omitted). Entries accept command names or JSON-expressible `WrapperSpec`s
+ * in `settings: { sh: { transparentWrappers: [...] } }`. The shared network
+ * wrapper is also transparent; conflicting specs for the same project name
+ * throw rather than allowing policies to disagree. Shared specs compare effective
+ * grammars for overlapping names, normalizing matcher defaults and retaining
+ * expanded built-in flag patterns; an extra transparent alias does not acquire
+ * network approval. Explicit specs remain complete replacements. Duplicate project
+ * names are rejected so list order cannot silently choose their meaning.
+ *
+ * Utility wrappers match absolute and relative paths by basename. Path words
+ * remain unchanged in analysis results. `shellBuiltin: true` entries match
+ * exact names only: an executable path cannot acquire in-process semantics.
+ * An explicit path spec takes precedence over a basename fallback regardless
+ * of configuration order.
+ * Aliases are built even when only `builtIns` are supplied. Overridden names
+ * are removed from lower-priority entries, preserving their unrelated aliases
+ * and preventing a utility entry from undoing an exact-name builtin override.
+ * The input tables are never mutated.
+ *
+ * @param context - The consuming rule's context.
+ * @param builtIns - The rule's own built-in wrapper scope.
+ * @throws Error when a configured wrapper is malformed or contradictory.
+ * @public
+ */
+export declare function resolveTransparentWrappers(context: TransparentWrappersBindingContext, builtIns?: readonly WrapperSpec[]): readonly WrapperSpec[];

package/dist/rules/resolve-transparent-wrappers.js

@@ -0,0 +1,98 @@
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { networkWrapperSpec, sameWrapperOptions, validateWrapperSetting, } from './resolve-network-wrapper.js';
+/** The complete nested binding, used in configuration errors. */
+const SETTING = 'settings: { sh: { transparentWrappers: [...] } }';
+/** A name-only entry preserves a known utility's default flag handling. */
+function asSpec(value) {
+    if (typeof value !== 'string') {
+        return value;
+    }
+    return (DEFAULT_TRANSPARENT_WRAPPERS.find((spec) => spec.names.includes(value)) ?? { names: [value] });
+}
+/**
+ * Returns the shared project wrappers followed by `builtIns` (defaults when
+ * omitted). Entries accept command names or JSON-expressible `WrapperSpec`s
+ * in `settings: { sh: { transparentWrappers: [...] } }`. The shared network
+ * wrapper is also transparent; conflicting specs for the same project name
+ * throw rather than allowing policies to disagree. Shared specs compare effective
+ * grammars for overlapping names, normalizing matcher defaults and retaining
+ * expanded built-in flag patterns; an extra transparent alias does not acquire
+ * network approval. Explicit specs remain complete replacements. Duplicate project
+ * names are rejected so list order cannot silently choose their meaning.
+ *
+ * Utility wrappers match absolute and relative paths by basename. Path words
+ * remain unchanged in analysis results. `shellBuiltin: true` entries match
+ * exact names only: an executable path cannot acquire in-process semantics.
+ * An explicit path spec takes precedence over a basename fallback regardless
+ * of configuration order.
+ * Aliases are built even when only `builtIns` are supplied. Overridden names
+ * are removed from lower-priority entries, preserving their unrelated aliases
+ * and preventing a utility entry from undoing an exact-name builtin override.
+ * The input tables are never mutated.
+ *
+ * @param context - The consuming rule's context.
+ * @param builtIns - The rule's own built-in wrapper scope.
+ * @throws Error when a configured wrapper is malformed or contradictory.
+ * @public
+ */
+export function resolveTransparentWrappers(context, builtIns = DEFAULT_TRANSPARENT_WRAPPERS) {
+    const sh = context.settings.sh;
+    const value = typeof sh === 'object' && sh !== null
+        ? sh.transparentWrappers
+        : undefined;
+    if (value !== undefined && !Array.isArray(value)) {
+        throw new Error(`Invalid ${SETTING}: expected an array of command names or wrapper specs.`);
+    }
+    const configured = (value ?? []).map((entry) => asSpec(validateWrapperSetting(entry, SETTING)));
+    const names = new Set();
+    for (const spec of configured) {
+        for (const name of spec.names) {
+            if (names.has(name)) {
+                throw new Error(`Invalid ${SETTING}: duplicate wrapper name ${JSON.stringify(name)}.`);
+            }
+            names.add(name);
+        }
+    }
+    const network = networkWrapperSpec(context.settings);
+    for (const spec of configured) {
+        if (network !== null &&
+            spec.names.some((name) => network.names.includes(name)) &&
+            !sameWrapperOptions(spec, network)) {
+            throw new Error(`Invalid ${SETTING}: a wrapper spec conflicts with the shared networkWrapper.`);
+        }
+    }
+    // Precedence applies to names, including their path-matching semantics.
+    // Keeping a shadowed utility name could recreate an alias that a higher
+    // priority shellBuiltin entry explicitly excludes.
+    const table = [];
+    const claimed = new Set();
+    for (const spec of [...configured, ...(network === null ? [] : [network]), ...builtIns]) {
+        const remaining = spec.names.filter((name) => !claimed.has(name));
+        if (remaining.length === 0) {
+            continue;
+        }
+        table.push(remaining.length === spec.names.length ? spec : { ...spec, names: remaining });
+        for (const name of remaining) {
+            claimed.add(name);
+        }
+    }
+    // Relative utility paths need exact aliases in sh-ast. Derive them only from
+    // static argv words in this file; no path is resolved or executed here.
+    const paths = new Map();
+    for (const site of context.sourceCode.getCommandSites()) {
+        for (const word of site.argv) {
+            if (!word.static || !word.text.includes('/') || paths.has(word.text)) {
+                continue;
+            }
+            const base = word.text.slice(word.text.lastIndexOf('/') + 1);
+            const spec = table.find((entry) => entry.names.includes(word.text)) ??
+                table.find((entry) => entry.shellBuiltin !== true && entry.names.includes(base));
+            // Keep the selected exact spelling ahead of generic entries; deriving
+            // an alias from an earlier basename would erase an explicit path's flags.
+            if (spec !== undefined) {
+                paths.set(word.text, { ...spec, names: [word.text] });
+            }
+        }
+    }
+    return [...paths.values(), ...table];
+}

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

@@ -99,7 +99,8 @@ export declare function formatSetCommand(options: readonly string[]): string;
  *   (`#!/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.
+ *   so every word after the shell name is read. GNU env's
+ *   `--split-string=<shell> <words…>` is read the same way; macOS env supports only `-S`.
  *
  * Plain `#!/usr/bin/env <shell> <flags>` counts as nothing: without `-S`,
  * Linux passes `<shell> <flags>` to `env` as one command name.

package/dist/rules/set-options.js

@@ -168,7 +168,8 @@ export function formatSetCommand(options) {
  *   (`#!/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.
+ *   so every word after the shell name is read. GNU env's
+ *   `--split-string=<shell> <words…>` is read the same way; macOS env supports only `-S`.
  *
  * Plain `#!/usr/bin/env <shell> <flags>` counts as nothing: without `-S`,
  * Linux passes `<shell> <flags>` to `env` as one command name.
@@ -184,13 +185,24 @@ export function shebangOptionChanges(text) {
         .trim()
         .split(/\s+/u);
     const [interpreter = '', ...rest] = words;
-    const isEnv = interpreter === 'env' || interpreter.endsWith('/env');
+    // Relative interpreters are resolved against the caller's directory, never through PATH.
+    if (!interpreter.startsWith('/'))
+        return [];
+    const isEnv = interpreter.endsWith('/env');
     let flagWords;
     if (isEnv) {
-        const [split, , ...shellArgs] = rest;
-        if (split !== '-S' && split !== '--split-string')
+        const [split = '', , ...shellArgs] = rest;
+        // The kernel's single argument makes `--split-string bash -eu` an unknown long option.
+        if (split === '-S') {
+            flagWords = shellArgs;
+        }
+        else if (split.startsWith('--split-string=')) {
+            // The first word carries the command when attached; an empty value puts it next.
+            flagWords = rest.slice(split === '--split-string=' ? 2 : 1);
+        }
+        else {
             return [];
-        flagWords = shellArgs;
+        }
     }
     else {
         if (rest.length !== 1)

package/dist/rules/shebang-interpreter.js

@@ -34,9 +34,11 @@ function envCommand(words) {
         if (word === '--') {
             return words.slice(index + 1).find((operand) => !ENV_ASSIGNMENT.test(operand));
         }
-        if (word === '-S' || word === '--split-string') {
+        // GNU env sees the whole kernel argument as an option name unless the long form uses '='.
+        if (word === '--split-string')
+            return undefined;
+        if (word === '-S')
             continue;
-        }
         if (word.startsWith('--split-string=')) {
             return word.slice('--split-string='.length) || words[index + 1];
         }