Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

Vendor tree-sitter-swift: npm i -g with no warnings (#670)

anirudhkumar-nanonets89248a9dec89
diff --git a/.trail/learnings/2026-10-22-npm-install-g-peer-warnings-tree-anirudhkumar.md b/.trail/learnings/2026-10-22-npm-install-g-peer-warnings-tree-anirudhkumar.md
new file mode 100644
index 00000000..f5900e95
--- /dev/null
+++ b/.trail/learnings/2026-10-22-npm-install-g-peer-warnings-tree-anirudhkumar.md
@@ -0,0 +1,29 @@
+---
+title: "npm install -g peer warnings: tree-sitter-swift is vendored now"
+author: Anirudhkumar-nanonets
+date: 2026-10-22
+branch: fix/tree-sitter-swift-peer
+touches:
+ - package-lock.json
+ - package.json
+ - src/graph/native.ts
+ - test/graph-native-fallback.test.ts
+ - scripts/vendor-grammars.mjs
+ - test/package-peers.test.ts
+---
+
+## Decided
+- `npm i -g` printed a 21-line "ERESOLVE overriding peer dependency" block: tree-sitter-swift 0.7.1 asks for tree-sitter ^0.22.1, we ship 0.21.1. The repo's `overrides` hid it locally; npm applies overrides only to the project it runs in, never to people installing the package.
+- Fix: tree-sitter-swift is a devDependency. `npm run build` runs scripts/vendor-grammars.mjs, which copies its six prebuilt binaries, node-types.json and LICENSE into dist/vendor/tree-sitter-swift/. native.ts `requireGrammar` loads from there, and from node_modules when running from src/. A packed tarball's global install prints 0 npm warnings and is ~73 MB smaller (no tree-sitter-swift src, no tree-sitter-cli).
+- test/package-peers.test.ts fails when any dependency's tree-sitter peer doesn't accept the tree-sitter we ship.
+
+## Tried and ruled out
+- tree-sitter 0.22: go, java, kotlin, php, r and typescript all peer ^0.21, and npm warns on mismatched optional peers too. A real global install went from 21 to 106-127 warning lines. kotlin's latest (0.3.8) still wants ^0.21.
+- tree-sitter-swift 0.6.0 (peer ^0.21.1): its binding.gyp waits on a nested node_modules/tree-sitter-cli and fails to compile in a hoisted install.
+- Publishing a fork with a wider peer range: needs @trailhq npm publish rights; vendoring needs none.
+- Testing with `npm install --package-lock-only` into a root project: it doesn't print the peer warning. Only a real `npm i -g --prefix <scratch> <tarball>` reproduces it.
+
+## Watch out
+- On a platform with no Swift prebuild (Alpine/musl, FreeBSD), Swift files go to the WASM breadth tier, and the fallback notice names no package for Swift, since no install flag would help.
+- To bump tree-sitter-swift: bump the devDependency, rebuild, and check the global install from a packed tarball.
+- The funding line on `npm i -g` comes from dotenv's `funding` field; only the installer's own npm config can hide it.
diff --git a/package-lock.json b/package-lock.json
index bb621325..8fac235b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -22,7 +22,6 @@
"tree-sitter-php": "^0.23.4",
"tree-sitter-python": "^0.21.0",
"tree-sitter-r": "npm:@davisvaughan/tree-sitter-r@^1.3.0",
- "tree-sitter-swift": "^0.7.1",
"tree-sitter-typescript": "^0.23.2",
"tree-sitter-wasm": "^2.0.4",
"vscode-jsonrpc": "^8.2.1",
@@ -38,6 +37,7 @@
"d3-force": "^3.0.0",
"esbuild": "^0.28.1",
"node-gyp": "^12.4.0",
+ "tree-sitter-swift": "^0.7.1",
"tsx": "^4.22.4",
"typescript": "^6.0.3"
},
@@ -1085,6 +1085,7 @@
"version": "0.23.2",
"resolved": "https://registry.npmjs.org/tree-sitter-cli/-/tree-sitter-cli-0.23.2.tgz",
"integrity": "sha512-kPPXprOqREX+C/FgUp2Qpt9jd0vSwn+hOgjzVv/7hapdoWpa+VeWId53rf4oNNd29ikheF12BYtGD/W90feMbA==",
+ "dev": true,
"hasInstallScript": true,
"license": "MIT",
"bin": {
@@ -1244,6 +1245,7 @@
"version": "0.7.1",
"resolved": "https://registry.npmjs.org/tree-sitter-swift/-/tree-sitter-swift-0.7.1.tgz",
"integrity": "sha512-pneKVTuGamaBsqqqfB9BvNQjktzh/0IVPR54jLB5Fq/JTDQwYHd0Wo6pVyZ5jAYpbztzq+rJ/rpL9ruxTmSoKw==",
+ "dev": true,
"hasInstallScript": true,
"license": "MIT",
"dependencies": {
@@ -1265,12 +1267,14 @@
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
"integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+ "dev": true,
"license": "ISC"
},
"node_modules/tree-sitter-swift/node_modules/which": {
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
"integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+ "dev": true,
"license": "ISC",
"dependencies": {
"isexe": "^2.0.0"
diff --git a/package.json b/package.json
index 24e85383..7d1ecfcf 100644
--- a/package.json
+++ b/package.json
@@ -43,7 +43,7 @@
"LICENSE"
],
"scripts": {
- "build": "tsc -p tsconfig.json && tsc -p viewer/tsconfig.json && node scripts/build-viewer.mjs",
+ "build": "tsc -p tsconfig.json && tsc -p viewer/tsconfig.json && node scripts/build-viewer.mjs && node scripts/vendor-grammars.mjs",
"dev": "tsc -p tsconfig.json --watch",
"cli": "tsx src/cli.ts",
"test": "node scripts/run-tests.mjs",
@@ -67,7 +67,6 @@
"tree-sitter-php": "^0.23.4",
"tree-sitter-python": "^0.21.0",
"tree-sitter-r": "npm:@davisvaughan/tree-sitter-r@^1.3.0",
- "tree-sitter-swift": "^0.7.1",
"tree-sitter-typescript": "^0.23.2",
"tree-sitter-wasm": "^2.0.4",
"vscode-jsonrpc": "^8.2.1",
@@ -80,6 +79,7 @@
"d3-force": "^3.0.0",
"esbuild": "^0.28.1",
"node-gyp": "^12.4.0",
+ "tree-sitter-swift": "^0.7.1",
"tsx": "^4.22.4",
"typescript": "^6.0.3"
},
diff --git a/scripts/vendor-grammars.mjs b/scripts/vendor-grammars.mjs
new file mode 100644
index 00000000..07b566b7
--- /dev/null
+++ b/scripts/vendor-grammars.mjs
@@ -0,0 +1,35 @@
+/**
+ * Copies the grammars the package ships itself into dist/vendor/. Runs as part
+ * of `npm run build`; native.ts loads them from there.
+ *
+ * tree-sitter-swift is a dev dependency only: it asks for tree-sitter ^0.22
+ * while every other grammar asks for ^0.21, so as a dependency it made every
+ * `npm install -g` print a wall of ERESOLVE peer warnings. What it ships is a
+ * prebuilt binary per platform plus node-types.json, and that is all native.ts
+ * needs. Its MIT license comes along.
+ *
+ * Usage: node scripts/vendor-grammars.mjs [outDir] (default dist/vendor)
+ */
+import { copyFileSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const outDir = resolve(process.argv[2] ?? join(root, "dist", "vendor"));
+const require = createRequire(join(root, "package.json"));
+
+for (const id of ["tree-sitter-swift"]) {
+ const pkg = dirname(require.resolve(`${id}/package.json`));
+ const { version } = require(`${id}/package.json`);
+ const out = join(outDir, id);
+ rmSync(out, { recursive: true, force: true });
+ const platforms = readdirSync(join(pkg, "prebuilds"));
+ for (const platform of platforms) {
+ mkdirSync(join(out, "prebuilds", platform), { recursive: true });
+ copyFileSync(join(pkg, "prebuilds", platform, `${id}.node`), join(out, "prebuilds", platform, `${id}.node`));
+ }
+ copyFileSync(join(pkg, "src", "node-types.json"), join(out, "node-types.json"));
+ copyFileSync(join(pkg, "LICENSE"), join(out, "LICENSE"));
+ console.log(`vendored grammar → ${id}@${version} (${platforms.length} platforms)`);
+}
diff --git a/src/graph/native.ts b/src/graph/native.ts
index 32ac41a1..8b26a43d 100644
--- a/src/graph/native.ts
+++ b/src/graph/native.ts
@@ -16,12 +16,37 @@
* breadth tier instead (`fallbackLangOf` in generic.ts), and the build says which
* languages and how to get the native parser back ({@link nativeFallbackNotice}).
*/
+import { existsSync } from "node:fs";
import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
import type Parser from "tree-sitter";
import type { Language } from "./extract.js";
const nodeRequire = createRequire(import.meta.url);
+/**
+ * Grammars the build copies into dist/vendor/ (scripts/vendor-grammars.mjs)
+ * instead of the package depending on them. tree-sitter-swift asks for
+ * tree-sitter ^0.22 while every other grammar asks for ^0.21, so as a dependency
+ * it made every `npm install -g` print a wall of peer warnings. Its prebuilt
+ * binaries cover all six desktop platforms; anywhere else the require fails and
+ * Swift goes to its WASM stand-in like any missing grammar. Run from src/, there
+ * is no dist/vendor/ and the dev dependency stands in.
+ */
+const VENDORED = new Set(["tree-sitter-swift"]);
+const VENDOR_DIR = fileURLToPath(new URL("../vendor/", import.meta.url));
+
+/** `id` from `vendorDir` when the build put it there, else from node_modules. */
+export function requireGrammar(id: string, vendorDir = VENDOR_DIR): unknown {
+ const dir = join(vendorDir, id);
+ if (!VENDORED.has(id) || !existsSync(dir)) return nodeRequire(id);
+ const grammar = nodeRequire(join(dir, "prebuilds", `${process.platform}-${process.arch}`, `${id}.node`)) as Record<string, unknown>;
+ // What the package's own bindings/node/index.js adds to the binding.
+ grammar.nodeTypeInfo = nodeRequire(join(dir, "node-types.json"));
+ return grammar;
+}
+
const CORE = "tree-sitter";
/** The module each depth-tier grammar comes from, and the export that is the
@@ -47,7 +72,7 @@ const NPM_NAME: Record<string, string> = {
type Loaded = { ok: true; value: unknown } | { ok: false; error: string };
-let requireModule: (id: string) => unknown = (id) => nodeRequire(id);
+let requireModule: (id: string) => unknown = (id) => requireGrammar(id);
const modules = new Map<string, Loaded>();
const ready = new Map<Language, boolean>();
/** undefined: not tried yet. null: tried, and the core binding is unusable. */
@@ -143,7 +168,8 @@ export function missingNativePackages(langs: Iterable<Language>): string[] {
if (nativeReady(lang)) continue;
for (const id of [CORE, GRAMMAR_MODULES[lang].module]) {
const m = modules.get(id);
- if (m && !m.ok) out.add(NPM_NAME[id] ?? id);
+ // A vendored grammar has no install script for a flag to allow.
+ if (m && !m.ok && !VENDORED.has(id)) out.add(NPM_NAME[id] ?? id);
}
}
return [...out].sort();
@@ -175,7 +201,7 @@ export function nativeFallbackNotice(fallback: NativeFallback | undefined, packa
* `require`), and forget everything loaded so far. A missing binary is simulated by
* a function that throws for that module id, the way node-gyp-build does. */
export function setNativeRequireForTest(fn: ((id: string) => unknown) | null): void {
- requireModule = fn ?? ((id) => nodeRequire(id));
+ requireModule = fn ?? ((id) => requireGrammar(id));
modules.clear();
ready.clear();
parser = undefined;
@@ -183,5 +209,5 @@ export function setNativeRequireForTest(fn: ((id: string) => unknown) | null): v
/** The real `require` the seam above wraps, for a test's pass-through. */
export function realNativeRequire(id: string): unknown {
- return nodeRequire(id);
+ return requireGrammar(id);
}
diff --git a/test/graph-native-fallback.test.ts b/test/graph-native-fallback.test.ts
index b5b540dd..824c117c 100644
--- a/test/graph-native-fallback.test.ts
+++ b/test/graph-native-fallback.test.ts
@@ -12,15 +12,20 @@
*/
import { afterEach, test } from "node:test";
import assert from "node:assert/strict";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
import { buildGraph } from "../src/graph/build.js";
import { checkGraph } from "../src/graph/check.js";
+import { extractFile } from "../src/graph/extract.js";
import {
missingNativePackages,
nativeFallbackNotice,
nativeReady,
realNativeRequire,
+ requireGrammar,
setNativeRequireForTest,
} from "../src/graph/native.js";
import { tmpRepo } from "./helpers.js";
@@ -44,6 +49,8 @@ const KOTLIN = [
const PY = ["class Store:", " def load(self):", " return fetch()", "", "def fetch():", " return 1", ""].join("\n");
+const SWIFT = ["class Greeter {", " func greet() -> String { return helper() }", "}", "", 'func helper() -> String { return "hi" }', ""].join("\n");
+
const TS = ["export function add(a: number, b: number): number {", " return a + b;", "}", "export function twice(a: number): number {", " return add(a, a);", "}", ""].join("\n");
function repo(): string {
@@ -183,3 +190,24 @@ test("a .vue file's script falls back with its language, spans still on the .vue
assert.ok(shout, "the script's function is still indexed");
assert.equal(shout.span, "L6-L8");
});
+
+test("the vendored Swift grammar parses exactly like the package it is copied from", () => {
+ const out = mkdtempSync(join(tmpdir(), "vendor-"));
+ const script = join(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "vendor-grammars.mjs");
+ const run = spawnSync(process.execPath, [script, out], { encoding: "utf8" });
+ assert.equal(run.status, 0, run.stderr);
+
+ setNativeRequireForTest(null);
+ const fromPackage = extractFile("app/Greeter.swift", SWIFT, "swift");
+ setNativeRequireForTest((id) => (id === "tree-sitter-swift" ? requireGrammar(id, out) : realNativeRequire(id)));
+ const fromVendor = extractFile("app/Greeter.swift", SWIFT, "swift");
+ assert.ok(nativeReady("swift"), "the vendored binary loads");
+ assert.deepEqual(fromVendor, fromPackage);
+ assert.ok(fromVendor.nodes.some((n) => n.name === "Greeter" && n.origin === "ast"), "parsed on the native tier");
+});
+
+test("a vendored grammar that won't load names no install flag, since none would fix it", () => {
+ setNativeRequireForTest(failing(["tree-sitter-swift"]));
+ assert.equal(nativeReady("swift"), false);
+ assert.deepEqual(missingNativePackages(["swift"]), []);
+});
diff --git a/test/package-peers.test.ts b/test/package-peers.test.ts
new file mode 100644
index 00000000..0197b275
--- /dev/null
+++ b/test/package-peers.test.ts
@@ -0,0 +1,51 @@
+/**
+ * Every grammar the package depends on accepts the tree-sitter it ships.
+ *
+ * One that doesn't makes every `npm install -g` print a wall of "ERESOLVE
+ * overriding peer dependency" warnings. The repo's own `overrides` hide it here,
+ * because npm applies overrides only to the project it is run in, never to the
+ * people installing the package. tree-sitter-swift was that grammar (it asks for
+ * ^0.22); it is vendored into dist/ now (scripts/vendor-grammars.mjs).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+type Manifest = { version: string; dependencies: Record<string, string>; peerDependencies?: Record<string, string> };
+/** A package's package.json, read from disk: some packages' `exports` don't let `require` reach it. */
+const manifest = (dir: string): Manifest => JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+const pkg = manifest(root);
+
+/** `version` satisfies `range`, for the plain `^x.y.z` ranges grammars use, joined by `||`. */
+function satisfies(version: string, range: string): boolean {
+ const [maj, min, pat] = version.split(".").map(Number);
+ return range.split("||").some((part) => {
+ const m = /^\s*\^(\d+)\.(\d+)\.(\d+)\s*$/.exec(part);
+ assert.ok(m, `peer range "${part.trim()}" is not a ^x.y.z range; teach this test to read it`);
+ const [a, b, c] = m.slice(1).map(Number);
+ if (a !== maj) return false;
+ if (a > 0) return min! > b! || (min === b && pat! >= c!);
+ return min === b && pat! >= c!;
+ });
+}
+
+test("every dependency's tree-sitter peer accepts the tree-sitter the package ships", () => {
+ const shipped = manifest(join(root, "node_modules", "tree-sitter")).version;
+ const clashes: string[] = [];
+ for (const name of Object.keys(pkg.dependencies)) {
+ const want = manifest(join(root, "node_modules", name)).peerDependencies?.["tree-sitter"];
+ if (want && !satisfies(shipped, want)) clashes.push(`${name} wants tree-sitter ${want}`);
+ }
+ assert.deepEqual(clashes, [], `tree-sitter ${shipped} ships`);
+});
+
+test("the range check reads carets the way npm does", () => {
+ assert.ok(satisfies("0.21.1", "^0.21.0"));
+ assert.ok(!satisfies("0.21.1", "^0.22.1"));
+ assert.ok(satisfies("0.21.1", "^0.22.1 || ^0.21.1"));
+ assert.ok(satisfies("1.4.0", "^1.3.0"));
+ assert.ok(!satisfies("2.0.0", "^1.3.0"));
+});