@eslint-sh/eslint-plugin 0.6.0 → 0.8.0

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

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

@@ -11,7 +11,8 @@ import type { WrapperSpec } from 'sh-ast/analyze';
 /**
  * Bash's `builtin [shell-builtin [args …]]`: runs the named builtin, bypassing
  * any function of the same name. It takes no options of its own, so the word
- * after it is the command it runs.
+ * after it is the command it runs. Only the exact builtin name has these
+ * semantics; an executable path with the same basename is an ordinary program.
  *
  * `sh-ast/analyze`'s default wrapper table leaves `builtin` out, so
  * `builtin "$x"` would otherwise resolve to the static command `builtin`.
@@ -42,8 +43,8 @@ export declare const BUILTIN_WRAPPER: WrapperSpec;
  * clusters ending in `c` or `s` are listed as exact tokens. Longer clusters
  * (`-xec`) end in `'unknown-flag'`.
  *
- * Names match exactly, like every `sh-ast/analyze` wrapper: `/bin/bash` is not
- * `bash`.
+ * Wrapper names also match the final segment of absolute paths (`/bin/bash`).
+ * Relative paths require an exact table entry.
  *
  * @see https://www.gnu.org/software/bash/manual/bash.html#Invoking-Bash
  * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/sh.html — POSIX `sh`

package/dist/rules/transparent-wrappers.js

@@ -1,7 +1,8 @@
 /**
  * Bash's `builtin [shell-builtin [args …]]`: runs the named builtin, bypassing
  * any function of the same name. It takes no options of its own, so the word
- * after it is the command it runs.
+ * after it is the command it runs. Only the exact builtin name has these
+ * semantics; an executable path with the same basename is an ordinary program.
  *
  * `sh-ast/analyze`'s default wrapper table leaves `builtin` out, so
  * `builtin "$x"` would otherwise resolve to the static command `builtin`.
@@ -9,7 +10,7 @@
  * @see https://www.gnu.org/software/bash/manual/bash.html#Bash-Builtins — `builtin`
  * @internal
  */
-export const BUILTIN_WRAPPER = { names: ['builtin'] };
+export const BUILTIN_WRAPPER = { names: ['builtin'], shellBuiltin: true };
 /**
  * The single-letter shell options that take no operand when a shell is
  * invoked: every option letter the `set` builtin accepts, plus Bash's
@@ -67,8 +68,8 @@ const SHELL_NO_ARG_LETTERS = [
  * clusters ending in `c` or `s` are listed as exact tokens. Longer clusters
  * (`-xec`) end in `'unknown-flag'`.
  *
- * Names match exactly, like every `sh-ast/analyze` wrapper: `/bin/bash` is not
- * `bash`.
+ * Wrapper names also match the final segment of absolute paths (`/bin/bash`).
+ * Relative paths require an exact table entry.
  *
  * @see https://www.gnu.org/software/bash/manual/bash.html#Invoking-Bash
  * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/sh.html — POSIX `sh`

package/dist/rules/user-pattern.d.ts

@@ -1,6 +1,7 @@
 /**
  * Compiling regular-expression sources that a rule takes from its options and
- * tests against text from the linted script.
+ * tests against text from the linted script. Every source uses Unicode (`u`)
+ * semantics; callers choose whether matching also ignores case.
  *
  * The configuration is trusted, but the subject is not: when the plugin lints
  * a repository it does not control, the script's author picks the names a
@@ -48,7 +49,7 @@ export declare function findNestedRepetition(source: string): NestedRepetition |
 /**
  * Compiles a regular-expression source from a rule option that will be tested
  * against script-controlled text. Throws a `TypeError` naming the rule and the
- * option when the source is not a valid expression, or when it nests one
+ * option and source when it is not a valid Unicode expression, or when it nests one
  * repetition inside another (see {@link findNestedRepetition}). ESLint reports
  * the error from the rule's `create()`, so it surfaces on the first file linted
  * with the rule ("Occurred while linting <file>"), not when the config loads.
@@ -56,7 +57,8 @@ export declare function findNestedRepetition(source: string): NestedRepetition |
  * @param rule - The rule's full name, such as `sh/prefer-local`.
  * @param option - The option as the user wrote it, such as `patterns[0]`.
  * @param source - The regular-expression source.
- * @param flags - The flags to compile with.
+ * @param flags - Rule-specific flags. Unicode semantics are always added;
+ * case-insensitivity is preserved without changing the subject or source.
  *
  * @internal
  */

package/dist/rules/user-pattern.js

@@ -1,6 +1,7 @@
 /**
  * Compiling regular-expression sources that a rule takes from its options and
- * tests against text from the linted script.
+ * tests against text from the linted script. Every source uses Unicode (`u`)
+ * semantics; callers choose whether matching also ignores case.
  *
  * The configuration is trusted, but the subject is not: when the plugin lints
  * a repository it does not control, the script's author picks the names a
@@ -153,7 +154,7 @@ export function findNestedRepetition(source) {
 /**
  * Compiles a regular-expression source from a rule option that will be tested
  * against script-controlled text. Throws a `TypeError` naming the rule and the
- * option when the source is not a valid expression, or when it nests one
+ * option and source when it is not a valid Unicode expression, or when it nests one
  * repetition inside another (see {@link findNestedRepetition}). ESLint reports
  * the error from the rule's `create()`, so it surfaces on the first file linted
  * with the rule ("Occurred while linting <file>"), not when the config loads.
@@ -161,14 +162,15 @@ export function findNestedRepetition(source) {
  * @param rule - The rule's full name, such as `sh/prefer-local`.
  * @param option - The option as the user wrote it, such as `patterns[0]`.
  * @param source - The regular-expression source.
- * @param flags - The flags to compile with.
+ * @param flags - Rule-specific flags. Unicode semantics are always added;
+ * case-insensitivity is preserved without changing the subject or source.
  *
  * @internal
  */
 export function compileUserPattern(rule, option, source, flags) {
     let pattern;
     try {
-        pattern = new RegExp(source, flags);
+        pattern = new RegExp(source, flags.includes('u') ? flags : `${flags}u`);
     }
     catch {
         throw new TypeError(`${rule}: \`${option}\` must be a valid regular expression; got ${JSON.stringify(source)}.`);

package/dist/syntax/index.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
  */
 export * from 'sh-ast';

package/dist/syntax/index.js

@@ -20,6 +20,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
  */
 export * from 'sh-ast';

package/docs/compat.md

@@ -5,14 +5,14 @@ are for scripts that must run on an older Bash, such as the Bash 3.2 that macOS
 `/bin/bash`, or on a plain POSIX `sh`.
 
 `compat/*` is reserved for version gates: rules that read the gate table below and your
-`shellVersion`/`dialect`. A rule that checks the file against your config without reading the
+`minBashVersion`/`dialect`. A rule that checks the file against your config without reading the
 target, such as [`sh/shebang-matches-dialect`](./rules/shebang-matches-dialect.md), lives outside
 the namespace.
 
-The parser does not do this for you. It accepts everything its grammar knows, whatever target
-you configure: Bash mode parses `declare -A` and `mapfile` even with `shellVersion: "3.2"`, and
+The parser does not do this for you. It accepts everything its grammar knows, whatever support requirement
+you configure: Bash mode parses `declare -A` and `mapfile` even with `minBashVersion: "3.2"`, and
 POSIX mode parses `declare -A` as an ordinary command. Only the `compat/*` rules enforce the
-target.
+support requirement.
 
 A `compat/*` finding stays reported when the code is behind a runtime version guard
 (`if (( BASH_VERSINFO[0] >= 4 )); then …`): the rules do not follow control flow. Silence a guarded
@@ -31,6 +31,7 @@ fi
 | ---- | ------- | ---- | -------- |
 | [`sh/compat/no-append-all-redirect`](./rules/compat/no-append-all-redirect.md) | `&>>` | 4.0 | no |
 | [`sh/compat/no-associative-arrays`](./rules/compat/no-associative-arrays.md) | `declare -A`, `typeset -A` | 4.0 | no |
+| [`sh/compat/no-brace-sequence-padding-step`](./rules/compat/no-brace-sequence-padding-step.md) | `{01..10}`, `{1..10..2}`, `{a..e..2}` | 4.0 | no |
 | [`sh/compat/no-case-attributes`](./rules/compat/no-case-attributes.md) | `declare -l`, `declare -u` (and `typeset`, `local`) | 4.0 | no |
 | [`sh/compat/no-case-fallthrough`](./rules/compat/no-case-fallthrough.md) | `;&`, `;;&` in `case` | 4.0 | no |
 | [`sh/compat/no-case-modification`](./rules/compat/no-case-modification.md) | `${v^}`, `${v^^}`, `${v,}`, `${v,,}` | 4.0 | no |
@@ -63,12 +64,13 @@ reports each operator against its own release. `sh/compat/no-unicode-escape` nee
 points but 4.3 for U+0080 to U+00FF, because the Bash 4.2 release writes those as a single Latin-1 byte
 instead of UTF-8. `sh/compat/no-nounset-empty-array` gates a behavior, not syntax: every Bash has
 `"${a[@]}"`, but through 4.3 an empty array aborts the script under `set -u`. `every` means every Bash release has the feature, so only
-`dialect: "posix"` can lack it: those three are the POSIX-only gates, and the other twenty-one are
-the version gates. The `bash-3.2` preset enables the version gates and the `posix-portable` preset
-enables all twenty-four; see
+`dialect: "posix"` can lack it: those three are the POSIX-only gates, and the other twenty-two are
+the version gates. The `bash-3.2` preset enables twenty-one version gates, excluding the opt-in
+`sh/compat/no-nounset-empty-array`, and the `posix-portable` preset
+enables all twenty-five; see
 [Presets](#presets).
 
-## Setting the target
+## Setting required shell support
 
 Every `compat/*` rule reads the same two `languageOptions`, and nothing else. They have no rule
 options of their own:
@@ -81,7 +83,7 @@ import sh from '@eslint-sh/eslint-plugin';
 export default defineConfig({
   files: ['**/*.sh'],
   extends: [sh.configs.recommended],
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-associative-arrays': 'error',
     'sh/compat/no-mapfile': 'error',
@@ -92,33 +94,67 @@ export default defineConfig({
 
 A gated feature is available, and its rule reports nothing, according to these rules:
 
-- **`shellVersion` unset means the newest version.** With no `shellVersion`, every Bash feature
-  is available and no `compat/*` rule reports under `dialect: "bash"`. Set a version to opt in.
-- **Versions compare numerically, major first, then minor.** `shellVersion` has the shape
+- **`minBashVersion` is a floor.** `"3.2"` means the script must support Bash 3.2 and
+  every newer Bash. Nothing checks for a version being too new. Unset means no Bash
+  version constraint, so Bash version gates report nothing under `bash` or `bats`.
+- **Versions compare numerically, major first, then minor.** `minBashVersion` has the shape
   `MAJOR[.MINOR]`. A missing minor is `0`, so `"4"` is the same as `"4.0"`. Each part is a
   number, not text, so `"3.10"` is newer than `"3.2"` and still older than `"4.0"`. A feature
-  is available when `shellVersion` is its minimum version or newer.
-- **`dialect: "posix"` makes Bash-only features unavailable at any `shellVersion`.** A POSIX sh
-  script cannot rely on a feature that only Bash has, whatever version number is configured.
-- **`dialect: "bats"` is gated as Bash**, because Bats test files run under Bash.
-  `shellVersion` is the version of that Bash.
-- **`dialect: "mksh"` and `dialect: "zsh"` are not gated.** These shells number their own
-  releases, so a `shellVersion` there is not a Bash version, and the rules have no data on
-  which of their releases added which feature. The `compat/*` rules report nothing for them.
+  is available when the configured floor is its first Bash release or newer.
+- **Only `bash` and `bats` accept `minBashVersion`.** An omitted `dialect` defaults to
+  `bash`. Bats test files run under Bash and use the same floor. With `posix`, `mksh` or
+  `zsh`, remove `minBashVersion` or change the dialect to `bash` or `bats`; otherwise
+  ESLint rejects the config before linting.
+- **`dialect: "posix"` makes Bash-only features unavailable.** A POSIX sh script cannot
+  rely on a feature that only Bash has.
+- **`dialect: "mksh"` and `dialect: "zsh"` are not gated.** The table has no release data
+  for these shells, so the `compat/*` rules report nothing for them.
+
+### Migrating from `shellVersion`
+
+Replace `languageOptions.shellVersion` with `languageOptions.minBashVersion` and custom
+rule reads of `sourceCode.shellVersion` with `sourceCode.minBashVersion`. The old option
+is removed, with no alias: ESLint rejects it with migration guidance. The normalized and
+JSON option types use `minBashVersion` too. For `posix`, `mksh` and `zsh`, remove the old
+option rather than renaming it, because a Bash floor does not apply to these dialects.
+
+Check inherited options too. Extending `sh.configs['bash-3.2']` and then setting
+`languageOptions: { dialect: 'posix' }` retains the preset's Bash 3.2 floor and now
+throws a config error. Extending `[sh.configs['bash-3.2'], sh.configs['posix-portable']]`
+also throws: the later POSIX preset changes the dialect without removing the inherited
+floor. Setting `minBashVersion: undefined` does **not** clear that floor during ESLint's
+config merge, so it does not fix either composition.
+
+For scripts that must support POSIX sh, replace the Bash preset with the intended POSIX
+preset, without inheriting `bash-3.2` from any config that applies to those files:
+
+```js
+// eslint.config.js
+import { defineConfig } from 'eslint/config';
+import sh from '@eslint-sh/eslint-plugin';
+
+export default defineConfig({
+  files: ['**/*.sh'],
+  extends: [sh.configs.recommended, sh.configs['posix-portable']],
+});
+```
 
 ## Presets
 
-Two presets name a deployment target and enable every rule that enforces it, so you do not list
-the rules yourself:
+Two presets name a deployment target and enable its checks, with the empty-array nounset check
+an explicit opt-in for Bash:
 
-- **`sh.configs['bash-3.2']`** sets `languageOptions: { dialect: 'bash', shellVersion: '3.2' }`
-  and enables all twenty-one version-gated `compat/*` rules at `error`. Use it for scripts that must run on the Bash
-  3.2 that macOS ships as `/bin/bash`.
+- **`sh.configs['bash-3.2']`** sets `languageOptions: { dialect: 'bash', minBashVersion: '3.2' }`
+  and enables twenty-one version-gated `compat/*` rules at `error`. Use it for scripts that must run on the Bash
+  3.2 that macOS ships as `/bin/bash`. It leaves `sh/compat/no-nounset-empty-array` off: enable
+  that rule explicitly when a script uses `set -u` and arrays that can really be empty. The rule
+  cannot prove safety across every caller or helper contract; see its
+  [configuration example](./rules/compat/no-nounset-empty-array.md#options).
 - **`sh.configs['posix-portable']`** reports the Bash-only constructs in the table above, which
   fail or read as unset on dash, but not `local`, `echo -e` or the others listed under
   [What `posix-portable` does not report](#what-posix-portable-does-not-report), so a clean run does
   not prove a script runs under every POSIX `sh`. It sets `languageOptions: { dialect: 'posix' }` and
-  enables all twenty-four `compat/*` rules, `sh/shebang-matches-dialect`, and
+  enables all twenty-five `compat/*` rules, `sh/shebang-matches-dialect`, and
   `sh/require-strict-mode` configured as `set -eu`, all at `error`. Strict mode is `set -eu` and not
   `set -euo pipefail` because `pipefail` joined POSIX only in POSIX.1-2024, and older `dash` and
   BusyBox `ash` reject it, so a `pipefail` requirement would make the autofix break a working
@@ -205,10 +241,6 @@ suggestion that you apply by choice. Each rule's page says when it offers one.
 
 ## Not covered
 
-- **Zero-padded and stepped brace sequences** (`{01..10}`, `{1..10..2}`, Bash 4.0). Bash 3.2 drops
-  the padding and leaves the stepped form unexpanded, with no error. The parser keeps a brace
-  expansion as part of a word's literal text and gives it no node of its own, so a rule could find
-  one only by matching text, which would also match literal braces. No rule reports it.
 - **Bash syntax that the POSIX parser rejects.** Under `dialect: "posix"`, `|&`, `&>>`, `;&`, `;;&`,
   `{fd}` redirections, `${v@op}` and arrays are parse errors, so a POSIX file that uses them is
   reported as unparsable, and the rules for those features never run on it. `$'…'` is read as a
@@ -226,6 +258,14 @@ is installed system-wide), and runs every probe in
 scripts/compat-matrix/run.sh
 ```
 
+Builds use at most two compiler jobs and retry serially if parallel `make` fails. Bash 3.2–4.2
+use `config.guess` and `config.sub` from the checksum-pinned Bash 5.3 archive so their configure
+scripts recognize aarch64, including Linux containers on Apple Silicon. Only platform-detection
+helpers are replaced; the shell sources retain their pinned release checksums. The script keeps
+running other shells after a failure, labels the affected column `download failed`,
+`checksum mismatch`, or `build failed`, and exits 1 after printing the table. Invalid arguments,
+including an inaccessible `--probes` directory, exit 2.
+
 A probe is a short script that uses one feature, or one recommended alternative, and prints a known
 value. "yes" means the shell ran it, exited 0, and printed exactly that value; "no" means it did not.
 Each Bash column is the x.y release tarball with no upstream patches applied, pinned by SHA-256 in
@@ -236,6 +276,8 @@ the script. The `dash` column is the evidence for the POSIX sh column.
 | `associative-arrays-alt-jq` | the message's `jq -r --arg k "$key" '.[$k]' map.json` lookup (needs `jq` on PATH) | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
 | `associative-arrays-typeset` | `typeset -A m` keeps two string keys apart | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
 | `associative-arrays` | `declare -A m` keeps two string keys apart | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `brace-pad-step` | zero-padded `{01..03}` and stepped `{1..9..4}` brace expansion | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `brace-sequence-alt-loop` | the messages' counting loops, the padded one with `printf '%02d\n'` and the stepped one by `i + 4`, each written exactly as printed | not run | not run | not run | not run | not run | not run | not run | not run | not run | not run | not run |
 | `case-attributes-alt-tr` | the message's `$(printf '%s' "$v" \| tr '[:upper:]' '[:lower:]')` and its upper-case twin | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
 | `case-fallthrough-alt` | the message's rewrites: the next branch's commands repeated for `;&`, and a second `case` for `;;&` | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
 | `case-fallthrough` | `;&` runs the next branch without testing its pattern | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
@@ -283,11 +325,11 @@ the script. The `dash` column is the evidence for the POSIX sh column.
 | `nounset-empty-array-star-alt` | the suggestion's `"${a[*]-}"` under `set -u` gives one empty word for an empty array, and the joined words otherwise | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
 | `nounset-empty-array-star` | `"${a[*]}"` and unquoted `${a[@]}` of an empty array under `set -u` | no | no | no | no | no | yes | yes | yes | yes | yes | no |
 | `nounset-empty-array` | `"${a[@]}"` of an empty array under `set -u` | no | no | no | no | no | yes | yes | yes | yes | yes | no |
-| `param-transform-alt-case-operators` | the case messages' Bash 4.0 spellings for a target from 4.0 to 5.0: `"${v^^}"`, `"${v^}"`, `"${V,,}"` | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `param-transform-alt-case-operators` | the case messages' Bash 4.0 spellings when the minimum supported Bash is from 4.0 to 5.0: `"${v^^}"`, `"${v^}"`, `"${V,,}"` | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
 | `param-transform-alt-declare-p` | the `@A` message's `declare -p`, whose output re-creates the variable | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
 | `param-transform-alt-printf-b` | the `@E` message's `printf '%b'` expanding backslash escapes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
 | `param-transform-alt-printf-q` | the `@Q` message's `printf '%q'`, whose output `eval` reads back as the same value | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
-| `param-transform-alt-tr` | the `tr` examples the `@U`, `@u` and `@L` messages print for a target older than 4.0, written exactly as printed | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `param-transform-alt-tr` | the `tr` examples the `@U`, `@u` and `@L` messages print when the minimum supported Bash is older than 4.0, written exactly as printed | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
 | `param-transform-eapa` | the other Bash 4.4 operators `${v@E}`, `${v@P}`, `${v@A}`, `${v@a}` | no | no | no | no | no | yes | yes | yes | yes | yes | no |
 | `param-transform-k-lower` | `${a[@]@k}` key-value pairs as separate words | no | no | no | no | no | no | no | no | yes | yes | no |
 | `param-transform-k-upper` | `${a[@]@K}` quoted key-value pairs | no | no | no | no | no | no | no | yes | yes | yes | no |
@@ -316,7 +358,7 @@ How to read it:
   matrix because it is the release just before the 4.2 boundary of `declare -g` and `lastpipe`.
   Bash 4.0 is the release just before the 4.1 boundary of `{fd}` redirections.
 - **POSIX-only gates.** The rows for `[[`, `let` and `source`, the rule table's `every`, are "yes" on
-  every Bash in the matrix and "no" under dash, so no `shellVersion` can change whether they report.
+  every Bash in the matrix and "no" under dash, so no `minBashVersion` can change whether they report.
   dash runs a script past each one without a syntax error, which is why a shell's own version check
   can guard them; see [A branch for one shell](#a-branch-for-one-shell).
 - **Parameter transformations.** `@Q`, `@E`, `@P`, `@A` and `@a` start working in 4.4; `@U`, `@u`,
@@ -331,9 +373,17 @@ How to read it:
   which a minimum-version gate cannot express, so the rule does not report them.
 - **Negative subscripts.** Bash 4.2 reads `${a[-1]}`, but rejects `${#a[-1]}`, `a[-1]=Z` and
   `unset 'a[-1]'` with `bad array subscript`. 4.3 is the first release where every form works.
+- **Brace sequences.** `brace-pad-step` is "no" on Bash 3.2, which prints `1 2 3 {1..9..4}` with
+  no error, and on dash, which prints `{01..03} {1..9..4}`; it is "yes" from 4.0. That row records
+  the `run.sh` result reported in issue #237; the probe was also re-run on `/bin/bash` (3.2.57),
+  Homebrew's Bash 5.3.9 and the system `dash`, with the same outcomes. The
+  `brace-sequence-alt-loop` row has not been run through `run.sh`: its probe was run only on macOS's
+  `/bin/bash` (3.2.57), Homebrew's Bash 5.3.9 and the system `dash`, which are distribution builds,
+  not the tarball releases in the other columns, and each printed the expected line. Fill the row by
+  running `scripts/compat-matrix/run.sh`.
 - **Alternatives.** Every alternative a message recommends for a Bash target works on Bash 3.2,
   except `param-transform-alt-case-operators` (`"${v^^}"` and its twins), which the
-  `no-parameter-transformation` message offers only for a target from 4.0 to 5.0, where it works.
+  `no-parameter-transformation` message offers only when the minimum supported Bash is from 4.0 to 5.0, where it works.
   The ones that are "no" under dash (`< <(cmd)`, the `mapfile` suggestion's array loop, the
   `${arr[$((${#arr[@]}-1))]}` count, `printf -v`, `printf '%q'`, `declare -p`, the `${a[@]+…}` and
   `${a[*]-}` guards, `$'\303\251'`) use Bash syntax and appear only in Bash-target messages; the
@@ -344,4 +394,10 @@ How to read it:
   `date`. `%s` is not in POSIX `date`; the message says so.
 - **`jq`.** The `no-associative-arrays` advice runs an external program, so its row shows that the
   command as written works wherever `jq` is installed, not that a shell provides it.
+- **Plain assignments.** `declare-g-alt-assign` confirms that `name=value` and `export name=value`
+  inside a function leave values visible after the function returns when no caller has a
+  same-named local. It is not a discriminating test of `declare -g`: ordinary assignment follows
+  a caller's local scope, whereas `declare -g` explicitly targets the global in Bash 4.3–5.3 but
+  assigns a same-named caller local in Bash 4.2, leaving the global unset. The row does not
+  establish that the plain-assignment advice is interchangeable with `declare -g` in that case.
 

package/docs/custom-rule-tutorial.md

@@ -421,6 +421,11 @@ with, so you don't install `sh-ast` and its version always matches the records `
 They track the plugin's pinned `sh-ast` minor: an `sh-ast` 0.x minor bump is a minor release of the
 plugin.
 
+The low-level `/syntax` export `printSync` retains upstream behavior: literal vertical tabs and
+form feeds can change during printing, including inside quotes. It does not apply the high-level
+content refusal used by `format` or `getPrintedReplacement`. For an ESLint printed fix, use
+`getPrintedReplacement`, which refuses these values with `TypeError`.
+
 ## 8. Printed fixes
 
 Some fixes are easier to describe as an edit to the syntax than as new text. Turning
@@ -437,7 +442,8 @@ into an ESLint fix:
   returns `{ range, text }`, ready for `fixer.replaceTextRange(range, text)`. The range is
   `node.range`, or the whole file when `edited` is a `File`. `edited` must be a root `printSync`
   accepts (`File`, `Stmt`, `Word`, `Assign`, a `Command` or a `WordPart`), and output that is not
-  valid UTF-8 throws a `TypeError` instead of becoming a fix.
+  valid UTF-8 or edited syntax containing literal vertical tabs or form feeds throws a `TypeError`
+  instead of becoming a fix. A `File`'s `Name` is unprinted metadata and does not trigger that refusal.
 
 `docs/examples/no-backticks-rule.mjs` reports backtick command substitution and fixes it to `$(…)`:
 
@@ -714,13 +720,13 @@ import type { ShellCommandSite, ShellRuleContext } from '@eslint-sh/eslint-plugi
 /** The rule's one options object; `commands` defaults to `[]`. */
 type Options = [{ commands?: string[] }?];
 
-/** Reports `site` when the command it runs, after wrappers, is in `listed`. */
+/** Reports the program named by `site`, after wrappers, including interpreters running strings. */
 function reportIfListed(
   context: ShellRuleContext<Options, 'listed'>,
   site: ShellCommandSite,
   listed: ReadonlySet<string>,
 ): void {
-  const { effective } = site.resolveInvokedCommand();
+  const { effective } = site.resolveInvokedCommand({ embeddedCommandInterpreters: [] });
   if (effective.static && listed.has(effective.text)) {
     context.report({ node: site.node, messageId: 'listed', data: { name: effective.text } });
   }

package/docs/examples/no-listed-commands-rule.ts

@@ -19,13 +19,13 @@ import type { ShellCommandSite, ShellRuleContext } from '@eslint-sh/eslint-plugi
 /** The rule's one options object; `commands` defaults to `[]`. */
 type Options = [{ commands?: string[] }?];
 
-/** Reports `site` when the command it runs, after wrappers, is in `listed`. */
+/** Reports the program named by `site`, after wrappers, including interpreters running strings. */
 function reportIfListed(
   context: ShellRuleContext<Options, 'listed'>,
   site: ShellCommandSite,
   listed: ReadonlySet<string>,
 ): void {
-  const { effective } = site.resolveInvokedCommand();
+  const { effective } = site.resolveInvokedCommand({ embeddedCommandInterpreters: [] });
   if (effective.static && listed.has(effective.text)) {
     context.report({ node: site.node, messageId: 'listed', data: { name: effective.text } });
   }