@eslint-sh/eslint-plugin 0.6.0 → 0.8.0

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

@@ -14,6 +14,7 @@
  * {@link DECLARATION_AND_LOCAL_COMMANDS}.
  */
 import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { resolveTransparentWrappers } from '../resolve-transparent-wrappers.js';
 import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
 /** The declaration commands that take option clusters. */
 const DECLARATION_COMMANDS = new Set(['declare', 'typeset']);
@@ -78,7 +79,9 @@ function declClauseArgs(node) {
  *
  * @internal
  */
-export function declarationFlagVisitor(sourceCode, flag, report, commands = DECLARATION_COMMANDS) {
+export function declarationFlagVisitor(context, flag, report, commands = DECLARATION_COMMANDS) {
+    const { sourceCode } = context;
+    const transparentWrappers = resolveTransparentWrappers(context, TRANSPARENT_WRAPPERS);
     const flagPattern = new RegExp(`^-[a-zA-Z]*${flag}[a-zA-Z]*$`, 'u');
     return {
         DeclClause(node) {
@@ -91,7 +94,7 @@ export function declarationFlagVisitor(sourceCode, flag, report, commands = DECL
         },
         CallExpr(node) {
             const invoked = sourceCode.resolveInvokedCommand(node, {
-                transparentWrappers: TRANSPARENT_WRAPPERS,
+                transparentWrappers,
             });
             if (invoked?.effective.static !== true)
                 return;

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

@@ -37,7 +37,7 @@ export const noAppendAllRedirect = createCompatRule({
             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.',
+            appendAll: '`&>>` needs {{required}}, but this file must support {{target}}. Append both streams with `>> file 2>&1` instead.',
             useAppendRedirects: 'Replace `&>> {{file}}` with `>> {{file}} 2>&1`.',
         },
     },

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

@@ -28,11 +28,11 @@ export const noAssociativeArrays = createCompatRule({
             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`.',
+            associativeArray: 'Associative arrays (`{{command}} -A`) need {{required}}, but this file must support {{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) => {
+        return declarationFlagVisitor(context, '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>;

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

@@ -0,0 +1,287 @@
+/**
+ * `sh/compat/no-brace-sequence-padding-step`: reports a brace sequence that
+ * is zero-padded (`{01..10}`) or stepped (`{1..10..2}`, `{a..e..2}`) in
+ * files whose target shell lacks those forms, that is, Bash older than 4.0
+ * (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Neither form is an error on Bash 3.2, which is what makes them easy to
+ * miss. Bash 3.2 expands `{01..03}` to `1 2 3`, dropping the padding, and
+ * leaves `{1..9..4}` as that literal word, so the script carries on with
+ * different words. POSIX does not specify brace expansion, so under a POSIX
+ * target what a shell does with the word depends on the shell (observed: dash
+ * leaves it literal, macOS's `/bin/sh` drops the padding as Bash 3.2 does,
+ * and `bash --posix` 5.3 pads); a plain `{1..3}` is as shell-dependent there,
+ * and this rule does not report it: only the Bash 4.0 additions are in its
+ * scope. The
+ * message suggests the portable alternative: count in a `while` loop and
+ * format with `printf`.
+ *
+ * What is read: the parser keeps a brace sequence as literal text inside a
+ * word, so the rule scans the literal parts of words that the shell
+ * brace-expands. A sequence is a `{` and `}` with nothing but the sequence
+ * between them (so `{01..03,x}`, a comma list, is not one), where:
+ *
+ * - the endpoints are both integers (an optional sign and digits) or both
+ *   single ASCII letters, with an optional third `..` field that is an
+ *   integer step: that makes it stepped, for either kind of endpoint;
+ * - integer endpoints are padded when either has more than one digit and
+ *   starts with `0` after an optional `-` (`01`, `00`, `-01`, `1..03`; `0`,
+ *   `-0` and `+01` are not).
+ *
+ * Anything that is not a sequence in Bash 4.0 and newer is left alone:
+ * `{a..c}` and `{1..3}` (no padding, no step, the same on every Bash),
+ * mixed endpoints (`{a..5..2}`), a variable endpoint (`{01..$n}`, which the
+ * shell never expands), an unterminated or malformed one (`{01..}`), and a
+ * `{` or `}` that is quoted or backslash-escaped, since quoted text is a
+ * separate part of the word and an escape is skipped when scanning.
+ *
+ * Numbers are bounded as Bash 5.3 bounds them, because past the bounds the
+ * word stays literal on every Bash and nothing differs: endpoints must fit a
+ * signed 64-bit integer, so must the distance between them, and so must the
+ * step's magnitude (a step of -9223372036854775808 or a value past 64 bits
+ * leaves the word literal;
+ * leading zeros do not count towards the value, so `{1..00000000000000000003}`
+ * is a sequence). Bash 3.2 reads the same words as literal or wraps them
+ * (its integers are narrower), and the older 4.x releases' bound was not
+ * measured, so a sequence inside the 64-bit range is reported and one outside
+ * it is not.
+ *
+ * Only words that are brace-expanded are read: command words and arguments,
+ * `for`/`select` lists, the elements of an array literal without an index,
+ * and the operands of `declare`, `local`, `export` and `readonly`. Not read,
+ * because the shell does no brace expansion there: a plain assignment
+ * (`a={01..03}`), a `case` subject or pattern, the operands of `[[ ]]`,
+ * here-strings and here-documents, and parameter-expansion words.
+ *
+ * A descriptor duplication target is not reported where it behaves the same
+ * on every Bash; see `isSameOnEveryBash`.
+ *
+ * Text inside a quoted string that the shell later runs as code (`eval
+ * '...'`, `trap '...'`) is not seen: the parser holds it as a string.
+ *
+ * A redirection target (`: > out{01..01}`) is read only when the sequence
+ * can be shown to yield exactly one word, since several words make it an
+ * "ambiguous redirect" error on Bash 4 and newer (on 3.2 too for a padded
+ * one), and the script is then wrong on every Bash that has the feature,
+ * not a portability gap. The word must hold that one sequence and no other
+ * brace group, whose product with it could not be counted here. A single-word
+ * result differs by target: `out{01..01}` names `out1` on Bash 3.2 and
+ * `out01` on 5.3, and `out{1..3..5}` names a file called `out{1..3..5}` on
+ * 3.2 and `out1` on 5.3. A sequence is always static text here (a variable
+ * endpoint is no sequence), so its length is always known. The report is on
+ * the whole word, once per word.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+import { DashHdoc, DplIn, DplOut, Hdoc, WordHdoc } from 'sh-ast/analyze';
+/** The sequence between braces: two endpoints and an optional step. */
+const SEQUENCE = /^([+-]?\d+|[A-Za-z])\.\.([+-]?\d+|[A-Za-z])(?:\.\.([+-]?\d+))?$/u;
+/**
+ * An integer endpoint with leading zeros, which Bash 4.0 pads to. A `+` sign
+ * does not count: Bash 5.3 expands `{+01..3}` as `1 2 3`, as 3.2 does.
+ */
+const ZERO_PADDED = /^-?0\d+$/u;
+/** An integer endpoint. */
+const INTEGER = /^[+-]?\d+$/u;
+/** The signed 64-bit range Bash 5.3 accepts for an endpoint. */
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+/**
+ * `text` with every backslash escape (the backslash and the character it
+ * quotes) replaced by `\0`, which no sequence contains, so an escaped brace
+ * cannot open or close a sequence and an escape inside one disqualifies it.
+ */
+function maskEscapes(text) {
+    let masked = '';
+    for (let index = 0; index < text.length; index++) {
+        if (text[index] === '\\') {
+            masked += '\0\0';
+            index++;
+        }
+        else {
+            masked += text[index];
+        }
+    }
+    return masked;
+}
+/** The value of an endpoint: an integer's number, or a letter's code point. */
+function endpointValue(endpoint) {
+    return INTEGER.test(endpoint) ? BigInt(endpoint) : BigInt(endpoint.charCodeAt(0));
+}
+/**
+ * The number of words a valid sequence yields. A step of zero counts as 1,
+ * and a step's sign is ignored: the direction follows the endpoints.
+ */
+function resultCount(start, end, step) {
+    const size = step === undefined || step === 0n ? 1n : step < 0n ? -step : step;
+    return span(start, end) / size + 1n;
+}
+/** The distance between two endpoints. */
+function span(start, end) {
+    return end > start ? end - start : start - end;
+}
+/**
+ * The first brace sequence in the literal text `text` that needs Bash 4.0
+ * and that Bash 5.3 expands, or `undefined`. Innermost brace pairs are the
+ * only candidates, which is where Bash finds a sequence, including one
+ * nested in a comma list (`{x,{01..03}}`).
+ */
+function findSequence(text) {
+    const masked = maskEscapes(text);
+    for (const pair of masked.matchAll(/\{([^{}]*)\}/gu)) {
+        const match = SEQUENCE.exec(pair[1]);
+        if (match === null)
+            continue;
+        const [, start, end] = match;
+        const integers = INTEGER.test(start) && INTEGER.test(end);
+        const letters = !INTEGER.test(start) && !INTEGER.test(end);
+        if (!integers && !letters)
+            continue;
+        // A third `..` field is the step (SEQUENCE has already checked its form).
+        const stepText = match[0].split('..').length === 3 ? match[0].split('..')[2] : undefined;
+        const step = stepText === undefined ? undefined : BigInt(stepText);
+        const first = endpointValue(start);
+        const last = endpointValue(end);
+        const inRange = first >= INT64_MIN &&
+            first <= INT64_MAX &&
+            last >= INT64_MIN &&
+            last <= INT64_MAX &&
+            (step === undefined || (step > INT64_MIN && step <= INT64_MAX));
+        // The distance between the endpoints must fit too:
+        // `{-1..9223372036854775807..9223372036854775807}` stays literal on Bash
+        // 5.3 although every number in it is in range.
+        if (!inRange || span(first, last) > INT64_MAX)
+            continue;
+        const results = resultCount(first, last, step);
+        const written = text.slice(pair.index, pair.index + pair[0].length);
+        if (step !== undefined)
+            return { text: written, kind: 'stepped', results, first };
+        if (integers && (ZERO_PADDED.test(start) || ZERO_PADDED.test(end))) {
+            return { text: written, kind: 'padded', results, first };
+        }
+    }
+    return undefined;
+}
+/** How many unescaped `{` the literal parts of `word` hold. */
+function braceGroupCount(word) {
+    let count = 0;
+    for (const part of word.parts) {
+        if (part.type === 'Lit')
+            count += maskEscapes(part.value).split('{').length - 1;
+    }
+    return count;
+}
+/** Redirection operators whose word the shell does not brace-expand. */
+const NO_BRACE_REDIRECTS = new Set([Hdoc, DashHdoc, WordHdoc]);
+/** The `<&` and `>&` operators, whose lone-number word names a descriptor. */
+const DESCRIPTOR_DUPLICATES = new Set([DplIn, DplOut]);
+/**
+ * Whether a one-word sequence that is the whole target of `<&` or `>&`
+ * behaves the same on Bash 3.2 and newer (checked on 3.2.57 and 5.3.9):
+ *
+ * - a descriptor position (`<&`, or `>&` with a descriptor before it, as in
+ *   `2>&`) with a negative number is an "ambiguous redirect" error on both,
+ *   whatever the form, so there is nothing to port;
+ * - a padded non-negative number names the same descriptor on both (`>&{01..01}`
+ *   is descriptor 1), but a stepped one differs (`>&{1..3..5}` is literal on
+ *   3.2 and descriptor 1 on 5.3);
+ * - a bare `>&` with a word that is not a descriptor writes a file, so a
+ *   negative number is a file name that differs (`-1` on 3.2, `-01` on 5.3).
+ */
+function isSameOnEveryBash(redirect, sequence) {
+    if (sequence.results !== 1n)
+        return false;
+    const descriptorPosition = redirect.op === DplIn || redirect.n !== undefined;
+    if (sequence.first < 0n)
+        return descriptorPosition;
+    return sequence.kind === 'padded';
+}
+/**
+ * Whether the shell brace-expands `word`, a `Word` node whose parent is
+ * `parent`. This is the complete list of such positions; anything not named
+ * here is exempt.
+ */
+function isBraceExpanded(word, parent, grandparent) {
+    switch (parent?.type) {
+        case 'CallExpr':
+        case 'WordIter':
+            return true;
+        // An array literal element; a keyed element (`[k]=v`) is assigned like a
+        // variable and is not expanded.
+        case 'ArrayElem':
+            return parent.index === undefined && parent.value === word;
+        // A declaration's operands are arguments to the builtin, so both a bare
+        // one and the value of `NAME=value` are expanded; a plain assignment is
+        // not.
+        case 'Assign':
+            return grandparent?.type === 'DeclClause';
+        // The target of an ordinary redirection; a here-document's delimiter and
+        // a here-string's word are not brace-expanded.
+        case 'Redirect':
+            return parent.word === word && !NO_BRACE_REDIRECTS.has(parent.op);
+        default:
+            return false;
+    }
+}
+/**
+ * The `sh/compat/no-brace-sequence-padding-step` rule module.
+ *
+ * @internal
+ */
+export const noBraceSequencePaddingStep = createCompatRule({
+    name: 'compat/no-brace-sequence-padding-step',
+    feature: 'braceSequencePaddingStep',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow zero-padded (`{01..10}`) and stepped (`{1..10..2}`) brace sequences when the target shell lacks them',
+        },
+        messages: {
+            padded: '`{{sequence}}` needs {{required}}, but this file must support {{target}}, which expands it without the zero padding. Count in a loop and format with `printf` instead, for example `i=1; while [ "$i" -le 3 ]; do printf \'%02d\\n\' "$i"; i=$((i + 1)); done`.',
+            stepped: '`{{sequence}}` needs {{required}}, but this file must support {{target}}, which leaves it as that literal word. Count in a loop instead, for example `i=1; while [ "$i" -le 9 ]; do echo "$i"; i=$((i + 4)); done`.',
+            posixPadded: '`{{sequence}}` needs {{required}}, but this file must support {{target}}, which does not specify brace expansion, so what a shell does with this word depends on the shell. Count in a loop and format with `printf` instead, for example `i=1; while [ "$i" -le 3 ]; do printf \'%02d\\n\' "$i"; i=$((i + 1)); done`.',
+            posixStepped: '`{{sequence}}` needs {{required}}, but this file must support {{target}}, which does not specify brace expansion, so what a shell does with this word depends on the shell. Count in a loop instead, for example `i=1; while [ "$i" -le 9 ]; do echo "$i"; i=$((i + 4)); done`.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        const posix = sourceCode.dialect === 'posix';
+        return {
+            Word(node) {
+                const parent = sourceCode.getParent(node);
+                const grandparent = parent === undefined ? undefined : sourceCode.getParent(parent);
+                if (!isBraceExpanded(node, parent, grandparent))
+                    return;
+                const redirectTarget = parent?.type === 'Redirect';
+                for (const part of node.parts) {
+                    if (part.type !== 'Lit')
+                        continue;
+                    const sequence = findSequence(part.value);
+                    if (sequence === undefined)
+                        continue;
+                    // A redirection target is an ambiguous-redirect error unless it is
+                    // exactly one word, which is only certain for a lone sequence.
+                    if (redirectTarget && (sequence.results !== 1n || braceGroupCount(node) !== 1))
+                        return;
+                    if (!posix &&
+                        parent?.type === 'Redirect' &&
+                        DESCRIPTOR_DUPLICATES.has(parent.op) &&
+                        node.parts.length === 1 &&
+                        part.value === sequence.text &&
+                        isSameOnEveryBash(parent, sequence)) {
+                        return;
+                    }
+                    context.report({
+                        node,
+                        messageId: posix
+                            ? sequence.kind === 'padded'
+                                ? 'posixPadded'
+                                : 'posixStepped'
+                            : sequence.kind,
+                        data: { ...gate, sequence: sequence.text },
+                    });
+                    return;
+                }
+            },
+        };
+    },
+});

package/dist/rules/compat/no-case-attributes.js

@@ -36,13 +36,13 @@ export const noCaseAttributes = createCompatRule({
             description: 'Disallow the case attributes `declare -l` and `declare -u` when the target shell lacks them',
         },
         messages: {
-            caseAttribute: '`{{command}} -{{flag}}` needs {{required}}, but this file targets {{target}}. Convert the value when you assign it instead, for example `v=$(printf \'%s\' "$v" | {{tr}})`.',
-            caseAttributesBoth: '`{{command}} {{option}}` needs {{required}}, but this file targets {{target}}. Where it is supported, `-l` and `-u` together cancel out and leave the value as written, so drop both letters.',
+            caseAttribute: '`{{command}} -{{flag}}` needs {{required}}, but this file must support {{target}}. Convert the value when you assign it instead, for example `v=$(printf \'%s\' "$v" | {{tr}})`.',
+            caseAttributesBoth: '`{{command}} {{option}}` needs {{required}}, but this file must support {{target}}. Where it is supported, `-l` and `-u` together cancel out and leave the value as written, so drop both letters.',
         },
     },
     create(context, gate) {
         const { sourceCode } = context;
-        return declarationFlagVisitor(sourceCode, '[lu]', (node, command) => {
+        return declarationFlagVisitor(context, '[lu]', (node, command) => {
             const option = (node.type === 'Word' ? sourceCode.resolveWordText(node) : null) ?? '';
             if (option.includes('l') && option.includes('u')) {
                 context.report({

package/dist/rules/compat/no-case-fallthrough.js

@@ -37,8 +37,8 @@ export const noCaseFallthrough = createCompatRule({
             description: 'Disallow the `case` terminators `;&` and `;;&` when the target shell lacks them',
         },
         messages: {
-            fallthrough: "`;&` needs {{required}}, but this file targets {{target}}. Repeat the next branch's commands at the end of this branch and end it with `;;` instead.",
-            resume: '`;;&` needs {{required}}, but this file targets {{target}}. End this branch with `;;` and test the patterns that follow it in a second `case` statement instead.',
+            fallthrough: "`;&` needs {{required}}, but this file must support {{target}}. Repeat the next branch's commands at the end of this branch and end it with `;;` instead.",
+            resume: '`;;&` needs {{required}}, but this file must support {{target}}. End this branch with `;;` and test the patterns that follow it in a second `case` statement instead.',
         },
     },
     create(context, gate) {

package/dist/rules/compat/no-case-modification.js

@@ -55,8 +55,8 @@ export const noCaseModification = createCompatRule({
             description: 'Disallow case-modifying expansions (`${v^^}`, `${v,,}` and variants) when the target shell lacks them',
         },
         messages: {
-            caseModification: '`${…{{operator}}}` needs {{required}}, but this file targets {{target}}. Convert the case with `tr` instead, for example {{example}}.',
-            caseModificationPattern: '`${…{{operator}}pattern}` needs {{required}}, but this file targets {{target}}. It changes only the characters the pattern matches, so a plain case-converting `tr` is not equivalent; spell out the matching characters instead (for example `tr a A`).',
+            caseModification: '`${…{{operator}}}` needs {{required}}, but this file must support {{target}}. Convert the case with `tr` instead, for example {{example}}.',
+            caseModificationPattern: '`${…{{operator}}pattern}` needs {{required}}, but this file must support {{target}}. It changes only the characters the pattern matches, so a plain case-converting `tr` is not equivalent; spell out the matching characters instead (for example `tr a A`).',
         },
     },
     create(context, gate) {

package/dist/rules/compat/no-coproc.js

@@ -28,7 +28,7 @@ export const noCoproc = createCompatRule({
             description: 'Disallow the `coproc` reserved word when the target shell lacks it',
         },
         messages: {
-            coproc: '`coproc` needs {{required}}, but this file targets {{target}}. Use a named pipe instead: create it with `mkfifo`, start the coprocess in the background reading or writing the pipe, and open the pipe from the script.',
+            coproc: '`coproc` needs {{required}}, but this file must support {{target}}. Use a named pipe instead: create it with `mkfifo`, start the coprocess in the background reading or writing the pipe, and open the pipe from the script.',
         },
     },
     create(context, gate) {

package/dist/rules/compat/no-declare-g.js

@@ -39,12 +39,12 @@ export const noDeclareG = createCompatRule({
             description: 'Disallow `declare -g` and `typeset -g` when the target shell lacks the option',
         },
         messages: {
-            declareGlobal: '`{{command}} -g` needs {{required}}, but this file targets {{target}}. Assign the global with a plain `name=value` (a variable not declared `local` is global), or `export name=value` to also export it.',
-            declareGlobalWithAttributes: '`{{command}} {{flags}}` needs {{required}}, but this file targets {{target}}. A plain `name=value` cannot express its other options, so dropping `g` is not enough: declare the variable outside any function, or raise the target.',
+            declareGlobal: '`{{command}} -g` needs {{required}}, but this file must support {{target}}. Assign the global with a plain `name=value` (a variable not declared `local` is global), or `export name=value` to also export it.',
+            declareGlobalWithAttributes: '`{{command}} {{flags}}` needs {{required}}, but this file must support {{target}}. A plain `name=value` cannot express its other options, so dropping `g` is not enough: declare the variable outside any function, or raise the minimum Bash version.',
         },
     },
     create(context, gate) {
-        return declarationFlagVisitor(context.sourceCode, 'g', (node, command, options) => {
+        return declarationFlagVisitor(context, 'g', (node, command, options) => {
             if (!isPlainAssignmentEquivalent(options)) {
                 context.report({
                     node,

package/dist/rules/compat/no-double-bracket.js

@@ -39,10 +39,10 @@ export const noDoubleBracket = createCompatRule({
         },
     },
     create(context, gate) {
-        const { sourceCode } = context;
+        const reachableWord = reachableCommandWord(context, '[[');
         return {
             CallExpr(node) {
-                const word = reachableCommandWord(sourceCode, node, '[[');
+                const word = reachableWord(node);
                 if (word === undefined)
                     return;
                 context.report({ node: word, messageId: 'doubleBracket', data: { target: gate.target } });

package/dist/rules/compat/no-epoch-variables.js

@@ -27,8 +27,8 @@ export const noEpochVariables = createCompatRule({
             description: 'Disallow `$EPOCHSECONDS` and `$EPOCHREALTIME` when the target shell lacks them',
         },
         messages: {
-            epochSeconds: '`$EPOCHSECONDS` needs {{required}}, but this file targets {{target}}, where it is unset. Use `$(date +%s)` instead (GNU, BSD and BusyBox `date`; POSIX `date` has no `%s`).',
-            epochRealtime: '`$EPOCHREALTIME` needs {{required}}, but this file targets {{target}}, where it is unset. `$(date +%s)` gives whole seconds (GNU, BSD and BusyBox `date`); there is no portable source of the fraction.',
+            epochSeconds: '`$EPOCHSECONDS` needs {{required}}, but this file must support {{target}}, where it is unset. Use `$(date +%s)` instead (GNU, BSD and BusyBox `date`; POSIX `date` has no `%s`).',
+            epochRealtime: '`$EPOCHREALTIME` needs {{required}}, but this file must support {{target}}, where it is unset. `$(date +%s)` gives whole seconds (GNU, BSD and BusyBox `date`); there is no portable source of the fraction.',
         },
     },
     create(context, gate) {

package/dist/rules/compat/no-fd-variable.js

@@ -32,7 +32,7 @@ export const noFdVariable = createCompatRule({
             description: 'Disallow `{varname}` file-descriptor redirections (`exec {fd}>file`) when the target shell lacks them',
         },
         messages: {
-            fdVariable: '`{{{name}}}` descriptor allocation needs {{required}}, but this file targets {{target}}. Use a fixed descriptor number instead, for example `exec 3>file`, then `>&3`, then `exec 3>&-`.',
+            fdVariable: '`{{{name}}}` descriptor allocation needs {{required}}, but this file must support {{target}}. Use a fixed descriptor number instead, for example `exec 3>file`, then `>&3`, then `exec 3>&-`.',
         },
     },
     create(context, gate) {

package/dist/rules/compat/no-globstar.js

@@ -28,7 +28,7 @@ export const noGlobstar = createCompatRule({
             description: 'Disallow `shopt -s globstar` when the target shell lacks the option',
         },
         messages: {
-            globstar: "`shopt -s globstar` needs {{required}}, but this file targets {{target}}, where `**` matches like `*`. Search the tree with `find` instead, for example `find dir -name '*.txt'`.",
+            globstar: "`shopt -s globstar` needs {{required}}, but this file must support {{target}}, where `**` matches like `*`. Search the tree with `find` instead, for example `find dir -name '*.txt'`.",
         },
     },
     create(context, gate) {

package/dist/rules/compat/no-lastpipe-semantics.js

@@ -37,8 +37,8 @@ export const noLastpipeSemantics = createCompatRule({
             description: 'Disallow `shopt -s lastpipe` when the target shell lacks the option',
         },
         messages: {
-            lastpipe: '`shopt -s lastpipe` needs {{required}}, but this file targets {{target}}. Keep the loop in the current shell by feeding it with process substitution instead, for example `while read -r line; do …; done < <(cmd)`.',
-            lastpipePosix: '`shopt -s lastpipe` needs {{required}}, but this file targets {{target}}. Process substitution is not POSIX either; keep the loop in the current shell by writing the output to a temporary file and reading that, for example `cmd > "$tmp"` then `while read -r line; do …; done < "$tmp"`, or by feeding the loop a here-document.',
+            lastpipe: '`shopt -s lastpipe` needs {{required}}, but this file must support {{target}}. Keep the loop in the current shell by feeding it with process substitution instead, for example `while read -r line; do …; done < <(cmd)`.',
+            lastpipePosix: '`shopt -s lastpipe` needs {{required}}, but this file must support {{target}}. Process substitution is not POSIX either; keep the loop in the current shell by writing the output to a temporary file and reading that, for example `cmd > "$tmp"` then `while read -r line; do …; done < "$tmp"`, or by feeding the loop a here-document.',
         },
     },
     create(context, gate) {

package/dist/rules/compat/no-let.js

@@ -47,9 +47,10 @@ export const noLet = createCompatRule({
     create(context, gate) {
         const { sourceCode } = context;
         const fileDefinesLet = definedFunctionNames(sourceCode).has(LET);
+        const reachableWord = reachableCommandWord(context, LET);
         return {
             CallExpr(node) {
-                const word = reachableCommandWord(sourceCode, node, LET);
+                const word = reachableWord(node);
                 if (word === undefined)
                     return;
                 // Only a name written directly can run a function: a wrapper skips it.

package/dist/rules/compat/no-mapfile.js

@@ -28,6 +28,7 @@
  * all, get the report without a suggestion.
  */
 import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { resolveTransparentWrappers } from '../resolve-transparent-wrappers.js';
 import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
 import { createCompatRule } from './create-compat-rule.js';
 /** The builtin's two names. */
@@ -84,17 +85,18 @@ export const noMapfile = createCompatRule({
             description: 'Disallow `mapfile` and `readarray` when the target shell lacks them',
         },
         messages: {
-            mapfile: '`{{command}}` needs {{required}}, but this file targets {{target}}. Read the lines with a `while IFS= read -r` loop instead.',
+            mapfile: '`{{command}}` needs {{required}}, but this file must support {{target}}. Read the lines with a `while IFS= read -r` loop instead.',
             useReadLoop: 'Replace with a `while IFS= read -r` loop that appends each line to `{{array}}` (the loop also sets `REPLY` to the empty string).',
         },
     },
     create(context, gate) {
         const { sourceCode } = context;
+        const transparentWrappers = resolveTransparentWrappers(context, TRANSPARENT_WRAPPERS);
         const arraysAvailable = sourceCode.dialect !== 'posix';
         return {
             CallExpr(node) {
                 const invoked = sourceCode.resolveInvokedCommand(node, {
-                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                    transparentWrappers,
                 });
                 if (invoked?.effective.static !== true)
                     return;

package/dist/rules/compat/no-nameref.js

@@ -30,14 +30,14 @@ export const noNameref = createCompatRule({
             description: 'Disallow namerefs (`declare -n`, `local -n`) when the target shell lacks them',
         },
         messages: {
-            nameref: '`{{command}} -n` needs {{required}}, but this file targets {{target}}. Pass the variable name instead: assign through it with `printf -v "$name" \'%s\' "$value"` and read it with `${!name}`.',
-            namerefPosix: '`{{command}} -n` needs {{required}}, but this file targets {{target}}. Pass the variable name instead and use `eval`: assign with `eval "$name=\\$value"` and read with `eval "value=\\$$name"`, after checking that the name is a valid identifier.',
+            nameref: '`{{command}} -n` needs {{required}}, but this file must support {{target}}. Pass the variable name instead: assign through it with `printf -v "$name" \'%s\' "$value"` and read it with `${!name}`.',
+            namerefPosix: '`{{command}} -n` needs {{required}}, but this file must support {{target}}. Pass the variable name instead and use `eval`: assign with `eval "$name=\\$value"` and read with `eval "value=\\$$name"`, after checking that the name is a valid identifier.',
         },
     },
     create(context, gate) {
         const { sourceCode } = context;
         const messageId = sourceCode.dialect === 'posix' ? 'namerefPosix' : 'nameref';
-        return declarationFlagVisitor(sourceCode, 'n', (node, command) => {
+        return declarationFlagVisitor(context, 'n', (node, command) => {
             context.report({ node, messageId, data: { ...gate, command } });
         }, DECLARATION_AND_LOCAL_COMMANDS);
     },