@eslint-sh/eslint-plugin 0.6.0 → 0.7.0

package/README.md

@@ -24,7 +24,7 @@ recipes. Four shared configs ship, each supplying `plugins: { sh }` and `languag
 `sh/max-script-complexity`, with every rule at `error`. Its convention and wrapper rules report nothing until you bind a declaration
 convention or a wrapper. The [rules index](./docs/rules/README.md) lists all forty built-in rules,
 their presets, and
-autofix availability. The version-gated rules `sh/compat/no-append-all-redirect`, `sh/compat/no-associative-arrays`, `sh/compat/no-case-attributes`, `sh/compat/no-case-fallthrough`, `sh/compat/no-case-modification`, `sh/compat/no-coproc`, `sh/compat/no-declare-g`, `sh/compat/no-epoch-variables`, `sh/compat/no-fd-variable`, `sh/compat/no-globstar`, `sh/compat/no-lastpipe-semantics`, `sh/compat/no-mapfile`, `sh/compat/no-nameref`, `sh/compat/no-negative-array-index`, `sh/compat/no-nounset-empty-array`, `sh/compat/no-parameter-transformation`, `sh/compat/no-pipe-all`, `sh/compat/no-printf-time-format`, `sh/compat/no-test-v`, `sh/compat/no-unicode-escape` and `sh/compat/no-wait-n`, report features your target shell version
+autofix availability. The version-gated rules `sh/compat/no-append-all-redirect`, `sh/compat/no-associative-arrays`, `sh/compat/no-brace-sequence-padding-step`, `sh/compat/no-case-attributes`, `sh/compat/no-case-fallthrough`, `sh/compat/no-case-modification`, `sh/compat/no-coproc`, `sh/compat/no-declare-g`, `sh/compat/no-epoch-variables`, `sh/compat/no-fd-variable`, `sh/compat/no-globstar`, `sh/compat/no-lastpipe-semantics`, `sh/compat/no-mapfile`, `sh/compat/no-nameref`, `sh/compat/no-negative-array-index`, `sh/compat/no-nounset-empty-array`, `sh/compat/no-parameter-transformation`, `sh/compat/no-pipe-all`, `sh/compat/no-printf-time-format`, `sh/compat/no-test-v`, `sh/compat/no-unicode-escape` and `sh/compat/no-wait-n`, report features your target shell version
 lacks; `configs['bash-3.2']` (`shellVersion: '3.2'`) and `configs['posix-portable']` (`dialect: 'posix'`, with
 `sh/require-strict-mode` as `set -eu`) enable them for those targets. `configs['posix-portable']` also reports `[[`, `let` and `source`, which fail on dash (`sh/compat/no-double-bracket`, `sh/compat/no-let`, `sh/compat/no-source`), but not `local`, `echo -e` or the other constructs it leaves to shellcheck, so a clean run does not prove a script runs under every POSIX `sh`; see [version compatibility](./docs/compat.md). Run shellcheck alongside eslint-sh: shellcheck catches shell correctness
 problems; eslint-sh enforces project policy. [Running eslint-sh beside shellcheck](./docs/shellcheck.md)
@@ -36,6 +36,11 @@ Disable directives / inline config are implemented and live: all four
 interplay work through ESLint's native machinery. The rule id below is illustrative; the
 directives suppress built-in rules and your own custom rules alike: for a rule you've configured as `sh/your-rule`,
 `# eslint-disable-next-line sh/your-rule -- justification` suppresses it on the following line.
+A script can therefore switch any rule off for itself. When the scripts you lint come from someone
+who doesn't own the policy, see [linting code you don't control](./docs/untrusted-code.md): a
+config that ignores those comments, and how to run ESLint from outside the checkout under review,
+so that it can't supply the config, ESLint, the plugin, or anything else ESLint looks for in the
+directory it runs in.
 
 ## CommonJS config
 

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

@@ -13,6 +13,7 @@
 const bash32Rules = {
     'sh/compat/no-append-all-redirect': 'error',
     'sh/compat/no-associative-arrays': 'error',
+    'sh/compat/no-brace-sequence-padding-step': 'error',
     'sh/compat/no-case-attributes': 'error',
     'sh/compat/no-case-fallthrough': 'error',
     'sh/compat/no-case-modification': 'error',

package/dist/configs/posix-portable.js

@@ -12,6 +12,7 @@ const posixPortableRules = {
     'sh/shebang-matches-dialect': 'error',
     'sh/compat/no-append-all-redirect': 'error',
     'sh/compat/no-associative-arrays': 'error',
+    'sh/compat/no-brace-sequence-padding-step': 'error',
     'sh/compat/no-case-attributes': 'error',
     'sh/compat/no-case-fallthrough': 'error',
     'sh/compat/no-case-modification': 'error',

package/dist/rules/compat/no-brace-sequence-padding-step.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Message ids this rule reports with: `padded` for a zero-padded sequence on
+ * a Bash that expands it without the padding, `stepped` for a stepped one on
+ * a Bash that leaves it literal, and `posixPadded` / `posixStepped` for the
+ * same two under a POSIX target, where the result depends on the shell.
+ *
+ * @internal
+ */
+export type NoBraceSequencePaddingStepMessageId = 'padded' | 'stepped' | 'posixPadded' | 'posixStepped';
+/**
+ * The `sh/compat/no-brace-sequence-padding-step` rule module.
+ *
+ * @internal
+ */
+export declare const noBraceSequencePaddingStep: import("../define-shell-rule.js").ShellRule<[], NoBraceSequencePaddingStepMessageId>;

package/dist/rules/compat/no-brace-sequence-padding-step.js

@@ -0,0 +1,287 @@
+/**
+ * `sh/compat/no-brace-sequence-padding-step`: reports a brace sequence that
+ * is zero-padded (`{01..10}`) or stepped (`{1..10..2}`, `{a..e..2}`) in
+ * files whose target shell lacks those forms, that is, Bash older than 4.0
+ * (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Neither form is an error on Bash 3.2, which is what makes them easy to
+ * miss. Bash 3.2 expands `{01..03}` to `1 2 3`, dropping the padding, and
+ * leaves `{1..9..4}` as that literal word, so the script carries on with
+ * different words. POSIX does not specify brace expansion, so under a POSIX
+ * target what a shell does with the word depends on the shell (observed: dash
+ * leaves it literal, macOS's `/bin/sh` drops the padding as Bash 3.2 does,
+ * and `bash --posix` 5.3 pads); a plain `{1..3}` is as shell-dependent there,
+ * and this rule does not report it: only the Bash 4.0 additions are in its
+ * scope. The
+ * message suggests the portable alternative: count in a `while` loop and
+ * format with `printf`.
+ *
+ * What is read: the parser keeps a brace sequence as literal text inside a
+ * word, so the rule scans the literal parts of words that the shell
+ * brace-expands. A sequence is a `{` and `}` with nothing but the sequence
+ * between them (so `{01..03,x}`, a comma list, is not one), where:
+ *
+ * - the endpoints are both integers (an optional sign and digits) or both
+ *   single ASCII letters, with an optional third `..` field that is an
+ *   integer step: that makes it stepped, for either kind of endpoint;
+ * - integer endpoints are padded when either has more than one digit and
+ *   starts with `0` after an optional `-` (`01`, `00`, `-01`, `1..03`; `0`,
+ *   `-0` and `+01` are not).
+ *
+ * Anything that is not a sequence in Bash 4.0 and newer is left alone:
+ * `{a..c}` and `{1..3}` (no padding, no step, the same on every Bash),
+ * mixed endpoints (`{a..5..2}`), a variable endpoint (`{01..$n}`, which the
+ * shell never expands), an unterminated or malformed one (`{01..}`), and a
+ * `{` or `}` that is quoted or backslash-escaped, since quoted text is a
+ * separate part of the word and an escape is skipped when scanning.
+ *
+ * Numbers are bounded as Bash 5.3 bounds them, because past the bounds the
+ * word stays literal on every Bash and nothing differs: endpoints must fit a
+ * signed 64-bit integer, so must the distance between them, and so must the
+ * step's magnitude (a step of -9223372036854775808 or a value past 64 bits
+ * leaves the word literal;
+ * leading zeros do not count towards the value, so `{1..00000000000000000003}`
+ * is a sequence). Bash 3.2 reads the same words as literal or wraps them
+ * (its integers are narrower), and the older 4.x releases' bound was not
+ * measured, so a sequence inside the 64-bit range is reported and one outside
+ * it is not.
+ *
+ * Only words that are brace-expanded are read: command words and arguments,
+ * `for`/`select` lists, the elements of an array literal without an index,
+ * and the operands of `declare`, `local`, `export` and `readonly`. Not read,
+ * because the shell does no brace expansion there: a plain assignment
+ * (`a={01..03}`), a `case` subject or pattern, the operands of `[[ ]]`,
+ * here-strings and here-documents, and parameter-expansion words.
+ *
+ * A descriptor duplication target is not reported where it behaves the same
+ * on every Bash; see `isSameOnEveryBash`.
+ *
+ * Text inside a quoted string that the shell later runs as code (`eval
+ * '...'`, `trap '...'`) is not seen: the parser holds it as a string.
+ *
+ * A redirection target (`: > out{01..01}`) is read only when the sequence
+ * can be shown to yield exactly one word, since several words make it an
+ * "ambiguous redirect" error on Bash 4 and newer (on 3.2 too for a padded
+ * one), and the script is then wrong on every Bash that has the feature,
+ * not a portability gap. The word must hold that one sequence and no other
+ * brace group, whose product with it could not be counted here. A single-word
+ * result differs by target: `out{01..01}` names `out1` on Bash 3.2 and
+ * `out01` on 5.3, and `out{1..3..5}` names a file called `out{1..3..5}` on
+ * 3.2 and `out1` on 5.3. A sequence is always static text here (a variable
+ * endpoint is no sequence), so its length is always known. The report is on
+ * the whole word, once per word.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+import { DashHdoc, DplIn, DplOut, Hdoc, WordHdoc } from 'sh-ast/analyze';
+/** The sequence between braces: two endpoints and an optional step. */
+const SEQUENCE = /^([+-]?\d+|[A-Za-z])\.\.([+-]?\d+|[A-Za-z])(?:\.\.([+-]?\d+))?$/u;
+/**
+ * An integer endpoint with leading zeros, which Bash 4.0 pads to. A `+` sign
+ * does not count: Bash 5.3 expands `{+01..3}` as `1 2 3`, as 3.2 does.
+ */
+const ZERO_PADDED = /^-?0\d+$/u;
+/** An integer endpoint. */
+const INTEGER = /^[+-]?\d+$/u;
+/** The signed 64-bit range Bash 5.3 accepts for an endpoint. */
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+/**
+ * `text` with every backslash escape (the backslash and the character it
+ * quotes) replaced by `\0`, which no sequence contains, so an escaped brace
+ * cannot open or close a sequence and an escape inside one disqualifies it.
+ */
+function maskEscapes(text) {
+    let masked = '';
+    for (let index = 0; index < text.length; index++) {
+        if (text[index] === '\\') {
+            masked += '\0\0';
+            index++;
+        }
+        else {
+            masked += text[index];
+        }
+    }
+    return masked;
+}
+/** The value of an endpoint: an integer's number, or a letter's code point. */
+function endpointValue(endpoint) {
+    return INTEGER.test(endpoint) ? BigInt(endpoint) : BigInt(endpoint.charCodeAt(0));
+}
+/**
+ * The number of words a valid sequence yields. A step of zero counts as 1,
+ * and a step's sign is ignored: the direction follows the endpoints.
+ */
+function resultCount(start, end, step) {
+    const size = step === undefined || step === 0n ? 1n : step < 0n ? -step : step;
+    return span(start, end) / size + 1n;
+}
+/** The distance between two endpoints. */
+function span(start, end) {
+    return end > start ? end - start : start - end;
+}
+/**
+ * The first brace sequence in the literal text `text` that needs Bash 4.0
+ * and that Bash 5.3 expands, or `undefined`. Innermost brace pairs are the
+ * only candidates, which is where Bash finds a sequence, including one
+ * nested in a comma list (`{x,{01..03}}`).
+ */
+function findSequence(text) {
+    const masked = maskEscapes(text);
+    for (const pair of masked.matchAll(/\{([^{}]*)\}/gu)) {
+        const match = SEQUENCE.exec(pair[1]);
+        if (match === null)
+            continue;
+        const [, start, end] = match;
+        const integers = INTEGER.test(start) && INTEGER.test(end);
+        const letters = !INTEGER.test(start) && !INTEGER.test(end);
+        if (!integers && !letters)
+            continue;
+        // A third `..` field is the step (SEQUENCE has already checked its form).
+        const stepText = match[0].split('..').length === 3 ? match[0].split('..')[2] : undefined;
+        const step = stepText === undefined ? undefined : BigInt(stepText);
+        const first = endpointValue(start);
+        const last = endpointValue(end);
+        const inRange = first >= INT64_MIN &&
+            first <= INT64_MAX &&
+            last >= INT64_MIN &&
+            last <= INT64_MAX &&
+            (step === undefined || (step > INT64_MIN && step <= INT64_MAX));
+        // The distance between the endpoints must fit too:
+        // `{-1..9223372036854775807..9223372036854775807}` stays literal on Bash
+        // 5.3 although every number in it is in range.
+        if (!inRange || span(first, last) > INT64_MAX)
+            continue;
+        const results = resultCount(first, last, step);
+        const written = text.slice(pair.index, pair.index + pair[0].length);
+        if (step !== undefined)
+            return { text: written, kind: 'stepped', results, first };
+        if (integers && (ZERO_PADDED.test(start) || ZERO_PADDED.test(end))) {
+            return { text: written, kind: 'padded', results, first };
+        }
+    }
+    return undefined;
+}
+/** How many unescaped `{` the literal parts of `word` hold. */
+function braceGroupCount(word) {
+    let count = 0;
+    for (const part of word.parts) {
+        if (part.type === 'Lit')
+            count += maskEscapes(part.value).split('{').length - 1;
+    }
+    return count;
+}
+/** Redirection operators whose word the shell does not brace-expand. */
+const NO_BRACE_REDIRECTS = new Set([Hdoc, DashHdoc, WordHdoc]);
+/** The `<&` and `>&` operators, whose lone-number word names a descriptor. */
+const DESCRIPTOR_DUPLICATES = new Set([DplIn, DplOut]);
+/**
+ * Whether a one-word sequence that is the whole target of `<&` or `>&`
+ * behaves the same on Bash 3.2 and newer (checked on 3.2.57 and 5.3.9):
+ *
+ * - a descriptor position (`<&`, or `>&` with a descriptor before it, as in
+ *   `2>&`) with a negative number is an "ambiguous redirect" error on both,
+ *   whatever the form, so there is nothing to port;
+ * - a padded non-negative number names the same descriptor on both (`>&{01..01}`
+ *   is descriptor 1), but a stepped one differs (`>&{1..3..5}` is literal on
+ *   3.2 and descriptor 1 on 5.3);
+ * - a bare `>&` with a word that is not a descriptor writes a file, so a
+ *   negative number is a file name that differs (`-1` on 3.2, `-01` on 5.3).
+ */
+function isSameOnEveryBash(redirect, sequence) {
+    if (sequence.results !== 1n)
+        return false;
+    const descriptorPosition = redirect.op === DplIn || redirect.n !== undefined;
+    if (sequence.first < 0n)
+        return descriptorPosition;
+    return sequence.kind === 'padded';
+}
+/**
+ * Whether the shell brace-expands `word`, a `Word` node whose parent is
+ * `parent`. This is the complete list of such positions; anything not named
+ * here is exempt.
+ */
+function isBraceExpanded(word, parent, grandparent) {
+    switch (parent?.type) {
+        case 'CallExpr':
+        case 'WordIter':
+            return true;
+        // An array literal element; a keyed element (`[k]=v`) is assigned like a
+        // variable and is not expanded.
+        case 'ArrayElem':
+            return parent.index === undefined && parent.value === word;
+        // A declaration's operands are arguments to the builtin, so both a bare
+        // one and the value of `NAME=value` are expanded; a plain assignment is
+        // not.
+        case 'Assign':
+            return grandparent?.type === 'DeclClause';
+        // The target of an ordinary redirection; a here-document's delimiter and
+        // a here-string's word are not brace-expanded.
+        case 'Redirect':
+            return parent.word === word && !NO_BRACE_REDIRECTS.has(parent.op);
+        default:
+            return false;
+    }
+}
+/**
+ * The `sh/compat/no-brace-sequence-padding-step` rule module.
+ *
+ * @internal
+ */
+export const noBraceSequencePaddingStep = createCompatRule({
+    name: 'compat/no-brace-sequence-padding-step',
+    feature: 'braceSequencePaddingStep',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow zero-padded (`{01..10}`) and stepped (`{1..10..2}`) brace sequences when the target shell lacks them',
+        },
+        messages: {
+            padded: '`{{sequence}}` needs {{required}}, but this file targets {{target}}, which expands it without the zero padding. Count in a loop and format with `printf` instead, for example `i=1; while [ "$i" -le 3 ]; do printf \'%02d\\n\' "$i"; i=$((i + 1)); done`.',
+            stepped: '`{{sequence}}` needs {{required}}, but this file targets {{target}}, which leaves it as that literal word. Count in a loop instead, for example `i=1; while [ "$i" -le 9 ]; do echo "$i"; i=$((i + 4)); done`.',
+            posixPadded: '`{{sequence}}` needs {{required}}, but this file targets {{target}}, which does not specify brace expansion, so what a shell does with this word depends on the shell. Count in a loop and format with `printf` instead, for example `i=1; while [ "$i" -le 3 ]; do printf \'%02d\\n\' "$i"; i=$((i + 1)); done`.',
+            posixStepped: '`{{sequence}}` needs {{required}}, but this file targets {{target}}, which does not specify brace expansion, so what a shell does with this word depends on the shell. Count in a loop instead, for example `i=1; while [ "$i" -le 9 ]; do echo "$i"; i=$((i + 4)); done`.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        const posix = sourceCode.dialect === 'posix';
+        return {
+            Word(node) {
+                const parent = sourceCode.getParent(node);
+                const grandparent = parent === undefined ? undefined : sourceCode.getParent(parent);
+                if (!isBraceExpanded(node, parent, grandparent))
+                    return;
+                const redirectTarget = parent?.type === 'Redirect';
+                for (const part of node.parts) {
+                    if (part.type !== 'Lit')
+                        continue;
+                    const sequence = findSequence(part.value);
+                    if (sequence === undefined)
+                        continue;
+                    // A redirection target is an ambiguous-redirect error unless it is
+                    // exactly one word, which is only certain for a lone sequence.
+                    if (redirectTarget && (sequence.results !== 1n || braceGroupCount(node) !== 1))
+                        return;
+                    if (!posix &&
+                        parent?.type === 'Redirect' &&
+                        DESCRIPTOR_DUPLICATES.has(parent.op) &&
+                        node.parts.length === 1 &&
+                        part.value === sequence.text &&
+                        isSameOnEveryBash(parent, sequence)) {
+                        return;
+                    }
+                    context.report({
+                        node,
+                        messageId: posix
+                            ? sequence.kind === 'padded'
+                                ? 'posixPadded'
+                                : 'posixStepped'
+                            : sequence.kind,
+                        data: { ...gate, sequence: sequence.text },
+                    });
+                    return;
+                }
+            },
+        };
+    },
+});

package/dist/rules/compat/version-gates.d.ts

@@ -27,7 +27,7 @@ import type { ShellLanguageOptions } from '../../language/shell-language-options
  *
  * @internal
  */
-export type CompatFeature = 'appendAllRedirect' | 'associativeArrays' | 'caseAttributes' | 'caseFallthrough' | 'caseModification' | 'coproc' | 'declareGlobal' | 'doubleBracket' | 'epochVariables' | 'fdVariable' | 'globstar' | 'lastpipe' | 'letCommand' | 'mapfile' | 'nameref' | 'negativeArrayIndex' | 'nounsetEmptyArray' | 'parameterTransformation' | 'parameterTransformationCase' | 'parameterTransformationKeys' | 'parameterTransformationQuotedKeys' | 'pipeAll' | 'printfTimeFormat' | 'sourceCommand' | 'testVariableSet' | 'unicodeEscape' | 'unicodeEscapeLatin1' | 'waitNext';
+export type CompatFeature = 'appendAllRedirect' | 'associativeArrays' | 'braceSequencePaddingStep' | 'caseAttributes' | 'caseFallthrough' | 'caseModification' | 'coproc' | 'declareGlobal' | 'doubleBracket' | 'epochVariables' | 'fdVariable' | 'globstar' | 'lastpipe' | 'letCommand' | 'mapfile' | 'nameref' | 'negativeArrayIndex' | 'nounsetEmptyArray' | 'parameterTransformation' | 'parameterTransformationCase' | 'parameterTransformationKeys' | 'parameterTransformationQuotedKeys' | 'pipeAll' | 'printfTimeFormat' | 'sourceCommand' | 'testVariableSet' | 'unicodeEscape' | 'unicodeEscapeLatin1' | 'waitNext';
 /**
  * The two `languageOptions` fields gating reads. Both the raw and the
  * normalized options satisfy it; an unset `dialect` means `"bash"`, as it

package/dist/rules/compat/version-gates.js

@@ -11,6 +11,14 @@ const FEATURE_GATES = Object.freeze({
     appendAllRedirect: Object.freeze({ bash: '4.0', posix: false }),
     /** `declare -A` / `typeset -A`: Bash 4.0 NEWS, "associative arrays". */
     associativeArrays: Object.freeze({ bash: '4.0', posix: false }),
+    /**
+     * Zero-padded (`{01..10}`) and stepped (`{1..10..2}`, `{a..e..2}`) brace
+     * sequences: Bash 4.0 NEWS (brace expansion gained zero-padding and an
+     * increment). Bash 3.2 expands the padded form without the padding and
+     * leaves the stepped form as a literal word; POSIX sh has no brace
+     * expansion.
+     */
+    braceSequencePaddingStep: Object.freeze({ bash: '4.0', posix: false }),
     /**
      * The case-modifying expansions `${v^}`, `${v^^}`, `${v,}`, `${v,,}`: Bash
      * 4.0 NEWS, "new case-modifying word expansions".

package/dist/rules/index.js

@@ -1,5 +1,6 @@
 import { noAppendAllRedirect } from './compat/no-append-all-redirect.js';
 import { noAssociativeArrays } from './compat/no-associative-arrays.js';
+import { noBraceSequencePaddingStep } from './compat/no-brace-sequence-padding-step.js';
 import { noCaseAttributes } from './compat/no-case-attributes.js';
 import { noCaseFallthrough } from './compat/no-case-fallthrough.js';
 import { noCaseModification } from './compat/no-case-modification.js';
@@ -47,6 +48,7 @@ import { shebangMatchesDialect } from './shebang-matches-dialect.js';
 export const rules = {
     'compat/no-append-all-redirect': noAppendAllRedirect,
     'compat/no-associative-arrays': noAssociativeArrays,
+    'compat/no-brace-sequence-padding-step': noBraceSequencePaddingStep,
     'compat/no-case-attributes': noCaseAttributes,
     'compat/no-case-fallthrough': noCaseFallthrough,
     'compat/no-case-modification': noCaseModification,

package/dist/rules/require-tty-guard.js

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

package/docs/compat.md

@@ -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,9 +64,9 @@ 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
+`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
-enables all twenty-four; see
+enables all twenty-five; see
 [Presets](#presets).
 
 ## Setting the target
@@ -112,13 +113,13 @@ Two presets name a deployment target and enable every rule that enforces it, so
 the rules yourself:
 
 - **`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
+  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['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 +206,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
@@ -236,6 +233,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 |
@@ -331,6 +330,14 @@ 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.

package/docs/rules/README.md

@@ -12,6 +12,7 @@ See the [canonical quickstart](https://github.com/mike-north/eslint-sh/blob/main
 | ---- | ------- | ------- | ----------- | ------- |
 | [`sh/compat/no-append-all-redirect`](./compat/no-append-all-redirect.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow the `&>>` redirection when the target shell lacks it, suggesting `>> file 2>&1`. |
 | [`sh/compat/no-associative-arrays`](./compat/no-associative-arrays.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `declare -A` / `typeset -A` when the target shell lacks associative arrays. |
+| [`sh/compat/no-brace-sequence-padding-step`](./compat/no-brace-sequence-padding-step.md) | `bash-3.2`, `posix-portable` | No | No | Disallow zero-padded (`{01..10}`) and stepped (`{1..10..2}`) brace sequences when the target shell lacks them, pointing at a counting loop. |
 | [`sh/compat/no-case-attributes`](./compat/no-case-attributes.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `declare -l` / `declare -u` (and `typeset`, `local`) when the target shell lacks them, pointing at `tr`. |
 | [`sh/compat/no-case-fallthrough`](./compat/no-case-fallthrough.md) | `bash-3.2`, `posix-portable` | No | No | Disallow the `case` terminators `;&` and `;;&` when the target shell lacks them. |
 | [`sh/compat/no-case-modification`](./compat/no-case-modification.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `${v^^}`, `${v,,}` and variants when the target shell lacks them, pointing at `tr`. |
@@ -58,7 +59,7 @@ offer editor suggestions, which you apply one at a time from your editor; the Au
 describes edits available through `eslint --fix`. `quote-expansions` suggests quoting instead of
 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-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
+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.

package/docs/rules/compat/no-brace-sequence-padding-step.md

@@ -0,0 +1,90 @@
+# `sh/compat/no-brace-sequence-padding-step`
+
+Disallow zero-padded (`{01..10}`) and stepped (`{1..10..2}`, `{a..e..2}`) brace sequences in scripts
+whose target shell lacks them: Bash older than 4.0, including the Bash 3.2 that macOS ships as
+`/bin/bash`, and POSIX sh.
+
+| Configs                      | Fixable     | Languages |
+| ---------------------------- | ----------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+Both forms arrived in Bash 4.0, and neither fails on Bash 3.2, which is what makes them easy to miss. On Bash 3.2.57, `echo {01..03} {1..9..4}` prints `1 2 3 {1..9..4}` and exits 0: the padding is dropped and the stepped sequence stays as a literal word. The script carries on with different words. POSIX does not specify brace expansion, so what a POSIX target does with these words depends on the shell: dash prints `{01..03} {1..9..4}`, macOS's `/bin/sh` prints `1 2 3` for `{01..03}`, and Bash 5.3 under `--posix` prints `01 02 03`. A plain `{1..3}` is as shell-dependent, but this rule reports only the two forms Bash 4.0 added.
+
+The parser keeps a brace sequence as literal text inside a word, so the rule reads the literal text of the words the shell brace-expands. It reports a `{…}` that holds nothing but a sequence:
+
+- two integer endpoints (an optional sign and digits) or two single ASCII letters, with an optional third `..` field that is an integer step. A step makes the sequence stepped, for numbers and letters alike, and the step may be `0` or negative.
+- integer endpoints are padded when either has more than one digit and starts with `0` after an optional `-`: `{01..10}`, `{1..03}`, `{-01..1}`, `{00..10}`. A lone `0` (`{0..3}`) and `{-0..2}` are not padded, and neither is a `+01` endpoint, which Bash 5.3 expands without padding, as Bash 3.2 does.
+
+Everything else is left alone, because it is the same on every Bash or is not a sequence at all: `{1..3}`, `{a..c}`, a descending `{3..1}`, a comma list (`{01,02}`, `{01..03,x}`), mixed endpoints (`{a..5..2}`), multi-character endpoints, a variable endpoint (`{01..$n}`, which the shell never expands), and a malformed one (`{01..}`, `{1..9..x}`, spaces inside). Quoting and escaping are honoured: `"{01..10}"`, `'{01..10}'`, `$'{01..10}'`, `\{01..10}` and `{01..10\}` are plain text.
+
+Only code the parser sees is read: a sequence inside a quoted string that is run later (`eval '...'`, `trap '...'`) is not seen. A sequence is read where the shell brace-expands: command words and arguments, `for` and `select` lists, the elements of an array literal without an index (`a=({01..03})`), and the operands of `declare`, `local`, `export` and `readonly` (also the value in `declare d={01..03}`). It is not read where the shell does no brace expansion: a plain assignment (`a={01..03}`), a `case` subject or pattern, the operands of `[[ ]]`, here-strings and here-documents, parameter-expansion words (`${v:-{01..03}}`), and a keyed array element (`a=([5]={01..03})`). A redirection target (`: > out{01..01}`) is read only when the sequence provably yields one word. With several words the target is an "ambiguous redirect" error on Bash 5.3 (and for a padded sequence on 3.2 too), so the script is broken on every Bash that has the feature and there is nothing to port. With one word the shells disagree silently: `out{01..01}` writes `out1` on Bash 3.2.57 and `out01` on 5.3.9, and `out{1..3..5}` writes a file literally named `out{1..3..5}` on 3.2.57 and `out1` on 5.3.9. A sequence is always static text, so its length is always known; a target that also holds another brace group (`out{01..01}{a,b}`) is not read, because the product cannot be counted here, so a redirect target with more than one brace group is skipped. The same selection applies under `dialect: "posix"`, although the system `dash` creates a literal file such as `out{01..02}` for any of them without an error: a several-word target is still a sequence that no Bash accepts. A here-string or here-document word is never read. A descriptor duplication whose whole target is a one-word sequence is read only where the shells differ (checked on 3.2.57 and 5.3.9). A padded non-negative number names the same descriptor on both (`>&{01..01}`, `2>&{02..02}`, `<&{00..00}`, and `>&{-00..-00}`, which is 0), so it is not reported. A negative number in a descriptor position (`2>&{-01..-01}`, `<&{-01..-01}`, `3>&{-01..-01}`) is an "ambiguous redirect" error on both, so it is not reported either. A stepped sequence still differs (`>&{1..3..5}`, `3>&{1..3..5}` and `<&{0..0..2}` are an error or a literal word on 3.2.57 and descriptor 1 or 0 on 5.3.9), and a bare `>&` with a negative number writes a file named `-1` on 3.2.57 and `-01` on 5.3.9, as does `&>{-01..-01}`, so those are reported. The report is on the whole word, once per word, for the first sequence in it.
+
+Numbers are bounded the way Bash 5.3 bounds them, because a word outside the bounds stays literal on every Bash and nothing differs: each endpoint and the distance between them must fit a signed 64-bit integer, and so must the step's magnitude (a step of `-9223372036854775808` is not a step). Leading zeros do not count towards the value, so `{1..00000000000000000003}` is a sequence. `{1..3..999999999999999999999}`, `{1..99999999999999999999}` and `{-1..9223372036854775807..9223372036854775807}` are not reported. These bounds were measured on Bash 5.3.9 and 3.2.57 only; the 4.x releases' bounds were not measured.
+
+The portable alternative is to count in a loop and format with `printf`, for example `i=1; while [ "$i" -le 3 ]; do printf '%02d\n' "$i"; i=$((i + 1)); done` for a padded sequence, or `i=1; while [ "$i" -le 9 ]; do echo "$i"; i=$((i + 4)); done` for a stepped one. Both run on Bash 3.2 and on dash.
+
+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 does not specify brace expansion.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-brace-sequence-padding-step': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 3} -->
+
+```sh
+for n in {01..12}; do echo "report-$n"; done
+echo {1..9..4}
+cp backup{a..e..2}.tar /tmp
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+
+```sh
+n=1
+while [ "$n" -le 12 ]; do printf 'report-%02d\n' "$n"; n=$((n + 1)); done
+echo {1..3} {a..c}
+echo '{01..12}'
+a={01..03}
+```
+
+With `shellVersion: "4.0"` or newer, or with no `shellVersion`, both forms are fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `shellVersion`
+unset, which makes the rule report nothing.
+
+## Relationship to shellcheck
+
+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 SC3009 (brace expansion is undefined in POSIX sh) under `-s sh` for every brace expansion, a plain `{1..3}` and `{a,b}` included. Under `-s bash` it reports nothing for these sequences. It does not know which Bash release a script must run on, so it cannot report the padded and stepped forms for a Bash 3.2 target. This rule exists for that target.

package/docs/rules/require-tty-guard.md

@@ -82,7 +82,10 @@ if [ -t 0 ]; then read name; fi
 A multi-line statement that starts its own line is wrapped on lines of its own. Anywhere else the
 wrapper goes around it in place, because an earlier command on the line may have opened a
 here-document whose body begins at the next line break; a line break goes before `fi` only when the
-statement ends in a here-document of its own. A statement run in the background (`read x &`)
+statement ends in a here-document of its own. A statement whose here-document opener shares its
+line with another command (`read x 3<<EOF; echo hi`, or a trailing comment) gets no suggestion: the
+statement's source runs on to the terminator, so wrapping it would pull that command into the guard
+and it would run only on a terminal. A statement run in the background (`read x &`)
 gets no suggestion, because wrapping it would change what is backgrounded. A statement whose exit
 status steers control flow (an `if`/`while`/`until` condition, or an operand of `&&` or `||`) is
 reported without a suggestion too: the wrapper would exit 0 when there is no terminal, which

package/docs/shellcheck.md

@@ -78,6 +78,7 @@ reason given, and each rule's page has a "Relationship to shellcheck" section. T
 | [`sh/compat/no-double-bracket`](./rules/compat/no-double-bracket.md), [`no-let`](./rules/compat/no-let.md), [`no-source`](./rules/compat/no-source.md) | SC3010 (`[[`), SC3039 (`let`), SC3046 (`source`), under `-s sh` only | Under `-s bash` shellcheck reports nothing for `[[` or `source`, and for `let` only SC2219, a style note that prefers `(( ))`. These rules report them for the dialect you configure, because they fail on dash and would otherwise defeat a preset named for portability. |
 | [`sh/compat/no-test-v`](./rules/compat/no-test-v.md), [`no-wait-n`](./rules/compat/no-wait-n.md), [`no-globstar`](./rules/compat/no-globstar.md), [`no-pipe-all`](./rules/compat/no-pipe-all.md), [`no-fd-variable`](./rules/compat/no-fd-variable.md), [`no-unicode-escape`](./rules/compat/no-unicode-escape.md) | SC3016 (`test -v`, with SC3010 for `[[`), SC3045 (`wait -n`), SC3044 (`shopt`), SC3029 (`\|&`), SC3022 (`{fd}`), SC3003 (`$'…'`) | shellcheck reports these Bash features only for scripts it treats as POSIX `sh`. These rules report them for a Bash version you name. |
 | [`sh/compat/no-nameref`](./rules/compat/no-nameref.md), [`no-case-attributes`](./rules/compat/no-case-attributes.md) | SC3043 (`local`), SC3044 (`declare`, `typeset`): the command, not the `-n`, `-l` or `-u` option | Under `-s sh` shellcheck reports the command that carries the option; under `-s bash` it reports nothing for either. These rules report the option for a Bash version you name. |
+| [`sh/compat/no-brace-sequence-padding-step`](./rules/compat/no-brace-sequence-padding-step.md) | SC3009 (brace expansion, under `-s sh` only) | Under `-s sh` shellcheck reports every brace expansion, a plain `{1..3}` and `{a,b}` too, as undefined in POSIX sh. Under `-s bash` it reports nothing, so a Bash older than 4.0 gets no finding for the padded and stepped forms. The rule reports only those two forms, for a Bash version you name. |
 | [`sh/compat/no-case-fallthrough`](./rules/compat/no-case-fallthrough.md) | SC2127 (an error, not an SC3xxx check) | Under `-s sh` shellcheck asks for a bash or ksh shebang; under `-s bash` it reports nothing. The rule reports `;&` and `;;&` for a Bash version you name. |
 | [`sh/compat/no-epoch-variables`](./rules/compat/no-epoch-variables.md) | SC3028 (`$EPOCHSECONDS`, `$EPOCHREALTIME`, under `-s sh` only) | Under `-s bash` shellcheck reports nothing, so a Bash older than 5.0 gets no finding. The rule reports them for a Bash version you name. |
 | [`sh/compat/no-append-all-redirect`](./rules/compat/no-append-all-redirect.md), [`no-parameter-transformation`](./rules/compat/no-parameter-transformation.md), [`no-printf-time-format`](./rules/compat/no-printf-time-format.md), [`no-nounset-empty-array`](./rules/compat/no-nounset-empty-array.md) | none | shellcheck reports nothing for `&>>`, `${v@op}`, `printf '%(…)T'` or an empty array under `set -u`, under `-s sh` or `-s bash` (it reports only the array syntax, SC3030 and SC3054, under `-s sh`). |

package/docs/untrusted-code.md

@@ -0,0 +1,440 @@
+# Linting code you don't control
+
+eslint-sh is often a policy gate: CI lints a pull request, an agent's output, or a vendored
+repository whose author does not own the policy. In that setting, the author controls the scripts
+under review and every other file in the checkout. This page covers what that lets them change, how
+to run the lint from a directory outside those files, so that they can't change its configuration
+or its exit code, and what a passing run still doesn't tell you:
+
+- [What a script's comments can switch off](#what-a-scripts-comments-can-switch-off)
+- [A policy config that ignores them](#a-policy-config-that-ignores-them)
+- [Run ESLint from outside the checkout](#run-eslint-from-outside-the-checkout)
+- [Declaration conventions that read files](#declaration-conventions-that-read-files)
+- [Which files get linted](#which-files-get-linted)
+- [What this does not cover](#what-this-does-not-cover)
+
+Everything below was run against ESLint 10.2.0, the oldest version this plugin's peer range allows,
+and against 10.7.0.
+
+## What a script's comments can switch off
+
+ESLint's inline comments work in shell scripts the same way they do in JavaScript, with `#` as the
+comment marker. With the default `linterOptions`, a script can silence any rule for itself, and
+neither `sh/recommended` nor `sh/agent-authored` changes that. Each of these scripts lints with no
+`sh/no-eval` report under `sh.configs.recommended`:
+
+```sh
+#!/bin/bash
+# eslint-disable-next-line sh/no-eval
+eval "$x"
+```
+
+| Comment                                      | Effect                                       |
+| -------------------------------------------- | -------------------------------------------- |
+| `# eslint-disable-next-line sh/no-eval`      | Silences the rule on the next line.          |
+| `eval "$x" # eslint-disable-line sh/no-eval` | Silences the rule on its own line.           |
+| `# eslint-disable` … `# eslint-enable`       | Silences every rule between the two.         |
+| `# eslint sh/no-eval: off`                   | Turns the rule off for the whole file.       |
+
+The `eslint` prefix is the default `languageOptions.directivePrefix`. A config that sets it, for
+example to `shellcheck-sh`, makes `# shellcheck-sh-disable-next-line sh/no-eval` the working form
+and turns `# eslint-disable-next-line` into an ordinary comment. The prefix is chosen by the config,
+not by the script, and it does not stop directives, it only renames them.
+
+## A policy config that ignores them
+
+Set `linterOptions.noInlineConfig` in the config you lint with. The `globalIgnores` line and the
+`checkout/` in `files` belong to [the recipe](#run-eslint-from-outside-the-checkout), which explains
+them.
+
+```js
+// policy/eslint.config.mjs
+import { defineConfig, globalIgnores } from 'eslint/config';
+import sh from '@eslint-sh/eslint-plugin';
+
+export default defineConfig([
+  globalIgnores(['!**/node_modules/', 'checkout/.git/']),
+  {
+    files: ['**/*.sh', '**/*.bash', 'checkout/**/bin/?*'],
+    extends: [sh.configs.recommended],
+    linterOptions: { noInlineConfig: true },
+  },
+]);
+```
+
+`noInlineConfig: true` makes ESLint ignore every comment in the table above, whatever the
+`directivePrefix`. The rule reports as if the comment were not there, and ESLint adds a warning with
+no rule id at the comment itself. For the script above, with its other report:
+
+```text
+1:1  error    Enable strict mode with `set -euo pipefail` within the first 5 statements; not enabled: errexit, nounset, pipefail                      sh/require-strict-mode
+2:1  warning  '# eslint-disable-next-line sh/no-eval' has no effect because you have 'noInlineConfig' setting in your config
+3:1  error    `eval` runs text as shell code at run time, so the code it executes cannot be statically reviewed. Write the commands directly instead  sh/no-eval
+```
+
+The plugin returns its directives to ESLint through the language's `getDisableDirectives` and
+`getInlineConfigNodes` hooks, and ESLint applies `noInlineConfig` to them as it does to
+JavaScript comments. Under `--max-warnings 0`, that warning fails the
+run on its own: a contributed script that contains any directive fails the gate, even one that would
+have suppressed nothing. If you would rather let those through, run without `--max-warnings 0` and
+read the warnings, but then no other warning fails the run either (see the
+[continuous integration exit codes](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-sh/README.md#continuous-integration)).
+
+**If you accept directives instead.** `linterOptions.reportUnusedDisableDirectives` sets the
+severity of a disable comment that suppressed nothing. ESLint 10's default is `"warn"`; `"error"`
+fails the run on one:
+
+```js
+// policy/eslint.config.mjs, directives allowed
+import { defineConfig, globalIgnores } from 'eslint/config';
+import sh from '@eslint-sh/eslint-plugin';
+
+export default defineConfig([
+  globalIgnores(['!**/node_modules/', 'checkout/.git/']),
+  {
+    files: ['**/*.sh', '**/*.bash', 'checkout/**/bin/?*'],
+    extends: [sh.configs.recommended],
+    linterOptions: { reportUnusedDisableDirectives: 'error' },
+  },
+]);
+```
+
+This keeps stale directives out of the tree, but it is not a gate: the `# eslint-disable-next-line
+sh/no-eval` above still silences `sh/no-eval`, because it did suppress something. Setting both
+options is allowed, but `reportUnusedDisableDirectives` then reports nothing, because
+`noInlineConfig` has already discarded every directive.
+
+## Run ESLint from outside the checkout
+
+`linterOptions` only helps if the contributor can't replace the config, ESLint or the plugin, and
+can't change the result some other way. ESLint finds several of its inputs in the directory it runs
+in, and Node looks through that directory's parents for packages. When that directory is the
+checkout, every one of these belongs to the contributor:
+
+- **The config.** `eslint .` without `--config` imports the `eslint.config.mjs` in the directory it
+  runs in, as JavaScript, with your job's environment variables. ESLint 10 also loads an
+  `eslint.config.*` from a subdirectory for the files under it, so a nested config in the checkout
+  runs, and replaces your policy for its directory, even if your config sits at the root.
+- **Where the config's imports resolve.** `import sh from '@eslint-sh/eslint-plugin'` resolves
+  from the config file's own location. A copy of your config placed inside the checkout imports
+  the checkout's `node_modules`.
+- **Which ESLint runs.** `npx eslint` in the checkout runs the checkout's
+  `node_modules/.bin/eslint`.
+- **The formatter.** ESLint resolves a formatter name, including the default `stylish`, as the
+  package `eslint-formatter-stylish` from the directory it runs in and then from each of its parents,
+  with or without `--config`. That package is code in your job. It can print what it likes and set
+  the exit code.
+- **The suppressions file.** ESLint applies `eslint-suppressions.json` from the directory it runs in
+  whenever that file exists, with no flag, and neither `--config` nor `noInlineConfig` affects it.
+  An error listed in the file is hidden, and the run exits 0.
+- **The cache file.** With `--cache`, ESLint reads `.eslintcache` from the directory it runs in and
+  reuses the results recorded there. The default `--cache-strategy metadata` trusts a recorded size
+  and modification time. `--cache-strategy content` doesn't help either, because the hash it
+  compares against is in the same file.
+- **Your job's own relative paths.** A relative entry in `PATH`, or a relative file in
+  `NODE_OPTIONS`, resolves against the directory ESLint runs in, so either can run a file from the
+  checkout. A version manager may read its settings from there too: `nodenv` runs ESLint under the
+  Node version named in a `.node-version` in the checkout or any parent. Other version managers were
+  not tested.
+
+Installing the checkout is a separate hazard: `npm ci` and `npm install` run the package's lifecycle
+scripts, such as `preinstall`. The lint needs none of the checkout's dependencies, so don't install
+them.
+
+The recipe is to run ESLint somewhere else and pass the checkout as an argument. Keep the policy
+where the contributor can't change it in the same change, such as a separate repository or a path
+your CI provides, with `eslint` and `@eslint-sh/eslint-plugin` installed there from its own lockfile.
+If `policy` is a link to such a path, the rule below applies to the parents of its real location
+too, and the guards don't look there.
+Put it beside the checkout, in a directory your job creates and the contributor can't write to.
+Neither that directory nor any of its parents may be inside the contributor's files: a CI job often
+starts in a clone of the repository under review, so don't create it there. The recipe refuses a
+`node_modules` in a parent, but it has no guard for the rest of that rule, such as a `.node-version`
+there.
+
+```text
+job-directory/
+  policy/      eslint.config.mjs and its own node_modules
+  checkout/    the code under review
+```
+
+Create `checkout` yourself, so that nothing of the contributor's lands beside it. From a repository:
+
+```sh
+git clone URL checkout
+```
+
+From a tarball, keep the input archive outside `job-directory` (here, `../x.tar`) and unpack only
+into `checkout`. Keep every path as archived: the policy covers files directly inside any `bin/`
+directory under `checkout`, so wrappers and siblings need no special handling.
+
+```sh
+[ ! -e checkout ] && [ ! -L checkout ] || { printf 'checkout already exists\n' >&2; exit 1; }
+mkdir checkout && tar -xf ../x.tar -C checkout || exit 1
+```
+
+Stop the job if this fails: a failed `tar` can leave only some of the files. Don't strip path
+components or move files out of a wrapper; stripping can silently discard top-level files.
+
+Then, from `job-directory`, not from inside the checkout:
+
+```sh
+[ "$(ls -A | wc -l)" -eq 2 ] && [ -d policy ] && [ -d checkout ] || {
+  printf 'the job directory must hold only checkout and policy\n' >&2
+  exit 1
+}
+dir=$(pwd -P)
+while :; do
+  if [ -e "$dir/node_modules" ]; then
+    printf 'node_modules in or above the job directory: %s\n' "$dir" >&2
+    exit 1
+  fi
+  [ "$dir" != / ] || break
+  dir=$(dirname "$dir")
+done
+policy/node_modules/.bin/eslint \
+  --config policy/eslint.config.mjs \
+  --max-warnings 0 \
+  checkout
+```
+
+- The working directory is what closes the list above. `eslint-suppressions.json`, `.eslintcache`
+  and any relative path in your job's environment resolve in `job-directory`, the formatter name
+  resolves there and in its parents, and the checkout's copies are never consulted.
+- The first guard refuses anything else in `job-directory`, because ESLint reads its inputs from
+  there: a tarball unpacked here rather than as above can leave an `eslint-suppressions.json` beside
+  the checkout. It can't catch such a tarball writing into `policy/`, which only unpacking elsewhere
+  prevents.
+- The second guard refuses a `node_modules` in `job-directory` or any parent, because Node looks
+  there for the formatter and for a package ESLint's own dependencies ask for on every run, whatever
+  `--format` says, and a package found there runs in your job and can set the exit code. If it
+  refuses a `node_modules` of your own, such as one in your home directory, make the job directory
+  with `mktemp -d` instead.
+- `--config` loads only the policy, and its imports resolve from `policy/node_modules`.
+- The checkout has to be under the working directory. With `--config`, ESLint matches the config's
+  `files` and `ignores` against the directory it runs in and treats anything outside it as ignored:
+  running from inside `policy/` with `../checkout`, or from elsewhere with an absolute path, exits 2
+  with `all of the files matching the glob pattern ... are ignored`. The policy's
+  `checkout/**/bin/?*` matches files directly in a `bin` at any depth under `checkout`.
+- `!**/node_modules/` in `globalIgnores` turns off ESLint's default ignore of `**/node_modules/`.
+  Without it, a script under any directory named `node_modules`, at any depth, is not linted, and
+  the contributor can commit a directory of that name anywhere. A wrapper named `node_modules`
+  or starting with a dot is covered too. `node_modules/.bin` is not a directory named `bin`:
+  regular files there need a `.sh` or `.bash` extension to match; its usual symlinks fail the check.
+- `checkout/.git/` in `globalIgnores` keeps the lint out of the clone's repository data, because
+  ESLint's default ignores only a `.git` in the directory it runs in, and a branch called
+  `fix/deploy.sh` is a file there that matches `files`.
+- `--max-warnings 0` makes warnings, including the "has no effect" warnings above, fail the run.
+  The exit codes are the ones in the
+  [continuous integration table](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-sh/README.md#continuous-integration).
+- Leave `--cache` off. The recipe needs no cache, and if you add one, it must not come from the
+  checkout or from anything else the contributor could write.
+
+To find what was left, this command was run with every `fs` call, module load and child process
+logged, against a checkout holding each ESLint input named on this page and a marker-writing copy
+of every package in the policy's install. Under the checkout, ESLint only listed directories and read the
+files it lints. It loaded no module from there and started no process. That is a result for the
+ESLint versions above, not a promise from ESLint; this page's tests repeat the trace on the version
+the repository uses.
+
+The workflow that runs this command is part of the gate too: keep it, like the policy, where the
+contributor's change can't edit it. Nothing of the contributor's should have run on the machine
+before it, either: an install, build or test run in the same job can change any file the job can
+write, including the policy.
+
+## Declaration conventions that read files
+
+A [`DeclarationConvention`](./declaration-conventions.md) is code in your config, and one that reads
+files reads whatever path it is given. When linting code you don't control, read only paths you
+control: a file built from the policy config's own location (`new URL('./commands.txt',
+import.meta.url)`), or data in the config itself. Don't read a file located from the linted script's
+path, such as the per-script sidecars in
+[declarations outside the script](./declaration-conventions.md#declarations-outside-the-script) or
+`scriptSidecarCommands()` in the repository's
+[container-entrypoint example pack](https://github.com/mike-north/eslint-sh/tree/main/examples/container-entrypoint-pack):
+in a checkout under review, every file next to a script belongs to the contributor.
+
+## Which files get linted
+
+ESLint lints the files the policy's `files` patterns match, and the contributor chooses file names.
+With the policy above, a checkout with a clean `ok.sh` and these scripts, each starting `#!/bin/bash`
+and containing `eval "$x"`, exits 0 with no report from the recipe:
+
+- `ci/run` and `deploy`: no extension, outside any `bin/`.
+- `build.SH`: the patterns are case-sensitive.
+- `x.zsh`: the extension is not in the patterns.
+- `script.sh.txt`: the pattern needs the name to end in `.sh`.
+
+Naming a script differently is enough to avoid being linted. Widening the patterns does not close
+this, because any list of names is a list the contributor can step around. What you can do is
+check the checkout for files that start with a shell shebang and that the patterns do not match,
+and fail the job when there are any. Run this from `job-directory`, before the lint, from a workflow
+the contributor can't edit:
+
+```sh
+[ -d checkout ] && [ ! -L checkout ] || { printf 'no checkout directory here\n' >&2; exit 2; }
+status=0
+while IFS= read -r -d '' file; do
+  if [ -L "$file" ] || [ ! -f "$file" ] || [ ! -r "$file" ]; then
+    printf 'symlink, special or unreadable file: %q\n' "$file" >&2
+    status=1
+    continue
+  fi
+  case "$file" in
+    *.sh | *.bash) continue ;;
+  esac
+  # The policy covers direct children of every bin, regardless of wrappers.
+  case "${file%/*}" in
+    */bin) continue ;;
+  esac
+  if head -c 1024 "$file" | head -n 1 | LC_ALL=C grep -Eiq '^#!.*sh'; then
+    printf 'not linted, but has a shell shebang: %q\n' "$file" >&2
+    status=1
+  fi
+done < <(find checkout -path checkout/.git -type d -prune -o ! -type d -print0)
+[ "$status" -eq 0 ] || exit "$status"
+```
+
+This needs `bash` (it uses `read -d` and process substitution). It exits non-zero when it finds
+something and otherwise falls through, so it can sit above the recipe in one script or run as its
+own step. Its first line exits 2 without a real `checkout` directory, because a failing `find`
+wouldn't fail the check, and a check run from the wrong directory would pass every time. The first
+`case` covers the extensions; the second checks the parent directory, so it covers direct children
+of every `bin/` without accidentally accepting `bin/sub/run`. Keep these checks in sync with the
+policy's `files`.
+
+To rename `checkout`, change it everywhere. Left behind in the guards or the recipe's argument, the
+old name stops the run, and in `globalIgnores` it can only add failures. The policy's `files`, the
+`case` and the `find` must change together: if only `files` is left behind, `.sh` files are still
+linted, so nothing looks wrong, but `bin/` silently isn't.
+
+The check looks everywhere in the checkout except a top-level `.git` directory, including under
+`node_modules`. The lint skips that directory too, and only a tarball can put files of its own there,
+so don't run anything from it. The check names every file in the example above except `ok.sh`, and it
+fails on any symlink, special file or file it can't read (see [symlinks](#what-this-does-not-cover)),
+so an installed `node_modules`, whose `.bin` holds symlinks, fails it too. A directory it can't read
+only makes `find` print an error, and the recipe then exits 2 on it. It flags any first line starting `#!` that contains `sh` in any
+case, so `#!/usr/local/bin/publish` fails it as well. When it fails, either fix the name or extend
+the policy's `files` to cover the file.
+
+It uses `find` where `git ls-files` would be shorter, because git reads the checkout's own repository
+configuration, which a checkout you did not clone yourself can set, and that configuration can run
+commands. Don't run git in such a checkout, including to list changed files.
+
+It is not a complete answer. A script with no shebang, outside every `bin/` and without a `.sh` or
+`.bash` extension, passes both the lint and this check, even if something runs it as `sh deploy` or
+`source`s it. So does one whose
+shebang doesn't contain `sh`, such as a wrapper with another name. The check narrows what a
+contributor can hide; it does not make the set of linted files equal to the set of scripts the
+project runs.
+
+The lint sees the files on disk, not the commit, so run it on a file system that keeps every name
+apart, such as Linux's: on macOS's default, a commit with both `A.sh` and `a.sh` clones to one file,
+and only that file is linted. The same goes for names that differ only in Unicode normal form,
+which collide on APFS even on a case-sensitive volume. Lint what you will run, too. A plain clone leaves a submodule's directory empty, so use
+`git clone --recurse-submodules` if anything later fetches submodules. And the contributor's
+`.gitattributes` can mark a file `export-ignore`, which keeps it out of a `git archive` tarball, so
+a tarball can lint clean while a clone of the same commit holds the file.
+
+An honest repository can also fail the recipe. ESLint lints `*.js`, `*.mjs` and `*.cjs` by default,
+whatever the policy's `files` say, and `checkout/**/bin/?*` covers everything directly in any `bin/`
+under `checkout`, including vendored binaries. Those files are linted as shell, and can fail with
+parse errors or shell policy findings. A JavaScript file with a disable comment, a JavaScript file
+that ESLint's default parser rejects, or a
+Python script in `bin/` each exits 1. So does any JavaScript file directly in `bin/`, however valid,
+with a message telling you to add a `files` entry that is already there, and an empty `bin/.gitkeep`.
+A checkout with nothing to lint exits 2 with `all of the files matching the glob pattern ... are
+ignored`. These failures are closed rather than open. The policy's `files` and `ignores` are yours
+to adjust, as long as the check's `case` patterns stay the same as what you leave linted.
+
+## What this does not cover
+
+Run this way, ESLint reads the checkout's files only as text to lint. That is all the recipe does.
+
+**A clean lint is not evidence that a script is harmless.** Exit 0 means your policy's rules found
+nothing in the files your policy matched. The rules look for patterns; they do not work out what a
+script does. Under `sh.configs.recommended`, `eval "$1"` is an error and `bash -c "$1"`, which also
+runs its argument as code, exits 0 with no report. Passing text to a shell another way, or
+downloading a file and running it, passes too. Don't take a clean lint as a reason to run a script
+you haven't reviewed.
+
+**It is not a sandbox.** Linting parses the contributor's files in the job's own process, with the
+job's environment variables and file access. The linter does not execute the scripts under review:
+a script that touches a file at its top level, in `$(...)`, in `<(...)`, in an `eval` string, or
+in a `source`d file created none of the test's marker files. But that is not isolation. If a leaked
+secret or a parser fault in the job is the concern, run the lint in a container or a CI job that has
+no secrets and no network access it does not need. Give the job a time limit: a named pipe called
+`f.sh`, which a tarball can deliver though git can't, hung the run until it was killed. This page
+did not test pathological inputs exhaustively.
+
+**The report contains the contributor's text.** ESLint prints file names as they are, and rule
+messages quote parts of the script. A file name containing newlines can print lines that look like
+a clean summary. The exit code doesn't depend on any of that text, so gate on the exit code, and
+treat the report as untrusted wherever you display it.
+
+**`noInlineConfig` does not cover a script's own declarations.** `noInlineConfig` ignores ESLint's
+comments. It leaves alone anything a `DeclarationConvention` reads out of the script. With
+`commentPragma` bound, `sh/no-undeclared-commands` at `error`, and `noInlineConfig: true`, this
+script has two reports, for `curl` and for `sh`:
+
+```sh
+#!/bin/bash
+set -euo pipefail
+curl https://example.com/install | sh
+```
+
+and this one, whose header declares them itself, has none and the run exits 0:
+
+```sh
+#!/bin/bash
+# uses: curl sh
+set -euo pipefail
+curl https://example.com/install | sh
+```
+
+Don't bind `commentPragma`, or any convention that reads declarations from the script, in a policy
+for code you don't control. To use the declaration rules as a gate, take the declarations from the
+policy: a convention that returns a list written in the config, which the script cannot add to.
+
+```js
+// policy/eslint.config.mjs
+const allowed = ['jq', 'git'];
+
+/** Declarations come from this config, never from the script. */
+const policyDeclarations = {
+  declaredCommands: () =>
+    allowed.map((name) => ({
+      kind: 'described',
+      name,
+      description: 'the allowed commands in policy/eslint.config.mjs',
+    })),
+};
+
+// In the config entry: settings: { sh: { declarationConvention: policyDeclarations } },
+```
+
+With that convention, the script with the `# uses: curl sh` header is reported for `curl` and `sh`,
+the same as the one without it.
+
+**A relative sidecar path resolves against the working directory.** With the recipe, that is
+`job-directory`. With the example pack's `sidecarCommands('commands.txt')` in the policy and no such
+file in `job-directory`, the config fails to load and ESLint exits 2, whatever the checkout holds.
+A path that reaches into the checkout hands over the list: with
+`sidecarCommands('checkout/commands.txt')` and that file listing `curl` and `sh`, the script above
+exits 0. The same config with the absolute path of a file in your policy,
+`sidecarCommands('/ci/policy/commands.txt')`, reports both commands. Give a convention an absolute
+path to a file outside the checkout, or build it from `import.meta.url` as
+[above](#declaration-conventions-that-read-files), or use no sidecar.
+
+**A symlink in the checkout can point outside it.** A file symlink whose name matches the policy's
+`files`, or ESLint's default JavaScript patterns, is followed: ESLint lints the file it points at,
+wherever that is. A `leak.sh` linking to a
+text file outside the checkout printed that file's parse error, such as ``Parsing error: `if` must
+be followed by a statement list``, and a link to a script outside the checkout printed rule
+messages naming its unquoted variables and their line numbers. If the report is posted where the
+contributor can read it, that leaks a little of whatever the link points to, and text inside an
+unquoted `$(...)` prints verbatim. Other symlinked directories are not followed: files behind a link
+to a directory were not linted or reported. A link to a directory or to nothing stops the run with
+exit 2 if its own name matches `files` or ESLint's default JavaScript patterns, and is skipped
+otherwise. The check above rejects every symlink under the checkout, including one named
+`node_modules` or `.git`, which closes the file case when it runs before the lint.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eslint-sh/eslint-plugin",
   "description": "Shell script linting for ESLint, with built-in policy rules, shared presets, and custom rules over a typed shell AST",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "author": "Mike North <michael.l.north@gmail.com>",
   "dependencies": {
     "@eslint/core": "^1.2.1",