@esneiderbravo/speclaw 0.1.0

package/dist/cli/lib/ui.js

@@ -0,0 +1,89 @@
+// Brand-themed terminal UI. Colors come from the speclaw palette (cyan #2EE6E6
+// = the "law", cream text, muted gray, green/amber for status) rendered as
+// 24-bit truecolor ANSI — no dependency needed. Colors auto-disable when the
+// output is not a TTY or NO_COLOR is set.
+const PALETTE = {
+    cyan: [46, 230, 230], // #2EE6E6 — the accent / "law"
+    cyanDim: [23, 193, 193], // #17C1C1
+    cream: [244, 241, 234], // #F4F1EA — primary text
+    muted: [110, 123, 128], // #6E7B80 — secondary text
+    green: [63, 185, 80], // #3FB950 — success
+    amber: [227, 179, 65], // #E3B341 — warning
+    red: [235, 90, 90],
+};
+const colorOn = (Boolean(process.stdout.isTTY) || process.env.FORCE_COLOR === "1") &&
+    !process.env.NO_COLOR;
+function paint(rgb, s) {
+    if (!colorOn)
+        return s;
+    return `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${s}\x1b[0m`;
+}
+function bold(s) {
+    return colorOn ? `\x1b[1m${s}\x1b[0m` : s;
+}
+/** Brand color helpers for composing styled strings. */
+export const c = {
+    cyan: (s) => paint(PALETTE.cyan, s),
+    cyanDim: (s) => paint(PALETTE.cyanDim, s),
+    cream: (s) => paint(PALETTE.cream, s),
+    muted: (s) => paint(PALETTE.muted, s),
+    green: (s) => paint(PALETTE.green, s),
+    amber: (s) => paint(PALETTE.amber, s),
+    red: (s) => paint(PALETTE.red, s),
+    bold,
+};
+/** Styled output primitives used across the CLI. */
+export const ui = {
+    heading: (s) => console.log("\n" + bold(c.cyan(s))),
+    step: (s) => console.log("\n" + c.cyan("◇ ") + bold(c.cream(s))),
+    ok: (s) => console.log("  " + c.green("✓") + " " + c.cream(s)),
+    info: (s) => console.log("  " + c.muted(s)),
+    warn: (s) => console.log("  " + c.amber("!") + " " + c.cream(s)),
+    err: (s) => console.error("  " + c.red("✗") + " " + c.cream(s)),
+    plain: (s = "") => console.log(s),
+    code: (s) => c.cyan(s),
+};
+/**
+ * The speclaw wordmark + logo mark (a document whose bottom line — the law — is
+ * highlighted in cyan). Printed at the top of `speclaw init`.
+ */
+export function banner() {
+    const bar = c.cyan("▇▇▇▇▇▇");
+    const line = c.muted("──────");
+    const edge = c.muted;
+    console.log();
+    console.log("  " + edge("╭────────╮"));
+    console.log("  " + edge("│ ") + line + edge(" │") + "   " + bold(c.cream("s p e c l a w")));
+    console.log("  " + edge("│ ") + c.muted("────  ") + edge(" │") + "   " + c.muted("where specs become law"));
+    console.log("  " + edge("│ ") + c.muted("─────") + " " + edge(" │"));
+    console.log("  " + edge("│ ") + bar + edge(" │"));
+    console.log("  " + edge("╰────────╯"));
+    console.log();
+}
+/** Render a single-line progress bar on stderr (so stdout stays clean). */
+export function renderProgress(done, total, label) {
+    if (!process.stderr.isTTY)
+        return;
+    const width = 26;
+    const ratio = total > 0 ? done / total : 1;
+    const filled = Math.round(ratio * width);
+    const bar = c.cyan("█".repeat(filled)) + c.muted("░".repeat(width - filled));
+    const pct = c.cyanDim(String(Math.round(ratio * 100)).padStart(3) + "%");
+    const shortLabel = label.length > 38 ? "…" + label.slice(-37) : label;
+    process.stderr.write(`\r  ${bar} ${pct}  ${c.muted(shortLabel.padEnd(38))}`);
+}
+export function clearProgress() {
+    if (process.stderr.isTTY)
+        process.stderr.write("\r" + " ".repeat(80) + "\r");
+}
+/** Draw a cyan-bordered block (used for the copy-paste agent prompt). */
+export function box(lines, title) {
+    const width = Math.min(72, Math.max(...lines.map((l) => l.length), title?.length ?? 0) + 2);
+    const top = title
+        ? "╭─ " + c.cyanDim(title) + " " + "─".repeat(Math.max(0, width - title.length - 3))
+        : "╭" + "─".repeat(width);
+    console.log("  " + c.muted(top) + c.muted("╮"));
+    for (const l of lines)
+        console.log("  " + c.muted("│ ") + c.cream(l.padEnd(width - 2)) + c.muted(" │"));
+    console.log("  " + c.muted("╰" + "─".repeat(width) + "╯"));
+}

package/dist/modules/compass/db.js

@@ -0,0 +1,84 @@
+import { DatabaseSync } from "node:sqlite";
+import fs from "node:fs";
+import path from "node:path";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT
+);
+CREATE TABLE IF NOT EXISTS files (
+  id INTEGER PRIMARY KEY,
+  path TEXT UNIQUE NOT NULL,
+  hash TEXT NOT NULL,
+  lang TEXT NOT NULL
+);
+-- nodes: the definitions in the codebase (functions, classes, methods, types).
+CREATE TABLE IF NOT EXISTS nodes (
+  id INTEGER PRIMARY KEY,
+  file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  start_line INTEGER NOT NULL,
+  end_line INTEGER NOT NULL,
+  start_byte INTEGER NOT NULL,
+  end_byte INTEGER NOT NULL,
+  parent_id INTEGER,
+  signature TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
+CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_id);
+-- edges: a reference from one node to a named target, resolved lazily.
+CREATE TABLE IF NOT EXISTS edges (
+  id INTEGER PRIMARY KEY,
+  src_node_id INTEGER REFERENCES nodes(id) ON DELETE CASCADE,
+  src_file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  dst_name TEXT NOT NULL,
+  dst_node_id INTEGER,
+  kind TEXT NOT NULL,
+  line INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst_name);
+CREATE INDEX IF NOT EXISTS idx_edges_src ON edges(src_node_id);
+CREATE INDEX IF NOT EXISTS idx_edges_dstid ON edges(dst_node_id);
+-- node_embeddings: the local vector store (one embedding per node).
+CREATE TABLE IF NOT EXISTS node_embeddings (
+  node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+  dim INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  vec BLOB NOT NULL
+);
+`;
+/** Schema version stamped into the `meta` table on first creation. */
+export const SCHEMA_VERSION = "2";
+/**
+ * Open (creating if needed) the index database at `<projectPath>/.speclaw/index.db`.
+ *
+ * Ensures the `.speclaw` directory exists, applies the schema (idempotently),
+ * enables WAL journaling and foreign keys, and stamps the schema version on a
+ * fresh database.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns An open connection to the index database.
+ */
+export function openDb(projectPath) {
+    const dir = path.join(projectPath, ".speclaw");
+    fs.mkdirSync(dir, { recursive: true });
+    const db = new DatabaseSync(path.join(dir, "index.db"));
+    db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
+    db.exec(SCHEMA);
+    const row = db
+        .prepare("SELECT value FROM meta WHERE key = 'schema_version'")
+        .get();
+    if (!row) {
+        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
+    }
+    return db;
+}
+/** Absolute path to the index database file for a project. */
+export function indexPath(projectPath) {
+    return path.join(projectPath, ".speclaw", "index.db");
+}
+/** Whether an index database already exists for the project. */
+export function indexExists(projectPath) {
+    return fs.existsSync(indexPath(projectPath));
+}

package/dist/modules/compass/embedder.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+/**
+ * Split identifiers into lowercase subtokens.
+ *
+ * Splits on camelCase boundaries, snake_case, dots, and other non-word
+ * characters, dropping tokens of length 1 or less.
+ *
+ * @param text - Raw identifier or free text to tokenize.
+ * @returns The list of subtokens, lowercased.
+ */
+export function tokenize(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/)
+        .map((t) => t.toLowerCase())
+        .filter((t) => t.length > 1);
+}
+/**
+ * Zero-dependency, offline lexical embedder. Hashes subtokens into a fixed-dim
+ * bag-of-tokens vector, L2-normalized. Captures token overlap similarity —
+ * weaker than a neural model but instant, deterministic, and requires no
+ * download. The default; swap in a model-backed Embedder for true semantics.
+ */
+export class LexicalEmbedder {
+    dim;
+    id = "lexical-hash-v1";
+    constructor(dim = 256) {
+        this.dim = dim;
+    }
+    /**
+     * Embed text as an L2-normalized bag-of-hashed-subtokens vector.
+     *
+     * @param text - Text to embed.
+     * @returns A `dim`-length unit vector suitable for cosine comparison.
+     */
+    embed(text) {
+        const vec = new Float32Array(this.dim);
+        for (const tok of tokenize(text)) {
+            // two hashed buckets per token (signed) reduce collisions
+            const h = createHash("md5").update(tok).digest();
+            const bucket = ((h[0] << 8) | h[1]) % this.dim;
+            const sign = h[2] & 1 ? 1 : -1;
+            vec[bucket] += sign;
+            const bucket2 = ((h[3] << 8) | h[4]) % this.dim;
+            vec[bucket2] += sign;
+        }
+        let norm = 0;
+        for (const v of vec)
+            norm += v * v;
+        norm = Math.sqrt(norm) || 1;
+        for (let i = 0; i < vec.length; i++)
+            vec[i] /= norm;
+        return vec;
+    }
+}
+let active = new LexicalEmbedder();
+/** The currently active embedder (defaults to {@link LexicalEmbedder}). */
+export function getEmbedder() {
+    return active;
+}
+/** Replace the active embedder used for indexing and recall. */
+export function setEmbedder(e) {
+    active = e;
+}
+/** Serialize a vector to a raw little-endian `Float32` blob for storage. */
+export function toBlob(vec) {
+    return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+/** Deserialize a stored blob back into a `Float32Array` vector. */
+export function fromBlob(blob) {
+    const buf = Buffer.isBuffer(blob) ? blob : Buffer.from(blob);
+    return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+}
+/**
+ * Cosine similarity between two vectors.
+ *
+ * @remarks Assumes both vectors are pre-normalized, so this is just their dot
+ * product over the shared prefix length.
+ * @returns Similarity in `[-1, 1]`; higher means more similar.
+ */
+export function cosine(a, b) {
+    const n = Math.min(a.length, b.length);
+    let dot = 0;
+    for (let i = 0; i < n; i++)
+        dot += a[i] * b[i];
+    return dot; // vectors are pre-normalized
+}

package/dist/modules/compass/extract.js

@@ -0,0 +1,91 @@
+import { parse } from "./parser.js";
+const DEF_LOOKUP = new WeakMap();
+function defKindMap(lang) {
+    let m = DEF_LOOKUP.get(lang);
+    if (!m) {
+        m = new Map(lang.defs.map((d) => [d.node, d.kind]));
+        DEF_LOOKUP.set(lang, m);
+    }
+    return m;
+}
+/** Resolve the identifier name a definition node declares. */
+function defName(node) {
+    const field = node.childForFieldName("name");
+    return field ? field.text : null;
+}
+/** Resolve the final callee name from a call node's function field. */
+function calleeName(node, lang) {
+    const fn = node.childForFieldName(lang.callField);
+    if (!fn)
+        return null;
+    // a.b.c() -> c ; foo() -> foo
+    if (fn.type === "member_expression" || fn.type === "attribute") {
+        const prop = fn.childForFieldName("property") ?? fn.childForFieldName("attribute");
+        return prop ? prop.text : fn.text;
+    }
+    if (fn.type === "identifier")
+        return fn.text;
+    return fn.text.split(/[.\s(]/)[0] || null;
+}
+/** First line of the node's text, trimmed — a lightweight signature. */
+function signatureOf(node) {
+    return node.text.split("\n")[0].trim().slice(0, 200);
+}
+/**
+ * Walk a parsed tree extracting definitions (with nesting) and the call/import
+ * references each definition contains. Single traversal, O(nodes).
+ *
+ * @param source - The full source text of the file.
+ * @param lang - Language configuration describing definition/call/import nodes.
+ * @returns The extracted symbols and references; `parentIndex`/`ownerIndex`
+ * fields index back into the `symbols` array to express nesting and ownership.
+ * @throws If the source cannot be parsed for the given language.
+ */
+export async function extract(source, lang) {
+    const tree = await parse(source, lang);
+    const kinds = defKindMap(lang);
+    const importSet = new Set(lang.importNodes);
+    const symbols = [];
+    const refs = [];
+    const walk = (node, ownerIndex) => {
+        let nextOwner = ownerIndex;
+        if (kinds.has(node.type)) {
+            const name = defName(node);
+            if (name) {
+                const index = symbols.length;
+                symbols.push({
+                    name,
+                    kind: kinds.get(node.type),
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                    startByte: node.startIndex,
+                    endByte: node.endIndex,
+                    parentIndex: ownerIndex,
+                    signature: signatureOf(node),
+                });
+                nextOwner = index;
+            }
+        }
+        else if (node.type === lang.callNode) {
+            const name = calleeName(node, lang);
+            if (name)
+                refs.push({ name, kind: "call", line: node.startPosition.row + 1, ownerIndex });
+        }
+        else if (importSet.has(node.type)) {
+            refs.push({
+                name: node.text.split("\n")[0].trim().slice(0, 200),
+                kind: "import",
+                line: node.startPosition.row + 1,
+                ownerIndex,
+            });
+        }
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child)
+                walk(child, nextOwner);
+        }
+    };
+    walk(tree.rootNode, null);
+    tree.delete();
+    return { symbols, refs };
+}

package/dist/modules/compass/indexer.js

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { openDb } from "./db.js";
+import { langForPath } from "./languages.js";
+import { extract } from "./extract.js";
+import { getEmbedder, toBlob } from "./embedder.js";
+const SKIP_DIRS = new Set([
+    ".git", "node_modules", "dist", "build", ".next", "out", "coverage",
+    "__pycache__", ".venv", "venv", ".speclaw", ".mypy_cache", ".pytest_cache",
+    "vendor", "target", ".turbo", ".cache",
+]);
+const MAX_FILE_BYTES = 1_500_000;
+function hashOf(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function* walkFiles(root) {
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name))
+                    stack.push(full);
+            }
+            else if (entry.isFile()) {
+                if (langForPath(full))
+                    yield full;
+            }
+        }
+    }
+}
+/**
+ * Build or incrementally refresh the index for a project.
+ *
+ * Walks the project's source files (skipping vendored/build directories and
+ * oversized files), and for each file whose content hash changed, re-parses it,
+ * replacing its nodes and edges and re-embedding each node. Files whose hash is
+ * unchanged are skipped; files that disappeared are pruned. Finally resolves
+ * call edges to their target node definitions by name. The whole run executes
+ * in a single transaction, rolled back on any error.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param onProgress - Optional callback invoked once per scanned file.
+ * @returns Counts of files, nodes, edges, embeddings, and pruned/unchanged files.
+ * @throws Re-throws any error encountered mid-run after rolling back the transaction.
+ */
+export async function buildIndex(projectPath, onProgress) {
+    const db = openDb(projectPath);
+    const embedder = getEmbedder();
+    const stats = {
+        files: 0, nodes: 0, edges: 0, embeddings: 0,
+        unchanged: 0, removed: 0, embedder: embedder.id,
+    };
+    const existing = new Map();
+    for (const row of db.prepare("SELECT id, path, hash FROM files").all()) {
+        existing.set(row.path, { id: row.id, hash: row.hash });
+    }
+    const seen = new Set();
+    const insFile = db.prepare("INSERT INTO files(path, hash, lang) VALUES (?, ?, ?)");
+    const updFile = db.prepare("UPDATE files SET hash = ?, lang = ? WHERE id = ?");
+    const delNodes = db.prepare("DELETE FROM nodes WHERE file_id = ?");
+    const delEdges = db.prepare("DELETE FROM edges WHERE src_file_id = ?");
+    const insNode = db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insEdge = db.prepare(`INSERT INTO edges(src_node_id, src_file_id, dst_name, kind, line) VALUES (?, ?, ?, ?, ?)`);
+    const insEmbed = db.prepare(`INSERT OR REPLACE INTO node_embeddings(node_id, dim, model, vec) VALUES (?, ?, ?, ?)`);
+    const allFiles = [...walkFiles(projectPath)];
+    db.exec("BEGIN");
+    try {
+        let done = 0;
+        for (const filePath of allFiles) {
+            const rel = path.relative(projectPath, filePath);
+            done++;
+            if (onProgress)
+                onProgress({ file: rel, done, total: allFiles.length });
+            seen.add(rel);
+            const lang = langForPath(filePath);
+            let content;
+            try {
+                const stat = fs.statSync(filePath);
+                if (stat.size > MAX_FILE_BYTES)
+                    continue;
+                content = fs.readFileSync(filePath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const hash = hashOf(content);
+            const prior = existing.get(rel);
+            if (prior && prior.hash === hash) {
+                stats.unchanged++;
+                continue;
+            }
+            let fileId;
+            if (prior) {
+                updFile.run(hash, lang.id, prior.id);
+                delNodes.run(prior.id);
+                delEdges.run(prior.id);
+                fileId = prior.id;
+            }
+            else {
+                fileId = Number(insFile.run(rel, hash, lang.id).lastInsertRowid);
+            }
+            const { symbols, refs } = await extract(content, lang);
+            const nodeIds = [];
+            for (const s of symbols) {
+                const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
+                const id = Number(insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature).lastInsertRowid);
+                nodeIds.push(id);
+                // embed the node from its name + signature (cheap, meaningful text)
+                const vec = await embedder.embed(`${s.kind} ${s.name} ${s.signature ?? ""}`);
+                insEmbed.run(id, embedder.dim, embedder.id, toBlob(vec));
+                stats.embeddings++;
+            }
+            for (const r of refs) {
+                const srcId = r.ownerIndex !== null ? nodeIds[r.ownerIndex] : null;
+                insEdge.run(srcId, fileId, r.name, r.kind, r.line);
+                stats.edges++;
+            }
+            stats.files++;
+            stats.nodes += symbols.length;
+        }
+        // prune files that no longer exist
+        for (const [rel, row] of existing) {
+            if (!seen.has(rel)) {
+                db.prepare("DELETE FROM files WHERE id = ?").run(row.id);
+                stats.removed++;
+            }
+        }
+        // resolve call edges to node definitions by name match
+        db.exec(`
+      UPDATE edges SET dst_node_id = (
+        SELECT n.id FROM nodes n
+        WHERE n.name = edges.dst_name
+        LIMIT 1
+      )
+      WHERE kind = 'call' AND dst_node_id IS NULL
+    `);
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    finally {
+        db.close();
+    }
+    return stats;
+}

package/dist/modules/compass/languages.js

@@ -0,0 +1,67 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+const require = createRequire(import.meta.url);
+/** Directory holding the pre-built tree-sitter WASM grammars. */
+function wasmDir() {
+    return path.join(path.dirname(require.resolve("tree-sitter-wasms/package.json")), "out");
+}
+export const LANGUAGES = [
+    {
+        id: "python",
+        grammar: "tree-sitter-python",
+        extensions: [".py", ".pyi"],
+        defs: [
+            { node: "function_definition", kind: "function" },
+            { node: "class_definition", kind: "class" },
+        ],
+        callNode: "call",
+        callField: "function",
+        importNodes: ["import_statement", "import_from_statement"],
+    },
+    {
+        id: "javascript",
+        grammar: "tree-sitter-javascript",
+        extensions: [".js", ".jsx", ".mjs", ".cjs"],
+        defs: [
+            { node: "function_declaration", kind: "function" },
+            { node: "class_declaration", kind: "class" },
+            { node: "method_definition", kind: "method" },
+        ],
+        callNode: "call_expression",
+        callField: "function",
+        importNodes: ["import_statement"],
+    },
+    {
+        id: "typescript",
+        grammar: "tree-sitter-typescript",
+        extensions: [".ts", ".tsx", ".mts", ".cts"],
+        defs: [
+            { node: "function_declaration", kind: "function" },
+            { node: "class_declaration", kind: "class" },
+            { node: "method_definition", kind: "method" },
+            { node: "interface_declaration", kind: "interface" },
+            { node: "type_alias_declaration", kind: "type" },
+            { node: "enum_declaration", kind: "enum" },
+        ],
+        callNode: "call_expression",
+        callField: "function",
+        importNodes: ["import_statement"],
+    },
+];
+const BY_EXT = new Map();
+for (const lang of LANGUAGES) {
+    for (const ext of lang.extensions)
+        BY_EXT.set(ext, lang);
+}
+/**
+ * Resolve the language configuration for a file by its extension.
+ *
+ * @returns The matching {@link LangConfig}, or `undefined` for unsupported files.
+ */
+export function langForPath(filePath) {
+    return BY_EXT.get(path.extname(filePath).toLowerCase());
+}
+/** Absolute path to the tree-sitter WASM grammar file for a language. */
+export function grammarPath(lang) {
+    return path.join(wasmDir(), `${lang.grammar}.wasm`);
+}

package/dist/modules/compass/parser.js

@@ -0,0 +1,37 @@
+import { Parser, Language } from "web-tree-sitter";
+import { grammarPath } from "./languages.js";
+let initialized = false;
+const languageCache = new Map();
+async function ensureInit() {
+    if (!initialized) {
+        await Parser.init();
+        initialized = true;
+    }
+}
+async function loadLanguage(lang) {
+    const cached = languageCache.get(lang.id);
+    if (cached)
+        return cached;
+    const loaded = await Language.load(grammarPath(lang));
+    languageCache.set(lang.id, loaded);
+    return loaded;
+}
+/**
+ * Parse source into a tree-sitter tree for the given language.
+ *
+ * Lazily initializes tree-sitter and caches the loaded grammar per language.
+ *
+ * @param source - The source text to parse.
+ * @param lang - Language configuration selecting the grammar.
+ * @returns The parsed syntax tree; the caller owns it and must `delete()` it.
+ * @throws If parsing yields no tree.
+ */
+export async function parse(source, lang) {
+    await ensureInit();
+    const parser = new Parser();
+    parser.setLanguage(await loadLanguage(lang));
+    const tree = parser.parse(source);
+    if (!tree)
+        throw new Error(`failed to parse ${lang.id} source`);
+    return tree;
+}