@eslint/shell 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview The ShellSourceCode class, the SourceCode implementation that
+ * ESLint uses to interact with a parsed shell script.
+ */
+import { Directive, TextSourceCodeBase } from "@eslint/plugin-kit";
+import type { FileProblem, RulesConfig, SourceLocation, SourceRange, TraversalStep } from "@eslint/core";
+import type { ShellLanguageOptions, ShellNode, CommentNode, ProgramNode } from "../types.js";
+export interface ShellSourceCodeOptions {
+    text: string;
+    ast: ProgramNode;
+}
+/**
+ * SourceCode implementation for shell scripts. Nodes carry `start`/`end`
+ * character offsets; `getLoc()` and `getRange()` derive positions from
+ * those offsets, so nodes have no `loc` or `range` properties.
+ */
+export declare class ShellSourceCode extends TextSourceCodeBase<{
+    LangOptions: ShellLanguageOptions;
+    RootNode: ProgramNode;
+    SyntaxElementWithLoc: ShellNode;
+    ConfigNode: CommentNode;
+}> {
+    #private;
+    /** All comments found in the file, in source order. */
+    comments: CommentNode[];
+    constructor({ text, ast }: ShellSourceCodeOptions);
+    getLoc(node: ShellNode): SourceLocation;
+    getRange(node: ShellNode): SourceRange;
+    getParent(node: ShellNode): ShellNode | undefined;
+    traverse(): Iterable<TraversalStep>;
+    /**
+     * Returns all comments that look like inline ESLint configuration.
+     */
+    getInlineConfigNodes(): CommentNode[];
+    /**
+     * Returns directives for disabling/enabling rules found in comments,
+     * such as `# eslint-disable-next-line shell/no-backticks`.
+     */
+    getDisableDirectives(): {
+        directives: Directive[];
+        problems: FileProblem[];
+    };
+    /**
+     * Applies `# eslint rule: severity` configuration comments.
+     */
+    applyInlineConfig(): {
+        configs: {
+            config: {
+                rules: RulesConfig;
+            };
+            loc: SourceLocation;
+        }[];
+        problems: FileProblem[];
+    };
+}

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

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview The ShellSourceCode class, the SourceCode implementation that
+ * ESLint uses to interact with a parsed shell script.
+ */
+import { ConfigCommentParser, Directive, TextSourceCodeBase, VisitNodeStep, } from "@eslint/plugin-kit";
+import { visitorKeys } from "../visitor-keys.js";
+const commentParser = new ConfigCommentParser();
+const INLINE_CONFIG = /^\s*eslint(?:-enable|-disable(?:(?:-next)?-line)?)?(?:\s|$)/u;
+/**
+ * The directive labels ESLint understands, mapped to directive types.
+ */
+const DIRECTIVE_TYPES = new Map([
+    ["eslint-disable", "disable"],
+    ["eslint-enable", "enable"],
+    ["eslint-disable-line", "disable-line"],
+    ["eslint-disable-next-line", "disable-next-line"],
+]);
+/**
+ * SourceCode implementation for shell scripts. Nodes carry `start`/`end`
+ * character offsets; `getLoc()` and `getRange()` derive positions from
+ * those offsets, so nodes have no `loc` or `range` properties.
+ */
+export class ShellSourceCode extends TextSourceCodeBase {
+    /** All comments found in the file, in source order. */
+    comments;
+    #parents = new Map();
+    #steps = null;
+    #lineOffsets = null;
+    #inlineConfigComments = null;
+    constructor({ text, ast }) {
+        super({ text, ast });
+        this.comments = ast.comments;
+    }
+    /** Character offsets at which each line starts. */
+    get #lineStarts() {
+        if (!this.#lineOffsets) {
+            const offsets = [0];
+            for (let i = 0; i < this.text.length; i++) {
+                if (this.text[i] === "\n") {
+                    offsets.push(i + 1);
+                }
+            }
+            this.#lineOffsets = offsets;
+        }
+        return this.#lineOffsets;
+    }
+    /**
+     * Converts a character offset into a 1-based line/column pair.
+     */
+    #locFromIndex(index) {
+        const lineStarts = this.#lineStarts;
+        let low = 0;
+        let high = lineStarts.length - 1;
+        while (low < high) {
+            const mid = (low + high + 1) >> 1;
+            if (lineStarts[mid] <= index) {
+                low = mid;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        return {
+            line: low + 1,
+            column: index - lineStarts[low] + 1,
+        };
+    }
+    getLoc(node) {
+        return {
+            start: this.#locFromIndex(node.start),
+            end: this.#locFromIndex(node.end),
+        };
+    }
+    getRange(node) {
+        return [node.start, node.end];
+    }
+    getParent(node) {
+        this.#ensureTraversed();
+        return this.#parents.get(node);
+    }
+    #ensureTraversed() {
+        if (!this.#steps) {
+            void [...this.traverse()];
+        }
+    }
+    traverse() {
+        if (this.#steps) {
+            return this.#steps.values();
+        }
+        const steps = (this.#steps = []);
+        const visit = (node, parent) => {
+            if (parent) {
+                this.#parents.set(node, parent);
+            }
+            steps.push(new VisitNodeStep({
+                target: node,
+                phase: 1,
+                args: [node, parent],
+            }));
+            for (const key of visitorKeys[node.type] ?? []) {
+                const child = node[key];
+                if (Array.isArray(child)) {
+                    for (const element of child) {
+                        if (element) {
+                            visit(element, node);
+                        }
+                    }
+                }
+                else if (child) {
+                    visit(child, node);
+                }
+            }
+            steps.push(new VisitNodeStep({
+                target: node,
+                phase: 2,
+                args: [node, parent],
+            }));
+        };
+        visit(this.ast, undefined);
+        return steps.values();
+    }
+    /**
+     * Returns all comments that look like inline ESLint configuration.
+     */
+    getInlineConfigNodes() {
+        if (!this.#inlineConfigComments) {
+            this.#inlineConfigComments = this.comments.filter(comment => INLINE_CONFIG.test(comment.text));
+        }
+        return this.#inlineConfigComments;
+    }
+    /**
+     * Returns directives for disabling/enabling rules found in comments,
+     * such as `# eslint-disable-next-line shell/no-backticks`.
+     */
+    getDisableDirectives() {
+        const directives = [];
+        const problems = [];
+        for (const comment of this.getInlineConfigNodes()) {
+            const parsed = commentParser.parseDirective(comment.text.trim());
+            if (!parsed) {
+                continue;
+            }
+            const directiveType = DIRECTIVE_TYPES.get(parsed.label);
+            if (!directiveType) {
+                continue;
+            }
+            directives.push(new Directive({
+                type: directiveType,
+                node: comment,
+                value: parsed.value,
+                justification: parsed.justification,
+            }));
+        }
+        return { directives, problems };
+    }
+    /**
+     * Applies `# eslint rule: severity` configuration comments.
+     */
+    applyInlineConfig() {
+        const configs = [];
+        const problems = [];
+        for (const comment of this.getInlineConfigNodes()) {
+            const parsed = commentParser.parseDirective(comment.text.trim());
+            if (!parsed || parsed.label !== "eslint") {
+                continue;
+            }
+            const parseResult = commentParser.parseJSONLikeConfig(parsed.value);
+            if (parseResult.ok) {
+                configs.push({
+                    config: { rules: parseResult.config },
+                    loc: this.getLoc(comment),
+                });
+            }
+            else {
+                problems.push({
+                    ruleId: null,
+                    message: parseResult.error.message,
+                    loc: this.getLoc(comment),
+                });
+            }
+        }
+        return { configs, problems };
+    }
+}

package/dist/parser/parse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Parses shell source code into an ESTree-style syntax tree by
+ * wrapping the mvdan-sh parser (a GopherJS build of mvdan.cc/sh) and
+ * translating its tree. See docs/syntax-tree.md for the tree format.
+ * @author Claude Opus 5.5
+ */
+import type { ShellVariant, CommentNode, ProgramNode } from "../types.js";
+/**
+ * The error thrown when shell source code cannot be parsed.
+ */
+export declare class ShellSyntaxError extends SyntaxError {
+    line: number;
+    column: number;
+    /** The file path passed to the parser, when there was one. */
+    path: string | undefined;
+    constructor(message: string, line: number, column: number, path?: string);
+}
+export interface ShellParseOptions {
+    /** The shell dialect to parse. Defaults to `"bash"`. */
+    variant?: ShellVariant;
+    /** The file path reported as `ShellSyntaxError#path` on syntax errors. */
+    path?: string;
+}
+export interface ShellParseResult {
+    ast: ProgramNode;
+    comments: CommentNode[];
+}
+/**
+ * Parses shell source code into an ESTree-style syntax tree.
+ * @throws {ShellSyntaxError} When the source code contains a syntax error.
+ */
+export declare function parseShell(text: string, options?: ShellParseOptions): ShellParseResult;