@eslint-sh/eslint-plugin 0.5.0 → 0.6.0

package/dist/language/lint-view-types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The static types of the lint view's nodes, derived from the faithful syntax
+ * interfaces `sh-ast` generates from mvdan/sh.
+ *
+ * Nothing here restates a field list. Each lint-view node type is computed from
+ * the matching `sh-ast` interface by the same rules the runtime projection in
+ * `syntax-view.ts` applies to `SYNTAX_SCHEMA`, so an mvdan/sh upgrade that
+ * adds, removes, renames or retypes a field changes these types in the same
+ * `pnpm install`, and any rule (built-in or third-party) that reads a field
+ * that no longer exists stops compiling. The remaining way for types and
+ * runtime to part is a change to the rules themselves; `test/lint-view-types-drift.test.ts`
+ * compares both against the runtime schema to catch that.
+ *
+ * The projection rules mirrored here:
+ * - `Type` becomes the discriminator `type`; every other field is renamed to
+ *   its lowercase spelling (`Cmd` → `cmd`, `RsrvWord` → `rsrvword`).
+ * - Position fields (`SyntaxPos`) have no counterpart: the view carries
+ *   `range` and `loc` instead.
+ * - A nil child is an absent key (an optional property); a nil slice is an
+ *   empty array and nil slice elements are dropped.
+ * - Go strings are decoded to JavaScript strings; booleans and operator
+ *   values are copied unchanged.
+ */
+import type { Expansion, Node, Replace, Slice, SyntaxPos } 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;
+}
+/**
+ * The lint-view type of one upstream field value `Value`: a record becomes the
+ * node type of that record (a union of records, a union of node types), a slice
+ * becomes a read-only array of such nodes with its nil elements removed, a Go
+ * string becomes a JavaScript `string`, and booleans and operator values stay
+ * as they are. Upstream nil (`null`) and typed nils never reach a view, so
+ * neither appears in the result.
+ *
+ * It is the type of every field of every {@link ShellNodeMap} entry, exported
+ * so a helper that takes or returns a node's field value can name it.
+ *
+ * @public
+ */
+export type ShellNodeField<Value> = Exclude<Value, null | {
+    readonly Type: 'TypedNil';
+}> extends infer Present ? Present extends readonly (infer Element)[] ? readonly ShellNodeField<Element>[] : Present extends {
+    readonly Type: infer Type extends ShellNodeType;
+} ? ShellNodeMap[Type] : Present extends string | Uint8Array ? string : Present : never;
+/**
+ * Lint-view node types by their `type` discriminator, one entry per upstream
+ * syntax record. It is computed from `sh-ast`'s generated interfaces, so it
+ * follows the pinned mvdan/sh version.
+ *
+ * A node has `type`, `range` and `loc`, plus a lowercase field for each
+ * non-position upstream field. A field that is a single child that may be nil
+ * upstream is optional, because the view omits the key when the child is
+ * absent; a slice is always present.
+ *
+ * `range` is a half-open UTF-16 span of the source text and `loc` its ESLint
+ * line/column form; both describe the view, not the upstream byte positions. A
+ * node whose line ends in CRLF ends before the `\r` (and a text field such as
+ * `value` loses that one trailing `\r`), so a CRLF file reads like its LF
+ * twin. Auxiliary records (`Expansion`, `Replace`, `Slice`) take their span
+ * from their children.
+ *
+ * @public
+ */
+export type ShellNodeMap = {
+    [Record in Exclude<Node, {
+        readonly Type: 'TypedNil';
+    }> | Expansion | Replace | Slice as Record['Type']]: {
+        /** Syntax kind of this node; the discriminator to narrow a ShellNode by. */
+        readonly type: Record['Type'];
+        /**
+         * Half-open UTF-16 span of the node in the source text. Its type is the
+         * mutable tuple ESLint's `fixer` methods take, so `node.range` can be passed
+         * to `fixer.insertTextBeforeRange` and the others without a cast; treat it
+         * as read-only.
+         */
+        range: [number, number];
+        /** ESLint line and column of the span's two ends. */
+        readonly loc: {
+            readonly start: ShellPosition;
+            readonly end: ShellPosition;
+        };
+    } & {
+        readonly [Name in keyof Record & string as Name extends 'Type' ? never : [Record[Name]] extends [SyntaxPos] ? never : null extends Record[Name] ? Exclude<Record[Name], null | {
+            readonly Type: 'TypedNil';
+        }> extends {
+            readonly Type: string;
+        } ? never : Lowercase<Name> : Lowercase<Name>]: ShellNodeField<Record[Name]>;
+    } & {
+        readonly [Name in keyof Record & string as null extends Record[Name] ? Exclude<Record[Name], null | {
+            readonly Type: 'TypedNil';
+        }> extends {
+            readonly Type: string;
+        } ? Lowercase<Name> : never : never]?: ShellNodeField<Record[Name]>;
+    };
+};
+/** Every value a lint-view node's `type` can hold. @public */
+export type ShellNodeType = keyof ShellNodeMap;
+/** The lint-view node whose `type` is `Type`, for example `ShellNodeOf<'Stmt'>`. @public */
+export type ShellNodeOf<Type extends ShellNodeType> = ShellNodeMap[Type];

package/dist/language/lint-view-types.js

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

package/dist/language/non-shell-file-guard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Recognizes files that are certainly not shell scripts but reached
+ * `ShellLanguage.parse` anyway, and explains why.
+ *
+ * `sh.configs.recommended` deliberately carries no `files` key: the user's own
+ * globs decide which paths are shell. A config entry that selects
+ * `language: 'sh/sh'` without `files` (most often the preset dropped bare into
+ * the config array) applies to every file some other entry matches,
+ * including ESLint's default JavaScript globs. Without this guard each such
+ * file gets an upstream shell syntax error that says nothing about the
+ * misconfiguration. Here this plugin's own code is running, so it can name
+ * the real cause instead.
+ *
+ * Scope boundaries:
+ *
+ * - Detection is by file extension only, against a fixed list of common
+ *   non-shell source types. Content is never sniffed: an extensionless file,
+ *   a shell extension, or any extension not on the list goes through the
+ *   normal shell parse.
+ * - Matching is exact and case-sensitive, the same way ESLint's own `files`
+ *   globs match extensions.
+ * - The guard is not configurable.
+ */
+import type { FileError } from '@eslint/core';
+/**
+ * Returns the diagnostic for a file whose extension marks it as a known
+ * non-shell source type, or `undefined` when the file should be parsed as
+ * shell. The diagnostic names the file type, says the file is being linted
+ * as shell, and shows the fix as a one-line config entry. It sits at line 1,
+ * column 1, since it describes the whole file rather than any position in
+ * it.
+ *
+ * @internal
+ */
+export declare function nonShellFileError(filePath: string): FileError | undefined;

package/dist/language/non-shell-file-guard.js

@@ -0,0 +1,59 @@
+/**
+ * Known non-shell source extensions, each mapped to the human name used in
+ * the diagnostic. Lookup is by the exact extension, leading dot included.
+ */
+const NON_SHELL_FILE_TYPES = new Map([
+    ['.js', 'JavaScript'],
+    ['.mjs', 'JavaScript'],
+    ['.cjs', 'JavaScript'],
+    ['.jsx', 'JavaScript (JSX)'],
+    ['.ts', 'TypeScript'],
+    ['.mts', 'TypeScript'],
+    ['.cts', 'TypeScript'],
+    ['.tsx', 'TypeScript (TSX)'],
+    ['.json', 'JSON'],
+    ['.jsonc', 'JSONC'],
+    ['.json5', 'JSON5'],
+    ['.md', 'Markdown'],
+    ['.css', 'CSS'],
+    ['.html', 'HTML'],
+    ['.vue', 'Vue'],
+    ['.svelte', 'Svelte'],
+    ['.yml', 'YAML'],
+    ['.yaml', 'YAML'],
+]);
+/**
+ * The extension of the last path segment, leading dot included, or `''`
+ * when there is none. A leading dot alone (a dotfile such as `.bashrc`) is
+ * not an extension. Both `/` and `\` separate segments so Windows paths
+ * resolve the same way.
+ */
+function extensionOf(filePath) {
+    const baseName = filePath.slice(Math.max(filePath.lastIndexOf('/'), filePath.lastIndexOf('\\')) + 1);
+    const dot = baseName.lastIndexOf('.');
+    return dot > 0 ? baseName.slice(dot) : '';
+}
+/**
+ * Returns the diagnostic for a file whose extension marks it as a known
+ * non-shell source type, or `undefined` when the file should be parsed as
+ * shell. The diagnostic names the file type, says the file is being linted
+ * as shell, and shows the fix as a one-line config entry. It sits at line 1,
+ * column 1, since it describes the whole file rather than any position in
+ * it.
+ *
+ * @internal
+ */
+export function nonShellFileError(filePath) {
+    const extension = extensionOf(filePath);
+    const fileType = NON_SHELL_FILE_TYPES.get(extension);
+    if (fileType === undefined) {
+        return undefined;
+    }
+    return {
+        message: `This ${fileType} file (${extension}) is being linted as shell: a config entry selects ` +
+            `language 'sh/sh' (for example sh.configs.recommended) without a files list. ` +
+            `Wrap the preset in an entry with files, e.g. { files: ['**/*.sh'], extends: [sh.configs.recommended] }`,
+        line: 1,
+        column: 1,
+    };
+}

package/dist/language/selector-classes.d.ts

@@ -50,4 +50,3 @@ export type SelectorClassName = keyof typeof SELECTOR_CLASS_NODE_TYPES;
  * @public
  */
 export declare function matchesSelectorClass(className: string, node: ShNode): boolean;
-//# sourceMappingURL=selector-classes.d.ts.map

package/dist/language/selector-classes.js

@@ -49,4 +49,3 @@ const nodeTypesByClassName = new Map(Object.entries(SELECTOR_CLASS_NODE_TYPES).m
 export function matchesSelectorClass(className, node) {
     return nodeTypesByClassName.get(className)?.has(node.type) ?? false;
 }
-//# sourceMappingURL=selector-classes.js.map

package/dist/language/shell-language-options.d.ts

@@ -18,6 +18,13 @@ export type ShellDialect = 'bash' | 'posix' | 'mksh' | 'bats' | 'zsh';
  */
 export interface ShellLanguageOptions extends Record<string, unknown> {
     readonly dialect?: ShellDialect;
+    /**
+     * The Bash version (`MAJOR[.MINOR]`, such as `"3.2"`) the scripts must run
+     * on. The parser ignores it. The `compat/*` rules read it: unset means the
+     * newest version, versions compare numerically by major then minor, and
+     * under `dialect: "posix"` Bash-only features are unavailable at any
+     * version.
+     */
     readonly shellVersion?: string;
     /**
      * The prefix directive/inline-config comments must start with — e.g. the
@@ -99,4 +106,3 @@ export declare function validateShellLanguageOptions(languageOptions: Record<str
  * @public
  */
 export declare function normalizeShellLanguageOptions(languageOptions: Record<string, unknown>): NormalizedShellLanguageOptions;
-//# sourceMappingURL=shell-language-options.d.ts.map

package/dist/language/shell-language-options.js

@@ -36,9 +36,10 @@ function isValidDirectivePrefix(value) {
  * string — including `''` and `'not-a-version'` — with zero feedback). This
  * validates *shape only*, not membership in a known-versions list: a
  * shape-valid but nonexistent version like `'99.99'` is intentionally
- * accepted, per this issue's acceptance criteria and non-goals (deciding
- * `shellVersion`'s consumption semantics, and per-dialect known-version
- * allowlists, are separate concerns left to the rule layer).
+ * accepted, per this issue's acceptance criteria and non-goals (per-dialect
+ * known-version allowlists are out of scope). How rules consume
+ * `shellVersion` is defined by the `compat/*` rules' gate
+ * (`src/rules/compat/version-gates.ts`, documented in `docs/compat.md`).
  */
 const SHELL_VERSION_PATTERN = /^\d+(?:\.\d+)?$/u;
 function isValidShellVersionShape(value) {
@@ -105,4 +106,3 @@ export function normalizeShellLanguageOptions(languageOptions) {
         },
     };
 }
-//# sourceMappingURL=shell-language-options.js.map

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

@@ -60,6 +60,13 @@ export declare class ShellLanguage implements Language {
      * the `{ok: true, ast}` / `{ok: false, errors}` shape `Language.parse` is
      * required to return. Never throws — parse failures are reported as
      * fatal lint messages, per the `Language` contract.
+     *
+     * A file whose extension marks it as a known non-shell source type (for
+     * example `.js` or `.json`) is never shell-parsed: it fails with a single
+     * diagnostic explaining that a `language: 'sh/sh'` config entry without
+     * `files` reached it, and how to scope that entry. A source in which
+     * the parser silently drops text at a U+0080 fails at that character; a
+     * U+0080 the parser reads as an ordinary character does not.
      */
     parse(file: File, context: {
         languageOptions: ShellLanguageOptions;
@@ -73,10 +80,11 @@ export declare class ShellLanguage implements Language {
      * `createSourceCode` is called) — `directivePrefix` is therefore always
      * present, but `?? 'eslint'` stays as an explicit, honest fallback for
      * direct construction (e.g. tests that skip the `Language` normalization
-     * step), mirroring `parse()`'s `dialect` default above.
+     * step), mirroring `parse()`'s `dialect` default above. `dialect` and
+     * `shellVersion` are forwarded so rules read the same normalized values
+     * through `sourceCode.dialect` / `sourceCode.shellVersion`.
      */
     createSourceCode(file: File, parseResult: OkParseResult<ShellFile>, context: {
         languageOptions: ShellLanguageOptions;
     }): ShellSourceCode;
 }
-//# sourceMappingURL=shell-language.d.ts.map

package/dist/language/shell-language.js

@@ -1,5 +1,7 @@
 /** Adapts upstream parsing and diagnostics to ESLint's synchronous Language contract. */
 import { LangBash, LangBats, LangError, LangMirBSDKorn, LangPOSIX, LangZsh, ParseError, parseWithPositionsSync, } from 'sh-ast';
+import { firstDroppedTextIndex } from './end-of-input-marker.js';
+import { nonShellFileError } from './non-shell-file-guard.js';
 import { matchesSelectorClass as matchesShellSelectorClass } from './selector-classes.js';
 import { ShellSourceCode } from './shell-source-code.js';
 import { SourceCoordinates } from './source-coordinates.js';
@@ -24,6 +26,15 @@ function stripPositionPrefix(message, filename) {
     const escaped = filename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return message.replace(new RegExp(`^${escaped}:(?:\\d+|\\?):(?:\\d+|\\?):\\s*`), '');
 }
+/**
+ * Starts the message of a parse failure that is not a syntax error: the parser
+ * runtime aborted or the bridge to it failed, so nothing is known about the
+ * input. A syntax error never carries it. ESLint itself puts `Parsing error: `
+ * in front of every message a language returns from `parse`; this prefix is
+ * what tells the two kinds apart after that, for users and for tooling such as
+ * the corpus soak.
+ */
+const PARSER_RUNTIME_FAILURE_PREFIX = 'eslint-sh parser runtime failure (not a syntax error in this file): ';
 /** Preserve actual syntax positions while converting byte offsets into this source's UTF-16 diagnostics. */
 function toFileError(error, source) {
     if (error instanceof ParseError || error instanceof LangError) {
@@ -40,7 +51,26 @@ function toFileError(error, source) {
         };
     }
     // Bridge/input failures carry no asserted syntax position. The fallback is an ESLint presentation policy.
-    return { message: error instanceof Error ? error.message : String(error), line: 1, column: 1 };
+    const detail = error instanceof Error ? error.message : String(error);
+    return { message: `${PARSER_RUNTIME_FAILURE_PREFIX}${detail}`, line: 1, column: 1 };
+}
+/**
+ * The fatal parse error for a source in which the parser drops text at a U+0080, at that
+ * character, or `undefined` when nothing is dropped. Checked before parsing so a silently
+ * truncated tree never reaches the rules. A U+0080 the parser reads as an ordinary character
+ * (inside a quoted-delimiter heredoc body, after a backslash) is not an error; one the parser
+ * rejects (inside quotes or an expansion) is reported by the parser itself.
+ */
+function endOfInputMarkerError(source, options) {
+    const index = firstDroppedTextIndex(source, options);
+    if (index === undefined)
+        return undefined;
+    const location = new SourceCoordinates(source).atIndex(index);
+    return {
+        message: 'the character U+0080 is not supported: the parser reads it as end of input',
+        line: location.line,
+        column: location.column,
+    };
 }
 /**
  * `ShellLanguage` — the `@eslint/core` `Language` implementation for shell
@@ -106,16 +136,32 @@ export class ShellLanguage {
      * the `{ok: true, ast}` / `{ok: false, errors}` shape `Language.parse` is
      * required to return. Never throws — parse failures are reported as
      * fatal lint messages, per the `Language` contract.
+     *
+     * A file whose extension marks it as a known non-shell source type (for
+     * example `.js` or `.json`) is never shell-parsed: it fails with a single
+     * diagnostic explaining that a `language: 'sh/sh'` config entry without
+     * `files` reached it, and how to scope that entry. A source in which
+     * the parser silently drops text at a U+0080 fails at that character; a
+     * U+0080 the parser reads as an ordinary character does not.
      */
     parse(file, context) {
+        const misappliedError = nonShellFileError(file.path);
+        if (misappliedError !== undefined) {
+            return { ok: false, errors: [misappliedError] };
+        }
         const text = file.body;
         const dialect = context.languageOptions.dialect ?? 'bash';
+        const parseOptions = {
+            Variant: DIALECT_VARIANTS[dialect],
+            Filename: file.path,
+            KeepComments: true,
+        };
+        const unsupported = endOfInputMarkerError(text, parseOptions);
+        if (unsupported !== undefined) {
+            return { ok: false, errors: [unsupported] };
+        }
         try {
-            const parsed = parseWithPositionsSync(text, {
-                Variant: DIALECT_VARIANTS[dialect],
-                Filename: file.path,
-                KeepComments: true,
-            });
+            const parsed = parseWithPositionsSync(text, parseOptions);
             const ast = adaptSyntaxFile(parsed.File, text, parsed.Positions);
             return { ok: true, ast };
         }
@@ -132,14 +178,19 @@ export class ShellLanguage {
      * `createSourceCode` is called) — `directivePrefix` is therefore always
      * present, but `?? 'eslint'` stays as an explicit, honest fallback for
      * direct construction (e.g. tests that skip the `Language` normalization
-     * step), mirroring `parse()`'s `dialect` default above.
+     * step), mirroring `parse()`'s `dialect` default above. `dialect` and
+     * `shellVersion` are forwarded so rules read the same normalized values
+     * through `sourceCode.dialect` / `sourceCode.shellVersion`.
      */
     createSourceCode(file, parseResult, context) {
         return new ShellSourceCode({
             text: file.body,
             ast: parseResult.ast,
             directivePrefix: context.languageOptions.directivePrefix ?? 'eslint',
+            dialect: context.languageOptions.dialect ?? 'bash',
+            ...(context.languageOptions.shellVersion === undefined
+                ? {}
+                : { shellVersion: context.languageOptions.shellVersion }),
         });
     }
 }
-//# sourceMappingURL=shell-language.js.map