code-auditor-mcp 4.1.1 → 5.0.2

package/dist/languages/go/goResolution.js

@@ -0,0 +1,799 @@
+/**
+ * Go receiver resolution — Spec 69 §10 S5e (#369).
+ *
+ * The Go half of the three-way receiver disposition. It answers the same
+ * question the TypeScript processor (`analyzers/receiverRoot.ts`) answers —
+ * "does this identifier resolve to a DB handle, a definitively non-DB value, or
+ * something undetermined?" — using Go's own declaration grammar:
+ *
+ *   • `parameter_declaration`   — `db *sql.DB` (function params AND method
+ *                                  receivers; both are parameter_declarations).
+ *   • `var_spec`                 — package-level `var db *sql.DB`.
+ *   • `short_var_declaration`    — `db, err := sql.Open(...)` / `c := New()`.
+ *   • `field_declaration`        — struct field `db *sql.DB`.
+ *   • `function_declaration` / `method_declaration` — the return-type half of
+ *                                  form-5: `func New() *Engine` resolves a
+ *                                  `router := New()` receiver to not-a-handle.
+ *
+ * The ecosystem list lives HERE with the Go adapter — not in a shared constant
+ * and not in the TypeScript implementation's `DB_PACKAGES` (tsEcosystem.ts,
+ * which is npm/TypeScript only). A
+ * name is a *handle* because it resolved to the `database/sql` package (the
+ * parsed SQL argument proves the handle, not the type name), never because it
+ * *looks* like `db`; a name is
+ * *not-a-handle* because it resolved to a local type/primitive or an ambient
+ * global, never because it is on a list. A name that resolved to an
+ * *unrecognized* package (a non-`database/sql` import such as `gin`, `net/http`,
+ * `testing`) is `unproven` — Spec 70 R4 reports `cannot-fire` for a package the
+ * manifest does not recognize, rather than guessing it is not a DB client.
+ *
+ * The functions here are pure and parser-agnostic at their boundary: they take
+ * the already-parsed `AST` + adapter, so the analyzer layer (`receiverResolution.ts`)
+ * dispatches to them the same way it dispatches to the TypeScript processor.
+ */
+import { getRawNode } from '../tree-sitter/rawNode.js';
+import databasePackages from './database-packages.json' with { type: 'json' };
+import stdlibPackages from './stdlib-packages.json' with { type: 'json' };
+/**
+ * Package paths whose types are DB handles. Go-only, stdlib-first.
+ *
+ * Spec 70 R4 / criterion 10: loaded from the per-ecosystem manifest
+ * (`src/languages/go/database-packages.json`, beside the format adapter), a
+ * declarative data file holding import paths only. An unlisted package reached
+ * by resolution reports `cannot-fire` (see `classifyGoRootIdentifier` /
+ * `classifyGoTypeText`), never a guessed `not-handle`.
+ */
+export const GO_DB_PACKAGES = new Set(databasePackages);
+/**
+ * Go standard-library import paths — the authoritative `go list std` snapshot
+ * (committed from `scripts/generate-go-stdlib.mjs`, not hand-edited). A receiver
+ * whose import path resolves to a stdlib package (`fmt`, `strings`, `net/http`,
+ * `reflect`, …) is `not-handle` — it cannot be a database client. This is the
+ * package discriminant's `not-handle` half for Go, replacing the deleted method-
+ * name surface: the *package* a receiver resolves to proves it is not a DB handle,
+ * never the method name (criterion: the method name cannot discriminate).
+ */
+export const GO_STDLIB_PACKAGES = new Set(stdlibPackages);
+/** Unqualified builtin types that are definitively not a DB handle. */
+const GO_NON_HANDLE_TYPES = new Set([
+    'bool',
+    'byte',
+    'complex64',
+    'complex128',
+    'error',
+    'float32',
+    'float64',
+    'int',
+    'int8',
+    'int16',
+    'int32',
+    'int64',
+    'rune',
+    'string',
+    'uint',
+    'uint8',
+    'uint16',
+    'uint32',
+    'uint64',
+    'uintptr',
+    'any',
+    'nil',
+]);
+/**
+ * Project a live tree-sitter value node onto a {@link GoValueDescriptor}. Bounded
+ * to `depth` named-field hops — `classifyGoValue` reads at most `call_expression
+ * → function → operand` (two hops), so depth 4 is more than sufficient while
+ * guarding against pathological nesting.
+ */
+function describeGoValue(raw, depth = 4) {
+    // tree-sitter-go wraps even a single `const`/`var` value in an
+    // `expression_list` (`const x = `…`` → the `value` field is `expression_list`
+    // whose only named child is the `raw_string_literal`). Unwrap a one-element
+    // list so the descriptor carries the literal/expression itself, not the wrapper.
+    if (raw.type === 'expression_list') {
+        const children = raw.namedChildren ?? [];
+        if (children.length === 1)
+            return describeGoValue(children[0], depth - 1);
+    }
+    const child = (field) => {
+        if (depth <= 0)
+            return null;
+        const c = raw.childForFieldName(field);
+        return c ? describeGoValue(c, depth - 1) : null;
+    };
+    return {
+        type: raw.type,
+        text: raw.text ?? '',
+        function: child('function'),
+        operand: child('operand'),
+        typeNode: child('type'),
+    };
+}
+// ── Import resolution ────────────────────────────────────────────────────────
+/** The package name for an import path when no explicit alias is present. */
+function defaultPackageName(source) {
+    const parts = source.split('/');
+    return parts[parts.length - 1] || source;
+}
+/** Strip surrounding quotes from a Go string-literal node text. */
+function unquote(text) {
+    if (text.length >= 2 && (text[0] === '"' || text[0] === '`')) {
+        return text.slice(1, -1);
+    }
+    return text;
+}
+/**
+ * Build the package-name → import-path map for one Go file.
+ *
+ * Handles both `import "database/sql"` (single) and the parenthesized
+ * `import ( "database/sql"; alias "fmt" )` form — the latter is the shape
+ * `adapter.extractImports` misses (its `import_declaration` iteration only
+ * sees the `import_spec_list` wrapper, not the `import_spec` children). Dot and
+ * blank imports (`. "x"`, `_ "x"`) are skipped: they contribute no package name.
+ *
+ * @param ast the parsed Go file AST
+ * @param adapter the language adapter used to find `import_spec` nodes
+ * @returns the package-name → import-path map for this file
+ */
+export function buildGoImportMap(ast, adapter) {
+    const imports = new Map();
+    const specs = adapter.findNodes(ast, { custom: (n) => n.type === 'import_spec' });
+    for (const spec of specs) {
+        const raw = getRawNode(spec);
+        const pathNode = raw.childForFieldName('path');
+        if (!pathNode)
+            continue;
+        const source = unquote(pathNode.text);
+        if (!source)
+            continue;
+        const nameNode = raw.childForFieldName('name');
+        let pkgName;
+        if (!nameNode) {
+            pkgName = defaultPackageName(source);
+        }
+        else if (nameNode.type === 'package_identifier' || nameNode.type === 'identifier') {
+            pkgName = nameNode.text;
+        }
+        else {
+            continue; // dot or blank import — no package name to resolve
+        }
+        if (pkgName)
+            imports.set(pkgName, source);
+    }
+    return imports;
+}
+// ── Binding extraction ───────────────────────────────────────────────────────
+/**
+ * Build the per-file binding environment: imports, parameters (incl. method
+ * receivers), package/local vars, short-vars, struct fields, function/method
+ * return types, and local type declarations.
+ *
+ * @param ast the parsed Go file AST
+ * @param adapter the language adapter used to walk nodes
+ * @param sourceCode the file source text for reading node text
+ * @returns the name → binding map for every name bound in the file
+ */
+export function buildGoBindingEnv(ast, adapter, sourceCode) {
+    const bindings = new Map();
+    const imports = buildGoImportMap(ast, adapter);
+    for (const [pkgName, source] of imports) {
+        if (!bindings.has(pkgName))
+            bindings.set(pkgName, { kind: 'import', source });
+    }
+    const rawWalk = (node, visit) => {
+        visit(getRawNode(node));
+        for (const child of adapter.getChildren(node))
+            rawWalk(child, visit);
+    };
+    rawWalk(ast.root, (raw) => {
+        switch (raw.type) {
+            case 'parameter_declaration': {
+                const nameNode = raw.childForFieldName('name');
+                const typeNode = raw.childForFieldName('type');
+                if (nameNode && !bindings.has(nameNode.text)) {
+                    bindings.set(nameNode.text, {
+                        kind: 'parameter',
+                        typeText: typeNode?.text,
+                    });
+                }
+                break;
+            }
+            case 'var_spec': {
+                const nameNode = raw.childForFieldName('name');
+                const typeNode = raw.childForFieldName('type');
+                const valueNode = raw.childForFieldName('value');
+                if (nameNode && !bindings.has(nameNode.text)) {
+                    bindings.set(nameNode.text, {
+                        kind: 'variable',
+                        typeText: typeNode?.text,
+                        value: valueNode ? describeGoValue(valueNode) : undefined,
+                    });
+                }
+                break;
+            }
+            case 'short_var_declaration': {
+                const left = raw.childForFieldName('left');
+                const right = raw.childForFieldName('right');
+                const rightExprs = right?.namedChildren ?? [];
+                const singleRight = rightExprs.length === 1 ? rightExprs[0] : null;
+                for (const id of left?.namedChildren ?? []) {
+                    if (id.type !== 'identifier' || bindings.has(id.text))
+                        continue;
+                    bindings.set(id.text, {
+                        kind: 'variable',
+                        value: singleRight ? describeGoValue(singleRight) : undefined,
+                    });
+                }
+                break;
+            }
+            case 'field_declaration': {
+                const nameNode = raw.childForFieldName('name');
+                const typeNode = raw.childForFieldName('type');
+                const valueNode = raw.childForFieldName('value');
+                if (nameNode && !bindings.has(nameNode.text)) {
+                    bindings.set(nameNode.text, {
+                        kind: 'field',
+                        typeText: typeNode?.text,
+                        value: valueNode ? describeGoValue(valueNode) : undefined,
+                    });
+                }
+                break;
+            }
+            case 'type_spec': {
+                const nameNode = raw.childForFieldName('name');
+                if (nameNode && !bindings.has(nameNode.text)) {
+                    bindings.set(nameNode.text, { kind: 'type' });
+                }
+                break;
+            }
+            case 'const_spec': {
+                // A package-level `const` — the sqlc-generated SQL surface: sqlc emits
+                // `const getAllUsers = `-- name: GetAllUsers :many\nSELECT …`` and the
+                // query method references it by identifier
+                // (`q.db.QueryContext(ctx, getAllUsers)`). The value is a literal; store
+                // it as a serializable descriptor so the analyzer can unquote it with
+                // `stripSqlQuotes` (raw strings are literal, interpreted strings un-escape).
+                const nameNode = raw.childForFieldName('name');
+                const valueNode = raw.childForFieldName('value');
+                if (nameNode && !bindings.has(nameNode.text)) {
+                    bindings.set(nameNode.text, {
+                        kind: 'const',
+                        value: valueNode ? describeGoValue(valueNode) : undefined,
+                    });
+                }
+                break;
+            }
+            case 'function_declaration':
+            case 'method_declaration': {
+                const nameNode = raw.childForFieldName('name');
+                const resultNode = raw.childForFieldName('result');
+                if (nameNode && !bindings.has(nameNode.text)) {
+                    bindings.set(nameNode.text, {
+                        kind: raw.type === 'method_declaration' ? 'method' : 'function',
+                        returnTypeText: resultNode?.text,
+                    });
+                }
+                break;
+            }
+        }
+    });
+    return bindings;
+}
+/**
+ * Build a *package-scope* symbol table from a set of Go files in the same
+ * package: top-level `function_declaration`/`method_declaration` (name + return
+ * type), `type_declaration` → `type_spec` (name), and `var_declaration` →
+ * `var_spec` (name + type + value). Local declarations (params, short-vars,
+ * fields inside function bodies) are deliberately excluded — those are file/scope
+ * local and must never bleed across files.
+ *
+ * This is the Go equivalent of the TS cross-file in-repo resolution: an
+ * unqualified package-level call like `New()` / `CreateTestContext()` in one
+ * file resolves through the symbol declared in a *sibling* file, so its return
+ * type (`*Engine` / `*Context`) drives the receiver disposition instead of
+ * `unproven`.
+ *
+ * @param files the Go files (AST + adapter) that share this package
+ * @returns the package-scope name → binding symbol table
+ */
+export function buildGoPackageBindings(files) {
+    const bindings = new Map();
+    for (const { ast } of files) {
+        for (const [name, binding] of buildGoFileBindings(ast)) {
+            if (!bindings.has(name))
+                bindings.set(name, binding);
+        }
+    }
+    return bindings;
+}
+/**
+ * Extract one Go file's *package-scope* declarations — the per-file half of
+ * {@link buildGoPackageBindings}. Spec 70 Item 4 (2a): the phase model lifts
+ * this per-file extraction into the `go-package-bindings` file fact so the
+ * cross-file fixed point can group files by directory and merge first-wins,
+ * exactly as {@link buildGoPackageBindings} does, with no AST outliving its
+ * file. The bindings returned are `GoBinding` (already a serializable
+ * projection: `value` is a {@link GoValueDescriptor}, not a live node).
+ *
+ * @param ast the parsed Go file AST
+ * @returns this file's package-scope name → binding symbol table
+ */
+export function buildGoFileBindings(ast) {
+    const bindings = new Map();
+    const root = getRawNode(ast.root);
+    for (const decl of root.namedChildren) {
+        switch (decl.type) {
+            case 'function_declaration':
+            case 'method_declaration': {
+                const nameNode = decl.childForFieldName('name');
+                const resultNode = decl.childForFieldName('result');
+                if (nameNode && !bindings.has(nameNode.text)) {
+                    bindings.set(nameNode.text, {
+                        kind: decl.type === 'method_declaration' ? 'method' : 'function',
+                        returnTypeText: resultNode?.text,
+                    });
+                }
+                break;
+            }
+            case 'type_declaration': {
+                for (const spec of decl.namedChildren) {
+                    if (spec.type !== 'type_spec')
+                        continue;
+                    const nameNode = spec.childForFieldName('name');
+                    if (nameNode && !bindings.has(nameNode.text)) {
+                        bindings.set(nameNode.text, { kind: 'type' });
+                    }
+                }
+                break;
+            }
+            case 'var_declaration': {
+                for (const spec of decl.namedChildren) {
+                    if (spec.type !== 'var_spec')
+                        continue;
+                    const nameNode = spec.childForFieldName('name');
+                    const typeNode = spec.childForFieldName('type');
+                    const valueNode = spec.childForFieldName('value');
+                    if (nameNode && !bindings.has(nameNode.text)) {
+                        bindings.set(nameNode.text, {
+                            kind: 'variable',
+                            typeText: typeNode?.text,
+                            value: valueNode ? describeGoValue(valueNode) : undefined,
+                        });
+                    }
+                }
+                break;
+            }
+        }
+    }
+    return bindings;
+}
+// ── Classification ───────────────────────────────────────────────────────────
+/** Resolve a package name to its import path (or null when not imported). */
+function resolvePackage(pkgName, env) {
+    return env.imports.get(pkgName) ?? null;
+}
+/**
+ * The first return *type* of a Go function signature text, e.g.
+ * `(*sql.DB, error)` → `*sql.DB`, `*Engine` → `*Engine`,
+ * `(c *Context, r *Engine)` → `*Context` (named results). Handles three shapes:
+ *
+ *   1. bare      — `*Engine`, `error`, `map[string]*sql.DB`
+ *   2. parens    — `(*sql.DB, error)` → strip the outer parens, take first
+ *   3. named     — `(c *Context, r *Engine)` → drop the leading result *name*,
+ *                  keep its type
+ *
+ * Splits on top-level commas (tracking paren/bracket/brace depth) so
+ * `map[string]*sql.DB` and `func() error` stay whole.
+ */
+function firstReturnType(resultText) {
+    let t = resultText.trim();
+    // Strip a single outer paren group: `(c *Context, r *Engine)` →
+    // `c *Context, r *Engine`, `(*sql.DB, error)` → `*sql.DB, error`.
+    if (t.startsWith('(') && t.endsWith(')'))
+        t = t.slice(1, -1).trim();
+    let depth = 0;
+    let first = '';
+    for (const ch of t) {
+        if (ch === '(' || ch === '[' || ch === '{')
+            depth++;
+        if (ch === ')' || ch === ']' || ch === '}')
+            depth--;
+        if (ch === ',' && depth === 0)
+            break;
+        first += ch;
+    }
+    first = first.trim();
+    // Named result: `c *Context` → the name is a plain identifier prefix, the type
+    // is the rest. A bare type like `*Context` / `map[K]V` / `chan int` has no
+    // such leading identifier, and `map`/`chan`/`func`/`struct`/`interface` are
+    // type keywords, never result names.
+    const named = first.match(/^([A-Za-z_][A-Za-z0-9_]*)\s+(.+)$/s);
+    if (named && !/^(map|chan|func|struct|interface)$/.test(named[1])) {
+        return named[2].trim();
+    }
+    return first;
+}
+/**
+ * Classify a bare Go root identifier's disposition under the file's env.
+ *
+ * @param name the bare root identifier to classify
+ * @param env the file's Go resolution environment (provenance, bindings, imports)
+ * @param depth recursion guard; classification gives up past depth 8
+ * @returns `handle`, `not-handle`, or `unproven`
+ */
+export function classifyGoRootIdentifier(name, env, depth = 0) {
+    if (!name)
+        return 'unproven';
+    if (env.provenance.has(name))
+        return 'handle';
+    if (depth > 8)
+        return 'unproven';
+    const binding = env.bindings.get(name) ?? env.packageBindings?.get(name);
+    if (!binding)
+        return 'not-handle'; // ambient global → not-handle
+    switch (binding.kind) {
+        case 'import': {
+            const source = binding.source ?? '';
+            // A DB package proves handle; a stdlib package proves not-handle (it cannot
+            // be a DB client); any other package is unrecognized, not a DB client, or a
+            // DB client we do not list — all `unproven` (cannot-fire), never a guessed
+            // `not-handle` (Spec 70 R4).
+            return GO_DB_PACKAGES.has(source)
+                ? 'handle'
+                : GO_STDLIB_PACKAGES.has(source)
+                    ? 'not-handle'
+                    : 'unproven';
+        }
+        case 'variable':
+        case 'field':
+            if (binding.typeText)
+                return classifyGoTypeText(binding.typeText, env, depth);
+            if (binding.value)
+                return classifyGoValue(binding.value, env, depth);
+            return 'unproven';
+        case 'parameter':
+            if (binding.typeText)
+                return classifyGoTypeText(binding.typeText, env, depth);
+            return 'unproven';
+        case 'function':
+        case 'method':
+            if (binding.returnTypeText) {
+                return classifyGoTypeText(firstReturnType(binding.returnTypeText), env, depth + 1);
+            }
+            return 'unproven';
+        case 'type':
+            // A local type name is definitively not a DB handle (unless provenanced,
+            // checked above).
+            return 'not-handle';
+        case 'const':
+            // A `const` can only hold a compile-time literal (string/number/bool),
+            // never a DB handle, so it is definitively not a handle (unless provenanced,
+            // checked above). The sqlc SQL const reaches the parser via the SQL-argument
+            // source's `extractStaticSql` const resolution, not via this classifier.
+            return 'not-handle';
+    }
+}
+/**
+ * Classify a Go type text (`*sql.DB`, `sql.DB`, `*gin.Context`, `string`).
+ * Strips pointer/slice prefixes, then dispatches on qualified (`pkg.Type`) vs
+ * unqualified (`Type` / builtin).
+ *
+ * @param typeText the Go type expression to classify
+ * @param env the file's Go resolution environment
+ * @param depth recursion guard
+ * @returns `handle`, `not-handle`, or `unproven`
+ */
+export function classifyGoTypeText(typeText, env, depth) {
+    let t = typeText.trim();
+    // Strip leading pointer (`*sql.DB`) and slice/array (`[]byte`, `[4]string`)
+    // prefixes. The slice regex is anchored to a leading `[`, so a `map[K]V` type
+    // (no leading `[`) is left untouched.
+    for (;;) {
+        if (t.startsWith('*')) {
+            t = t.slice(1).trim();
+            continue;
+        }
+        const slice = t.match(/^\[(\d*)\](.*)$/s);
+        if (slice) {
+            t = slice[2].trim();
+            continue;
+        }
+        break;
+    }
+    const dot = t.indexOf('.');
+    if (dot > 0 && !/[\s()\[\]{},*]/.test(t)) {
+        // Qualified type: `pkg.Type`. Handle-ness follows the *package* (the
+        // `database/sql` import path), never the type name — the parsed SQL argument
+        // is the handle proof; the package is the resolution fallback.
+        const pkgName = t.slice(0, dot);
+        const source = resolvePackage(pkgName, env);
+        if (source === null)
+            return 'unproven'; // package not imported → unknown
+        if (GO_DB_PACKAGES.has(source))
+            return 'handle';
+        if (GO_STDLIB_PACKAGES.has(source))
+            return 'not-handle'; // stdlib → not a DB client
+        return 'unproven'; // unrecognized package → cannot-fire (Spec 70 R4)
+    }
+    // Unqualified: a builtin or a local named type.
+    if (GO_NON_HANDLE_TYPES.has(t))
+        return 'not-handle';
+    return classifyGoRootIdentifier(t, env, depth + 1);
+}
+/**
+ * Classify a Go value expression's disposition (an initializer). A call to a
+ * function whose return type is known resolves through it — `c := New()` where
+ * `New() *Engine` is not-a-handle, `db := sql.Open(...)` is a handle.
+ */
+function classifyGoValue(raw, env, depth) {
+    if (raw.type === 'identifier') {
+        return classifyGoRootIdentifier(raw.text, env, depth + 1);
+    }
+    if (raw.type === 'call_expression') {
+        const fnNode = raw.function;
+        if (fnNode?.type === 'identifier') {
+            const name = fnNode.text;
+            if (env.provenance.has(name))
+                return 'handle';
+            const b = env.bindings.get(name) ?? env.packageBindings?.get(name);
+            if (b && (b.kind === 'function' || b.kind === 'method') && b.returnTypeText) {
+                return classifyGoTypeText(firstReturnType(b.returnTypeText), env, depth + 1);
+            }
+            return 'unproven';
+        }
+        if (fnNode?.type === 'selector_expression') {
+            const operand = fnNode.operand;
+            const root = operand?.text ?? '';
+            if (root && env.provenance.has(root))
+                return 'handle';
+            const b = env.bindings.get(root);
+            if (b && b.kind === 'import') {
+                const source = b.source ?? '';
+                if (GO_DB_PACKAGES.has(source))
+                    return 'handle';
+                if (GO_STDLIB_PACKAGES.has(source))
+                    return 'not-handle';
+                return 'unproven';
+            }
+            return 'unproven';
+        }
+        return 'unproven';
+    }
+    if (raw.type === 'selector_expression') {
+        const operand = raw.operand;
+        if (operand?.type === 'identifier')
+            return classifyGoRootIdentifier(operand.text, env, depth + 1);
+        return 'unproven';
+    }
+    if (raw.type === 'unary_expression') {
+        // `&Context{}` / `&sql.DB{}` — classify the operand (the address-of target).
+        const operand = raw.operand;
+        if (operand) {
+            const opText = operand.text;
+            if (opText)
+                return classifyGoTypeText(opText, env, depth + 1);
+        }
+        return 'unproven';
+    }
+    if (raw.type === 'composite_literal') {
+        const typeNode = raw.typeNode;
+        if (typeNode?.text)
+            return classifyGoTypeText(typeNode.text, env, depth + 1);
+        return 'unproven';
+    }
+    if (raw.type === 'interpreted_string_literal' ||
+        raw.type === 'raw_string_literal' ||
+        raw.type === 'int_literal' ||
+        raw.type === 'float_literal' ||
+        raw.type === 'true' ||
+        raw.type === 'false' ||
+        raw.type === 'nil') {
+        return 'not-handle';
+    }
+    return 'unproven';
+}
+// ── Unproven reason (Go) ─────────────────────────────────────────────────────
+/** The package path a qualified type text (`*ent.Client`, `sqlx.DB`) resolves to,
+ *  when that package is imported but absent from the database-packages manifest.
+ *  Mirrors `classifyGoTypeText`'s pointer/slice stripping + qualified-type
+ *  package resolution, but returns the *source* instead of the disposition. */
+function unrecognizedPackageInType(typeText, env) {
+    let t = typeText.trim();
+    for (;;) {
+        if (t.startsWith('*')) {
+            t = t.slice(1).trim();
+            continue;
+        }
+        const slice = t.match(/^\[(\d*)\](.*)$/s);
+        if (slice) {
+            t = slice[2].trim();
+            continue;
+        }
+        break;
+    }
+    const dot = t.indexOf('.');
+    if (dot > 0 && !/[\s()\[\]{},*]/.test(t)) {
+        const pkgName = t.slice(0, dot);
+        const source = resolvePackage(pkgName, env);
+        if (source !== null && !GO_DB_PACKAGES.has(source))
+            return source;
+    }
+    return null;
+}
+/** The package path a value/initializer descriptor resolves to when that package
+ *  is imported but absent from the manifest (`client, _ := ent.Open(…)` → `ent` →
+ *  `entgo.io/ent`). Mirrors `classifyGoValue`'s selector/identifier/type arms. */
+function unrecognizedPackageInValue(raw, env, depth) {
+    if (depth > 8)
+        return null;
+    if (raw.type === 'selector_expression') {
+        if (raw.operand?.type === 'identifier') {
+            const b = env.bindings.get(raw.operand.text) ?? env.packageBindings?.get(raw.operand.text);
+            if (b?.kind === 'import')
+                return b.source && !GO_DB_PACKAGES.has(b.source) ? b.source : null;
+        }
+        return null;
+    }
+    if (raw.type === 'call_expression') {
+        const fn = raw.function;
+        if (!fn)
+            return null;
+        if (fn.type === 'identifier') {
+            const b = env.bindings.get(fn.text) ?? env.packageBindings?.get(fn.text);
+            if (b && (b.kind === 'function' || b.kind === 'method') && b.returnTypeText) {
+                return unrecognizedPackageInType(firstReturnType(b.returnTypeText), env);
+            }
+            return null;
+        }
+        return unrecognizedPackageInValue(fn, env, depth + 1);
+    }
+    if (raw.type === 'unary_expression' || raw.type === 'composite_literal') {
+        if (raw.typeNode?.text)
+            return unrecognizedPackageInType(raw.typeNode.text, env);
+        return null;
+    }
+    return null;
+}
+/** The package path a binding resolves to when it is imported but absent from the
+ *  manifest — the source `describeGoUnprovenCause` names instead of a generic
+ *  "indeterminate". Returns null when the binding does not resolve to an
+ *  unrecognized package (no type, an unlisted-but-unimported name, etc.). */
+function unrecognizedPackageOf(binding, env, depth = 0) {
+    if (depth > 8)
+        return null;
+    switch (binding.kind) {
+        case 'import':
+            return binding.source && !GO_DB_PACKAGES.has(binding.source) ? binding.source : null;
+        case 'parameter':
+        case 'variable':
+        case 'field':
+            if (binding.typeText)
+                return unrecognizedPackageInType(binding.typeText, env);
+            if (binding.value)
+                return unrecognizedPackageInValue(binding.value, env, depth + 1);
+            return null;
+        case 'function':
+        case 'method':
+            if (binding.returnTypeText) {
+                return unrecognizedPackageInType(firstReturnType(binding.returnTypeText), env);
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Why a Go root classified `unproven` stayed unresolved — the Go-specific reason
+ * behind `goResolution.resolveRoot`. Where the generic `describeUnprovenCause`
+ * reports a qualified type as "indeterminate", this names the package the type
+ * *does* resolve to when that package is absent from the database-packages
+ * manifest: `*ent.Client` is not indeterminate — it resolves to `entgo.io/ent`,
+ * which the manifest simply does not list (Spec 70 R4 — an unrecognized package
+ * reached by resolution is an honest unknown, not a guessed clean).
+ *
+ * @param root the receiver's base identifier being described.
+ * @param env the file's Go resolution environment (provenance, bindings, imports).
+ * @returns a human-readable reason the root stayed `unproven`.
+ */
+export function describeGoUnprovenCause(root, env) {
+    if (env.provenance.has(root))
+        return 'resolved to a DB handle (misclassified)';
+    const binding = env.bindings.get(root) ?? env.packageBindings?.get(root);
+    if (!binding)
+        return 'has no binding in the file scope chain';
+    const pkg = unrecognizedPackageOf(binding, env);
+    if (pkg) {
+        return `resolves to \`${pkg}\` — an unrecognized package (not in the database-packages manifest)`;
+    }
+    switch (binding.kind) {
+        case 'import':
+            return `imports from '${binding.source ?? '?'}' — an unrecognized package (not in the database-packages manifest)`;
+        case 'parameter':
+            return binding.typeText ? `parameter type \`${binding.typeText}\` is indeterminate` : 'is an un-annotated parameter';
+        case 'variable':
+            if (binding.typeText)
+                return `declared type \`${binding.typeText}\` is indeterminate`;
+            return binding.value ? 'is an un-annotated factory return' : 'is an un-annotated declaration';
+        case 'field':
+            if (binding.typeText)
+                return `field type \`${binding.typeText}\` is indeterminate`;
+            return binding.value ? 'is an un-annotated field initializer' : 'is an un-annotated struct field';
+        case 'function':
+        case 'method':
+            return 'is a function reference without a DB return type';
+        case 'type':
+            return 'is a local type name';
+        default:
+            return 'is indeterminate';
+    }
+}
+// ── Within-file provenance ───────────────────────────────────────────────────
+/**
+ * The Go within-file provenance: seed DB package names (`sql` for
+ * `database/sql`) plus every binding whose type/value resolves to a DB handle.
+ * `packageBindings` (optional) carries package-scope declarations from *other*
+ * files in the same package, so `router := New()` resolves `New`'s return type
+ * (`*Engine` → not-a-handle) instead of falling back to `unproven`.
+ *
+ * @param ast the parsed Go file AST
+ * @param adapter the language adapter used to walk nodes
+ * @param sourceCode the file source text for reading node text
+ * @param packageBindings package-scope declarations from sibling files (optional)
+ * @returns the name → provenance-evidence map of DB handles resolved in this file
+ */
+export function buildGoWithinFileProvenance(ast, adapter, sourceCode, packageBindings) {
+    const imports = buildGoImportMap(ast, adapter);
+    const bindings = buildGoBindingEnv(ast, adapter, sourceCode);
+    return classifyGoBindings(imports, bindings, packageBindings);
+}
+/**
+ * The corpus-side, no-AST arm of {@link buildGoWithinFileProvenance}: seed DB
+ * package names then classify every binding against the (already-extracted)
+ * imports + bindings + package-scope declarations. This is the functional
+ * half — it reads only the serializable maps, so the receiver-provenance corpus
+ * producer (Spec 70 Item 4) can finalize a Go file's within-file provenance once
+ * its sibling package-scope symbols are known, without re-holding the AST.
+ *
+ * @param imports package-name → import path for the file
+ * @param bindings the file's name → binding environment (from `buildGoBindingEnv`)
+ * @param packageBindings package-scope declarations from sibling `.go` files
+ * @returns the name → provenance-evidence map of DB handles resolved in this file
+ */
+export function classifyGoBindings(imports, bindings, packageBindings) {
+    const env = {
+        provenance: new Map(),
+        bindings,
+        imports,
+        packageBindings,
+    };
+    const prov = new Map();
+    for (const [pkgName, source] of imports) {
+        if (GO_DB_PACKAGES.has(source)) {
+            prov.set(pkgName, {
+                identifier: pkgName,
+                reason: 'package',
+                source: `import ${source}`,
+                chain: [],
+            });
+        }
+    }
+    for (const [name, binding] of bindings) {
+        let disposition = 'unproven';
+        if (binding.typeText)
+            disposition = classifyGoTypeText(binding.typeText, env, 0);
+        else if (binding.value)
+            disposition = classifyGoValue(binding.value, env, 0);
+        if (disposition === 'handle') {
+            prov.set(name, {
+                identifier: name,
+                reason: 'binding',
+                source: binding.typeText
+                    ? `declared ${binding.typeText}`
+                    : 'declared as a DB handle',
+                chain: [],
+            });
+        }
+    }
+    return prov;
+}
+//# sourceMappingURL=goResolution.js.map