Initial commit

Author: webpro

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+      - run: pnpm run build

.gitignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+playground/parser.js

.oxfmtrc.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 120
+}

LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) Lars Kappert
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -0,0 +1,104 @@
+# unbash
+
+Fast 0-deps bash parser written in TypeScript
+
+## Install
+
+```sh
+npm install unbash
+```
+
+## Usage
+
+```ts
+import { parse } from "unbash";
+
+const ast = parse('if [ -f "$1" ]; then cat "$1"; fi');
+```
+
+```js
+// Result:
+{
+  type: "Script",
+  commands: [{
+    type: "If",
+    clause: { type: "Command", name: { text: "[" }, ... },
+    then: { type: "Command", name: { text: "cat" }, ... }
+  }]
+}
+```
+
+## unbash vs tree-sitter-bash
+
+[tree-sitter-bash][1] is an excellent choice if you need:
+
+- Incremental parsing
+- CST output preserving all tokens and punctuation
+- Granular error recovery that wraps errors in `ERROR` nodes and continues parsing
+
+unbash might be a good fit if you prefer:
+
+- AST output
+- A zero-dependency dependendency that runs in any JS environment
+- A typed TypeScript API
+- Built-in parsing for command/process substitutions, coproc, Bash 5.3 `${ cmd; }`, `[[ ]]`, `(( ))`, and extglob
+- Error recovery that collects errors instead of throwing
+
+## unbash vs sh-syntax
+
+[sh-syntax][2] is a WASM wrapper around the robust [mvdan/sh][3] Go parser. It is highly recommended if you need:
+
+- Support for multiple shell dialects (bash, POSIX sh, mksh, Bats)
+- Built-in formatting and pretty-printing (`print`)
+
+unbash might be a good fit if you prefer:
+
+- A zero-dependency, synchronous API
+- A detailed AST with structured word parts, parameter expansions, arithmetic expressions, and test expressions
+
+## unbash vs bash-parser
+
+[bash-parser][4] (last publish: 2017) and its fork [@ericcornelissen/bash-parser][5] (community dependency maintenance fork ❤️ now archived) might be interesting if you need:
+
+- A POSIX-only mode that rejects bash-specific syntax
+
+unbash might be a good fit if you prefer:
+
+- A zero-dependency architecture
+- A typed TypeScript API (ESM-only)
+- Error recovery that collects errors instead of throwing
+- Structured AST nodes for parameter expansions, arithmetic expressions, and `[[ ]]` test expressions
+- Support for many additional syntax features (like herestrings, C-style for loops, `select`, process substitution, etc. etc.)
+
+## Benchmarks
+
+Relative performance comparison (on Apple M1 Pro/32GB), unbash is x times faster:
+
+| Parser                       | short | advanced | medium | large |
+| ---------------------------- | ----: | -------: | -----: | ----: |
+| tree-sitter-bash (native)    |   14x |       9x |     4x |    4x |
+| tree-sitter-bash (WASM)      |   14x |      10x |     7x |    7x |
+| sh-syntax                    | 2008x |    1296x |     7x |    4x |
+| bash-parser                  |  230x |      N/A |    N/A |   N/A |
+| @ericcornelissen/bash-parser |  247x |      N/A |    N/A |   N/A |
+
+Run the benchmarks using Node.js v22 or v24:
+
+```sh
+pnpm install
+node bench/all.ts
+```
+
+## Size
+
+unbash is under 50K minified, 12KB gzipped.
+
+## License
+
+ISC
+
+[1]: https://github.com/tree-sitter/tree-sitter-bash
+[2]: https://github.com/un-ts/sh-syntax
+[3]: https://github.com/mvdan/sh
+[4]: https://github.com/vorpaljs/bash-parser
+[5]: https://github.com/ericcornelissen/bash-parser

bench/all.ts

@@ -0,0 +1,89 @@
+import { parse } from "../src/parser.ts";
+import { join } from "node:path";
+import { bench, group, run, summary } from "mitata";
+import { short, advanced, installers, large } from "./fixtures.ts";
+
+type ParseFn = (s: string) => unknown;
+type Parser = { name: string; parse: ParseFn; limited?: boolean };
+
+const parsers: Parser[] = [];
+
+try {
+  // @ts-ignore — CJS default export
+  const bashParser = (await import("bash-parser")).default;
+  parsers.push({ name: "bash-parser", parse: bashParser, limited: true });
+} catch {
+  console.warn("Error adding bash-parser");
+}
+
+try {
+  // @ts-ignore — CJS default export
+  const ecBashParser = (await import("@ericcornelissen/bash-parser")).default;
+  parsers.push({ name: "@ericcornelissen/bash-parser", parse: ecBashParser, limited: true });
+} catch {
+  console.warn("Error adding @ericcornelissen/bash-parser");
+}
+
+try {
+  // @ts-ignore
+  const NativeParser = (await import("tree-sitter")).default;
+  const tsbNative = new NativeParser();
+  tsbNative.setLanguage((await import("tree-sitter-bash")).default as never);
+  parsers.push({ name: "tree-sitter (native)", parse: tsbNative.parse.bind(tsbNative) });
+} catch {
+  console.warn("Error adding tree-sitter-bash");
+}
+
+try {
+  // @ts-ignore
+  const { Language, Parser: WasmParser } = await import("web-tree-sitter");
+  await WasmParser.init();
+  const lang = await Language.load(join(import.meta.dirname, "../node_modules/tree-sitter-bash/tree-sitter-bash.wasm"));
+  const tsbWasm = new WasmParser();
+  tsbWasm.setLanguage(lang);
+  parsers.push({ name: "tree-sitter (WASM)", parse: tsbWasm.parse.bind(tsbWasm) });
+} catch {
+  console.warn("Error adding tree-sitter-bash.wasm");
+}
+
+type AsyncParser = { name: string; parse: (s: string) => Promise<unknown> };
+const asyncParsers: AsyncParser[] = [];
+
+try {
+  const { parse: shSyntaxParse } = await import("sh-syntax");
+  await shSyntaxParse("echo hello"); // warm up WASM
+  asyncParsers.push({ name: "sh-syntax", parse: shSyntaxParse });
+} catch {
+  console.warn("Error adding sh-syntax");
+}
+
+for (const [label, scripts] of [
+  ["short", short],
+  ["advanced", advanced],
+  ["medium", installers],
+  ["large", large],
+] as const) {
+  group(label, () => {
+    summary(() => {
+      bench("unbash", () => {
+        for (const script of scripts) parse(script);
+      }).baseline();
+
+      for (const parser of parsers) {
+        if (/advanced|medium|large/.test(label) && parser.name.includes("bash-parser")) continue;
+
+        bench(parser.name, () => {
+          for (const script of scripts) parser.parse(script);
+        });
+      }
+
+      for (const parser of asyncParsers) {
+        bench(parser.name, async () => {
+          for (const script of scripts) await parser.parse(script);
+        });
+      }
+    });
+  });
+}
+
+await run();

bench/fixtures.ts

@@ -0,0 +1,77 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const fixturesDir = join(import.meta.dirname, "../fixtures");
+
+const readFixture = (name: string) => readFileSync(join(fixturesDir, "bench", name), "utf8");
+
+function readDir(subdir: string, ext: string): string[] {
+  const dir = join(fixturesDir, subdir);
+  const out: string[] = [];
+  try {
+    for (const f of readdirSync(dir)) {
+      if (f.endsWith(ext)) out.push(readFileSync(join(dir, f), "utf8"));
+    }
+  } catch {}
+  return out;
+}
+
+export const short = [
+  "echo hello",
+  "program -short --long args",
+  "npm run script",
+  "pnpm install",
+  "node script.js",
+  "tsx ./main.ts",
+  "bun test",
+  "eslint .",
+  "program -x && exec -y -- program2 -z",
+  "cross-env NODE_ENV=production node -r pkg/config ./script.js",
+  "dotenv -e .env3 -v VARIABLE=somevalue -- program",
+  "npx --package @scope/pkg@0.6.0 --package pkg -- curl",
+  "pnpm --silent run program script.js",
+  "c8 --reporter=lcov --reporter text node --test --test-reporter=@org/rep",
+  "NODE_ENV=production cross-env -- program --cache",
+  "yarn --cwd components vitest -c vitest.components.config.ts",
+  "changeset version && node ./scripts/deps/update-example-versions.js && pnpm install --no-frozen-lockfile && pnpm run format",
+  'turbo run build --filter=astro --filter=create-astro --filter="@astrojs/*"',
+  "biome ci --formatter-enabled=false --enforce-assist=false --reporter=github && eslint . --concurrency=auto && knip",
+  'if test "$NODE_ENV" = "production" ; then make install ; fi',
+  'f() { vite build "$@" || (echo content; exit 1;) }; f',
+  "var=$(node ./script.js)",
+  "var=`node ./script.js`;var=`node ./require.js`",
+  '#!/bin/sh\n. "$(dirname "$0")/_/husky.sh"\nnpx lint-staged',
+  'for S in "s"; do\n\tnpx rc@0.6.0\n\tnpx @scope/rc@0.6.0\ndone',
+  "NODE_OPTIONS='--require pkg-a --require pkg-b' program",
+];
+
+export const advanced = [
+  "for (( c=1; c<=5; c++ )); do echo $c; done",
+  "select i in 1 2 3; do echo $i; done",
+  '[[ "$lsb_dist" != "Ubuntu" || "$ver" < "14.04" ]]',
+  "case a in a) echo A ;& *) echo star ;; esac",
+  'echo $"hello world"',
+  'declare -A map\nmap[key]="value"\necho "${map[key]}"',
+  'if [[ $(cat $file) =~ $regex ]]; then\n    version="${BASH_REMATCH[1]}"\nfi',
+  "node --maxWorkers=\"$(node -e 'process.stdout.write(os.cpus().length.toString())')\"",
+  '[ "$CF_PAGES" = "1" ] && find dist -mindepth 2 -type f -name \'index.html\' -exec bash -c \'f="$1"; d=$(dirname "$f"); bn=$(basename "$d"); mv -v "$f" "$d/../$bn.html"\' _ {} \\; || true',
+  'caddy run --config - <<< \'{"apps":{"http":{"servers":{"srv0":{"listen":[":8003"]}}}}}\'',
+  'pnpm exec "cat package.json | jq -r \'\\\"\\\\(.name)@\\\\(.version)\\\"\'" | sort',
+  "echo data | tee >(grep pattern > matches.txt) >(wc -l > count.txt) > /dev/null",
+  "wc -c <(echo abc && echo def)",
+  'case "$Z" in\n  ab*|cd*) ef ;;\nesac',
+];
+
+export const installers = readDir("installers", ".sh");
+
+export const large = readDir("large", ".sh");
+
+export const specialized: [string, string[]][] = [
+  ["word-parts", [readFixture("word-parts.sh")]],
+  ["param-expansion", [readFixture("param-expansion.sh")]],
+  ["arithmetic", [readFixture("arithmetic.sh")]],
+  ["test-expressions", [readFixture("test-expressions.sh")]],
+  ["heredoc-expansion", [readFixture("heredoc-expansion.sh")]],
+  ["assignments", [readFixture("assignments.sh")]],
+  ["dedicated-nodes", [readFixture("dedicated-nodes.sh")]],
+];

bench/self.ts

@@ -0,0 +1,19 @@
+import { parse } from "../src/parser.ts";
+import { bench, group, run } from "mitata";
+import { short, advanced, specialized, installers, large } from "./fixtures.ts";
+
+for (const [label, scripts] of [
+  ["short", short],
+  ["advanced", advanced],
+  ...specialized,
+  ["medium", installers],
+  ["large", large],
+] as const) {
+  group(label, () => {
+    bench(label, () => {
+      for (const s of scripts) parse(s);
+    });
+  });
+}
+
+await run();