@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/dist/command-harvest/builtins/posix.js

@@ -0,0 +1,93 @@
+/**
+ * The commands a POSIX `sh` runs as builtins: data for the command harvest,
+ * never rule logic.
+ *
+ * Three groups, each from its own source (POSIX.1-2017, XCU Issue 7, whose
+ * section numbers are used here):
+ *
+ * - **Special built-ins**, XCU §2.14 "Special Built-In Utilities": `break`,
+ *   `:`, `continue`, `.`, `eval`, `exec`, `exit`, `export`, `readonly`,
+ *   `return`, `set`, `shift`, `times`, `trap`, `unset`.
+ * - **Regular built-ins**, XCU §2.9.1.1 "Command Search and Execution",
+ *   step 1.d: the utilities a shell must invoke before searching `PATH`
+ *   (`alias`, `bg`, `cd`, `command`, `false`, `fc`, `fg`, `getopts`, `hash`,
+ *   `jobs`, `kill`, `newgrp`, `pwd`, `read`, `true`, `umask`, `unalias`,
+ *   `wait`), plus `type` and `ulimit`, which the same step lists under the
+ *   XSI option. POSIX.1-2024 (Issue 8) calls most of these "intrinsic
+ *   utilities" (XCU §1.7).
+ * - **Built in by every POSIX shell in practice**: `echo`, `printf`, `test`
+ *   and `[`. POSIX specifies them as ordinary utilities that a shell may
+ *   build in (XCU §1.6), and dash, ash, ksh, mksh and bash all do (see the
+ *   "Builtins" section of dash(1)). Counting them as external would make
+ *   nearly every script declare `echo`.
+ *
+ * Bash-only builtins such as `local`, `source` and `mapfile` are
+ * deliberately absent: in a `posix` file they are commands that a POSIX
+ * shell need not provide.
+ *
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_14 — XCU §2.14 Special Built-In Utilities
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_09_01_01 — XCU §2.9.1.1 Command Search and Execution
+ * @see https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap01.html — POSIX.1-2024 XCU §1.7 Intrinsic Utilities
+ * @see https://man7.org/linux/man-pages/man1/dash.1.html — dash(1), "Builtins"
+ */
+/**
+ * POSIX special built-in utilities (XCU §2.14).
+ *
+ * @internal
+ */
+export const POSIX_SPECIAL_BUILTINS = Object.freeze([
+    'break',
+    ':',
+    'continue',
+    '.',
+    'eval',
+    'exec',
+    'exit',
+    'export',
+    'readonly',
+    'return',
+    'set',
+    'shift',
+    'times',
+    'trap',
+    'unset',
+]);
+/**
+ * POSIX regular built-in utilities (XCU §2.9.1.1 step 1.d, including the
+ * XSI `type` and `ulimit`).
+ *
+ * @internal
+ */
+export const POSIX_REGULAR_BUILTINS = Object.freeze([
+    'alias',
+    'bg',
+    'cd',
+    'command',
+    'false',
+    'fc',
+    'fg',
+    'getopts',
+    'hash',
+    'jobs',
+    'kill',
+    'newgrp',
+    'pwd',
+    'read',
+    'true',
+    'type',
+    'ulimit',
+    'umask',
+    'unalias',
+    'wait',
+]);
+/**
+ * Utilities POSIX lets a shell build in, and every POSIX shell does.
+ *
+ * @internal
+ */
+export const POSIX_CONVENTIONAL_BUILTINS = Object.freeze([
+    'echo',
+    'printf',
+    'test',
+    '[',
+]);

package/dist/command-harvest/harvest-commands.d.ts

@@ -0,0 +1,66 @@
+import type { WrapperSpec } from 'sh-ast/analyze';
+import type { ShellCommandSite } from '../language/command-resolution.js';
+import type { ShellSourceCode } from '../language/shell-source-code.js';
+import type { ShellNode } from '../language/syntax-view.js';
+/**
+ * Options for {@link harvestCommands}.
+ *
+ * @internal
+ */
+export interface HarvestCommandsOptions {
+    /**
+     * The transparent-wrapper table to follow, forwarded to
+     * `resolveInvokedCommand` unchanged. It **replaces** `sh-ast/analyze`'s
+     * `DEFAULT_TRANSPARENT_WRAPPERS` (spread the defaults in to extend them).
+     * Defaults to `DEFAULT_TRANSPARENT_WRAPPERS`.
+     */
+    readonly transparentWrappers?: readonly WrapperSpec[];
+}
+/**
+ * The first use of one external command in a file.
+ *
+ * @internal
+ */
+export interface HarvestedCommand {
+    /** The command name, exactly as the shell would look it up (`jq`, `./build.sh`). */
+    readonly name: string;
+    /**
+     * The `Word` node that names the command at its first use: the command
+     * word itself, or for a wrapped command the word after the wrapper
+     * (`curl` in `sudo curl x`). Falls back to the whole `CallExpr` in the
+     * unexpected case that the word cannot be located.
+     */
+    readonly node: ShellNode;
+    /** The command site of that first use. */
+    readonly site: ShellCommandSite;
+}
+/**
+ * The names of every function the file defines, anywhere in it (top level,
+ * nested in another function, inside a conditional, …). Position is not read,
+ * so this answers "could this name be a function", not "is it one at this
+ * call": a call in a function body usually runs after a later definition, but a
+ * top-level call before the definition does not run it. zsh's
+ * `function a b { … }` defines every listed name.
+ *
+ * @internal
+ */
+export declare function definedFunctionNames(sourceCode: ShellSourceCode): ReadonlySet<string>;
+/**
+ * Returns every external command `sourceCode` runs, keyed by name, each with
+ * its first use. The map iterates in first-use (source) order.
+ *
+ * A command is every static word in an invocation's wrapper chain (the
+ * wrappers and the effective command), excluding:
+ *
+ * - dynamic words, which name no knowable command;
+ * - builtins of the file's dialect (`sourceCode.dialect`);
+ * - functions the file defines anywhere.
+ *
+ * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when the file's
+ * nesting exceeds analysis's recursion guard: a partial harvest would miss
+ * real commands.
+ * @throws `ShAnalyzeInvalidWrapperSpecError` (from `sh-ast/analyze`) when
+ * `options.transparentWrappers` contains a malformed entry.
+ * @internal
+ */
+export declare function harvestCommands(sourceCode: ShellSourceCode, options?: HarvestCommandsOptions): ReadonlyMap<string, HarvestedCommand>;

package/dist/command-harvest/harvest-commands.js

@@ -0,0 +1,97 @@
+/**
+ * The command harvest: which external commands a shell file depends on.
+ *
+ * "Usage" here is the definition the declaration-convention rules compare
+ * declarations against: every command name the file statically runs, minus
+ * the shell's builtins and minus functions the file defines itself, following
+ * transparent wrappers so that `sudo curl …` uses both `sudo` and `curl`.
+ *
+ * Every fact comes from `sh-ast/analyze` through the `ShellSourceCode`
+ * helpers. `getCommandSites` supplies every command in the file, wherever it
+ * is nested (function bodies, `$(…)` in arguments, assignment values,
+ * redirect targets, loop lists, case subjects, …), and each site's
+ * `resolveInvokedCommand` supplies the wrapper chain. Whether a word is
+ * static is the analysis answer (`WordResolution.static`), never decided
+ * here.
+ *
+ * Out of scope, by design:
+ *
+ * - Dynamic command words (`"$cmd" x`, `sudo "$prog"`, `$(pick) x`). They
+ *   name no knowable command; `no-dynamic-invocation` reports them. Static
+ *   wrappers in front of a dynamic word (`sudo` in `sudo "$prog"`) are still
+ *   used.
+ * - Commands inside strings that another program runs (`bash -c '…'`,
+ *   `env -S '…'`). Those are text, not syntax.
+ *
+ * This module is internal. It is shaped to move, unchanged, into a public
+ * analysis-services package later; until then rules in this package use it.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { walkShell } from '../language/syntax-view.js';
+import { builtinsForDialect } from './builtins/index.js';
+/**
+ * The names of every function the file defines, anywhere in it (top level,
+ * nested in another function, inside a conditional, …). Position is not read,
+ * so this answers "could this name be a function", not "is it one at this
+ * call": a call in a function body usually runs after a later definition, but a
+ * top-level call before the definition does not run it. zsh's
+ * `function a b { … }` defines every listed name.
+ *
+ * @internal
+ */
+export function definedFunctionNames(sourceCode) {
+    const names = new Set();
+    walkShell(sourceCode.ast, (node) => {
+        if (node.type !== 'FuncDecl')
+            return;
+        if (node.name)
+            names.add(node.name.value);
+        for (const lit of node.names)
+            names.add(lit.value);
+    });
+    return names;
+}
+/**
+ * The `Word` node in `site`'s command at argv position `index`. argv and the
+ * `CallExpr`'s `args` list the same words in the same order, so a position
+ * from `chainIndices` selects the syntax word directly.
+ */
+function wordNodeAt(site, index) {
+    return site.node.args[index] ?? site.node;
+}
+/**
+ * Returns every external command `sourceCode` runs, keyed by name, each with
+ * its first use. The map iterates in first-use (source) order.
+ *
+ * A command is every static word in an invocation's wrapper chain (the
+ * wrappers and the effective command), excluding:
+ *
+ * - dynamic words, which name no knowable command;
+ * - builtins of the file's dialect (`sourceCode.dialect`);
+ * - functions the file defines anywhere.
+ *
+ * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when the file's
+ * nesting exceeds analysis's recursion guard: a partial harvest would miss
+ * real commands.
+ * @throws `ShAnalyzeInvalidWrapperSpecError` (from `sh-ast/analyze`) when
+ * `options.transparentWrappers` contains a malformed entry.
+ * @internal
+ */
+export function harvestCommands(sourceCode, options = {}) {
+    const transparentWrappers = options.transparentWrappers ?? DEFAULT_TRANSPARENT_WRAPPERS;
+    const builtins = builtinsForDialect(sourceCode.dialect);
+    const functions = definedFunctionNames(sourceCode);
+    const harvested = new Map();
+    for (const site of sourceCode.getCommandSites()) {
+        const { chain, chainIndices } = site.resolveInvokedCommand({ transparentWrappers });
+        for (const [position, word] of chain.entries()) {
+            if (!word.static)
+                continue;
+            const name = word.text;
+            if (harvested.has(name) || builtins.has(name) || functions.has(name))
+                continue;
+            harvested.set(name, { name, node: wordNodeAt(site, chainIndices[position]), site });
+        }
+    }
+    return harvested;
+}

package/dist/command-harvest/wrapper-table.d.ts

@@ -0,0 +1,24 @@
+import type { WrapperSpec } from 'sh-ast/analyze';
+import type { ShellDialect } from '../language/shell-language-options.js';
+/**
+ * Returns the transparent-wrapper table for harvesting a `dialect` file
+ * with the given configured wrapper names, in this order:
+ *
+ * 1. `sh-ast/analyze`'s `DEFAULT_TRANSPARENT_WRAPPERS` (`sudo`, `env`, …);
+ * 2. the dialect's own wrappers (`run` under `bats`);
+ * 3. the project's network wrapper (`settings.sh.networkWrapper`), when set,
+ *    with the options its spec declares: a wrapper that network commands must
+ *    run through runs the command after it;
+ * 4. one name-only entry per configured name. A name-only entry recognizes
+ *    no flags, so `with-retry -n 3 curl` stops at `-n` rather than guessing
+ *    past it.
+ *
+ * The first entry whose names match is the one used, so a network wrapper
+ * spec with options wins over a name-only entry for the same name.
+ *
+ * @param dialect - The linted file's `sourceCode.dialect`.
+ * @param wrapperNames - The rule's `transparentWrappers` option names.
+ * @param networkWrapper - The spec from `settings.sh.networkWrapper`, or `null`.
+ * @internal
+ */
+export declare function harvestWrapperTable(dialect: ShellDialect, wrapperNames: readonly string[], networkWrapper?: WrapperSpec | null): readonly WrapperSpec[];

package/dist/command-harvest/wrapper-table.js

@@ -0,0 +1,49 @@
+/**
+ * The one wrapper table that rules comparing declarations against usage
+ * pass to `harvestCommands` (`./harvest-commands.ts`).
+ *
+ * `no-undeclared-commands` and `no-unused-declarations` must agree exactly on
+ * which commands a file uses, or one would report a command the other calls
+ * unused. Usage depends on the wrapper table, so both build it here from the
+ * same inputs: the file's dialect, the network wrapper from
+ * `settings.sh.networkWrapper`, and the rule's `transparentWrappers` option
+ * names.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BATS_RUN_WRAPPER } from './builtins/bats.js';
+/**
+ * Wrappers a dialect's runtime provides beyond sh-ast's defaults: bats' `run`
+ * for `bats` files.
+ */
+const DIALECT_WRAPPERS = {
+    bats: [BATS_RUN_WRAPPER],
+};
+/**
+ * Returns the transparent-wrapper table for harvesting a `dialect` file
+ * with the given configured wrapper names, in this order:
+ *
+ * 1. `sh-ast/analyze`'s `DEFAULT_TRANSPARENT_WRAPPERS` (`sudo`, `env`, …);
+ * 2. the dialect's own wrappers (`run` under `bats`);
+ * 3. the project's network wrapper (`settings.sh.networkWrapper`), when set,
+ *    with the options its spec declares: a wrapper that network commands must
+ *    run through runs the command after it;
+ * 4. one name-only entry per configured name. A name-only entry recognizes
+ *    no flags, so `with-retry -n 3 curl` stops at `-n` rather than guessing
+ *    past it.
+ *
+ * The first entry whose names match is the one used, so a network wrapper
+ * spec with options wins over a name-only entry for the same name.
+ *
+ * @param dialect - The linted file's `sourceCode.dialect`.
+ * @param wrapperNames - The rule's `transparentWrappers` option names.
+ * @param networkWrapper - The spec from `settings.sh.networkWrapper`, or `null`.
+ * @internal
+ */
+export function harvestWrapperTable(dialect, wrapperNames, networkWrapper = null) {
+    return [
+        ...DEFAULT_TRANSPARENT_WRAPPERS,
+        ...(DIALECT_WRAPPERS[dialect] ?? []),
+        ...(networkWrapper === null ? [] : [networkWrapper]),
+        ...wrapperNames.map((name) => ({ names: [name] })),
+    ];
+}

package/dist/configs/agent-authored.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `sh/agent-authored` shared config: the strict preset for scripts that
+ * are machine-written and human-reviewed.
+ *
+ * Such a script is only as trustworthy as a reviewer's ability to vouch for
+ * it mechanically, so this preset adds the contract rules on top of
+ * `sh/recommended`: every command a script runs must be statically
+ * enumerable, declared, and (for network access) routed through the
+ * project's wrapper, and no script may stop to prompt a terminal that may not
+ * exist (`require-tty-guard`). Each contract rule reports at `error`, and so
+ * do `no-secret-flags` and `quote-expansions`, which `recommended` keeps at
+ * `warn`.
+ *
+ * It follows the same shape contract as `sh/recommended` (see
+ * `./recommended.ts`): one files-less config object that registers this
+ * plugin under `sh` and selects `language: 'sh/sh'`, so the two presets are
+ * interchangeable inside a user's `extends`.
+ *
+ * `max-script-complexity` keeps a machine-written script small enough for a
+ * reviewer to read in one sitting.
+ *
+ * Three members are inert until configured: `no-undeclared-commands` and
+ * `no-unused-declarations` need a declaration convention bound in
+ * `settings.sh.declarationConvention`, and `require-network-wrapper` needs a
+ * wrapper, set once in `settings.sh.networkWrapper` (which the declaration
+ * rules also read) or as the rule's `wrapper` option. They are enabled here so that binding the convention or
+ * wrapper is the only step a project takes; shipping a default convention or
+ * wrapper would impose one project's policy on every project.
+ *
+ * Rule membership follows the **Configs** column of the rule catalog
+ * (rules marked `A`), which a test checks against this
+ * module.
+ */
+import type { ConfigObject, Plugin } from '@eslint/core';
+/**
+ * Builds the `sh/agent-authored` config bound to `plugin`, which must be this
+ * package's default export (the preset registers it under `plugins.sh`).
+ *
+ * @internal
+ */
+export declare function createAgentAuthoredConfig(plugin: Plugin): ConfigObject;

package/dist/configs/agent-authored.js

@@ -0,0 +1,33 @@
+import { recommendedRules } from './recommended.js';
+/**
+ * The rules `sh/agent-authored` enables: every `sh/recommended` rule, then
+ * the contract rules, all at `error`.
+ */
+const agentAuthoredRules = {
+    ...recommendedRules,
+    'sh/no-secret-flags': 'error',
+    'sh/quote-expansions': 'error',
+    'sh/no-dynamic-invocation': 'error',
+    'sh/no-masked-exit-status': 'error',
+    'sh/max-script-complexity': 'error',
+    'sh/no-secret-env-reads': 'error',
+    'sh/no-undeclared-commands': 'error',
+    'sh/no-unused-declarations': 'error',
+    'sh/prefer-local': 'error',
+    'sh/require-network-wrapper': 'error',
+    'sh/require-tty-guard': 'error',
+};
+/**
+ * Builds the `sh/agent-authored` config bound to `plugin`, which must be this
+ * package's default export (the preset registers it under `plugins.sh`).
+ *
+ * @internal
+ */
+export function createAgentAuthoredConfig(plugin) {
+    return {
+        name: 'sh/agent-authored',
+        plugins: { sh: plugin },
+        language: 'sh/sh',
+        rules: { ...agentAuthoredRules },
+    };
+}

package/dist/configs/bash-3-2.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The `sh/bash-3.2` shared config: the preset for scripts that must run on the
+ * Bash 3.2 that macOS ships as `/bin/bash`.
+ *
+ * The parser accepts every construct its grammar knows whatever target is
+ * configured, so a Bash 3.2 target is enforced only by the `compat/*` rules.
+ * This preset names that target once (`languageOptions.shellVersion: '3.2'`)
+ * and turns on every version-gated rule that reads it, so a project states its
+ * deployment target as a config choice instead of enumerating rules.
+ *
+ * It follows the shape contract in `./recommended.ts`, with one deliberate
+ * extension: it carries `languageOptions`, because the target version is the
+ * preset's whole meaning and a pack that left it to the user would enable
+ * rules that report nothing. It still carries no `files` or `ignores`, so it
+ * inherits the user's globs, and it composes with the other presets through
+ * `extends: [sh.configs.recommended, sh.configs['bash-3.2']]`.
+ *
+ * Rule membership follows the **Configs** column of the rule catalog (rows
+ * marked `3.2`), which a test checks against this module.
+ */
+import type { ConfigObject, Plugin } from '@eslint/core';
+/**
+ * Builds the `sh/bash-3.2` config bound to `plugin`, which must be this
+ * package's default export (the preset registers it under `plugins.sh`).
+ *
+ * @internal
+ */
+export declare function createBash32Config(plugin: Plugin): ConfigObject;

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

@@ -0,0 +1,50 @@
+/**
+ * The rules `sh/bash-3.2` enables: every version-gated `compat/*` rule, all at
+ * `error`, keyed as a user writes them (`sh/<rule-name>`). Each reports a
+ * feature that Bash 3.2 lacks and names the portable alternative.
+ * `shebang-matches-dialect` is not a version gate and belongs to the
+ * presets whose catalog row names it. The POSIX-only gates
+ * (`compat/no-double-bracket`, `compat/no-let`, `compat/no-source`) are not
+ * version gates either: every Bash has those features, so they could never
+ * report here.
+ *
+ * @internal
+ */
+const bash32Rules = {
+    'sh/compat/no-append-all-redirect': 'error',
+    'sh/compat/no-associative-arrays': 'error',
+    'sh/compat/no-case-attributes': 'error',
+    'sh/compat/no-case-fallthrough': 'error',
+    'sh/compat/no-case-modification': 'error',
+    'sh/compat/no-coproc': 'error',
+    'sh/compat/no-declare-g': 'error',
+    'sh/compat/no-epoch-variables': 'error',
+    'sh/compat/no-fd-variable': 'error',
+    'sh/compat/no-globstar': 'error',
+    'sh/compat/no-lastpipe-semantics': 'error',
+    'sh/compat/no-mapfile': 'error',
+    'sh/compat/no-nameref': 'error',
+    'sh/compat/no-negative-array-index': 'error',
+    'sh/compat/no-nounset-empty-array': 'error',
+    'sh/compat/no-parameter-transformation': 'error',
+    'sh/compat/no-pipe-all': 'error',
+    'sh/compat/no-printf-time-format': 'error',
+    'sh/compat/no-test-v': 'error',
+    'sh/compat/no-unicode-escape': 'error',
+    'sh/compat/no-wait-n': 'error',
+};
+/**
+ * Builds the `sh/bash-3.2` config bound to `plugin`, which must be this
+ * package's default export (the preset registers it under `plugins.sh`).
+ *
+ * @internal
+ */
+export function createBash32Config(plugin) {
+    return {
+        name: 'sh/bash-3.2',
+        plugins: { sh: plugin },
+        language: 'sh/sh',
+        languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+        rules: { ...bash32Rules },
+    };
+}

package/dist/configs/posix-portable.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `sh/posix-portable` shared config: the preset for scripts meant for a
+ * POSIX `sh` rather than for Bash.
+ *
+ * It sets `languageOptions.dialect: 'posix'`, which makes every Bash-only
+ * feature unavailable at any `shellVersion`, and enables the `compat/*` rules
+ * that report those features. The dialect is also what every dialect-aware
+ * rule reads, so the preset is one switch rather than a list of settings that
+ * could drift apart.
+ *
+ * The preset is not a proof of portability. Its rules report named constructs
+ * that really fail on dash, and the parser rejects some others; it deliberately
+ * leaves `local`, `echo -e` and the rest of shellcheck's SC3xxx catalog to
+ * shellcheck, which is why it does not promise "any POSIX `sh`". The scope and
+ * the shell behaviour behind it are stated for users in `docs/compat.md`.
+ *
+ * `require-strict-mode` is configured, not merely enabled. Its default under
+ * `posix` is already `set -eu`, but the preset states `mode: 'set -eu'`
+ * explicitly so that neither a later edit to that default nor an inherited
+ * `recommended` severity-only entry can make the pack demand `pipefail`,
+ * which POSIX gained only in POSIX.1-2024 and which dash and older BusyBox
+ * ash reject. A pack that asked for `pipefail` would make its own autofix
+ * break a working `#!/bin/sh` script.
+ *
+ * It follows the shape contract in `./recommended.ts`, extended with
+ * `languageOptions` for the reason given in `./bash-3-2.ts`. It composes
+ * through `extends: [sh.configs.recommended, sh.configs['posix-portable']]`;
+ * the later entry's `require-strict-mode` options win.
+ *
+ * Rule membership follows the **Configs** column of the rule catalog (rows
+ * marked `P`), which a test checks against this module.
+ */
+import type { ConfigObject, Plugin } from '@eslint/core';
+/**
+ * Builds the `sh/posix-portable` config bound to `plugin`, which must be this
+ * package's default export (the preset registers it under `plugins.sh`).
+ *
+ * @internal
+ */
+export declare function createPosixPortableConfig(plugin: Plugin): ConfigObject;

package/dist/configs/posix-portable.js

@@ -0,0 +1,52 @@
+/**
+ * The rules `sh/posix-portable` enables, all at `error`, keyed as a user
+ * writes them (`sh/<rule-name>`): every `compat/*` rule (each reports under
+ * `dialect: 'posix'` whatever the version), including the POSIX-only gates
+ * `bash-3.2` has no use for, the shebang/dialect check, and strict mode in its
+ * POSIX spelling.
+ *
+ * @internal
+ */
+const posixPortableRules = {
+    'sh/require-strict-mode': ['error', { mode: 'set -eu' }],
+    'sh/shebang-matches-dialect': 'error',
+    'sh/compat/no-append-all-redirect': 'error',
+    'sh/compat/no-associative-arrays': 'error',
+    'sh/compat/no-case-attributes': 'error',
+    'sh/compat/no-case-fallthrough': 'error',
+    'sh/compat/no-case-modification': 'error',
+    'sh/compat/no-coproc': 'error',
+    'sh/compat/no-declare-g': 'error',
+    'sh/compat/no-double-bracket': 'error',
+    'sh/compat/no-epoch-variables': 'error',
+    'sh/compat/no-fd-variable': 'error',
+    'sh/compat/no-globstar': 'error',
+    'sh/compat/no-lastpipe-semantics': 'error',
+    'sh/compat/no-let': 'error',
+    'sh/compat/no-mapfile': 'error',
+    'sh/compat/no-nameref': 'error',
+    'sh/compat/no-negative-array-index': 'error',
+    'sh/compat/no-nounset-empty-array': 'error',
+    'sh/compat/no-parameter-transformation': 'error',
+    'sh/compat/no-pipe-all': 'error',
+    'sh/compat/no-printf-time-format': 'error',
+    'sh/compat/no-source': 'error',
+    'sh/compat/no-test-v': 'error',
+    'sh/compat/no-unicode-escape': 'error',
+    'sh/compat/no-wait-n': 'error',
+};
+/**
+ * Builds the `sh/posix-portable` config bound to `plugin`, which must be this
+ * package's default export (the preset registers it under `plugins.sh`).
+ *
+ * @internal
+ */
+export function createPosixPortableConfig(plugin) {
+    return {
+        name: 'sh/posix-portable',
+        plugins: { sh: plugin },
+        language: 'sh/sh',
+        languageOptions: { dialect: 'posix' },
+        rules: { ...posixPortableRules },
+    };
+}

package/dist/configs/recommended.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The `sh/recommended` shared config: the preset most users extend to adopt
+ * eslint-sh.
+ *
+ * Its job is to take `language: 'sh/sh'` out of the user's hands. A config
+ * that forgets that key makes ESLint parse shell scripts as JavaScript, and
+ * none of this plugin's code runs to explain why. Extending this preset
+ * supplies the key, together with the plugin registration it resolves
+ * against.
+ *
+ * Shape contract (binding for every config this plugin ships):
+ *
+ * - A single config object, not an array, so it composes through
+ *   `extends: [sh.configs.recommended, ...]` and through object spread.
+ * - No `files`, `ignores` or `languageOptions`. ESLint intersects an extended
+ *   config's `files` with the extending entry's `files`, so a preset that
+ *   carried its own globs would silently drop any path the user matched
+ *   outside them (extensionless scripts such as `scripts/deploy` in
+ *   particular). Without `files`, the preset inherits exactly the globs the
+ *   user wrote. Shell paths are the user's knowledge; the preset never
+ *   guesses them.
+ * - The plugin is registered under the key `sh`, because `language: 'sh/sh'`
+ *   resolves against the config's plugin key, not `meta.namespace`. The
+ *   registered value is the plugin's own default export, so a user who also
+ *   writes `plugins: { sh }` registers the identical object and ESLint
+ *   accepts it.
+ *
+ * Rule membership follows the **Configs** column of the rule catalog
+ * (rules marked `R`): safe defaults that assume no project
+ * conventions. A rule joins this preset only by appearing in that column; a
+ * test parses the catalog and fails when the two drift apart.
+ */
+import type { ConfigObject, Plugin, RulesConfig } from '@eslint/core';
+/**
+ * The rules `sh/recommended` enables, with their severities, keyed as a user
+ * writes them (`sh/<rule-name>`).
+ *
+ * `no-secret-flags` is a heuristic screen with documented false positives, and
+ * `quote-expansions` duplicates shellcheck's SC2086 for teams that also run
+ * shellcheck, so both report at `warn` here; every other member is `error`. `agent-authored`
+ * extends this record, so a rule added here is enabled there too.
+ *
+ * @internal
+ */
+export declare const recommendedRules: Readonly<RulesConfig>;
+/**
+ * Builds the `sh/recommended` config bound to `plugin`, which must be this
+ * package's default export (the preset registers it under `plugins.sh`).
+ *
+ * @internal
+ */
+export declare function createRecommendedConfig(plugin: Plugin): ConfigObject;

package/dist/configs/recommended.js

@@ -0,0 +1,34 @@
+/**
+ * The rules `sh/recommended` enables, with their severities, keyed as a user
+ * writes them (`sh/<rule-name>`).
+ *
+ * `no-secret-flags` is a heuristic screen with documented false positives, and
+ * `quote-expansions` duplicates shellcheck's SC2086 for teams that also run
+ * shellcheck, so both report at `warn` here; every other member is `error`. `agent-authored`
+ * extends this record, so a rule added here is enabled there too.
+ *
+ * @internal
+ */
+export const recommendedRules = {
+    'sh/require-strict-mode': 'error',
+    'sh/require-shebang': 'error',
+    'sh/no-eval': 'error',
+    'sh/no-secret-flags': 'warn',
+    'sh/no-unchecked-cd': 'error',
+    'sh/shebang-matches-dialect': 'error',
+    'sh/quote-expansions': 'warn',
+};
+/**
+ * Builds the `sh/recommended` config bound to `plugin`, which must be this
+ * package's default export (the preset registers it under `plugins.sh`).
+ *
+ * @internal
+ */
+export function createRecommendedConfig(plugin) {
+    return {
+        name: 'sh/recommended',
+        plugins: { sh: plugin },
+        language: 'sh/sh',
+        rules: { ...recommendedRules },
+    };
+}