@eslint-sh/eslint-plugin 0.6.0 → 0.8.0

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;