@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/dist/rules/no-masked-exit-status.js

@@ -0,0 +1,667 @@
+/**
+ * `sh/no-masked-exit-status`: a declaration builtin whose value is a command
+ * substitution reports the builtin's exit status, not the command's.
+ *
+ * `local x=$(cmd)`, `export X=$(cmd)`, `readonly X=$(cmd)`, `declare x=$(cmd)`
+ * and `typeset x=$(cmd)` all succeed whatever `cmd` did, so `set -e` does not
+ * stop the script and `… && next` runs `next` anyway. A script that turns
+ * strict mode on still swallows the failure there (shellcheck SC2155).
+ *
+ * **What is reported.** A `local`, `declare`, `typeset`, `export` or
+ * `readonly` operand of the form `name=value` whose value contains a command
+ * substitution (`$(…)` or backticks) at any depth of the word: inside double
+ * quotes, next to other text, inside a parameter expansion's operand, a
+ * substring offset or an array subscript, and inside an arithmetic expansion.
+ * Real shells give a plain assignment the status of a substitution in any of
+ * those places, so the declaration hides it from all of them. A process
+ * substitution (`<(…)`) is not looked into: it expands to a path. The builtin
+ * is also read behind the transparent wrappers `builtin` and `command`. One
+ * report is made per operand, on the operand. An array value
+ * (`local -a a=($(cmd))`) is not reported: shellcheck 0.11.0 does not report
+ * it either, and a status-bearing scalar is the construct the rule exists for.
+ *
+ * Not reported: a value with no substitution, a declaration with no value,
+ * a plain assignment (`x=$(cmd)` keeps the command's status), and the split
+ * form `local x; x=$(cmd)`.
+ *
+ * **Options.** `builtins` limits which of the five builtins are checked.
+ * `onlyWithErrexit` reports only where `errexit` is known to be on, except
+ * where the script reads the status explicitly: the left side of `&&` / `||`,
+ * the right side of one that is itself read (the middle of `a && b && c`), and
+ * the last command of an `if`/`elif`/`while`/`until` condition. There the
+ * status is the builtin's whatever the options. `errexit` is known to be on
+ * for a statement when the plain top-level `set` statements before it (read
+ * with `require-strict-mode`'s `set` reading) leave it on, wherever they sit,
+ * and, with `allowShebangOnly`, when the shebang line enables it. A function
+ * body is read at the point it is defined. Under the `bats` dialect a
+ * statement written directly in an `@test` body or a top-level `setup` /
+ * `teardown` hook is on, as in `no-unchecked-cd`. A `set` inside a function,
+ * a group or a condition, in a sourced file, or `set -e` on a command line
+ * (`bash -e script.sh`) is not seen.
+ *
+ * **No autofix, only a suggestion.** Splitting the declaration changes
+ * behavior on purpose: under `set -e` a failure now stops the script. The
+ * suggestion declares the names first and assigns each substituted one on its
+ * own statement, keeping the builtin's flags; `export` assigns first and
+ * exports afterwards, because exporting first would put the old value in the
+ * substitution's environment. It is withheld where splitting
+ * would not be equivalent, would change the surrounding list, or would turn
+ * invalid input into a valid assignment:
+ *
+ * - the value reads a name the split moves before it. For `local`, `declare`
+ *   and `typeset` inside a function that includes the variable itself (the
+ *   declaration creates an empty local, so the old value the substitution
+ *   read is gone); for every builtin it includes the other operands of the
+ *   same declaration, which the split assigns earlier or later than before.
+ *   Any mention of such a name in the value counts, because a command can
+ *   read a variable by name (`[ -v x ]`, `declare -p x`, `printenv x`), and
+ *   under `-i` the builtin evaluates values as arithmetic, and `export` runs
+ *   after the assignments, so both reach the values without a substitution;
+ * - a scoped declaration of a variable the shell or its commands consult
+ *   (`local PATH=$(cmd)`): the declaration empties it before the command runs;
+ * - code the rule cannot read may read such a name: the value runs `eval`,
+ *   `source` or `.`, a command whose name is not static, or a function
+ *   defined in this file. This applies where the split changes what is
+ *   visible: `local`, `declare` or `typeset` inside a function, several
+ *   operands, or any flag. A function defined in another file cannot be seen,
+ *   so a call to it is not detected;
+ * - the statement has prefix assignments (`A=1 export x=$(cmd)`), which the
+ *   replacement would delete;
+ * - a flag changes the meaning of the split or is not valid with an
+ *   assignment: `-g` (the split writes the local, not the global), `-x` on
+ *   `local`, `declare` or `typeset` (declaring first exports the name to the
+ *   substitution), `-n` on those builtins (the assignment writes through a
+ *   nameref that already exists), `-f`, `-F`, `-p`, `export -x`, or any flag
+ *   not static;
+ * - `local` outside a function, which is an error;
+ * - the declaration is not a standalone statement: an operand of `&&` / `||`
+ *   or a pipeline, a condition, negated, backgrounded, redirected, or the
+ *   body of a function written without braces;
+ * - the declaration is reached through `builtin` or `command`;
+ * - an operand is an append (`+=`) or has a subscript (`a[1]=…`).
+ *
+ * `-r` (and `readonly` itself) forbids a later assignment, so those forms are
+ * split into the declaration, the assignment, then `readonly <names>`.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { childNodes } from '../language/syntax-view.js';
+import { lineBreakOf } from '../language/line-breaks.js';
+import { createRule } from './create-rule.js';
+import { batsErrexitIsOn, isStatusChecked } from './no-unchecked-cd.js';
+import { setStatementChanges } from './require-strict-mode.js';
+import { applySetOptionChanges, shebangOptionChanges } from './set-options.js';
+import { BUILTIN_WRAPPER } from './transparent-wrappers.js';
+/** Every declaration builtin the rule can check; the default for `builtins`. */
+const ALL_BUILTINS = ['local', 'declare', 'typeset', 'export', 'readonly'];
+/** The builtins that create a variable in the enclosing function's scope. */
+const SCOPED_BUILTINS = new Set(['local', 'declare', 'typeset']);
+/**
+ * Variables the shell or the commands it runs consult. A scoped declaration
+ * empties them for the substitution that the split moves after it, so
+ * `local PATH; PATH=$(cmd)` cannot even find `cmd`. An exported variable of any
+ * other name can be read by a command too, but that is not visible here.
+ */
+const CONSULTED_VARIABLES = new Set([
+    'BASH_ENV',
+    'CDPATH',
+    'ENV',
+    'GLOBIGNORE',
+    'HOME',
+    'IFS',
+    'LANG',
+    'LANGUAGE',
+    'LC_ALL',
+    'LC_COLLATE',
+    'LC_CTYPE',
+    'LC_MESSAGES',
+    'LC_NUMERIC',
+    'LC_TIME',
+    'LD_LIBRARY_PATH',
+    'OLDPWD',
+    'PATH',
+    'POSIXLY_CORRECT',
+    'PWD',
+    'SHELL',
+    'TERM',
+    'TMPDIR',
+    'TZ',
+    'USER',
+]);
+/** A valid shell variable name. */
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/**
+ * Wrappers followed to find the declaration builtin: `command` (with its
+ * `-p`) and `builtin`. Other wrappers (`sudo`, `env`) run external programs,
+ * which cannot be declaration builtins.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS.filter((spec) => spec.names.includes('command')),
+    BUILTIN_WRAPPER,
+];
+/**
+ * Whether `node` contains a command substitution whose status the declaration
+ * would replace. A substitution counts wherever it sits in the word, including
+ * inside an arithmetic expansion, a substring offset or an array subscript:
+ * in a plain assignment a failing substitution there fails the assignment
+ * (and so trips `set -e`) in Bash, dash, zsh and ksh93. A process
+ * substitution is not entered: it expands to a path, so there is no status.
+ */
+function containsCommandSubstitution(node) {
+    if (node.type === 'CmdSubst')
+        return true;
+    if (node.type === 'ProcSubst')
+        return false;
+    return childNodes(node).some(containsCommandSubstitution);
+}
+/** Whether `text` mentions `name` as a whole identifier. */
+function mentionsIdentifier(text, name) {
+    return new RegExp(`(?<![A-Za-z0-9_])${name}(?![A-Za-z0-9_])`, 'u').test(text);
+}
+/**
+ * Whether evaluating `node` reads any of `names`: a parameter expansion of
+ * the name (`$x`, `${x:-…}`, `${a[x]}`), or an arithmetic expansion that
+ * mentions it as a bare name (`$((x + 1))`), or an indirect expansion
+ * (`${!ref}`), which can read any name. Command substitutions are entered, so
+ * `$(echo "$x")` counts. Reads made by code the substitution runs are
+ * {@link runsUnseenCode}'s concern.
+ */
+function readsAnyName(node, names, sourceCode) {
+    if (names.length === 0)
+        return false;
+    if (node.type === 'ParamExp') {
+        if (node.excl)
+            return true;
+        const param = node.param?.value;
+        if (param !== undefined && names.includes(param))
+            return true;
+        if (node.index !== undefined) {
+            const indexText = sourceCode.text.slice(node.index.range[0], node.index.range[1]);
+            if (names.some((name) => mentionsIdentifier(indexText, name)))
+                return true;
+        }
+    }
+    if (node.type === 'ArithmExp' || node.type === 'ArithmCmd') {
+        const arithmetic = sourceCode.text.slice(node.range[0], node.range[1]);
+        if (names.some((name) => mentionsIdentifier(arithmetic, name)))
+            return true;
+    }
+    return childNodes(node).some((child) => readsAnyName(child, names, sourceCode));
+}
+/**
+ * Whether `node` sits inside a function body: a function definition or a bats
+ * `@test` block, which bats runs as a function.
+ */
+function insideFunction(node, sourceCode) {
+    for (let up = sourceCode.getParent(node); up !== undefined; up = sourceCode.getParent(up)) {
+        if (up.type === 'FuncDecl' || up.type === 'TestDecl')
+            return true;
+    }
+    return false;
+}
+/**
+ * Builtins that run code the rule cannot read: they evaluate a string or a
+ * file, so they may read any variable.
+ */
+const CODE_RUNNING_BUILTINS = new Set(['eval', 'source', '.']);
+/** The names of the functions defined anywhere in the file, at any depth. */
+function collectFunctionNames(node, into) {
+    if (node.type === 'FuncDecl' && node.name !== undefined)
+        into.add(node.name.value);
+    for (const child of childNodes(node))
+        collectFunctionNames(child, into);
+    return into;
+}
+/**
+ * Whether evaluating `node` may run code that reads shell variables without
+ * showing it: `eval`, `source` / `.`, a command whose name is not static, or
+ * a call to a function defined in this file. The split moves a declaration
+ * earlier, so such code can see a different variable afterwards. A function
+ * defined in another file cannot be seen and is not detected.
+ */
+function runsUnseenCode(node, functionNames, sourceCode) {
+    if (node.type === 'CallExpr' && node.args.length > 0) {
+        const invoked = sourceCode.resolveInvokedCommand(node, {
+            transparentWrappers: TRANSPARENT_WRAPPERS,
+        });
+        if (invoked?.effective.static !== true)
+            return true;
+        const name = invoked.effective.text;
+        if (CODE_RUNNING_BUILTINS.has(name) || functionNames.has(name))
+            return true;
+    }
+    return childNodes(node).some((child) => runsUnseenCode(child, functionNames, sourceCode));
+}
+/**
+ * The state of `errexit` before each top-level statement of `file`, from the
+ * shebang (when `allowShebangOnly`) and the plain top-level `set` statements
+ * before it, read in order with `require-strict-mode`'s own `set` reading.
+ * Unlike that rule there is no statement window: a `set -e` at any position
+ * counts for the statements after it. A `set` inside a function, a group, a
+ * condition or a sourced file is not seen.
+ */
+function errexitBeforeEachTopLevelStatement(file, sourceCode, allowShebangOnly) {
+    const enabled = applySetOptionChanges(new Set(), allowShebangOnly ? shebangOptionChanges(sourceCode.text) : []);
+    const before = new Map();
+    for (const stmt of file.stmts) {
+        before.set(stmt, enabled.has('errexit'));
+        applySetOptionChanges(enabled, setStatementChanges(stmt, sourceCode));
+    }
+    return before;
+}
+/**
+ * Whether `stmt` is a whole statement of a statement list, so replacing its
+ * command with several statements changes nothing about the list around it.
+ */
+function isStandalone(stmt, sourceCode) {
+    if (stmt.background || stmt.negated || stmt.redirs.length > 0)
+        return false;
+    const parent = sourceCode.getParent(stmt);
+    switch (parent?.type) {
+        case 'File':
+        case 'Block':
+        case 'Subshell':
+        case 'CaseItem':
+            return true;
+        case 'IfClause':
+        case 'WhileClause':
+            return !parent.cond.includes(stmt);
+        case 'ForClause':
+            return parent.do.includes(stmt);
+        default:
+            return false;
+    }
+}
+/** The operand text a declaration keeps for `operand`: its bare name when substituted. */
+function keptText(operand) {
+    return operand.substituted ? operand.name : operand.text;
+}
+/** Reads `name=value` operands of an `Assign` list (a parsed `DeclClause`). */
+function operandsOfDeclClause(node, sourceCode) {
+    const flags = [];
+    const operands = [];
+    let flagsKnown = true;
+    for (const arg of node.args) {
+        if (arg.name === undefined) {
+            const flag = arg.value === undefined ? null : sourceCode.resolveWordText(arg.value);
+            if (flag === null)
+                flagsKnown = false;
+            else
+                flags.push(flag);
+            continue;
+        }
+        const substituted = !arg.naked &&
+            arg.array === undefined &&
+            arg.value !== undefined &&
+            containsCommandSubstitution(arg.value);
+        operands.push({
+            node: arg,
+            name: arg.name.value,
+            substituted,
+            values: arg.value === undefined ? [] : [arg.value],
+            text: sourceCode.text.slice(arg.range[0], arg.range[1]),
+            unsplittable: arg.append || arg.index !== undefined,
+        });
+    }
+    return { variant: node.variant?.value ?? '', flags, operands, flagsKnown };
+}
+/**
+ * Reads `word` as `name=value`, `name+=value` or `name[subscript]=value`, or
+ * `null` when it is not an assignment. The text before the `=` can span parts:
+ * the parser may split `w[1]=` into two literals, and a subscript may hold
+ * expansions and quotes, which are parts of their own, so only literal parts
+ * are scanned for the bracket that closes it. A substitution in the subscript
+ * is not part of the value, as in a parsed `Assign`.
+ */
+function assignmentOfWord(word) {
+    const first = word.parts.at(0);
+    if (first?.type !== 'Lit')
+        return null;
+    const name = /^[A-Za-z_][A-Za-z0-9_]*/u.exec(first.value)?.[0];
+    if (name === undefined)
+        return null;
+    let depth = 0;
+    let subscripted = false;
+    for (const [index, part] of word.parts.entries()) {
+        if (part.type !== 'Lit') {
+            if (depth === 0)
+                return null;
+            continue;
+        }
+        for (let at = index === 0 ? name.length : 0; at < part.value.length; at += 1) {
+            const character = part.value[at];
+            if (depth > 0) {
+                if (character === '\\')
+                    at += 1;
+                else if (character === '[')
+                    depth += 1;
+                else if (character === ']')
+                    depth -= 1;
+            }
+            else if (character === '[') {
+                subscripted = true;
+                depth = 1;
+            }
+            else {
+                const append = part.value.startsWith('+=', at);
+                if (character !== '=' && !append)
+                    return null;
+                return {
+                    name,
+                    values: word.parts.slice(index + 1),
+                    unsplittable: subscripted || append,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Reads a declaration builtin whose operands the parser left as ordinary
+ * words: under the `posix` dialect (which has no declaration clause) and
+ * behind `builtin` / `command`. A word {@link assignmentOfWord} recognizes
+ * is an assignment operand; a static word starting with `-` is
+ * a flag; a static bare name is a valueless operand. Any other word (a
+ * dynamic one, say) makes the flags unknown, which only withholds the
+ * suggestion.
+ */
+function declarationOfWords(variant, words, sourceCode) {
+    const flags = [];
+    const operands = [];
+    let flagsKnown = true;
+    for (const word of words) {
+        const text = sourceCode.text.slice(word.range[0], word.range[1]);
+        const assignment = assignmentOfWord(word);
+        if (assignment !== null) {
+            operands.push({
+                node: word,
+                name: assignment.name,
+                substituted: assignment.values.some(containsCommandSubstitution),
+                values: assignment.values,
+                text,
+                unsplittable: assignment.unsplittable,
+            });
+            continue;
+        }
+        const resolved = sourceCode.resolveWordText(word);
+        if (resolved !== null && VARIABLE_NAME.test(resolved)) {
+            operands.push({
+                node: word,
+                name: resolved,
+                substituted: false,
+                values: [],
+                text,
+                unsplittable: false,
+            });
+        }
+        else if (resolved?.startsWith('-') === true) {
+            flags.push(resolved);
+        }
+        else {
+            flagsKnown = false;
+        }
+    }
+    return { variant, flags, operands, flagsKnown };
+}
+/**
+ * The option letters each builtin accepts together with a `name=value`
+ * operand, restricted to ones that mean the same in the split form. Anything
+ * else (`-g`, which retargets the assignment to the global scope; `-x`, which
+ * would export the name to the substitution when declared first; `-n`, whose
+ * later assignment writes through a nameref that already exists instead of
+ * rebinding it; `-f`, `-F` and `-p`, which do not take assignments; an option
+ * the builtin does not have, such as `export -x`) withholds the suggestion, so it never turns an
+ * error into an assignment or moves a write to another scope.
+ */
+const VALID_FLAG_LETTERS = {
+    local: 'aAilrtu',
+    declare: 'aAilrtu',
+    typeset: 'aAilrtu',
+    export: 'n',
+    readonly: '',
+};
+/** Whether every flag word is a short-option cluster of letters valid for `variant`. */
+function flagsAreValid(variant, flags) {
+    const letters = VALID_FLAG_LETTERS[variant] ?? '';
+    return flags.every((flag) => new RegExp(`^-[${letters}]+$`, 'u').test(flag));
+}
+/** Whether a flag word is a short-option cluster that includes `-i` (integer). */
+function isIntegerFlag(flag) {
+    return /^-[A-Za-z]*i[A-Za-z]*$/u.test(flag);
+}
+/** The text after the first `=` of an operand, or `''` for a bare name. */
+function valueText(operand) {
+    const equals = operand.text.indexOf('=');
+    return equals === -1 ? '' : operand.text.slice(equals + 1);
+}
+/** Whether a flag word is a short-option cluster that includes `-r`. */
+function isReadonlyFlag(flag) {
+    return /^-[A-Za-z]*r[A-Za-z]*$/u.test(flag);
+}
+/** `flag` without its `r` letter, or `null` when only the dash would be left. */
+function withoutReadonly(flag) {
+    const remaining = flag.replace('r', '');
+    return remaining === '-' ? null : remaining;
+}
+/**
+ * The replacement text for a standalone declaration, or `null` where no
+ * equivalent split exists. `separator` joins the statements.
+ */
+function splitText(declaration, scoped, separator, functionNames, sourceCode) {
+    const { variant, flags, operands, flagsKnown } = declaration;
+    if (!flagsKnown || operands.some((operand) => operand.unsplittable))
+        return null;
+    const isReadonlyBuiltin = variant === 'readonly';
+    if (isReadonlyBuiltin && flags.length > 0)
+        return null;
+    if (!flagsAreValid(variant, flags))
+        return null;
+    if (scoped && operands.some((operand) => CONSULTED_VARIABLES.has(operand.name)))
+        return null;
+    const names = operands.map((operand) => operand.name);
+    // The names a value could read that the split changes: its own when the
+    // declaration creates a new scope, and the other operands'.
+    const namesAffectingValueOf = (operand) => scoped ? names : names.filter((name) => name !== operand.name);
+    for (const operand of operands) {
+        if (!operand.substituted)
+            continue;
+        const others = namesAffectingValueOf(operand);
+        if (operand.values.some((value) => readsAnyName(value, others, sourceCode)))
+            return null;
+        // A command can read a variable by name, with no expansion to see:
+        // `[ -v x ]`, `declare -p x`, `printenv x`.
+        if (others.some((name) => mentionsIdentifier(valueText(operand), name)))
+            return null;
+    }
+    // Operands without a substitution count in two cases. Under `-i` the builtin
+    // evaluates each value as arithmetic, where a bare identifier reads a
+    // variable. And `export` runs after the assignments, so its other values
+    // would read the new value (`export A=$(c) B=$A`).
+    if (variant === 'export' || flags.some(isIntegerFlag)) {
+        for (const operand of operands) {
+            const text = valueText(operand);
+            if (namesAffectingValueOf(operand).some((name) => mentionsIdentifier(text, name))) {
+                return null;
+            }
+        }
+    }
+    // Code the split cannot see into may read a name that the split declares
+    // earlier or in a new scope. A lone, flagless `export` or `readonly`
+    // operand declares nothing that code could observe differently.
+    const mayObserveDeclaration = scoped || operands.length > 1 || flags.length > 0;
+    if (mayObserveDeclaration &&
+        operands.some((operand) => operand.values.some((value) => runsUnseenCode(value, functionNames, sourceCode)))) {
+        return null;
+    }
+    const makesReadonly = isReadonlyBuiltin || flags.some(isReadonlyFlag);
+    const keptFlags = flags.flatMap((flag) => {
+        if (!isReadonlyFlag(flag))
+            return [flag];
+        const stripped = withoutReadonly(flag);
+        return stripped === null ? [] : [stripped];
+    });
+    const substituted = operands.filter((operand) => operand.substituted);
+    // `export` creates no scope, so nothing needs it to come first, and coming
+    // first would export the old value to the substitution.
+    if (variant === 'export') {
+        return {
+            text: [
+                ...substituted.map((operand) => operand.text),
+                [variant, ...flags, ...operands.map(keptText)].join(' '),
+            ].join(separator),
+            messageId: 'assignThenExport',
+        };
+    }
+    const statements = [];
+    const declared = isReadonlyBuiltin
+        ? operands.filter((operand) => !operand.substituted)
+        : operands;
+    if (declared.length > 0) {
+        statements.push([variant, ...keptFlags, ...declared.map(keptText)].join(' '));
+    }
+    for (const operand of substituted)
+        statements.push(operand.text);
+    if (makesReadonly) {
+        const readonlyNames = isReadonlyBuiltin ? substituted : operands;
+        statements.push(`readonly ${readonlyNames.map((operand) => operand.name).join(' ')}`);
+    }
+    return {
+        text: statements.join(separator),
+        messageId: makesReadonly ? 'assignThenReadonly' : 'declareThenAssign',
+    };
+}
+/** Built-in rule `sh/no-masked-exit-status`. @internal */
+export const noMaskedExitStatus = createRule({
+    name: 'no-masked-exit-status',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'disallow a declaration builtin (`local`, `export`, …) assigned from a command substitution, which hides the command’s exit status',
+        },
+        hasSuggestions: true,
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    onlyWithErrexit: { type: 'boolean' },
+                    allowShebangOnly: { type: 'boolean' },
+                    builtins: {
+                        type: 'array',
+                        items: { enum: [...ALL_BUILTINS] },
+                        minItems: 1,
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        defaultOptions: [
+            { onlyWithErrexit: false, allowShebangOnly: false, builtins: [...ALL_BUILTINS] },
+        ],
+        messages: {
+            maskedExitStatus: '`{{builtin}}` returns its own exit status instead of the command substitution’s in the value of `{{name}}`, so neither `set -e` nor `&&` sees the command fail. Assign `{{name}}` in a separate statement from `{{builtin}}`.',
+            declareThenAssign: 'Declare `{{names}}` first and assign it in a separate statement.',
+            assignThenExport: 'Assign `{{names}}` in a separate statement, then export it.',
+            assignThenReadonly: 'Declare and assign `{{names}}` in separate statements, then make it read-only.',
+        },
+    },
+    create(context) {
+        const [options] = context.options;
+        const { sourceCode } = context;
+        const checked = new Set(options.builtins ?? ALL_BUILTINS);
+        const parentOf = (node) => sourceCode.getParent(node);
+        let errexitBefore = new Map();
+        let functionNames = new Set();
+        /**
+         * Whether `errexit` is known to be on when `stmt` runs: the statement is
+         * written directly in a bats `@test` body or hook, or the plain top-level
+         * `set` statements before the top-level statement that contains it leave
+         * it on. A function body is read at its definition.
+         */
+        const errexitIsOn = (stmt) => {
+            if (sourceCode.dialect === 'bats' && batsErrexitIsOn(stmt, parentOf, sourceCode))
+                return true;
+            let topLevel = stmt;
+            for (let up = parentOf(topLevel); up !== undefined && up.type !== 'File'; up = parentOf(up)) {
+                topLevel = up;
+            }
+            return errexitBefore.get(topLevel) === true;
+        };
+        /** Reports each substituted operand of `declaration`, with a suggestion where one is safe. */
+        const check = (node, builtin, declaration, offerSuggestion) => {
+            if (!checked.has(builtin))
+                return;
+            const substituted = declaration.operands.filter((operand) => operand.substituted);
+            if (substituted.length === 0)
+                return;
+            const stmt = sourceCode.getParent(node);
+            if (stmt?.type !== 'Stmt')
+                return;
+            if (options.onlyWithErrexit === true &&
+                !isStatusChecked(stmt, parentOf) &&
+                !errexitIsOn(stmt)) {
+                return;
+            }
+            let suggestion = null;
+            const inFunction = insideFunction(node, sourceCode);
+            // `local` outside a function is an error, which a split would turn into
+            // an assignment of a global.
+            const validHere = builtin !== 'local' || inFunction;
+            if (offerSuggestion && validHere && isStandalone(stmt, sourceCode)) {
+                const text = sourceCode.text;
+                const start = node.range[0];
+                const lineStart = Math.max(text.lastIndexOf('\n', start - 1), text.lastIndexOf('\r', start - 1));
+                const indent = text.slice(lineStart + 1, start);
+                const separator = /^[ \t]*$/u.test(indent) ? lineBreakOf(text) + indent : '; ';
+                const scoped = SCOPED_BUILTINS.has(builtin) && inFunction;
+                suggestion = splitText(declaration, scoped, separator, functionNames, sourceCode);
+            }
+            for (const operand of substituted) {
+                context.report({
+                    node: operand.node,
+                    messageId: 'maskedExitStatus',
+                    data: { builtin, name: operand.name },
+                    suggest: suggestion === null
+                        ? []
+                        : [
+                            {
+                                messageId: suggestion.messageId,
+                                data: { names: substituted.map((s) => s.name).join(' ') },
+                                fix: (fixer) => fixer.replaceTextRange(node.range, suggestion.text),
+                            },
+                        ],
+                });
+            }
+        };
+        return {
+            File(node) {
+                functionNames = collectFunctionNames(node, new Set());
+                if (options.onlyWithErrexit === true) {
+                    errexitBefore = errexitBeforeEachTopLevelStatement(node, sourceCode, options.allowShebangOnly === true);
+                }
+            },
+            DeclClause(node) {
+                const declaration = operandsOfDeclClause(node, sourceCode);
+                check(node, declaration.variant, declaration, true);
+            },
+            CallExpr(node) {
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (invoked?.effective.static !== true)
+                    return;
+                const builtin = invoked.effective.text;
+                if (!ALL_BUILTINS.includes(builtin))
+                    return;
+                const effectiveIndex = invoked.chainIndices.at(-1);
+                if (effectiveIndex === undefined)
+                    return;
+                const declaration = declarationOfWords(builtin, node.args.slice(effectiveIndex + 1), sourceCode);
+                // A suggestion rewrites the whole command, which is only safe to
+                // rebuild when no wrapper precedes the builtin.
+                // Prefix assignments (`A=1 export x=$(c)`) belong to the command the
+                // replacement overwrites, so they too withhold the suggestion.
+                check(node, builtin, declaration, invoked.chain.length === 1 && node.assigns.length === 0);
+            },
+        };
+    },
+});

package/dist/rules/no-secret-env-reads.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The rule's single options object.
+ *
+ * @internal
+ */
+export interface NoSecretEnvReadsOptions {
+    /**
+     * Regex sources tested against each expanded variable's name. Replaces
+     * {@link DEFAULT_PATTERNS} entirely.
+     */
+    readonly patterns?: readonly string[];
+    /**
+     * Command names whose arguments may read a secret-shaped variable. A
+     * command run by path matches by basename.
+     */
+    readonly allowedSinks?: readonly string[];
+}
+/**
+ * The `sh/no-secret-env-reads` rule module, registered as
+ * `no-secret-env-reads`.
+ *
+ * @internal
+ */
+export declare const noSecretEnvReads: import("./define-shell-rule.js").ShellRule<[NoSecretEnvReadsOptions?], "secretEnvRead">;