@eslint-sh/eslint-plugin 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,25 +1,68 @@
+/** Exposes the ESLint language, source view, and rule-author helpers as one plugin boundary. */
+import type { ConfigObject } from '@eslint/core';
 import { ShellLanguage } from './language/shell-language.js';
 export { ShellLanguage } from './language/shell-language.js';
 export { ShellSourceCode } from './language/shell-source-code.js';
 export type { NormalizedShellLanguageOptions, ShellLanguageOptions, ShellLanguageOptionsJSON, } from './language/shell-language-options.js';
 export { resolveWord } from './language/word-resolution.js';
-export type { ShellFile, ShellNode, ShellComment, ShellPosition } from './language/syntax-view.js';
+export type { Argv0Resolution } from 'sh-ast/analyze';
+export type { CommandContext, ResolveArgv0Options, WordResolution } from 'sh-ast/analyze';
+export type { ShellCommandSite } from './language/command-resolution.js';
+export type { ShellComment, ShellFile, ShellNode, ShellNodeField, ShellNodeMap, ShellNodeOf, ShellNodeType, ShellPosition, } from './language/syntax-view.js';
 export type { ShellDialect } from './language/shell-language-options.js';
+export type { DeclarationConvention, DeclaredCommand, FileDeclaredCommand, LintedFile, DescribedDeclaredCommand, ScriptDeclaredCommand, } from './declaration-conventions/declaration-convention.js';
+export { readDeclaredCommands } from './declaration-conventions/read-declared-commands.js';
+export type { DeclarationReadContext } from './declaration-conventions/read-declared-commands.js';
+export { commentPragma } from './declaration-conventions/comment-pragma.js';
+export { resolveDeclarationConvention } from './rules/resolve-declaration-convention.js';
+export type { DeclarationConventionBindingContext } from './rules/resolve-declaration-convention.js';
+export { defineShellRule } from './rules/define-shell-rule.js';
+export type { ShellListener, ShellRule, ShellRuleContext, ShellRuleMeta, ShellRuleSpec, ShellRuleVisitor, ShellTypedListeners, } from './rules/define-shell-rule.js';
+export { createWrapperRule } from './rules/create-wrapper-rule.js';
+export type { WrapperRuleConfig, WrapperRuleLocalInvocation, WrapperRuleLocalOperand, WrapperRuleSubcommands, } from './rules/create-wrapper-rule.js';
+export type { WrapperSpec } from 'sh-ast/analyze';
 /**
- * The `@eslint-sh/eslint-plugin` plugin object: `languages.sh` provides
+ * The `@eslint-sh/eslint-plugin` plugin object, this package's default
+ * export (`import sh from '@eslint-sh/eslint-plugin'`). `languages.sh` provides
  * `ShellLanguage` / `ShellSourceCode`, selected in a flat config via
  * `language: "sh/sh"` (`namespace: "sh"`). `meta.version` is read from this
  * package's own `package.json` at runtime — never hardcoded (see
  * `version.ts`).
  *
- * The empty `rules` registry lets consumers supply their own rules while
- * sharing parsing, selectors, source coordinates, and directive semantics.
+ * `rules` holds the plugin's built-in rules, each built with
+ * `defineShellRule` (so each declares `meta.languages: ["sh/sh"]`) and
+ * linking its docs page from `meta.docs.url`. Consumers can also supply their
+ * own rules, built with the same `defineShellRule`, while sharing parsing,
+ * selectors, source coordinates, and directive semantics.
+ *
+ * `configs.recommended` is the `sh/recommended` preset: a single config
+ * object carrying `plugins: { sh }` and `language: "sh/sh"` but no `files`,
+ * so it inherits the globs of the entry that extends it:
+ * `{ files: [...], extends: [sh.configs.recommended] }`. It enables the
+ * convention-free policy rules. The rules index at
+ * https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/rules/README.md
+ * describes preset membership and available autofixes.
+ * `configs['agent-authored']` is the strict `sh/agent-authored` preset for
+ * machine-written, human-reviewed scripts:
+ * every `recommended` rule plus the contract rules, all at `error`.
+ * `configs['bash-3.2']` and `configs['posix-portable']` are deployment-target
+ * packs: the first sets `languageOptions.shellVersion: "3.2"` and enables
+ * every version-gated `compat/*` rule; the second sets
+ * `languageOptions.dialect: "posix"`, enables the `compat/*` rules and the
+ * shebang/dialect check, and requires `set -eu`; it reports named constructs
+ * that fail on dash, not every non-POSIX construct, and leaves `local`,
+ * `echo -e` and the rest of shellcheck's SC3xxx catalog to shellcheck. Every
+ * shipped config is a
+ * single object with no `files`; the two packs also carry `languageOptions`,
+ * because the target they name is their meaning.
  *
  * Re-exported, unchanged, as the default export of the `eslint-sh` umbrella
  * package: importing this package or the umbrella package both yield the
  * same plugin object.
+ *
+ * @public
  */
-declare const _default: {
+declare const plugin: {
     meta: {
         name: string;
         version: string;
@@ -28,7 +71,12 @@ declare const _default: {
     languages: {
         sh: ShellLanguage;
     };
-    rules: {};
+    rules: Record<string, import("@eslint/core").RuleDefinition<import("@eslint/core").RuleDefinitionTypeOptions>>;
+    configs: {
+        recommended: ConfigObject;
+        "agent-authored": ConfigObject;
+        "bash-3.2": ConfigObject;
+        "posix-portable": ConfigObject;
+    };
 };
-export default _default;
-//# sourceMappingURL=index.d.ts.map
+export default plugin;

package/dist/index.js

@@ -1,23 +1,62 @@
+import { createAgentAuthoredConfig } from './configs/agent-authored.js';
+import { createBash32Config } from './configs/bash-3-2.js';
+import { createPosixPortableConfig } from './configs/posix-portable.js';
+import { createRecommendedConfig } from './configs/recommended.js';
 import { ShellLanguage } from './language/shell-language.js';
+import { rules } from './rules/index.js';
 import { readPackageVersion } from './version.js';
 export { ShellLanguage } from './language/shell-language.js';
 export { ShellSourceCode } from './language/shell-source-code.js';
 export { resolveWord } from './language/word-resolution.js';
+export { readDeclaredCommands } from './declaration-conventions/read-declared-commands.js';
+export { commentPragma } from './declaration-conventions/comment-pragma.js';
+export { resolveDeclarationConvention } from './rules/resolve-declaration-convention.js';
+export { defineShellRule } from './rules/define-shell-rule.js';
+export { createWrapperRule } from './rules/create-wrapper-rule.js';
+/* eslint-disable @api-extractor-tools/public-on-non-exported -- `plugin` is exported below as
+   `export default plugin`; the rule only recognizes inline exports. */
 /**
- * The `@eslint-sh/eslint-plugin` plugin object: `languages.sh` provides
+ * The `@eslint-sh/eslint-plugin` plugin object, this package's default
+ * export (`import sh from '@eslint-sh/eslint-plugin'`). `languages.sh` provides
  * `ShellLanguage` / `ShellSourceCode`, selected in a flat config via
  * `language: "sh/sh"` (`namespace: "sh"`). `meta.version` is read from this
  * package's own `package.json` at runtime — never hardcoded (see
  * `version.ts`).
  *
- * The empty `rules` registry lets consumers supply their own rules while
- * sharing parsing, selectors, source coordinates, and directive semantics.
+ * `rules` holds the plugin's built-in rules, each built with
+ * `defineShellRule` (so each declares `meta.languages: ["sh/sh"]`) and
+ * linking its docs page from `meta.docs.url`. Consumers can also supply their
+ * own rules, built with the same `defineShellRule`, while sharing parsing,
+ * selectors, source coordinates, and directive semantics.
+ *
+ * `configs.recommended` is the `sh/recommended` preset: a single config
+ * object carrying `plugins: { sh }` and `language: "sh/sh"` but no `files`,
+ * so it inherits the globs of the entry that extends it:
+ * `{ files: [...], extends: [sh.configs.recommended] }`. It enables the
+ * convention-free policy rules. The rules index at
+ * https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/rules/README.md
+ * describes preset membership and available autofixes.
+ * `configs['agent-authored']` is the strict `sh/agent-authored` preset for
+ * machine-written, human-reviewed scripts:
+ * every `recommended` rule plus the contract rules, all at `error`.
+ * `configs['bash-3.2']` and `configs['posix-portable']` are deployment-target
+ * packs: the first sets `languageOptions.shellVersion: "3.2"` and enables
+ * every version-gated `compat/*` rule; the second sets
+ * `languageOptions.dialect: "posix"`, enables the `compat/*` rules and the
+ * shebang/dialect check, and requires `set -eu`; it reports named constructs
+ * that fail on dash, not every non-POSIX construct, and leaves `local`,
+ * `echo -e` and the rest of shellcheck's SC3xxx catalog to shellcheck. Every
+ * shipped config is a
+ * single object with no `files`; the two packs also carry `languageOptions`,
+ * because the target they name is their meaning.
  *
  * Re-exported, unchanged, as the default export of the `eslint-sh` umbrella
  * package: importing this package or the umbrella package both yield the
  * same plugin object.
+ *
+ * @public
  */
-export default {
+const plugin = {
     meta: {
         name: '@eslint-sh/eslint-plugin',
         version: readPackageVersion(),
@@ -26,6 +65,14 @@ export default {
     languages: {
         sh: new ShellLanguage(),
     },
-    rules: {},
+    rules,
+    // Filled in below: each shipped config registers this very object under
+    // `plugins.sh`, so the plugin must exist before its configs can.
+    configs: {},
 };
-//# sourceMappingURL=index.js.map
+/* eslint-enable @api-extractor-tools/public-on-non-exported */
+plugin.configs.recommended = createRecommendedConfig(plugin);
+plugin.configs['agent-authored'] = createAgentAuthoredConfig(plugin);
+plugin.configs['bash-3.2'] = createBash32Config(plugin);
+plugin.configs['posix-portable'] = createPosixPortableConfig(plugin);
+export default plugin;

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

@@ -0,0 +1,124 @@
+import type { Argv0Resolution, CallExpr, CommandContext, CommandSite, ResolveArgv0Options, WordResolution } from 'sh-ast/analyze';
+import type { ShellFile, ShellNode, ShellNodeOf } from './syntax-view.js';
+/**
+ * Every command site in one parsed file, from a single `enumerateCommands`
+ * call. `sites` keeps analysis's own list and order (source order); `byNode`
+ * looks a site up by the raw `CallExpr` object analysis reports as
+ * `CommandSite.node`. A `CallExpr` with no entry invokes no command (an
+ * assignment-only statement such as `FOO=1`).
+ * @internal
+ */
+export interface CommandSiteIndex {
+    readonly sites: readonly CommandSite[];
+    readonly byNode: ReadonlyMap<CallExpr, CommandSite>;
+}
+/**
+ * One command invocation in a linted shell file, in lint-view terms: an
+ * `sh-ast/analyze` `CommandSite` whose `node` is the `CallExpr` view node
+ * ESLint passes to rule visitors, so a rule can `context.report()` on it.
+ *
+ * The data comes from `sh-ast/analyze`'s `enumerateCommands` and is facts
+ * only: how the command is reached and what its words resolve to, never a
+ * verdict on whether running it is safe. A dynamic (`static: false`) `argv0`
+ * is a normal result.
+ *
+ * Read one through `ShellSourceCode.getCommandSites()`.
+ *
+ * Every rule linting a file sees the same sites, so each one is deeply
+ * frozen: the entry, its `context` array and every frame in it, its `argv`
+ * array, and every `WordResolution` in `argv` (`argv0` included). Writing to
+ * any of them throws in strict-mode code and is ignored otherwise, so one rule
+ * cannot change what another rule reads. The `node` is the shared lint view
+ * node, which, like every node ESLint passes to rules, is not frozen and must
+ * not be modified.
+ *
+ * @public
+ */
+export interface ShellCommandSite {
+    /**
+     * The `CallExpr` view node for this command: the same object (`===`)
+     * ESLint passes to a `CallExpr` visitor, with `range` and `loc` in this
+     * file's UTF-16 coordinates.
+     */
+    readonly node: ShellNodeOf<'CallExpr'>;
+    /**
+     * The path from the file root to this command, outermost frame first,
+     * exactly as `sh-ast/analyze` reports it. For example, `date` in
+     * `f() { echo "$(date)"; }` has
+     * `[{ kind: 'function', name: 'f' }, { kind: 'cmdSubst' }]`.
+     */
+    readonly context: readonly CommandContext[];
+    /** The command word (`argv[0]`) resolved with `{ context: 'command-argument' }`. */
+    readonly argv0: WordResolution;
+    /**
+     * Every word of the command, `argv0` included, in argument order, each
+     * resolved with `{ context: 'command-argument' }`. Leading `VAR=val`
+     * assignments are not part of argv.
+     */
+    readonly argv: readonly WordResolution[];
+    /**
+     * Follows this command's argv0 through transparent wrappers (`env`, `sudo`,
+     * `nohup`, `exec`, …) and returns `sh-ast/analyze`'s `resolveArgv0`
+     * result. Same answer as
+     * `ShellSourceCode.resolveInvokedCommand(node, options)`; both read the
+     * same per-file index.
+     *
+     * @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 A new result on every call. Its `chain` and `chainIndices`
+     * arrays belong to the caller. `chainIndices` gives each chain entry's
+     * position in this site's `argv`.
+     * @throws `ShAnalyzeInvalidWrapperSpecError` (from `sh-ast/analyze`) when
+     * `options.transparentWrappers` contains a malformed entry.
+     */
+    resolveInvokedCommand(options?: ResolveArgv0Options): Argv0Resolution;
+}
+/**
+ * Builds the {@link CommandSiteIndex} for a whole parsed file with a single
+ * `enumerateCommands` call over the file's original syntax. Each site's
+ * `node` is the parser's own `CallExpr` object, the same object the lint view
+ * associates with its projected `CallExpr`, so lookups are by identity.
+ *
+ * Building a `CommandSite` by hand instead would duplicate analysis's choices
+ * about which words form argv and how they resolve, which is exactly the drift
+ * this bridge exists to prevent.
+ *
+ * The index is shared by every rule linting the file, and its data reaches
+ * rules: `getCommandSites` exposes each site's `context`, `argv0` and `argv`.
+ * Analysis also shares one `context` array and its frames between
+ * sibling commands. So every site is frozen in place here, before any rule
+ * can see it (see {@link freezeCommandSite}).
+ *
+ * @throws TypeError when `file` has no associated parsed syntax.
+ * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when the file's
+ * nesting exceeds analysis's recursion guard. It propagates unchanged: a
+ * partial index would silently omit real commands, so callers fail closed.
+ * @internal
+ */
+export declare function buildCommandSiteIndex(file: ShellFile): CommandSiteIndex;
+/**
+ * Re-expresses every site in `index` in lint-view terms, in analysis's order.
+ * Each `node` comes from the syntax → view association recorded when `file`
+ * was projected, so no second walk of the view is needed and the node is the
+ * very object ESLint's traversal visits. The returned array and its entries
+ * are frozen, and the `context`, `argv0` and `argv` they carry were frozen
+ * when the index was built: the same array is shared by every rule linting
+ * this file.
+ *
+ * @throws Error when a site's `CallExpr` has no view node in `file`. Analysis
+ * of the same parse only reports parser nodes the projection saw, so this
+ * marks a broken invariant rather than a shell construct; failing loudly is
+ * safer than silently dropping a command.
+ * @internal
+ */
+export declare function viewCommandSites(file: ShellFile, index: CommandSiteIndex): readonly ShellCommandSite[];
+/**
+ * Returns the parser's own `CallExpr` behind a lint `CallExpr`.
+ *
+ * @throws TypeError when `callExpr` is not a parsed `CallExpr` from this
+ * language adapter (a fabricated or synthetic view node has no syntax).
+ * @internal
+ */
+export declare function rawCallExprFor(callExpr: ShellNode): CallExpr;

package/dist/language/command-resolution.js

@@ -0,0 +1,120 @@
+/**
+ * Bridges command-level questions from ESLint view identity back to faithful
+ * syntax. `sh-ast/analyze` owns what a command invocation is and which command
+ * it runs; this module only builds the per-file index of the `CommandSite`s
+ * analysis reports, maps a lint `CallExpr` to its raw syntax node, and maps
+ * each site's raw `CallExpr` forward to its lint view node, so every rule gets
+ * the analysis answer rather than a local reinterpretation.
+ */
+import { enumerateCommands, resolveArgv0 } from 'sh-ast/analyze';
+import { syntaxForNode, viewForSyntax, withoutCrlfCarriageReturn } from './syntax-view.js';
+/**
+ * Builds the {@link CommandSiteIndex} for a whole parsed file with a single
+ * `enumerateCommands` call over the file's original syntax. Each site's
+ * `node` is the parser's own `CallExpr` object, the same object the lint view
+ * associates with its projected `CallExpr`, so lookups are by identity.
+ *
+ * Building a `CommandSite` by hand instead would duplicate analysis's choices
+ * about which words form argv and how they resolve, which is exactly the drift
+ * this bridge exists to prevent.
+ *
+ * The index is shared by every rule linting the file, and its data reaches
+ * rules: `getCommandSites` exposes each site's `context`, `argv0` and `argv`.
+ * Analysis also shares one `context` array and its frames between
+ * sibling commands. So every site is frozen in place here, before any rule
+ * can see it (see {@link freezeCommandSite}).
+ *
+ * @throws TypeError when `file` has no associated parsed syntax.
+ * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when the file's
+ * nesting exceeds analysis's recursion guard. It propagates unchanged: a
+ * partial index would silently omit real commands, so callers fail closed.
+ * @internal
+ */
+export function buildCommandSiteIndex(file) {
+    const syntax = syntaxForNode(file);
+    if (syntax?.Type !== 'File') {
+        throw new TypeError('expected a parsed shell File from this language adapter');
+    }
+    const sites = Object.freeze(enumerateCommands(syntax).map((site) => freezeCommandSite(withLfArgv(site))));
+    return { sites, byNode: new Map(sites.map((site) => [site.node, site])) };
+}
+/**
+ * `site` with each argv word resolved as its LF equivalent (see
+ * `withoutCrlfCarriageReturn`): on CRLF input, a static word that ends its
+ * line otherwise carries the terminator's `\r` (`ls\r`). Normalizing argv
+ * here, once, reaches every consumer, because `resolveArgv0` reads wrapper
+ * chains from `site.argv` and `getCommandName` reads `site.argv0`.
+ */
+function withLfArgv(site) {
+    const words = site.node.Args ?? [];
+    const argv = site.argv.map((resolution, index) => withoutCrlfCarriageReturn(words[index] ?? null, resolution));
+    if (argv.every((resolution, index) => resolution === site.argv[index]))
+        return site;
+    return { ...site, argv0: argv[0], argv };
+}
+/**
+ * Freezes the data a rule can reach through `site`: the site, its `context`
+ * array and each frame, its `argv` array and each resolution (`argv0` is
+ * `argv[0]`, frozen again harmlessly). `site.node` is the parser's syntax
+ * record, which rules never receive, and is left alone.
+ *
+ * Freezing in place, instead of copying, keeps every value identical to what
+ * analysis returned. That is safe because `enumerateCommands` builds these
+ * objects fresh on each call, and nothing in `sh-ast/analyze` writes to them
+ * after it returns: `resolveArgv0` only reads a site. A frame's fields are
+ * primitives or source text, so freezing each frame shallowly is complete.
+ */
+function freezeCommandSite(site) {
+    for (const frame of site.context)
+        Object.freeze(frame);
+    Object.freeze(site.context);
+    for (const word of site.argv)
+        Object.freeze(word);
+    Object.freeze(site.argv);
+    Object.freeze(site.argv0);
+    return Object.freeze(site);
+}
+/**
+ * Re-expresses every site in `index` in lint-view terms, in analysis's order.
+ * Each `node` comes from the syntax → view association recorded when `file`
+ * was projected, so no second walk of the view is needed and the node is the
+ * very object ESLint's traversal visits. The returned array and its entries
+ * are frozen, and the `context`, `argv0` and `argv` they carry were frozen
+ * when the index was built: the same array is shared by every rule linting
+ * this file.
+ *
+ * @throws Error when a site's `CallExpr` has no view node in `file`. Analysis
+ * of the same parse only reports parser nodes the projection saw, so this
+ * marks a broken invariant rather than a shell construct; failing loudly is
+ * safer than silently dropping a command.
+ * @internal
+ */
+export function viewCommandSites(file, index) {
+    return Object.freeze(index.sites.map((site) => {
+        const node = viewForSyntax(file, site.node);
+        if (node?.type !== 'CallExpr') {
+            throw new Error('command site has no CallExpr in the lint view of this file');
+        }
+        return Object.freeze({
+            node,
+            context: site.context,
+            argv0: site.argv0,
+            argv: site.argv,
+            resolveInvokedCommand: (options) => resolveArgv0(site, options),
+        });
+    }));
+}
+/**
+ * Returns the parser's own `CallExpr` behind a lint `CallExpr`.
+ *
+ * @throws TypeError when `callExpr` is not a parsed `CallExpr` from this
+ * language adapter (a fabricated or synthetic view node has no syntax).
+ * @internal
+ */
+export function rawCallExprFor(callExpr) {
+    const syntax = syntaxForNode(callExpr);
+    if (syntax?.Type !== 'CallExpr') {
+        throw new TypeError('expected a parsed shell CallExpr from this language adapter');
+    }
+    return syntax;
+}

package/dist/language/end-of-input-marker.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Detects a source whose U+0080 made the parser silently drop text.
+ *
+ * mvdan/sh's reader uses U+0080 (`utf8.RuneSelf`) as its internal end-of-input marker. In some
+ * positions the parser reads it as an ordinary character and returns the whole tree; in others
+ * it stops there and returns a tree for only the text before it, with no error. A linter that
+ * accepted the second kind would skip every rule on the lost text, so those sources must be
+ * refused while the first kind keeps linting.
+ *
+ * The two are told apart by asking the parser what it does with the same source when U+0080 is
+ * an ordinary character: the parse is complete exactly when the printed tree is the same as the
+ * printed tree of the source with every U+0080 swapped for `X`. Text the parser dropped is
+ * missing from the first print and present in the second. Nothing is inferred from tree
+ * extents, so a trailing comment or heredoc body cannot make a truncated file look complete.
+ */
+import { type ParseOptions } from 'sh-ast';
+/**
+ * The UTF-16 index of the first U+0080 whose presence makes the parser drop text, or
+ * `undefined` when `text` holds none or the parser handles every one of them completely.
+ *
+ * A source the parser rejects with an error is also `undefined`: that is a fatal parse error the
+ * caller reports through its normal path, not a silent loss. Every other doubt is a refusal:
+ * a source that parses but prints differently from its swapped counterpart is refused, and so is
+ * one whose swapped counterpart no longer parses, so an undecidable position is never accepted.
+ *
+ * @param text - The source about to be parsed.
+ * @param options - The parse options the caller will use, so the dialect matches.
+ */
+export declare function firstDroppedTextIndex(text: string, options: ParseOptions): number | undefined;

package/dist/language/end-of-input-marker.js

@@ -0,0 +1,88 @@
+/**
+ * Detects a source whose U+0080 made the parser silently drop text.
+ *
+ * mvdan/sh's reader uses U+0080 (`utf8.RuneSelf`) as its internal end-of-input marker. In some
+ * positions the parser reads it as an ordinary character and returns the whole tree; in others
+ * it stops there and returns a tree for only the text before it, with no error. A linter that
+ * accepted the second kind would skip every rule on the lost text, so those sources must be
+ * refused while the first kind keeps linting.
+ *
+ * The two are told apart by asking the parser what it does with the same source when U+0080 is
+ * an ordinary character: the parse is complete exactly when the printed tree is the same as the
+ * printed tree of the source with every U+0080 swapped for `X`. Text the parser dropped is
+ * missing from the first print and present in the second. Nothing is inferred from tree
+ * extents, so a trailing comment or heredoc body cannot make a truncated file look complete.
+ */
+import { parseSync, printSync } from 'sh-ast';
+const END_OF_INPUT_MARKER = '\u0080';
+/** An ordinary one-UTF-16-unit word character, so offsets are the same in both parses. */
+const ORDINARY_CHARACTER = 'X';
+/** What the parser makes of a source: the printed tree, or `ERROR` when it does not parse. */
+const ERROR = Symbol('parse error');
+/**
+ * Prints `text` the way the parser sees it. Every U+0080 in the result is swapped for the
+ * ordinary character so the print of the original can be compared with the print of the
+ * swapped source.
+ */
+function printed(text, options) {
+    try {
+        const output = printSync(parseSync(text, options));
+        const decoded = typeof output === 'string' ? output : new TextDecoder().decode(output);
+        return decoded.replaceAll(END_OF_INPUT_MARKER, ORDINARY_CHARACTER);
+    }
+    catch {
+        return ERROR;
+    }
+}
+/**
+ * The UTF-16 index of the first U+0080 whose presence makes the parser drop text, or
+ * `undefined` when `text` holds none or the parser handles every one of them completely.
+ *
+ * A source the parser rejects with an error is also `undefined`: that is a fatal parse error the
+ * caller reports through its normal path, not a silent loss. Every other doubt is a refusal:
+ * a source that parses but prints differently from its swapped counterpart is refused, and so is
+ * one whose swapped counterpart no longer parses, so an undecidable position is never accepted.
+ *
+ * @param text - The source about to be parsed.
+ * @param options - The parse options the caller will use, so the dialect matches.
+ */
+export function firstDroppedTextIndex(text, options) {
+    const indices = [];
+    for (let at = text.indexOf(END_OF_INPUT_MARKER); at !== -1; at = text.indexOf(END_OF_INPUT_MARKER, at + 1)) {
+        indices.push(at);
+    }
+    if (indices.length === 0)
+        return undefined;
+    const ordinary = text.replaceAll(END_OF_INPUT_MARKER, ORDINARY_CHARACTER);
+    const expected = printed(ordinary, options);
+    const actual = printed(text, options);
+    if (actual === ERROR)
+        return undefined;
+    if (expected !== ERROR && actual === expected)
+        return undefined;
+    /** Whether keeping only the first `count` U+0080 characters (the rest swapped) still differs. */
+    const dropsText = (count) => {
+        let candidate = '';
+        let from = 0;
+        for (const index of indices.slice(0, count)) {
+            candidate += ordinary.slice(from, index) + END_OF_INPUT_MARKER;
+            from = index + 1;
+        }
+        candidate += ordinary.slice(from);
+        const result = printed(candidate, options);
+        return result === ERROR || expected === ERROR || result !== expected;
+    };
+    // The full source differs, so the smallest differing prefix of U+0080 characters exists; the
+    // search assumes that keeping more of them never repairs the parse, and only ever lands on a
+    // count that was itself observed to differ.
+    let low = 1;
+    let high = indices.length;
+    while (low < high) {
+        const middle = (low + high) >> 1;
+        if (dropsText(middle))
+            high = middle;
+        else
+            low = middle + 1;
+    }
+    return indices[high - 1];
+}

package/dist/language/line-breaks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Line-break handling shared by rules, so a CRLF file lints like its LF
+ * equivalent: an edit that writes a line break uses the file's own style, and
+ * report text quoting source never prints the `\r` of a `\r\n`.
+ */
+/**
+ * The line break an edit to `text` writes: the file's first line break, so a
+ * CRLF file stays CRLF, or `\n` when `text` has none.
+ * @internal
+ */
+export declare function lineBreakOf(text: string): string;
+/**
+ * `excerpt` (source text a message quotes) with each `\r\n` written as `\n`,
+ * so a quoted multi-line construct reads the same in a CRLF file as in its LF
+ * equivalent.
+ * @internal
+ */
+export declare function messageExcerpt(excerpt: string): string;

package/dist/language/line-breaks.js

@@ -0,0 +1,22 @@
+/**
+ * Line-break handling shared by rules, so a CRLF file lints like its LF
+ * equivalent: an edit that writes a line break uses the file's own style, and
+ * report text quoting source never prints the `\r` of a `\r\n`.
+ */
+/**
+ * The line break an edit to `text` writes: the file's first line break, so a
+ * CRLF file stays CRLF, or `\n` when `text` has none.
+ * @internal
+ */
+export function lineBreakOf(text) {
+    return /\r\n|\n|\r/u.exec(text)?.[0] ?? '\n';
+}
+/**
+ * `excerpt` (source text a message quotes) with each `\r\n` written as `\n`,
+ * so a quoted multi-line construct reads the same in a CRLF file as in its LF
+ * equivalent.
+ * @internal
+ */
+export function messageExcerpt(excerpt) {
+    return excerpt.replace(/\r\n/gu, '\n');
+}