vigiles 30.0.2 → 31.0.1

package/dist/core/frame.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.frameFor = frameFor;
+exports.frameAt = frameAt;
+const posix_path_js_1 = require("../posix-path.js");
+/**
+ * Node on Windows hands out `C:\\repo`, and `../posix-path.js` recognises only a leading `/`
+ * as absolute. The frame works in `/`-separated form, so every path entering it passes here:
+ * backslashes become `/`, and a drive-letter path (`C:/…`) counts as absolute.
+ */
+function slashed(p) {
+    return p.replaceAll("\\", "/");
+}
+function isAbs(p) {
+    return (0, posix_path_js_1.isAbsolute)(p) || /^[A-Za-z]:\//.test(p);
+}
+/** `rel` is `abs`'s position below `root` when it does not climb out. */
+function isBelow(rel) {
+    return rel === "" || (rel !== ".." && !rel.startsWith("../"));
+}
+/**
+ * The frame for a command run from `cwd` against `target` (absolute).
+ *
+ * The root is `cwd` — where `loadConfig()` read `.vigilesrc.json` (it does not
+ * walk up; measured 2026-09-23) — UNLESS the target lies outside it. A foreign
+ * target (`vigiles lint ../other`) is somebody else's repository, and its paths
+ * mean something from ITS root; relative to `cwd` they would all start with
+ * `../`, and a foreign lint must never let the caller's own files satisfy the
+ * target's `sharedDirs` references. That exception was `sharedDirsRootFor` in
+ * the CLI, applied to `sharedDirs` alone; it is owned here now, so `include`,
+ * `exclude`, `sharedDirs` and every printed path agree on one root.
+ */
+function frameFor(cwd, target) {
+    return frameAt(isBelow((0, posix_path_js_1.relative)(slashed(cwd), slashed(target))) ? cwd : target);
+}
+/** The frame rooted at an absolute directory. */
+function frameAt(root) {
+    const base = (0, posix_path_js_1.normalize)(slashed(root));
+    const repo = (raw) => {
+        const abs = slashed(raw);
+        if (!isAbs(abs))
+            throw new Error(`frame.repo() takes an absolute path, got "${raw}" — a relative string has no frame to convert from`);
+        return ((0, posix_path_js_1.relative)(base, abs) || ".");
+    };
+    const bundle = (raw) => {
+        const dir = (0, posix_path_js_1.normalize)(slashed(raw));
+        const path = (p) => repo((0, posix_path_js_1.join)(dir, p));
+        return {
+            abs: dir,
+            at: repo(dir),
+            path,
+            // The ONE place a plain string is taken to be bundle-relative.
+            scanned: (p) => (isAbs(slashed(p)) ? repo(p) : path(p)),
+        };
+    };
+    return { root: base, repo, bundle };
+}
+//# sourceMappingURL=frame.js.map

package/dist/core/glob-ignore.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One `ignore` for `globSync` out of a detector's own string floor plus the
+ * repository's exclude — glob takes EITHER a pattern list OR one `IgnoreLike`,
+ * never both, so a detector that has both needs this union.
+ *
+ * 🔴 WHY THE REPO EXCLUDE ARRIVES AS AN `IgnoreLike` AND NOT AS STRINGS (#281).
+ * `ExcludeSet` used to hand detectors a string list whose patterns were relative
+ * to the repository root, with the precondition "only correct for a glob rooted
+ * AT that root" written in a comment. Two callers globbed from a nested bundle
+ * and broke it silently: a root-relative `skills/lonely` dropped
+ * `plugins/p/skills/lonely`, and the real exclusion never reached the bundle.
+ * `ExcludeSet.globIgnore` computes each candidate's position from the repo root
+ * itself, so it is correct from ANY glob `cwd`; the string face was retired.
+ *
+ * A plain string list is still accepted — for a direct library caller whose
+ * patterns are, by that caller's own contract, relative to the `cwd` it globs
+ * from. That is the one frame a string can safely carry.
+ */
+import { type IgnoreLike } from "glob";
+/** What a detector takes for "also skip these". */
+export type GlobIgnore = readonly string[] | IgnoreLike;
+/**
+ * `floor` (patterns relative to the glob's `cwd`) plus `extra`, in the form
+ * `globSync`'s `ignore` option accepts. Stays a plain list when both halves are
+ * lists, so a string-only caller sees exactly the glob behaviour it always had.
+ */
+export declare function withIgnored(floor: readonly string[], extra: GlobIgnore | undefined): string[] | IgnoreLike;
+//# sourceMappingURL=glob-ignore.d.ts.map

package/dist/core/glob-ignore.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withIgnored = withIgnored;
+/**
+ * One `ignore` for `globSync` out of a detector's own string floor plus the
+ * repository's exclude — glob takes EITHER a pattern list OR one `IgnoreLike`,
+ * never both, so a detector that has both needs this union.
+ *
+ * 🔴 WHY THE REPO EXCLUDE ARRIVES AS AN `IgnoreLike` AND NOT AS STRINGS (#281).
+ * `ExcludeSet` used to hand detectors a string list whose patterns were relative
+ * to the repository root, with the precondition "only correct for a glob rooted
+ * AT that root" written in a comment. Two callers globbed from a nested bundle
+ * and broke it silently: a root-relative `skills/lonely` dropped
+ * `plugins/p/skills/lonely`, and the real exclusion never reached the bundle.
+ * `ExcludeSet.globIgnore` computes each candidate's position from the repo root
+ * itself, so it is correct from ANY glob `cwd`; the string face was retired.
+ *
+ * A plain string list is still accepted — for a direct library caller whose
+ * patterns are, by that caller's own contract, relative to the `cwd` it globs
+ * from. That is the one frame a string can safely carry.
+ */
+const glob_1 = require("glob");
+function isPatternList(x) {
+    return Array.isArray(x);
+}
+/**
+ * `floor` (patterns relative to the glob's `cwd`) plus `extra`, in the form
+ * `globSync`'s `ignore` option accepts. Stays a plain list when both halves are
+ * lists, so a string-only caller sees exactly the glob behaviour it always had.
+ */
+function withIgnored(floor, extra) {
+    if (extra === undefined)
+        return [...floor];
+    if (isPatternList(extra))
+        return [...floor, ...extra];
+    const own = new glob_1.Ignore([...floor], {});
+    return {
+        ignored: (p) => own.ignored(p) || extra.ignored?.(p) === true,
+        childrenIgnored: (p) => own.childrenIgnored(p) || extra.childrenIgnored?.(p) === true,
+    };
+}
+//# sourceMappingURL=glob-ignore.js.map

package/dist/core/orphans.d.ts

@@ -11,6 +11,7 @@
  * references (markdown links and backtick paths). Works against source
  * README plus compiled CLAUDE.md — no spec loading required.
  */
+import { type GlobIgnore } from "./glob-ignore.js";
 import type { PluginLayout } from "./layout.js";
 export interface OrphanReport {
     /** Include globs that were scanned. */
@@ -35,12 +36,13 @@ export interface FindOrphansOptions {
     /** Glob patterns to exclude within the include scope (orphan CANDIDACY only). */
     readonly exclude?: readonly string[];
     /**
-     * The repo-wide `.vigilesrc.json#exclude` (the ExcludeSet string face,
-     * src/exclude.ts). Applied to BOTH walks — candidates AND the reference scan —
+     * The repo-wide `.vigilesrc.json#exclude` (`ExcludeSet.globIgnore`,
+     * src/exclude.ts — correct from any glob cwd; a plain list is relative to
+     * `basePath`). Applied to BOTH walks — candidates AND the reference scan —
      * so an excluded corpus can neither be an orphan nor keep one alive (#192).
      * The CLI always passes it; a direct library caller may omit it.
      */
-    readonly repoExclude?: readonly string[];
+    readonly repoExclude?: GlobIgnore;
     /**
      * Harnesses whose surface files (instruction file, `SKILL.md`, subagents,
      * commands) are load-bearing by location and thus never orphan CANDIDATES

package/dist/core/orphans.js

@@ -18,6 +18,7 @@ exports.formatOrphanReport = formatOrphanReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
+const glob_ignore_js_1 = require("./glob-ignore.js");
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
@@ -100,7 +101,7 @@ function isOrphanExempt(absPath) {
 function collectDocs(basePath, include, ignore, layouts) {
     const docs = new Set();
     for (const pattern of include) {
-        for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
+        for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore })) {
             if (isHarnessLoadedFile(p, layouts))
                 continue; // harness files are never orphans
             if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
@@ -160,13 +161,13 @@ function findOrphanDocs(options = {}) {
     // CANDIDATE nor a SOURCE of references (a link from inside it must not keep a
     // doc alive). The rule's own `exclude` only narrows candidacy: a doc kept out
     // of the orphan list can still reference others. Union, never override.
-    const repoExclude = options.repoExclude ?? [];
-    const ignore = [...DEFAULT_IGNORE, ...repoExclude, ...userExclude];
+    const repoExclude = options.repoExclude;
+    const ignore = (0, glob_ignore_js_1.withIgnored)([...DEFAULT_IGNORE, ...userExclude], repoExclude);
     const layouts = options.layouts ?? [];
     const allDocs = collectDocs(basePath, include, ignore, layouts);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
         cwd: basePath,
-        ignore: [...DEFAULT_IGNORE, ...repoExclude],
+        ignore: (0, glob_ignore_js_1.withIgnored)(DEFAULT_IGNORE, repoExclude),
     });
     const referencedBy = new Map();
     for (const mdPath of allMarkdown) {

package/dist/core/refs.d.ts

@@ -26,7 +26,7 @@ export declare function symbolRefs(markdown: string): SymbolRef[];
  * file must exist and define the named symbol. `basePath` is the directory the
  * paths resolve against (the instruction file's own directory).
  */
-export declare function verifySymbolRefs(markdown: string, basePath: string): SymbolRefError[];
+export declare function verifySymbolRefs(markdown: string, basePath: string): Promise<SymbolRefError[]>;
 /**
  * Whether a span is a **linter-rule reference** that ought to be marked
  * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the lint can verify the
@@ -50,7 +50,7 @@ export declare function unmarkedCodeRefs(markdown: string): Span[];
  * code-shaped span that ought to be a mark. The shared detector behind both the
  * `vigiles refs` CLI and the PostToolUse refs-hook.
  */
-export declare function collectRefIssues(markdown: string, basePath: string): string[];
+export declare function collectRefIssues(markdown: string, basePath: string): Promise<string[]>;
 /** What the refs-hook should do given the issue count and configured severity. */
 export type RefsHookAction = "ok" | "nudge" | "block";
 /**

package/dist/core/refs.js

@@ -70,11 +70,11 @@ function symbolRefs(markdown) {
  * file must exist and define the named symbol. `basePath` is the directory the
  * paths resolve against (the instruction file's own directory).
  */
-function verifySymbolRefs(markdown, basePath) {
+async function verifySymbolRefs(markdown, basePath) {
     const errors = [];
     for (const ref of symbolRefs(markdown)) {
         const full = (0, node_path_1.resolve)(basePath, ref.file);
-        const support = (0, symbols_js_1.langForFile)(ref.file);
+        const support = await (0, symbols_js_1.langForFile)(ref.file);
         if (!(0, node_fs_1.existsSync)(full)) {
             errors.push({ ...ref, reason: `File not found: "${ref.file}"` });
         }
@@ -84,15 +84,12 @@ function verifySymbolRefs(markdown, basePath) {
                 reason: `Unsupported language for symbol check: "${ref.file}"`,
             });
         }
-        else if (support.kind === "grammar-missing") {
-            // NOT "unsupported": the language is one this tool parses, the optional grammar just is
-            // not installed here. Saying it the other way would report an un-run check as a verdict.
-            errors.push({
-                ...ref,
-                reason: `Symbol not checked: the ${support.id} grammar is not installed (npm i -D ${support.pkg})`,
-            });
+        else if (support.kind === "grammar-load-failed") {
+            // NOT "unsupported" and NOT "not defined": the language is one this tool parses, its
+            // grammar failed to load here. Either other wording would report an un-run check as a verdict.
+            errors.push({ ...ref, reason: (0, symbols_js_1.notCheckedReason)(support) });
         }
-        else if (!(0, symbols_js_1.fileDefinesSymbol)(full, ref.symbol)) {
+        else if (!(await (0, symbols_js_1.fileDefinesSymbol)(full, ref.symbol))) {
             errors.push({
                 ...ref,
                 reason: `"${ref.symbol}" is not defined in ${ref.file}`,
@@ -149,9 +146,9 @@ function unmarkedCodeRefs(markdown) {
  * code-shaped span that ought to be a mark. The shared detector behind both the
  * `vigiles refs` CLI and the PostToolUse refs-hook.
  */
-function collectRefIssues(markdown, basePath) {
+async function collectRefIssues(markdown, basePath) {
     const out = [];
-    for (const b of verifySymbolRefs(markdown, basePath)) {
+    for (const b of await verifySymbolRefs(markdown, basePath)) {
         out.push(`line ${String(b.line)}: ${b.reason}`);
     }
     for (const u of unmarkedCodeRefs(markdown)) {

package/dist/core/spec.js

@@ -1,4 +1,9 @@
 "use strict";
+// 🔴 PUBLIC ENTRY POINT `vigiles/spec` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-spec.api.md`, which
+// `npm run api:check` fails on.
 /**
  * vigiles v2 — Executable specification system.
  *

package/dist/core/symbols.d.ts

@@ -1,30 +1,33 @@
 import { Lang } from "@ast-grep/napi";
-/** Which optional grammars this process actually has. Exported so a report can say so. */
-export declare function installedGrammars(): ReadonlySet<string>;
-/** A language key accepted by ast-grep's `parse` (core enum or registered id). */
-type LangKey = Lang | string;
+import { type WasmLang } from "./tree-sitter-wasm.js";
+/** A language key: an `@ast-grep/napi` built-in, or one of the WASM grammars. */
+type LangKey = Lang | WasmLang;
 /**
  * Whether this file's language can be parsed HERE, and if not, which of the two reasons.
  *
- * 🔴 THE THREE CASES ARE SEPARATE MEMBERS BECAUSE THEY ARE SEPARATE FACTS. The previous
- * signature was `LangKey | null`, where `null` meant "extension not in the table" and callers
- * printed "Unsupported language for symbol check". Making the grammars optional would have
- * given that same `null` a second meaning — "the language IS ours, the package is simply not
- * installed" — and both callers would have kept printing the first sentence. That is the
- * failure this codebase exists to catch: a check that did not run, reported in the words of a
- * check that did. A union makes the compiler demand the distinction at every call site.
+ * 🔴 THE THREE CASES ARE SEPARATE MEMBERS BECAUSE THEY ARE SEPARATE FACTS. "Extension not in
+ * the table" and "the language IS ours but its grammar failed to load in this process" must not
+ * share one `null`: both callers would print the first sentence, and a check that did not run
+ * would read as a verdict. With WASM grammars shipped as a regular dependency there is no
+ * install or platform gap left, so `grammar-load-failed` should not happen — but if the runtime
+ * genuinely cannot load, the report carries the loader's own error text, never "not defined"
+ * and never an install instruction the user cannot act on.
  */
 export type LangSupport = {
     readonly kind: "ready";
     readonly lang: LangKey;
 } | {
-    readonly kind: "grammar-missing";
-    readonly id: string;
-    readonly pkg: string;
+    readonly kind: "grammar-load-failed";
+    readonly lang: WasmLang;
+    readonly error: string;
 } | {
     readonly kind: "unsupported";
 };
-export declare function langForFile(file: string): LangSupport;
+export declare function langForFile(file: string): Promise<LangSupport>;
+/** The one sentence both callers print for a symbol reference that could not be checked. */
+export declare function notCheckedReason(support: Extract<LangSupport, {
+    kind: "grammar-load-failed";
+}>): string;
 /** A symbol definition found in a file. */
 export interface SymbolDef {
     /** The defined identifier, e.g. "parseConfig". */
@@ -36,10 +39,13 @@ export interface SymbolDef {
     /** 1-based line of the definition. */
     readonly line: number;
 }
-/** Extract the symbols defined in a single file's source. */
-export declare function definedSymbols(code: string, lang: LangKey): SymbolDef[];
+/**
+ * Extract the symbols defined in a single file's source. Async because the Python / Ruby / Rust
+ * grammars are WebAssembly, whose instantiation is async; the napi languages resolve at once.
+ */
+export declare function definedSymbols(code: string, lang: LangKey): Promise<SymbolDef[]>;
 /** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
-export declare function definedSymbolsInFile(file: string): SymbolDef[];
+export declare function definedSymbolsInFile(file: string): Promise<SymbolDef[]>;
 /**
  * Whether `file` defines a top-level (or scoped) symbol named `name`. This is
  * the whole check for a file-qualified reference (`path#symbol`): we parse the
@@ -47,6 +53,6 @@ export declare function definedSymbolsInFile(file: string): SymbolDef[];
  * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
  * typed dynamic symbols resolve without running Sorbet / the TS compiler.
  */
-export declare function fileDefinesSymbol(file: string, name: string): boolean;
+export declare function fileDefinesSymbol(file: string, name: string): Promise<boolean>;
 export {};
 //# sourceMappingURL=symbols.d.ts.map

package/dist/core/symbols.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.installedGrammars = installedGrammars;
 exports.langForFile = langForFile;
+exports.notCheckedReason = notCheckedReason;
 exports.definedSymbols = definedSymbols;
 exports.definedSymbolsInFile = definedSymbolsInFile;
 exports.fileDefinesSymbol = fileDefinesSymbol;
@@ -21,60 +21,32 @@ exports.fileDefinesSymbol = fileDefinesSymbol;
  * delegated. Ambiguity (a name defined in several files) is reported, not guessed.
  */
 const node_fs_1 = require("node:fs");
-const node_module_1 = require("node:module");
+const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
 const napi_1 = require("@ast-grep/napi");
+const tree_sitter_wasm_js_1 = require("./tree-sitter-wasm.js");
 /**
- * The non-web grammars, as OPTIONAL packages keyed by the id ast-grep registers them under.
+ * Python, Ruby and Rust are parsed by WebAssembly builds of their tree-sitter grammars
+ * (`./tree-sitter-wasm.ts`); TypeScript, TSX, JavaScript and CSS by the grammars built into
+ * `@ast-grep/napi`.
  *
- * 🔴 WHY OPTIONAL, AND WHY IT IS NOT A PREFERENCE. These three are the only packages in this
- * dependency tree carrying a `postinstall` (measured 2026-09-20 with `npm query
- * ":attr(scripts, [postinstall])"`). Since pnpm 10 a consumer's install FAILS on an
- * unapproved lifecycle script, so every downstream project installing vigiles with pnpm got
- * `ERR_PNPM_IGNORED_BUILDS` and a non-zero exit — for grammars most of them never use. The web
- * grammars every user does need (TypeScript, TSX, JavaScript, CSS) are built into
- * `@ast-grep/napi` and cost nothing.
- *
- * They load through `createRequire` rather than `await import()` on purpose: the packages are
- * CommonJS (`"main": "index.js"`, no `exports`), so a synchronous require works and NOTHING in
- * this module's public surface has to become async. Measured, not assumed.
+ * 🔴 WHY NOT `@ast-grep/lang-*` ANY MORE (#257). Those native grammars were the only packages in
+ * the tree carrying a `postinstall`, and since pnpm 10 an unapproved dependency build script
+ * FAILS a consumer's install (`ERR_PNPM_IGNORED_BUILDS`) — for every `pnpm add vigiles`, whether
+ * or not the project has a single `.py` file. Making them optional peers stopped the failure but
+ * moved the cost onto the user: a `.py` reference then reported "grammar not installed" after an
+ * upgrade. The WASM grammars are a plain dependency with no install script and no native
+ * binary, so they are simply there. `src/package-install-scripts.e2e.test.ts` holds both halves
+ * against the packed tarball: no install script in the tree, and a `.py` lookup that works
+ * right after a default install.
  */
-const OPTIONAL_GRAMMARS = {
-    python: "@ast-grep/lang-python",
-    rust: "@ast-grep/lang-rust",
-    ruby: "@ast-grep/lang-ruby",
-};
-// Anchored on THIS module's own file, not on the consumer's project root. Under pnpm a
-// consumer's root does not contain our transitive packages at all — the same addressing
-// mistake that made every hook fail there — and these grammars are OUR optional dependencies,
-// so they resolve from where this file lives. `__filename` rather than `import.meta.url`
-// because this package compiles to CommonJS (`module: Node16`, `main: ./dist/test.js`).
-const require_ = (0, node_module_1.createRequire)(__filename);
-/** Registered grammar ids, populated on first use. `null` until then. */
-let loaded = null;
-function ensureRegistered() {
-    if (loaded)
-        return loaded;
-    const dynamic = {};
-    const present = new Set();
-    for (const [id, pkg] of Object.entries(OPTIONAL_GRAMMARS)) {
-        try {
-            dynamic[id] = require_(pkg);
-            present.add(id);
-        }
-        catch {
-            // Absent by design: an optional dependency the consumer did not install. The caller is
-            // told WHICH id is missing (see `langForFile`), so "not checked" never reads as "clean".
-        }
-    }
-    if (present.size > 0)
-        (0, napi_1.registerDynamicLanguage)(dynamic);
-    loaded = present;
-    return loaded;
-}
-/** Which optional grammars this process actually has. Exported so a report can say so. */
-function installedGrammars() {
-    return ensureRegistered();
+const WASM_LANGS = new Set([
+    "python",
+    "ruby",
+    "rust",
+]);
+function isWasmLang(key) {
+    return typeof key === "string" && WASM_LANGS.has(key);
 }
 const EXT_LANG = {
     ".ts": napi_1.Lang.TypeScript,
@@ -93,28 +65,26 @@ const EXT_LANG = {
     ".rb": "ruby",
     ".rbi": "ruby",
 };
-function langForFile(file) {
+async function langForFile(file) {
     const key = file.endsWith(".d.ts")
         ? napi_1.Lang.TypeScript
         : EXT_LANG[(0, node_path_1.extname)(file).toLowerCase()];
     if (key === undefined)
         return { kind: "unsupported" };
-    // A string key is one of the dynamically registered grammars; the enum members are built in.
-    if (typeof key === "string" && key in OPTIONAL_GRAMMARS) {
-        if (!ensureRegistered().has(key))
-            return { kind: "grammar-missing", id: key, pkg: OPTIONAL_GRAMMARS[key] };
+    if (isWasmLang(key)) {
+        // Lazy: the first .py/.rb/.rs reference starts the runtime; later ones hit the cache.
+        const error = await (0, tree_sitter_wasm_js_1.loadWasmGrammar)(key);
+        if (error !== null)
+            return { kind: "grammar-load-failed", lang: key, error };
     }
     return { kind: "ready", lang: key };
 }
-const ID_KINDS = new Set(["identifier", "constant", "type_identifier"]);
-const SCOPE_KINDS = new Set([
-    "class_declaration",
-    "class_definition",
-    "class",
-    "module",
-    "interface_declaration",
-    "enum_declaration",
-]);
+/** The one sentence both callers print for a symbol reference that could not be checked. */
+function notCheckedReason(support) {
+    return `Symbol not checked: the ${support.lang} grammar failed to load: ${support.error}`;
+}
+const ID_KINDS = new Set(tree_sitter_wasm_js_1.ID_KINDS);
+const SCOPE_KINDS = new Set(tree_sitter_wasm_js_1.SCOPE_KINDS);
 function recordNode(node, scope, out) {
     const line = node.range().start.line + 1;
     const nameNode = node.field("name");
@@ -128,9 +98,13 @@ function recordNode(node, scope, out) {
         out.push({ name: left.text(), kind: node.kind(), scope, line });
     }
 }
-/** Extract the symbols defined in a single file's source. */
-function definedSymbols(code, lang) {
-    ensureRegistered();
+/**
+ * Extract the symbols defined in a single file's source. Async because the Python / Ruby / Rust
+ * grammars are WebAssembly, whose instantiation is async; the napi languages resolve at once.
+ */
+async function definedSymbols(code, lang) {
+    if (isWasmLang(lang))
+        return (0, tree_sitter_wasm_js_1.wasmDefinedSymbols)(code, lang);
     const out = [];
     const walk = (node, scope) => {
         recordNode(node, scope, out);
@@ -143,17 +117,20 @@ function definedSymbols(code, lang) {
     return out;
 }
 /** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
-function definedSymbolsInFile(file) {
-    const support = langForFile(file);
+async function definedSymbolsInFile(file) {
+    const support = await langForFile(file);
     if (support.kind !== "ready")
         return [];
-    const lang = support.lang;
+    let code;
     try {
-        return definedSymbols((0, node_fs_1.readFileSync)(file, "utf-8"), lang);
+        code = await (0, promises_1.readFile)(file, "utf-8");
     }
     catch {
         return [];
     }
+    // Deliberately OUTSIDE the try: a parser failure is not an empty file. Swallowing it would
+    // turn "could not parse" into "is not defined" — a check that did not run, read as a verdict.
+    return definedSymbols(code, support.lang);
 }
 // A co-located declaration file that may declare symbols the source defines
 // dynamically (Sorbet `.rbi`, TypeScript `.d.ts`) — checked as a fallback so a
@@ -173,15 +150,15 @@ const DECL_SIBLING = {
  * fallback we also consult a co-located declaration file (`.rbi` / `.d.ts`), so
  * typed dynamic symbols resolve without running Sorbet / the TS compiler.
  */
-function fileDefinesSymbol(file, name) {
-    if (definedSymbolsInFile(file).some((d) => d.name === name))
+async function fileDefinesSymbol(file, name) {
+    if ((await definedSymbolsInFile(file)).some((d) => d.name === name))
         return true;
     const ext = (0, node_path_1.extname)(file);
     const decl = DECL_SIBLING[ext];
     if (decl && !file.endsWith(decl)) {
         const sibling = file.slice(0, -ext.length) + decl;
         if ((0, node_fs_1.existsSync)(sibling) &&
-            definedSymbolsInFile(sibling).some((d) => d.name === name)) {
+            (await definedSymbolsInFile(sibling)).some((d) => d.name === name)) {
             return true;
         }
     }

package/dist/core/tree-sitter-wasm.d.ts

@@ -0,0 +1,24 @@
+/** The grammars this module parses, keyed by the id used in `tree-sitter-<id>.wasm`. */
+export type WasmLang = "python" | "ruby" | "rust";
+/** A definition found by the walk — the same shape `symbols.ts` exports as `SymbolDef`. */
+export interface WasmSymbolDef {
+    readonly name: string;
+    readonly kind: string;
+    readonly scope: string;
+    readonly line: number;
+}
+/**
+ * Node kinds that open a scope (their `name` becomes the `scope` of everything inside), and the
+ * kinds a `left` field must have to count as an assignment-style definition. ONE list for both
+ * walkers — the napi one in `symbols.ts` and the one below — so they cannot drift apart.
+ */
+export declare const SCOPE_KINDS: readonly string[];
+export declare const ID_KINDS: readonly string[];
+/**
+ * Load `lang`'s grammar once per process. Resolves to `null` on success, or the load error's own
+ * text — the caller reports it verbatim as "not checked", never as a missing symbol.
+ */
+export declare function loadWasmGrammar(lang: WasmLang): Promise<string | null>;
+/** Parse `code` and return its definitions. Rejects on a parse failure — never resolves []. */
+export declare function wasmDefinedSymbols(code: string, lang: WasmLang): Promise<WasmSymbolDef[]>;
+//# sourceMappingURL=tree-sitter-wasm.d.ts.map