sh-ast 0.0.0 → 0.2.0

package/README.md

@@ -0,0 +1,147 @@
+# sh-ast
+
+A synchronous, fully-typed shell AST for JavaScript and TypeScript. `sh-ast` parses shell scripts
+(bash, POSIX sh, mksh, zsh, and bats) using [mvdan/sh](https://github.com/mvdan/sh) — the Go
+shell parser used by `shfmt` and `shellcheck`-adjacent tooling — via a small Go/WASM shim, and
+normalizes the result into a plain-object AST with UTF-16-safe positions that's natural to
+consume from JS/TS (linters, formatters, codemods, static analysis, or anything else that needs
+to understand shell source structurally).
+
+```ts
+import { parseSync } from 'sh-ast';
+
+const file = parseSync('echo hi');
+file.stmts[0].cmd.type; // "CallExpr"
+```
+
+## Provenance
+
+`sh-ast` was extracted from [`eslint-sh`](https://github.com/mike-north/eslint-sh) (as
+`@eslint-sh/bridge`) at commit
+[`bdd55b3`](https://github.com/mike-north/eslint-sh/commit/bdd55b3), where it was built as the
+parser core underneath an ESLint plugin for shell scripts. The full commit history predating the
+extraction lives in that repository. This package carries no ESLint dependency and exposes the
+same public API `@eslint-sh/bridge` did.
+
+## Status
+
+The visitor-keys and child-type-schema tables, plus the `ShNodes.*` TypeScript typings, are
+generated from mvdan/sh's `syntax` package struct definitions by `tools/gen-visitor-keys` — see
+that tool's README for "The schema table is generated, not hand-written".
+
+## Public API
+
+- `parseSync(text, options?)` — synchronous parse; throws `ShParseError` (with `.line`,
+  `.column`, `.filename`) on a shell syntax error.
+- `ParseOptions` — `{ dialect?, filename? }`; `dialect` is one of `bash | posix | mksh | bats |
+zsh`, mapped to mvdan/sh's `LangVariant` by string name.
+- `ShNode` / `ShFile` — normalized node shape (`type`, `range`, `loc`, plus lowercased fields
+  from mvdan/sh's tree).
+- `ShNodes` — generated, strongly-typed `ShNode` subtypes for every mvdan/sh node type (e.g.
+  `ShNodes.ShCallExprNode`, `ShNodes.ShDeclClauseNode`), plus union aliases (`ShAnyNode`,
+  `ShCommandNode`, `ShWordPartNode`, …). Additive and optional — `ShNode`'s index signature
+  remains the base contract.
+- `visitorKeys` — generated node-type → child-field-name table.
+- `walk(node, visit)` — visits every node in a normalized tree; discovers children structurally
+  rather than depending on `visitorKeys`.
+
+## Regenerating the schema tables
+
+After bumping the pinned mvdan/sh version (`shim/go.mod` _and_ `../../tools/gen-visitor-keys/go.mod`
+must move together):
+
+```sh
+pnpm run generate:sh-ast-schema
+```
+
+This regenerates `generated/visitor-keys.js(.d.ts)`, `generated/child-type-schema.js(.d.ts)`, and
+`generated/node-types.d.ts`, then formats them with Prettier. CI
+(`.github/workflows/gen-visitor-keys.yml`) reruns the same script and fails the build if the
+committed artifacts don't come back byte-identical — the drift gate for future mvdan/sh bumps.
+Re-run the kitchen-sink golden test (`test/kitchen-sink.test.ts`) afterward; it fails if the new
+mvdan/sh version adds a node type the fixtures don't yet exercise.
+
+## The WASM shim
+
+`shim/main.go` parses with `mvdan.cc/sh/v3/syntax` and encodes the result with
+`shim/internal/nodeencode` — a performance fork of `mvdan.cc/sh/v3/syntax/typedjson`'s encode
+path (see that package's doc comment for why: typedjson's reflection-based encoder rebuilds an
+identical synthetic struct type per node _instance_ rather than once per node _type_, which
+dominated warm-parse latency — see "Performance" below) — so interface-typed nodes (`CallExpr`,
+`BinaryCmd`, …) carry a `Type` discriminator, exactly as upstream typedjson does (verified
+byte-identical in `shim/internal/nodeencode/encode_test.go`). The whole result envelope —
+including any error message — is marshaled with Go's `encoding/json`, so JSON-significant bytes
+in an error message (e.g. an unclosed-quote message containing `"`) survive the Go→JS boundary
+intact.
+
+The shim exposes a linear-memory ABI — `alloc`/`process`/`free` WASM exports plus the `mem`
+memory export — instead of a `syscall/js` global function. `wasm-instance.ts` writes UTF-8 bytes
+directly into WASM memory and reads the JSON result back with `TextDecoder`, avoiding
+`syscall/js`'s much more expensive per-call JS↔Go value marshaling (see "Performance" below).
+
+### Performance
+
+Local measurement (700-line/~9k-node fixture, warm instance, Apple M-series):
+
+| Stage                                 | Before (syscall/js + typedjson) | After (linear memory + nodeencode) |
+| ------------------------------------- | ------------------------------: | ---------------------------------: |
+| End-to-end warm `parseSync` (p50)     |                          ~97 ms |                             ~29 ms |
+| wasm call (parse + encode + transfer) |                          ~91 ms |                           ~23.5 ms |
+| `JSON.parse`                          |                           ~3 ms |                              ~3 ms |
+| `normalize`                           |                         ~2.5 ms |                            ~2.7 ms |
+| `sh-ast.wasm` size                    |                        ~4.10 MB |                           ~3.82 MB |
+
+The dominant fix was **not** the transport switch alone — profiling found `typedjson.Encode`'s
+`reflect.StructOf` call (rebuilding an identical synthetic struct type once per node _instance_)
+responsible for ~80ms of the ~90ms wasm call; `nodeencode`'s per-_type_ cache cut that to ~14ms.
+The linear-memory ABI switch and a hand-rolled envelope wrap (skipping a redundant
+`encoding/json.Marshal` re-compaction of the already-encoded AST bytes) account for the rest.
+
+**TinyGo**, evaluated for its ~4x smaller runtime, cannot run this shim: it compiles
+`reflect.StructOf` calls without error but panics at runtime with `unimplemented:
+reflect.StructOf()` the moment `nodeencode`/`typedjson`'s encoder runs (confirmed against
+TinyGo 0.41.1). Standard Go + `wasm-opt -Oz` (binaryen, pinned in CI) is the fallback:
+`sh-ast.wasm` is optimized after every build, for a ~7% size reduction (~4.09 MB → ~3.82 MB) with
+no behavior change. Neither path reaches a 1.5 MB stretch target.
+
+After editing `shim/main.go` or `shim/internal/nodeencode`, rebuild the committed
+`shim/sh-ast.wasm`:
+
+```sh
+cd shim
+GOOS=js GOARCH=wasm go build -buildvcs=false -trimpath -ldflags="-s -w -buildid=" -o sh-ast.wasm .
+wasm-opt -Oz --enable-bulk-memory-opt --enable-nontrapping-float-to-int sh-ast.wasm -o sh-ast.wasm
+```
+
+`wasm-opt` ships with [binaryen](https://github.com/WebAssembly/binaryen/releases) — CI installs
+a pinned release (see `.github/workflows/wasm-reproducibility.yml`'s `BINARYEN_VERSION`); install
+the same version locally (`brew install binaryen`, or download the pinned release directly) so
+your rebuild matches CI byte-for-byte. `--enable-bulk-memory-opt` and
+`--enable-nontrapping-float-to-int` tell `wasm-opt` to accept the two WASM proposal features
+Go's `js/wasm` target already emits (both broadly supported in Node and browsers since ~2020) —
+without them, `wasm-opt` rejects the input as invalid.
+
+The `-buildid=` flag blanks out Go's build-ID metadata (used only by the Go toolchain's own
+build cache, never read at runtime); without it, `-trimpath` alone is not enough for a
+byte-identical rebuild — the embedded build ID otherwise varies between build-cache states even
+with identical source and dependencies.
+
+`-buildvcs=false` is equally required: Go 1.18+ stamps binaries with `vcs.revision`/`vcs.time`/
+`vcs.modified` by default (`-buildvcs=auto`), reading whatever commit and dirty-state the
+checkout happens to be in at build time. That stamp isn't touched by `-s -w` (it lives outside
+the symbol table/DWARF that those flags strip), so two builds of _identical source_ differ
+whenever the checkout's commit or dirty-state differs — which is exactly what happens for a
+`pull_request`-triggered CI run (GitHub synthesizes a fresh merge commit, with its own SHA and
+timestamp, on every run) versus a `push`-triggered run (checks out the named branch commit
+as-is), and equally for a local checkout with any uncommitted changes elsewhere in the working
+tree. `-buildvcs=false` removes this source of non-determinism entirely; verified byte-for-byte
+identical across a native macOS/arm64 build, a `linux/amd64` build under Docker/QEMU emulation,
+and real `ubuntu-latest` CI runs triggered via `push`, `pull_request`, and `workflow_dispatch`.
+
+`wasm-opt -Oz` is a deterministic, version-pinned transform: rebuilding twice (Go build +
+wasm-opt) produces byte-identical output, verified locally and by CI's `rebuild-match` job.
+
+CI rebuilds the shim with a pinned Go toolchain (`shim/go.mod`) and a pinned `wasm-opt`
+(`.github/workflows/wasm-reproducibility.yml`), and fails if the output differs from the
+committed artifact. It also runs `shim/internal/nodeencode`'s Go test suite, which asserts the
+fork's output is byte-identical to upstream `typedjson.Encode`.

package/dist/analyze/ansi-c-escapes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Decodes `$'...'` (Bash ANSI-C Quoting) escape sequences.
+ *
+ * mvdan/sh's parser does **not** perform this decoding: for a `SglQuoted`
+ * word part with `dollar: true`, the normalized `value` field is the raw,
+ * un-decoded source text between the quotes (verified empirically against
+ * mvdan.cc/sh/v3 v3.13.1 — see `test/analyze-resolve-word.test.ts`'s module
+ * comment for how this was confirmed). This module fills that gap using the
+ * escape table the Bash Reference Manual documents, independently of
+ * whatever mvdan/sh itself does or doesn't decode.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#ANSI_002dC-Quoting
+ * @internal
+ */
+/**
+ * The result of {@link decodeAnsiCString}: either the fully decoded text,
+ * or `ok: false` when the raw text contains a `\u`/`\U` escape whose value
+ * has no corresponding Unicode character (see {@link MAX_UNICODE_CODE_POINT}'s
+ * doc comment for why that case can't be decoded to an exact JavaScript
+ * string, and can't be left as literal un-decoded text either without
+ * claiming a false `static: true` result). Never throws — callers (see
+ * `resolveWord`'s `SglQuoted` handling) turn `ok: false` into
+ * `{ static: false, reason: 'unsupported' }` for the whole word.
+ *
+ * @internal
+ */
+export type AnsiCDecodeResult = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+};
+/**
+ * Decodes the raw inner text of a `$'...'` (ANSI-C quoted) string per Bash
+ * Reference Manual §3.1.2.4, "ANSI-C Quoting". `raw` is the text between
+ * the quotes (mvdan/sh's `SglQuoted.Value` for a `Dollar: true` node),
+ * exactly as it appears in source — not yet interpreted in any way.
+ *
+ * Recognized escapes: `\a \b \e \E \f \n \r \t \v \\ \' \" \?`, octal
+ * `\nnn` (one to three digits), hex `\xHH` (one or two digits), Unicode
+ * `\uHHHH` (one to four digits) and `\UHHHHHHHH` (one to eight digits), and
+ * control-character `\cX`. An unrecognized backslash sequence (not in this
+ * table, and not a recognized numeric escape) is left as-is — Bash's own
+ * decoding is best-effort for malformed input, and this function mirrors
+ * that rather than throwing, matching {@link resolveWord}'s "never throw
+ * for well-formed input" contract at the string level too. A `\u`/`\U`
+ * whose value *is* well-formed but has no corresponding Unicode character
+ * is a different case — see {@link AnsiCDecodeResult}.
+ *
+ * @internal
+ */
+export declare function decodeAnsiCString(raw: string): AnsiCDecodeResult;
+//# sourceMappingURL=ansi-c-escapes.d.ts.map

package/dist/analyze/ansi-c-escapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi-c-escapes.d.ts","sourceRoot":"","sources":["../../src/analyze/ansi-c-escapes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwFH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAExE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CA8IhE"}

package/dist/analyze/ansi-c-escapes.js

@@ -0,0 +1,255 @@
+/**
+ * Decodes `$'...'` (Bash ANSI-C Quoting) escape sequences.
+ *
+ * mvdan/sh's parser does **not** perform this decoding: for a `SglQuoted`
+ * word part with `dollar: true`, the normalized `value` field is the raw,
+ * un-decoded source text between the quotes (verified empirically against
+ * mvdan.cc/sh/v3 v3.13.1 — see `test/analyze-resolve-word.test.ts`'s module
+ * comment for how this was confirmed). This module fills that gap using the
+ * escape table the Bash Reference Manual documents, independently of
+ * whatever mvdan/sh itself does or doesn't decode.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#ANSI_002dC-Quoting
+ * @internal
+ */
+/**
+ * Hex digit predicate for `\xHH`/`\uHHHH`/`\UHHHHHHHH`. `ch` is expected to
+ * come from `String.prototype.charAt`, which returns `''` (never
+ * `undefined`) past the end of the string — `''` correctly fails this test,
+ * so callers don't need a separate bounds check.
+ */
+function isHexDigit(ch) {
+    return /^[0-9a-fA-F]$/.test(ch);
+}
+/** Octal digit predicate for `\nnn`; see {@link isHexDigit}'s `charAt` note. */
+function isOctalDigit(ch) {
+    return ch.length === 1 && ch >= '0' && ch <= '7';
+}
+/**
+ * The highest Unicode scalar value `\uHHHH`/`\UHHHHHHHH` can validly decode
+ * to. `\uHHHH` (max 4 hex digits, i.e. `0xFFFF`) can never exceed this, but
+ * `\UHHHHHHHH` (up to 8 hex digits, i.e. up to `0xFFFFFFFF`) routinely does.
+ *
+ * The Bash Reference Manual's ANSI-C Quoting table documents `\UHHHHHHHH`
+ * only as "the Unicode ... character whose value is the hexadecimal value
+ * HHHHHHHH" — it does not say what happens when that value has no
+ * corresponding Unicode character (i.e. is greater than `U+10FFFF`, the
+ * highest code point Unicode defines). Real bash's behavior for this case
+ * is undocumented and not a reasonable decode target: it falls back to a
+ * pre-RFC-3629, up-to-6-byte "UTF-8-like" bit-packing with no range
+ * validation (confirmed empirically — e.g. `$'\U00110000'` produces the
+ * raw byte sequence `f4 90 80 80`, which is not valid UTF-8 text, and
+ * `$'\UFFFFFFFF'` produces no output at all, exit 0). Neither of those is
+ * representable as an exact JavaScript string, so this module does **not**
+ * fall back to treating the escape as literal, un-decoded text the way it
+ * does for other unrecognized escapes — that would silently claim a
+ * `static: true` exact text that real bash never produces (a false
+ * static). Instead, {@link decodeAnsiCString} reports an out-of-range
+ * `\u`/`\U` as *unrepresentable* via {@link AnsiCDecodeResult}, and
+ * `resolveWord` propagates that as `{ static: false, reason: 'unsupported' }`
+ * for the whole word — never `String.fromCodePoint`, which throws
+ * `RangeError` for any value over this limit and would violate
+ * `resolveWord`'s "never throw for well-formed input" contract.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#ANSI_002dC-Quoting
+ */
+const MAX_UNICODE_CODE_POINT = 0x10ffff;
+/**
+ * Greedily consumes up to `maxDigits` hex digits starting at `start`,
+ * returning the parsed numeric value and how many digits were consumed (`0`
+ * if none were valid).
+ */
+function readHexDigits(source, start, maxDigits) {
+    let digits = '';
+    let index = start;
+    while (digits.length < maxDigits) {
+        const ch = source.charAt(index);
+        if (!isHexDigit(ch))
+            break;
+        digits += ch;
+        index += 1;
+    }
+    return { value: digits.length > 0 ? parseInt(digits, 16) : 0, length: digits.length };
+}
+/**
+ * Greedily consumes up to `maxDigits` octal digits starting at `start`,
+ * returning the parsed numeric value and how many digits were consumed.
+ */
+function readOctalDigits(source, start, maxDigits) {
+    let digits = '';
+    let index = start;
+    while (digits.length < maxDigits) {
+        const ch = source.charAt(index);
+        if (!isOctalDigit(ch))
+            break;
+        digits += ch;
+        index += 1;
+    }
+    return { value: digits.length > 0 ? parseInt(digits, 8) : 0, length: digits.length };
+}
+/**
+ * Decodes the raw inner text of a `$'...'` (ANSI-C quoted) string per Bash
+ * Reference Manual §3.1.2.4, "ANSI-C Quoting". `raw` is the text between
+ * the quotes (mvdan/sh's `SglQuoted.Value` for a `Dollar: true` node),
+ * exactly as it appears in source — not yet interpreted in any way.
+ *
+ * Recognized escapes: `\a \b \e \E \f \n \r \t \v \\ \' \" \?`, octal
+ * `\nnn` (one to three digits), hex `\xHH` (one or two digits), Unicode
+ * `\uHHHH` (one to four digits) and `\UHHHHHHHH` (one to eight digits), and
+ * control-character `\cX`. An unrecognized backslash sequence (not in this
+ * table, and not a recognized numeric escape) is left as-is — Bash's own
+ * decoding is best-effort for malformed input, and this function mirrors
+ * that rather than throwing, matching {@link resolveWord}'s "never throw
+ * for well-formed input" contract at the string level too. A `\u`/`\U`
+ * whose value *is* well-formed but has no corresponding Unicode character
+ * is a different case — see {@link AnsiCDecodeResult}.
+ *
+ * @internal
+ */
+export function decodeAnsiCString(raw) {
+    let text = '';
+    let i = 0;
+    while (i < raw.length) {
+        const ch = raw[i];
+        if (ch !== '\\' || i + 1 >= raw.length) {
+            // `i < raw.length` (the while guard) means indexing here is always
+            // in-bounds and `ch` is a real character, not `undefined`.
+            text += ch;
+            i += 1;
+            continue;
+        }
+        // `i + 1 < raw.length` was just confirmed above, so this index is safe.
+        const next = raw[i + 1];
+        switch (next) {
+            case 'a':
+                text += '\x07';
+                i += 2;
+                break;
+            case 'b':
+                text += '\x08';
+                i += 2;
+                break;
+            case 'e':
+            case 'E':
+                text += '\x1b';
+                i += 2;
+                break;
+            case 'f':
+                text += '\x0c';
+                i += 2;
+                break;
+            case 'n':
+                text += '\n';
+                i += 2;
+                break;
+            case 'r':
+                text += '\r';
+                i += 2;
+                break;
+            case 't':
+                text += '\t';
+                i += 2;
+                break;
+            case 'v':
+                text += '\x0b';
+                i += 2;
+                break;
+            case '\\':
+                text += '\\';
+                i += 2;
+                break;
+            case "'":
+                text += "'";
+                i += 2;
+                break;
+            case '"':
+                text += '"';
+                i += 2;
+                break;
+            case '?':
+                text += '?';
+                i += 2;
+                break;
+            case 'x': {
+                const { value, length } = readHexDigits(raw, i + 2, 2);
+                if (length > 0) {
+                    text += String.fromCharCode(value);
+                    i += 2 + length;
+                }
+                else {
+                    text += ch;
+                    i += 1;
+                }
+                break;
+            }
+            case 'u': {
+                const { value, length } = readHexDigits(raw, i + 2, 4);
+                if (length === 0) {
+                    text += ch;
+                    i += 1;
+                    break;
+                }
+                // `\uHHHH` allows at most 4 hex digits (max 0xFFFF), which can
+                // never exceed MAX_UNICODE_CODE_POINT (0x10FFFF) — this check is
+                // purely defensive, mirroring the `\U` case below, and is
+                // unreachable today (see MAX_UNICODE_CODE_POINT's doc comment).
+                if (value > MAX_UNICODE_CODE_POINT) {
+                    return { ok: false };
+                }
+                text += String.fromCodePoint(value);
+                i += 2 + length;
+                break;
+            }
+            case 'U': {
+                const { value, length } = readHexDigits(raw, i + 2, 8);
+                if (length === 0) {
+                    // Not a recognized numeric escape (no valid hex digit at all):
+                    // leave un-decoded, same as any other unrecognized escape.
+                    text += ch;
+                    i += 1;
+                    break;
+                }
+                if (value > MAX_UNICODE_CODE_POINT) {
+                    // Well-formed 8-digit hex value, but out of Unicode's range (see
+                    // MAX_UNICODE_CODE_POINT's doc comment): bash's real output for
+                    // this case can't be represented as an exact JS string, so this
+                    // is not the same as an "unrecognized escape" — signal failure
+                    // for the whole string rather than claiming a false literal.
+                    return { ok: false };
+                }
+                text += String.fromCodePoint(value);
+                i += 2 + length;
+                break;
+            }
+            case 'c': {
+                const controlChar = raw.charAt(i + 2);
+                if (controlChar !== '') {
+                    // Bash's control-character formula: the char XOR 0x40 (e.g. 'A'
+                    // 0x41 ^ 0x40 = 0x01). See ANSI-C Quoting's "\cx" entry.
+                    const code = (controlChar.toUpperCase().charCodeAt(0) ^ 0x40) & 0xff;
+                    text += String.fromCharCode(code);
+                    i += 3;
+                }
+                else {
+                    text += ch;
+                    i += 1;
+                }
+                break;
+            }
+            default:
+                if (isOctalDigit(next)) {
+                    const { value, length } = readOctalDigits(raw, i + 1, 3);
+                    text += String.fromCharCode(value);
+                    i += 1 + length;
+                }
+                else {
+                    // Not a recognized escape: leave the backslash (and whatever
+                    // follows) untouched, one character at a time.
+                    text += ch;
+                    i += 1;
+                }
+        }
+    }
+    return { ok: true, text };
+}
+//# sourceMappingURL=ansi-c-escapes.js.map

package/dist/analyze/ansi-c-escapes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi-c-escapes.js","sourceRoot":"","sources":["../../src/analyze/ansi-c-escapes.ts"],"names":[],"mappings":"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"}

package/dist/analyze/decode-lit.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Decodes `Lit` word-part text and detects unquoted glob metacharacters.
+ * mvdan/sh's `Lit.Value` is raw source text for ordinary backslash escapes
+ * — a non-quoted backslash and the character it escapes both remain in
+ * `Lit.Value` exactly as written, undecoded (verified empirically; see
+ * `test/analyze-resolve-word.test.ts`) — so this module performs the two
+ * context-dependent decodings Bash itself defines for a `Lit` depending on
+ * whether it is a direct child of a `Word` ("unquoted") or nested inside a
+ * `DblQuoted` ("double-quoted"). The one exception is a backslash-newline
+ * *line continuation*: mvdan/sh's lexer consumes and discards it before
+ * `Lit.Value` is ever populated (verified empirically — parsing
+ * `cmd a\` + newline + `s` yields a `Lit` whose `value` is `"as"`, with no
+ * trace of the backslash or newline), so unlike ordinary escapes it never
+ * reaches this module and there is nothing here left to decode for it.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Escape-Character
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Double-Quotes
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Pattern-Matching
+ * @internal
+ */
+/**
+ * The result of decoding a `Lit` part that is a direct (unquoted) child of
+ * a `Word`.
+ *
+ * @internal
+ */
+export interface UnquotedLitResult {
+    /** The decoded literal text (escapes resolved, glob chars included verbatim). */
+    readonly text: string;
+    /** `true` iff an unescaped `*` or `?` appears in `raw`. */
+    readonly hasGlob: boolean;
+    /**
+     * Every unescaped `[` or `]` in `raw`, concatenated in source order (e.g.
+     * `raw`'s unescaped occurrences in `"a[b]c]"` yield `"[]]"`). A caller
+     * assembling a `Word`'s full bracket-expression classification
+     * concatenates this across all of a word's top-level `Lit` parts, in
+     * part order, then checks for a `[` with a later `]` — see
+     * `resolveWord`'s bracket scan and POSIX 2.13.1 / Bash §3.5.8.1.
+     */
+    readonly brackets: string;
+}
+/**
+ * Decodes a `Lit` part's raw value when it is an unquoted, direct child of
+ * a `Word` (not nested inside `DblQuoted`). Per Bash Reference Manual
+ * §3.1.2.1, "Escape Character": a non-quoted backslash preserves the
+ * literal value of the very next character. (A backslash-newline line
+ * continuation never reaches this function at all — see this module's
+ * doc comment — so there is no such case to handle here.) Escaping a glob
+ * metacharacter or bracket character suppresses its special meaning, so
+ * `hasGlob` and `brackets` only ever reflect *unescaped* occurrences.
+ *
+ * @internal
+ */
+export declare function decodeUnquotedLit(raw: string): UnquotedLitResult;
+/**
+ * Decodes a `Lit` part's raw value when nested inside a `DblQuoted`. Per
+ * Bash Reference Manual §3.1.2.3, "Double Quotes": inside double quotes, a
+ * backslash retains its special meaning only when followed by `$`, `` ` ``,
+ * `"`, `\`, or newline; any other backslash is preserved literally (both
+ * the backslash and the following character remain in the result). (As
+ * with {@link decodeUnquotedLit}, a backslash-newline line continuation
+ * never reaches this function — mvdan/sh's lexer strips it before
+ * `Lit.Value` is populated even inside double quotes, verified empirically:
+ * parsing `"a\` + newline + `b"` yields two sibling `Lit` nodes, `"a"` and
+ * `"b"`, with no `Lit` ever containing the backslash or newline — so there
+ * is no such case for this function to decode.) Quoting always suppresses
+ * pattern matching (Filename Expansion never applies to quoted text), so
+ * double-quoted `Lit` text never contributes to a word's glob
+ * classification — this function has no `hasGlob` output.
+ *
+ * @internal
+ */
+export declare function decodeDblQuotedLit(raw: string): string;
+//# sourceMappingURL=decode-lit.d.ts.map

package/dist/analyze/decode-lit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-lit.d.ts","sourceRoot":"","sources":["../../src/analyze/decode-lit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAmBH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAuBhE;AAKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqBtD"}

package/dist/analyze/decode-lit.js

@@ -0,0 +1,114 @@
+/**
+ * Decodes `Lit` word-part text and detects unquoted glob metacharacters.
+ * mvdan/sh's `Lit.Value` is raw source text for ordinary backslash escapes
+ * — a non-quoted backslash and the character it escapes both remain in
+ * `Lit.Value` exactly as written, undecoded (verified empirically; see
+ * `test/analyze-resolve-word.test.ts`) — so this module performs the two
+ * context-dependent decodings Bash itself defines for a `Lit` depending on
+ * whether it is a direct child of a `Word` ("unquoted") or nested inside a
+ * `DblQuoted` ("double-quoted"). The one exception is a backslash-newline
+ * *line continuation*: mvdan/sh's lexer consumes and discards it before
+ * `Lit.Value` is ever populated (verified empirically — parsing
+ * `cmd a\` + newline + `s` yields a `Lit` whose `value` is `"as"`, with no
+ * trace of the backslash or newline), so unlike ordinary escapes it never
+ * reaches this module and there is nothing here left to decode for it.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Escape-Character
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Double-Quotes
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Pattern-Matching
+ * @internal
+ */
+/**
+ * Unquoted glob metacharacters this module detects directly, by a single
+ * unescaped occurrence: `*` (any string) and `?` (any single character) —
+ * Bash Reference Manual §3.5.8.1, "Pattern Matching". Bracket expressions
+ * (`[...]`) are handled separately by {@link decodeUnquotedLit}'s
+ * `brackets` output, since — per POSIX 2.13.1 and Bash §3.5.8.1 — a lone
+ * unquoted `[` is only glob-significant when a later unquoted `]` closes
+ * it (`a[bc` with no closing bracket is a *literal* filename in Bash,
+ * while `a[bc]` is a pattern), and that closing `]` may live in a
+ * different, concatenated `Lit` part of the same `Word` (see
+ * `resolveWord`'s cross-part bracket scan).
+ */
+const GLOB_METACHARACTERS = new Set(['*', '?']);
+/** The two characters {@link decodeUnquotedLit} tracks for cross-part bracket-expression detection. */
+const BRACKET_CHARACTERS = new Set(['[', ']']);
+/**
+ * Decodes a `Lit` part's raw value when it is an unquoted, direct child of
+ * a `Word` (not nested inside `DblQuoted`). Per Bash Reference Manual
+ * §3.1.2.1, "Escape Character": a non-quoted backslash preserves the
+ * literal value of the very next character. (A backslash-newline line
+ * continuation never reaches this function at all — see this module's
+ * doc comment — so there is no such case to handle here.) Escaping a glob
+ * metacharacter or bracket character suppresses its special meaning, so
+ * `hasGlob` and `brackets` only ever reflect *unescaped* occurrences.
+ *
+ * @internal
+ */
+export function decodeUnquotedLit(raw) {
+    let text = '';
+    let hasGlob = false;
+    let brackets = '';
+    let i = 0;
+    while (i < raw.length) {
+        const ch = raw[i];
+        if (ch === '\\' && i + 1 < raw.length) {
+            const next = raw[i + 1];
+            text += next;
+            i += 2;
+            continue;
+        }
+        if (GLOB_METACHARACTERS.has(ch)) {
+            hasGlob = true;
+        }
+        if (BRACKET_CHARACTERS.has(ch)) {
+            brackets += ch;
+        }
+        text += ch;
+        i += 1;
+    }
+    return { text, hasGlob, brackets };
+}
+/** Characters after which a backslash retains special meaning inside double quotes. */
+const DBLQUOTED_ESCAPABLE = new Set(['$', '`', '"', '\\']);
+/**
+ * Decodes a `Lit` part's raw value when nested inside a `DblQuoted`. Per
+ * Bash Reference Manual §3.1.2.3, "Double Quotes": inside double quotes, a
+ * backslash retains its special meaning only when followed by `$`, `` ` ``,
+ * `"`, `\`, or newline; any other backslash is preserved literally (both
+ * the backslash and the following character remain in the result). (As
+ * with {@link decodeUnquotedLit}, a backslash-newline line continuation
+ * never reaches this function — mvdan/sh's lexer strips it before
+ * `Lit.Value` is populated even inside double quotes, verified empirically:
+ * parsing `"a\` + newline + `b"` yields two sibling `Lit` nodes, `"a"` and
+ * `"b"`, with no `Lit` ever containing the backslash or newline — so there
+ * is no such case for this function to decode.) Quoting always suppresses
+ * pattern matching (Filename Expansion never applies to quoted text), so
+ * double-quoted `Lit` text never contributes to a word's glob
+ * classification — this function has no `hasGlob` output.
+ *
+ * @internal
+ */
+export function decodeDblQuotedLit(raw) {
+    let text = '';
+    let i = 0;
+    while (i < raw.length) {
+        const ch = raw[i];
+        if (ch === '\\' && i + 1 < raw.length) {
+            const next = raw[i + 1];
+            if (DBLQUOTED_ESCAPABLE.has(next)) {
+                text += next;
+                i += 2;
+                continue;
+            }
+            // Not one of the escapable characters: the backslash stays literal.
+            text += ch;
+            i += 1;
+            continue;
+        }
+        text += ch;
+        i += 1;
+    }
+    return text;
+}
+//# sourceMappingURL=decode-lit.js.map