@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/dist/rules/no-undeclared-commands.js

@@ -0,0 +1,115 @@
+/**
+ * `sh/no-undeclared-commands`: reports external commands a script uses but
+ * does not declare.
+ *
+ * A script silently depends on every external command it runs, and any of
+ * them may be missing on the machine it lands on. When a project states a
+ * script's dependencies up front, this rule keeps that statement complete.
+ *
+ * The rule splits the question in two:
+ *
+ * - **Usage** is a fact about the syntax tree, computed by the internal
+ *   command harvest (`../command-harvest/harvest-commands.ts`): every static
+ *   command name, minus the dialect's builtins and the file's own functions,
+ *   following transparent wrappers.
+ * - **Declaration** is project policy, answered by the consumer's
+ *   `DeclarationConvention`, bound in `settings.sh.declarationConvention`
+ *   and resolved with `resolveDeclarationConvention`. With no convention
+ *   bound the rule is inert: shipping a default would impose one project's
+ *   declaration syntax on every project.
+ *
+ * The convention is bound through settings only. The rule has no
+ * `declarationConvention` option, because ESLint copies rule options with
+ * `structuredClone`, which cannot carry a convention's methods.
+ *
+ * Each undeclared command reports once, at the word naming it in its first
+ * use. The rule offers no fix: adding a dependency is a decision for the
+ * author. The report instead says how to declare the command, in the
+ * convention's own words when it has a `declarationHint` hook, since only the
+ * convention knows its syntax.
+ */
+import { harvestCommands } from '../command-harvest/harvest-commands.js';
+import { harvestWrapperTable } from '../command-harvest/wrapper-table.js';
+import { createRule } from './create-rule.js';
+import { readDeclaredCommands, toLintedFile, } from '../declaration-conventions/read-declared-commands.js';
+import { resolveDeclarationConvention } from './resolve-declaration-convention.js';
+import { networkWrapperSpec } from './resolve-network-wrapper.js';
+/** The registry name of this rule (`sh/no-undeclared-commands` in a user's config). */
+const RULE_NAME = 'no-undeclared-commands';
+/** The report's second sentence when the convention offers no hint for a command. */
+const GENERIC_HINT = "Declare it with the project's declaration convention.";
+/**
+ * The convention's hint for `command`, or {@link GENERIC_HINT} when it has
+ * none. Throws when the hook returns something other than `null` or a
+ * non-empty single-line string, so a broken hook surfaces as a readable
+ * configuration error instead of a garbled report.
+ */
+function howToDeclare(convention, command, sourceCode, file) {
+    if (convention.declarationHint === undefined)
+        return GENERIC_HINT;
+    const hint = convention.declarationHint(command, sourceCode, file);
+    if (hint === null)
+        return GENERIC_HINT;
+    if (typeof hint !== 'string' || hint.trim() === '' || /[\r\n\u2028\u2029]/u.test(hint)) {
+        throw new Error(`Invalid settings.sh.declarationConvention: \`declarationHint\` must return null or a non-empty single-line string, but returned ${typeof hint === 'string' ? JSON.stringify(hint) : typeof hint} for ${JSON.stringify(command)}.`);
+    }
+    return hint;
+}
+/**
+ * The `sh/no-undeclared-commands` rule module.
+ *
+ * @internal
+ */
+export const noUndeclaredCommands = createRule({
+    name: RULE_NAME,
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require every external command a script uses to be declared by the configured declaration convention',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    transparentWrappers: {
+                        type: 'array',
+                        items: { type: 'string', minLength: 1 },
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            undeclaredCommand: "'{{command}}' is used but not declared. {{howToDeclare}}",
+        },
+    },
+    create(context) {
+        const convention = resolveDeclarationConvention(context);
+        if (convention === null) {
+            return {};
+        }
+        const { sourceCode } = context;
+        const transparentWrappers = harvestWrapperTable(sourceCode.dialect, context.options[0]?.transparentWrappers ?? [], networkWrapperSpec(context.settings));
+        return {
+            File() {
+                // Only names matter here, so every kind of declaration counts the same.
+                const declared = new Set(readDeclaredCommands(convention, context).map(({ name }) => name));
+                for (const { name, node } of harvestCommands(sourceCode, {
+                    transparentWrappers,
+                }).values()) {
+                    if (declared.has(name))
+                        continue;
+                    context.report({
+                        node,
+                        messageId: 'undeclaredCommand',
+                        data: {
+                            command: name,
+                            howToDeclare: howToDeclare(convention, name, sourceCode, toLintedFile(context)),
+                        },
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-unused-declarations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The rule's single options object. It mirrors `no-undeclared-commands`'
+ * options, so a project configures both rules with the same wrappers and
+ * they compute the same usage.
+ *
+ * @internal
+ */
+export interface NoUnusedDeclarationsOptions {
+    /**
+     * 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`, and `with-retry "$tool"` runs a command the
+     * file cannot name.
+     */
+    readonly transparentWrappers?: readonly string[];
+}
+/**
+ * The `sh/no-unused-declarations` rule module.
+ *
+ * @internal
+ */
+export declare const noUnusedDeclarations: import("./define-shell-rule.js").ShellRule<[NoUnusedDeclarationsOptions?], "unusedDeclaration" | "unusedFileDeclaration" | "unusedDescribedDeclaration">;

package/dist/rules/no-unused-declarations.js

@@ -0,0 +1,259 @@
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { harvestCommands } from '../command-harvest/harvest-commands.js';
+import { harvestWrapperTable } from '../command-harvest/wrapper-table.js';
+import { createRule } from './create-rule.js';
+import { readDeclaredCommands } from '../declaration-conventions/read-declared-commands.js';
+import { resolveDeclarationConvention } from './resolve-declaration-convention.js';
+import { networkWrapperSpec } from './resolve-network-wrapper.js';
+import { SHELL_WRAPPER } from './transparent-wrappers.js';
+/** The registry name of this rule (`sh/no-unused-declarations` in a user's config). */
+const RULE_NAME = 'no-unused-declarations';
+/**
+ * A shell name (`cleanup`, `_on_exit`): the form of a `trap` action that
+ * names a single function or command rather than a code string.
+ *
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_235 — Name
+ */
+const SHELL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/** A `trap` option cluster that lists or prints traps instead of setting one (`-l`, `-p`, `-P`). */
+const TRAP_PRINT_OPTIONS = /^-[lpP]+$/u;
+/** A decimal integer: as `trap`'s first operand, it makes every operand a condition to reset. */
+const UNSIGNED_INTEGER = /^[0-9]+$/u;
+/**
+ * Whether `trap`'s `operands` (the words after `trap`) set an action that is a
+ * code string, which the shell evaluates later and this rule cannot read.
+ *
+ * Not a code string: no action at all (`trap`, `trap -p`, `trap -l`); the
+ * reset action `-` and the ignore action `''`; a leading integer, which POSIX
+ * treats as a condition to reset; and a plain name (`trap cleanup EXIT`),
+ * which runs that function or command. A name used as an action is an
+ * argument word, so it already counts as used. An action that is not static
+ * is a code string the rule cannot know.
+ *
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#trap
+ * @see https://www.gnu.org/software/bash/manual/bash.html#index-trap
+ */
+function trapSetsCodeString(operands) {
+    let index = 0;
+    if (operands.length > 0 && operands[0].static) {
+        const { text } = operands[0];
+        if (TRAP_PRINT_OPTIONS.test(text))
+            return false;
+        if (text === '--')
+            index = 1;
+    }
+    if (index >= operands.length)
+        return false;
+    const action = operands[index];
+    if (!action.static)
+        return true;
+    const { text } = action;
+    return !(text === '' || text === '-' || UNSIGNED_INTEGER.test(text) || SHELL_NAME.test(text));
+}
+/** Shell names, from {@link SHELL_WRAPPER}: a shell with no script operand reads code from stdin. */
+const SHELL_NAMES = new Set(SHELL_WRAPPER.names);
+/** The builtins that run another file's code in this shell: POSIX `.` and Bash's `source`. */
+const SOURCE_COMMANDS = new Set(['.', 'source']);
+/**
+ * The wrappers whose path forms (`/bin/bash`, `/usr/bin/env`) the completeness
+ * check also follows, by basename: shells invoked as commands and `env`,
+ * the wrappers that can run an embedded command string. sh-ast matches
+ * wrapper names exactly, so without this `/bin/bash -c '…'` would resolve to
+ * the static command `/bin/bash`.
+ */
+const PATH_FOLLOWED_WRAPPERS = [
+    SHELL_WRAPPER,
+    ...DEFAULT_TRANSPARENT_WRAPPERS.filter((spec) => spec.names.includes('env')),
+];
+/** The basename of `text` when it is a path (contains a slash), else `null`. */
+function pathBasename(text) {
+    const slash = text.lastIndexOf('/');
+    return slash === -1 ? null : text.slice(slash + 1);
+}
+/**
+ * The effective command of `site` under `table`, also following a shell or
+ * `env` named by path: while the effective command is a path whose basename
+ * names one of {@link PATH_FOLLOWED_WRAPPERS}, that path is added as a
+ * wrapper with the same spec and the site is resolved again. This mirrors how
+ * `createWrapperRule` follows path-named wrappers. Each round adds a new
+ * path, and a site has finitely many words, so the loop ends.
+ */
+function resolveEffective(site, table) {
+    let current = table;
+    for (;;) {
+        const resolution = site.resolveInvokedCommand({ transparentWrappers: current });
+        const { effective } = resolution;
+        if (!effective.static)
+            return resolution;
+        const path = effective.text;
+        const base = pathBasename(path);
+        if (base === null || current.some((spec) => spec.names.includes(path)))
+            return resolution;
+        const spec = PATH_FOLLOWED_WRAPPERS.find((entry) => entry.names.includes(base));
+        if (spec === undefined)
+            return resolution;
+        current = [{ ...spec, names: [path] }, ...current];
+    }
+}
+/** A short-option cluster that includes `c` (`-c`, `-ec`, `-xc`): a shell's command-string flag. */
+const COMMAND_STRING_CLUSTER = /^-[A-Za-z]*c[A-Za-z]*$/u;
+/**
+ * Whether `argv` names a shell as an argument and later passes it a command
+ * string: some word after argv0 is statically a shell name, by name or by
+ * basename (`sh`, `/bin/bash`), and a later word is a short-option cluster
+ * containing `c`. Many commands run their arguments as a command line
+ * (`xargs sh -c '…'`, `find . -exec sh -c '…' \;`, `setsid -f bash -c …`,
+ * `busybox sh -c …`), and they are not wrappers this rule follows, so the
+ * shell never becomes the effective command. Matching the words directly
+ * catches them without modeling each command's options.
+ */
+function passesShellCommandString(argv) {
+    const shellIndex = argv.findIndex((word, index) => index > 0 && word.static && SHELL_NAMES.has(pathBasename(word.text) ?? word.text));
+    return (shellIndex !== -1 &&
+        argv.slice(shellIndex + 1).some((word) => word.static && COMMAND_STRING_CLUSTER.test(word.text)));
+}
+/**
+ * Whether `site` may run code that cannot be read from the source:
+ *
+ * - its effective command is not static, including an embedded command
+ *   string;
+ * - it is `eval`;
+ * - it is a `trap` that sets a code string;
+ * - it is `.` or `source` with an operand, which runs another file;
+ * - it is a shell, by name or path, that is the effective command itself.
+ *   With {@link SHELL_WRAPPER} followed, a script operand would be the
+ *   effective command and `-c` would be an embedded command, so a shell that
+ *   is still the effective command reads its code from standard input
+ *   (`curl x | bash`, `bash < script`, `bash -s`);
+ * - it hands a command string to a shell named in its arguments (see
+ *   {@link passesShellCommandString}).
+ *
+ * `completenessWrappers` is the table to follow (see the rule's `create`).
+ */
+function runsUnknownCode(site, completenessWrappers) {
+    if (passesShellCommandString(site.argv))
+        return true;
+    const resolution = resolveEffective(site, completenessWrappers);
+    const { effective, chainIndices } = resolution;
+    if (!effective.static)
+        return true;
+    const { text } = effective;
+    if (text === 'eval')
+        return true;
+    if (SHELL_NAMES.has(pathBasename(text) ?? text))
+        return true;
+    if (!SOURCE_COMMANDS.has(text) && text !== 'trap')
+        return false;
+    // `chainIndices` locates the effective command in argv; its operands follow it.
+    const effectiveIndex = chainIndices.at(-1);
+    const operands = effectiveIndex === undefined ? [] : site.argv.slice(effectiveIndex + 1);
+    return text === 'trap' ? trapSetsCodeString(operands) : operands.length > 0;
+}
+/** `text`, and also its basename when `text` is a path (contains a slash). */
+function namesFor(text) {
+    const base = pathBasename(text);
+    return base === null ? [text] : [text, base];
+}
+/**
+ * How a report names where an out-of-script declaration lives: `path:line`
+ * (or `path` when the line is unknown) for a file, the description for a
+ * described source.
+ */
+function sourceText(declared) {
+    if (declared.kind === 'described')
+        return declared.description;
+    return declared.line === undefined ? declared.path : `${declared.path}:${String(declared.line)}`;
+}
+/**
+ * The `sh/no-unused-declarations` rule module.
+ *
+ * @internal
+ */
+export const noUnusedDeclarations = createRule({
+    name: RULE_NAME,
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow declaring external commands that a script never uses, per the configured declaration convention',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    transparentWrappers: {
+                        type: 'array',
+                        items: { type: 'string', minLength: 1 },
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            unusedDeclaration: "'{{command}}' is declared but never used. Remove the declaration so the script's stated dependencies match what it runs.",
+            unusedFileDeclaration: "'{{command}}' is declared in {{source}} but this script never uses it. Remove it there so the script's stated dependencies match what it runs.",
+            unusedDescribedDeclaration: "'{{command}}' is declared in {{source}} but this script never uses it. Remove it there so the script's stated dependencies match what it runs.",
+        },
+    },
+    create(context) {
+        const convention = resolveDeclarationConvention(context);
+        if (convention === null) {
+            return {};
+        }
+        const { sourceCode } = context;
+        const transparentWrappers = harvestWrapperTable(sourceCode.dialect, context.options[0]?.transparentWrappers ?? [], networkWrapperSpec(context.settings));
+        // The completeness check follows the harvest's table plus shells
+        // invoked as commands, so `bash -c '…'` and `sh -c '…'` resolve to an
+        // embedded command (as in `no-dynamic-invocation`) instead of stopping
+        // at the shell. `env -S` is already embedded in the defaults. Path
+        // forms (`/bin/bash`, `/usr/bin/env`) are followed per site by
+        // `resolveEffective`.
+        const completenessWrappers = [...transparentWrappers, SHELL_WRAPPER];
+        // Bound once so the hook keeps its convention as `this`, however it is written.
+        const removeDeclaration = convention.removeDeclaration?.bind(convention);
+        return {
+            File() {
+                const sites = sourceCode.getCommandSites();
+                if (sites.some((site) => runsUnknownCode(site, completenessWrappers)))
+                    return;
+                const used = new Set();
+                for (const name of harvestCommands(sourceCode, { transparentWrappers }).keys()) {
+                    for (const each of namesFor(name))
+                        used.add(each);
+                }
+                for (const site of sites) {
+                    for (const word of site.argv.slice(1)) {
+                        if (word.static)
+                            for (const each of namesFor(word.text))
+                                used.add(each);
+                    }
+                }
+                for (const declared of readDeclaredCommands(convention, context)) {
+                    if (used.has(declared.name))
+                        continue;
+                    if (declared.kind === 'script') {
+                        context.report({
+                            loc: {
+                                start: sourceCode.getLocFromIndex(declared.range[0]),
+                                end: sourceCode.getLocFromIndex(declared.range[1]),
+                            },
+                            messageId: 'unusedDeclaration',
+                            data: { command: declared.name },
+                            fix: removeDeclaration
+                                ? (fixer) => removeDeclaration(sourceCode, declared, fixer)
+                                : null,
+                        });
+                        continue;
+                    }
+                    context.report({
+                        // A start with no end: the file as a whole, not any text in it.
+                        loc: sourceCode.getLocFromIndex(0),
+                        messageId: declared.kind === 'file' ? 'unusedFileDeclaration' : 'unusedDescribedDeclaration',
+                        data: { command: declared.name, source: sourceText(declared) },
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/prefer-local.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The rule's single options object.
+ *
+ * @internal
+ */
+export interface PreferLocalOptions {
+    /** Variable names that may be assigned in a function without `local`. */
+    readonly allow?: readonly string[];
+    /**
+     * A regular expression (source text, matched with the `u` flag); a name that
+     * matches it may be assigned without `local`. Defaults to UPPER_CASE names.
+     */
+    readonly allowPattern?: string;
+}
+/** Built-in rule `sh/prefer-local`. @internal */
+export declare const preferLocal: import("./define-shell-rule.js").ShellRule<[PreferLocalOptions], "preferLocal">;

package/dist/rules/prefer-local.js

@@ -0,0 +1,249 @@
+import { childNodes, walkShell } from '../language/syntax-view.js';
+import { createRule } from './create-rule.js';
+import { compileUserPattern } from './user-pattern.js';
+import { lineBreakOf } from '../language/line-breaks.js';
+/** The `allowPattern` used when none is configured: UPPER_CASE globals. */
+const DEFAULT_ALLOW_PATTERN = '^[A-Z][A-Z0-9_]*$';
+/** A valid shell variable name; anything else is not a binding target. */
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/** Declaration builtins whose names are function-scoped unless `-g` is given. */
+const SCOPED_DECLARATIONS = new Set(['local', 'declare', 'typeset']);
+/** `read` options that consume an argument that is not a variable name. */
+const READ_OPTIONS_WITH_ARGUMENT = new Set([
+    'p',
+    'd',
+    'n',
+    'N',
+    't',
+    'u',
+    'i',
+]);
+/**
+ * The variables a `read` command assigns, skipping its options. Option
+ * clusters follow `read`'s own parsing: a letter that takes an argument uses
+ * the rest of the cluster, or else the next word. `-a`'s array name is an
+ * ordinary target word. Words that are not static are not guessed at.
+ */
+function readTargets(args, sourceCode) {
+    const targets = [];
+    let optionsEnded = false;
+    let nextIsOptionArgument = false;
+    for (const word of args.slice(1)) {
+        const text = sourceCode.resolveWordText(word);
+        if (nextIsOptionArgument) {
+            nextIsOptionArgument = false;
+            continue;
+        }
+        if (text === null)
+            continue;
+        if (!optionsEnded && text === '--') {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && text.startsWith('-') && text.length > 1) {
+            for (let index = 1; index < text.length; index += 1) {
+                const letter = text.charAt(index);
+                if (READ_OPTIONS_WITH_ARGUMENT.has(letter)) {
+                    nextIsOptionArgument = index === text.length - 1;
+                    break;
+                }
+            }
+            continue;
+        }
+        if (VARIABLE_NAME.test(text))
+            targets.push({ name: text, kind: 'assign', node: word });
+    }
+    return targets;
+}
+/**
+ * The variables `node` assigns or declares, itself only (not its children).
+ * `declare`/`typeset` with a `-g` flag, and every non-scoped declaration
+ * (`export`, `readonly`), bind their names as intentional globals.
+ */
+function bindingsOf(node, sourceCode) {
+    if (node.type === 'ForClause') {
+        const { loop } = node;
+        if (loop?.type !== 'WordIter' || loop.name === undefined)
+            return [];
+        return [{ name: loop.name.value, kind: 'assign', node: loop.name }];
+    }
+    if (node.type === 'CallExpr') {
+        if (node.args.length === 0) {
+            return node.assigns.flatMap((assign) => assign.name === undefined
+                ? []
+                : [{ name: assign.name.value, kind: 'assign', node: assign }]);
+        }
+        return sourceCode.getCommandName(node) === 'read' ? readTargets(node.args, sourceCode) : [];
+    }
+    if (node.type === 'DeclClause') {
+        const variant = node.variant?.value;
+        const flags = node.args
+            .filter((arg) => arg.naked && arg.name === undefined && arg.value !== undefined)
+            .map((arg) => (arg.value === undefined ? null : sourceCode.resolveWordText(arg.value)));
+        const isGlobal = variant === undefined ||
+            !SCOPED_DECLARATIONS.has(variant) ||
+            flags.some((flag) => flag !== null && /^-[A-Za-z]*g/u.test(flag));
+        return node.args.flatMap((arg) => arg.name === undefined
+            ? []
+            : [
+                {
+                    name: arg.name.value,
+                    kind: isGlobal ? 'global' : 'local',
+                    node: arg,
+                },
+            ]);
+    }
+    return [];
+}
+/** Node types whose contents run in a child process and cannot leak assignments. */
+const ISOLATED_SCOPES = new Set(['Subshell', 'CmdSubst', 'ProcSubst']);
+/** `BinaryCmd.op` values for `|` and `|&`, the pipeline operators. */
+const PIPE_OPS = new Set([13, 14]);
+/**
+ * Whether the file enables `shopt -s lastpipe`. With it, the last element of a
+ * pipeline runs in the current shell, so what that element assigns does leak.
+ * The option is read file-wide, wherever the `shopt` appears, because it
+ * applies to every pipeline that runs after it.
+ */
+function enablesLastpipe(root, sourceCode) {
+    let enabled = false;
+    walkShell(root, (node) => {
+        if (node.type !== 'CallExpr' || sourceCode.getCommandName(node) !== 'shopt')
+            return;
+        const words = node.args.slice(1).map((word) => sourceCode.resolveWordText(word));
+        if (words.includes('-s') && words.includes('lastpipe'))
+            enabled = true;
+    });
+    return enabled;
+}
+/**
+ * Every binding in `root`'s own scope, in source order. Nested function
+ * definitions and isolated scopes (subshells, substitutions) are not entered.
+ * Pipeline elements run in subshells, so only the last element of a pipeline
+ * is entered, and only when `lastpipe` is enabled.
+ */
+function scopeBindings(root, sourceCode, lastpipe) {
+    const found = [];
+    const visit = (node) => {
+        if (node.type === 'FuncDecl' || ISOLATED_SCOPES.has(node.type))
+            return;
+        if (node.type === 'BinaryCmd' && PIPE_OPS.has(node.op)) {
+            if (lastpipe && node.y !== undefined)
+                visit(node.y);
+            return;
+        }
+        found.push(...bindingsOf(node, sourceCode));
+        for (const child of childNodes(node))
+            visit(child);
+    };
+    visit(root);
+    return found.sort((a, b) => a.node.range[0] - b.node.range[0]);
+}
+/** Built-in rule `sh/prefer-local`. @internal */
+export const preferLocal = createRule({
+    name: 'prefer-local',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'require variables assigned inside a function to be declared `local`, unless intentionally global',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allow: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+                    allowPattern: { type: 'string' },
+                },
+                additionalProperties: false,
+            },
+        ],
+        defaultOptions: [{ allow: [], allowPattern: DEFAULT_ALLOW_PATTERN }],
+        messages: {
+            preferLocal: '`{{name}}` is assigned in function `{{function}}` without being declared `local`, so it leaks into the global scope. Declare it with `local {{name}}`.',
+        },
+    },
+    create(context) {
+        const { sourceCode } = context;
+        // `local` is not POSIX: under `posix` there is nothing to declare with.
+        if (sourceCode.dialect === 'posix')
+            return {};
+        const [options] = context.options;
+        const allowed = new Set(options.allow ?? []);
+        const allowPattern = compileUserPattern('sh/prefer-local', 'allowPattern', options.allowPattern ?? DEFAULT_ALLOW_PATTERN, 'u');
+        const text = sourceCode.text;
+        const lastpipe = enablesLastpipe(sourceCode.ast, sourceCode);
+        // Names assigned or declared outside every function, with where each
+        // binding ends: assigned before a function is defined, they are globals
+        // the function is meant to share.
+        const topLevelBindings = [];
+        let topLevelCollected = false;
+        const topLevelBefore = (position) => {
+            if (!topLevelCollected) {
+                topLevelBindings.push(...scopeBindings(sourceCode.ast, sourceCode, lastpipe));
+                topLevelCollected = true;
+            }
+            return new Set(topLevelBindings.filter((b) => b.node.range[1] <= position).map((b) => b.name));
+        };
+        /**
+         * The one `local` declaration that covers `names`, as `[index, text]`, or
+         * `null` when the function has no `{ … }` block with a first statement to
+         * insert before. Every report of a function carries this same insertion
+         * (with the function's whole name list), because fixes that insert at one
+         * offset conflict: ESLint applies one per pass and stops after 10, so a
+         * function with more than 10 names would otherwise never settle.
+         */
+        const insertionFor = (func, names) => {
+            const block = func.body?.cmd;
+            if (block?.type !== 'Block')
+                return null;
+            const first = block.stmts.at(0);
+            if (first === undefined)
+                return null;
+            const lineStart = Math.max(text.lastIndexOf('\n', first.range[0] - 1), text.lastIndexOf('\r', first.range[0] - 1));
+            const indent = text.slice(lineStart + 1, first.range[0]);
+            const separator = /^[ \t]*$/u.test(indent) ? lineBreakOf(text) + indent : '; ';
+            return [first.range[0], `local ${names.join(' ')}${separator}`];
+        };
+        return {
+            FuncDecl(func) {
+                const { body } = func;
+                if (body === undefined || body.cmd?.type === 'Subshell')
+                    return;
+                const global = topLevelBefore(func.range[0]);
+                const declared = new Set();
+                const functionName = func.name?.value ?? '';
+                const leaks = [];
+                for (const binding of scopeBindings(body, sourceCode, lastpipe)) {
+                    const { name } = binding;
+                    if (binding.kind !== 'assign') {
+                        declared.add(name);
+                        continue;
+                    }
+                    if (declared.has(name) ||
+                        global.has(name) ||
+                        allowed.has(name) ||
+                        allowPattern.test(name)) {
+                        continue;
+                    }
+                    declared.add(name);
+                    leaks.push(binding);
+                }
+                if (leaks.length === 0)
+                    return;
+                const insertion = insertionFor(func, leaks.map((binding) => binding.name));
+                for (const binding of leaks) {
+                    const { name } = binding;
+                    context.report({
+                        node: binding.node,
+                        messageId: 'preferLocal',
+                        data: { name, function: functionName },
+                        fix: insertion === null
+                            ? null
+                            : (fixer) => fixer.insertTextBeforeRange([insertion[0], insertion[0]], insertion[1]),
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/quote-expansions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Message ids this rule reports with: `unquotedExpansion` for the problem,
+ * `wrapInQuotes` for its suggestion.
+ *
+ * @internal
+ */
+export type QuoteExpansionsMessageId = 'unquotedExpansion' | 'wrapInQuotes';
+/**
+ * The `sh/quote-expansions` rule module.
+ *
+ * @internal
+ */
+export declare const quoteExpansions: import("./define-shell-rule.js").ShellRule<[], QuoteExpansionsMessageId>;