@eslint-sh/eslint-plugin 0.5.0 → 0.6.0

package/dist/language/source-coordinates.d.ts

@@ -13,11 +13,22 @@ export interface ISourceCoordinate {
 /** Source-bound conversion shared by tree projection and diagnostic adaptation. @internal */
 export declare class SourceCoordinates {
     #private;
-    /** Build one reusable coordinate index for the exact source passed to the parser. @internal */
+    /**
+     * Build one reusable coordinate index for the exact source passed to the parser.
+     * UTF-8 widths are computed from UTF-16 code units rather than by encoding.
+     * @internal
+     */
     constructor(source: string);
     /** Reject mismatched/out-of-source/interior-byte positions rather than inventing a fix boundary. @internal */
     fromByteOffset(offset: number): ISourceCoordinate;
     /** Derive a one-based location from a known JavaScript source index. @internal */
     atIndex(index: number): ISourceCoordinate;
+    /**
+     * Derive the JavaScript source index of a one-based `line`/`column`. The
+     * column may name any position on the line up to and including its line
+     * break (or the end of the source on the last line), the same range a
+     * location from {@link SourceCoordinates.atIndex} can take.
+     * @internal
+     */
+    indexAt(line: number, column: number): number;
 }
-//# sourceMappingURL=source-coordinates.d.ts.map

package/dist/language/source-coordinates.js

@@ -4,34 +4,71 @@
  * mutating the raw syntax position. Display widths, graphemes, and tab expansion
  * are deliberately outside this contract.
  */
+/**
+ * Sentinel in the byte table for an offset that falls inside a multi-byte
+ * UTF-8 sequence: such an offset has no JavaScript string counterpart.
+ */
+const INTERIOR_BYTE = -1;
 /** Source-bound conversion shared by tree projection and diagnostic adaptation. @internal */
 export class SourceCoordinates {
-    /** Only complete UTF-8 character boundaries have meaningful JavaScript counterparts. */
-    #byteIndices = new Map();
+    /**
+     * UTF-16 index for every UTF-8 byte offset from 0 through the encoded
+     * length; {@link INTERIOR_BYTE} marks offsets that are not character
+     * boundaries. Byte offsets are the encoding `TextEncoder` produces for the
+     * source, so a lone surrogate occupies the three bytes of U+FFFD.
+     */
+    #byteIndices;
     /** UTF-16 start indices of lines; CRLF becomes one line break at its LF. */
     #lineStarts = [0];
     /** The source extent constrains all derived ranges, including empty-file fallback. */
     #length;
-    /** Build one reusable coordinate index for the exact source passed to the parser. @internal */
+    /**
+     * Build one reusable coordinate index for the exact source passed to the parser.
+     * UTF-8 widths are computed from UTF-16 code units rather than by encoding.
+     * @internal
+     */
     constructor(source) {
         this.#length = source.length;
+        // No UTF-16 code unit needs more than three UTF-8 bytes (a surrogate pair
+        // is two units and four bytes), so this bounds the encoded length.
+        const byteIndices = new Int32Array(source.length * 3 + 1).fill(INTERIOR_BYTE);
+        byteIndices[0] = 0;
         let bytes = 0;
         let index = 0;
-        this.#byteIndices.set(0, 0);
-        const encoder = new TextEncoder();
-        for (const character of source) {
-            bytes += encoder.encode(character).length;
-            index += character.length;
-            this.#byteIndices.set(bytes, index);
-            if (character === '\n') {
+        while (index < source.length) {
+            const unit = source.charCodeAt(index);
+            let width = 3;
+            let units = 1;
+            if (unit < 0x80) {
+                width = 1;
+            }
+            else if (unit < 0x800) {
+                width = 2;
+            }
+            else if (unit >= 0xd800 && unit <= 0xdbff && index + 1 < source.length) {
+                const next = source.charCodeAt(index + 1);
+                if (next >= 0xdc00 && next <= 0xdfff) {
+                    // A surrogate pair is one supplementary character: four bytes.
+                    width = 4;
+                    units = 2;
+                }
+            }
+            // Every other unit, including a lone surrogate (encoded as U+FFFD), is three bytes.
+            bytes += width;
+            index += units;
+            byteIndices[bytes] = index;
+            if (unit === 0x0a) {
                 this.#lineStarts.push(index);
             }
         }
+        this.#byteIndices = byteIndices.subarray(0, bytes + 1);
     }
     /** Reject mismatched/out-of-source/interior-byte positions rather than inventing a fix boundary. @internal */
     fromByteOffset(offset) {
-        const index = this.#byteIndices.get(offset);
-        if (!Number.isInteger(offset) || index === undefined) {
+        const index = Number.isInteger(offset) && offset >= 0 && offset < this.#byteIndices.length
+            ? this.#byteIndices[offset]
+            : INTERIOR_BYTE;
+        if (index === INTERIOR_BYTE) {
             throw new RangeError(`byte offset ${String(offset)} is not a boundary in this source`);
         }
         return this.atIndex(index);
@@ -44,7 +81,7 @@ export class SourceCoordinates {
         let low = 0;
         let high = this.#lineStarts.length;
         while (low + 1 < high) {
-            const middle = Math.floor((low + high) / 2);
+            const middle = (low + high) >>> 1;
             if (this.#lineStarts[middle] <= index) {
                 low = middle;
             }
@@ -54,5 +91,22 @@ export class SourceCoordinates {
         }
         return { index, line: low + 1, column: index - this.#lineStarts[low] + 1 };
     }
+    /**
+     * Derive the JavaScript source index of a one-based `line`/`column`. The
+     * column may name any position on the line up to and including its line
+     * break (or the end of the source on the last line), the same range a
+     * location from {@link SourceCoordinates.atIndex} can take.
+     * @internal
+     */
+    indexAt(line, column) {
+        if (!Number.isInteger(line) || line < 1 || line > this.#lineStarts.length) {
+            throw new RangeError(`line ${String(line)} is outside this source (lines 1-${String(this.#lineStarts.length)})`);
+        }
+        const start = this.#lineStarts[line - 1];
+        const last = line === this.#lineStarts.length ? this.#length : this.#lineStarts[line] - 1;
+        if (!Number.isInteger(column) || column < 1 || start + column - 1 > last) {
+            throw new RangeError(`column ${String(column)} is outside line ${String(line)} (columns 1-${String(last - start + 1)})`);
+        }
+        return start + column - 1;
+    }
 }
-//# sourceMappingURL=source-coordinates.js.map

package/dist/language/syntax-view.d.ts

@@ -1,52 +1,66 @@
 import type { File, Node as SyntaxNode, PositionSnapshot } from 'sh-ast';
-/** An ESLint location counts UTF-16 units, with both line and column starting at one. @public */
-export interface ShellPosition {
-    /** One-based source line, with CRLF treated as one line break. */
-    readonly line: number;
-    /** One-based UTF-16 column; tabs and grapheme widths are not expanded. */
-    readonly column: number;
-}
-/**
- * A node in the consumer's lint view. Scalar/child fields use lowercase upstream
- * spellings; syntax fidelity belongs to the associated upstream tree. Auxiliary
- * view nodes may have spans derived from children and are not upstream Nodes.
+import type { WordResolution } from 'sh-ast/analyze';
+import type { ShellNodeMap, ShellNodeOf, ShellNodeType } from './lint-view-types.js';
+import { SourceCoordinates } from './source-coordinates.js';
+/**
+ * The lint view's node types are computed from `sh-ast`'s generated interfaces
+ * (see `lint-view-types.ts`); this module builds the values and owns the
+ * runtime projection those types describe.
+ */
+export type { ShellNodeField, ShellNodeMap, ShellNodeOf, ShellNodeType, ShellPosition, } from './lint-view-types.js';
+/**
+ * A node in the consumer's lint view: the union of every node type, so
+ * narrowing on `type` gives that node's fields with no cast. Scalar/child fields
+ * use lowercase upstream spellings; syntax fidelity belongs to the associated
+ * upstream tree. Auxiliary view nodes may have spans derived from children and
+ * are not upstream Nodes.
  * @public
  */
-export interface ShellNode {
-    /** Original syntax kind retained as the discriminator for lint selectors. */
-    readonly type: string;
-    /** Half-open UTF-16 span used to slice source and place fixes. */
-    readonly range: readonly [number, number];
-    /** Source-derived endpoints for ESLint diagnostics. */
-    readonly loc: {
-        readonly start: ShellPosition;
-        readonly end: ShellPosition;
-    };
-    /** Lowercase syntax fields containing consumer children or decoded scalar values. */
-    readonly [field: string]: unknown;
-}
+export type ShellNode = ShellNodeMap[ShellNodeType];
 /** The lint root has a statement collection even when upstream represents it as nil. @public */
-export interface ShellFile extends ShellNode {
-    /** Root discriminator retained for selectors. */
-    readonly type: 'File';
-    /** Top-level statements in source order; nil upstream slices become an empty view. */
-    readonly stmts: readonly ShellNode[];
-}
+export type ShellFile = ShellNodeOf<'File'>;
 /** Directive processing uses the comment text without its leading shell hash. @public */
-export interface ShellComment extends ShellNode {
-    /** Comment discriminator used by directive collection. */
-    readonly type: 'Comment';
-    /** Decoded comment content after the leading hash, preserving its whitespace. */
-    readonly text: string;
-}
+export type ShellComment = ShellNodeOf<'Comment'>;
 /** ESLint child relationships follow the consumer projection, including auxiliary views; not upstream Walk ordering. @internal */
 export declare const shellVisitorKeys: Readonly<Record<string, readonly string[]>>;
-/** Identifies projected children without confusing raw position records or byte strings with nodes. @internal */
-export declare function isShellNode(value: unknown): value is ShellNode;
 /** Directive processing requires both the comment kind and its decoded text. @internal */
 export declare function isShellComment(node: ShellNode): node is ShellComment;
+/**
+ * Returns every comment view projected under `root`, in projection order, or
+ * undefined when `root` was not built by {@link adaptSyntaxFile}. Callers that
+ * need source order sort the result themselves. Saves a full-tree walk whose
+ * only purpose would be to rediscover comments the projection already visited.
+ * @internal
+ */
+export declare function projectedComments(root: ShellNode): readonly ShellComment[] | undefined;
+/**
+ * Returns the coordinate index `root` was projected with: the conversion for
+ * the exact source `root`'s original parse came from. Undefined when `root`
+ * was not built by {@link adaptSyntaxFile}, which means there is no original
+ * parse whose positions could be converted.
+ * @internal
+ */
+export declare function projectedCoordinates(root: ShellNode): SourceCoordinates | undefined;
 /** Returns the actual parser node, or undefined for consumer-created/synthetic views. @internal */
 export declare function syntaxForNode(node: ShellNode): SyntaxNode | undefined;
+/**
+ * Returns the view node projected from `syntax` within the lint view rooted at
+ * `root`, or undefined when `syntax` is not a real parser node of that view.
+ * This is the syntax → view direction of {@link syntaxForNode}'s association,
+ * recorded during projection rather than recovered by walking the view.
+ * @internal
+ */
+export declare function viewForSyntax(root: ShellFile, syntax: SyntaxNode): ShellNode | undefined;
+/**
+ * `resolution` as its LF equivalent: when `word` is a parser `Word` whose view
+ * was ended before a CRLF `\r` (see {@link endsBeforeCrlfNewline}), a static
+ * text loses that one trailing `\r`, so `ls\r\n` names the command `ls`, the
+ * same as on LF input. Any other resolution is returned unchanged; a word
+ * whose own text ends in `\r` (`$'\r'`) is not followed directly by a
+ * terminator `\r` and keeps it.
+ * @internal
+ */
+export declare function withoutCrlfCarriageReturn(word: SyntaxNode | null, resolution: WordResolution): WordResolution;
 /**
  * Builds a source-bound view immediately from one parse's File and Positions.
  * Snapshot bounds describe that original parse, never subsequent syntax edits.
@@ -55,6 +69,13 @@ export declare function syntaxForNode(node: ShellNode): SyntaxNode | undefined;
  * @internal
  */
 export declare function adaptSyntaxFile(file: File, source: string, positions: PositionSnapshot): ShellFile;
+/**
+ * The projected children of `node` in visitor-key order, whichever of its
+ * fields hold them (a single child or a slice). Traversal is keyed by the
+ * schema's field names rather than by the typed fields, so this is the one
+ * place that reads a view through its dynamic keys; rules read typed fields.
+ * @internal
+ */
+export declare function childNodes(node: ShellNode): ShellNode[];
 /** Consumer traversal visits each projected child, including auxiliary views, without claiming upstream Walk control semantics. @internal */
 export declare function walkShell(root: ShellNode, visit: (node: ShellNode) => void): void;
-//# sourceMappingURL=syntax-view.d.ts.map

package/dist/language/syntax-view.js

@@ -9,10 +9,50 @@ import { SYNTAX_INTERFACES, SYNTAX_SCHEMA } from 'sh-ast';
 import { SourceCoordinates } from './source-coordinates.js';
 /** Raw syntax is associated without adding parent cycles or consumer fields to its records. */
 const originalSyntax = new WeakMap();
+/**
+ * The inverse association, recorded per projected root: within one lint view,
+ * each real parser node maps to the one view node projected from it. Keyed by
+ * root so two views projected from the same syntax never answer for each other.
+ */
+const projectedViews = new WeakMap();
 /** The upstream Node union distinguishes real nodes from auxiliary syntax records. */
 const nodeTypes = new Set(SYNTAX_INTERFACES.Node);
 /** Parser input is a JavaScript string; unexpected invalid-byte fields must never be silently replaced. */
 const textDecoder = new TextDecoder('utf-8', { fatal: true });
+/**
+ * Projection plan per upstream syntax type, derived once from the schema so
+ * projecting a record never re-enumerates or re-lowercases schema fields. Only
+ * types present here are projectable; anything else is an unknown record.
+ */
+const projectionPlans = new Map(Object.entries(SYNTAX_SCHEMA).map(([type, schema]) => [
+    type,
+    Object.entries(schema.fields)
+        .filter(([, field]) => field.kind !== 'position')
+        .map(([name, field]) => ({
+        name,
+        key: name.toLowerCase(),
+        kind: field.kind === 'struct' || field.kind === 'interface'
+            ? 'child'
+            : field.kind === 'string'
+                ? 'text'
+                : 'value',
+        slice: field.slice,
+    })),
+]));
+/**
+ * Comment views observed while projecting each root, in projection order (not
+ * source order). Keyed by root identity so a view carries no extra fields;
+ * roots this module did not build have no entry.
+ */
+const projectedCommentsByRoot = new WeakMap();
+/**
+ * The coordinate index each root was projected with, keyed by root identity.
+ * Upstream byte positions are only meaningful against the exact source they
+ * were parsed from, so the one index projection built for that source is the
+ * one every later byte → UTF-16 conversion for the file reuses. Roots this
+ * module did not build have no entry.
+ */
+const projectedCoordinatesByRoot = new WeakMap();
 /** ESLint child relationships follow the consumer projection, including auxiliary views; not upstream Walk ordering. @internal */
 export const shellVisitorKeys = Object.freeze(Object.fromEntries(Object.entries(SYNTAX_SCHEMA).map(([name, schema]) => [
     name,
@@ -28,8 +68,8 @@ function isRecord(value) {
 function isSyntaxNode(value) {
     return isRecord(value) && typeof value.Type === 'string' && nodeTypes.has(value.Type);
 }
-/** Identifies projected children without confusing raw position records or byte strings with nodes. @internal */
-export function isShellNode(value) {
+/** Identifies projected children without confusing raw position records or byte strings with nodes. */
+function isShellNode(value) {
     return isRecord(value) && typeof value.type === 'string' && Array.isArray(value.range);
 }
 /** Directive processing requires both the comment kind and its decoded text. @internal */
@@ -40,10 +80,40 @@ export function isShellComment(node) {
 function isShellFile(node) {
     return node.type === 'File' && Array.isArray(node.stmts) && node.stmts.every(isShellNode);
 }
+/**
+ * Returns every comment view projected under `root`, in projection order, or
+ * undefined when `root` was not built by {@link adaptSyntaxFile}. Callers that
+ * need source order sort the result themselves. Saves a full-tree walk whose
+ * only purpose would be to rediscover comments the projection already visited.
+ * @internal
+ */
+export function projectedComments(root) {
+    return projectedCommentsByRoot.get(root);
+}
+/**
+ * Returns the coordinate index `root` was projected with: the conversion for
+ * the exact source `root`'s original parse came from. Undefined when `root`
+ * was not built by {@link adaptSyntaxFile}, which means there is no original
+ * parse whose positions could be converted.
+ * @internal
+ */
+export function projectedCoordinates(root) {
+    return projectedCoordinatesByRoot.get(root);
+}
 /** Returns the actual parser node, or undefined for consumer-created/synthetic views. @internal */
 export function syntaxForNode(node) {
     return originalSyntax.get(node);
 }
+/**
+ * Returns the view node projected from `syntax` within the lint view rooted at
+ * `root`, or undefined when `syntax` is not a real parser node of that view.
+ * This is the syntax → view direction of {@link syntaxForNode}'s association,
+ * recorded during projection rather than recovered by walking the view.
+ * @internal
+ */
+export function viewForSyntax(root, syntax) {
+    return projectedViews.get(root)?.get(syntax);
+}
 /** Converts valid source-associated Go strings; invalid byte sequences have no faithful text view here. */
 function sourceText(value) {
     if (typeof value === 'string') {
@@ -54,6 +124,50 @@ function sourceText(value) {
     }
     throw new TypeError('shell text view expected a Go string');
 }
+/**
+ * Parser nodes whose view span was shortened by {@link endsBeforeCrlfNewline}.
+ * Keyed by the raw syntax record, which is what word-resolution results are
+ * computed from, so a resolver can tell that a trailing `\r` in its text is
+ * the line terminator's and not the word's (see {@link withoutCrlfCarriageReturn}).
+ */
+const crlfTrimmedViews = new WeakSet();
+/**
+ * Whether `span` ends just after the `\r` of a `\r\n` line terminator.
+ *
+ * The parser treats only `\n` as a line break, so on CRLF input it keeps the
+ * `\r` before it as an ordinary character of whatever is last on the line: an
+ * unbraced parameter expansion or a word-final literal includes it in both its
+ * bounds and its value (`ls $z\r\n` puts `$z` at `[3,6]`). sh-ast reports that
+ * faithfully and leaves adaptation to the consumer. The lint view is that
+ * consumer's surface, and a CRLF file must lint like its LF equivalent, so the
+ * view ends such a node before the `\r`: messages never print it, and a fix or
+ * suggestion that rewrites the node's range never moves it (`ls "$z"\r\n`,
+ * not `ls "$z\r"\n`). A node whose text continues past the line break (a
+ * quoted string or here-doc body spanning lines) never ends there, so this
+ * touches only nodes the line terminator cuts off. A span made only of the
+ * `\r` itself is left alone, so no real node becomes empty.
+ */
+function endsBeforeCrlfNewline(source, span) {
+    const end = span.end.index;
+    return end - span.start.index > 1 && source[end - 1] === '\r' && source[end] === '\n';
+}
+/**
+ * `resolution` as its LF equivalent: when `word` is a parser `Word` whose view
+ * was ended before a CRLF `\r` (see {@link endsBeforeCrlfNewline}), a static
+ * text loses that one trailing `\r`, so `ls\r\n` names the command `ls`, the
+ * same as on LF input. Any other resolution is returned unchanged; a word
+ * whose own text ends in `\r` (`$'\r'`) is not followed directly by a
+ * terminator `\r` and keeps it.
+ * @internal
+ */
+export function withoutCrlfCarriageReturn(word, resolution) {
+    if (word === null || !crlfTrimmedViews.has(word) || !resolution.static) {
+        return resolution;
+    }
+    return resolution.text.endsWith('\r')
+        ? { static: true, text: resolution.text.slice(0, -1) }
+        : resolution;
+}
 /**
  * Builds a source-bound view immediately from one parse's File and Positions.
  * Snapshot bounds describe that original parse, never subsequent syntax edits.
@@ -66,18 +180,26 @@ export function adaptSyntaxFile(file, source, positions) {
         throw new TypeError('shell view requires a source position snapshot');
     }
     const coordinates = new SourceCoordinates(source);
+    const views = new WeakMap();
     const wholeSource = { start: coordinates.atIndex(0), end: coordinates.atIndex(source.length) };
     /** Invalid/recovered positions have no exact text boundary; the enclosing view supplies an explicit consumer fallback. */
     const position = (raw, fallback) => raw.IsValid && !raw.IsRecovered ? coordinates.fromByteOffset(raw.Offset) : fallback;
+    /** Comment views in projection order; registered against the root once projection succeeds. */
+    const comments = [];
     /** Each projected record owns its derived fields, while real syntax nodes retain their original identity. */
     const project = (raw, fallback) => {
-        if (!isRecord(raw) || typeof raw.Type !== 'string' || !Object.hasOwn(SYNTAX_SCHEMA, raw.Type)) {
+        if (!isRecord(raw) || typeof raw.Type !== 'string') {
+            throw new TypeError('shell view expected a known upstream syntax record');
+        }
+        const plan = projectionPlans.get(raw.Type);
+        if (plan === undefined) {
             throw new TypeError('shell view expected a known upstream syntax record');
         }
-        const schema = SYNTAX_SCHEMA[raw.Type];
         const realNode = isSyntaxNode(raw);
         // eslint-disable-next-line @api-extractor-tools/forgotten-export -- This span belongs only to the private projection closure, not the exported signature.
         let span = fallback;
+        // Whether this node's span lost a CRLF carriage return (see `endsBeforeCrlfNewline`).
+        let trimmedCarriageReturn = false;
         if (realNode) {
             const observed = positions.get(raw);
             if (observed === undefined) {
@@ -87,78 +209,111 @@ export function adaptSyntaxFile(file, source, positions) {
                 start: position(observed.Pos, fallback.start),
                 end: position(observed.End, fallback.end),
             };
+            if (endsBeforeCrlfNewline(source, span)) {
+                span = { start: span.start, end: coordinates.atIndex(span.end.index - 1) };
+                trimmedCarriageReturn = true;
+                crlfTrimmedViews.add(raw);
+            }
         }
-        const fields = {};
-        const children = [];
-        for (const [name, field] of Object.entries(schema.fields)) {
-            if (field.kind === 'position') {
-                continue;
+        // Schema fields first, in schema order, then `type`, `range` and `loc`.
+        const view = {};
+        // Auxiliary records take their span from the extent of their projected children.
+        let childStart = Number.POSITIVE_INFINITY;
+        let childEnd = Number.NEGATIVE_INFINITY;
+        const include = (child) => {
+            if (child.range[0] < childStart) {
+                childStart = child.range[0];
             }
-            const value = raw[name];
-            const key = name.toLowerCase();
-            if (field.kind === 'struct' || field.kind === 'interface') {
+            if (child.range[1] > childEnd) {
+                childEnd = child.range[1];
+            }
+            return child;
+        };
+        for (const field of plan) {
+            const value = raw[field.name];
+            if (field.kind === 'child') {
                 if (field.slice) {
                     const items = value === null ? [] : value;
                     if (!Array.isArray(items)) {
-                        throw new TypeError(`shell view expected ${raw.Type}.${name} to be a slice`);
+                        throw new TypeError(`shell view expected ${raw.Type}.${field.name} to be a slice`);
+                    }
+                    const projected = [];
+                    for (const item of items) {
+                        if (item !== null) {
+                            projected.push(include(project(item, span)));
+                        }
                     }
-                    const projected = items
-                        .filter((item) => item !== null)
-                        .map((item) => project(item, span));
-                    fields[key] = projected;
-                    children.push(...projected);
+                    view[field.key] = projected;
                 }
                 else if (value !== null) {
-                    const child = project(value, span);
-                    fields[key] = child;
-                    children.push(child);
+                    view[field.key] = include(project(value, span));
                 }
             }
             else {
-                fields[key] = field.kind === 'string' ? sourceText(value) : value;
+                const text = field.kind === 'text' ? sourceText(value) : value;
+                view[field.key] =
+                    trimmedCarriageReturn && typeof text === 'string' && text.endsWith('\r')
+                        ? text.slice(0, -1)
+                        : text;
             }
         }
-        if (!realNode && children.length > 0) {
-            span = {
-                start: coordinates.atIndex(Math.min(...children.map((node) => node.range[0]))),
-                end: coordinates.atIndex(Math.max(...children.map((node) => node.range[1]))),
-            };
+        if (!realNode && childStart !== Number.POSITIVE_INFINITY) {
+            span = { start: coordinates.atIndex(childStart), end: coordinates.atIndex(childEnd) };
         }
-        const view = {
-            ...fields,
-            type: raw.Type,
-            range: [span.start.index, span.end.index],
-            loc: {
-                start: { line: span.start.line, column: span.start.column },
-                end: { line: span.end.line, column: span.end.column },
-            },
+        view.type = raw.Type;
+        view.range = [span.start.index, span.end.index];
+        view.loc = {
+            start: { line: span.start.line, column: span.start.column },
+            end: { line: span.end.line, column: span.end.column },
         };
+        const node = view;
+        if (isShellComment(node)) {
+            comments.push(node);
+        }
         if (realNode) {
-            originalSyntax.set(view, raw);
+            originalSyntax.set(node, raw);
+            views.set(raw, node);
         }
-        return view;
+        return node;
     };
     const root = project(file, wholeSource);
     if (!isShellFile(root)) {
         throw new TypeError('shell view expected a File with statements');
     }
+    projectedViews.set(root, views);
+    projectedCommentsByRoot.set(root, comments);
+    projectedCoordinatesByRoot.set(root, coordinates);
     return root;
 }
-/** Consumer traversal visits each projected child, including auxiliary views, without claiming upstream Walk control semantics. @internal */
-export function walkShell(root, visit) {
-    visit(root);
-    for (const key of shellVisitorKeys[root.type] ?? []) {
-        const value = root[key];
+/**
+ * The projected children of `node` in visitor-key order, whichever of its
+ * fields hold them (a single child or a slice). Traversal is keyed by the
+ * schema's field names rather than by the typed fields, so this is the one
+ * place that reads a view through its dynamic keys; rules read typed fields.
+ * @internal
+ */
+export function childNodes(node) {
+    const fields = node;
+    const children = [];
+    for (const key of shellVisitorKeys[node.type] ?? []) {
+        const value = fields[key];
         if (Array.isArray(value)) {
             for (const child of value) {
                 if (isShellNode(child)) {
-                    walkShell(child, visit);
+                    children.push(child);
                 }
             }
         }
         else if (isShellNode(value)) {
-            walkShell(value, visit);
+            children.push(value);
         }
     }
+    return children;
+}
+/** Consumer traversal visits each projected child, including auxiliary views, without claiming upstream Walk control semantics. @internal */
+export function walkShell(root, visit) {
+    visit(root);
+    for (const child of childNodes(root)) {
+        walkShell(child, visit);
+    }
 }
-//# sourceMappingURL=syntax-view.js.map

package/dist/language/word-resolution.d.ts

@@ -1,11 +1,12 @@
 import type { ResolveWordOptions, WordResolution } from 'sh-ast/analyze';
-import type { ShellNode } from './syntax-view.js';
+import type { ShellNodeOf } from './syntax-view.js';
 /**
  * Resolves a parsed lint Word using the upstream-shaped syntax associated with it.
  * The view supplies locations and selector fields; sh-ast/analyze owns the word
  * interpretation. Fabricated or synthetic view nodes have no source syntax and
  * are rejected instead of being treated as known or unknown shell values.
+ * A static word that ends a line of a CRLF file resolves without the line
+ * terminator's carriage return, as it would on LF input.
  * @public
  */
-export declare function resolveWord(word: ShellNode, options?: ResolveWordOptions): WordResolution;
-//# sourceMappingURL=word-resolution.d.ts.map
+export declare function resolveWord(word: ShellNodeOf<'Word'>, options?: ResolveWordOptions): WordResolution;

package/dist/language/word-resolution.js

@@ -1,11 +1,13 @@
 /** Bridges custom-rule analysis from ESLint view identity back to faithful syntax. */
 import { resolveWord as resolveSyntaxWord } from 'sh-ast/analyze';
-import { syntaxForNode } from './syntax-view.js';
+import { syntaxForNode, withoutCrlfCarriageReturn } from './syntax-view.js';
 /**
  * Resolves a parsed lint Word using the upstream-shaped syntax associated with it.
  * The view supplies locations and selector fields; sh-ast/analyze owns the word
  * interpretation. Fabricated or synthetic view nodes have no source syntax and
  * are rejected instead of being treated as known or unknown shell values.
+ * A static word that ends a line of a CRLF file resolves without the line
+ * terminator's carriage return, as it would on LF input.
  * @public
  */
 export function resolveWord(word, options) {
@@ -13,6 +15,5 @@ export function resolveWord(word, options) {
     if (syntax?.Type !== 'Word') {
         throw new TypeError('resolveWord expects a parsed shell Word from this language adapter');
     }
-    return resolveSyntaxWord(syntax, options);
+    return withoutCrlfCarriageReturn(syntax, resolveSyntaxWord(syntax, options));
 }
-//# sourceMappingURL=word-resolution.js.map