@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/dist/language/shell-source-code.d.ts

@@ -1,7 +1,10 @@
 import { TextSourceCodeBase } from '@eslint/plugin-kit';
-import type { ShellFile as ShFile, ShellNode as ShNode, ShellComment } from './syntax-view.js';
+import type { ShellFile as ShFile, ShellNode as ShNode, ShellNodeOf, ShellComment } from './syntax-view.js';
 import type { Directive as IDirective, FileProblem, RulesConfig, SourceLocation, TraversalStep } from '@eslint/core';
-import type { ShellLanguageOptions } from './shell-language-options.js';
+import type { Node as SyntaxNode, PrintOptions, SyntaxPos } from 'sh-ast';
+import type { Argv0Resolution, ResolveArgv0Options, ResolveWordOptions } from 'sh-ast/analyze';
+import type { ShellDialect, ShellLanguageOptions } from './shell-language-options.js';
+import type { ShellCommandSite } from './command-resolution.js';
 /**
  * `ShellSourceCode` — the `SourceCode` object ESLint uses to work with a
  * parsed shell file. Extends `@eslint/plugin-kit`'s `TextSourceCodeBase`, which
@@ -18,8 +21,8 @@ import type { ShellLanguageOptions } from './shell-language-options.js';
  * `applyInlineConfig`) recognizes all four disable-comment forms
  * (`<prefix>-disable`, `<prefix>-enable`, `<prefix>-disable-line`,
  * `<prefix>-disable-next-line`) plus whole-file inline rule config
- * (bare `<prefix> <rule-config>`), sourced from `Comment` nodes gathered via
- * the consumer's `walkShell()` and parsed with
+ * (bare `<prefix> <rule-config>`), sourced from the tree's `Comment` nodes
+ * and parsed with
  * `@eslint/plugin-kit`'s `ConfigCommentParser` — the same building blocks
  * `@eslint/json`'s `JSONSourceCode` uses, generalized so the `<prefix>` is
  * configurable (default `"eslint"`; see `ShellLanguageOptions.directivePrefix`)
@@ -29,6 +32,24 @@ import type { ShellLanguageOptions } from './shell-language-options.js';
  * classes) is implemented on `ShellLanguage` — see `shell-language.ts` and
  * `selector-classes.ts`.
  *
+ * Rule-author helpers (`resolveWordText`, `getCommandName`,
+ * `resolveInvokedCommand`, `getCommandSites`) answer "is this word statically
+ * the string `jq`?", "which command does this invocation run?", and "which
+ * commands does this file run, and where?" by delegating to
+ * `sh-ast/analyze`. They never reinterpret words themselves, so every rule
+ * gets the same answer for the same syntax. `dialect` and `shellVersion`
+ * expose the file's normalized language options.
+ *
+ * Syntax access (`getSyntax`, `getViewNode`, `getIndexFromSyntaxPos`,
+ * `getLocFromSyntaxPos`) reaches behind the lint view to the sh-ast records
+ * this file was parsed into: from a view node to its record and back, and
+ * from a record's byte positions (such as `BinaryCmd.OpPos`, which the view
+ * leaves out) to ESLint coordinates in this file's text.
+ *
+ * Printed fixes (`getEditableSyntax`, `getPrintedReplacement`) edit an
+ * independent copy of a view node's record and print it with sh-ast's
+ * printer, returning the source range and text for `fixer.replaceTextRange`.
+ *
  * @public
  */
 export declare class ShellSourceCode extends TextSourceCodeBase<{
@@ -42,7 +63,324 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
         text: string;
         ast: ShFile;
         directivePrefix?: string;
+        dialect?: ShellDialect;
+        shellVersion?: string;
     });
+    /**
+     * The shell dialect this file was parsed as: the normalized
+     * `languageOptions.dialect`, which defaults to `"bash"` when the config
+     * leaves it unset. Rules use it to gate dialect-specific checks.
+     */
+    get dialect(): ShellDialect;
+    /**
+     * The configured `languageOptions.shellVersion` (a `MAJOR[.MINOR]` string
+     * such as `"3.2"`), or `undefined` when the config does not set one. The
+     * parser never reads it; it exists for rules that gate on shell version.
+     */
+    get shellVersion(): string | undefined;
+    /**
+     * The one-based location of a UTF-16 `index` in this file's text, where
+     * `index` may be anywhere from 0 to `text.length`. CRLF counts as one line
+     * break.
+     *
+     * Overrides the base class, which measures every index from the root
+     * node's own start and so assumes the root spans the whole text. A shell
+     * file's root starts at its first statement or comment, so the base answer
+     * was shifted by any leading blank lines or indentation.
+     *
+     * @throws TypeError when `index` is not a number.
+     * @throws RangeError when `index` is not an integer from 0 to `text.length`.
+     */
+    getLocFromIndex(index: number): {
+        line: number;
+        column: number;
+    };
+    /**
+     * The UTF-16 index of a one-based `loc` in this file's text: the inverse of
+     * {@link ShellSourceCode.getLocFromIndex}. The column may name any position
+     * on its line up to and including the line break.
+     *
+     * Overrides the base class for the same reason as `getLocFromIndex`.
+     *
+     * @throws TypeError when `loc` is not an object with numeric `line` and `column`.
+     * @throws RangeError when `loc` is not inside the text.
+     */
+    getIndexFromLoc(loc: {
+        line: number;
+        column: number;
+    }): number;
+    /**
+     * Returns the literal text of `word` when `sh-ast/analyze`'s `resolveWord`
+     * reports it static, or `null` otherwise.
+     *
+     * Delegates to `resolveWord` (through this package's `resolveWord` export),
+     * which alone defines what "static" means: a word is static iff
+     * `resolveWord` reports `static: true`. Its non-static reasons are
+     * `expansion`, `tilde`, `glob`, `brace`, `locale`, and `unsupported`.
+     * Call the root `resolveWord` export instead when the reason matters.
+     *
+     * `options` is forwarded to `resolveWord` unchanged. When it is omitted, the
+     * word's grammar position picks the tilde context: a word in a `CallExpr`'s
+     * `args` uses `{ context: 'command-argument' }`, the context
+     * `enumerateCommands` uses for argv, so `resolveWordText(callExpr.args[0])`
+     * equals `getCommandName(callExpr)`. Any other word uses `resolveWord`'s
+     * conservative default, which also treats a `~` after an unquoted `:` as a
+     * tilde expansion, as assignment values do.
+     *
+     * @param word - A parsed `Word` node from this file's lint tree.
+     * @param options - Forwarded to `resolveWord` unchanged when supplied.
+     * @returns The resolved text, or `null` when the word is not static.
+     * @throws TypeError when `word` is not a parsed shell `Word`.
+     */
+    resolveWordText(word: ShellNodeOf<'Word'>, options?: ResolveWordOptions): string | null;
+    /**
+     * Returns the static text of `callExpr`'s command word (`argv[0]`) as
+     * written, or `null` when that word is dynamic or absent. Transparent
+     * wrappers are **not** followed: `sudo rm x` yields `"sudo"`. Use
+     * {@link ShellSourceCode.resolveInvokedCommand} for the command a wrapper
+     * chain actually runs.
+     *
+     * Delegates to `sh-ast/analyze`: the answer is the `argv0` resolution of the
+     * `CommandSite` that `enumerateCommands` reports for this `CallExpr` in this
+     * file. Leading `VAR=val` assignments are not part of argv, so
+     * `FOO=1 jq .` yields `"jq"`. An assignment-only statement (`FOO=1`) has no
+     * argv0 and no `CommandSite`, and yields `null`.
+     *
+     * @param callExpr - A parsed `CallExpr` node from this file's lint tree.
+     * @returns The command word's static text, or `null`.
+     * @throws TypeError when `callExpr` is not a parsed shell `CallExpr`.
+     * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when this file's
+     * nesting exceeds analysis's recursion guard; see
+     * {@link ShellSourceCode.resolveInvokedCommand}.
+     */
+    getCommandName(callExpr: ShellNodeOf<'CallExpr'>): string | null;
+    /**
+     * Follows `callExpr`'s argv0 through transparent wrappers (`env`, `sudo`,
+     * `nohup`, `exec`, …) and returns `sh-ast/analyze`'s full `resolveArgv0`
+     * result, or `null` for a `CallExpr` that has no `CommandSite` (an
+     * assignment-only statement such as `FOO=1`).
+     *
+     * Delegates to `resolveArgv0` with the `CommandSite` that `enumerateCommands`
+     * reports for this `CallExpr` in this file, so it inherits that function's
+     * guarantee that an unknowable word is never guessed through. Read the
+     * effective command's name as
+     * `res.effective.static ? res.effective.text : null`.
+     * `sudo -u x "$prog"` and `exec "$@"` have a non-static `effective` with
+     * reason `expansion`; `env -S '…'` has reason `embedded-command`; `chain`
+     * lists every word resolved along the way, outermost wrapper first, and
+     * `chainIndices` gives each entry's position in the command's `argv` (as
+     * {@link ShellSourceCode.getCommandSites} reports it). When `effective` is
+     * static, the effective command's arguments are
+     * `argv.slice(chainIndices.at(-1)! + 1)`: every entry after the effective
+     * command's own index.
+     *
+     * Enumeration runs once per file, the first time any command helper is
+     * called. If the file's nesting exceeds `enumerateCommands`'s recursion
+     * guard, its `ShAnalyzeMaxDepthError` propagates unchanged and ESLint
+     * reports the rule as crashed for that file. That fails closed: a partial
+     * index would silently omit real commands.
+     *
+     * @param callExpr - A parsed `CallExpr` node from this file's lint tree.
+     * @param options - Forwarded to `resolveArgv0` unchanged.
+     * `transparentWrappers` replaces `sh-ast/analyze`'s
+     * `DEFAULT_TRANSPARENT_WRAPPERS`; spread the defaults into the array to
+     * extend them instead.
+     * @returns The resolution, or `null` when `callExpr` invokes no command.
+     * @throws TypeError when `callExpr` is not a parsed shell `CallExpr`.
+     * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when this file's
+     * nesting exceeds analysis's recursion guard.
+     * @throws `ShAnalyzeInvalidWrapperSpecError` (from `sh-ast/analyze`) when
+     * `options.transparentWrappers` contains a malformed entry.
+     */
+    resolveInvokedCommand(callExpr: ShellNodeOf<'CallExpr'>, options?: ResolveArgv0Options): Argv0Resolution | null;
+    /**
+     * Returns every command invocation in this file, one entry per
+     * `sh-ast/analyze` `CommandSite`, in source order. Use it when a rule needs
+     * the whole file's commands with their structural context, such as every
+     * command inside a function or inside `$(…)`, instead of visiting
+     * `CallExpr` nodes one by one.
+     *
+     * The data comes from `sh-ast/analyze`'s `enumerateCommands`: facts about
+     * how each command is reached and what its words resolve to, never a
+     * verdict. Each entry's `context`, `argv0`, and `argv` are analysis's own
+     * values, unchanged; `context` lists frames outermost first, as in sh-ast.
+     * Each entry's `node` is the `CallExpr` view node (`===` the node ESLint
+     * passes to a `CallExpr` visitor), so it can be passed to
+     * `context.report()`.
+     *
+     * An assignment-only statement (`FOO=1`) runs no command and has no entry,
+     * although a command substitution in its value (`FOO=$(date)`) does.
+     *
+     * Enumeration runs at most once per file, shared with
+     * {@link ShellSourceCode.getCommandName} and
+     * {@link ShellSourceCode.resolveInvokedCommand}, and every call returns the
+     * same array. Because every rule shares it, the array and everything in each
+     * entry except `node` are deeply frozen (see `ShellCommandSite`): no rule can
+     * change what another rule reads. If the file's nesting exceeds `enumerateCommands`'s
+     * recursion guard, its `ShAnalyzeMaxDepthError` propagates unchanged, as it
+     * does for those helpers: a partial list would silently omit real commands.
+     *
+     * @returns This file's command sites, in source order.
+     * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when this file's
+     * nesting exceeds analysis's recursion guard.
+     */
+    getCommandSites(): readonly ShellCommandSite[];
+    /**
+     * Returns the sh-ast record `node` was projected from: this file's original
+     * parse of `node`, with every field the lint view leaves out, including
+     * named token positions such as `BinaryCmd.OpPos`, `Stmt.Semicolon` and
+     * `Redirect.OpPos`. Pass those positions to
+     * {@link ShellSourceCode.getIndexFromSyntaxPos} or
+     * {@link ShellSourceCode.getLocFromSyntaxPos} to report on them, or pass the
+     * record to an `sh-ast/analyze` function.
+     *
+     * The returned record is read-only by contract. It is the language's
+     * original parse, shared by every rule and helper linting this file, and
+     * mutating it is unsupported: helpers such as
+     * {@link ShellSourceCode.resolveWordText} read the same record and would see
+     * the edit. It is not frozen, so a write does not throw. Make edits on an
+     * editable copy from {@link ShellSourceCode.getEditableSyntax} instead.
+     *
+     * @param node - A view node from this file's lint tree.
+     * @returns The original sh-ast record, or `undefined` when `node` has none
+     * in this file: an auxiliary view (a record whose type is not an sh-ast
+     * `Node`, such as the `Slice` of `${x:1:2}`), a view node from another
+     * file's tree, or an
+     * object that did not come from the parser.
+     */
+    getSyntax(node: ShNode): SyntaxNode | undefined;
+    /**
+     * Returns the lint view node projected from `syntax`: the inverse of
+     * {@link ShellSourceCode.getSyntax}. The result is the same object (`===`)
+     * ESLint passes to rule visitors, so it can be passed to
+     * `context.report()`. Use it to come back to the view after navigating the
+     * original records, for example from a `Stmt` record's `Cmd`.
+     *
+     * Lookup is by object identity, so only the parser's own records match.
+     * sh-ast's `walk` passes its callback a fresh copy of each comment stored
+     * on a `Stmt`, `CaseItem` or `ArrayElem`, as Go's `syntax.Walk` does, so
+     * those `Comment` copies have no view node. Read the stored comment from
+     * the record's `Comments` array instead.
+     *
+     * @param syntax - An sh-ast `Node` record from this file's original parse.
+     * @returns The view node, or `undefined` for any other record, including a
+     * copy of one of this file's records (such as a `structuredClone`) and a
+     * record from another parse.
+     */
+    getViewNode(syntax: SyntaxNode): ShNode | undefined;
+    /**
+     * Returns an independent, editable deep copy of the sh-ast record `node`
+     * was parsed from: the first half of a printed fix. Edit the copy, then pass
+     * it to {@link ShellSourceCode.getPrintedReplacement}.
+     *
+     * The copy is `structuredClone` of the record
+     * {@link ShellSourceCode.getSyntax} returns. sh-ast documents and tests
+     * ordinary `structuredClone` as the supported way to make an independent
+     * editable copy of a syntax subtree (sh-ast 0.7.0 README, "Editing and
+     * printing"), so no second parse is involved. The copy owns its records,
+     * arrays, positions and byte buffers. Editing it leaves this file's original
+     * syntax, its lint view, its cached traversal and the answers of view-aware
+     * helpers such as `resolveWord` and
+     * {@link ShellSourceCode.resolveWordText} unchanged. Each call returns a new
+     * copy.
+     *
+     * The copy's position fields keep their original values, and the copy has
+     * no view node: {@link ShellSourceCode.getViewNode},
+     * {@link ShellSourceCode.getIndexFromSyntaxPos} and the parse's position
+     * snapshot describe the original source, not the edit. Keep `node` to know
+     * which source range the fix replaces.
+     *
+     * @param node - A view node from this file's lint tree.
+     * @returns A deep copy of `node`'s original sh-ast record.
+     * @throws TypeError when `node` has no original record in this file: an
+     * auxiliary view (such as the `Slice` of `${x:1:2}`), a view node of another
+     * file, or an object that did not come from the parser.
+     */
+    getEditableSyntax(node: ShNode): SyntaxNode;
+    /**
+     * Prints `edited` with sh-ast's `printSync` and pairs the text with the
+     * source range it replaces, so a printed fix is
+     * `fix: (fixer) => fixer.replaceTextRange(r.range, r.text)`. `edited` is
+     * usually a copy from {@link ShellSourceCode.getEditableSyntax} of `node`
+     * or of one of its ancestors.
+     *
+     * The range is `node.range`, except that a `File` root replaces the whole
+     * text (`[0, text.length]`) whatever `node` is, which allows whole-file
+     * regeneration. `options` is passed to `printSync` unchanged.
+     *
+     * The printer formats; it does not replay the source. Its output starts at
+     * column 0 and indents nested lines with upstream's indentation (tabs by
+     * default, `Indent` spaces when `options.Indent` is set). Replacing a
+     * multi-line root nested inside other code, such as an `if` statement in a
+     * function body, therefore keeps the shell meaning but may change the
+     * formatting of its lines. Use a `Word` or `WordPart` root for a surgical
+     * fix that leaves the surrounding source as written.
+     *
+     * A `Stmt` root is adjusted so its text matches `node.range`. A statement's
+     * own leading and trailing comments lie outside its range, so they are not
+     * printed (the copy passed in is not modified). When `node` is a statement
+     * whose range ends in its `;` or `&` terminator, upstream prints the
+     * statement without a `;`, so a `;` is appended unless the edited statement
+     * prints its own `&`, `|&` or disown operator. Without this, replacing `a`
+     * in `a; b` would produce `a b`.
+     *
+     * @param node - A view node from this file's lint tree: the node the fix
+     * replaces.
+     * @param edited - The record to print: a `File`, `Stmt`, `Word`, `Assign`,
+     * `Command` or `WordPart`.
+     * @param options - Forwarded to `printSync` unchanged.
+     * @returns The range to replace and the printed text to put there.
+     * @throws TypeError when `node` has no original record in this file (see
+     * {@link ShellSourceCode.getEditableSyntax}), when `edited` is not a
+     * printable root (the message names its type), or when the printer's output
+     * is not valid UTF-8. Non-UTF-8 output comes back from `printSync` as a
+     * `Uint8Array` and is never decoded lossily into a fix.
+     * @throws `PrintError` or `PrintPanicError` (from sh-ast) when upstream's
+     * printer fails for `edited` or `options`.
+     */
+    getPrintedReplacement(node: ShNode, edited: SyntaxNode, options?: PrintOptions): {
+        range: [number, number];
+        text: string;
+    };
+    /**
+     * Converts a byte position from this file's original parse into the
+     * UTF-16 index ESLint uses for `range` and `text.slice`. sh-ast positions
+     * count UTF-8 bytes, so a raw `Offset` is wrong for any source with
+     * non-ASCII text before it. For example, in `echo 🎉 && echo 中文`,
+     * `getIndexFromSyntaxPos(binaryCmd.OpPos)` is the index where `&&` starts.
+     *
+     * The conversion is only correct for positions of this file's original
+     * parse, as read from {@link ShellSourceCode.getSyntax}'s records. The live
+     * positions of an edited or copied tree describe that edit, not this
+     * source.
+     *
+     * @param pos - A `SyntaxPos` from one of this file's original records.
+     * @returns The UTF-16 index of `pos` in this file's text.
+     * @throws RangeError when `pos` is invalid (`IsValid === false`), recovered
+     * (`IsRecovered === true`), or overflowed (`OffsetOverflow === true`), or
+     * when its offset is not a UTF-8 character boundary of this source. Such a
+     * position is never rounded to a nearby boundary.
+     * @throws TypeError when `pos` is not a `SyntaxPos`, or when this source
+     * code's tree was not built by this language's parser.
+     */
+    getIndexFromSyntaxPos(pos: SyntaxPos): number;
+    /**
+     * Converts a byte position from this file's original parse into a one-based
+     * ESLint location, the shape `context.report({ loc })` takes. The column
+     * counts UTF-16 code units, not bytes, and CRLF counts as one line break.
+     * Same contract as {@link ShellSourceCode.getIndexFromSyntaxPos}.
+     *
+     * @param pos - A `SyntaxPos` from one of this file's original records.
+     * @returns The one-based line and UTF-16 column of `pos`.
+     * @throws RangeError when `pos` is invalid, recovered, or overflowed, or
+     * when its offset is not a UTF-8 character boundary of this source.
+     * @throws TypeError when `pos` is not a `SyntaxPos`, or when this source
+     * code's tree was not built by this language's parser.
+     */
+    getLocFromSyntaxPos(pos: SyntaxPos): {
+        line: number;
+        column: number;
+    };
     /**
      * Returns the parent of `node`, or `undefined` for the root `File` node
      * (or any node visited before `traverse()` has run once). ESLint always
@@ -109,4 +447,3 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
         problems: FileProblem[];
     };
 }
-//# sourceMappingURL=shell-source-code.d.ts.map