@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/dist/rules/no-secret-env-reads.js

@@ -0,0 +1,133 @@
+/**
+ * `sh/no-secret-env-reads`: a heuristic screen for reads of secret-shaped
+ * environment variables (`$GITHUB_TOKEN`, `${DB_PASSWORD}`) outside the
+ * commands a project has vetted to receive them.
+ *
+ * Once a secret is expanded into a command's arguments it is visible to every
+ * user on the machine (`ps`, `/proc/<pid>/cmdline`) and tends to end up in
+ * logs and `set -x` traces. The safe pattern is to hand the secret to a child
+ * process through that child's own environment, which expands in the parent
+ * but never appears in argv: `TOKEN=$GITHUB_TOKEN tool`.
+ *
+ * Scope, deliberately narrow:
+ *
+ * - Only reads are inspected: every parameter expansion (`$NAME`, `${NAME…}`)
+ *   whose name matches a pattern. Assignments to such names (`API_KEY=…`)
+ *   are not expansions, so they are never reported.
+ * - An expansion that never yields the value is not a read of the secret: a
+ *   length (`${#NAME}`) expands to a number, and an alternate value
+ *   (`${NAME:+word}`, `${NAME+word}`) expands to `word` or to nothing. Any
+ *   read nested in `word` is its own expansion and is judged on its own.
+ * - A read that appears only inside the value of an assignment prefix of a
+ *   command that runs (`TOKEN=$GITHUB_TOKEN tool`) is the recommended
+ *   pattern and is clean. A read nested deeper (a command substitution in
+ *   that value) belongs to the inner command and is judged there.
+ * - A read in the arguments of an allow-listed sink command is clean. The
+ *   command is the nearest enclosing `CallExpr`, resolved through
+ *   transparent wrappers by `ShellSourceCode#resolveInvokedCommand`.
+ * - Matching is a name pattern, not secret detection.
+ */
+import { AlternateUnset, AlternateUnsetOrNull } from 'sh-ast/analyze';
+import { createRule } from './create-rule.js';
+import { compileUserPattern } from './user-pattern.js';
+/**
+ * The default variable-name patterns, as regex sources. A variable whose name
+ * matches any of them is treated as holding a secret. Taken from the rule
+ * catalog's default for `no-secret-env-reads`. Case-sensitive on purpose:
+ * environment variables are upper-case by convention, and lower-case shell
+ * locals such as `cache_key` are not secrets.
+ */
+const DEFAULT_PATTERNS = ['(_TOKEN|_SECRET|_PASSWORD|_KEY)$'];
+/** The operators of `${NAME+word}` and `${NAME:+word}`, which expand `word`, never the value. */
+const ALTERNATE_OPERATORS = new Set([AlternateUnset, AlternateUnsetOrNull]);
+/**
+ * Whether the expansion `node` can produce the variable's value. A length
+ * (`${#NAME}`) produces a number and an alternate value (`${NAME:+word}`)
+ * produces `word`, so neither exposes the secret in argv, logs or traces.
+ */
+function expandsValue(node) {
+    return !node.length && !ALTERNATE_OPERATORS.has(node.exp?.op);
+}
+/** The final path segment of `command`, so `/usr/bin/vault` matches `vault`. */
+function basename(command) {
+    return command.slice(command.lastIndexOf('/') + 1);
+}
+/**
+ * The `sh/no-secret-env-reads` rule module, registered as
+ * `no-secret-env-reads`.
+ *
+ * @internal
+ */
+export const noSecretEnvReads = createRule({
+    name: 'no-secret-env-reads',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow reading secret-shaped environment variables (`*_TOKEN`, `*_SECRET`, …) outside allowed sink commands',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    patterns: {
+                        type: 'array',
+                        items: { type: 'string', format: 'regex' },
+                        minItems: 1,
+                    },
+                    allowedSinks: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            secretEnvRead: "'{{name}}' looks like a secret, and expanding it here can expose it in `ps` output, logs, and traces. Pass it to the child process through its environment instead (`TOKEN=${{name}} tool`), or read it from stdin or a credential helper.",
+        },
+    },
+    create(context) {
+        const options = context.options[0];
+        const patterns = (options?.patterns ?? DEFAULT_PATTERNS).map((source, index) => compileUserPattern('sh/no-secret-env-reads', `patterns[${String(index)}]`, source, ''));
+        const allowedSinks = new Set(options?.allowedSinks ?? []);
+        const { sourceCode } = context;
+        const isSecretName = (name) => patterns.some((pattern) => pattern.test(name));
+        /** Whether the command that `callExpr` runs, wrappers followed, is an allowed sink. */
+        function isAllowedSink(callExpr) {
+            if (allowedSinks.size === 0)
+                return false;
+            const effective = sourceCode.resolveInvokedCommand(callExpr)?.effective;
+            if (!effective?.static)
+                return false;
+            return allowedSinks.has(effective.text) || allowedSinks.has(basename(effective.text));
+        }
+        /**
+         * Whether the read at `node` is permitted: it sits in the arguments of an
+         * allowed sink, or directly in an assignment prefix of a command that runs.
+         * The nearest enclosing `Assign` or `CallExpr` decides, so a read inside a
+         * command substitution is judged by the inner command, not the outer one.
+         */
+        function isPermittedRead(node) {
+            for (let up = sourceCode.getParent(node); up !== undefined; up = sourceCode.getParent(up)) {
+                if (up.type === 'CallExpr')
+                    return isAllowedSink(up);
+                if (up.type === 'Assign') {
+                    const owner = sourceCode.getParent(up);
+                    return owner?.type === 'CallExpr' && owner.args.length > 0;
+                }
+            }
+            return false;
+        }
+        return {
+            ParamExp(node) {
+                const name = node.param?.value;
+                if (name === undefined || !isSecretName(name))
+                    return;
+                if (!expandsValue(node) || isPermittedRead(node))
+                    return;
+                context.report({ node, messageId: 'secretEnvRead', data: { name } });
+            },
+        };
+    },
+});

package/dist/rules/no-secret-flags.d.ts

@@ -0,0 +1,32 @@
+import type { ShellNode } from '../language/syntax-view.js';
+/**
+ * The rule's single options object.
+ *
+ * @internal
+ */
+export interface NoSecretFlagsOptions {
+    /**
+     * Regex sources tested against each flag's name (the word up to, not
+     * including, its first `=`). Replaces {@link DEFAULT_PATTERNS} entirely.
+     */
+    readonly patterns?: readonly string[];
+}
+/**
+ * One secret-shaped flag found in a command's arguments.
+ *
+ * @internal
+ */
+export interface SecretFlagFinding {
+    /** The flag's name as written, without `=` or value: `--token`. */
+    readonly flag: string;
+    /** The first word of the finding: the flag word. */
+    readonly start: ShellNode;
+    /** The last word of the finding: the flag word itself, or its separate value word. */
+    readonly end: ShellNode;
+}
+/**
+ * The `sh/no-secret-flags` rule module, registered as `no-secret-flags`.
+ *
+ * @internal
+ */
+export declare const noSecretFlags: import("./define-shell-rule.js").ShellRule<[NoSecretFlagsOptions?], "secretFlag">;

package/dist/rules/no-secret-flags.js

@@ -0,0 +1,162 @@
+/**
+ * `sh/no-secret-flags`: a heuristic screen for secrets written as literal
+ * command-line flag values (`--password=hunter2`, `--token abc`).
+ *
+ * A command's argv is readable by every user on the machine (`ps`,
+ * `/proc/<pid>/cmdline`), and a literal value in a script is also committed
+ * with it. The correct pattern is a dynamic value (`--token="$TOKEN"`), or not
+ * passing the secret through argv at all: stdin, a credential helper, or the
+ * child process's environment.
+ *
+ * Scope, deliberately narrow:
+ *
+ * - Only command arguments are inspected: the words of a `CallExpr` after its
+ *   command word. Assignment values (`X="--token=abc"`), heredoc bodies,
+ *   here-strings, redirect targets, and `[[ … ]]` operands are never argv
+ *   words, so they are never matched.
+ * - Whether a word is static is answered only by
+ *   `ShellSourceCode#resolveWordText`. A value is reported only when its
+ *   whole word resolves statically; any expansion, substitution, glob, or
+ *   other dynamic part makes it fine.
+ * - Matching is a name pattern, not secret detection. The default pattern
+ *   stops matching when a letter directly follows the secret word, so
+ *   `--author` is not `--auth`. It also excludes the `-stdin` and `-file`
+ *   suffixes, which name the safe routes the message recommends
+ *   (`--password-stdin`, `--token-file`). Other names that only look secret
+ *   can still match; the `patterns` option replaces the list.
+ */
+import { createRule } from './create-rule.js';
+import { compileUserPattern } from './user-pattern.js';
+/**
+ * The default flag-name patterns, as regex sources. A flag whose name matches
+ * any of them is treated as carrying a secret. Taken from the rule catalog's
+ * default for `no-secret-flags`.
+ *
+ * The one default pattern reads, left to right:
+ *
+ * - `(?!.*-(?:stdin|file)$)`: a name ending in `-stdin` or `-file` never
+ *   matches. Those flags take the secret from stdin or name a file that holds
+ *   it, which are the alternatives the rule recommends, and the word after
+ *   `--password-stdin` is a positional argument, not a value.
+ * - `--?`: one or two leading dashes.
+ * - `(?:access-|auth-?)?`: an optional qualifier, so `--access-token`,
+ *   `--auth-token`, and `--authtoken` match. Other qualifiers stay
+ *   unmatched (`--my-token`), because a general prefix would also catch
+ *   negations such as `--no-password`, which take no value.
+ * - `(?:password|passwd|token|secret|api-?key|auth(?:key|orization)?)`: the
+ *   secret word. `authkey` (`tailscale up --authkey=…`) and `authorization`
+ *   are spelled out because the next part would otherwise reject them.
+ * - `(?![a-z])`: no letter may directly follow the secret word, so a longer
+ *   word that only starts with one (`--author`, `--tokens`, `--tokenizer`)
+ *   does not match. A digit (`--password2`, `--token1`) or a further
+ *   `-segment` (`--secret-key`, `--authorization-token`) still matches.
+ */
+const DEFAULT_PATTERNS = [
+    '^(?!.*-(?:stdin|file)$)--?(?:access-|auth-?)?(?:password|passwd|token|secret|api-?key|auth(?:key|orization)?)(?![a-z])',
+];
+/**
+ * The flags every pattern is compiled with. Case-insensitive, matching the
+ * default pattern's `/i`. No `u` flag: config validation checks each source
+ * with ESLint's JSON-schema `regex` format, which compiles without flags, and
+ * a few sources valid there are syntax errors under `u`. Adding `i` never
+ * turns a valid source into an invalid one, so a pattern that passed
+ * validation always compiles here.
+ */
+const PATTERN_FLAGS = 'i';
+/**
+ * Splits a static argument word into the flag name the patterns are tested
+ * against and the value written in the same word, if any. `--token=abc` is
+ * `{ name: '--token', value: 'abc' }`; `--token` is `{ name: '--token',
+ * value: undefined }`.
+ */
+function splitFlagWord(text) {
+    const eq = text.indexOf('=');
+    return eq === -1 ? { name: text } : { name: text.slice(0, eq), value: text.slice(eq + 1) };
+}
+/**
+ * Whether a static word following a valueless flag is that flag's value. A
+ * word starting with `-` is another flag (or `-`/`--`, the stdin and
+ * end-of-options conventions), and an empty word passes nothing; neither is a
+ * literal secret.
+ */
+function isLiteralValueWord(text) {
+    return text !== '' && !text.startsWith('-');
+}
+/**
+ * The `sh/no-secret-flags` rule module, registered as `no-secret-flags`.
+ *
+ * @internal
+ */
+export const noSecretFlags = createRule({
+    name: 'no-secret-flags',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow secret-shaped command-line flags (`--password=`, `--token`, …) with a literal value',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    patterns: {
+                        type: 'array',
+                        items: { type: 'string', format: 'regex' },
+                        minItems: 1,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            secretFlag: "'{{flag}}' passes a literal value on the command line, where any user can read it with `ps` and it is committed with the script. Read the secret from stdin, use a credential helper, or pass it to the child process through an environment variable instead.",
+        },
+    },
+    create(context) {
+        const sources = context.options[0]?.patterns ?? DEFAULT_PATTERNS;
+        const patterns = sources.map((source, index) => compileUserPattern('sh/no-secret-flags', `patterns[${String(index)}]`, source, PATTERN_FLAGS));
+        const isSecretFlag = (name) => patterns.some((pattern) => pattern.test(name));
+        const { sourceCode } = context;
+        /** Finds every secret-shaped flag with a literal value among `args` (argv, command word first). */
+        function findSecretFlags(args) {
+            const findings = [];
+            // `args[0]` is the command word, not an argument.
+            for (let i = 1; i < args.length; i++) {
+                const word = args.at(i);
+                if (word === undefined)
+                    continue;
+                const text = sourceCode.resolveWordText(word);
+                if (text === null)
+                    continue;
+                const { name, value } = splitFlagWord(text);
+                if (!isSecretFlag(name))
+                    continue;
+                if (value !== undefined) {
+                    // `--flag=value` in one word; an empty value passes nothing.
+                    if (value !== '')
+                        findings.push({ flag: name, start: word, end: word });
+                    continue;
+                }
+                // `--flag value` across two words: the next word is the value when it
+                // is static and not itself a flag.
+                const next = args.at(i + 1);
+                const nextText = next === undefined ? null : sourceCode.resolveWordText(next);
+                if (next !== undefined && nextText !== null && isLiteralValueWord(nextText)) {
+                    findings.push({ flag: name, start: word, end: next });
+                    i++; // the value word is consumed; it is not a flag in its own right
+                }
+            }
+            return findings;
+        }
+        return {
+            CallExpr(node) {
+                for (const { flag, start, end } of findSecretFlags(node.args)) {
+                    context.report({
+                        loc: { start: start.loc.start, end: end.loc.end },
+                        messageId: 'secretFlag',
+                        data: { flag },
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-unchecked-cd.d.ts

@@ -0,0 +1,44 @@
+import type { ShellNode, ShellNodeOf } from '../language/syntax-view.js';
+import type { ShellSourceCode } from '../language/shell-source-code.js';
+/** The rule's single options object. @internal */
+export interface NoUncheckedCdOptions {
+    /**
+     * When `true` (the default), a file whose prologue enables `errexit` is not
+     * checked: the shell already stops at a failed `cd`.
+     */
+    readonly ignoreWhenErrexit?: boolean;
+}
+/** Message ids this rule reports with. @internal */
+export type NoUncheckedCdMessageId = 'uncheckedCd' | 'appendExit';
+/**
+ * Whether the exit status of `stmt` is observed by the construct around it.
+ * Walks outward through the constructs that pass a status along unchanged
+ * (a list's right side, the last command of a group or subshell) and stops at
+ * the first one that tests it or discards it.
+ *
+ * @internal
+ */
+export declare function isStatusChecked(stmt: ShellNodeOf<'Stmt'>, parentOf: (node: ShellNode) => ShellNode | undefined): boolean;
+/**
+ * Whether bats' `errexit` is still in force when `stmt` runs, for a statement
+ * written directly in a bats `@test` body or top-level hook, or directly in a
+ * `( … )` subshell that is itself such a statement. `false` for every other
+ * position, and for a statement `errexit` ignores (negated or in the
+ * background).
+ *
+ * bats starts each test and hook with `errexit` on; the subshell inherits it,
+ * so a failed `cd` ends the subshell with a failing status, which fails the
+ * test. A command substitution `$( … )` is not covered: its failure is masked
+ * by the command it expands in. The state is read by walking the earlier
+ * statements of the same body in order, applying each plain `set` among them
+ * (`set +e`, `set +o errexit`, `set -e`). Only that straight-line reading is
+ * possible: a `set` inside an `if`, loop or function, in a file the test
+ * `load`s, or in the hook that ran before the test, is not seen.
+ *
+ * Callers must have established that the file is a `bats` file.
+ *
+ * @internal
+ */
+export declare function batsErrexitIsOn(stmt: ShellNodeOf<'Stmt'>, parentOf: (node: ShellNode) => ShellNode | undefined, sourceCode: ShellSourceCode): boolean;
+/** Built-in rule `sh/no-unchecked-cd`. @internal */
+export declare const noUncheckedCd: import("./define-shell-rule.js").ShellRule<[NoUncheckedCdOptions], NoUncheckedCdMessageId>;

package/dist/rules/no-unchecked-cd.js

@@ -0,0 +1,250 @@
+/**
+ * `sh/no-unchecked-cd`: a directory change whose failure nothing observes.
+ *
+ * When `cd` fails, the script keeps running in the directory it was already
+ * in, and every relative path after it silently means something else; the
+ * classic result is `cd "$build" && rm -rf *` written without the `&&`. The
+ * same holds for `pushd` and `popd`, which change the directory (and the
+ * directory stack) and fail the same way.
+ *
+ * A directory-changing command is **checked** when its exit status decides
+ * what runs next:
+ *
+ * - it is the left side of `&&` or `||` (`cd x || exit`, `cd x && make`);
+ * - it is the last command of an `if`, `elif`, `while` or `until` condition;
+ * - it is the right side of a list, or the last command of a `{ …; }` group
+ *   or `( … )` subshell, whose own status is checked in one of these ways
+ *   (`a && cd x || exit`, `{ cd x; } || exit`).
+ *
+ * Everything else is reported, including `cd` inside a subshell
+ * (`( cd x; make )`): a subshell keeps the script's directory intact but does
+ * not make the commands after a failed `cd` safe. A negated `! cd x` is only as
+ * checked as the position it sits in. Function bodies, loop bodies, `case`
+ * arms, pipelines and background jobs never check on their own.
+ *
+ * A file whose prologue enables `errexit` (the same reading `require-strict-mode`
+ * uses, via `prologueEnabledOptions`) aborts on a failed `cd` by itself, so the
+ * rule stays quiet there unless `ignoreWhenErrexit` is `false`.
+ *
+ * Under `dialect: "bats"` the bodies of `@test` blocks and of the file's
+ * top-level `setup`, `teardown`, `setup_file` and `teardown_file` functions
+ * run with `errexit` on (bats-core sets it itself), so a bare `cd` directly in
+ * one of them, or directly in a `( … )` subshell that is itself a statement of
+ * one, fails the test and is not reported. It is reported again once the body
+ * has turned `errexit` off with a plain `set +e` (or `set +o errexit`) before
+ * the `cd`, until a later plain `set -e` turns it back on. Any other function,
+ * any statement nested in an `if`, loop or `case`, a `$( … )` substitution, and
+ * any dialect other than `bats` is read as before. `run cd x` is unaffected:
+ * `run` is not a wrapper this rule follows, so the command it sees is `run`,
+ * not `cd`. See `batsErrexitIsOn` for what the rule cannot see.
+ *
+ * The command is recognized as the effective command after transparent
+ * wrappers, so `builtin cd x` and `command cd x` are read as `cd`.
+ *
+ * The suggestion appends ` || exit` to the statement. It is offered only for a
+ * plain statement in a command list: not when the `cd` is already part of an
+ * `&&`/`||`/pipeline (appending would change what the rest of the list does),
+ * negated, in the background, or carrying a here-document (the text after the
+ * statement is the document body, not shell code).
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { createRule } from './create-rule.js';
+import { prologueEnabledOptions, setStatementChanges } from './require-strict-mode.js';
+import { BUILTIN_WRAPPER } from './transparent-wrappers.js';
+/** The commands that change the working directory and can fail doing so. */
+const DIRECTORY_COMMANDS = new Set(['cd', 'pushd', 'popd']);
+/** `BinaryCmd.op` values for `&&` and `||`; the list operators that test a status. */
+const AND_OP = 11;
+const OR_OP = 12;
+/** Wrappers followed to find the command that actually runs (`builtin cd`). */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/**
+ * The functions bats-core runs under `errexit` besides `@test` blocks: its
+ * per-test and per-file hooks.
+ *
+ * @see https://bats-core.readthedocs.io/en/stable/writing-tests.html#setup-and-teardown-pre--and-post-test-hooks
+ */
+const BATS_ERREXIT_HOOKS = new Set([
+    'setup',
+    'teardown',
+    'setup_file',
+    'teardown_file',
+]);
+/**
+ * Whether the exit status of `stmt` is observed by the construct around it.
+ * Walks outward through the constructs that pass a status along unchanged
+ * (a list's right side, the last command of a group or subshell) and stops at
+ * the first one that tests it or discards it.
+ *
+ * @internal
+ */
+export function isStatusChecked(stmt, parentOf) {
+    if (stmt.background)
+        return false;
+    const parent = parentOf(stmt);
+    if (parent === undefined)
+        return false;
+    if (parent.type === 'BinaryCmd') {
+        if (parent.x === stmt)
+            return parent.op === AND_OP || parent.op === OR_OP;
+        // The right side's status is the whole list's status.
+        const listStmt = parentOf(parent);
+        return listStmt?.type === 'Stmt' && isStatusChecked(listStmt, parentOf);
+    }
+    if (parent.type === 'IfClause' || parent.type === 'WhileClause') {
+        return parent.cond.at(-1) === stmt;
+    }
+    if (parent.type === 'Block' || parent.type === 'Subshell') {
+        if (parent.stmts.at(-1) !== stmt)
+            return false;
+        const groupStmt = parentOf(parent);
+        return groupStmt?.type === 'Stmt' && isStatusChecked(groupStmt, parentOf);
+    }
+    return false;
+}
+/**
+ * Whether bats' `errexit` is still in force when `stmt` runs, for a statement
+ * written directly in a bats `@test` body or top-level hook, or directly in a
+ * `( … )` subshell that is itself such a statement. `false` for every other
+ * position, and for a statement `errexit` ignores (negated or in the
+ * background).
+ *
+ * bats starts each test and hook with `errexit` on; the subshell inherits it,
+ * so a failed `cd` ends the subshell with a failing status, which fails the
+ * test. A command substitution `$( … )` is not covered: its failure is masked
+ * by the command it expands in. The state is read by walking the earlier
+ * statements of the same body in order, applying each plain `set` among them
+ * (`set +e`, `set +o errexit`, `set -e`). Only that straight-line reading is
+ * possible: a `set` inside an `if`, loop or function, in a file the test
+ * `load`s, or in the hook that ran before the test, is not seen.
+ *
+ * Callers must have established that the file is a `bats` file.
+ *
+ * @internal
+ */
+export function batsErrexitIsOn(stmt, parentOf, sourceCode) {
+    if (stmt.background || stmt.negated)
+        return false;
+    const container = parentOf(stmt);
+    let siblings;
+    let enabled;
+    if (container?.type === 'Block') {
+        const bodyStmt = parentOf(container);
+        const decl = bodyStmt === undefined ? undefined : parentOf(bodyStmt);
+        if (decl === undefined || !('body' in decl) || decl.body !== bodyStmt)
+            return false;
+        if (decl.type === 'FuncDecl') {
+            const declStmt = parentOf(decl);
+            const name = decl.name?.value;
+            if (name === undefined || !BATS_ERREXIT_HOOKS.has(name))
+                return false;
+            if (declStmt === undefined || parentOf(declStmt)?.type !== 'File')
+                return false;
+        }
+        siblings = container.stmts;
+        enabled = true;
+    }
+    else if (container?.type === 'Subshell') {
+        const subshellStmt = parentOf(container);
+        if (subshellStmt?.type !== 'Stmt' || subshellStmt.cmd !== container)
+            return false;
+        if (!batsErrexitIsOn(subshellStmt, parentOf, sourceCode))
+            return false;
+        siblings = container.stmts;
+        enabled = true;
+    }
+    else {
+        return false;
+    }
+    for (const earlier of siblings) {
+        if (earlier === stmt)
+            break;
+        for (const { option, enable } of setStatementChanges(earlier, sourceCode)) {
+            if (option === 'errexit')
+                enabled = enable;
+        }
+    }
+    return enabled;
+}
+/**
+ * The index just past the command and its redirections, excluding the
+ * statement's trailing separator (`;`, `&`), which `Stmt.range` includes.
+ */
+function commandEnd(stmt) {
+    const parts = [...(stmt.cmd === undefined ? [] : [stmt.cmd]), ...stmt.redirs];
+    return Math.max(...parts.map((part) => part.range[1]));
+}
+/** Built-in rule `sh/no-unchecked-cd`. @internal */
+export const noUncheckedCd = createRule({
+    name: 'no-unchecked-cd',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'require the failure of `cd`, `pushd` and `popd` to be checked, unless the file runs with `set -e`',
+        },
+        hasSuggestions: true,
+        schema: [
+            {
+                type: 'object',
+                properties: { ignoreWhenErrexit: { type: 'boolean' } },
+                additionalProperties: false,
+            },
+        ],
+        defaultOptions: [{ ignoreWhenErrexit: true }],
+        messages: {
+            uncheckedCd: 'If `{{command}}` fails the script keeps running in the wrong directory. Check it, for example `{{command}} … || exit`.',
+            appendExit: 'Append ` || exit` so the script stops if `{{command}}` fails.',
+        },
+    },
+    create(context) {
+        const [options] = context.options;
+        const { sourceCode } = context;
+        let errexitInForce = false;
+        return {
+            File(node) {
+                errexitInForce =
+                    options.ignoreWhenErrexit !== false &&
+                        prologueEnabledOptions(node, sourceCode).has('errexit');
+            },
+            CallExpr(node) {
+                if (errexitInForce)
+                    return;
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (invoked?.effective.static !== true || !DIRECTORY_COMMANDS.has(invoked.effective.text)) {
+                    return;
+                }
+                const command = invoked.effective.text;
+                const stmt = sourceCode.getParent(node);
+                if (stmt?.type !== 'Stmt')
+                    return;
+                const parentOf = (n) => sourceCode.getParent(n);
+                if (isStatusChecked(stmt, parentOf))
+                    return;
+                if (sourceCode.dialect === 'bats' && batsErrexitIsOn(stmt, parentOf, sourceCode))
+                    return;
+                const container = parentOf(stmt);
+                const hasHeredoc = stmt.redirs.some((r) => r.hdoc !== undefined);
+                const canAppend = !stmt.background && !stmt.negated && !hasHeredoc && container?.type !== 'BinaryCmd';
+                context.report({
+                    node,
+                    messageId: 'uncheckedCd',
+                    data: { command },
+                    suggest: canAppend
+                        ? [
+                            {
+                                messageId: 'appendExit',
+                                data: { command },
+                                fix: (fixer) => fixer.insertTextAfterRange([0, commandEnd(stmt)], ' || exit'),
+                            },
+                        ]
+                        : [],
+                });
+            },
+        };
+    },
+});

package/dist/rules/no-undeclared-commands.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The rule's single options object.
+ *
+ * @internal
+ */
+export interface NoUndeclaredCommandsOptions {
+    /**
+     * Names of project-specific transparent wrappers (`with-retry`), added to
+     * the default wrapper table (see `harvestWrapperTable`). The word after a listed
+     * wrapper is the command it runs, so `with-retry curl` uses `curl` as well
+     * as `with-retry`.
+     */
+    readonly transparentWrappers?: readonly string[];
+}
+/**
+ * The `sh/no-undeclared-commands` rule module.
+ *
+ * @internal
+ */
+export declare const noUndeclaredCommands: import("./define-shell-rule.js").ShellRule<[NoUndeclaredCommandsOptions?], "undeclaredCommand">;