Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
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.mdnew file mode 100644index 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.jsonindex 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.jsonindex 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.mjsnew file mode 100644index 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.tsindex 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.tsindex 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 .vueassert.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.tsnew file mode 100644index 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"));+});