@binclusive/tree-sitter-kotlin-wasm

The tree-sitter Kotlin grammar vendored as a checksum-pinned .wasm asset, with zero runtime dependencies and no install script.

Upstream is on npm, and we depended on it directly until #3834. Doing so cost 45 MB installed and an install: node-gyp-build lifecycle script, to load one 3.3 MB file — the other 41 MB is generated C parser source, native .node bindings for six platforms we never open, and npm-check-updates, a developer tool declared as a runtime dependency. This package republishes only the wasm, unmodified. Full provenance, the reproduce command and the upgrade procedure are in PROVENANCE.md.

The sibling @binclusive/tree-sitter-swift-wasm is the same shape for Swift. Both grammars now reach a customer the same way — a first-party vendored-wasm package resolved by name — so the Kotlin/Swift difference is a dependency name rather than a second acquisition mechanism.

Install

Pin it exactly. The grammar version decides what the scanner can see, so it is a correctness input, not a compatible-upgrade axis (#3828, #3931):

pnpm add -E @binclusive/tree-sitter-kotlin-wasm

Use

import { readFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
import {
  KOTLIN_GRAMMAR,
  KOTLIN_GRAMMAR_WASM_SPECIFIER,
} from "@binclusive/tree-sitter-kotlin-wasm";
import { Language, Parser } from "web-tree-sitter";

const wasmPath = fileURLToPath(import.meta.resolve(KOTLIN_GRAMMAR_WASM_SPECIFIER));

// Verify before you parse: a wrong or truncated grammar under-parses SILENTLY, so it
// surfaces as missing findings rather than an error.
const bytes = await readFile(wasmPath);
const digest = Buffer.from(
  await crypto.subtle.digest("SHA-256", bytes),
).toString("hex");
if (digest !== KOTLIN_GRAMMAR.sha256) throw new Error("Kotlin grammar digest mismatch");

await Parser.init();
const parser = new Parser();
parser.setLanguage(await Language.load(bytes));

import.meta.resolve is the load-bearing detail: resolution runs through this package's exports map by name. A directory join off the consumer's import.meta.url is the exact mechanism behind #3120 — it resolves on the machine that built the image and nowhere else.

Identify the language from KOTLIN_GRAMMAR, not from the loaded module: this grammar is ABI 14, which predates grammar name metadata, so Language.name reads null.

Exports

The entry point is constants only — no node: imports, no runtime dependency — so it loads on Node, Workers and the browser alike.

Publishing

The workspace tests verify the committed bytes; verify:tarball verifies the artifact a customer actually receives. It packs, installs the tarball into a throwaway directory outside this repo with --ignore-scripts, resolves the wasm by package name from that install and parses Kotlin with it — so a broken files list, a publishConfig exports map or a newly-grown lifecycle script fails here rather than at a consumer:

pnpm -C packages/tree-sitter-kotlin-wasm run verify:tarball

(pnpm -C … run, never pnpm --filter … <script> — the latter exits 0 when the script is missing, #3839.)

Then publish the tarball (this workspace publishes packed tarballs rather than running pnpm publish in place):

cd packages/tree-sitter-kotlin-wasm
pnpm build
pnpm pack
npm publish --access public binclusive-tree-sitter-kotlin-wasm-<version>.tgz

Licence

The grammar is MIT, © 2024 Amaan Qureshi. The upstream notice ships verbatim in LICENSE and applies to the vendored wasm, which is the unmodified upstream artifact. This package adds no separately-licensed code.