@eslint-sh/eslint-plugin 0.6.0 → 0.8.0

package/dist/rules/no-unused-declarations.d.ts

@@ -1,23 +1,6 @@
-/**
- * The rule's single options object. It mirrors `no-undeclared-commands`'
- * options, so a project configures both rules with the same wrappers and
- * they compute the same usage.
- *
- * @internal
- */
-export interface NoUnusedDeclarationsOptions {
-    /**
-     * Names of project-specific transparent wrappers (`with-retry`), added to
-     * the default wrapper table (see `harvestWrapperTable`). The word after a
-     * listed wrapper is the command it runs, so `with-retry curl` uses `curl`
-     * as well as `with-retry`, and `with-retry "$tool"` runs a command the
-     * file cannot name.
-     */
-    readonly transparentWrappers?: readonly string[];
-}
 /**
  * The `sh/no-unused-declarations` rule module.
  *
  * @internal
  */
-export declare const noUnusedDeclarations: import("./define-shell-rule.js").ShellRule<[NoUnusedDeclarationsOptions?], "unusedDeclaration" | "unusedFileDeclaration" | "unusedDescribedDeclaration">;
+export declare const noUnusedDeclarations: import("./define-shell-rule.js").ShellRule<[], "unusedDeclaration" | "unusedFileDeclaration" | "unusedDescribedDeclaration">;

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/require-tty-guard.js

@@ -25,6 +25,10 @@
  * so a dynamic command word is never matched.
  *
  * The suggestion wraps the offending statement in `if [ -t 0 ]; then … fi`.
+ * It is withheld when another command shares the line that opens the
+ * statement's here-document, because the statement's source range runs on to
+ * that here-document's terminator and would carry the other command into the
+ * guard.
  */
 import { DashHdoc, Hdoc } from 'sh-ast/analyze';
 import { createRule } from './create-rule.js';
@@ -147,6 +151,26 @@ function isControlFlowOperand(stmt, sourceCode) {
 }
 /** Redirection operators that open a here-document (`<<`, `<<-`), whose body follows the line. */
 const HEREDOC_OPERATORS = new Set([Hdoc, DashHdoc]);
+/**
+ * Whether other source shares the line that opens one of `stmt`'s
+ * here-documents. A here-document's body follows that line, so the statement's
+ * range reaches the body's terminator and covers whatever else sits on the
+ * opener line (`read x 3<<EOF; echo hi`, a trailing comment): wrapping the
+ * range would put that source inside the guard, where it runs only on a
+ * terminal. A bare `;` after the opener belongs to the statement and does not
+ * count. The opener line is read from the end of the statement's inline
+ * tokens (its command, its redirections' operators and words), so the
+ * statement's own further redirections on that line are not foreign.
+ */
+function sharesHeredocOpenerLine(stmt, text) {
+    const heredocs = stmt.redirs.filter((redir) => HEREDOC_OPERATORS.has(redir.op));
+    if (heredocs.length === 0)
+        return false;
+    const inlineEnd = Math.max(...(stmt.cmd === undefined ? [] : [stmt.cmd.range[1]]), ...stmt.redirs.map((redir) => HEREDOC_OPERATORS.has(redir.op) ? (redir.word?.range[1] ?? redir.range[1]) : redir.range[1]));
+    const lineEnd = text.indexOf('\n', inlineEnd);
+    const tail = text.slice(inlineEnd, lineEnd === -1 ? text.length : lineEnd);
+    return !/^[ \t]*;?[ \t]*\r?$/u.test(tail);
+}
 /**
  * The text that replaces `stmtText` (a statement starting at `start`) with
  * the statement inside `if [ -t 0 ]; then … fi`.
@@ -261,7 +285,12 @@ export const requireTtyGuard = createRule({
                     const stmt = sourceCode.getParent(node);
                     // A statement that runs in the background cannot be wrapped without
                     // changing what is backgrounded, so it gets no suggestion.
-                    const wrappable = stmt?.type === 'Stmt' && !stmt.background && !isControlFlowOperand(stmt, sourceCode);
+                    // A statement sharing its here-document's opener line with another
+                    // command gets none either (see `sharesHeredocOpenerLine`).
+                    const wrappable = stmt?.type === 'Stmt' &&
+                        !stmt.background &&
+                        !isControlFlowOperand(stmt, sourceCode) &&
+                        !sharesHeredocOpenerLine(stmt, sourceCode.text);
                     context.report({
                         node,
                         messageId: 'unguardedInteractive',

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[];