@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/dist/rules/define-shell-rule.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The public rule-authoring helper: the one place a shell rule, built-in or
+ * third-party, gets its `meta.languages` and its shell-specific types.
+ *
+ * ESLint (≥ 10.2) refuses to run a rule on a language its `meta.languages`
+ * does not list, which turns "a shell rule was enabled for a JavaScript file"
+ * (usually a config entry missing `language: 'sh/sh'`) into a configuration
+ * error naming the rule. A rule that omits `meta.languages` fails open: ESLint
+ * applies it everywhere and the user sees a misleading JavaScript `Parsing
+ * error` instead. {@link defineShellRule} therefore owns the field, so no rule
+ * built with it can omit or mistype it, and the types forbid an author from
+ * writing it at all.
+ *
+ * It also fixes the types a rule sees, so authors need no `@eslint/core`
+ * import of their own: `context.sourceCode` is {@link ShellSourceCode} and
+ * visitors receive {@link ShellNode} lint-view nodes — `type` discriminators,
+ * lowercase field names, UTF-16 `range`/`loc` — never the faithful `sh-ast`
+ * records the view is built from.
+ *
+ * The plugin's own built-in rules are built through this same helper (via the
+ * internal `createRule`, which only adds their docs URLs), so the guarantee a
+ * third-party rule gets is the one the built-in rules are tested against.
+ */
+import type { RuleContext, RuleDefinition, RulesMeta } from '@eslint/core';
+import type { NormalizedShellLanguageOptions } from '../language/shell-language-options.js';
+import type { ShellSourceCode } from '../language/shell-source-code.js';
+import type { ShellNode, ShellNodeOf, ShellNodeType } from '../language/syntax-view.js';
+/**
+ * A listener for a node of type `Node`. It is declared with method syntax on
+ * purpose: method parameters are checked bivariantly, which lets a listener
+ * for one node type sit alongside the union-typed listener every other
+ * selector key gets (see {@link ShellRuleVisitor}) without a type error.
+ *
+ * Exported so a helper that builds listeners for several rules can name the
+ * type it returns; `node` is the matched node and `parent` its parent
+ * (`undefined` for the root `File`).
+ *
+ * @public
+ */
+export type ShellListener<Node extends ShellNode = ShellNode> = {
+    listener(node: Node, parent: ShellNode | undefined): void;
+}['listener'];
+/**
+ * The listeners whose key names one node type, or that node type with the
+ * `:exit` suffix, each receiving exactly that node type. The key is
+ * unambiguous in both forms (`CallExpr`, `CallExpr:exit`), so a listener
+ * needs no `node.type` guard. Wildcard (`*`, `*:exit`) and attribute or
+ * class selectors name no single type and fall under the index signature.
+ *
+ * Exported because {@link ShellRuleVisitor} extends it.
+ *
+ * @public
+ */
+export type ShellTypedListeners = {
+    [Type in ShellNodeType as Type | `${Type}:exit`]?: ShellListener<ShellNodeOf<Type>>;
+};
+/**
+ * The listener map a shell rule's `create()` returns. Keys are node types or
+ * esquery selectors written against the lint view's spelling (for example
+ * `CallExpr[args.0.parts.0.value='jq']` or the `:command` selector class),
+ * optionally suffixed with `:exit`. ESLint calls each listener with the
+ * matched node and its parent (the parent is `undefined` for the root
+ * `File`).
+ *
+ * A key that is exactly a node type, with or without `:exit` (`CallExpr`,
+ * `Word:exit`), types its listener's node as that node type, so
+ * `CallExpr(node) { node.args }` reads `args` with no `type` check. Any other
+ * selector string (`*`, `CallExpr[…]`, `:command`, `Stmt > CallExpr`) matches
+ * nodes of more than one type, or of one type the key does not state, so its
+ * listener receives the whole {@link ShellNode} union: narrow it on `type`.
+ *
+ * @public
+ */
+export interface ShellRuleVisitor extends ShellTypedListeners {
+    [selector: string]: ShellListener | undefined;
+}
+/**
+ * The `context` a shell rule's `create()` receives: ESLint's rule context
+ * specialized to the shell language, so `context.sourceCode` is
+ * {@link ShellSourceCode}, `context.languageOptions` is
+ * {@link NormalizedShellLanguageOptions}, `context.options` is `RuleOptions`,
+ * and `context.report` takes {@link ShellNode}s and only the `MessageIds` the
+ * rule declares. Name it when a helper outside `create()` needs the context.
+ *
+ * `context.languageOptions` is the object `ShellLanguage.normalizeLanguageOptions`
+ * returned, not the user's config input, so `dialect` is always set (`"bash"`
+ * by default) and needs no fallback. `context.sourceCode.dialect` carries that
+ * same normalized value; read whichever is closer to hand.
+ *
+ * @public
+ */
+export type ShellRuleContext<RuleOptions extends unknown[] = [], MessageIds extends string = string> = RuleContext<{
+    LangOptions: NormalizedShellLanguageOptions;
+    Code: ShellSourceCode;
+    RuleOptions: RuleOptions;
+    Node: ShellNode;
+    MessageIds: MessageIds;
+}>;
+/**
+ * The `meta` a rule author writes: every field ESLint's rule `meta` accepts
+ * (`type`, `docs`, `schema`, `messages`, `fixable`, `defaultOptions`, …)
+ * except the language fields, which {@link defineShellRule} owns. `languages`
+ * and its deprecated singular predecessor `language` are typed `never`, so
+ * writing either — in particular a language other than `sh/sh` — is a
+ * compile error rather than a value the helper silently replaces.
+ *
+ * @public
+ */
+export type ShellRuleMeta<RuleOptions extends unknown[] = [], MessageIds extends string = string> = Omit<RulesMeta<MessageIds, RuleOptions>, 'languages' | 'language'> & {
+    readonly languages?: never;
+    readonly language?: never;
+};
+/**
+ * What a rule author hands to {@link defineShellRule}: the rule's `meta` and
+ * its `create()`, exactly as in any ESLint rule, minus `meta.languages`. It is
+ * the rule before the helper finishes it; {@link ShellRule} is the finished
+ * rule (ESLint's `RuleDefinition`), so the input is named a spec, not a
+ * definition.
+ *
+ * @public
+ */
+export interface ShellRuleSpec<RuleOptions extends unknown[] = [], MessageIds extends string = string> {
+    /** The rule's metadata; see {@link ShellRuleMeta}. */
+    readonly meta: ShellRuleMeta<RuleOptions, MessageIds>;
+    /** Builds the rule's listeners for one file from the shell-typed context. */
+    readonly create: (context: ShellRuleContext<RuleOptions, MessageIds>) => ShellRuleVisitor;
+}
+/**
+ * A finished shell rule, as {@link defineShellRule} returns it: an ordinary
+ * ESLint rule definition (it goes in a plugin's `rules` like any other)
+ * specialized to the shell language, whose `meta.languages` is always exactly
+ * `["sh/sh"]`. The `meta.languages` requirement is part of the type, so a
+ * hand-written object that omits it, or names another language, is not a
+ * `ShellRule`.
+ *
+ * @public
+ */
+export type ShellRule<RuleOptions extends unknown[] = [], MessageIds extends string = string> = Omit<RuleDefinition<{
+    LangOptions: NormalizedShellLanguageOptions;
+    Code: ShellSourceCode;
+    RuleOptions: RuleOptions;
+    Visitor: ShellRuleVisitor;
+    Node: ShellNode;
+    MessageIds: MessageIds;
+    ExtRuleDocs: unknown;
+}>, 'meta'> & {
+    readonly meta: Omit<RulesMeta<MessageIds, RuleOptions>, 'languages'> & {
+        languages: ['sh/sh'];
+    };
+};
+/**
+ * Builds a shell rule from its spec, setting `meta.languages` to
+ * exactly `["sh/sh"]` so ESLint refuses to run the rule on any other language.
+ * Everything else in `meta`, and `create`, is kept as written; message ids
+ * and option types are inferred from `meta` or may be given explicitly
+ * (`defineShellRule<[], 'found'>(…)`).
+ *
+ * The language fields are written last, so a JavaScript caller that bypasses
+ * the types and supplies its own `languages` or `language` still gets
+ * exactly `["sh/sh"]` (and no `language`). A JavaScript caller that omits
+ * `meta`, which ESLint allows for a rule, is treated as having written
+ * `meta: {}`.
+ *
+ * @example
+ * ```ts
+ * import { defineShellRule } from '@eslint-sh/eslint-plugin';
+ *
+ * export const noEval = defineShellRule({
+ *   meta: { type: 'problem', schema: [], messages: { evalUsed: 'Avoid eval.' } },
+ *   create(context) {
+ *     return {
+ *       CallExpr(node) {
+ *         if (context.sourceCode.getCommandName(node) === 'eval') {
+ *           context.report({ node, messageId: 'evalUsed' });
+ *         }
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function defineShellRule<RuleOptions extends unknown[] = [], MessageIds extends string = string>(spec: ShellRuleSpec<RuleOptions, MessageIds>): ShellRule<RuleOptions, MessageIds>;

package/dist/rules/define-shell-rule.js

@@ -0,0 +1,56 @@
+/**
+ * The `"<plugin namespace>/<language key>"` identifier this plugin's language
+ * is selected by in a flat config (`language: "sh/sh"`), and therefore the
+ * only entry a shell rule's `meta.languages` holds. ESLint also accepts the
+ * plugin's `meta.namespace` as the plugin part, so the value still matches
+ * when a consumer registers the plugin under another key.
+ */
+const SHELL_LANGUAGE_ID = 'sh/sh';
+/**
+ * Builds a shell rule from its spec, setting `meta.languages` to
+ * exactly `["sh/sh"]` so ESLint refuses to run the rule on any other language.
+ * Everything else in `meta`, and `create`, is kept as written; message ids
+ * and option types are inferred from `meta` or may be given explicitly
+ * (`defineShellRule<[], 'found'>(…)`).
+ *
+ * The language fields are written last, so a JavaScript caller that bypasses
+ * the types and supplies its own `languages` or `language` still gets
+ * exactly `["sh/sh"]` (and no `language`). A JavaScript caller that omits
+ * `meta`, which ESLint allows for a rule, is treated as having written
+ * `meta: {}`.
+ *
+ * @example
+ * ```ts
+ * import { defineShellRule } from '@eslint-sh/eslint-plugin';
+ *
+ * export const noEval = defineShellRule({
+ *   meta: { type: 'problem', schema: [], messages: { evalUsed: 'Avoid eval.' } },
+ *   create(context) {
+ *     return {
+ *       CallExpr(node) {
+ *         if (context.sourceCode.getCommandName(node) === 'eval') {
+ *           context.report({ node, messageId: 'evalUsed' });
+ *         }
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export function defineShellRule(spec) {
+    // The type requires `meta`, but ESLint accepts a rule without one, so an
+    // untyped (JavaScript) caller's missing `meta` is read as empty rather than
+    // crashing. The types cannot see that caller, hence the suppression.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const meta = spec.meta ?? {};
+    // Drop the deprecated singular key an untyped caller may have supplied, so
+    // the only language declaration ESLint sees is the one set here.
+    const { language: _language, ...authorMeta } = meta;
+    const { create } = spec;
+    return {
+        meta: { ...authorMeta, languages: [SHELL_LANGUAGE_ID] },
+        create,
+    };
+}

package/dist/rules/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The built-in rule registry: the one and only place this package's rules are
+ * listed. The plugin object's `rules` is this record, so a rule is shipped
+ * exactly when it appears here.
+ *
+ * Adding a rule means one line here (`'<rule-name>': <ruleModule>,`, keyed by
+ * the same name passed to `createRule`) plus the rule's own files: its module
+ * under `src/rules/`, its tests, and its docs page at
+ * `docs/rules/<rule-name>.md` (a test fails if a registered rule has no docs
+ * page, or a docs page has no registered rule). A namespaced name such as
+ * `compat/no-mapfile` keeps its namespace as a directory: the module is
+ * `src/rules/compat/no-mapfile.ts` and the page `docs/rules/compat/no-mapfile.md`.
+ *
+ * Every entry is built with `createRule` (see `./create-rule.ts`), so every
+ * entry declares `meta.languages: ["sh/sh"]` and a `meta.docs.url` pointing at
+ * its docs page. An empty registry is a valid state: the plugin then ships
+ * `rules: {}` and remains usable for consumer-supplied rules.
+ */
+import type { RuleDefinition } from '@eslint/core';
+/**
+ * Built-in rules keyed by rule name (without the `sh/` namespace a user writes
+ * in their config).
+ *
+ * @internal
+ */
+export declare const rules: Record<string, RuleDefinition>;

package/dist/rules/index.js

@@ -0,0 +1,90 @@
+import { noAppendAllRedirect } from './compat/no-append-all-redirect.js';
+import { noAssociativeArrays } from './compat/no-associative-arrays.js';
+import { noBraceSequencePaddingStep } from './compat/no-brace-sequence-padding-step.js';
+import { noCaseAttributes } from './compat/no-case-attributes.js';
+import { noCaseFallthrough } from './compat/no-case-fallthrough.js';
+import { noCaseModification } from './compat/no-case-modification.js';
+import { noCoproc } from './compat/no-coproc.js';
+import { noDeclareG } from './compat/no-declare-g.js';
+import { noDoubleBracket } from './compat/no-double-bracket.js';
+import { noEpochVariables } from './compat/no-epoch-variables.js';
+import { noFdVariable } from './compat/no-fd-variable.js';
+import { noGlobstar } from './compat/no-globstar.js';
+import { noLastpipeSemantics } from './compat/no-lastpipe-semantics.js';
+import { noLet } from './compat/no-let.js';
+import { noMapfile } from './compat/no-mapfile.js';
+import { noNameref } from './compat/no-nameref.js';
+import { noNegativeArrayIndex } from './compat/no-negative-array-index.js';
+import { noNounsetEmptyArray } from './compat/no-nounset-empty-array.js';
+import { noParameterTransformation } from './compat/no-parameter-transformation.js';
+import { noPipeAll } from './compat/no-pipe-all.js';
+import { noPrintfTimeFormat } from './compat/no-printf-time-format.js';
+import { noSource } from './compat/no-source.js';
+import { noTestV } from './compat/no-test-v.js';
+import { noUnicodeEscape } from './compat/no-unicode-escape.js';
+import { noWaitN } from './compat/no-wait-n.js';
+import { maxScriptComplexity } from './max-script-complexity.js';
+import { noDynamicInvocation } from './no-dynamic-invocation.js';
+import { noEval } from './no-eval.js';
+import { noMaskedExitStatus } from './no-masked-exit-status.js';
+import { noSecretEnvReads } from './no-secret-env-reads.js';
+import { noSecretFlags } from './no-secret-flags.js';
+import { noUncheckedCd } from './no-unchecked-cd.js';
+import { noUndeclaredCommands } from './no-undeclared-commands.js';
+import { noUnusedDeclarations } from './no-unused-declarations.js';
+import { preferLocal } from './prefer-local.js';
+import { quoteExpansions } from './quote-expansions.js';
+import { requireNetworkWrapper } from './require-network-wrapper.js';
+import { requireShebang } from './require-shebang.js';
+import { requireStrictMode } from './require-strict-mode.js';
+import { requireTtyGuard } from './require-tty-guard.js';
+import { shebangMatchesDialect } from './shebang-matches-dialect.js';
+/**
+ * Built-in rules keyed by rule name (without the `sh/` namespace a user writes
+ * in their config).
+ *
+ * @internal
+ */
+export const rules = {
+    'compat/no-append-all-redirect': noAppendAllRedirect,
+    'compat/no-associative-arrays': noAssociativeArrays,
+    'compat/no-brace-sequence-padding-step': noBraceSequencePaddingStep,
+    'compat/no-case-attributes': noCaseAttributes,
+    'compat/no-case-fallthrough': noCaseFallthrough,
+    'compat/no-case-modification': noCaseModification,
+    'compat/no-coproc': noCoproc,
+    'compat/no-declare-g': noDeclareG,
+    'compat/no-double-bracket': noDoubleBracket,
+    'compat/no-epoch-variables': noEpochVariables,
+    'compat/no-fd-variable': noFdVariable,
+    'compat/no-globstar': noGlobstar,
+    'compat/no-lastpipe-semantics': noLastpipeSemantics,
+    'compat/no-let': noLet,
+    'compat/no-mapfile': noMapfile,
+    'compat/no-nameref': noNameref,
+    'compat/no-negative-array-index': noNegativeArrayIndex,
+    'compat/no-nounset-empty-array': noNounsetEmptyArray,
+    'compat/no-parameter-transformation': noParameterTransformation,
+    'compat/no-pipe-all': noPipeAll,
+    'compat/no-printf-time-format': noPrintfTimeFormat,
+    'compat/no-source': noSource,
+    'compat/no-test-v': noTestV,
+    'compat/no-unicode-escape': noUnicodeEscape,
+    'compat/no-wait-n': noWaitN,
+    'max-script-complexity': maxScriptComplexity,
+    'no-dynamic-invocation': noDynamicInvocation,
+    'no-eval': noEval,
+    'no-masked-exit-status': noMaskedExitStatus,
+    'no-secret-env-reads': noSecretEnvReads,
+    'no-secret-flags': noSecretFlags,
+    'no-unchecked-cd': noUncheckedCd,
+    'no-undeclared-commands': noUndeclaredCommands,
+    'no-unused-declarations': noUnusedDeclarations,
+    'prefer-local': preferLocal,
+    'quote-expansions': quoteExpansions,
+    'require-network-wrapper': requireNetworkWrapper,
+    'require-shebang': requireShebang,
+    'require-strict-mode': requireStrictMode,
+    'require-tty-guard': requireTtyGuard,
+    'shebang-matches-dialect': shebangMatchesDialect,
+};

package/dist/rules/max-script-complexity.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The rule's single options object, as written in a config. Each field is a
+ * non-negative integer limit (`0` allows none of that construct), `null` to
+ * switch that one limit off, or omitted to take the default.
+ *
+ * @internal
+ */
+export interface MaxScriptComplexityOptions {
+    /** Most function declarations a file may contain (default 20). */
+    readonly maxFunctions?: number | null;
+    /** Deepest control-structure nesting a file may contain (default 4). */
+    readonly maxNesting?: number | null;
+    /** Most statements a file may contain (default 300). */
+    readonly maxStatements?: number | null;
+}
+/**
+ * The rule's report kinds, one per limit: `tooManyFunctions`,
+ * `tooMuchNesting`, `tooManyStatements`.
+ *
+ * @internal
+ */
+export type MaxScriptComplexityMessageId = 'tooManyFunctions' | 'tooMuchNesting' | 'tooManyStatements';
+/**
+ * The `sh/max-script-complexity` rule module.
+ *
+ * @internal
+ */
+export declare const maxScriptComplexity: import("./define-shell-rule.js").ShellRule<[MaxScriptComplexityOptions], MaxScriptComplexityMessageId>;

package/dist/rules/max-script-complexity.js

@@ -0,0 +1,130 @@
+import { createRule } from './create-rule.js';
+/** The registry name of this rule (`sh/max-script-complexity` in a user's config). */
+const RULE_NAME = 'max-script-complexity';
+/** The limits applied when an option is omitted. */
+const DEFAULT_LIMITS = {
+    maxFunctions: 20,
+    maxNesting: 4,
+    maxStatements: 300,
+};
+/**
+ * Resolve one configured limit: an omitted field takes the default, while an
+ * explicit `null` stays `null` (the limit is off). `??` is deliberately not
+ * used because it would turn `null` back into the default.
+ */
+function resolveLimit(configured, fallback) {
+    return configured === undefined ? fallback : configured;
+}
+/**
+ * Selectors for every construct that adds one nesting level. `elif`/`else`
+ * arms are `IfClause` children of an `IfClause` and so are excluded, and a
+ * function's body braces (`FuncDecl > Stmt > Block`) are the function's
+ * syntax, not a brace group.
+ */
+const NESTING_SELECTORS = [
+    'IfClause:not(IfClause > IfClause)',
+    'ForClause',
+    'WhileClause',
+    'CaseClause',
+    'Subshell',
+    'Block:not(FuncDecl > Stmt > Block)',
+];
+/**
+ * Selector for a counted statement: not an operand of `&&`, `||` or `|`, and
+ * not a function's body wrapper (the declaration is already one statement).
+ */
+const STATEMENT_SELECTOR = 'Stmt:not(BinaryCmd > Stmt):not(FuncDecl > Stmt)';
+/**
+ * The `sh/max-script-complexity` rule module.
+ *
+ * @internal
+ */
+export const maxScriptComplexity = createRule({
+    name: RULE_NAME,
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Cap the number of functions, the nesting depth and the statement count of a script',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    maxFunctions: { type: ['integer', 'null'], minimum: 0 },
+                    maxNesting: { type: ['integer', 'null'], minimum: 0 },
+                    maxStatements: { type: ['integer', 'null'], minimum: 0 },
+                },
+                additionalProperties: false,
+            },
+        ],
+        defaultOptions: [{ ...DEFAULT_LIMITS }],
+        messages: {
+            tooManyFunctions: 'This script declares {{count}} functions, more than the {{max}} allowed. Split it into smaller scripts.',
+            tooMuchNesting: 'This construct is nested {{depth}} levels deep, more than the {{max}} allowed. Flatten it or move the inner part into a function.',
+            tooManyStatements: 'This script has more than {{max}} statements. Split it into smaller scripts.',
+        },
+    },
+    create(context) {
+        const { sourceCode } = context;
+        const [options] = context.options;
+        const maxFunctions = resolveLimit(options.maxFunctions, DEFAULT_LIMITS.maxFunctions);
+        const maxNesting = resolveLimit(options.maxNesting, DEFAULT_LIMITS.maxNesting);
+        const maxStatements = resolveLimit(options.maxStatements, DEFAULT_LIMITS.maxStatements);
+        let functionCount = 0;
+        let depth = 0;
+        let nestingReported = false;
+        let statementCount = 0;
+        let statementsReported = false;
+        const handlers = {
+            FuncDecl() {
+                functionCount++;
+            },
+            [STATEMENT_SELECTOR](node) {
+                statementCount++;
+                if (maxStatements !== null && statementCount > maxStatements && !statementsReported) {
+                    statementsReported = true;
+                    context.report({
+                        node,
+                        messageId: 'tooManyStatements',
+                        data: { max: String(maxStatements) },
+                    });
+                }
+            },
+            'File:exit'() {
+                if (maxFunctions === null || functionCount <= maxFunctions) {
+                    return;
+                }
+                // Line 1 in full, from the line's own length (as in `require-shebang`).
+                const firstLine = sourceCode.lines[0] ?? '';
+                context.report({
+                    loc: {
+                        start: { line: 1, column: 1 },
+                        end: { line: 1, column: firstLine.length + 1 },
+                    },
+                    messageId: 'tooManyFunctions',
+                    data: { count: String(functionCount), max: String(maxFunctions) },
+                });
+            },
+        };
+        // Entry and exit must be registered per selector: ESLint reads `:exit`
+        // only as a trailing marker on a whole selector string, so a comma-joined
+        // list would pair one exit handler with just its last alternative.
+        for (const selector of NESTING_SELECTORS) {
+            handlers[selector] = (node) => {
+                depth++;
+                if (maxNesting !== null && depth > maxNesting && !nestingReported) {
+                    nestingReported = true;
+                    context.report({
+                        node,
+                        messageId: 'tooMuchNesting',
+                        data: { depth: String(depth), max: String(maxNesting) },
+                    });
+                }
+            };
+            handlers[`${selector}:exit`] = () => {
+                depth--;
+            };
+        }
+        return handlers;
+    },
+});

package/dist/rules/no-dynamic-invocation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Message ids this rule reports with: `dynamicInvocation` when the command
+ * that runs is not statically known, and `embeddedCommand` when the command
+ * runs code embedded in a string (`bash -c …`).
+ *
+ * @internal
+ */
+export type NoDynamicInvocationMessageId = 'dynamicInvocation' | 'embeddedCommand';
+/**
+ * The rule's single options object.
+ *
+ * @internal
+ */
+export interface NoDynamicInvocationOptions {
+    /**
+     * Names of dispatcher functions. A dynamic invocation lexically inside a
+     * function with one of these names, at any depth, does not report
+     * `dynamicInvocation`. Embedded commands still report.
+     */
+    readonly allowInFunctions?: readonly string[];
+    /**
+     * Command names to treat as transparent wrappers, in addition to the
+     * built-in list: the word after one is the command that runs. Each is
+     * followed by name only, with no options of its own, so a flag after it
+     * makes the effective command unknown. A name already in the built-in list
+     * keeps its built-in option handling.
+     */
+    readonly allowWrappers?: readonly string[];
+}
+/**
+ * The `sh/no-dynamic-invocation` rule module.
+ *
+ * @internal
+ */
+export declare const noDynamicInvocation: import("./define-shell-rule.js").ShellRule<[NoDynamicInvocationOptions], NoDynamicInvocationMessageId>;

package/dist/rules/no-dynamic-invocation.js

@@ -0,0 +1,117 @@
+/**
+ * `sh/no-dynamic-invocation`: reports every command whose effective command
+ * cannot be statically enumerated, so a script's call graph can be read off
+ * its source.
+ *
+ * This is the load-bearing rule for review-and-sign workflows: a reviewer
+ * vouching for a script has to know every command it can run. A command word
+ * that is only known at run time (`"$cmd" args`, `${tool} x`,
+ * `$(pick-tool) x`, `"${cmd[@]}"`) defeats that, and so does a command
+ * string handed to another shell (`bash -c "$x"`, `sh -c '…'`).
+ *
+ * The rule asks, never decides:
+ *
+ * - Every command in the file comes from `ShellSourceCode.getCommandSites`,
+ *   so commands nested in command substitutions, process substitutions,
+ *   pipelines and function bodies are all checked, each once.
+ * - Which command each one runs comes from `resolveInvokedCommand`, which
+ *   follows transparent wrappers (`exec`, `sudo`, `time`, `env`, …) and never
+ *   guesses through a word it cannot know. A non-static effective command
+ *   reports. `'embedded-command'` reports as `embeddedCommand`; every other
+ *   reason (an expansion, a glob, a tilde, an unrecognized wrapper flag, …)
+ *   reports as `dynamicInvocation`.
+ * - The wrappers followed are `sh-ast/analyze`'s defaults, Bash's `builtin`,
+ *   shells invoked as commands (so `bash -c` is an embedded command and
+ *   `bash script.sh` runs `script.sh`), and the names in `allowWrappers`.
+ *
+ * The analysis is syntactic by design: `cmd=ls; "$cmd"` reports, because
+ * resolving it would need dataflow. Aliases need no handling: they are not
+ * expanded in non-interactive scripts, so an alias name is an ordinary static
+ * command word. The rule offers no fix and no suggestion; choosing the
+ * command is a human decision.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { createRule } from './create-rule.js';
+import { BUILTIN_WRAPPER, SHELL_WRAPPER } from './transparent-wrappers.js';
+/** The registry name of this rule (`sh/no-dynamic-invocation` in a user's config). */
+const RULE_NAME = 'no-dynamic-invocation';
+/**
+ * The wrappers every invocation is followed through before any configured in
+ * `allowWrappers`: `sh-ast/analyze`'s defaults, then Bash's `builtin`, then
+ * shells invoked as commands. `resolveArgv0` uses the first entry whose name
+ * matches, so the built-in entries take precedence over a user's.
+ */
+const BUILT_IN_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+    SHELL_WRAPPER,
+];
+/** Schema for a list of distinct, non-empty names. */
+const NAME_LIST_SCHEMA = {
+    type: 'array',
+    items: { type: 'string', minLength: 1 },
+    uniqueItems: true,
+};
+/**
+ * Whether `context` places a command inside a function named in `names`, at
+ * any depth. A function name that is not valid UTF-8 reaches analysis as
+ * bytes (`Uint8Array`), and a configured name is always a string, so such a
+ * function never matches.
+ */
+function isInsideFunction(context, names) {
+    return context.some((frame) => frame.kind === 'function' && typeof frame.name === 'string' && names.has(frame.name));
+}
+/**
+ * The `sh/no-dynamic-invocation` rule module.
+ *
+ * @internal
+ */
+export const noDynamicInvocation = createRule({
+    name: RULE_NAME,
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow commands whose executed command cannot be statically determined',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allowInFunctions: NAME_LIST_SCHEMA,
+                    allowWrappers: NAME_LIST_SCHEMA,
+                },
+                additionalProperties: false,
+            },
+        ],
+        defaultOptions: [{ allowInFunctions: [], allowWrappers: [] }],
+        messages: {
+            dynamicInvocation: 'The command this runs is not known until run time, so the script cannot be statically reviewed. Name the command with a literal word instead.',
+            embeddedCommand: 'This runs shell code embedded in a string, which cannot be statically reviewed. Write the commands directly instead.',
+        },
+    },
+    create(context) {
+        const { sourceCode } = context;
+        // `defaultOptions` guarantees the options object; either list may still be omitted in it.
+        const [{ allowInFunctions = [], allowWrappers = [] }] = context.options;
+        const dispatchers = new Set(allowInFunctions);
+        const transparentWrappers = [
+            ...BUILT_IN_WRAPPERS,
+            ...allowWrappers.map((name) => ({ names: [name] })),
+        ];
+        return {
+            File() {
+                for (const site of sourceCode.getCommandSites()) {
+                    const { effective } = site.resolveInvokedCommand({ transparentWrappers });
+                    if (effective.static)
+                        continue;
+                    if (effective.reason === 'embedded-command') {
+                        context.report({ node: site.node, messageId: 'embeddedCommand' });
+                    }
+                    else if (!isInsideFunction(site.context, dispatchers)) {
+                        context.report({ node: site.node, messageId: 'dynamicInvocation' });
+                    }
+                }
+            },
+        };
+    },
+});