@eslint-sh/eslint-plugin 0.5.0 → 0.6.0

package/dist/declaration-conventions/comment-pragma.d.ts

@@ -0,0 +1,33 @@
+import type { DeclarationConvention } from './declaration-convention.js';
+/**
+ * The reference {@link DeclarationConvention}: a script declares the external
+ * commands it uses in `# uses:` comments in its header.
+ *
+ * ```sh
+ * #!/usr/bin/env bash
+ * # uses: jq curl
+ * # uses: git
+ * set -euo pipefail
+ * ```
+ *
+ * declares `jq`, `curl`, and `git`. The header is the run of blank and
+ * comment-only lines at the top of the file; a `# uses:` comment after the
+ * first command is not a declaration. Several pragma lines accumulate, names
+ * are whitespace-separated, and each declaration is `kind: 'script'` with a
+ * `range` that covers exactly that name. A word starting with `#` ends the list and begins a trailing
+ * remark: `# uses: jq # for json` declares only `jq`.
+ *
+ * Its `removeDeclaration` hook deletes one name and the whitespace that
+ * separated it, or the whole pragma line (with its `\n` or `\r\n`) when that
+ * name was the line's last.
+ *
+ * Its `declarationHint` hook tells a person exactly what to add: the line
+ * `# uses: curl`, on a line below the shebang, or as the first line of the
+ * file when there is no shebang. A name a pragma cannot express (one with
+ * whitespace, or starting with `#`) gets no hint.
+ *
+ * Bind it with `settings: { sh: { declarationConvention: commentPragma } }`.
+ *
+ * @public
+ */
+export declare const commentPragma: Readonly<Required<DeclarationConvention>>;

package/dist/declaration-conventions/comment-pragma.js

@@ -0,0 +1,153 @@
+/**
+ * A header line (terminator excluded) that is blank or holds only a `#`
+ * comment. `[\s\S]` rather than `.`, so a stray `\r` or U+2028 inside a comment
+ * does not end the header early.
+ */
+const HEADER_LINE = /^[ \t]*(?:#[\s\S]*)?$/u;
+/**
+ * A pragma line; group 1 is everything after `uses:`: the whitespace-separated
+ * name list, then optionally a `#`-word and a trailing remark.
+ */
+const PRAGMA_LINE = /^[ \t]*#[ \t]*uses:([\s\S]*)$/u;
+/** One name in a pragma's name list. */
+const PRAGMA_NAME = /\S+/gu;
+/**
+ * Scans the header of `text` and returns its pragma lines in source order.
+ * Lines end at `\n`; a `\r` immediately before it belongs to the terminator
+ * (so CRLF files declare `jq`, never `jq\r`).
+ */
+function readPragmaLines(text) {
+    const pragmas = [];
+    let lineStart = 0;
+    while (lineStart < text.length) {
+        const newline = text.indexOf('\n', lineStart);
+        const lineEnd = newline === -1 ? text.length : newline + 1;
+        const contentEnd = newline === -1
+            ? text.length
+            : newline > lineStart && text[newline - 1] === '\r'
+                ? newline - 1
+                : newline;
+        const content = text.slice(lineStart, contentEnd);
+        if (!HEADER_LINE.test(content)) {
+            break;
+        }
+        const pragma = PRAGMA_LINE.exec(content);
+        if (pragma) {
+            const list = pragma[1];
+            const listStart = lineStart + content.length - list.length;
+            const names = [];
+            for (const match of list.matchAll(PRAGMA_NAME)) {
+                // A `#`-word starts a trailing remark (`# uses: jq # for json`), not a name.
+                if (match[0].startsWith('#'))
+                    break;
+                names.push({
+                    kind: 'script',
+                    name: match[0],
+                    range: [listStart + match.index, listStart + match.index + match[0].length],
+                });
+            }
+            pragmas.push({ lineStart, contentEnd, lineEnd, names });
+        }
+        lineStart = lineEnd;
+    }
+    return pragmas;
+}
+/**
+ * The `[start, end)` range that removes `names[index]` from its pragma line
+ * while the line keeps other names: the name plus the whitespace separating it
+ * from its successor, or, for the last name, from its predecessor. Either way
+ * the remaining names keep single, original separators. Only called with
+ * `names.length > 1`; a line's only name is removed with its whole line.
+ */
+function nameRemovalRange(names, index) {
+    const target = names[index];
+    return index < names.length - 1
+        ? [target.range[0], names[index + 1].range[0]]
+        : [names[index - 1].range[1], target.range[1]];
+}
+/**
+ * The `[start, end)` range that deletes `line` entirely, terminator included.
+ * The header's last line can lack a terminator (a file that is nothing but
+ * header); there the newline *before* the line goes instead, so the file does
+ * not end in a newly empty line.
+ */
+function lineRemovalRange(text, line) {
+    if (line.lineEnd > line.contentEnd || line.lineStart === 0) {
+        return [line.lineStart, line.lineEnd];
+    }
+    const precedingTerminatorLength = text[line.lineStart - 2] === '\r' ? 2 : 1;
+    return [line.lineStart - precedingTerminatorLength, line.lineEnd];
+}
+function declaredCommands(sourceCode) {
+    return readPragmaLines(sourceCode.text).flatMap((line) => line.names);
+}
+function removeDeclaration(sourceCode, declared, fixer) {
+    const text = sourceCode.text;
+    for (const line of readPragmaLines(text)) {
+        const index = line.names.findIndex((candidate) => candidate.name === declared.name &&
+            candidate.range[0] === declared.range[0] &&
+            candidate.range[1] === declared.range[1]);
+        if (index === -1) {
+            continue;
+        }
+        return fixer.removeRange(line.names.length === 1 ? lineRemovalRange(text, line) : nameRemovalRange(line.names, index));
+    }
+    // Not one of this file's pragma declarations (for example, produced by a
+    // different convention): there is nothing this convention can safely edit.
+    return null;
+}
+/**
+ * A name a pragma line can declare: one whitespace-free word that does not
+ * start a trailing remark (`#`).
+ */
+const DECLARABLE_NAME = /^[^\s#]\S*$/u;
+/**
+ * Where to write a new pragma line so that it is in the header: directly
+ * below the shebang when the file has one (above it, the shebang would stop
+ * being line 1), otherwise as the first line. Either place is always a header
+ * line, whatever the rest of the header holds.
+ */
+function declarationHint(command, sourceCode) {
+    if (!DECLARABLE_NAME.test(command))
+        return null;
+    const where = sourceCode.text.startsWith('#!')
+        ? 'on a line below the shebang'
+        : 'as the first line of the file';
+    return `Add \`# uses: ${command}\` ${where}.`;
+}
+/**
+ * The reference {@link DeclarationConvention}: a script declares the external
+ * commands it uses in `# uses:` comments in its header.
+ *
+ * ```sh
+ * #!/usr/bin/env bash
+ * # uses: jq curl
+ * # uses: git
+ * set -euo pipefail
+ * ```
+ *
+ * declares `jq`, `curl`, and `git`. The header is the run of blank and
+ * comment-only lines at the top of the file; a `# uses:` comment after the
+ * first command is not a declaration. Several pragma lines accumulate, names
+ * are whitespace-separated, and each declaration is `kind: 'script'` with a
+ * `range` that covers exactly that name. A word starting with `#` ends the list and begins a trailing
+ * remark: `# uses: jq # for json` declares only `jq`.
+ *
+ * Its `removeDeclaration` hook deletes one name and the whitespace that
+ * separated it, or the whole pragma line (with its `\n` or `\r\n`) when that
+ * name was the line's last.
+ *
+ * Its `declarationHint` hook tells a person exactly what to add: the line
+ * `# uses: curl`, on a line below the shebang, or as the first line of the
+ * file when there is no shebang. A name a pragma cannot express (one with
+ * whitespace, or starting with `#`) gets no hint.
+ *
+ * Bind it with `settings: { sh: { declarationConvention: commentPragma } }`.
+ *
+ * @public
+ */
+export const commentPragma = Object.freeze({
+    declaredCommands,
+    removeDeclaration,
+    declarationHint,
+});

package/dist/declaration-conventions/declaration-convention.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The declaration-convention extension point: how a project states which
+ * external commands a script depends on.
+ *
+ * Which commands a script *uses* is a fact this plugin can derive from the
+ * syntax tree. How a script *declares* the commands it intends to use is
+ * project policy — a header comment, a manifest variable, a sourced
+ * dependency file — and differs between consumers. This plugin therefore
+ * never hardcodes a declaration syntax. Rules that compare usage against
+ * declarations ask a {@link DeclarationConvention} for the declarations and,
+ * when they offer an autofix, ask the same convention to produce the edit,
+ * because only the convention knows its own syntax.
+ *
+ * A convention is bound by the consumer, through the shared
+ * `settings.sh.declarationConvention` setting (see
+ * `../rules/resolve-declaration-convention.ts`). This package ships exactly one
+ * reference implementation, `commentPragma` (`./comment-pragma.ts`).
+ */
+import type { RuleTextEdit, RuleTextEditor } from '@eslint/core';
+import type { ShellSourceCode } from '../language/shell-source-code.js';
+/**
+ * The file ESLint is linting, as its rule context names it. A
+ * {@link DeclarationConvention} receives it so it can find declarations kept
+ * outside the script, such as a per-script sidecar file next to it.
+ *
+ * A rule's own `context` is a `LintedFile`, so a rule that calls
+ * `declaredCommands` passes `context`.
+ *
+ * @public
+ */
+export interface LintedFile {
+    /**
+     * The name ESLint lints the code under (`context.filename`). For a code
+     * block a processor extracts from another file it is virtual
+     * (`README.md/0_0.sh`).
+     */
+    readonly filename: string;
+    /**
+     * The path on disk ESLint associates with the code
+     * (`context.physicalFilename`): the file it read, or the file a
+     * processor's code block came from. With `--stdin --stdin-filename`, it is
+     * the name given on the command line; the code came from standard input,
+     * and that file may not exist. Resolve sidecar paths from this one, and
+     * treat a missing sidecar as a normal case.
+     */
+    readonly physicalFilename: string;
+    /**
+     * ESLint's working directory (`context.cwd`). A relative
+     * {@link FileDeclaredCommand.path} is relative to it.
+     */
+    readonly cwd: string;
+}
+/**
+ * A declaration written in the linted script's own text: the only kind an
+ * ESLint fix can edit, because a fix edits only the file being linted.
+ *
+ * @public
+ */
+export interface ScriptDeclaredCommand {
+    /** Says the declaration is in the script. */
+    readonly kind: 'script';
+    /** The declared command name, exactly as it would be invoked (`jq`, `docker-compose`). */
+    readonly name: string;
+    /**
+     * The `[start, end)` source range of this declaration, as UTF-16 offsets
+     * into `sourceCode.text` (the same coordinates as every node's `range`),
+     * with `0 <= start <= end <= sourceCode.text.length`. Rules report a
+     * declaration at this range, so it should cover the text that declares
+     * this one name and nothing else.
+     */
+    readonly range: readonly [number, number];
+}
+/**
+ * A declaration written in a file other than the linted script: a per-script
+ * sidecar, or a manifest several scripts share. A report about it names the
+ * file, and carries no fix, since a fix can only edit the linted script.
+ *
+ * @public
+ */
+export interface FileDeclaredCommand {
+    /** Says the declaration is in another file. */
+    readonly kind: 'file';
+    /** The declared command name, exactly as it would be invoked. */
+    readonly name: string;
+    /**
+     * Where a person or a tool should look for the declaration: a path
+     * relative to {@link LintedFile.cwd}, or an absolute path. It must be a
+     * non-empty single line. Rules name it in their reports as given; they never
+     * read it.
+     */
+    readonly path: string;
+    /** The 1-based line of `path` that declares the command, when the convention knows it. */
+    readonly line?: number;
+}
+/**
+ * A declaration whose source can only be described in words: there is no
+ * range in the script and no path to point at, only a phrase that tells a
+ * person where it comes from, such as a list written in the ESLint config, a
+ * convention's own constant, or a snapshot of a tool registry. A report about
+ * it names the source by `description` and carries no fix.
+ *
+ * @public
+ */
+export interface DescribedDeclaredCommand {
+    /** Says the declaration's source is described in words, by `description`. */
+    readonly kind: 'described';
+    /** The declared command name, exactly as it would be invoked. */
+    readonly name: string;
+    /**
+     * Names the source for a person who wants to change the declaration, as a
+     * phrase that reads after "declared in": "the web image list in
+     * eslint.config.js", "the tool registry snapshot of 2026-11-01". It must be a
+     * non-empty single line.
+     */
+    readonly description: string;
+}
+/**
+ * One command a script declares it depends on, as reported by a
+ * {@link DeclarationConvention}. Where the declaration lives is part of what
+ * it is, so it is one of three kinds, told apart by the required `kind`:
+ * written in the script ({@link ScriptDeclaredCommand}), in another file
+ * ({@link FileDeclaredCommand}), or in a source that can only be described in
+ * words ({@link DescribedDeclaredCommand}). Only the script kind has a `range`, so
+ * narrow on `kind` before reading it.
+ *
+ * @public
+ */
+export type DeclaredCommand = ScriptDeclaredCommand | FileDeclaredCommand | DescribedDeclaredCommand;
+/**
+ * How a project declares the external commands its shell scripts depend on.
+ *
+ * Implement this to teach the plugin a project's own declaration syntax, then
+ * bind it with `settings: { sh: { declarationConvention: myConvention } }`.
+ * Until a convention is bound, rules that consume one report nothing.
+ *
+ * Bind it through `settings`, not through a rule's options: ESLint copies
+ * rule options with `structuredClone`, which cannot copy functions. Define it
+ * as a plain object whose methods are its own properties, and bind it in one
+ * config entry: when two matching config entries both set it, ESLint merges
+ * the two objects property by property, which drops methods inherited from a
+ * class prototype and can mix methods from two different conventions.
+ *
+ * One convention object serves every file its config entry matches, so its
+ * answer must depend only on its arguments and on data it holds, never on
+ * which file it saw before. ESLint's `--cache` sees a convention's own
+ * enumerable data properties (they are part of the config it hashes) but not
+ * files the convention reads while linting.
+ *
+ * {@link commentPragma} is the reference implementation.
+ *
+ * @public
+ */
+export interface DeclarationConvention {
+    /**
+     * Returns every command the linted file declares, in source order. A name
+     * declared twice appears twice, each with its own source. `file` names the
+     * file being linted, for a convention whose declarations live beside it;
+     * a convention that reads only `sourceCode` can leave it out.
+     */
+    declaredCommands(sourceCode: ShellSourceCode, file: LintedFile): DeclaredCommand[];
+    /**
+     * Optional edit hook: returns the fix that deletes the single stale
+     * declaration `declared` (an in-script entry previously returned by
+     * {@link DeclarationConvention.declaredCommands} for the same
+     * `sourceCode`), built with the rule's `fixer`. Returns `null` when that
+     * declaration cannot be removed safely.
+     *
+     * It is only ever called with a {@link ScriptDeclaredCommand}: a fix edits
+     * only the linted script, and no edit to the script removes a declaration
+     * kept anywhere else.
+     *
+     * A convention without this hook still reports stale declarations; those
+     * reports simply carry no autofix.
+     */
+    removeDeclaration?(sourceCode: ShellSourceCode, declared: ScriptDeclaredCommand, fixer: RuleTextEditor): RuleTextEdit | RuleTextEdit[] | null;
+    /**
+     * Optional hint hook: returns one short sentence that tells a person how to
+     * declare `command`, with text they can copy. {@link commentPragma}'s hint says to
+     * add `# uses: curl` on a line below the shebang.
+     * `sh/no-undeclared-commands` appends it to its report. Following the
+     * sentence literally must make that report go away.
+     *
+     * Return `null` when this convention cannot declare `command` as written
+     * (for example, a name its syntax cannot express). The report then falls
+     * back to a generic sentence, as it does for a convention without this
+     * hook. Anything other than `null` must be a non-empty single-line string.
+     */
+    declarationHint?(command: string, sourceCode: ShellSourceCode, file: LintedFile): string | null;
+}

package/dist/declaration-conventions/declaration-convention.js

@@ -0,0 +1 @@
+export {};

package/dist/declaration-conventions/read-declared-commands.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The one path by which a rule reads a bound convention's declarations for
+ * the file it is linting. The built-in consumers (`sh/no-undeclared-commands`,
+ * `sh/no-unused-declarations`) and a pack's own rules all call
+ * {@link readDeclaredCommands}, so they hand the convention the same
+ * {@link LintedFile} and trust only declarations that passed the same checks.
+ *
+ * The checks exist because a declaration's kind decides where a report goes
+ * and whether a fix is offered. A declaration of an unknown kind, one missing
+ * its kind's fields, or a script range outside the text would otherwise be
+ * reported at a made-up location, crash deep inside a rule, or be silently
+ * accepted by a rule that only reads names. Failing with the declaration and
+ * the setting in the message makes the convention's bug the thing the user
+ * sees.
+ */
+import type { ShellSourceCode } from '../language/shell-source-code.js';
+import type { DeclarationConvention, DeclaredCommand, LintedFile } from './declaration-convention.js';
+/**
+ * What {@link readDeclaredCommands} reads from a rule's context: the linted
+ * file and its source code. Any shell rule's `context` satisfies it.
+ *
+ * @public
+ */
+export interface DeclarationReadContext extends LintedFile {
+    /** The source code of the file being linted. */
+    readonly sourceCode: ShellSourceCode;
+}
+/**
+ * The only view of the linted file a convention's hooks receive: `filename`,
+ * `physicalFilename` and `cwd`, frozen. A rule's `context` must never reach a
+ * hook, because it would let a convention report, read options or reach other
+ * rule state.
+ *
+ * @internal
+ */
+export declare function toLintedFile(context: LintedFile): LintedFile;
+/**
+ * Returns the declarations `convention` makes for the file `context` is
+ * linting, after checking each one against its kind. Call it from a rule's
+ * listener with the convention `resolveDeclarationConvention` returned and
+ * the rule's own `context`.
+ *
+ * The convention receives a frozen {@link LintedFile} holding only
+ * `filename`, `physicalFilename` and `cwd`, never the whole context, so it
+ * sees which file it is reading and nothing it could report through.
+ *
+ * Throws an `Error` that names the setting, starting
+ * `Invalid settings.sh.declarationConvention:`, and shows the offending value when
+ * `declaredCommands` does not return an array, or returns a declaration with
+ * a missing or unknown `kind`, without its kind's fields, or with a `range`
+ * outside the linted text.
+ *
+ * @example
+ * ```ts
+ * const convention = resolveDeclarationConvention(context);
+ * if (convention === null) return {};
+ * return {
+ *   File() {
+ *     for (const declared of readDeclaredCommands(convention, context)) {
+ *       if (declared.kind === 'script') {
+ *         // declared.range is an offset pair into context.sourceCode.text
+ *       }
+ *     }
+ *   },
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare function readDeclaredCommands(convention: DeclarationConvention, context: DeclarationReadContext): DeclaredCommand[];

package/dist/declaration-conventions/read-declared-commands.js

@@ -0,0 +1,128 @@
+/**
+ * The binding a validation error names. A convention can only be bound in
+ * settings in practice: ESLint copies rule options with `structuredClone`,
+ * which rejects an object with methods.
+ */
+const BINDING = 'settings.sh.declarationConvention';
+/**
+ * The only view of the linted file a convention's hooks receive: `filename`,
+ * `physicalFilename` and `cwd`, frozen. A rule's `context` must never reach a
+ * hook, because it would let a convention report, read options or reach other
+ * rule state.
+ *
+ * @internal
+ */
+export function toLintedFile(context) {
+    return Object.freeze({
+        filename: context.filename,
+        physicalFilename: context.physicalFilename,
+        cwd: context.cwd,
+    });
+}
+/** `value` is a non-empty string with no line break or NUL, fit to name a source in one message line. */
+function isSingleLine(value) {
+    return typeof value === 'string' && value !== '' && !/[\r\n\0]/u.test(value);
+}
+/**
+ * Why `value` is not a valid {@link DeclaredCommand} for a file whose text is
+ * `textLength` UTF-16 units long, or `null` when it is. Each kind is held to
+ * exactly the fields its reports need.
+ */
+function invalidReason(value, textLength) {
+    if (typeof value !== 'object' || value === null)
+        return 'it is not an object';
+    const declared = value;
+    if (typeof declared.name !== 'string' || declared.name === '') {
+        return '`name` must be a non-empty string';
+    }
+    switch (declared.kind) {
+        case 'script': {
+            const { range } = declared;
+            const valid = Array.isArray(range) &&
+                range.length === 2 &&
+                Number.isInteger(range[0]) &&
+                Number.isInteger(range[1]) &&
+                0 <= range[0] &&
+                range[0] <= range[1] &&
+                range[1] <= textLength;
+            return valid
+                ? null
+                : `a script declaration needs \`range\`: two offsets [start, end) with 0 <= start <= end <= ${String(textLength)}, the length of the linted text`;
+        }
+        case 'file':
+            if (!isSingleLine(declared.path)) {
+                return 'a file declaration needs `path`: a non-empty single-line path, relative to `cwd` or absolute';
+            }
+            return declared.line === undefined ||
+                (Number.isInteger(declared.line) && declared.line >= 1)
+                ? null
+                : 'the optional `line` of a file declaration must be a positive integer';
+        case 'described':
+            return isSingleLine(declared.description)
+                ? null
+                : 'a described declaration needs `description`: a non-empty single line';
+        case undefined:
+            return "`kind` is missing: it must be 'script', 'file' or 'described'";
+        default:
+            return `\`kind\` must be 'script', 'file' or 'described', not ${describe(declared.kind)}`;
+    }
+}
+/** A short rendering of a value for an error message. */
+function describe(value) {
+    try {
+        // `JSON.stringify` returns `undefined` for a function or `undefined`.
+        const text = JSON.stringify(value);
+        return text ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Returns the declarations `convention` makes for the file `context` is
+ * linting, after checking each one against its kind. Call it from a rule's
+ * listener with the convention `resolveDeclarationConvention` returned and
+ * the rule's own `context`.
+ *
+ * The convention receives a frozen {@link LintedFile} holding only
+ * `filename`, `physicalFilename` and `cwd`, never the whole context, so it
+ * sees which file it is reading and nothing it could report through.
+ *
+ * Throws an `Error` that names the setting, starting
+ * `Invalid settings.sh.declarationConvention:`, and shows the offending value when
+ * `declaredCommands` does not return an array, or returns a declaration with
+ * a missing or unknown `kind`, without its kind's fields, or with a `range`
+ * outside the linted text.
+ *
+ * @example
+ * ```ts
+ * const convention = resolveDeclarationConvention(context);
+ * if (convention === null) return {};
+ * return {
+ *   File() {
+ *     for (const declared of readDeclaredCommands(convention, context)) {
+ *       if (declared.kind === 'script') {
+ *         // declared.range is an offset pair into context.sourceCode.text
+ *       }
+ *     }
+ *   },
+ * };
+ * ```
+ *
+ * @public
+ */
+export function readDeclaredCommands(convention, context) {
+    const { sourceCode } = context;
+    const file = toLintedFile(context);
+    const declarations = convention.declaredCommands(sourceCode, file);
+    if (!Array.isArray(declarations)) {
+        throw new Error(`Invalid ${BINDING}: \`declaredCommands\` must return an array, but returned ${describe(declarations)}.`);
+    }
+    for (const declared of declarations) {
+        const reason = invalidReason(declared, sourceCode.text.length);
+        if (reason !== null) {
+            throw new Error(`Invalid ${BINDING}: \`declaredCommands\` returned the declaration ${describe(declared)}, but ${reason}.`);
+        }
+    }
+    return declarations;
+}

package/dist/eslint-plugin-syntax-analyze.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The faithful shell analysis surface (`@eslint-sh/eslint-plugin/syntax/analyze`): the complete
+ * public surface of `sh-ast/analyze`, re-exported unchanged from the very `sh-ast` instance this
+ * plugin's language parses with.
+ *
+ * It provides `enumerateCommands`, `resolveArgv0` (whose `chainIndices` locate a resolved command's
+ * arguments in its site's `argv`), `DEFAULT_TRANSPARENT_WRAPPERS`, `WrapperSpec`, the raw
+ * `resolveWord(Node)`, and the named operator constants with `rawOperator` for comparing and
+ * constructing the operator values those records carry. All of it works on the faithful records
+ * from `@eslint-sh/eslint-plugin/syntax`. The plugin root's `resolveWord` takes a lint-view
+ * `ShellNode` instead; the two share a name but not an input contract, so this subpath is kept
+ * separate from the root.
+ *
+ * Like `@eslint-sh/eslint-plugin/syntax`, it tracks the plugin's pinned `sh-ast` minor and never
+ * wraps or renames anything.
+ *
+ * @packageDocumentation
+ */
+
+
+export * from "sh-ast/analyze";
+
+export { }

package/dist/eslint-plugin-syntax.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The faithful shell syntax surface (`@eslint-sh/eslint-plugin/syntax`): the complete public
+ * surface of `sh-ast`'s root entry point, re-exported unchanged from the very `sh-ast` instance
+ * this plugin's language parses with.
+ *
+ * Use it when a custom rule edits or analyzes the parser's own records rather than the plugin's
+ * lint view: `walk`, `parseSync`, `printSync` and `PrintOptions`, the record types (`Node`,
+ * `Word`, `CallExpr`, `SyntaxPos`, `GoString`, …), and the operator and language constants.
+ * Importing them from here, instead of installing `sh-ast` separately, means a rule always gets
+ * the same `sh-ast` version and module instance as the language that produced its syntax. Under
+ * 0.x a different `sh-ast` minor is a breaking change, and records from one copy are not
+ * guaranteed to be accepted by another.
+ *
+ * This entry point tracks the plugin's pinned `sh-ast` minor, so an `sh-ast` 0.x minor bump is a
+ * minor release of this plugin. It never wraps or renames anything: every name has `sh-ast`'s
+ * own contract. The plugin root (`@eslint-sh/eslint-plugin`) keeps the view-aware helpers such
+ * as `resolveWord(ShellNode)`, which differ from the raw helpers of the same name in
+ * `@eslint-sh/eslint-plugin/syntax/analyze`. That is why these names live on their own subpath
+ * and are not merged into the root.
+ *
+ * @packageDocumentation
+ */
+
+
+export * from "sh-ast";
+
+export { }