@eslint-sh/eslint-plugin 0.7.0 → 0.8.0

package/README.md

@@ -24,9 +24,10 @@ recipes. Four shared configs ship, each supplying `plugins: { sh }` and `languag
 `sh/max-script-complexity`, with every rule at `error`. Its convention and wrapper rules report nothing until you bind a declaration
 convention or a wrapper. The [rules index](./docs/rules/README.md) lists all forty built-in rules,
 their presets, and
-autofix availability. The version-gated rules `sh/compat/no-append-all-redirect`, `sh/compat/no-associative-arrays`, `sh/compat/no-brace-sequence-padding-step`, `sh/compat/no-case-attributes`, `sh/compat/no-case-fallthrough`, `sh/compat/no-case-modification`, `sh/compat/no-coproc`, `sh/compat/no-declare-g`, `sh/compat/no-epoch-variables`, `sh/compat/no-fd-variable`, `sh/compat/no-globstar`, `sh/compat/no-lastpipe-semantics`, `sh/compat/no-mapfile`, `sh/compat/no-nameref`, `sh/compat/no-negative-array-index`, `sh/compat/no-nounset-empty-array`, `sh/compat/no-parameter-transformation`, `sh/compat/no-pipe-all`, `sh/compat/no-printf-time-format`, `sh/compat/no-test-v`, `sh/compat/no-unicode-escape` and `sh/compat/no-wait-n`, report features your target shell version
-lacks; `configs['bash-3.2']` (`shellVersion: '3.2'`) and `configs['posix-portable']` (`dialect: 'posix'`, with
-`sh/require-strict-mode` as `set -eu`) enable them for those targets. `configs['posix-portable']` also reports `[[`, `let` and `source`, which fail on dash (`sh/compat/no-double-bracket`, `sh/compat/no-let`, `sh/compat/no-source`), but not `local`, `echo -e` or the other constructs it leaves to shellcheck, so a clean run does not prove a script runs under every POSIX `sh`; see [version compatibility](./docs/compat.md). Run shellcheck alongside eslint-sh: shellcheck catches shell correctness
+autofix availability. The version-gated rules `sh/compat/no-append-all-redirect`, `sh/compat/no-associative-arrays`, `sh/compat/no-brace-sequence-padding-step`, `sh/compat/no-case-attributes`, `sh/compat/no-case-fallthrough`, `sh/compat/no-case-modification`, `sh/compat/no-coproc`, `sh/compat/no-declare-g`, `sh/compat/no-epoch-variables`, `sh/compat/no-fd-variable`, `sh/compat/no-globstar`, `sh/compat/no-lastpipe-semantics`, `sh/compat/no-mapfile`, `sh/compat/no-nameref`, `sh/compat/no-negative-array-index`, `sh/compat/no-nounset-empty-array`, `sh/compat/no-parameter-transformation`, `sh/compat/no-pipe-all`, `sh/compat/no-printf-time-format`, `sh/compat/no-test-v`, `sh/compat/no-unicode-escape` and `sh/compat/no-wait-n`, report features the minimum Bash version your scripts must support lacks; `configs['bash-3.2']` (`minBashVersion: '3.2'`) and `configs['posix-portable']` (`dialect: 'posix'`, with
+`sh/require-strict-mode` as `set -eu`) enable them for those targets, except that
+`sh/compat/no-nounset-empty-array` is an explicit opt-in for `bash-3.2`. Enable it for scripts
+that use `set -u` on Bash below 4.4 and have arrays that can really be empty. `configs['posix-portable']` also reports `[[`, `let` and `source`, which fail on dash (`sh/compat/no-double-bracket`, `sh/compat/no-let`, `sh/compat/no-source`), but not `local`, `echo -e` or the other constructs it leaves to shellcheck, so a clean run does not prove a script runs under every POSIX `sh`; see [version compatibility](./docs/compat.md). Run shellcheck alongside eslint-sh: shellcheck catches shell correctness
 problems; eslint-sh enforces project policy. [Running eslint-sh beside shellcheck](./docs/shellcheck.md)
 covers who owns what and the rules that overlap it deliberately (see also the
 [design rationale](https://github.com/mike-north/eslint-sh/blob/main/design/README.md#eslint-sh-and-shellcheck)).
@@ -78,7 +79,7 @@ ShellLanguage }, rules, configs: { recommended, 'agent-authored', 'bash-3.2', 'p
 - `ShellLanguage` — the `@eslint/core` `Language` implementation: `fileType: "text"`,
   `lineStart`/`columnStart: 1`, `nodeTypeKey: "type"`, the consumer's schema-derived `visitorKeys`,
   `validateLanguageOptions`/`normalizeLanguageOptions` for the
-  `{dialect, shellVersion, directivePrefix}` schema, `parse`/`createSourceCode`, and
+  `{dialect, minBashVersion, directivePrefix}` schema, `parse`/`createSourceCode`, and
   `matchesSelectorClass` for the six launch esquery selector classes (`:command`, `:loop`,
   `:conditional`, `:expansion`, `:quoted`, `:function` — see the
   [selector cookbook](./docs/selectors.md)).
@@ -91,9 +92,9 @@ ShellLanguage }, rules, configs: { recommended, 'agent-authored', 'bash-3.2', 'p
   without following wrappers), and `resolveInvokedCommand(callExpr, { transparentWrappers? })` (the
   full `Argv0Resolution` once wrappers such as `env`, `sudo`, and `exec` are followed, including the
   wrapper `chain` and the `effective` command or the reason it is unknowable). The `dialect` and
-  `shellVersion` accessors return the file's normalized language options.
+  `minBashVersion` accessors return the file's normalized language options.
 - `ShellLanguageOptions` / `NormalizedShellLanguageOptions` / `ShellLanguageOptionsJSON` — the
-  `languageOptions` types (`dialect`, `shellVersion`, `directivePrefix`). `directivePrefix` is the
+  `languageOptions` types (`dialect`, `minBashVersion`, `directivePrefix`). `directivePrefix` is the
   prefix directive/inline-config comments must start with — e.g. the default `"eslint"` recognizes
   `# eslint-disable-next-line ...`; consumers who already overload `# eslint-*` comments for
   something else can configure a different prefix (e.g. `directivePrefix: 'shellcheck-sh'`).
@@ -154,9 +155,14 @@ ShellLanguage }, rules, configs: { recommended, 'agent-authored', 'bash-3.2', 'p
   `ShellRuleVisitor`. See [Writing your own rules](#writing-your-own-rules).
 - `resolveDeclarationConvention` / `DeclarationConventionBindingContext` — resolves the declaration
   convention bound for a rule (its `declarationConvention` option, else
-  `settings.sh.declarationConvention`, else `null`) with the validation and error messages the
+  `settings: { sh: { declarationConvention: commentPragma } }`, else `null`) with the validation and error messages the
   built-in consumers use, so a rule of your own can read the convention. See [declaration
   conventions](./docs/declaration-conventions.md#reading-the-convention-in-your-own-rule).
+- `resolveTransparentWrappers` / `TransparentWrappersBindingContext` — resolves project wrapper
+  facts from `settings: { sh: { transparentWrappers: ['with-retry'] } }` and the shared network
+  wrapper, composed with a rule's built-in scope. Every wrapper-following built-in uses it;
+  rule packs can use the same validation, precedence and path matching. See
+  [shared transparent wrappers](./docs/transparent-wrappers.md).
 - `createWrapperRule` / `WrapperRuleConfig` / `WrapperRuleSubcommands` / `WrapperSpec` — the
   factory for "command X must be run through wrapper Y" rules a rule pack
   binds to its own commands and wrapper. `sh/require-network-wrapper` is the built-in rule made
@@ -194,7 +200,7 @@ import {
   `…/syntax/analyze` takes a faithful `Node`. That is why the subpaths are kept apart from the
   root.
 - **Versioning.** `…/syntax` and `…/syntax/analyze` track this plugin's pinned `sh-ast` minor
-  (currently `sh-ast@^0.7.0`). Under 0.x, a different `sh-ast` minor is a breaking change, so
+  (currently `sh-ast@^0.9.0`). Under 0.x, a different `sh-ast` minor is a breaking change, so
   an `sh-ast` 0.x minor bump is a minor bump of this plugin, and the changelog entry names the
   new `sh-ast` version.
 

package/dist/command-harvest/builtins/bash.d.ts

@@ -17,7 +17,7 @@
  * Reserved words (`if`, `time`, `[[`, `function`, …) are not here: the
  * parser never produces them as command words.
  *
- * The list is the latest bash's, and is not narrowed by `shellVersion`:
+ * The list is the latest bash's, and is not narrowed by `minBashVersion`:
  * `mapfile`, `readarray` and `compopt` (added in bash 4.0) are builtins here
  * even for a file configured as bash 3.2. Whether a script may use them on
  * an old bash is a version-compatibility question, not a dependency one.

package/dist/command-harvest/builtins/bash.js

@@ -17,7 +17,7 @@
  * Reserved words (`if`, `time`, `[[`, `function`, …) are not here: the
  * parser never produces them as command words.
  *
- * The list is the latest bash's, and is not narrowed by `shellVersion`:
+ * The list is the latest bash's, and is not narrowed by `minBashVersion`:
  * `mapfile`, `readarray` and `compopt` (added in bash 4.0) are builtins here
  * even for a file configured as bash 3.2. Whether a script may use them on
  * an old bash is a version-compatibility question, not a dependency one.

package/dist/command-harvest/builtins/bats.d.ts

@@ -32,6 +32,8 @@ export declare const BATS_HELPERS: readonly string[];
 /**
  * bats' `run`, as a transparent wrapper: it runs the command after its own
  * options and captures the result, so `run curl x` uses `curl`.
+ * Only the exact function name has these semantics; an executable path such
+ * as `/tmp/run` is an external dependency whose arguments remain opaque.
  *
  * Its options, all before the command (bats-core manual, "`run`: Test other
  * commands"): `-N` (expect exit status N, 0–255), `!` (expect a nonzero

package/dist/command-harvest/builtins/bats.js

@@ -16,6 +16,8 @@ export const BATS_HELPERS = Object.freeze([
 /**
  * bats' `run`, as a transparent wrapper: it runs the command after its own
  * options and captures the result, so `run curl x` uses `curl`.
+ * Only the exact function name has these semantics; an executable path such
+ * as `/tmp/run` is an external dependency whose arguments remain opaque.
  *
  * Its options, all before the command (bats-core manual, "`run`: Test other
  * commands"): `-N` (expect exit status N, 0–255), `!` (expect a nonzero
@@ -28,6 +30,7 @@ export const BATS_HELPERS = Object.freeze([
  */
 export const BATS_RUN_WRAPPER = Object.freeze({
     names: Object.freeze(['run']),
+    shellBuiltin: true,
     noArgFlags: Object.freeze(['!', '--keep-empty-lines', '--separate-stderr']),
     noArgFlagPattern: /^-\d+$/u,
 });

package/dist/command-harvest/wrapper-table.d.ts

@@ -1,24 +1,8 @@
 import type { WrapperSpec } from 'sh-ast/analyze';
 import type { ShellDialect } from '../language/shell-language-options.js';
 /**
- * Returns the transparent-wrapper table for harvesting a `dialect` file
- * with the given configured wrapper names, in this order:
- *
- * 1. `sh-ast/analyze`'s `DEFAULT_TRANSPARENT_WRAPPERS` (`sudo`, `env`, …);
- * 2. the dialect's own wrappers (`run` under `bats`);
- * 3. the project's network wrapper (`settings.sh.networkWrapper`), when set,
- *    with the options its spec declares: a wrapper that network commands must
- *    run through runs the command after it;
- * 4. one name-only entry per configured name. A name-only entry recognizes
- *    no flags, so `with-retry -n 3 curl` stops at `-n` rather than guessing
- *    past it.
- *
- * The first entry whose names match is the one used, so a network wrapper
- * spec with options wins over a name-only entry for the same name.
- *
- * @param dialect - The linted file's `sourceCode.dialect`.
- * @param wrapperNames - The rule's `transparentWrappers` option names.
- * @param networkWrapper - The spec from `settings.sh.networkWrapper`, or `null`.
+ * Returns the built-in harvest scope for a dialect, including bats' in-process
+ * `run` helper only in bats files. Project wrappers are resolved separately.
  * @internal
  */
-export declare function harvestWrapperTable(dialect: ShellDialect, wrapperNames: readonly string[], networkWrapper?: WrapperSpec | null): readonly WrapperSpec[];
+export declare function harvestWrapperTable(dialect: ShellDialect): readonly WrapperSpec[];

package/dist/command-harvest/wrapper-table.js

@@ -1,49 +1,19 @@
 /**
- * The one wrapper table that rules comparing declarations against usage
- * pass to `harvestCommands` (`./harvest-commands.ts`).
- *
- * `no-undeclared-commands` and `no-unused-declarations` must agree exactly on
- * which commands a file uses, or one would report a command the other calls
- * unused. Usage depends on the wrapper table, so both build it here from the
- * same inputs: the file's dialect, the network wrapper from
- * `settings.sh.networkWrapper`, and the rule's `transparentWrappers` option
- * names.
+ * Built-in wrappers used when comparing command declarations with usage.
+ * Both declaration rules compose this dialect scope with the shared project
+ * facts through resolveTransparentWrappers, so they compute the same usage.
  */
 import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
 import { BATS_RUN_WRAPPER } from './builtins/bats.js';
-/**
- * Wrappers a dialect's runtime provides beyond sh-ast's defaults: bats' `run`
- * for `bats` files.
- */
+/** Wrappers a dialect runtime provides beyond sh-ast's defaults. */
 const DIALECT_WRAPPERS = {
     bats: [BATS_RUN_WRAPPER],
 };
 /**
- * Returns the transparent-wrapper table for harvesting a `dialect` file
- * with the given configured wrapper names, in this order:
- *
- * 1. `sh-ast/analyze`'s `DEFAULT_TRANSPARENT_WRAPPERS` (`sudo`, `env`, …);
- * 2. the dialect's own wrappers (`run` under `bats`);
- * 3. the project's network wrapper (`settings.sh.networkWrapper`), when set,
- *    with the options its spec declares: a wrapper that network commands must
- *    run through runs the command after it;
- * 4. one name-only entry per configured name. A name-only entry recognizes
- *    no flags, so `with-retry -n 3 curl` stops at `-n` rather than guessing
- *    past it.
- *
- * The first entry whose names match is the one used, so a network wrapper
- * spec with options wins over a name-only entry for the same name.
- *
- * @param dialect - The linted file's `sourceCode.dialect`.
- * @param wrapperNames - The rule's `transparentWrappers` option names.
- * @param networkWrapper - The spec from `settings.sh.networkWrapper`, or `null`.
+ * Returns the built-in harvest scope for a dialect, including bats' in-process
+ * `run` helper only in bats files. Project wrappers are resolved separately.
  * @internal
  */
-export function harvestWrapperTable(dialect, wrapperNames, networkWrapper = null) {
-    return [
-        ...DEFAULT_TRANSPARENT_WRAPPERS,
-        ...(DIALECT_WRAPPERS[dialect] ?? []),
-        ...(networkWrapper === null ? [] : [networkWrapper]),
-        ...wrapperNames.map((name) => ({ names: [name] })),
-    ];
+export function harvestWrapperTable(dialect) {
+    return [...DEFAULT_TRANSPARENT_WRAPPERS, ...(DIALECT_WRAPPERS[dialect] ?? [])];
 }

package/dist/configs/bash-3-2.d.ts

@@ -2,14 +2,15 @@
  * The `sh/bash-3.2` shared config: the preset for scripts that must run on the
  * Bash 3.2 that macOS ships as `/bin/bash`.
  *
- * The parser accepts every construct its grammar knows whatever target is
- * configured, so a Bash 3.2 target is enforced only by the `compat/*` rules.
- * This preset names that target once (`languageOptions.shellVersion: '3.2'`)
- * and turns on every version-gated rule that reads it, so a project states its
- * deployment target as a config choice instead of enumerating rules.
+ * The parser accepts every construct its grammar knows whatever floor is
+ * configured, so required Bash 3.2 support is enforced only by the `compat/*` rules.
+ * This preset names that floor once (`languageOptions.minBashVersion: '3.2'`)
+ * and enables the version gates except the opt-in empty-array nounset check,
+ * so a project states its minimum supported Bash as a config choice instead of
+ * enumerating rules.
  *
  * It follows the shape contract in `./recommended.ts`, with one deliberate
- * extension: it carries `languageOptions`, because the target version is the
+ * extension: it carries `languageOptions`, because the minimum supported version is the
  * preset's whole meaning and a pack that left it to the user would enable
  * rules that report nothing. It still carries no `files` or `ignores`, so it
  * inherits the user's globs, and it composes with the other presets through

package/dist/configs/bash-3-2.js

@@ -1,7 +1,9 @@
 /**
- * The rules `sh/bash-3.2` enables: every version-gated `compat/*` rule, all at
+ * The rules `sh/bash-3.2` enables: twenty-one version-gated `compat/*` rules, all at
  * `error`, keyed as a user writes them (`sh/<rule-name>`). Each reports a
  * feature that Bash 3.2 lacks and names the portable alternative.
+ * `compat/no-nounset-empty-array` is opt-in: caller and helper contracts can
+ * guarantee non-empty arrays beyond the rule's local safety proofs.
  * `shebang-matches-dialect` is not a version gate and belongs to the
  * presets whose catalog row names it. The POSIX-only gates
  * (`compat/no-double-bracket`, `compat/no-let`, `compat/no-source`) are not
@@ -26,7 +28,6 @@ const bash32Rules = {
     'sh/compat/no-mapfile': 'error',
     'sh/compat/no-nameref': 'error',
     'sh/compat/no-negative-array-index': 'error',
-    'sh/compat/no-nounset-empty-array': 'error',
     'sh/compat/no-parameter-transformation': 'error',
     'sh/compat/no-pipe-all': 'error',
     'sh/compat/no-printf-time-format': 'error',
@@ -45,7 +46,7 @@ export function createBash32Config(plugin) {
         name: 'sh/bash-3.2',
         plugins: { sh: plugin },
         language: 'sh/sh',
-        languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+        languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
         rules: { ...bash32Rules },
     };
 }

package/dist/configs/posix-portable.d.ts

@@ -3,7 +3,7 @@
  * POSIX `sh` rather than for Bash.
  *
  * It sets `languageOptions.dialect: 'posix'`, which makes every Bash-only
- * feature unavailable at any `shellVersion`, and enables the `compat/*` rules
+ * feature unavailable at any `minBashVersion`, and enables the `compat/*` rules
  * that report those features. The dialect is also what every dialect-aware
  * rule reads, so the preset is one switch rather than a list of settings that
  * could drift apart.

package/dist/declaration-conventions/read-declared-commands.d.ts

@@ -44,8 +44,8 @@ export declare function toLintedFile(context: LintedFile): LintedFile;
  * `filename`, `physicalFilename` and `cwd`, never the whole context, so it
  * sees which file it is reading and nothing it could report through.
  *
- * Throws an `Error` that names the setting, starting
- * `Invalid settings.sh.declarationConvention:`, and shows the offending value when
+ * Throws an `Error` naming the declaration-convention setting and showing the
+ * offending value when
  * `declaredCommands` does not return an array, or returns a declaration with
  * a missing or unknown `kind`, without its kind's fields, or with a `range`
  * outside the linted text.

package/dist/declaration-conventions/read-declared-commands.js

@@ -88,8 +88,8 @@ function describe(value) {
  * `filename`, `physicalFilename` and `cwd`, never the whole context, so it
  * sees which file it is reading and nothing it could report through.
  *
- * Throws an `Error` that names the setting, starting
- * `Invalid settings.sh.declarationConvention:`, and shows the offending value when
+ * Throws an `Error` naming the declaration-convention setting and showing the
+ * offending value when
  * `declaredCommands` does not return an array, or returns a declaration with
  * a missing or unknown `kind`, without its kind's fields, or with a `range`
  * outside the linted text.

package/dist/eslint-plugin-syntax.d.ts

@@ -18,6 +18,10 @@
  * `@eslint-sh/eslint-plugin/syntax/analyze`. That is why these names live on their own subpath
  * and are not merged into the root.
  *
+ * The low-level `printSync` keeps upstream behavior, including changes to literal vertical tabs
+ * and form feeds. It does not apply the high-level content refusal used by `format` and
+ * `ShellSourceCode.getPrintedReplacement`; callers printing directly must account for that loss.
+ *
  * @packageDocumentation
  */
 

package/dist/eslint-plugin.d.ts

@@ -333,7 +333,7 @@ export declare interface LintedFile {
 export declare interface NormalizedShellLanguageOptions extends Record<string, unknown> {
     readonly dialect: ShellDialect;
     readonly directivePrefix: string;
-    readonly shellVersion?: string;
+    readonly minBashVersion?: string;
     toJSON(): ShellLanguageOptionsJSON;
 }
 
@@ -362,8 +362,9 @@ export declare interface NormalizedShellLanguageOptions extends Record<string, u
  * machine-written, human-reviewed scripts:
  * every `recommended` rule plus the contract rules, all at `error`.
  * `configs['bash-3.2']` and `configs['posix-portable']` are deployment-target
- * packs: the first sets `languageOptions.shellVersion: "3.2"` and enables
- * every version-gated `compat/*` rule; the second sets
+ * packs: the first sets `languageOptions.minBashVersion: "3.2"` and enables
+ * the version-gated `compat/*` rules except the opt-in
+ * `compat/no-nounset-empty-array`; the second sets
  * `languageOptions.dialect: "posix"`, enables the `compat/*` rules and the
  * shebang/dialect check, and requires `set -eu`; it reports named constructs
  * that fail on dash, not every non-POSIX construct, and leaves `local`,
@@ -407,8 +408,8 @@ export default plugin;
  * `filename`, `physicalFilename` and `cwd`, never the whole context, so it
  * sees which file it is reading and nothing it could report through.
  *
- * Throws an `Error` that names the setting, starting
- * `Invalid settings.sh.declarationConvention:`, and shows the offending value when
+ * Throws an `Error` naming the declaration-convention setting and showing the
+ * offending value when
  * `declaredCommands` does not return an array, or returns a declaration with
  * a missing or unknown `kind`, without its kind's fields, or with a `range`
  * outside the linted text.
@@ -437,16 +438,15 @@ export { ResolveArgv0Options }
 /**
  * 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.
@@ -480,6 +480,34 @@ export { ResolveArgv0Options }
  */
 export declare function resolveDeclarationConvention(context: DeclarationConventionBindingContext): DeclarationConvention | null;
 
+/**
+ * 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[];
+
 /**
  * Resolves a parsed lint Word using the upstream-shaped syntax associated with it.
  * The view supplies locations and selector fields; sh-ast/analyze owns the word
@@ -610,11 +638,12 @@ export declare class ShellLanguage implements Language {
     readonly defaultLanguageOptions: ShellLanguageOptions;
     /**
      * Validates `languageOptions.dialect` (must be one of the five supported
-     * dialects, if present), `languageOptions.shellVersion` (must be a
-     * string matching the `MAJOR[.MINOR]` numeric shape, if present), and
+     * dialects, if present), `languageOptions.minBashVersion` (must be a
+     * string matching the `MAJOR[.MINOR]` numeric shape, if present, and
+     * applies only to `bash` and `bats`), and
      * `languageOptions.directivePrefix` (must be a valid directive-comment
-     * label, if present). Unknown keys are silently ignored, per the
-     * `Language` contract. See `shell-language-options.ts`'s
+     * label, if present). The removed `shellVersion` key throws with
+     * migration guidance; other unknown keys are silently ignored. See `shell-language-options.ts`'s
      * `validateShellLanguageOptions` for the full rationale.
      */
     validateLanguageOptions(languageOptions: ShellLanguageOptions): void;
@@ -648,9 +677,9 @@ export declare class ShellLanguage implements Language {
      * A file whose extension marks it as a known non-shell source type (for
      * example `.js` or `.json`) is never shell-parsed: it fails with a single
      * diagnostic explaining that a `language: 'sh/sh'` config entry without
-     * `files` reached it, and how to scope that entry. A source in which
-     * the parser silently drops text at a U+0080 fails at that character; a
-     * U+0080 the parser reads as an ordinary character does not.
+     * `files` reached it, and how to scope that entry. Unicode characters remain
+     * source text. A native nesting-budget refusal returns no partial tree and
+     * becomes a fatal resource diagnostic at 1:1.
      */
     parse(file: File_2, context: {
         languageOptions: ShellLanguageOptions;
@@ -665,8 +694,8 @@ export declare class ShellLanguage implements Language {
      * present, but `?? 'eslint'` stays as an explicit, honest fallback for
      * direct construction (e.g. tests that skip the `Language` normalization
      * step), mirroring `parse()`'s `dialect` default above. `dialect` and
-     * `shellVersion` are forwarded so rules read the same normalized values
-     * through `sourceCode.dialect` / `sourceCode.shellVersion`.
+     * `minBashVersion` are forwarded so rules read the same normalized values
+     * through `sourceCode.dialect` / `sourceCode.minBashVersion`.
      */
     createSourceCode(file: File_2, parseResult: OkParseResult<ShellFile>, context: {
         languageOptions: ShellLanguageOptions;
@@ -675,7 +704,7 @@ export declare class ShellLanguage implements Language {
 
 /**
  * `languageOptions` accepted by {@link ShellLanguage}: `dialect` selects
- * mvdan/sh's `LangVariant` through a consumer-owned mapping (default `"bash"`); `shellVersion`
+ * mvdan/sh's `LangVariant` through a consumer-owned mapping (default `"bash"`); `minBashVersion`
  * is consumed by the rule layer (e.g. the bash-3.2 compatibility pack),
  * never by the parser itself.
  *
@@ -691,13 +720,14 @@ export declare class ShellLanguage implements Language {
 export declare interface ShellLanguageOptions extends Record<string, unknown> {
     readonly dialect?: ShellDialect;
     /**
-     * The Bash version (`MAJOR[.MINOR]`, such as `"3.2"`) the scripts must run
-     * on. The parser ignores it. The `compat/*` rules read it: unset means the
-     * newest version, versions compare numerically by major then minor, and
-     * under `dialect: "posix"` Bash-only features are unavailable at any
-     * version.
+     * The minimum Bash version (`MAJOR[.MINOR]`, such as `"3.2"`) the
+     * script must support, including every newer Bash. Only valid with the
+     * `bash` or `bats` dialect (the default is `bash`). The parser ignores
+     * it; `compat/*` rules report features unavailable at this floor. Unset
+     * means no Bash version constraint. Versions compare numerically by
+     * major then minor, with no upper version limit.
      */
-    readonly shellVersion?: string;
+    readonly minBashVersion?: string;
     /**
      * The prefix directive/inline-config comments must start with — e.g. the
      * default `"eslint"` recognizes `# eslint-disable-next-line ...` and
@@ -711,14 +741,14 @@ export declare interface ShellLanguageOptions extends Record<string, unknown> {
 
 /**
  * The plain-data shape {@link NormalizedShellLanguageOptions.toJSON} returns:
- * `dialect` and `directivePrefix` always present (both defaulted), `shellVersion`
+ * `dialect` and `directivePrefix` always present (both defaulted), `minBashVersion`
  * present only when the caller supplied one. Keys are always emitted in this
  * fixed order so that two logically-identical inputs serialize identically
  * regardless of the key order the caller happened to use — the property this
  * type exists to guarantee for cache-key stability (see
  * {@link NormalizedShellLanguageOptions}). `directivePrefix` is included
- * unconditionally (like `dialect`, unlike `shellVersion`) because — like
- * `dialect` and unlike `shellVersion` — it always has a concrete effect on
+ * unconditionally (like `dialect`, unlike `minBashVersion`) because — like
+ * `dialect` and unlike `minBashVersion` — it always has a concrete effect on
  * linting results (which comments the `SourceCode` recognizes as directives)
  * whether or not the caller supplied one, so two configs that differ only in
  * an *implicit* default vs. an *explicit* `directivePrefix: "eslint"` must
@@ -729,7 +759,7 @@ export declare interface ShellLanguageOptions extends Record<string, unknown> {
 export declare interface ShellLanguageOptionsJSON {
     readonly dialect: ShellDialect;
     readonly directivePrefix: string;
-    readonly shellVersion?: string;
+    readonly minBashVersion?: string;
 }
 
 /**
@@ -974,7 +1004,7 @@ export declare interface ShellRuleVisitor extends ShellTypedListeners {
  * the string `jq`?", "which command does this invocation run?", and "which
  * commands does this file run, and where?" by delegating to
  * `sh-ast/analyze`. They never reinterpret words themselves, so every rule
- * gets the same answer for the same syntax. `dialect` and `shellVersion`
+ * gets the same answer for the same syntax. `dialect` and `minBashVersion`
  * expose the file's normalized language options.
  *
  * Syntax access (`getSyntax`, `getViewNode`, `getIndexFromSyntaxPos`,
@@ -1001,7 +1031,7 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
         ast: ShellFile;
         directivePrefix?: string;
         dialect?: ShellDialect;
-        shellVersion?: string;
+        minBashVersion?: string;
     });
     /**
      * The shell dialect this file was parsed as: the normalized
@@ -1010,11 +1040,12 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
      */
     get dialect(): ShellDialect;
     /**
-     * The configured `languageOptions.shellVersion` (a `MAJOR[.MINOR]` string
+     * The configured `languageOptions.minBashVersion` (a `MAJOR[.MINOR]` string
      * such as `"3.2"`), or `undefined` when the config does not set one. The
-     * parser never reads it; it exists for rules that gate on shell version.
+     * script must support this Bash and every newer release. The parser never
+     * reads it; compatibility rules use it as a floor with no upper limit.
      */
-    get shellVersion(): string | undefined;
+    get minBashVersion(): string | undefined;
     /**
      * The one-based location of a UTF-16 `index` in this file's text, where
      * `index` may be anywhere from 0 to `text.length`. CRLF counts as one line
@@ -1103,13 +1134,19 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
      * effective command's name as
      * `res.effective.static ? res.effective.text : null`.
      * `sudo -u x "$prog"` and `exec "$@"` have a non-static `effective` with
-     * reason `expansion`; `env -S '…'` has reason `embedded-command`; `chain`
+     * reason `expansion`; `env -S '…'` and `bash -c '…'` have reason
+     * `embedded-command`; `chain`
      * lists every word resolved along the way, outermost wrapper first, and
      * `chainIndices` gives each entry's position in the command's `argv` (as
      * {@link ShellSourceCode.getCommandSites} reports it). When `effective` is
      * static, the effective command's arguments are
      * `argv.slice(chainIndices.at(-1)! + 1)`: every entry after the effective
-     * command's own index.
+     * command's own index. For an interpreter command string the final chain
+     * index instead locates the selector flag; the interpreter is in `chain.at(-2)`.
+     * `embeddedCommandInterpreters: []` retains the interpreter as the static
+     * effective command when a policy needs program identity. Utility wrappers
+     * can match absolute-path basenames; `shellBuiltin: true` entries require
+     * exact names, so external paths do not acquire in-process semantics.
      *
      * Enumeration runs once per file, the first time any command helper is
      * called. If the file's nesting exceeds `enumerateCommands`'s recursion
@@ -1270,8 +1307,9 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
      * @throws TypeError when `node` has no original record in this file (see
      * {@link ShellSourceCode.getEditableSyntax}), when `edited` is not a
      * printable root (the message names its type), or when the printer's output
-     * is not valid UTF-8. Non-UTF-8 output comes back from `printSync` as a
-     * `Uint8Array` and is never decoded lossily into a fix.
+     * is not valid UTF-8, or the edited syntax contains literal vertical tabs or
+     * form feeds that the printer cannot preserve. Non-UTF-8 output comes back
+     * from `printSync` as a `Uint8Array` and is never decoded lossily into a fix.
      * @throws `PrintError` or `PrintPanicError` (from sh-ast) when upstream's
      * printer fails for `edited` or `options`.
      */
@@ -1400,6 +1438,14 @@ export declare type ShellTypedListeners = {
     [Type in ShellNodeType as Type | `${Type}:exit`]?: ShellListener<ShellNodeOf<Type>>;
 };
 
+/** The rule-context fields needed to resolve shared wrappers and their path spellings. @public */
+export declare 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;
+}
+
 export { WordResolution }
 
 /**

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export type { DeclarationConvention, DeclaredCommand, FileDeclaredCommand, Linte
 export { readDeclaredCommands } from './declaration-conventions/read-declared-commands.js';
 export type { DeclarationReadContext } from './declaration-conventions/read-declared-commands.js';
 export { commentPragma } from './declaration-conventions/comment-pragma.js';
+export { resolveTransparentWrappers } from './rules/resolve-transparent-wrappers.js';
+export type { TransparentWrappersBindingContext } from './rules/resolve-transparent-wrappers.js';
 export { resolveDeclarationConvention } from './rules/resolve-declaration-convention.js';
 export type { DeclarationConventionBindingContext } from './rules/resolve-declaration-convention.js';
 export { defineShellRule } from './rules/define-shell-rule.js';
@@ -46,8 +48,9 @@ export type { WrapperSpec } from 'sh-ast/analyze';
  * machine-written, human-reviewed scripts:
  * every `recommended` rule plus the contract rules, all at `error`.
  * `configs['bash-3.2']` and `configs['posix-portable']` are deployment-target
- * packs: the first sets `languageOptions.shellVersion: "3.2"` and enables
- * every version-gated `compat/*` rule; the second sets
+ * packs: the first sets `languageOptions.minBashVersion: "3.2"` and enables
+ * the version-gated `compat/*` rules except the opt-in
+ * `compat/no-nounset-empty-array`; the second sets
  * `languageOptions.dialect: "posix"`, enables the `compat/*` rules and the
  * shebang/dialect check, and requires `set -eu`; it reports named constructs
  * that fail on dash, not every non-POSIX construct, and leaves `local`,

package/dist/index.js

@@ -10,6 +10,7 @@ export { ShellSourceCode } from './language/shell-source-code.js';
 export { resolveWord } from './language/word-resolution.js';
 export { readDeclaredCommands } from './declaration-conventions/read-declared-commands.js';
 export { commentPragma } from './declaration-conventions/comment-pragma.js';
+export { resolveTransparentWrappers } from './rules/resolve-transparent-wrappers.js';
 export { resolveDeclarationConvention } from './rules/resolve-declaration-convention.js';
 export { defineShellRule } from './rules/define-shell-rule.js';
 export { createWrapperRule } from './rules/create-wrapper-rule.js';
@@ -40,8 +41,9 @@ export { createWrapperRule } from './rules/create-wrapper-rule.js';
  * machine-written, human-reviewed scripts:
  * every `recommended` rule plus the contract rules, all at `error`.
  * `configs['bash-3.2']` and `configs['posix-portable']` are deployment-target
- * packs: the first sets `languageOptions.shellVersion: "3.2"` and enables
- * every version-gated `compat/*` rule; the second sets
+ * packs: the first sets `languageOptions.minBashVersion: "3.2"` and enables
+ * the version-gated `compat/*` rules except the opt-in
+ * `compat/no-nounset-empty-array`; the second sets
  * `languageOptions.dialect: "posix"`, enables the `compat/*` rules and the
  * shebang/dialect check, and requires `set -eu`; it reports named constructs
  * that fail on dash, not every non-POSIX construct, and leaves `local`,