@eslint-sh/eslint-plugin 0.5.0 → 0.6.0

package/dist/language/shell-source-code.js

@@ -1,5 +1,10 @@
 import { ConfigCommentParser, Directive, TextSourceCodeBase, VisitNodeStep, } from '@eslint/plugin-kit';
-import { isShellComment, isShellNode, shellVisitorKeys, walkShell } from './syntax-view.js';
+import { childNodes, isShellComment, projectedComments, projectedCoordinates, syntaxForNode, viewForSyntax, walkShell, } from './syntax-view.js';
+import { SourceCoordinates } from './source-coordinates.js';
+import { SYNTAX_INTERFACES, printSync } from 'sh-ast';
+import { resolveArgv0 } from 'sh-ast/analyze';
+import { buildCommandSiteIndex, rawCallExprFor, viewCommandSites } from './command-resolution.js';
+import { resolveWord } from './word-resolution.js';
 /**
  * Shared instance — `ConfigCommentParser` is stateless (see
  * `@eslint/plugin-kit`'s implementation), so every `ShellSourceCode`
@@ -39,12 +44,9 @@ function buildDirectiveLabels(directivePrefix) {
  * call: the leading `#` is already excluded, e.g. the source
  * `# eslint-disable-next-line sh/foo -- reason` produces
  * `comment.text === " eslint-disable-next-line sh/foo -- reason"`).
- * `ShNode`'s index signature types every field `unknown`, so this narrows
- * defensively rather than assuming the shape.
  */
 function getCommentText(comment) {
-    const { text } = comment;
-    return typeof text === 'string' ? text : '';
+    return comment.text;
 }
 /**
  * Length of the line terminator starting at `text[index]` — `2` for `\r\n`,
@@ -179,6 +181,75 @@ function computeUnusedDirectiveFixRange(comment, text) {
     }
     return [start, end + newlineLength];
 }
+/**
+ * Returns the byte offset of `pos` when it names an exact boundary the parser
+ * observed, and throws otherwise. Invalid, recovered, and overflowed positions
+ * carry no exact offset (upstream may report zero or a saturated value), so
+ * converting them would place a report or fix somewhere the parser never
+ * pointed. They are rejected rather than rounded to a nearby boundary.
+ *
+ * @throws TypeError when `pos` is not shaped like an sh-ast `SyntaxPos`.
+ * @throws RangeError when `pos` is invalid, recovered, or overflowed.
+ */
+function exactByteOffset(pos) {
+    const candidate = pos;
+    if (typeof candidate !== 'object' ||
+        candidate === null ||
+        typeof pos.Offset !== 'number' ||
+        typeof pos.IsValid !== 'boolean' ||
+        typeof pos.IsRecovered !== 'boolean' ||
+        typeof pos.OffsetOverflow !== 'boolean') {
+        throw new TypeError('expected an sh-ast SyntaxPos');
+    }
+    if (!pos.IsValid || pos.IsRecovered || pos.OffsetOverflow) {
+        throw new RangeError(`syntax position has no exact source offset (IsValid: ${String(pos.IsValid)}, ` +
+            `IsRecovered: ${String(pos.IsRecovered)}, OffsetOverflow: ${String(pos.OffsetOverflow)})`);
+    }
+    return pos.Offset;
+}
+/**
+ * The record types `printSync` accepts as a root: `File`, `Stmt`, `Word`,
+ * `Assign`, every `Command` and every `WordPart` (sh-ast's documented
+ * supported roots). Any other record makes upstream's printer fail, so
+ * {@link ShellSourceCode.getPrintedReplacement} rejects it up front with a
+ * `TypeError` that names the type instead of surfacing a printer error.
+ */
+const printableRootTypes = new Set([
+    'File',
+    'Stmt',
+    'Word',
+    'Assign',
+    ...SYNTAX_INTERFACES.Command,
+    ...SYNTAX_INTERFACES.WordPart,
+]);
+/**
+ * Returns `edited`'s record type when it is a printable root, and throws a
+ * `TypeError` naming the type otherwise. `edited` is checked as an unknown
+ * value because rule code can pass anything.
+ */
+function printableRootType(edited) {
+    const candidate = edited;
+    if (typeof candidate !== 'object' ||
+        candidate === null ||
+        !('Type' in candidate) ||
+        typeof candidate.Type !== 'string') {
+        throw new TypeError('expected an sh-ast syntax record to print');
+    }
+    if (!printableRootTypes.has(candidate.Type)) {
+        throw new TypeError(`cannot print a ${candidate.Type} as a fix: printSync accepts File, Stmt, Word, Assign, ` +
+            'Command and WordPart roots');
+    }
+    return candidate.Type;
+}
+/**
+ * Whether the printer writes `stmt`'s terminator itself. A background (`&`),
+ * coprocess (`|&`) or disowned statement prints its own operator; any other
+ * statement prints with no terminator at all, because upstream leaves `;` to
+ * the enclosing statement list.
+ */
+function printsOwnTerminator(stmt) {
+    return stmt.Background || stmt.Coprocess || stmt.Disown;
+}
 /**
  * Wraps `comment` in a shallow copy whose `.range` is
  * {@link computeUnusedDirectiveFixRange}'s (possibly widened) range, while
@@ -209,8 +280,8 @@ function withUnusedDirectiveFixRange(comment, text) {
  * `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`)
@@ -220,6 +291,24 @@ function withUnusedDirectiveFixRange(comment, text) {
  * 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 class ShellSourceCode extends TextSourceCodeBase {
@@ -254,7 +343,7 @@ export class ShellSourceCode extends TextSourceCodeBase {
      */
     #inlineConfigPattern;
     /**
-     * Comments gathered through the consumer's child graph. Source-order sorting
+     * Comments in the consumer's child graph. Source-order sorting
      * is required for repeated inline configuration; schema field order does not
      * encode physical source order. The lint view is a stable parse snapshot.
      */
@@ -265,15 +354,460 @@ export class ShellSourceCode extends TextSourceCodeBase {
      * config, once indirectly via `getDisableDirectives`/`applyInlineConfig`).
      */
     #inlineConfigNodes;
+    /** The normalized `languageOptions.dialect` this file was parsed with. */
+    #dialect;
+    /** The configured `languageOptions.shellVersion`, if the config supplied one. */
+    #shellVersion;
+    /** This file's coordinate index; see `#textCoordinates`. */
+    #ownCoordinates;
+    /**
+     * Every command site in this file, from one `enumerateCommands` call over
+     * the original syntax, built the first time a command helper needs it and
+     * reused for the rest of the lint run. Files whose rules never ask a
+     * command question never pay for (or fail on) enumeration.
+     */
+    #commandSites;
+    /**
+     * {@link ShellSourceCode.getCommandSites}'s answer: the index's sites in
+     * view terms, built once from `#commandSites` so every caller shares one
+     * frozen array.
+     */
+    #commandSiteViews;
     constructor(options) {
         super(options);
-        // Defensive default for direct construction outside the `ShellLanguage`
+        // Defensive defaults for direct construction outside the `ShellLanguage`
         // pipeline (e.g. unit tests) — `ShellLanguage.createSourceCode` always
-        // supplies the already-normalized, defaulted value.
+        // supplies the already-normalized, defaulted values.
         this.#directivePrefix = options.directivePrefix ?? 'eslint';
+        this.#dialect = options.dialect ?? 'bash';
+        this.#shellVersion = options.shellVersion;
         this.#directiveLabels = buildDirectiveLabels(this.#directivePrefix);
         this.#inlineConfigPattern = buildInlineConfigPattern(this.#directivePrefix);
     }
+    /**
+     * 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() {
+        return this.#dialect;
+    }
+    /**
+     * 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() {
+        return this.#shellVersion;
+    }
+    /**
+     * 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) {
+        if (typeof index !== 'number')
+            throw new TypeError('Expected `index` to be a number.');
+        const { line, column } = this.#textCoordinates().atIndex(index);
+        return { line, column };
+    }
+    /**
+     * 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) {
+        if (typeof loc !== 'object' ||
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- callers may be untyped JavaScript
+            loc === null ||
+            typeof loc.line !== 'number' ||
+            typeof loc.column !== 'number') {
+            throw new TypeError('Expected `loc` to be an object with numeric `line` and `column` properties.');
+        }
+        return this.#textCoordinates().indexAt(loc.line, loc.column);
+    }
+    /**
+     * The coordinate index of this file's text: the one the language built while
+     * parsing, or, for a source code constructed directly, one built from the
+     * text on first use.
+     */
+    #textCoordinates() {
+        this.#ownCoordinates ??= projectedCoordinates(this.ast) ?? new SourceCoordinates(this.text);
+        return this.#ownCoordinates;
+    }
+    /**
+     * 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, options) {
+        const resolution = resolveWord(word, options ?? this.#defaultWordOptions(word));
+        return resolution.static ? resolution.text : null;
+    }
+    /**
+     * The `resolveWord` options implied by `word`'s grammar position when the
+     * caller supplies none: command-argument context for a `CallExpr` argument,
+     * otherwise `resolveWord`'s own conservative default.
+     */
+    #defaultWordOptions(word) {
+        const parent = this.getParent(word);
+        const isCommandArgument = parent?.type === 'CallExpr' && Array.isArray(parent.args) && parent.args.includes(word);
+        return isCommandArgument ? { context: 'command-argument' } : undefined;
+    }
+    /**
+     * 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) {
+        const argv0 = this.#commandSiteFor(callExpr)?.argv0;
+        return argv0?.static ? argv0.text : 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, options) {
+        const site = this.#commandSiteFor(callExpr);
+        return site ? resolveArgv0(site, options) : 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() {
+        this.#commandSiteViews ??= viewCommandSites(this.ast, this.#getCommandSiteIndex());
+        return this.#commandSiteViews;
+    }
+    /**
+     * 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) {
+        const syntax = syntaxForNode(node);
+        // A view node of another file also has a record; it is not this file's.
+        return syntax !== undefined && viewForSyntax(this.ast, syntax) === node ? syntax : 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) {
+        return viewForSyntax(this.ast, syntax);
+    }
+    /**
+     * 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) {
+        return structuredClone(this.#originalSyntaxFor(node));
+    }
+    /**
+     * 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, edited, options) {
+        const original = this.#originalSyntaxFor(node);
+        const rootType = printableRootType(edited);
+        const root = edited.Type === 'Stmt' ? { ...edited, Comments: null } : edited;
+        const printed = printSync(root, options);
+        if (typeof printed !== 'string') {
+            throw new TypeError('printSync produced output that is not valid UTF-8; a text fix cannot hold it without ' +
+                'lossy decoding');
+        }
+        if (rootType === 'File') {
+            return { range: [0, this.text.length], text: printed };
+        }
+        const dropsTerminator = edited.Type === 'Stmt' &&
+            original.Type === 'Stmt' &&
+            original.Semicolon.IsValid &&
+            !printsOwnTerminator(edited);
+        return {
+            range: [node.range[0], node.range[1]],
+            text: dropsTerminator ? `${printed};` : printed,
+        };
+    }
+    /**
+     * `node`'s original record in this file, or a `TypeError` when it has none,
+     * so the printed-fix helpers never copy or replace a range they cannot tie
+     * to this file's parse.
+     */
+    #originalSyntaxFor(node) {
+        const syntax = this.getSyntax(node);
+        if (syntax === undefined) {
+            throw new TypeError('expected a view node parsed from this file; auxiliary views, view nodes of other ' +
+                'files and objects that did not come from the parser have no original syntax');
+        }
+        return syntax;
+    }
+    /**
+     * 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) {
+        return this.#coordinateAt(pos).index;
+    }
+    /**
+     * 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) {
+        const { line, column } = this.#coordinateAt(pos);
+        return { line, column };
+    }
+    /**
+     * Converts `pos` with the coordinate index projection built for this
+     * file's source, so the file pays for one index however many positions
+     * rules convert.
+     */
+    #coordinateAt(pos) {
+        const coordinates = projectedCoordinates(this.ast);
+        if (coordinates === undefined) {
+            throw new TypeError('expected a parsed shell File from this language adapter');
+        }
+        return coordinates.fromByteOffset(exactByteOffset(pos));
+    }
+    /** This file's command-site index, built by one `enumerateCommands` call on first use. */
+    #getCommandSiteIndex() {
+        this.#commandSites ??= buildCommandSiteIndex(this.ast);
+        return this.#commandSites;
+    }
+    /**
+     * Looks up `callExpr`'s `CommandSite` in this file's lazily built index.
+     * The `CallExpr` is validated before the index is built, so a misuse
+     * reports `TypeError` rather than an unrelated analysis error.
+     */
+    #commandSiteFor(callExpr) {
+        const raw = rawCallExprFor(callExpr);
+        return this.#getCommandSiteIndex().byNode.get(raw);
+    }
     /**
      * Returns the parent of `node`, or `undefined` for the root `File` node
      * (or any node visited before `traverse()` has run once). ESLint always
@@ -300,19 +834,8 @@ export class ShellSourceCode extends TextSourceCodeBase {
                 this.#parents.set(node, parent);
             }
             steps.push(new VisitNodeStep({ target: node, phase: 1, args: [node, parent] }));
-            const keys = shellVisitorKeys[node.type] ?? [];
-            for (const key of keys) {
-                const value = node[key];
-                if (Array.isArray(value)) {
-                    for (const child of value) {
-                        if (isShellNode(child)) {
-                            visit(child, node);
-                        }
-                    }
-                }
-                else if (isShellNode(value)) {
-                    visit(value, node);
-                }
+            for (const child of childNodes(node)) {
+                visit(child, node);
             }
             steps.push(new VisitNodeStep({ target: node, phase: 2, args: [node, parent] }));
         };
@@ -323,15 +846,22 @@ export class ShellSourceCode extends TextSourceCodeBase {
      * Returns retained comments in source order. Reflection-field order can place
      * a later enclosing comment before an earlier nested comment, so sort by the
      * exact derived source span before directive and inline-config processing.
+     *
+     * A tree built by the parser already recorded its comments during projection,
+     * so no extra tree walk is needed. Only a tree constructed some other way
+     * (for example, passed directly to the constructor) is walked to find them.
      */
     #getComments() {
         if (!this.#comments) {
-            const comments = [];
-            walkShell(this.ast, (node) => {
-                if (isShellComment(node)) {
-                    comments.push(node);
-                }
-            });
+            const projected = projectedComments(this.ast);
+            const comments = projected === undefined ? [] : [...projected];
+            if (projected === undefined) {
+                walkShell(this.ast, (node) => {
+                    if (isShellComment(node)) {
+                        comments.push(node);
+                    }
+                });
+            }
             comments.sort((a, b) => a.range[0] - b.range[0] || a.range[1] - b.range[1]);
             this.#comments = comments;
         }
@@ -418,4 +948,3 @@ export class ShellSourceCode extends TextSourceCodeBase {
         return { configs, problems };
     }
 }
-//# sourceMappingURL=shell-source-code.js.map