@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/dist/rules/index.js

@@ -0,0 +1,88 @@
+import { noAppendAllRedirect } from './compat/no-append-all-redirect.js';
+import { noAssociativeArrays } from './compat/no-associative-arrays.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-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' });
+                    }
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-eval.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Message ids this rule reports with: `noEval` for any `eval`, and
+ * `dynamicSource` for a `source` / `.` whose path word is not static.
+ *
+ * @internal
+ */
+export type NoEvalMessageId = 'noEval' | 'dynamicSource';
+/**
+ * The `sh/no-eval` rule module.
+ *
+ * @internal
+ */
+export declare const noEval: import("./define-shell-rule.js").ShellRule<[], NoEvalMessageId>;

package/dist/rules/no-eval.js

@@ -0,0 +1,89 @@
+/**
+ * `sh/no-eval`: reports shell code whose text is only assembled at run time,
+ * and therefore cannot be reviewed before it runs.
+ *
+ * Two constructs break eslint-sh's review contract this way:
+ *
+ * - **`eval`**, in any form. The arguments `eval` runs are re-parsed as shell
+ *   code when the line executes, so the code a reviewer reads is not the code
+ *   that runs. Even `eval "literal"` is reported: the literal is still a second
+ *   layer of shell parsing that tooling (this linter included) never sees as
+ *   commands. `eval` is recognized as the *effective* command, after following
+ *   transparent wrappers (`command eval …`, `builtin eval …`, `exec eval …`)
+ *   through `ShellSourceCode.resolveInvokedCommand`.
+ * - **`source` / `.` of a non-static path.** Loading a file whose path is only
+ *   known at run time (`source "$DIR/lib.sh"`, `. $(pick)`) runs code the
+ *   reviewer cannot locate. Like `eval`, it is recognized as the effective
+ *   command, so `command source "$p"` and `builtin . "$p"` report too; the
+ *   path is the word after the effective command in the call's arguments. A path word is static exactly when
+ *   `ShellSourceCode.resolveWordText` resolves it; this rule never decides
+ *   static-ness itself.
+ *
+ * Out of scope, by design: a command word that is itself dynamic
+ * (`$cmd args`) and embedded command strings (`bash -c "$x"`) belong to
+ * `no-dynamic-invocation`. The rule has no options and offers no fix or
+ * suggestion, because no mechanical rewrite of `eval` preserves behavior.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { createRule } from './create-rule.js';
+import { BUILTIN_WRAPPER } from './transparent-wrappers.js';
+/** The registry name of this rule (`sh/no-eval` in a user's config). */
+const RULE_NAME = 'no-eval';
+/**
+ * The wrappers followed to find the command an invocation actually runs:
+ * `sh-ast/analyze`'s defaults (`command`, `exec`, `env`, `sudo`, …) plus
+ * Bash's `builtin`, so `builtin eval …` is recognized as `eval`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** The command names that load and run another file in the current shell. */
+const SOURCE_COMMANDS = new Set(['source', '.']);
+/**
+ * The `sh/no-eval` rule module.
+ *
+ * @internal
+ */
+export const noEval = createRule({
+    name: RULE_NAME,
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `eval`, and `source` or `.` of a path that is not a static literal',
+        },
+        schema: [],
+        messages: {
+            noEval: '`eval` runs text as shell code at run time, so the code it executes cannot be statically reviewed. Write the commands directly instead.',
+            dynamicSource: '`{{command}}` loads a path that is not a static literal, so the code it runs cannot be statically reviewed. Use a literal path instead.',
+        },
+    },
+    create(context) {
+        const { sourceCode } = context;
+        return {
+            CallExpr(node) {
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (!invoked?.effective.static) {
+                    return;
+                }
+                const command = invoked.effective.text;
+                if (command === 'eval') {
+                    context.report({ node, messageId: 'noEval' });
+                    return;
+                }
+                if (!SOURCE_COMMANDS.has(command)) {
+                    return;
+                }
+                // The path is the word right after the effective command, wherever the
+                // wrapper chain placed that command in the call's arguments.
+                const effectiveIndex = invoked.chainIndices.at(-1);
+                const path = effectiveIndex === undefined ? undefined : node.args[effectiveIndex + 1];
+                if (path !== undefined && sourceCode.resolveWordText(path) === null) {
+                    context.report({ node: path, messageId: 'dynamicSource', data: { command } });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-masked-exit-status.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The rule's single options object.
+ *
+ * @internal
+ */
+export interface NoMaskedExitStatusOptions {
+    /** Report only where `errexit` is known to be on. Defaults to `false`. */
+    readonly onlyWithErrexit?: boolean;
+    /**
+     * With `onlyWithErrexit`, count options on the shebang line (`#!/bin/bash -e`)
+     * as enabled, as `require-strict-mode`'s option of the same name does.
+     * Defaults to `false`.
+     */
+    readonly allowShebangOnly?: boolean;
+    /** The declaration builtins to check. Defaults to all five. */
+    readonly builtins?: readonly string[];
+}
+/** Message ids this rule reports with. @internal */
+export type NoMaskedExitStatusMessageId = 'maskedExitStatus' | 'declareThenAssign' | 'assignThenExport' | 'assignThenReadonly';
+/** Built-in rule `sh/no-masked-exit-status`. @internal */
+export declare const noMaskedExitStatus: import("./define-shell-rule.js").ShellRule<[NoMaskedExitStatusOptions], NoMaskedExitStatusMessageId>;