@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/dist/rules/compat/no-negative-array-index.js

@@ -0,0 +1,123 @@
+/**
+ * `sh/compat/no-negative-array-index`: reports negative indexed-array
+ * subscripts written as a literal (`${arr[-1]}`, `arr[-2]=x`, `${#arr[-1]}`)
+ * in files whose target shell lacks them, that is, Bash older than 4.3
+ * (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 3.2 evaluates `-1` as the arithmetic value minus one and fails with
+ * "bad array subscript", so the read yields nothing and the assignment is
+ * refused. The message suggests the portable alternative: count from the
+ * array length, `${arr[$((${#arr[@]}-1))]}`.
+ *
+ * The suggestion rewrites exactly a bare `${NAME[-N]}` read to
+ * `${NAME[$((${#NAME[@]}-N))]}`. Negative subscripts count back from the
+ * highest assigned index plus one, while `${#NAME[@]}` counts set elements,
+ * so the two agree only for arrays without holes; the suggestion message says
+ * so. Assignments and other expansion forms are reported without a suggestion.
+ *
+ * What is read: an `Index` that is a unary minus applied to a static decimal
+ * integer, on a `ParamExp` or an `Assign`. A computed subscript such as
+ * `-$n` is not a literal and is not reported, and neither is `-0`, which is
+ * zero. A `ParamExp` or `Assign` subscript is read from the syntax tree, so
+ * its operand can be any arithmetic node (`-(1)` holds a parenthesized one);
+ * only a plain word is resolved.
+ *
+ * Unsetting an element (`unset arr[-1]`, quoted or not) is reported from the
+ * `unset` command's operand text, since the parser keeps that operand as an
+ * ordinary word; option words (`-v`) never match an element name.
+ */
+import { Minus } from 'sh-ast';
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+import { createCompatRule } from './create-compat-rule.js';
+/** A bare negative-subscript read, the only shape the suggestion rewrites. */
+const BARE_READ = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\[\s*-\s*(\d+)\s*\]\}$/u;
+/**
+ * The wrappers followed to find an `unset` command: `sh-ast/analyze`'s
+ * defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** An `unset` operand naming an element by a literal negative subscript. */
+const UNSET_NEGATIVE = /^[A-Za-z_][A-Za-z0-9_]*\[\s*-\s*\d+\s*\]$/u;
+/**
+ * The `sh/compat/no-negative-array-index` rule module.
+ *
+ * @internal
+ */
+export const noNegativeArrayIndex = createCompatRule({
+    name: 'compat/no-negative-array-index',
+    feature: 'negativeArrayIndex',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow negative array subscripts (`${arr[-1]}`) when the target shell lacks them',
+        },
+        messages: {
+            negativeIndex: 'Negative array subscripts need {{required}}, but this file targets {{target}}. Count from the length instead, for example `${arr[$((${#arr[@]}-1))]}`.',
+            useArrayLength: 'Replace with `${{{name}}[$((${#{{name}}[@]}-{{n}}))]}` (the two differ only for an array with unset elements).',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        /** Whether `index` is a unary minus on a static decimal integer. */
+        function isNegativeLiteral(index) {
+            if (index?.type !== 'UnaryArithm' || index.op !== Minus)
+                return false;
+            const operand = index.x;
+            // The operand may be any arithmetic node (`-(1)` holds a ParenArithm);
+            // only a Word can be resolved, and `-0` is zero, not a negative index.
+            if (operand?.type !== 'Word')
+                return false;
+            const digits = sourceCode.resolveWordText(operand) ?? '';
+            return /^\d+$/u.test(digits) && /[1-9]/u.test(digits);
+        }
+        return {
+            CallExpr(node) {
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (invoked?.effective.static !== true || invoked.effective.text !== 'unset')
+                    return;
+                // `chainIndices` index `node.args` directly, so slice before filtering.
+                for (const word of node.args.slice((invoked.chainIndices.at(-1) ?? 0) + 1)) {
+                    // An unquoted `a[-1]` holds a glob bracket, so it is not "static"; its
+                    // written text is what names the element.
+                    const text = sourceCode.resolveWordText(word) ?? sourceCode.getText(word);
+                    if (text === '--')
+                        continue;
+                    if (UNSET_NEGATIVE.test(text) && /[1-9]/u.test(text)) {
+                        context.report({ node: word, messageId: 'negativeIndex', data: { ...gate } });
+                    }
+                }
+            },
+            ParamExp(node) {
+                if (!isNegativeLiteral(node.index))
+                    return;
+                const match = BARE_READ.exec(sourceCode.getText(node));
+                context.report({
+                    node,
+                    messageId: 'negativeIndex',
+                    data: { ...gate },
+                    suggest: match === null
+                        ? []
+                        : [
+                            {
+                                messageId: 'useArrayLength',
+                                data: { name: match[1], n: match[2] },
+                                fix: (fixer) => fixer.replaceText(node, `\${${match[1]}[$((\${#${match[1]}[@]}-${match[2]}))]}`),
+                            },
+                        ],
+                });
+            },
+            Assign(node) {
+                if (!isNegativeLiteral(node.index))
+                    return;
+                context.report({ node, messageId: 'negativeIndex', data: { ...gate } });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-nounset-empty-array.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Message ids this rule reports with: `emptyArray` for the report and
+ * `guardExpansion` for its suggestion.
+ *
+ * @internal
+ */
+export type NoNounsetEmptyArrayMessageId = 'emptyArray' | 'guardExpansion';
+/**
+ * The `sh/compat/no-nounset-empty-array` rule module.
+ *
+ * @internal
+ */
+export declare const noNounsetEmptyArray: import("../define-shell-rule.js").ShellRule<[], NoNounsetEmptyArrayMessageId>;

package/dist/rules/compat/no-nounset-empty-array.js

@@ -0,0 +1,158 @@
+/**
+ * `sh/compat/no-nounset-empty-array`: reports whole-array expansions
+ * (`"${a[@]}"`, `${a[*]}`) in a file that turns on `set -u`, when its target
+ * shell is Bash older than 4.4 (macOS's stock `/bin/bash` is 3.2) or POSIX
+ * sh.
+ *
+ * The syntax is in every Bash, but through 4.3 expanding an empty array
+ * while `nounset` is on aborts the script with "unbound variable". Bash 4.4
+ * is the first release where it expands to nothing. This is the classic
+ * "works on Linux CI, breaks on a Mac" failure for a script that passes an
+ * optional, possibly empty, argument array under `set -euo pipefail`.
+ *
+ * The suggestion rewrites a word that is exactly `"${a[@]}"` to
+ * `${a[@]+"${a[@]}"}`, which expands to nothing for an empty array and to the
+ * same words otherwise, and a word that is exactly `"${a[*]}"` to
+ * `"${a[*]-}"`, which keeps the one (empty) word `"${a[*]}"` gives for an
+ * empty array. Other spellings (unquoted, or inside a longer word) are
+ * reported without one. POSIX sh has no arrays at all; under
+ * `dialect: "posix"` the parser rejects array syntax, so the rule never sees
+ * one there.
+ *
+ * What is read:
+ *
+ * - whether the file turns `nounset` on anywhere: a `set` command that
+ *   enables it (`set -u`, `set -eu`, `set -o nounset`), or a shebang that
+ *   passes the flag (`#!/bin/bash -eu`). Where in the file that happens is
+ *   not considered, since a function defined before `set -u` can run after
+ *   it;
+ * - every `${name[@]}` and `${name[*]}` with no operator, except inside
+ *   `${name[@]+…}` or `${name[@]:+…}` of the same array (the guard this rule
+ *   suggests), whose word Bash expands only when the array is set. `${#a[@]}`,
+ *   `${!a[@]}` and `${a[@]-default}` work on an empty array under `set -u` in
+ *   every Bash, so they are not reported. The slice `${a[@]:1}` and the
+ *   replacement `${a[@]/x/y}` were observed to work on Bash 3.2 to 4.1 and
+ *   fail only on 4.2 and 4.3, which a minimum-version gate cannot express, so
+ *   they are not reported either.
+ */
+import { AlternateUnset, AlternateUnsetOrNull } from 'sh-ast';
+import { createCompatRule } from './create-compat-rule.js';
+import { parseSetArguments, shebangOptionChanges } from '../set-options.js';
+/** A shell variable name. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/**
+ * The guarded spelling of `"${name[subscript]}"`: `${name[@]+"${name[@]}"}`
+ * for `@` (no words for an empty array, the same words otherwise) and
+ * `"${name[*]-}"` for `*` (one empty word for an empty array, as Bash 4.4
+ * gives, and the same joined word otherwise).
+ */
+function guardedExpansion(name, subscript) {
+    return subscript === '@' ? `\${${name}[@]+"\${${name}[@]}"}` : `"\${${name}[*]-}"`;
+}
+/** Whether `changes` turn `nounset` on. */
+function enablesNounset(changes) {
+    return changes.some((change) => change.option === 'nounset' && change.enable);
+}
+/**
+ * The `sh/compat/no-nounset-empty-array` rule module.
+ *
+ * @internal
+ */
+export const noNounsetEmptyArray = createCompatRule({
+    name: 'compat/no-nounset-empty-array',
+    feature: 'nounsetEmptyArray',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow whole-array expansions under `set -u` when the target shell aborts on an empty array',
+        },
+        messages: {
+            emptyArray: 'If this array is empty, `${{{name}}[{{subscript}}]}` under `set -u` needs {{required}}, but this file targets {{target}}, where it aborts with "unbound variable". Guard it, for example `{{example}}`.',
+            guardExpansion: 'Replace with `{{replacement}}`.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        let nounset = enablesNounset(shebangOptionChanges(sourceCode.text));
+        const candidates = [];
+        /** The `@` or `*` of a whole-array subscript, or `undefined`. */
+        function wholeArraySubscript(index) {
+            if (index?.type !== 'Word')
+                return undefined;
+            const text = sourceCode.resolveWordText(index) ?? sourceCode.getText(index);
+            return text === '@' || text === '*' ? text : undefined;
+        }
+        /**
+         * Whether `node` sits inside `${name[…]+…}` or `${name[…]:+…}` of the same
+         * array, as in the guard `${a[@]+"${a[@]}"}`: Bash expands that inner
+         * word only when the array is set, so it cannot abort.
+         */
+        function insideOwnGuard(node, name) {
+            for (let up = sourceCode.getParent(node); up !== undefined; up = sourceCode.getParent(up)) {
+                if (up.type === 'ParamExp' &&
+                    up.param?.value === name &&
+                    (up.exp?.op === AlternateUnset || up.exp?.op === AlternateUnsetOrNull)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        /**
+         * The quoted expansion `node` is when it is the whole of a word that is
+         * exactly `"${name[@]}"` or `"${name[*]}"`, or `undefined`.
+         */
+        function wholeQuotedWord(node) {
+            const quoted = sourceCode.getParent(node);
+            if (quoted?.type !== 'DblQuoted' || quoted.parts.length !== 1)
+                return undefined;
+            const word = sourceCode.getParent(quoted);
+            return word?.type === 'Word' && word.parts.length === 1 ? quoted : undefined;
+        }
+        return {
+            CallExpr(node) {
+                if (sourceCode.getCommandName(node) !== 'set')
+                    return;
+                const args = node.args.slice(1).map((word) => sourceCode.resolveWordText(word));
+                if (enablesNounset(parseSetArguments(args).changes))
+                    nounset = true;
+            },
+            ParamExp(node) {
+                const name = node.param?.value;
+                if (name === undefined || !IDENTIFIER.test(name))
+                    return;
+                if (node.exp !== undefined || node.slice !== undefined || node.repl !== undefined)
+                    return;
+                if (node.length || node.excl || node.width || node.isset || node.modifiers.length > 0) {
+                    return;
+                }
+                const subscript = wholeArraySubscript(node.index);
+                if (subscript === undefined || insideOwnGuard(node, name))
+                    return;
+                candidates.push({ node, name, subscript });
+            },
+            'File:exit'() {
+                if (!nounset)
+                    return;
+                for (const { node, name, subscript } of candidates) {
+                    const replacement = guardedExpansion(name, subscript);
+                    const quoted = wholeQuotedWord(node);
+                    context.report({
+                        node,
+                        messageId: 'emptyArray',
+                        data: { ...gate, name, subscript, example: replacement },
+                        suggest: quoted === undefined
+                            ? []
+                            : [
+                                {
+                                    messageId: 'guardExpansion',
+                                    data: { replacement },
+                                    fix: (fixer) => fixer.replaceText(quoted, replacement),
+                                },
+                            ],
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/compat/no-parameter-transformation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Message ids this rule reports with: `transformation` names an alternative,
+ * `transformationNoAlternative` has none to offer.
+ *
+ * @internal
+ */
+export type NoParameterTransformationMessageId = 'transformation' | 'transformationNoAlternative';
+/**
+ * The `sh/compat/no-parameter-transformation` rule module.
+ *
+ * @internal
+ */
+export declare const noParameterTransformation: import("../define-shell-rule.js").ShellRule<[], NoParameterTransformationMessageId>;

package/dist/rules/compat/no-parameter-transformation.js

@@ -0,0 +1,123 @@
+/**
+ * `sh/compat/no-parameter-transformation`: reports the parameter
+ * transformations `${v@op}` in files whose target shell lacks the operator.
+ * The minimum Bash depends on the operator:
+ *
+ * - `@Q`, `@E`, `@P`, `@A`, `@a`: Bash 4.4;
+ * - `@U`, `@u`, `@L` and `@K`: Bash 5.1;
+ * - `@k`: Bash 5.2.
+ *
+ * POSIX sh has none of them. An older Bash fails with "bad substitution"
+ * when the word is expanded. The message names a portable alternative where
+ * one exists for the target: `printf '%q'` for `@Q` (it quotes differently,
+ * but `eval` reads it back as the same value), `printf '%b'` for `@E`,
+ * `declare -p` for `@A`, and for the case operators the Bash 4.0 case
+ * expansions (`${v^^}`, `${v^}`, `${v,,}`) on a Bash that has them, or `tr`
+ * otherwise. `printf '%q'` and `declare -p` are not POSIX, so a POSIX target
+ * is not offered them.
+ *
+ * What is read: a `ParamExp` whose expansion operator is `@` followed by one
+ * of the letters above. The report is on the whole expansion.
+ */
+import { OtherParamOps } from 'sh-ast';
+import { createMultiFeatureCompatRule } from './create-compat-rule.js';
+import { TO_LOWER, TO_UPPER, trExample } from './no-case-modification.js';
+import { isFeatureAvailable } from './version-gates.js';
+/** Each operator letter's gate-table row. */
+const OPERATOR_FEATURES = new Map([
+    ['Q', 'parameterTransformation'],
+    ['E', 'parameterTransformation'],
+    ['P', 'parameterTransformation'],
+    ['A', 'parameterTransformation'],
+    ['a', 'parameterTransformation'],
+    ['U', 'parameterTransformationCase'],
+    ['u', 'parameterTransformationCase'],
+    ['L', 'parameterTransformationCase'],
+    ['K', 'parameterTransformationQuotedKeys'],
+    ['k', 'parameterTransformationKeys'],
+]);
+/** The case operators and their equivalents. */
+const CASE_EQUIVALENTS = new Map([
+    ['U', { expansion: '^^', upper: true, all: true }],
+    ['u', { expansion: '^', upper: true, all: false }],
+    ['L', { expansion: ',,', upper: false, all: true }],
+]);
+/**
+ * The `sh/compat/no-parameter-transformation` rule module.
+ *
+ * @internal
+ */
+export const noParameterTransformation = createMultiFeatureCompatRule({
+    name: 'compat/no-parameter-transformation',
+    features: [...new Set(OPERATOR_FEATURES.values())],
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow parameter transformations (`${v@Q}`, `${v@U}` and the others) when the target shell lacks the operator',
+        },
+        messages: {
+            transformation: '`${…@{{operator}}}` needs {{required}}, but this file targets {{target}}. Use {{alternative}} instead.',
+            transformationNoAlternative: '`${…@{{operator}}}` needs {{required}}, but this file targets {{target}}, which has no equivalent expansion; restructure the code that needs it.',
+        },
+    },
+    create(context, gates) {
+        const { sourceCode, languageOptions } = context;
+        const posix = sourceCode.dialect === 'posix';
+        const caseExpansions = isFeatureAvailable('caseModification', languageOptions);
+        /** The alternative shown for `operator` on `name`, or `undefined`. */
+        function alternative(operator, name) {
+            const value = `"$${name}"`;
+            if (operator === 'Q') {
+                return posix
+                    ? undefined
+                    : `\`printf '%q' ${value}\` (it quotes differently, but \`eval\` reads it back as the same value)`;
+            }
+            if (operator === 'E')
+                return `\`printf '%b' ${value}\``;
+            if (operator === 'A') {
+                return posix
+                    ? undefined
+                    : `\`declare -p ${name}\` (it prints the declaration; capture it and \`eval\` it to re-create the variable)`;
+            }
+            const equivalent = CASE_EQUIVALENTS.get(operator);
+            if (equivalent === undefined)
+                return undefined;
+            if (caseExpansions)
+                return `\`"\${${name}${equivalent.expansion}}"\``;
+            const example = trExample(name, {
+                operator: equivalent.expansion,
+                all: equivalent.all,
+                tr: equivalent.upper ? TO_UPPER : TO_LOWER,
+            });
+            return `\`tr\`, for example ${example}`;
+        }
+        return {
+            ParamExp(node) {
+                const { exp } = node;
+                if (exp?.op !== OtherParamOps || exp.word === undefined)
+                    return;
+                const operator = sourceCode.resolveWordText(exp.word);
+                if (operator === null)
+                    return;
+                const feature = OPERATOR_FEATURES.get(operator);
+                const gate = feature === undefined ? undefined : gates.get(feature);
+                if (gate === undefined)
+                    return;
+                const advice = alternative(operator, node.param?.value ?? 'v');
+                if (advice === undefined) {
+                    context.report({
+                        node,
+                        messageId: 'transformationNoAlternative',
+                        data: { ...gate, operator },
+                    });
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'transformation',
+                    data: { ...gate, operator, alternative: advice },
+                });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-pipe-all.d.ts

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

package/dist/rules/compat/no-pipe-all.js

@@ -0,0 +1,68 @@
+/**
+ * `sh/compat/no-pipe-all`: reports the `|&` pipe, shorthand for `2>&1 |`, 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.
+ * The portable spelling is `cmd 2>&1 | other`. The Bash manual defines `|&`
+ * as that implicit `2>&1`, applied after any redirections the left-hand
+ * command writes, so writing `2>&1` just before the `|` is exactly
+ * equivalent. The rule offers that rewrite as a suggestion.
+ *
+ * What is read: a pipeline (`BinaryCmd`) whose operator is `|&`. A plain `|`,
+ * `||`, `&&`, a background `&`, and any of these inside quotes are other
+ * syntax and are not reported. The report is on the `|&` operator.
+ */
+import { PipeAll } from 'sh-ast';
+import { createCompatRule } from './create-compat-rule.js';
+import { operatorRange } from './operator-range.js';
+/**
+ * The `sh/compat/no-pipe-all` rule module.
+ *
+ * @internal
+ */
+export const noPipeAll = createCompatRule({
+    name: 'compat/no-pipe-all',
+    feature: 'pipeAll',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow the `|&` pipe when the target shell lacks it',
+        },
+        messages: {
+            pipeAll: '`|&` needs {{required}}, but this file targets {{target}}. Write `cmd 2>&1 | other` instead.',
+            useStderrRedirect: 'Replace `|&` with `2>&1 |`.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        return {
+            BinaryCmd(node) {
+                if (node.op !== PipeAll)
+                    return;
+                const range = operatorRange(sourceCode, node, '|&');
+                if (range === undefined) {
+                    context.report({ node, messageId: 'pipeAll', data: { ...gate } });
+                    return;
+                }
+                const [start, end] = range;
+                // `cmd|&other` has no space before the operator, and `2>&1` must not
+                // join the command's last word.
+                const before = sourceCode.text[start - 1];
+                const separator = before === ' ' || before === '\t' ? '' : ' ';
+                context.report({
+                    loc: { start: sourceCode.getLocFromIndex(start), end: sourceCode.getLocFromIndex(end) },
+                    messageId: 'pipeAll',
+                    data: { ...gate },
+                    suggest: [
+                        {
+                            messageId: 'useStderrRedirect',
+                            fix: (fixer) => fixer.replaceTextRange(range, `${separator}2>&1 |`),
+                        },
+                    ],
+                });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-printf-time-format.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Message ids this rule reports with.
+ *
+ * @internal
+ */
+export type NoPrintfTimeFormatMessageId = 'printfTime';
+/**
+ * The `sh/compat/no-printf-time-format` rule module.
+ *
+ * @internal
+ */
+export declare const noPrintfTimeFormat: import("../define-shell-rule.js").ShellRule<[], "printfTime">;

package/dist/rules/compat/no-printf-time-format.js

@@ -0,0 +1,99 @@
+/**
+ * `sh/compat/no-printf-time-format`: reports `printf`'s `%(fmt)T` date
+ * format in files whose target shell lacks it, that is, Bash older than 4.2
+ * (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 4.1 rejects the directive with "invalid format character", so
+ * nothing is printed. The message suggests the portable alternative for the
+ * current time: `date '+fmt'`, which takes the same `strftime` format.
+ *
+ * What is read: a `printf` command (after transparent wrappers such as
+ * `builtin`) whose format argument, after an optional `-v name` and `--`, is
+ * a static word containing a `%(…)T` directive. The format is scanned as
+ * `printf` reads it: `%%` is a literal percent sign, and a directive may
+ * carry flags, a width and a precision before the `(`. A format that is not
+ * static cannot be read, and is not reported. The report is on the format
+ * word.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+import { createCompatRule } from './create-compat-rule.js';
+/**
+ * The wrappers followed to find the `printf` command: `sh-ast/analyze`'s
+ * defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** A conversion's flags, width and precision, as `printf` accepts them. */
+const DIRECTIVE_PREFIX = /^[-+ #0']*(?:\d+|\*)?(?:\.(?:\d+|\*)?)?/u;
+/**
+ * The `strftime` format of the first `%(fmt)T` directive in a `printf`
+ * format string, or `undefined` when it has none.
+ */
+function timeFormatIn(format) {
+    for (let index = 0; index < format.length; index++) {
+        if (format[index] !== '%')
+            continue;
+        if (format[index + 1] === '%') {
+            index++;
+            continue;
+        }
+        const rest = format.slice(index + 1);
+        const prefix = DIRECTIVE_PREFIX.exec(rest)?.[0] ?? '';
+        const afterPrefix = rest.slice(prefix.length);
+        if (!afterPrefix.startsWith('('))
+            continue;
+        const close = afterPrefix.indexOf(')');
+        if (close !== -1 && afterPrefix[close + 1] === 'T')
+            return afterPrefix.slice(1, close);
+    }
+    return undefined;
+}
+/**
+ * The `sh/compat/no-printf-time-format` rule module.
+ *
+ * @internal
+ */
+export const noPrintfTimeFormat = createCompatRule({
+    name: 'compat/no-printf-time-format',
+    feature: 'printfTimeFormat',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: "Disallow `printf`'s `%(fmt)T` date format when the target shell lacks it",
+        },
+        messages: {
+            printfTime: "`printf '%({{format}})T'` needs {{required}}, but this file targets {{target}}. For the current time, run `date '+{{format}}'` instead.",
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        return {
+            CallExpr(node) {
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (invoked?.effective.static !== true || invoked.effective.text !== 'printf')
+                    return;
+                // `chainIndices` index `node.args` directly, so slice before filtering.
+                const words = node.args.slice((invoked.chainIndices.at(-1) ?? 0) + 1);
+                let index = 0;
+                const first = words.at(0);
+                if (first !== undefined && sourceCode.resolveWordText(first) === '-v')
+                    index = 2;
+                if (index < words.length && sourceCode.resolveWordText(words[index]) === '--')
+                    index++;
+                const formatWord = words.at(index);
+                if (formatWord === undefined)
+                    return;
+                const text = sourceCode.resolveWordText(formatWord);
+                const format = text === null ? undefined : timeFormatIn(text);
+                if (format === undefined)
+                    return;
+                context.report({ node: formatWord, messageId: 'printfTime', data: { ...gate, format } });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-source.d.ts

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