@eslint-sh/eslint-plugin 0.7.0 → 0.8.0

package/dist/language/shell-language-options.d.ts

@@ -3,7 +3,7 @@
 export type ShellDialect = 'bash' | 'posix' | 'mksh' | 'bats' | 'zsh';
 /**
  * `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.
  *
@@ -19,13 +19,14 @@ export type ShellDialect = 'bash' | 'posix' | 'mksh' | 'bats' | 'zsh';
 export 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
@@ -38,14 +39,14 @@ export 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
@@ -56,7 +57,7 @@ export interface ShellLanguageOptions extends Record<string, unknown> {
 export interface ShellLanguageOptionsJSON {
     readonly dialect: ShellDialect;
     readonly directivePrefix: string;
-    readonly shellVersion?: string;
+    readonly minBashVersion?: string;
 }
 /**
  * The result of {@link ShellLanguage.normalizeLanguageOptions}: `dialect` and
@@ -73,19 +74,21 @@ export interface ShellLanguageOptionsJSON {
 export interface NormalizedShellLanguageOptions extends Record<string, unknown> {
     readonly dialect: ShellDialect;
     readonly directivePrefix: string;
-    readonly shellVersion?: string;
+    readonly minBashVersion?: string;
     toJSON(): ShellLanguageOptionsJSON;
 }
 /**
  * Validates `languageOptions` for {@link ShellLanguage}. Throws a
  * `TypeError` when `dialect` is present but not one of the five supported
- * dialects, when `shellVersion` is present but not a string or does not
- * match the `MAJOR[.MINOR]` numeric shape (see {@link SHELL_VERSION_PATTERN};
+ * dialects, when `minBashVersion` is present but not a string or does not
+ * match the `MAJOR[.MINOR]` numeric shape (see {@link MIN_BASH_VERSION_PATTERN};
  * e.g. `''` and `'not-a-version'` are rejected, but a shape-valid,
  * nonexistent version like `'99.99'` is accepted — shape is validated, not
  * membership in a known-versions list), or when `directivePrefix` is present
  * but not a valid directive-comment label (see {@link DIRECTIVE_PREFIX_PATTERN}).
- * Unknown keys are silently ignored, per the ESLint `Language` contract.
+ * The Bash floor is rejected for dialects other than `bash` and `bats`.
+ * The removed `shellVersion` key throws with migration guidance, even if
+ * its value is undefined. Other unknown keys are silently ignored.
  *
  * The parameter is treated as `Record<string, unknown>` internally (rather
  * than trusting {@link ShellLanguageOptions}'s declared field types) because

package/dist/language/shell-language-options.js

@@ -30,31 +30,27 @@ function isValidDirectivePrefix(value) {
     return typeof value === 'string' && DIRECTIVE_PREFIX_PATTERN.test(value);
 }
 /**
- * Matches the `MAJOR[.MINOR]` numeric shape {@link validateShellLanguageOptions}
- * requires `shellVersion` to have (issue #34: the sibling `dialect` option throws
- * an exemplary enum-listing TypeError, while `shellVersion` accepted any
- * string — including `''` and `'not-a-version'` — with zero feedback). This
- * validates *shape only*, not membership in a known-versions list: a
- * shape-valid but nonexistent version like `'99.99'` is intentionally
- * accepted, per this issue's acceptance criteria and non-goals (per-dialect
- * known-version allowlists are out of scope). How rules consume
- * `shellVersion` is defined by the `compat/*` rules' gate
- * (`src/rules/compat/version-gates.ts`, documented in `docs/compat.md`).
+ * The Bash floor accepts numeric MAJOR[.MINOR] values, including future
+ * releases. Validation checks shape rather than a release allowlist;
+ * compatibility rules compare the floor with each feature's first release.
  */
-const SHELL_VERSION_PATTERN = /^\d+(?:\.\d+)?$/u;
-function isValidShellVersionShape(value) {
-    return SHELL_VERSION_PATTERN.test(value);
+const MIN_BASH_VERSION_PATTERN = /^\d+(?:\.\d+)?$/u;
+/** Whether a Bash floor has the numeric shape required for comparison. */
+function isValidMinBashVersionShape(value) {
+    return MIN_BASH_VERSION_PATTERN.test(value);
 }
 /**
  * Validates `languageOptions` for {@link ShellLanguage}. Throws a
  * `TypeError` when `dialect` is present but not one of the five supported
- * dialects, when `shellVersion` is present but not a string or does not
- * match the `MAJOR[.MINOR]` numeric shape (see {@link SHELL_VERSION_PATTERN};
+ * dialects, when `minBashVersion` is present but not a string or does not
+ * match the `MAJOR[.MINOR]` numeric shape (see {@link MIN_BASH_VERSION_PATTERN};
  * e.g. `''` and `'not-a-version'` are rejected, but a shape-valid,
  * nonexistent version like `'99.99'` is accepted — shape is validated, not
  * membership in a known-versions list), or when `directivePrefix` is present
  * but not a valid directive-comment label (see {@link DIRECTIVE_PREFIX_PATTERN}).
- * Unknown keys are silently ignored, per the ESLint `Language` contract.
+ * The Bash floor is rejected for dialects other than `bash` and `bats`.
+ * The removed `shellVersion` key throws with migration guidance, even if
+ * its value is undefined. Other unknown keys are silently ignored.
  *
  * The parameter is treated as `Record<string, unknown>` internally (rather
  * than trusting {@link ShellLanguageOptions}'s declared field types) because
@@ -64,15 +60,26 @@ function isValidShellVersionShape(value) {
  * @public
  */
 export function validateShellLanguageOptions(languageOptions) {
-    const { dialect, shellVersion, directivePrefix } = languageOptions;
+    // A removed key must not disappear during normalization: that would
+    // silently disable the consumer's compatibility requirement.
+    if ('shellVersion' in languageOptions) {
+        throw new TypeError('@eslint-sh/eslint-plugin: languageOptions.shellVersion has been removed. Use languageOptions.minBashVersion with dialect "bash" or "bats" instead.');
+    }
+    const { dialect, minBashVersion, directivePrefix } = languageOptions;
     if (dialect !== undefined && !isShellDialect(dialect)) {
         throw new TypeError(`@eslint-sh/eslint-plugin: languageOptions.dialect must be one of ${SUPPORTED_SHELL_DIALECTS.join(', ')}; received ${JSON.stringify(dialect)}.`);
     }
-    if (shellVersion !== undefined && typeof shellVersion !== 'string') {
-        throw new TypeError(`@eslint-sh/eslint-plugin: languageOptions.shellVersion must be a string (e.g. "3.2"); received ${JSON.stringify(shellVersion)}.`);
+    if (minBashVersion !== undefined &&
+        dialect !== undefined &&
+        dialect !== 'bash' &&
+        dialect !== 'bats') {
+        throw new TypeError(`@eslint-sh/eslint-plugin: languageOptions.minBashVersion applies only to bash and bats; dialect is "${dialect}". Remove minBashVersion or set dialect to "bash" or "bats".`);
+    }
+    if (minBashVersion !== undefined && typeof minBashVersion !== 'string') {
+        throw new TypeError(`@eslint-sh/eslint-plugin: languageOptions.minBashVersion must be a string (e.g. "3.2"); received ${JSON.stringify(minBashVersion)}.`);
     }
-    if (typeof shellVersion === 'string' && !isValidShellVersionShape(shellVersion)) {
-        throw new TypeError(`@eslint-sh/eslint-plugin: languageOptions.shellVersion must match the shape MAJOR[.MINOR] (e.g. "3.2", "5"); received ${JSON.stringify(shellVersion)}.`);
+    if (typeof minBashVersion === 'string' && !isValidMinBashVersionShape(minBashVersion)) {
+        throw new TypeError(`@eslint-sh/eslint-plugin: languageOptions.minBashVersion must match the shape MAJOR[.MINOR] (e.g. "3.2", "5"); received ${JSON.stringify(minBashVersion)}.`);
     }
     if (directivePrefix !== undefined && !isValidDirectivePrefix(directivePrefix)) {
         throw new TypeError(`@eslint-sh/eslint-plugin: languageOptions.directivePrefix must be one or more lowercase, hyphen-separated words (e.g. "eslint", "shellcheck-sh"); received ${JSON.stringify(directivePrefix)}.`);
@@ -91,18 +98,18 @@ export function validateShellLanguageOptions(languageOptions) {
 export function normalizeShellLanguageOptions(languageOptions) {
     const dialect = languageOptions.dialect ?? 'bash';
     const directivePrefix = languageOptions.directivePrefix ?? DEFAULT_DIRECTIVE_PREFIX;
-    const shellVersion = languageOptions.shellVersion;
+    const minBashVersion = languageOptions.minBashVersion;
     return {
         dialect,
         directivePrefix,
         // `exactOptionalPropertyTypes` forbids assigning `undefined` to an
         // optional property directly — omit the key entirely rather than set it
-        // to `undefined` when the caller didn't supply a shellVersion.
-        ...(shellVersion === undefined ? {} : { shellVersion }),
+        // to `undefined` when the caller didn't supply a minBashVersion.
+        ...(minBashVersion === undefined ? {} : { minBashVersion }),
         toJSON() {
-            return shellVersion === undefined
+            return minBashVersion === undefined
                 ? { dialect, directivePrefix }
-                : { dialect, directivePrefix, shellVersion };
+                : { dialect, directivePrefix, minBashVersion };
         },
     };
 }

package/dist/language/shell-language.d.ts

@@ -26,11 +26,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;
@@ -64,9 +65,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, context: {
         languageOptions: ShellLanguageOptions;
@@ -81,8 +82,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, parseResult: OkParseResult<ShellFile>, context: {
         languageOptions: ShellLanguageOptions;

package/dist/language/shell-language.js

@@ -1,6 +1,5 @@
 /** Adapts upstream parsing and diagnostics to ESLint's synchronous Language contract. */
-import { LangBash, LangBats, LangError, LangMirBSDKorn, LangPOSIX, LangZsh, ParseError, parseWithPositionsSync, } from 'sh-ast';
-import { firstDroppedTextIndex } from './end-of-input-marker.js';
+import { LangBash, LangBats, LangError, LangMirBSDKorn, LangPOSIX, LangZsh, ParseError, ShParseMaxDepthError, parseWithPositionsSync, } from 'sh-ast';
 import { nonShellFileError } from './non-shell-file-guard.js';
 import { matchesSelectorClass as matchesShellSelectorClass } from './selector-classes.js';
 import { ShellSourceCode } from './shell-source-code.js';
@@ -50,28 +49,15 @@ function toFileError(error, source) {
             column: location.column,
         };
     }
+    // A native budget refusal carries no partial tree or source position. It is
+    // an input resource limit, not a broken parser runtime; later files may parse.
+    if (error instanceof ShParseMaxDepthError) {
+        return { message: error.message, line: 1, column: 1 };
+    }
     // Bridge/input failures carry no asserted syntax position. The fallback is an ESLint presentation policy.
     const detail = error instanceof Error ? error.message : String(error);
     return { message: `${PARSER_RUNTIME_FAILURE_PREFIX}${detail}`, line: 1, column: 1 };
 }
-/**
- * The fatal parse error for a source in which the parser drops text at a U+0080, at that
- * character, or `undefined` when nothing is dropped. Checked before parsing so a silently
- * truncated tree never reaches the rules. A U+0080 the parser reads as an ordinary character
- * (inside a quoted-delimiter heredoc body, after a backslash) is not an error; one the parser
- * rejects (inside quotes or an expansion) is reported by the parser itself.
- */
-function endOfInputMarkerError(source, options) {
-    const index = firstDroppedTextIndex(source, options);
-    if (index === undefined)
-        return undefined;
-    const location = new SourceCoordinates(source).atIndex(index);
-    return {
-        message: 'the character U+0080 is not supported: the parser reads it as end of input',
-        line: location.line,
-        column: location.column,
-    };
-}
 /**
  * `ShellLanguage` — the `@eslint/core` `Language` implementation for shell
  * scripts. Registered by the plugin as `languages.sh`, so consumers select
@@ -96,11 +82,12 @@ export class ShellLanguage {
     defaultLanguageOptions = { dialect: 'bash' };
     /**
      * 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) {
@@ -140,9 +127,9 @@ export class ShellLanguage {
      * 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, context) {
         const misappliedError = nonShellFileError(file.path);
@@ -156,10 +143,6 @@ export class ShellLanguage {
             Filename: file.path,
             KeepComments: true,
         };
-        const unsupported = endOfInputMarkerError(text, parseOptions);
-        if (unsupported !== undefined) {
-            return { ok: false, errors: [unsupported] };
-        }
         try {
             const parsed = parseWithPositionsSync(text, parseOptions);
             const ast = adaptSyntaxFile(parsed.File, text, parsed.Positions);
@@ -179,8 +162,8 @@ export class ShellLanguage {
      * 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, parseResult, context) {
         return new ShellSourceCode({
@@ -188,9 +171,9 @@ export class ShellLanguage {
             ast: parseResult.ast,
             directivePrefix: context.languageOptions.directivePrefix ?? 'eslint',
             dialect: context.languageOptions.dialect ?? 'bash',
-            ...(context.languageOptions.shellVersion === undefined
+            ...(context.languageOptions.minBashVersion === undefined
                 ? {}
-                : { shellVersion: context.languageOptions.shellVersion }),
+                : { minBashVersion: context.languageOptions.minBashVersion }),
         });
     }
 }

package/dist/language/shell-source-code.d.ts

@@ -37,7 +37,7 @@ import type { ShellCommandSite } from './command-resolution.js';
  * 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`,
@@ -64,7 +64,7 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
         ast: ShFile;
         directivePrefix?: string;
         dialect?: ShellDialect;
-        shellVersion?: string;
+        minBashVersion?: string;
     });
     /**
      * The shell dialect this file was parsed as: the normalized
@@ -73,11 +73,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
@@ -166,13 +167,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
@@ -333,8 +340,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`.
      */

package/dist/language/shell-source-code.js

@@ -5,6 +5,38 @@ import { SYNTAX_INTERFACES, printSync } from 'sh-ast';
 import { resolveArgv0 } from 'sh-ast/analyze';
 import { buildCommandSiteIndex, rawCallExprFor, viewCommandSites } from './command-resolution.js';
 import { resolveWord } from './word-resolution.js';
+/**
+ * Refuses edited syntax whose string or byte values the upstream printer treats as layout.
+ * Checking the edited tree also catches controls introduced by a rule, without refusing ordinary
+ * text edits elsewhere in a file. The input filename is metadata, never printer output.
+ * Iteration tolerates shared/cyclic records; sh-ast still validates
+ * the printable syntax itself.
+ */
+// format.ts's refusePrinterControlCharacters independently guards the formatter's source text.
+function refusePrinterControlCharacters(root) {
+    const pending = [root.Type === 'File' ? { ...root, Name: '' } : root];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const unsafe = (typeof current === 'string' && /[\v\f]/u.test(current)) ||
+            (current instanceof Uint8Array && current.some((byte) => byte === 0x0b || byte === 0x0c));
+        if (unsafe) {
+            throw new TypeError('cannot print a text fix containing literal vertical tabs and form feeds: ' +
+                'the printer changes their value');
+        }
+        // A checked byte-valued string is a leaf; its individual numbers are not syntax children.
+        if (current instanceof Uint8Array) {
+            continue;
+        }
+        if (current !== null && typeof current === 'object' && !seen.has(current)) {
+            seen.add(current);
+            const children = Object.values(current);
+            for (const child of children) {
+                pending.push(child);
+            }
+        }
+    }
+}
 /**
  * Shared instance — `ConfigCommentParser` is stateless (see
  * `@eslint/plugin-kit`'s implementation), so every `ShellSourceCode`
@@ -296,7 +328,7 @@ function withUnusedDirectiveFixRange(comment, text) {
  * 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`,
@@ -356,8 +388,8 @@ export class ShellSourceCode extends TextSourceCodeBase {
     #inlineConfigNodes;
     /** The normalized `languageOptions.dialect` this file was parsed with. */
     #dialect;
-    /** The configured `languageOptions.shellVersion`, if the config supplied one. */
-    #shellVersion;
+    /** The configured `languageOptions.minBashVersion`, if the config supplied one. */
+    #minBashVersion;
     /** This file's coordinate index; see `#textCoordinates`. */
     #ownCoordinates;
     /**
@@ -380,7 +412,7 @@ export class ShellSourceCode extends TextSourceCodeBase {
         // supplies the already-normalized, defaulted values.
         this.#directivePrefix = options.directivePrefix ?? 'eslint';
         this.#dialect = options.dialect ?? 'bash';
-        this.#shellVersion = options.shellVersion;
+        this.#minBashVersion = options.minBashVersion;
         this.#directiveLabels = buildDirectiveLabels(this.#directivePrefix);
         this.#inlineConfigPattern = buildInlineConfigPattern(this.#directivePrefix);
     }
@@ -393,12 +425,13 @@ export class ShellSourceCode extends TextSourceCodeBase {
         return this.#dialect;
     }
     /**
-     * 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() {
-        return this.#shellVersion;
+    get minBashVersion() {
+        return this.#minBashVersion;
     }
     /**
      * The one-based location of a UTF-16 `index` in this file's text, where
@@ -521,13 +554,19 @@ export 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
@@ -702,8 +741,9 @@ export 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`.
      */
@@ -711,6 +751,7 @@ export class ShellSourceCode extends TextSourceCodeBase {
         const original = this.#originalSyntaxFor(node);
         const rootType = printableRootType(edited);
         const root = edited.Type === 'Stmt' ? { ...edited, Comments: null } : edited;
+        refusePrinterControlCharacters(root);
         const printed = printSync(root, options);
         if (typeof printed !== 'string') {
             throw new TypeError('printSync produced output that is not valid UTF-8; a text fix cannot hold it without ' +

package/dist/rules/bash-variable-semantics.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The common Bash 3.2+ intrinsic numeric profile used by shell rules. Value
+ * shape and assignment behavior are separate properties: a variable that
+ * always yields an integer need not evaluate assigned text arithmetically.
+ * Writable intrinsic setters still differ from ordinary string bindings;
+ * their handling can vary between Bash versions.
+ *
+ * This is a name profile, not dataflow over unset, local, or declaration
+ * attributes. Callers decide when intrinsic meaning applies. POSIX and other
+ * shell dialects do not inherit this Bash profile, and newer Bash-only names
+ * are excluded from the common minimum-version guarantee.
+ */
+/** A name whose intrinsic value is numeric throughout the common Bash profile. @internal */
+export declare function isBashIntegerVariable(name: string): boolean;
+/**
+ * A name with a non-ordinary writable integer setter. OPTIND can evaluate
+ * assigned text as arithmetic; numeric output alone makes no such promise
+ * about the other setters. Proofs that do not model these setters must fence
+ * their writes rather than treat them as ordinary string assignments.
+ * @internal
+ */
+export declare function hasSpecialBashIntegerSetter(name: string): boolean;

package/dist/rules/bash-variable-semantics.js

@@ -0,0 +1,41 @@
+/**
+ * The common Bash 3.2+ intrinsic numeric profile used by shell rules. Value
+ * shape and assignment behavior are separate properties: a variable that
+ * always yields an integer need not evaluate assigned text arithmetically.
+ * Writable intrinsic setters still differ from ordinary string bindings;
+ * their handling can vary between Bash versions.
+ *
+ * This is a name profile, not dataflow over unset, local, or declaration
+ * attributes. Callers decide when intrinsic meaning applies. POSIX and other
+ * shell dialects do not inherit this Bash profile, and newer Bash-only names
+ * are excluded from the common minimum-version guarantee.
+ */
+/**
+ * Every listed intrinsic yields a decimal integer. Writable setters control
+ * the random generator, elapsed clock, or option parser; the other bindings
+ * ignore assignments or reject them. Environment-controlled names such as
+ * UID/EUID/COLUMNS, and later additions such as BASHPID/SRANDOM, are outside
+ * this common profile.
+ */
+const INTEGER_BINDINGS = new Map([
+    ['RANDOM', 'writable'],
+    ['SECONDS', 'writable'],
+    ['OPTIND', 'writable'],
+    ['LINENO', 'ignored'],
+    ['BASH_SUBSHELL', 'ignored'],
+    ['PPID', 'readonly'],
+]);
+/** A name whose intrinsic value is numeric throughout the common Bash profile. @internal */
+export function isBashIntegerVariable(name) {
+    return INTEGER_BINDINGS.has(name);
+}
+/**
+ * A name with a non-ordinary writable integer setter. OPTIND can evaluate
+ * assigned text as arithmetic; numeric output alone makes no such promise
+ * about the other setters. Proofs that do not model these setters must fence
+ * their writes rather than treat them as ordinary string assignments.
+ * @internal
+ */
+export function hasSpecialBashIntegerSetter(name) {
+    return INTEGER_BINDINGS.get(name) === 'writable';
+}

package/dist/rules/compat/create-compat-rule.js

@@ -4,7 +4,7 @@
  * A compat rule reports one gated feature (a row of the gate table in
  * `./version-gates.ts`) wherever a file uses it while its `languageOptions`
  * say the feature is unavailable. The factory owns the gate decision, so no
- * compat rule reads `shellVersion` or `dialect` itself:
+ * compat rule reads `minBashVersion` or `dialect` itself:
  *
  * - when {@link isFeatureAvailable} says the feature is available, the rule
  *   returns no listeners at all, so it costs nothing and cannot report;

package/dist/rules/compat/declaration-options.d.ts

@@ -1,4 +1,4 @@
-import type { ShellSourceCode } from '../../language/shell-source-code.js';
+import type { TransparentWrappersBindingContext } from '../resolve-transparent-wrappers.js';
 import type { ShellNode } from '../../language/syntax-view.js';
 import type { ShellRuleVisitor } from '../define-shell-rule.js';
 /**
@@ -16,4 +16,4 @@ export declare const DECLARATION_AND_LOCAL_COMMANDS: ReadonlySet<string>;
  *
  * @internal
  */
-export declare function declarationFlagVisitor(sourceCode: ShellSourceCode, flag: string, report: (option: ShellNode, command: string, options: readonly string[]) => void, commands?: ReadonlySet<string>): ShellRuleVisitor;
+export declare function declarationFlagVisitor(context: TransparentWrappersBindingContext, flag: string, report: (option: ShellNode, command: string, options: readonly string[]) => void, commands?: ReadonlySet<string>): ShellRuleVisitor;