@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/dist/rules/compat/create-compat-rule.d.ts

@@ -0,0 +1,59 @@
+import type { BuiltInRuleMeta } from '../create-rule.js';
+import type { ShellRule, ShellRuleContext, ShellRuleVisitor } from '../define-shell-rule.js';
+import type { CompatFeature, GateDescription } from './version-gates.js';
+/**
+ * What a compat rule hands to {@link createCompatRule}.
+ *
+ * @internal
+ */
+export interface CompatRuleSpec<MessageIds extends string> {
+    /**
+     * The registry name, always under the `compat/` namespace
+     * (`compat/no-mapfile`, written `sh/compat/no-mapfile` in a config). Its
+     * docs page is `docs/rules/compat/<name>.md`.
+     */
+    readonly name: `compat/${string}`;
+    /** The gate-table row this rule enforces. */
+    readonly feature: CompatFeature;
+    /** The rule's metadata; `schema` is fixed to `[]` by the factory. */
+    readonly meta: Omit<BuiltInRuleMeta<[], MessageIds>, 'schema'>;
+    /**
+     * Builds the listeners for a file in which the feature is unavailable.
+     * `gate` describes the requirement and the file's target for messages.
+     */
+    readonly create: (context: ShellRuleContext<[], MessageIds>, gate: GateDescription) => ShellRuleVisitor;
+}
+/**
+ * Builds a `compat/*` rule: a built-in rule (through `createRule`) that is
+ * a no-op unless the file's `languageOptions` make `spec.feature`
+ * unavailable.
+ *
+ * @internal
+ */
+export declare function createCompatRule<MessageIds extends string>(spec: CompatRuleSpec<MessageIds>): ShellRule<[], MessageIds>;
+/**
+ * What a compat rule that reports several gate-table rows hands to
+ * {@link createMultiFeatureCompatRule}: one rule for one construct whose
+ * minimum version depends on how it is written (such as `${v@op}`, where
+ * the operator decides the release).
+ *
+ * @internal
+ */
+export interface MultiFeatureCompatRuleSpec<MessageIds extends string> extends Omit<CompatRuleSpec<MessageIds>, 'feature' | 'create'> {
+    /** The gate-table rows this rule enforces. */
+    readonly features: readonly CompatFeature[];
+    /**
+     * Builds the listeners for a file in which at least one of `features` is
+     * unavailable. `gates` holds a {@link GateDescription} for exactly the
+     * unavailable ones, so a feature missing from it must not be reported.
+     */
+    readonly create: (context: ShellRuleContext<[], MessageIds>, gates: ReadonlyMap<CompatFeature, GateDescription>) => ShellRuleVisitor;
+}
+/**
+ * Builds a `compat/*` rule over several gate-table rows: a no-op unless the
+ * file's `languageOptions` make at least one of `spec.features`
+ * unavailable, and then given the description of each unavailable one.
+ *
+ * @internal
+ */
+export declare function createMultiFeatureCompatRule<MessageIds extends string>(spec: MultiFeatureCompatRuleSpec<MessageIds>): ShellRule<[], MessageIds>;

package/dist/rules/compat/create-compat-rule.js

@@ -0,0 +1,65 @@
+/**
+ * `createCompatRule`: the factory every `compat/*` rule is built with.
+ *
+ * A compat rule reports one gated feature (a row of the gate table in
+ * `./version-gates.ts`) wherever a file uses it while its `languageOptions`
+ * say the feature is unavailable. The factory owns the gate decision, so no
+ * compat rule reads `shellVersion` or `dialect` itself:
+ *
+ * - when {@link isFeatureAvailable} says the feature is available, the rule
+ *   returns no listeners at all, so it costs nothing and cannot report;
+ * - otherwise the rule's own `create()` runs and receives the
+ *   {@link GateDescription} (`required`, `target`) to interpolate into its
+ *   messages as `{{required}}` and `{{target}}`.
+ *
+ * Compat rules have no options: what they gate on is the language options,
+ * which the user already sets once for the whole file set.
+ */
+import { createRule } from '../create-rule.js';
+import { describeGate, isFeatureAvailable } from './version-gates.js';
+/**
+ * Builds a `compat/*` rule: a built-in rule (through `createRule`) that is
+ * a no-op unless the file's `languageOptions` make `spec.feature`
+ * unavailable.
+ *
+ * @internal
+ */
+export function createCompatRule(spec) {
+    const { name, feature, meta, create } = spec;
+    return createRule({
+        name,
+        meta: { ...meta, schema: [] },
+        create(context) {
+            const { languageOptions } = context;
+            if (isFeatureAvailable(feature, languageOptions))
+                return {};
+            return create(context, describeGate(feature, languageOptions));
+        },
+    });
+}
+/**
+ * Builds a `compat/*` rule over several gate-table rows: a no-op unless the
+ * file's `languageOptions` make at least one of `spec.features`
+ * unavailable, and then given the description of each unavailable one.
+ *
+ * @internal
+ */
+export function createMultiFeatureCompatRule(spec) {
+    const { name, features, meta, create } = spec;
+    return createRule({
+        name,
+        meta: { ...meta, schema: [] },
+        create(context) {
+            const { languageOptions } = context;
+            const gates = new Map();
+            for (const feature of features) {
+                if (!isFeatureAvailable(feature, languageOptions)) {
+                    gates.set(feature, describeGate(feature, languageOptions));
+                }
+            }
+            if (gates.size === 0)
+                return {};
+            return create(context, gates);
+        },
+    });
+}

package/dist/rules/compat/declaration-options.d.ts

@@ -0,0 +1,19 @@
+import type { ShellSourceCode } from '../../language/shell-source-code.js';
+import type { ShellNode } from '../../language/syntax-view.js';
+import type { ShellRuleVisitor } from '../define-shell-rule.js';
+/**
+ * `declare`, `typeset` and `local`: the commands for an option that `local`
+ * accepts as well, which is every `declare` option except `-g`, `-f` and
+ * `-F`.
+ *
+ * @internal
+ */
+export declare const DECLARATION_AND_LOCAL_COMMANDS: ReadonlySet<string>;
+/**
+ * Builds the listeners that call `report(optionWord, command, optionWords)` for each
+ * `declare` / `typeset` (or each of `commands`) whose option cluster contains
+ * `flag`: one letter, or a character class such as `[lu]` for either of two.
+ *
+ * @internal
+ */
+export declare function declarationFlagVisitor(sourceCode: ShellSourceCode, flag: string, report: (option: ShellNode, command: string, options: readonly string[]) => void, commands?: ReadonlySet<string>): ShellRuleVisitor;

package/dist/rules/compat/declaration-options.js

@@ -0,0 +1,110 @@
+/**
+ * Shared detection of an option flag on `declare` / `typeset`, for the compat
+ * rules that gate one flag of those builtins (`-A` associative arrays, `-g`
+ * global scope).
+ *
+ * What is read: the option words of a `declare` or `typeset` command, up to
+ * its first operand (a name, `--`, or a word that is not static), exactly as
+ * the builtin's option parser stops. An option word matches when it is a `-`
+ * cluster containing the flag (`-A`, `-gA`, `-Ar`). The command is found both
+ * as Bash's declaration clause and as an ordinary command (POSIX mode parses
+ * `declare -A m` as one, and so does a wrapper such as `builtin declare -A m`).
+ * By default `local`, `readonly` and `export` are outside scope; a caller
+ * gating an option `local` shares (`-n`, `-l`, `-u`) adds `local` with
+ * {@link DECLARATION_AND_LOCAL_COMMANDS}.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+/** The declaration commands that take option clusters. */
+const DECLARATION_COMMANDS = new Set(['declare', 'typeset']);
+/**
+ * `declare`, `typeset` and `local`: the commands for an option that `local`
+ * accepts as well, which is every `declare` option except `-g`, `-f` and
+ * `-F`.
+ *
+ * @internal
+ */
+export const DECLARATION_AND_LOCAL_COMMANDS = new Set([
+    'declare',
+    'typeset',
+    'local',
+]);
+/**
+ * The wrappers followed to find a declaration command written as an ordinary
+ * command: `sh-ast/analyze`'s defaults (which include `command`) plus Bash's
+ * `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/**
+ * Finds the option word carrying `flag` among a declaration command's
+ * arguments (the words after the command name), together with all of the
+ * command's option words, or `undefined` when no option word carries it.
+ * Option processing stops at the first operand, at `--`, and at a word that
+ * is not static, because what follows it may not be an option.
+ */
+function findFlagOption(sourceCode, flagPattern, args) {
+    let report;
+    const options = [];
+    for (const { report: node, word } of args) {
+        if (word === undefined)
+            break;
+        const text = sourceCode.resolveWordText(word);
+        if (text === null || text === '--' || !/^[-+]./u.test(text))
+            break;
+        options.push(text);
+        if (report === undefined && flagPattern.test(text))
+            report = node;
+    }
+    return report === undefined ? undefined : { report, options };
+}
+/**
+ * The arguments of a `DeclClause` as candidates. An option such as `-A` is an
+ * `Assign` with no `name` and the option word as its `value`; an `Assign` that
+ * has a `name` is an operand and contributes no word.
+ */
+function declClauseArgs(node) {
+    return node.args.map((assign) => {
+        const word = assign.name === undefined ? assign.value : undefined;
+        return { report: word ?? assign, word };
+    });
+}
+/**
+ * Builds the listeners that call `report(optionWord, command, optionWords)` for each
+ * `declare` / `typeset` (or each of `commands`) whose option cluster contains
+ * `flag`: one letter, or a character class such as `[lu]` for either of two.
+ *
+ * @internal
+ */
+export function declarationFlagVisitor(sourceCode, flag, report, commands = DECLARATION_COMMANDS) {
+    const flagPattern = new RegExp(`^-[a-zA-Z]*${flag}[a-zA-Z]*$`, 'u');
+    return {
+        DeclClause(node) {
+            const command = node.variant?.value;
+            if (command === undefined || !commands.has(command))
+                return;
+            const option = findFlagOption(sourceCode, flagPattern, declClauseArgs(node));
+            if (option !== undefined)
+                report(option.report, command, option.options);
+        },
+        CallExpr(node) {
+            const invoked = sourceCode.resolveInvokedCommand(node, {
+                transparentWrappers: TRANSPARENT_WRAPPERS,
+            });
+            if (invoked?.effective.static !== true)
+                return;
+            const command = invoked.effective.text;
+            if (!commands.has(command))
+                return;
+            // `chainIndices` index `node.args` directly, so slice before filtering.
+            const operands = node.args
+                .slice((invoked.chainIndices.at(-1) ?? 0) + 1)
+                .map((word) => ({ report: word, word }));
+            const option = findFlagOption(sourceCode, flagPattern, operands);
+            if (option !== undefined)
+                report(option.report, command, option.options);
+        },
+    };
+}

package/dist/rules/compat/no-append-all-redirect.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Message ids this rule reports with: `appendAll` for the report and
+ * `useAppendRedirects` for its suggestion.
+ *
+ * @internal
+ */
+export type NoAppendAllRedirectMessageId = 'appendAll' | 'useAppendRedirects';
+/**
+ * The `sh/compat/no-append-all-redirect` rule module.
+ *
+ * @internal
+ */
+export declare const noAppendAllRedirect: import("../define-shell-rule.js").ShellRule<[], NoAppendAllRedirectMessageId>;

package/dist/rules/compat/no-append-all-redirect.js

@@ -0,0 +1,73 @@
+/**
+ * `sh/compat/no-append-all-redirect`: reports the `&>>` redirection, which
+ * appends both stdout and stderr to a file, in files whose target shell
+ * lacks it, that is, Bash older than 4.0 (macOS's stock `/bin/bash` is 3.2)
+ * and POSIX sh.
+ *
+ * Bash 3.2 rejects `&>>` as a syntax error, so the whole script fails to
+ * run. POSIX sh reads `cmd &>> file` as `cmd &` (run in the background)
+ * followed by an empty command that appends nothing to `file`. The portable
+ * spelling is `>> file 2>&1`, which the Bash manual defines `&>>` to mean.
+ *
+ * The rule offers that rewrite as a suggestion: the operator becomes `>>`
+ * and ` 2>&1` follows the target word, so the redirection keeps its place
+ * among the command's other redirections.
+ *
+ * What is read: a `Redirect` whose operator is `&>>`. The two-way `&>` and
+ * the plain `>>`, `>&` and `2>&1` are different operators and are not
+ * reported, and neither is any of them inside quotes. The report is on the
+ * whole redirection.
+ */
+import { AppAll } from 'sh-ast';
+import { createCompatRule } from './create-compat-rule.js';
+/** The operator as written. */
+const OPERATOR = '&>>';
+/**
+ * The `sh/compat/no-append-all-redirect` rule module.
+ *
+ * @internal
+ */
+export const noAppendAllRedirect = createCompatRule({
+    name: 'compat/no-append-all-redirect',
+    feature: 'appendAllRedirect',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow the `&>>` redirection when the target shell lacks it',
+        },
+        messages: {
+            appendAll: '`&>>` needs {{required}}, but this file targets {{target}}. Append both streams with `>> file 2>&1` instead.',
+            useAppendRedirects: 'Replace `&>> {{file}}` with `>> {{file}} 2>&1`.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        return {
+            Redirect(node) {
+                if (node.op !== AppAll)
+                    return;
+                const [start] = sourceCode.getRange(node);
+                const { word } = node;
+                const exact = word !== undefined && sourceCode.text.startsWith(OPERATOR, start);
+                context.report({
+                    node,
+                    messageId: 'appendAll',
+                    data: { ...gate },
+                    suggest: exact
+                        ? [
+                            {
+                                messageId: 'useAppendRedirects',
+                                data: { file: sourceCode.getText(word) },
+                                fix: (fixer) => [
+                                    fixer.replaceTextRange([start, start + OPERATOR.length], '>>'),
+                                    fixer.insertTextAfter(word, ' 2>&1'),
+                                ],
+                            },
+                        ]
+                        : [],
+                });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-associative-arrays.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Message ids this rule reports with.
+ *
+ * @internal
+ */
+export type NoAssociativeArraysMessageId = 'associativeArray';
+/**
+ * The `sh/compat/no-associative-arrays` rule module.
+ *
+ * @internal
+ */
+export declare const noAssociativeArrays: import("../define-shell-rule.js").ShellRule<[], "associativeArray">;

package/dist/rules/compat/no-associative-arrays.js

@@ -0,0 +1,39 @@
+/**
+ * `sh/compat/no-associative-arrays`: reports associative-array declarations
+ * (`declare -A`, `typeset -A`) in files whose target shell lacks them, that
+ * is, Bash older than 4.0 (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 3.2 rejects `-A` as an invalid option, so the script fails where the
+ * array is declared, and every later `${map[key]}` silently indexes an
+ * ordinary array by the arithmetic value of `key`. The message suggests the
+ * portable alternative: move the keyed lookup into `jq` over a JSON object.
+ *
+ * What is read: `declare`/`typeset` option clusters containing `A` (`-A`,
+ * `-gA`, `-Ar`), found as `declarationFlagVisitor` defines. `local -A`,
+ * `readonly -A` and `export -A` are outside this rule's scope.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+import { declarationFlagVisitor } from './declaration-options.js';
+/**
+ * The `sh/compat/no-associative-arrays` rule module.
+ *
+ * @internal
+ */
+export const noAssociativeArrays = createCompatRule({
+    name: 'compat/no-associative-arrays',
+    feature: 'associativeArrays',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow associative arrays (`declare -A`, `typeset -A`) when the target shell lacks them',
+        },
+        messages: {
+            associativeArray: 'Associative arrays (`{{command}} -A`) need {{required}}, but this file targets {{target}}. Consider moving the keyed lookup into `jq`, for example `jq -r --arg k "$key" \'.[$k]\' map.json`.',
+        },
+    },
+    create(context, gate) {
+        return declarationFlagVisitor(context.sourceCode, 'A', (node, command) => {
+            context.report({ node, messageId: 'associativeArray', data: { ...gate, command } });
+        });
+    },
+});

package/dist/rules/compat/no-brace-sequence-padding-step.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Message ids this rule reports with: `padded` for a zero-padded sequence on
+ * a Bash that expands it without the padding, `stepped` for a stepped one on
+ * a Bash that leaves it literal, and `posixPadded` / `posixStepped` for the
+ * same two under a POSIX target, where the result depends on the shell.
+ *
+ * @internal
+ */
+export type NoBraceSequencePaddingStepMessageId = 'padded' | 'stepped' | 'posixPadded' | 'posixStepped';
+/**
+ * The `sh/compat/no-brace-sequence-padding-step` rule module.
+ *
+ * @internal
+ */
+export declare const noBraceSequencePaddingStep: import("../define-shell-rule.js").ShellRule<[], NoBraceSequencePaddingStepMessageId>;