@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

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

@@ -0,0 +1,120 @@
+/**
+ * `sh/compat/no-unicode-escape`: reports the `\uXXXX` and `\UXXXXXXXX`
+ * escapes in a `$'…'` string in files whose target shell does not decode
+ * them to UTF-8. The minimum Bash depends on the code point:
+ *
+ * - Bash 4.1 and older leave every such escape as literal text, with no
+ *   error: Bash 4.2 is the first release that decodes them;
+ * - the Bash 4.2 release writes a code point from U+0080 to U+00FF as a
+ *   single Latin-1 byte even in a UTF-8 locale (observed: `e9` for U+00E9,
+ *   where UTF-8 is `c3 a9`), while every other code point is UTF-8. Bash 4.3
+ *   is the first release that writes them all as UTF-8.
+ *
+ * The message suggests the portable alternative: write the character's
+ * UTF-8 bytes as octal escapes, which every Bash decodes in `$'…'` (for
+ * example `$'\303\251'` for U+00E9). Under `dialect: "posix"` the parser
+ * reads `$'…'` as a literal `$` followed by an ordinary single-quoted string,
+ * as dash does, so there is no `$'…'` string to report; the gate's
+ * `posix: false` records that POSIX sh does not decode these escapes.
+ *
+ * What is read: a `$'…'` string's text, scanned as Bash decodes it: `\\` is a
+ * backslash, `\cX` is one control character (so in `\cu00e9` the `u`
+ * belongs to `\c`), and `\u` takes one to four hex digits, `\U` one to
+ * eight. A `\u` with no hex digit after it is literal text. Plain `'…'`
+ * and `"…"` strings do not decode escapes and are not read. The report is on
+ * the whole string, once per string.
+ */
+import { createMultiFeatureCompatRule } from './create-compat-rule.js';
+/** The backslash that starts every escape. */
+const BACKSLASH = '\\';
+/** The unicode escapes of a `$'…'` string's text, in order. */
+function unicodeEscapes(text) {
+    const found = [];
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] !== BACKSLASH) {
+            index++;
+            continue;
+        }
+        const letter = text[index + 1];
+        if (letter === 'c') {
+            index += 3;
+            continue;
+        }
+        const maxDigits = letter === 'u' ? 4 : letter === 'U' ? 8 : 0;
+        if (maxDigits === 0) {
+            index += 2;
+            continue;
+        }
+        const digits = /^[0-9A-Fa-f]+/u.exec(text.slice(index + 2, index + 2 + maxDigits))?.[0];
+        if (digits === undefined) {
+            index += 2;
+            continue;
+        }
+        const length = 2 + digits.length;
+        found.push({ text: text.slice(index, index + length), codePoint: parseInt(digits, 16) });
+        index += length;
+    }
+    return found;
+}
+/** Whether a code point is one the Bash 4.2 release writes as a Latin-1 byte. */
+function isLatin1Upper(codePoint) {
+    return codePoint >= 0x80 && codePoint <= 0xff;
+}
+/**
+ * The UTF-8 bytes of `codePoint` as octal escapes (`\303\251`), or
+ * `undefined` for a value that is not a Unicode scalar value.
+ */
+function octalBytes(codePoint) {
+    if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff))
+        return undefined;
+    const bytes = new TextEncoder().encode(String.fromCodePoint(codePoint));
+    return [...bytes].map((byte) => BACKSLASH + byte.toString(8).padStart(3, '0')).join('');
+}
+/**
+ * The `sh/compat/no-unicode-escape` rule module.
+ *
+ * @internal
+ */
+export const noUnicodeEscape = createMultiFeatureCompatRule({
+    name: 'compat/no-unicode-escape',
+    features: ['unicodeEscape', 'unicodeEscapeLatin1'],
+    meta: {
+        type: 'problem',
+        docs: {
+            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}}'`.",
+        },
+    },
+    create(context, gates) {
+        const escapeGate = gates.get('unicodeEscape');
+        const latin1Gate = gates.get('unicodeEscapeLatin1');
+        return {
+            SglQuoted(node) {
+                if (!node.dollar)
+                    return;
+                const escapes = unicodeEscapes(node.value);
+                const latin1 = escapes.find((escape) => isLatin1Upper(escape.codePoint));
+                // The escape the message names, and the gate it needs: a Latin-1
+                // escape needs the newer release, so it decides when present.
+                const shown = latin1 ?? escapes.at(0);
+                const gate = latin1 === undefined ? escapeGate : latin1Gate;
+                if (shown === undefined || gate === undefined)
+                    return;
+                const messageId = escapeGate === undefined ? 'unicodeEscapeLatin1' : 'unicodeEscape';
+                context.report({
+                    node,
+                    messageId,
+                    data: {
+                        ...gate,
+                        escape: shown.text,
+                        octal: octalBytes(shown.codePoint) ?? '\\NNN',
+                    },
+                });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-wait-n.d.ts

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

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

@@ -0,0 +1,73 @@
+/**
+ * `sh/compat/no-wait-n`: reports `wait -n` in files whose target shell lacks
+ * it, that is, Bash older than 4.3 (macOS's stock `/bin/bash` is 3.2) and
+ * POSIX sh.
+ *
+ * Bash 4.2 and older reject `-n` as an invalid option and return 2 at once,
+ * so a job pool that throttles itself with `wait -n` stops waiting and runs
+ * every job together. The message suggests the portable alternative: keep
+ * each job's `$!` and wait for one job at a time with `wait "$pid"`, which
+ * returns that job's exit status.
+ *
+ * What is read: a `wait` command (after transparent wrappers such as
+ * `builtin`) whose option words, up to the first operand or `--`, include a
+ * cluster containing `n` (`-n`, `-fn`). The value after a `-p` cluster
+ * (Bash 5.1's `wait -p var`) is its operand, not an option. The report is on
+ * the option 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 `wait` command: `sh-ast/analyze`'s
+ * defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** An option cluster of `wait`: letters after a single `-`. */
+const OPTION_CLUSTER = /^-[A-Za-z]+$/u;
+/**
+ * The `sh/compat/no-wait-n` rule module.
+ *
+ * @internal
+ */
+export const noWaitN = createCompatRule({
+    name: 'compat/no-wait-n',
+    feature: 'waitNext',
+    meta: {
+        type: 'problem',
+        docs: {
+            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.',
+        },
+    },
+    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 !== 'wait')
+                    return;
+                // `chainIndices` index `node.args` directly, so slice before filtering.
+                const words = node.args.slice((invoked.chainIndices.at(-1) ?? 0) + 1);
+                for (let index = 0; index < words.length; index++) {
+                    const text = sourceCode.resolveWordText(words[index]);
+                    if (text === null || !OPTION_CLUSTER.test(text))
+                        return;
+                    if (text.includes('n')) {
+                        context.report({ node: words[index], messageId: 'waitNext', data: { ...gate } });
+                        return;
+                    }
+                    if (text.includes('p'))
+                        index++;
+                }
+            },
+        };
+    },
+});

package/dist/rules/compat/operator-range.d.ts

@@ -0,0 +1,10 @@
+import type { ShellSourceCode } from '../../language/shell-source-code.js';
+import type { ShellNode } from '../../language/syntax-view.js';
+/**
+ * The `[start, end)` UTF-16 range of `operator` at `node`'s `OpPos`, or
+ * `undefined` when the record has no valid `OpPos` or the text there is not
+ * `operator`.
+ *
+ * @internal
+ */
+export declare function operatorRange(sourceCode: ShellSourceCode, node: ShellNode, operator: string): [number, number] | undefined;

package/dist/rules/compat/operator-range.js

@@ -0,0 +1,15 @@
+/**
+ * The `[start, end)` UTF-16 range of `operator` at `node`'s `OpPos`, or
+ * `undefined` when the record has no valid `OpPos` or the text there is not
+ * `operator`.
+ *
+ * @internal
+ */
+export function operatorRange(sourceCode, node, operator) {
+    const syntax = sourceCode.getSyntax(node);
+    const pos = syntax?.OpPos;
+    if (pos?.IsValid !== true)
+        return undefined;
+    const start = sourceCode.getIndexFromSyntaxPos(pos);
+    return sourceCode.text.startsWith(operator, start) ? [start, start + operator.length] : undefined;
+}

package/dist/rules/compat/posix-absent-command.d.ts

@@ -0,0 +1,12 @@
+import type { ShellSourceCode } from '../../language/shell-source-code.js';
+import type { ShellNode, ShellNodeOf } from '../../language/syntax-view.js';
+/**
+ * The word that names `command` in `node`, when `command` is what `node`
+ * effectively runs and a shell without it can reach `node` (see the module
+ * comment), or `undefined` otherwise. Reporting this word rather than the whole
+ * command matters for `[[`: the parser ends that command at the first `&&` or
+ * `||`, so the node would cover an arbitrary part of the expression.
+ *
+ * @internal
+ */
+export declare function reachableCommandWord(sourceCode: ShellSourceCode, node: ShellNodeOf<'CallExpr'>, command: string): ShellNode | undefined;

package/dist/rules/compat/posix-absent-command.js

@@ -0,0 +1,134 @@
+/**
+ * How a POSIX-only compat rule finds a use of a command word POSIX sh lacks.
+ *
+ * Under `dialect: "posix"` the parser has no `[[` clause, `let` clause or
+ * similar: it reads `[[ a ]]`, `let n=1` and `source f` as ordinary commands,
+ * so the rules recognize them by the command they run. That reading is shared
+ * here so the three rules agree on what counts as a use:
+ *
+ * - **It is the effective command**, after following transparent wrappers,
+ *   which is what actually runs (`command let n=1` fails on dash as `let n=1`
+ *   does). `command -v let` asks a question instead of running `let`, and
+ *   resolves to no such command.
+ * - **A shell without the construct can reach it.** These constructs are
+ *   commands, not syntax, so a POSIX shell only fails when it runs one. A script
+ *   meant for `sh` can hold a branch for one shell, and dash never enters it:
+ *   `if [ -n "${BASH_VERSION-}" ]; then source ~/.bashrc; fi`. Such a use is not
+ *   reported, because the finding's claim would be false.
+ *
+ * Recognizing that branch is deliberately shallow and syntactic, like the guard
+ * in `require-tty-guard`: no dataflow, and only the shapes {@link isGuarded}
+ * lists, each testing one of `BASH_VERSION`, `KSH_VERSION` or `ZSH_VERSION`
+ * directly. Anything else, including a version captured in another variable,
+ * reports.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+/**
+ * The wrappers followed to find the command an invocation runs:
+ * `sh-ast/analyze`'s defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** `sh-ast`'s `BinCmdOperator` codes for `&&` and `||`, which the lint view preserves. */
+const AND_STMT = 11;
+const OR_STMT = 12;
+/**
+ * The source text of a word that reads a shell's own version variable: `$X`,
+ * `${X}`, `${X-}` or `${X:-}`, quoted or not. dash sets none of these variables.
+ */
+const SHELL_VERSION_WORD = /^"?\$(?:\{(?:BASH|KSH|ZSH)_VERSION(?::?-)?\}|(?:BASH|KSH|ZSH)_VERSION)"?$/u;
+/**
+ * What `stmt` tests, when it is exactly `[ -n V ]`, `test -n V` (`set`) or the
+ * `-z` forms (`unset`) for a version variable `V`, not negated. Anything else
+ * is `undefined`.
+ */
+function shellVersionTest(sourceCode, stmt) {
+    if (stmt?.type !== 'Stmt' || stmt.negated || stmt.cmd?.type !== 'CallExpr')
+        return undefined;
+    const { args } = stmt.cmd;
+    const name = sourceCode.getCommandName(stmt.cmd);
+    if (args.length !== (name === '[' ? 4 : name === 'test' ? 3 : 0))
+        return undefined;
+    if (name === '[' && sourceCode.resolveWordText(args[3]) !== ']')
+        return undefined;
+    if (!SHELL_VERSION_WORD.test(sourceCode.getText(args[2])))
+        return undefined;
+    const operator = sourceCode.resolveWordText(args[1]);
+    if (operator === '-n')
+        return 'set';
+    return operator === '-z' ? 'unset' : undefined;
+}
+/**
+ * Whether `stmt` leaves the script or function unless a version variable is
+ * set: `[ -n V ] || exit` or `[ -z V ] && exit`, with `exit` or `return`.
+ */
+function leavesUnlessVersioned(sourceCode, stmt) {
+    if (stmt.type !== 'Stmt' || stmt.cmd?.type !== 'BinaryCmd')
+        return false;
+    const { op, x, y } = stmt.cmd;
+    const test = shellVersionTest(sourceCode, x);
+    if (!((op === OR_STMT && test === 'set') || (op === AND_STMT && test === 'unset')))
+        return false;
+    if (y?.cmd?.type !== 'CallExpr')
+        return false;
+    const name = sourceCode.getCommandName(y.cmd);
+    return name === 'exit' || name === 'return';
+}
+/**
+ * Whether only a shell that sets a version variable can run `node`, because it
+ * sits in one of these:
+ *
+ * - the `then` body of `if [ -n V ]`, or the `else` body of `if [ -z V ]`;
+ * - the right side of `[ -n V ] && …` or `[ -z V ] || …`;
+ * - a statement list, after an earlier `[ -n V ] || exit` or `[ -z V ] && exit`
+ *   in that list (the file, or a `{ … }` block such as a function body).
+ */
+function isGuarded(sourceCode, node) {
+    let child = node;
+    for (let parent = sourceCode.getParent(child); parent; parent = sourceCode.getParent(child)) {
+        if (parent.type === 'IfClause' && parent.cond.length === 1) {
+            const test = shellVersionTest(sourceCode, parent.cond[0]);
+            if (test === 'set' && parent.then.some((stmt) => stmt === child))
+                return true;
+            if (test === 'unset' && parent.else === child)
+                return true;
+        }
+        else if (parent.type === 'BinaryCmd' && parent.y === child) {
+            const test = shellVersionTest(sourceCode, parent.x);
+            if ((parent.op === AND_STMT && test === 'set') ||
+                (parent.op === OR_STMT && test === 'unset')) {
+                return true;
+            }
+        }
+        else if (parent.type === 'File' || parent.type === 'Block') {
+            const index = parent.stmts.findIndex((stmt) => stmt === child);
+            if (parent.stmts.slice(0, index).some((stmt) => leavesUnlessVersioned(sourceCode, stmt))) {
+                return true;
+            }
+        }
+        child = parent;
+    }
+    return false;
+}
+/**
+ * The word that names `command` in `node`, when `command` is what `node`
+ * effectively runs and a shell without it can reach `node` (see the module
+ * comment), or `undefined` otherwise. Reporting this word rather than the whole
+ * command matters for `[[`: the parser ends that command at the first `&&` or
+ * `||`, so the node would cover an arbitrary part of the expression.
+ *
+ * @internal
+ */
+export function reachableCommandWord(sourceCode, node, command) {
+    const invoked = sourceCode.resolveInvokedCommand(node, {
+        transparentWrappers: TRANSPARENT_WRAPPERS,
+    });
+    if (invoked?.effective.static !== true || invoked.effective.text !== command)
+        return undefined;
+    if (isGuarded(sourceCode, node))
+        return undefined;
+    return node.args[invoked.chainIndices.at(-1) ?? 0];
+}

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

@@ -0,0 +1,9 @@
+import type { ShellNode } from '../../language/syntax-view.js';
+import type { ShellRuleContext, ShellRuleVisitor } from '../define-shell-rule.js';
+/**
+ * Builds the listeners that call `report(word)` for each operand word of a
+ * `shopt -s` command whose static text is `option`.
+ *
+ * @internal
+ */
+export declare function shoptEnableVisitor<MessageIds extends string>(context: ShellRuleContext<[], MessageIds>, option: string, report: (word: ShellNode) => void): ShellRuleVisitor;

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

@@ -0,0 +1,63 @@
+/**
+ * Shared detection of `shopt -s NAME`, for the compat rules that gate one
+ * `shopt` option (`lastpipe`, `globstar`).
+ *
+ * What is read: a `shopt` command (after transparent wrappers such as
+ * `builtin`) whose option words, up to the first operand, include `-s`
+ * (possibly inside a cluster such as `-sq`). Its operands are the option
+ * names it turns on. `shopt -u` turns options off (so does a `-u` beside the
+ * `-s`), `shopt -o` names `set -o` options, and an operand that is not a
+ * static word cannot be read, so none of those count.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+/**
+ * The wrappers followed to find the `shopt` command: `sh-ast/analyze`'s
+ * defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/**
+ * Builds the listeners that call `report(word)` for each operand word of a
+ * `shopt -s` command whose static text is `option`.
+ *
+ * @internal
+ */
+export function shoptEnableVisitor(context, option, report) {
+    const { sourceCode } = context;
+    return {
+        CallExpr(node) {
+            const invoked = sourceCode.resolveInvokedCommand(node, {
+                transparentWrappers: TRANSPARENT_WRAPPERS,
+            });
+            if (invoked?.effective.static !== true || invoked.effective.text !== 'shopt')
+                return;
+            // `chainIndices` index `node.args` directly, so slice before filtering.
+            const words = node.args.slice((invoked.chainIndices.at(-1) ?? 0) + 1);
+            let enables = false;
+            let disables = false;
+            let namesShellOptions = false;
+            let index = 0;
+            for (; index < words.length; index++) {
+                const text = sourceCode.resolveWordText(words[index]);
+                if (text === null || !/^-./u.test(text))
+                    break;
+                if (text === '--') {
+                    index++;
+                    break;
+                }
+                enables ||= text.includes('s');
+                disables ||= text.includes('u');
+                namesShellOptions ||= text.includes('o');
+            }
+            if (!enables || disables || namesShellOptions)
+                return;
+            for (const word of words.slice(index)) {
+                if (sourceCode.resolveWordText(word) === option)
+                    report(word);
+            }
+        },
+    };
+}

package/dist/rules/compat/version-gates.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The version-gate table every `compat/*` rule reads, and the one function
+ * that decides whether a gated feature is available to a file.
+ *
+ * A gate is data: a feature name mapped to the oldest Bash release that has
+ * it and whether POSIX sh has it. A new gate is a new row here, not new
+ * decision logic in a rule. The semantics of `languageOptions.shellVersion`
+ * and `languageOptions.dialect` for gating are defined once, by
+ * {@link isFeatureAvailable}, and documented for users in `docs/compat.md`.
+ *
+ * Every row is checked against real shells by `scripts/compat-matrix/run.sh`,
+ * which builds each Bash release and dash from source and runs one probe per
+ * feature on each; the observed results are the Evidence table in
+ * `docs/compat.md`. A changed row needs a probe there that shows the new
+ * boundary.
+ *
+ * @see https://tiswww.case.edu/php/chet/bash/NEWS — Bash release notes, the
+ *   source of every minimum version below
+ * @see https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html
+ *   — POSIX Shell Command Language: section 2.4 (reserved words) and section
+ *   2.9.1.4 (command search) leave the results of the `doubleBracket`,
+ *   `letCommand` and `sourceCommand` rows unspecified
+ */
+import type { ShellLanguageOptions } from '../../language/shell-language-options.js';
+/**
+ * The name of a gated feature: a row of {@link FEATURE_GATES}.
+ *
+ * @internal
+ */
+export type CompatFeature = 'appendAllRedirect' | 'associativeArrays' | 'caseAttributes' | 'caseFallthrough' | 'caseModification' | 'coproc' | 'declareGlobal' | 'doubleBracket' | 'epochVariables' | 'fdVariable' | 'globstar' | 'lastpipe' | 'letCommand' | 'mapfile' | 'nameref' | 'negativeArrayIndex' | 'nounsetEmptyArray' | 'parameterTransformation' | 'parameterTransformationCase' | 'parameterTransformationKeys' | 'parameterTransformationQuotedKeys' | 'pipeAll' | 'printfTimeFormat' | 'sourceCommand' | 'testVariableSet' | 'unicodeEscape' | 'unicodeEscapeLatin1' | 'waitNext';
+/**
+ * The two `languageOptions` fields gating reads. Both the raw and the
+ * normalized options satisfy it; an unset `dialect` means `"bash"`, as it
+ * does for the parser.
+ *
+ * @internal
+ */
+export type GateLanguageOptions = Pick<ShellLanguageOptions, 'dialect' | 'shellVersion'>;
+/**
+ * Whether `feature` is available to a file linted with `languageOptions`.
+ *
+ * - `dialect: "posix"`: available only when the gate's `posix` is `true`,
+ *   at any `shellVersion` (a Bash-only feature is never available).
+ * - `dialect: "bash"` (the default) or `"bats"`: an unset `shellVersion`
+ *   means the newest Bash, so every Bash feature is available. A set
+ *   `shellVersion` makes the feature available when it is the gate's `bash`
+ *   minimum or newer, comparing major then minor numerically (`"4"` is
+ *   `4.0`; `"3.10"` is newer than `"3.2"`). A `null` minimum is available at
+ *   every version.
+ * - `dialect: "mksh"` or `"zsh"`: the table carries no data for these
+ *   shells, and their `shellVersion` numbers their own releases, not Bash's,
+ *   so no gate applies and every feature is available.
+ *
+ * @internal
+ */
+export declare function isFeatureAvailable(feature: CompatFeature, languageOptions: GateLanguageOptions): boolean;
+/**
+ * Human-readable words for a gate's report: what the feature needs
+ * (`required`, such as `bash 4.0 or newer`) and what the file targets
+ * (`target`, such as `bash 3.2` or `POSIX sh`). Compat rule messages
+ * interpolate both as `{{required}}` and `{{target}}`.
+ *
+ * @internal
+ */
+export interface GateDescription {
+    readonly required: string;
+    readonly target: string;
+}
+/**
+ * Describes why `feature` is unavailable under `languageOptions`, for a
+ * report's message data. Call it only when {@link isFeatureAvailable} is
+ * `false`.
+ *
+ * @internal
+ */
+export declare function describeGate(feature: CompatFeature, languageOptions: GateLanguageOptions): GateDescription;