docsgov 0.1.0

package/dist/codeq/resolve.test.js

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { parseCodeRef } from "../guard/code/index.js";
+import { createDefaultResolver } from "./resolver.js";
+// WHY: this is the end-to-end seam test for the WHOLE codeq dispatch. The unit
+// tests (resolver.test.ts) prove routing with FAKE per-language resolvers; this
+// proves the REAL wiring works across grammars: createDefaultResolver loads the
+// vendored wasm, picks the right grammar by extension, and a {{code:…}} token —
+// parsed by the guard/code parser, exactly as the check layer does — resolves
+// true when the symbol exists and false when it does not. Covering both Go and
+// TypeScript (two distinct grammars routed by extension) is what proves the
+// dispatch is per-language and not accidentally a single hard-wired grammar.
+const enc = new TextEncoder();
+class MemFS {
+    files;
+    constructor(files) {
+        this.files = files;
+    }
+    async readFile(name) {
+        const content = this.files[name];
+        if (content === undefined) {
+            const err = new Error(`ENOENT: ${name}`);
+            err.code = "ENOENT";
+            throw err;
+        }
+        return enc.encode(content);
+    }
+    async readDir() {
+        return [];
+    }
+    sub() {
+        return this;
+    }
+}
+describe("codeq end-to-end resolve (real grammars)", () => {
+    it("resolves a Go {{code}} ref against inline source", async () => {
+        const r = await createDefaultResolver();
+        const fs = new MemFS({
+            "pkg/foo.go": "package pkg\n\nfunc Bar() {}\n\ntype Baz struct{}\n",
+        });
+        // Present function and present type both resolve true.
+        expect(await r.resolve(fs, parseCodeRef("{{code:pkg/foo.go#Bar}}"))).toBe(true);
+        expect(await r.resolve(fs, parseCodeRef("{{code:pkg/foo.go#Baz}}"))).toBe(true);
+        // An absent symbol resolves false (not an error) — proving the real grammar
+        // ran and searched, rather than a stub blanket-returning true.
+        expect(await r.resolve(fs, parseCodeRef("{{code:pkg/foo.go#Missing}}"))).toBe(false);
+    });
+    it("resolves a TypeScript {{code}} ref against inline source", async () => {
+        const r = await createDefaultResolver();
+        const fs = new MemFS({
+            "src/api.ts": "export function fetchUser(id: string): void {}\n" +
+                "export class Client {}\n",
+        });
+        expect(await r.resolve(fs, parseCodeRef("{{code:src/api.ts#fetchUser}}"))).toBe(true);
+        expect(await r.resolve(fs, parseCodeRef("{{code:src/api.ts#Client}}"))).toBe(true);
+        expect(await r.resolve(fs, parseCodeRef("{{code:src/api.ts#nope}}"))).toBe(false);
+    });
+});
+// WHY: suggest is the candidate oracle behind a not-found ref. These prove the
+// REAL grammar enumerates the same symbol space resolve() searches — so a typo'd
+// ref can be answered with the names that actually exist — and that the
+// owner-missing signal distinguishes "wrong type" from "wrong member".
+describe("codeq suggest (real grammars)", () => {
+    it("lists top-level symbols for a bare symbol ref", async () => {
+        const r = await createDefaultResolver();
+        const fs = new MemFS({
+            "pkg/foo.go": "package pkg\n\nfunc Bar() {}\n\ntype Baz struct{}\n",
+        });
+        const sug = await r.suggest(fs, parseCodeRef("{{code:pkg/foo.go#Batz}}"));
+        expect(sug.kind).toBe("symbol");
+        expect(sug.ownerMissing).toBeUndefined();
+        expect([...sug.candidates].sort()).toEqual(["Bar", "Baz"]);
+    });
+    it("lists a type's members for a member ref whose owner exists", async () => {
+        const r = await createDefaultResolver();
+        const fs = new MemFS({
+            "pkg/foo.go": "package pkg\n\ntype Ctl struct{}\n\nfunc (c Ctl) Start() {}\nfunc (c Ctl) Stop() {}\n",
+        });
+        const sug = await r.suggest(fs, parseCodeRef("{{code:pkg/foo.go#Ctl.Strt}}"));
+        expect(sug.kind).toBe("member");
+        expect(sug.ownerMissing).toBeUndefined();
+        expect([...sug.candidates].sort()).toEqual(["Start", "Stop"]);
+    });
+    it("signals owner-missing when a member ref's type is absent", async () => {
+        const r = await createDefaultResolver();
+        const fs = new MemFS({
+            "pkg/foo.go": "package pkg\n\ntype Ctl struct{}\n\nfunc (c Ctl) Start() {}\n",
+        });
+        const sug = await r.suggest(fs, parseCodeRef("{{code:pkg/foo.go#Ctlx.Start}}"));
+        expect(sug.kind).toBe("member");
+        expect(sug.ownerMissing).toBe("Ctlx");
+        expect(sug.candidates).toEqual([]);
+    });
+    it("lists a function's params for a param ref (cross-grammar: TS)", async () => {
+        const r = await createDefaultResolver();
+        const fs = new MemFS({
+            "src/api.ts": "export function fetchUser(id: string, token: string): void {}\n",
+        });
+        const sug = await r.suggest(fs, parseCodeRef("{{code:src/api.ts#fetchUser@params.tokn}}"));
+        expect(sug.kind).toBe("param");
+        expect(sug.ownerMissing).toBeUndefined();
+        expect([...sug.candidates].sort()).toEqual(["id", "token"]);
+    });
+    it("yields no candidates for an unsupported extension (graceful)", async () => {
+        const r = await createDefaultResolver();
+        const fs = new MemFS({ "notes/x.rb": "class Foo; end\n" });
+        const sug = await r.suggest(fs, parseCodeRef("{{code:notes/x.rb#Foo}}"));
+        expect(sug.candidates).toEqual([]);
+    });
+});

package/dist/codeq/resolver.js

@@ -0,0 +1,128 @@
+import { SourceCache } from "./cache.js";
+import { UnsupportedLanguageError } from "./errors.js";
+import { refKind } from "./suggest.js";
+import { createGoResolver } from "./resolvers/go.js";
+import { createJavaResolver } from "./resolvers/java.js";
+import { createJSResolver } from "./resolvers/javascript.js";
+import { createTSResolver } from "./resolvers/typescript.js";
+import { loadGrammar } from "./treesitter.js";
+/**
+ * DefaultResolver is the by-extension dispatcher (the analogue of Go's
+ * byExtResolver + DefaultResolver). Build it with the async factory
+ * createDefaultResolver(); then call resolve(root, ref) once per CodeRef.
+ *
+ * resolve(root, ref) is ASYNC because it reads the file from the async FS; the
+ * per-language Resolver it dispatches to is SYNC.
+ */
+export class DefaultResolver {
+    byExt;
+    cache = new SourceCache();
+    /**
+     * @param byExt maps a file extension (including the leading ".") to the
+     *   per-language Resolver for that extension. The same TS Resolver instance is
+     *   registered under both ".ts" and ".tsx" only if it was built from the
+     *   matching grammar; in practice .ts and .tsx are DISTINCT grammars and get
+     *   distinct resolvers (see createDefaultResolver).
+     */
+    constructor(byExt) {
+        this.byExt = byExt;
+    }
+    /**
+     * resolve looks up `ref` in `root`. Returns true when found, false when
+     * absent. Throws UnsupportedLanguageError when no resolver is registered for
+     * the path's extension, FileNotFoundError when the file is missing, and
+     * ParseFailedError when the file fails to parse.
+     */
+    async resolve(root, ref) {
+        const ext = extname(ref.Path);
+        const sub = this.byExt.get(ext);
+        if (sub === undefined) {
+            throw new UnsupportedLanguageError(ext);
+        }
+        // SourceCache maps a missing file to FileNotFoundError; any other I/O fault
+        // propagates. On success we hand the decoded string to the sync resolver.
+        const source = await this.cache.read(root, ref.Path);
+        return sub.resolve(source, ref.Path, ref);
+    }
+    /**
+     * suggest lists candidate symbols for a not-found `ref`, dispatching to the
+     * per-language resolver by extension. It NEVER throws (suggestions are an
+     * enhancement, not a check): an unsupported extension, a missing file, a
+     * read/parse fault, or a resolver without suggest support all degrade to an
+     * empty candidate set. Call it only after resolve(root, ref) returned false.
+     */
+    async suggest(root, ref) {
+        const empty = { kind: refKind(ref), candidates: [] };
+        const sub = this.byExt.get(extname(ref.Path));
+        if (sub === undefined || sub.suggest === undefined) {
+            return empty;
+        }
+        let source;
+        try {
+            source = await this.cache.read(root, ref.Path);
+        }
+        catch {
+            return empty;
+        }
+        try {
+            return sub.suggest(source, ref.Path, ref);
+        }
+        catch {
+            return empty;
+        }
+    }
+}
+/**
+ * extname returns the file extension of a slash-separated path, INCLUDING the
+ * leading ".", matching Go's path.Ext (which operates on the final element after
+ * the last "/" and returns "" when there is no dot). We avoid node:path here
+ * because ref.Path is always slash-separated (io/fs convention), and path.Ext's
+ * semantics are simple enough to mirror exactly.
+ */
+function extname(p) {
+    const slash = p.lastIndexOf("/");
+    const base = slash >= 0 ? p.slice(slash + 1) : p;
+    const dot = base.lastIndexOf(".");
+    // A leading-dot-only basename (".foo") has no extension in path.Ext terms only
+    // if the dot is at index 0 AND there's no later dot — but path.Ext(".foo")
+    // returns ".foo". Mirror path.Ext exactly: it returns base[dot:] for the LAST
+    // dot, or "" if none.
+    return dot >= 0 ? base.slice(dot) : "";
+}
+/**
+ * createDefaultResolver eagerly loads all 5 vendored grammars, builds one
+ * resolver per language, and wires the by-extension dispatch table — the async
+ * analogue of Go's DefaultResolver() (internal/codeq/codeq_on.go).
+ *
+ * The extension map mirrors Go exactly:
+ *   .go → go, .java → java,
+ *   .ts → typescript grammar, .tsx → tsx grammar (DISTINCT grammars/queries),
+ *   .js → javascript, .jsx → javascript.
+ *
+ * Grammars load concurrently; per-language resolve() stays sync after this.
+ */
+export async function createDefaultResolver() {
+    // Annotate the tuple element type explicitly: a plain Promise.all over an array
+    // literal infers a tuple, so destructured elements stay Language (not
+    // Language | undefined as a Language[] would under noUncheckedIndexedAccess).
+    const [go, java, js, ts, tsx] = await Promise.all([
+        loadGrammar("go"),
+        loadGrammar("java"),
+        loadGrammar("javascript"),
+        loadGrammar("typescript"),
+        loadGrammar("tsx"),
+    ]);
+    const goR = createGoResolver(go);
+    const javaR = createJavaResolver(java);
+    const jsR = createJSResolver(js);
+    const tsR = createTSResolver(ts);
+    const tsxR = createTSResolver(tsx);
+    return new DefaultResolver(new Map([
+        [".go", goR],
+        [".java", javaR],
+        [".ts", tsR],
+        [".tsx", tsxR],
+        [".js", jsR],
+        [".jsx", jsR],
+    ]));
+}

package/dist/codeq/resolver.test.js

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { DefaultResolver, createDefaultResolver, } from "./resolver.js";
+import { FileNotFoundError, UnsupportedLanguageError } from "./errors.js";
+// WHY: DefaultResolver is the top-level routing seam (the analogue of Go's
+// byExtResolver). If it routes by the wrong extension, fails to surface
+// UnsupportedLanguage, or swallows FileNotFound, every code-ref check is
+// silently miscategorised. The per-language resolvers don't exist yet
+// (WireGate), so we inject FAKE resolvers via the constructor to test the
+// routing + error contract in isolation, exactly as Go's NewResolver(byExt) is
+// testable without the real tree-sitter resolvers.
+const enc = new TextEncoder();
+class MemFS {
+    files;
+    constructor(files) {
+        this.files = files;
+    }
+    async readFile(name) {
+        const content = this.files[name];
+        if (content === undefined) {
+            const err = new Error(`ENOENT: ${name}`);
+            err.code = "ENOENT";
+            throw err;
+        }
+        return enc.encode(content);
+    }
+    async readDir() {
+        return [];
+    }
+    sub() {
+        return this;
+    }
+}
+/** spyResolver records the (source, path) it was handed and returns `found`. */
+function spyResolver(found) {
+    const calls = [];
+    return {
+        calls,
+        resolve(source, path, ref) {
+            calls.push({ source, path, ref });
+            return found;
+        },
+    };
+}
+function ref(path, symbol) {
+    return { Path: path, Symbol: symbol, Member: "", Param: "" };
+}
+describe("DefaultResolver dispatch", () => {
+    it("routes by extension and hands the decoded source to the sub-resolver", async () => {
+        const go = spyResolver(true);
+        const r = new DefaultResolver(new Map([[".go", go]]));
+        const fs = new MemFS({ "pkg/foo.go": "package pkg\nfunc Bar(){}\n" });
+        const found = await r.resolve(fs, ref("pkg/foo.go", "Bar"));
+        expect(found).toBe(true);
+        expect(go.calls).toHaveLength(1);
+        // The sub-resolver receives the ALREADY-DECODED string (the async/sync split)
+        // and the path (for ParseFailedError construction), not an FS.
+        expect(go.calls[0].source).toBe("package pkg\nfunc Bar(){}\n");
+        expect(go.calls[0].path).toBe("pkg/foo.go");
+    });
+    it("returns the sub-resolver's false (absent symbol) verbatim", async () => {
+        const go = spyResolver(false);
+        const r = new DefaultResolver(new Map([[".go", go]]));
+        const fs = new MemFS({ "pkg/foo.go": "package pkg\n" });
+        expect(await r.resolve(fs, ref("pkg/foo.go", "Nope"))).toBe(false);
+    });
+    it("throws UnsupportedLanguageError for an unregistered extension", async () => {
+        // WHY: an unknown extension is NOT "symbol absent" — it means docgov has no
+        // grammar for it; the caller reports it differently. Mirrors Go returning
+        // ErrUnsupportedLanguage (wrapped with the ext).
+        const r = new DefaultResolver(new Map([[".go", spyResolver(true)]]));
+        const fs = new MemFS({ "other/baz.xyz": "whatever" });
+        await expect(r.resolve(fs, ref("other/baz.xyz", "Q"))).rejects.toBeInstanceOf(UnsupportedLanguageError);
+    });
+    it("propagates FileNotFoundError when the file is missing", async () => {
+        // WHY: a missing file is an operational failure distinct from absence; the
+        // dispatch must surface it rather than treating it as Found=false.
+        const r = new DefaultResolver(new Map([[".go", spyResolver(true)]]));
+        const fs = new MemFS({});
+        await expect(r.resolve(fs, ref("pkg/gone.go", "X"))).rejects.toBeInstanceOf(FileNotFoundError);
+    });
+    it("routes .ts and .tsx to their own (distinct) resolvers", async () => {
+        const ts = spyResolver(true);
+        const tsx = spyResolver(true);
+        const r = new DefaultResolver(new Map([
+            [".ts", ts],
+            [".tsx", tsx],
+        ]));
+        const fs = new MemFS({ "a.ts": "x", "b.tsx": "y" });
+        await r.resolve(fs, ref("a.ts", "X"));
+        await r.resolve(fs, ref("b.tsx", "Y"));
+        expect(ts.calls).toHaveLength(1);
+        expect(tsx.calls).toHaveLength(1);
+    });
+});
+describe("createDefaultResolver (wired)", () => {
+    it("loads all 5 grammars and returns a working DefaultResolver", async () => {
+        // WHY: the factory is the only place the 5 vendored wasm grammars are loaded
+        // and bound to per-language resolvers. If any grammar fails to load or a
+        // factory throws, this rejects — pinning that the wasm/load path stays on the
+        // critical path and that wiring produces a real (not half-built) resolver.
+        const r = await createDefaultResolver();
+        expect(r).toBeInstanceOf(DefaultResolver);
+    });
+    it("routes every Go-supported extension and rejects an unknown one", async () => {
+        // WHY: the extension map must mirror Go's DefaultResolver exactly
+        // (.go/.java/.ts/.tsx/.js/.jsx). A registered extension resolves (here:
+        // absent symbol -> false, NOT UnsupportedLanguage); an unmapped one throws
+        // UnsupportedLanguageError. This catches a dropped or mis-spelled map entry.
+        const r = await createDefaultResolver();
+        const fs = new MemFS({
+            "a.go": "package a\n",
+            "B.java": "class B {}\n",
+            "c.ts": "export const c = 1;\n",
+            "d.tsx": "export const d = 1;\n",
+            "e.js": "export const e = 1;\n",
+            "f.jsx": "export const f = 1;\n",
+        });
+        for (const path of ["a.go", "B.java", "c.ts", "d.tsx", "e.js", "f.jsx"]) {
+            // A missing symbol must come back false (extension WAS routed), not throw.
+            expect(await r.resolve(fs, ref(path, "Absent"))).toBe(false);
+        }
+        await expect(r.resolve(new MemFS({ "g.rb": "x" }), ref("g.rb", "X"))).rejects.toBeInstanceOf(UnsupportedLanguageError);
+    });
+});

package/dist/codeq/resolvers/go.js

@@ -0,0 +1,242 @@
+// go.ts ports internal/codeq/go_lang.go + go_queries.go: the Go per-language
+// Resolver. It is a faithful port of the *goResolver Resolve body MINUS the
+// cache.Read + ErrFileNotFound prelude (the dispatch layer owns I/O), per the
+// async/sync split recorded in resolver.ts.
+//
+// The query S-expressions below are VERBATIM from go_queries.go — the upstream
+// tree-sitter-go node-type names match the vendored wasm grammar, so the Go
+// queries port unchanged. Queries are compiled ONCE at factory time (the
+// analogue of Go's package-level mustQuery vars) and reused across parses.
+import { ParseFailedError } from "../errors.js";
+import { signaturesMatch } from "../signature.js";
+import { collectCapture, collectOwned, refKind, suggestFromExtractors, } from "../suggest.js";
+import { Parser, compileQuery, nodeText, parseTree, runQuery, } from "../treesitter.js";
+// goSymbolQuery matches top-level function, type, var, and const declarations.
+// Each match has a single capture named "name" with the declared identifier.
+const GO_SYMBOL_QUERY = `
+(function_declaration name: (identifier) @name)
+(type_declaration (type_spec name: (type_identifier) @name))
+(var_declaration (var_spec name: (identifier) @name))
+(const_declaration (const_spec name: (identifier) @name))
+`;
+// goMemberQuery matches struct fields and method declarations.
+// Each match provides @owner (the type name) and @name (field or method name).
+// Note: the method pattern binds the receiver TYPE via (type_identifier),
+// i.e. a VALUE receiver "(b Baz)" — a POINTER receiver "(b *Baz)" parses the
+// receiver type as (pointer_type ...), which (type_identifier) does not match,
+// so pointer-receiver methods do NOT resolve as members. This is intentional
+// and preserved from the Go original.
+const GO_MEMBER_QUERY = `
+(type_declaration (type_spec name: (type_identifier) @owner (struct_type (field_declaration_list (field_declaration name: (field_identifier) @name)))))
+(method_declaration receiver: (parameter_list (parameter_declaration type: (type_identifier) @owner)) name: (field_identifier) @name)
+`;
+// goMemberDeclQuery matches method declarations on named receiver types.
+// Each match provides @owner (receiver type name), @mname (method name), and
+// @mdecl (the full method_declaration node — used to walk parameter types for
+// overload disambiguation by signature). Same value-receiver caveat as above.
+const GO_MEMBER_DECL_QUERY = `
+(method_declaration receiver: (parameter_list (parameter_declaration type: (type_identifier) @owner)) name: (field_identifier) @mname) @mdecl
+`;
+// goParamQuery matches parameters of function and method declarations.
+// Each match provides @fn (the function or method name) and @param (the
+// parameter name).
+const GO_PARAM_QUERY = `
+(function_declaration name: (identifier) @fn parameters: (parameter_list (parameter_declaration name: (identifier) @param)))
+(method_declaration name: (field_identifier) @fn parameters: (parameter_list (parameter_declaration name: (identifier) @param)))
+`;
+/**
+ * createGoResolver builds the Go Resolver from an already-loaded tree-sitter
+ * Language. It compiles all four queries eagerly (compileQuery throws on a bad
+ * query — the mustQuery-panic contract) and returns a sync Resolver. The
+ * compiled queries are captured in the closure and reused across every parse,
+ * mirroring Go's package-level mustQuery vars.
+ */
+export function createGoResolver(language) {
+    const symbolQuery = compileQuery(language, GO_SYMBOL_QUERY);
+    const memberQuery = compileQuery(language, GO_MEMBER_QUERY);
+    const memberDeclQuery = compileQuery(language, GO_MEMBER_DECL_QUERY);
+    const paramQuery = compileQuery(language, GO_PARAM_QUERY);
+    return {
+        resolve(source, path, ref) {
+            // Per-call parser — cheap to create. parse/matches are sync post-init.
+            const parser = new Parser();
+            parser.setLanguage(language);
+            const root = parseTree(parser, source);
+            // Invalid Go produces ERROR nodes, not a parse failure. This is what the
+            // resolver maps to ParseFailedError (Go's ErrParseFailed) so callers can
+            // distinguish "could not check" from "symbol genuinely absent".
+            if (root.hasError) {
+                throw new ParseFailedError(path);
+            }
+            // Dispatch on ref facets EXACTLY as go_lang.go's Resolve switch does:
+            // Member → findMember, else Param → findParam, else findSymbol.
+            if (ref.Member !== "") {
+                return findMember(root, memberQuery, memberDeclQuery, ref.Symbol, ref.Member, ref.Signature);
+            }
+            if (ref.Param !== "") {
+                return findParam(root, paramQuery, ref.Symbol, ref.Param);
+            }
+            return findSymbol(root, symbolQuery, ref.Symbol);
+        },
+        suggest(source, _path, ref) {
+            const parser = new Parser();
+            parser.setLanguage(language);
+            const root = parseTree(parser, source);
+            // Unlike resolve, a malformed tree is not an error here — just no candidates.
+            if (root.hasError) {
+                return { kind: refKind(ref), candidates: [] };
+            }
+            const ex = {
+                symbolNames: (r) => collectCapture(r, symbolQuery, "name"),
+                memberNames: (r, owner) => collectOwned(r, memberQuery, owner, "owner", "name"),
+                paramNames: (r, fn) => collectOwned(r, paramQuery, fn, "fn", "param"),
+            };
+            return suggestFromExtractors(root, ref, ex);
+        },
+    };
+}
+/**
+ * findSymbol searches for a top-level declaration with the given name. Returns
+ * true when found, false when absent.
+ */
+function findSymbol(root, symbolQuery, name) {
+    for (const m of runQuery(root, symbolQuery)) {
+        const n = m.captures["name"];
+        if (n !== undefined && nodeText(n) === name) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * findMember searches for a struct field or method named member on symbol.
+ *
+ * When sig is undefined (name-only), the flat member query matches fields and
+ * methods by name. When sig is defined (including the zero-arg empty array),
+ * only method declarations whose parameter types satisfy signaturesMatch are
+ * considered — struct fields have no signature and are never matched in this
+ * branch. Returns true when found, false when absent.
+ */
+function findMember(root, memberQuery, memberDeclQuery, symbol, member, sig) {
+    if (sig === undefined) {
+        // Name-only: flat member query (matches fields and value-receiver methods).
+        for (const m of runQuery(root, memberQuery)) {
+            const owner = m.captures["owner"];
+            const name = m.captures["name"];
+            if (owner !== undefined &&
+                name !== undefined &&
+                nodeText(owner) === symbol &&
+                nodeText(name) === member) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // Signature-filtered: iterate method declarations and check param types.
+    for (const m of runQuery(root, memberDeclQuery)) {
+        const owner = m.captures["owner"];
+        const mname = m.captures["mname"];
+        const mdecl = m.captures["mdecl"];
+        if (owner !== undefined &&
+            mname !== undefined &&
+            mdecl !== undefined &&
+            nodeText(owner) === symbol &&
+            nodeText(mname) === member &&
+            signaturesMatch(sig, collectGoParamTypes(mdecl))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * findParam searches for a parameter named param on a function or method named
+ * symbol. Returns true when found, false when absent.
+ */
+function findParam(root, paramQuery, symbol, param) {
+    for (const m of runQuery(root, paramQuery)) {
+        const fn = m.captures["fn"];
+        const pname = m.captures["param"];
+        if (fn !== undefined &&
+            pname !== undefined &&
+            nodeText(fn) === symbol &&
+            nodeText(pname) === param) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * collectGoParamTypes walks a method_declaration or function_declaration node
+ * and returns the declared parameter types in document order. Grouped params
+ * (a, b int) repeat the shared type once per declared name so the returned
+ * arity is correct. Variadic params (xs ...string) are collected as the Go
+ * slice form "[]string" — the effective type a doc author writes — since Go's
+ * ... is a prefix qualifier, not a suffix.
+ *
+ * A method_declaration has two parameter_list children: the first is the
+ * receiver list ("(c Ctl)"), the second is the parameter list. A
+ * function_declaration has only one parameter_list child. We take the LAST
+ * parameter_list to skip the receiver in both cases.
+ */
+function collectGoParamTypes(decl) {
+    // Collect all parameter_list children; the parameters list is the last one
+    // (for method_declaration the first is the receiver; function_declaration has
+    // only one).
+    const paramLists = [];
+    for (let i = 0; i < decl.childCount; i++) {
+        const c = decl.child(i);
+        if (c !== null && c.type === "parameter_list") {
+            paramLists.push(c);
+        }
+    }
+    if (paramLists.length === 0) {
+        return [];
+    }
+    const pl = paramLists[paramLists.length - 1];
+    const types = [];
+    for (let i = 0; i < pl.childCount; i++) {
+        const pd = pl.child(i);
+        if (pd === null) {
+            continue;
+        }
+        if (pd.type === "parameter_declaration") {
+            // Count identifier children (names) to handle grouped params (a, b int).
+            // The type node is the last non-comma, non-identifier child.
+            let nameCount = 0;
+            let typeNode = null;
+            for (let j = 0; j < pd.childCount; j++) {
+                const c = pd.child(j);
+                if (c === null) {
+                    continue;
+                }
+                if (c.type === "identifier") {
+                    nameCount++;
+                }
+                else if (c.type !== ",") {
+                    // Anything that isn't a name identifier or comma is the type.
+                    typeNode = c;
+                }
+            }
+            if (typeNode === null) {
+                continue;
+            }
+            // Clamp nameCount to at least 1 (unnamed params like "_ int" / "int").
+            if (nameCount === 0) {
+                nameCount = 1;
+            }
+            const typeText = nodeText(typeNode);
+            for (let k = 0; k < nameCount; k++) {
+                types.push(typeText);
+            }
+        }
+        else if (pd.type === "variadic_parameter_declaration") {
+            // xs ...string: the "type" field is the element type node. The effective
+            // Go type is []elementType (what a doc author writes).
+            const tn = pd.childForFieldName("type");
+            if (tn !== null) {
+                types.push("[]" + nodeText(tn));
+            }
+        }
+    }
+    return types;
+}