@eslint-sh/eslint-plugin 0.7.0 → 0.8.0

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
@@ -65,11 +65,12 @@ points but 4.3 for U+0080 to U+00FF, because the Bash 4.2 release writes those a
 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-two are
-the version gates. The `bash-3.2` preset enables the version gates and the `posix-portable` preset
+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:
@@ -82,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',
@@ -93,28 +94,62 @@ 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-two 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
@@ -223,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
@@ -282,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 |
@@ -315,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`,
@@ -340,7 +383,7 @@ How to read it:
   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
@@ -351,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 } });
   }

package/docs/rules/README.md

@@ -27,7 +27,7 @@ See the [canonical quickstart](https://github.com/mike-north/eslint-sh/blob/main
 | [`sh/compat/no-mapfile`](./compat/no-mapfile.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow `mapfile` / `readarray` when the target shell lacks them, suggesting a read loop. |
 | [`sh/compat/no-nameref`](./compat/no-nameref.md) | `bash-3.2`, `posix-portable` | No | No | Disallow namerefs (`declare -n`, `local -n`) when the target shell lacks them. |
 | [`sh/compat/no-negative-array-index`](./compat/no-negative-array-index.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow negative array subscripts when the target shell lacks them, suggesting a length-based index. |
-| [`sh/compat/no-nounset-empty-array`](./compat/no-nounset-empty-array.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow whole-array expansions under `set -u` when the target shell aborts on an empty array, suggesting a guarded form. |
+| [`sh/compat/no-nounset-empty-array`](./compat/no-nounset-empty-array.md) | `posix-portable` | No | Yes | Disallow whole-array expansions under `set -u` when the target shell aborts on an empty array, suggesting a guarded form. |
 | [`sh/compat/no-parameter-transformation`](./compat/no-parameter-transformation.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `${v@op}` transformations when the target shell lacks the operator. |
 | [`sh/compat/no-pipe-all`](./compat/no-pipe-all.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow the stderr-merging pipe (pipe-ampersand) when the target shell lacks it, suggesting an explicit `2>&1` before the pipe. |
 | [`sh/compat/no-printf-time-format`](./compat/no-printf-time-format.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `printf`'s `%(fmt)T` date format when the target shell lacks it. |
@@ -60,9 +60,11 @@ describes edits available through `eslint --fix`. `quote-expansions` suggests qu
 fixing because only the script's author knows whether the splitting was intended.
 
 The version-gated `compat/*` rules (`compat/no-append-all-redirect`, `compat/no-associative-arrays`, `compat/no-brace-sequence-padding-step`, `compat/no-case-attributes`, `compat/no-case-fallthrough`, `compat/no-case-modification`, `compat/no-coproc`, `compat/no-declare-g`, `compat/no-epoch-variables`, `compat/no-fd-variable`, `compat/no-globstar`, `compat/no-lastpipe-semantics`, `compat/no-mapfile`, `compat/no-nameref`, `compat/no-negative-array-index`, `compat/no-nounset-empty-array`, `compat/no-parameter-transformation`, `compat/no-pipe-all`, `compat/no-printf-time-format`, `compat/no-test-v`, `compat/no-unicode-escape`, `compat/no-wait-n`) report
-shell features that your target shell lacks, as set by `languageOptions.shellVersion` and
-`dialect`. They report nothing when `shellVersion` is unset, so the `bash-3.2` preset sets it to `3.2`
-and the `posix-portable` preset sets `dialect: "posix"`; each enables all of them.
+shell features that your target shell lacks, as set by `languageOptions.minBashVersion` and
+`dialect`. They report nothing when `minBashVersion` is unset, so the `bash-3.2` preset sets it to `3.2`
+and the `posix-portable` preset sets `dialect: "posix"`. `bash-3.2` enables all except
+`compat/no-nounset-empty-array`, which is opt-in for scripts using `set -u` on Bash below 4.4
+with arrays that can really be empty; `posix-portable` retains all of them.
 See [version compatibility](../compat.md). `compat/*` means target gates only; `shebang-matches-dialect`
 compares the file with your config whatever the target, so it lives outside that namespace. `posix-portable` also enables
 `shebang-matches-dialect`, `require-strict-mode` (as `set -eu`) and the POSIX-only gates
@@ -77,3 +79,33 @@ To run these rules beside shellcheck, see [shellcheck](../shellcheck.md).
 `require-network-wrapper` reports nothing until you set its `wrapper` option (see
 [wrapper rules](../wrapper-rules.md)). Each linked rule page documents its options, limitations,
 and relationship to shellcheck.
+
+## Regular-expression options
+
+Every regular-expression source in a rule option is compiled with JavaScript's `u` flag
+(Unicode). `sh/no-secret-flags` also uses `i`, preserving case-insensitive matching for
+both default and custom patterns. `sh/no-secret-env-reads` and `sh/prefer-local` match
+case-sensitively. The original name and pattern are used without lower-casing either.
+Thus `patterns: ['token']` catches `--TOKEN` in `no-secret-flags`, but does not catch
+`$GITHUB_TOKEN` in `no-secret-env-reads`. `allowPattern: '^g_'` exempts `g_cache`, but not
+`G_cache`, in `prefer-local`. Sources are strings, without `/` delimiters or flag suffixes;
+write `\\p{Lu}` in a JavaScript string to match an uppercase Unicode letter.
+
+The shared compiler validates syntax with these actual flags, then applies the
+[pattern-safety guard](./no-secret-flags.md#patterns-run-against-script-controlled-text).
+All regex syntax errors, including `(`, fail when the enabled rule first runs on a file.
+The error names the rule, option (including the array index) and pattern; ESLint reports
+"Occurred while linting <file>" and exits with status 2.
+
+Config resolution does not compile regex sources: `--print-config` will not catch any regex syntax errors.
+The schemas still check option types and array lengths, but deliberately omit the `regex`
+format. ESLint validates that format without flags, which would reject Unicode-valid sources
+such as `^[\u{41}-\u{5A}]+$` (an uppercase-letter range under `u`). Keeping compilation in the
+rule allows these sources and gives every syntax error the same first-rule-run timing.
+
+Migration: sources accepted without `u` may now fail, including identity escapes such as
+`\-` outside a character class, `\q` (also invalid inside `[\q]`), and incomplete quantifiers
+such as `a{,5}`. Use `-`, `q` or `a\\{,5\\}` respectively in JavaScript strings for those
+literal characters. An escaped hyphen **inside** a class (`[\-]`, written `'[\\-]'` in a
+JavaScript string) remains valid. Unicode property escapes (`\p{Lu}`) and code point escapes
+(`\u{1F510}`) now have their Unicode meaning in every regex option.

package/docs/rules/_template.md

@@ -15,7 +15,7 @@
   `{"options": {"maxNesting": 2}, "dialect": "bash"}`, then the usual closing. See any
   existing page, e.g. `max-script-complexity.md`, for the exact spelling.
 
-  Keys: `options` (the rule's options value), `dialect`, `shellVersion`, `convention`
+  Keys: `options` (the rule's options value), `dialect`, `minBashVersion`, `convention`
   (`"commentPragma"`) and `filename`. Under `### Incorrect` you may also state what the prose
   claims exactly: `findings` (a count), `messageIds` (in report order), `output` (the source
   after autofix) and `suggestionOutputs`. A typo in the annotation fails the test.
@@ -38,7 +38,7 @@
 
 <Why this policy matters for shell scripts, and exactly what the rule reports. Say which
 node types or constructs it inspects and which it deliberately ignores. If the rule depends on
-`languageOptions` (`dialect`, `shellVersion`), say how.>
+`languageOptions` (`dialect`, `minBashVersion`), say how.>
 
 ## Options
 

package/docs/rules/compat/no-append-all-redirect.md

@@ -21,15 +21,15 @@ Under `dialect: "posix"` the parser itself rejects `&>>`, so a POSIX file that u
 This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
 described in [version compatibility](../../compat.md):
 
-- `shellVersion` unset: never reports. An unset version means the newest Bash.
-- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.0`.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` is older than `4.0`.
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 ### Suggestion
 
 A suggestion rewrites the redirection:
 
-<!-- transform: {"kind": "suggestion", "dialect": "bash", "shellVersion": "3.2"} -->
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 build &>> build.log
 # becomes
@@ -38,12 +38,12 @@ build >> build.log 2>&1
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-append-all-redirect': 'error',
   },
@@ -54,29 +54,29 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 1} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 1} -->
 ```sh
 build &>> build.log
 ```
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 build >> build.log 2>&1
 build &> build.log
 echo "use &>> on Bash 4"
 ```
 
-With `shellVersion: "4.0"` or newer, or with no `shellVersion`, `&>>` is fine.
+With `minBashVersion: "4.0"` or newer, or with no `minBashVersion`, `&>>` is fine.
 
 ## When not to use it
 
-Turn the rule off when your scripts never run on Bash older than 4.0, or leave `shellVersion`
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -84,4 +84,4 @@ unset, which makes the rule report nothing.
 eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
 layer. Run shellcheck beside it.
 
-shellcheck 0.11.0 reports nothing for `cmd &>> log` under either `-s sh` or `-s bash`. (`cmd &> log` is different: it reports SC3020 under `-s sh`.) So shellcheck gives no finding for `&>>` in a POSIX sh script or in a Bash 3.2 target. This rule exists for both.
+shellcheck 0.11.0 reports nothing for `cmd &>> log` under either `-s sh` or `-s bash`. (`cmd &> log` is different: it reports SC3020 under `-s sh`.) So shellcheck gives no finding for `&>>` in a POSIX sh script or in a script that must support Bash 3.2. This rule exists for both.

package/docs/rules/compat/no-associative-arrays.md

@@ -1,6 +1,6 @@
 # `sh/compat/no-associative-arrays`
 
-Disallow associative arrays (`declare -A`, `typeset -A`) in scripts whose target shell lacks
+Disallow associative arrays (`declare -A`, `typeset -A`) in scripts that must support a shell lacking
 them: Bash older than 4.0, including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
 
 | Configs | Fixable     | Languages |
@@ -17,9 +17,9 @@ return the wrong values without an error.
 This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
 described in [version compatibility](../../compat.md):
 
-- `shellVersion` unset: never reports. An unset version means the newest Bash.
-- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.0`.
-- `dialect: "posix"`: reports at any `shellVersion`, because POSIX sh has no arrays.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` is older than `4.0`.
+- `dialect: "posix"`: reports regardless of Bash releases, because POSIX sh has no arrays.
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 The rule reads the options of every `declare` and `typeset` command, up to the first operand,
@@ -37,12 +37,12 @@ The rule deliberately ignores:
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-associative-arrays': 'error',
   },
@@ -53,9 +53,9 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 4} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 4} -->
 ```sh
 declare -A ports            # associative arrays need Bash 4.0
 typeset -A ports            # the same declaration through typeset
@@ -65,9 +65,9 @@ builtin declare -A ports    # reached through the builtin wrapper
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 # Keep the mapping as JSON and look keys up with jq.
 port=$(jq -r --arg k "$service" '.[$k]' ports.json)
@@ -75,16 +75,16 @@ port=$(jq -r --arg k "$service" '.[$k]' ports.json)
 declare -a hosts            # indexed arrays exist in Bash 3.2
 ```
 
-With `shellVersion: "4.0"` or newer, or with no `shellVersion`:
+With `minBashVersion: "4.0"` or newer, or with no `minBashVersion`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "4.0"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "4.0"} -->
 ```sh
 declare -A ports
 ```
 
 ## When not to use it
 
-Turn the rule off when your scripts never run on Bash older than 4.0, or leave `shellVersion`
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -92,4 +92,4 @@ unset, which makes the rule report nothing.
 eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
 layer. Run shellcheck beside it.
 
-shellcheck 0.11.0 reports the command, not the option: under `-s sh`, `declare -A` draws SC3044 (`declare` is undefined in POSIX sh), and `local -A` draws SC3043. Under `-s bash` it reports nothing. It has no way to target a Bash version, so it reports nothing for `declare -A` in a script that must run on Bash 3.2. This rule exists for that target.
+shellcheck 0.11.0 reports the command, not the option: under `-s sh`, `declare -A` draws SC3044 (`declare` is undefined in POSIX sh), and `local -A` draws SC3043. Under `-s bash` it reports nothing. It has no way to check support for a minimum Bash version, so it reports nothing for `declare -A` in a script that must run on Bash 3.2. This rule checks that support requirement.