@eslint-sh/eslint-plugin 0.7.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.js

@@ -236,10 +236,10 @@ export const noBraceSequencePaddingStep = createCompatRule({
             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 targets {{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 targets {{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 targets {{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 targets {{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`.',
+            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) {

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);
     },

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

@@ -15,12 +15,13 @@
  * 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
+ * What is read: an `Index` that is a unary minus applied to a static
+ * integer (decimal, octal, hexadecimal or base#digits), 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.
+ * only a plain word is resolved. Arithmetic expressions are never evaluated.
  *
  * 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
@@ -28,6 +29,7 @@
  */
 import { Minus } from 'sh-ast';
 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';
 /** A bare negative-subscript read, the only shape the suggestion rewrites. */
@@ -41,7 +43,33 @@ const 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;
+const UNSET_NEGATIVE = /^[A-Za-z_][A-Za-z0-9_]*\[\s*-\s*([^\s\]]+)\s*\]$/u;
+/**
+ * Recognizes a nonzero integer token using Bash's digit alphabets, without evaluating expressions.
+ * Leading zero means octal; base#digits requires an unpadded base from 2..64. Variables and invalid digits
+ * provide no static evidence. Machine-integer overflow is outside this lexical recognizer.
+ */
+function isNonzeroInteger(text) {
+    if (/^0[xX][0-9a-fA-F]+$/u.test(text))
+        return /[1-9a-fA-F]/u.test(text.slice(2));
+    if (/^0[0-7]*$/u.test(text))
+        return /[1-7]/u.test(text);
+    if (/^[1-9][0-9]*$/u.test(text))
+        return true;
+    const based = /^([1-9]\d?)#([0-9a-zA-Z@_]+)$/u.exec(text);
+    if (based === null)
+        return false;
+    const base = Number(based[1]);
+    if (base < 2 || base > 64)
+        return false;
+    const digits = base <= 36 ? based[2].toLowerCase() : based[2];
+    const alphabet = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ@_'.slice(0, base);
+    for (const digit of digits) {
+        if (!alphabet.includes(digit))
+            return false;
+    }
+    return /[^0]/u.test(digits);
+}
 /**
  * The `sh/compat/no-negative-array-index` rule module.
  *
@@ -57,13 +85,14 @@ export const noNegativeArrayIndex = createCompatRule({
             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))]}`.',
+            negativeIndex: 'Negative array subscripts need {{required}}, but this file must support {{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. */
+        const transparentWrappers = resolveTransparentWrappers(context, TRANSPARENT_WRAPPERS);
+        /** Whether `index` is a unary minus on a nonzero static integer token. */
         function isNegativeLiteral(index) {
             if (index?.type !== 'UnaryArithm' || index.op !== Minus)
                 return false;
@@ -73,12 +102,12 @@ export const noNegativeArrayIndex = createCompatRule({
             if (operand?.type !== 'Word')
                 return false;
             const digits = sourceCode.resolveWordText(operand) ?? '';
-            return /^\d+$/u.test(digits) && /[1-9]/u.test(digits);
+            return isNonzeroInteger(digits);
         }
         return {
             CallExpr(node) {
                 const invoked = sourceCode.resolveInvokedCommand(node, {
-                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                    transparentWrappers,
                 });
                 if (invoked?.effective.static !== true || invoked.effective.text !== 'unset')
                     return;
@@ -89,7 +118,8 @@ export const noNegativeArrayIndex = createCompatRule({
                     const text = sourceCode.resolveWordText(word) ?? sourceCode.getText(word);
                     if (text === '--')
                         continue;
-                    if (UNSET_NEGATIVE.test(text) && /[1-9]/u.test(text)) {
+                    const match = UNSET_NEGATIVE.exec(text);
+                    if (match !== null && isNonzeroInteger(match[1])) {
                         context.report({ node: word, messageId: 'negativeIndex', data: { ...gate } });
                     }
                 }

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

@@ -24,8 +24,8 @@
  * - 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;
+ *   not itself a proof of execution order: 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[@]}`,
@@ -34,9 +34,17 @@
  *   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.
+ *
+ * Local safety proofs suppress candidates when a preceding static `set +u`,
+ * literal non-empty array assignment, or length guard establishes safety in
+ * the same statement list. Calls and compound statements invalidate facts;
+ * dynamic environment changes and variable attributes limit these proofs.
+ * `nounset-array-proof.ts` owns those boundaries. Reports remain conditional:
+ * unknown state is a reason to report, not proof that the array is empty.
  */
 import { AlternateUnset, AlternateUnsetOrNull } from 'sh-ast';
 import { createCompatRule } from './create-compat-rule.js';
+import { createArraySafetyProof } from './nounset-array-proof.js';
 import { parseSetArguments, shebangOptionChanges } from '../set-options.js';
 /** A shell variable name. */
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/u;
@@ -68,7 +76,7 @@ export const noNounsetEmptyArray = createCompatRule({
             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}}`.',
+            emptyArray: 'This expansion is not proven safe. If this array is empty, `${{{name}}[{{subscript}}]}` under `set -u` needs {{required}}, but this file must support {{target}}, where it aborts with "unbound variable". Guard it, for example `{{example}}`.',
             guardExpansion: 'Replace with `{{replacement}}`.',
         },
     },
@@ -132,9 +140,12 @@ export const noNounsetEmptyArray = createCompatRule({
                 candidates.push({ node, name, subscript });
             },
             'File:exit'() {
-                if (!nounset)
+                if (!nounset || candidates.length === 0)
                     return;
+                const provenSafe = createArraySafetyProof(sourceCode);
                 for (const { node, name, subscript } of candidates) {
+                    if (provenSafe(node, name))
+                        continue;
                     const replacement = guardedExpansion(name, subscript);
                     const quoted = wholeQuotedWord(node);
                     context.report({

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

@@ -56,8 +56,8 @@ export const noParameterTransformation = createMultiFeatureCompatRule({
             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.',
+            transformation: '`${…@{{operator}}}` needs {{required}}, but this file must support {{target}}. Use {{alternative}} instead.',
+            transformationNoAlternative: '`${…@{{operator}}}` needs {{required}}, but this file must support {{target}}, which has no equivalent expansion; restructure the code that needs it.',
         },
     },
     create(context, gates) {

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

@@ -31,7 +31,7 @@ export const noPipeAll = createCompatRule({
             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.',
+            pipeAll: '`|&` needs {{required}}, but this file must support {{target}}. Write `cmd 2>&1 | other` instead.',
             useStderrRedirect: 'Replace `|&` with `2>&1 |`.',
         },
     },

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

@@ -16,6 +16,7 @@
  * word.
  */
 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';
 /**
@@ -65,15 +66,16 @@ export const noPrintfTimeFormat = createCompatRule({
             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.",
+            printfTime: "`printf '%({{format}})T'` needs {{required}}, but this file must support {{target}}. For the current time, run `date '+{{format}}'` instead.",
         },
     },
     create(context, gate) {
         const { sourceCode } = context;
+        const transparentWrappers = resolveTransparentWrappers(context, TRANSPARENT_WRAPPERS);
         return {
             CallExpr(node) {
                 const invoked = sourceCode.resolveInvokedCommand(node, {
-                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                    transparentWrappers,
                 });
                 if (invoked?.effective.static !== true || invoked.effective.text !== 'printf')
                     return;

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

@@ -81,9 +81,10 @@ export const noSource = createCompatRule({
     create(context, gate) {
         const { sourceCode } = context;
         const fileDefinesSource = definedFunctionNames(sourceCode).has(SOURCE);
+        const reachableWord = reachableCommandWord(context, SOURCE);
         return {
             CallExpr(node) {
-                const word = reachableCommandWord(sourceCode, node, SOURCE);
+                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-test-v.js

@@ -27,6 +27,7 @@
  */
 import { TsVarSet } from 'sh-ast';
 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';
 /**
@@ -214,11 +215,12 @@ export const noTestV = createCompatRule({
             description: 'Disallow the `-v name` test (`[[ -v x ]]`, `test -v x`) when the target shell lacks it',
         },
         messages: {
-            testV: '`-v {{name}}` needs {{required}}, but this file targets {{target}}. Test whether the variable is set with `[ -n "${{{name}}+set}" ]` instead.',
+            testV: '`-v {{name}}` needs {{required}}, but this file must support {{target}}. Test whether the variable is set with `[ -n "${{{name}}+set}" ]` instead.',
         },
     },
     create(context, gate) {
         const { sourceCode } = context;
+        const transparentWrappers = resolveTransparentWrappers(context, TRANSPARENT_WRAPPERS);
         /** The variable name shown in the message for `operand`. */
         function nameOf(operand) {
             const text = operand?.type === 'Word' ? sourceCode.resolveWordText(operand) : null;
@@ -251,7 +253,7 @@ export const noTestV = createCompatRule({
             },
             CallExpr(node) {
                 const invoked = sourceCode.resolveInvokedCommand(node, {
-                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                    transparentWrappers,
                 });
                 if (invoked?.effective.static !== true)
                     return;

package/dist/rules/compat/no-unicode-escape.js

@@ -85,8 +85,8 @@ export const noUnicodeEscape = createMultiFeatureCompatRule({
             description: "Disallow `\\u`/`\\U` escapes in `$'…'` strings when the target shell does not decode them to UTF-8",
         },
         messages: {
-            unicodeEscape: "`{{escape}}` in `$'…'` needs {{required}}, but this file targets {{target}}, which leaves it as literal text. Write the UTF-8 bytes as octal escapes instead, for example `$'{{octal}}'`.",
-            unicodeEscapeLatin1: "`{{escape}}` in `$'…'` needs {{required}}, but this file targets {{target}}, which writes U+0080 to U+00FF as a single Latin-1 byte, not UTF-8. Write the UTF-8 bytes as octal escapes instead, for example `$'{{octal}}'`.",
+            unicodeEscape: "`{{escape}}` in `$'…'` needs {{required}}, but this file must support {{target}}, which leaves it as literal text. Write the UTF-8 bytes as octal escapes instead, for example `$'{{octal}}'`.",
+            unicodeEscapeLatin1: "`{{escape}}` in `$'…'` needs {{required}}, but this file must support {{target}}, which writes U+0080 to U+00FF as a single Latin-1 byte, not UTF-8. Write the UTF-8 bytes as octal escapes instead, for example `$'{{octal}}'`.",
         },
     },
     create(context, gates) {

package/dist/rules/compat/no-wait-n.js

@@ -16,6 +16,7 @@
  * the option word.
  */
 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';
 /**
@@ -42,15 +43,16 @@ export const noWaitN = createCompatRule({
             description: 'Disallow `wait -n` when the target shell lacks it',
         },
         messages: {
-            waitNext: '`wait -n` needs {{required}}, but this file targets {{target}}. Wait for one job at a time instead: keep each job\'s `$!` and run `wait "$pid"`, which returns that job\'s exit status.',
+            waitNext: '`wait -n` needs {{required}}, but this file must support {{target}}. Wait for one job at a time instead: keep each job\'s `$!` and run `wait "$pid"`, which returns that job\'s exit status.',
         },
     },
     create(context, gate) {
         const { sourceCode } = context;
+        const transparentWrappers = resolveTransparentWrappers(context, TRANSPARENT_WRAPPERS);
         return {
             CallExpr(node) {
                 const invoked = sourceCode.resolveInvokedCommand(node, {
-                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                    transparentWrappers,
                 });
                 if (invoked?.effective.static !== true || invoked.effective.text !== 'wait')
                     return;

package/dist/rules/compat/nounset-array-proof.d.ts

@@ -0,0 +1,8 @@
+import type { ShellSourceCode } from '../../language/shell-source-code.js';
+import type { ShellNodeOf } from '../../language/syntax-view.js';
+/**
+ * Binds a proof query to one parsed file. The rule retains responsibility for
+ * selecting expansions and version gating; this helper only answers safety.
+ * @internal
+ */
+export declare function createArraySafetyProof(source: ShellSourceCode): (node: ShellNodeOf<'ParamExp'>, name: string) => boolean;