code-auditor-mcp 4.1.1 → 5.0.2

package/dist/languages/go/goResolution.d.ts

@@ -0,0 +1,229 @@
+/**
+ * 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 type { AST, LanguageAdapter } from '../types.js';
+import type { ProvenanceEvidence } from '../../analyzers/provenance.js';
+/**
+ * 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 declare const GO_DB_PACKAGES: ReadonlySet<string>;
+/**
+ * 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 declare const GO_STDLIB_PACKAGES: ReadonlySet<string>;
+/** A receiver root's disposition (mirrors the TS processor's three-way split). */
+export type GoRootDisposition = 'handle' | 'not-handle' | 'unproven';
+/** How a name is bound in a Go file's scope. */
+export type GoBindingKind = 'import' | 'variable' | 'parameter' | 'field' | 'function' | 'method' | 'type' | 'const';
+/**
+ * A serializable projection of a Go value/initializer expression — the structure
+ * `classifyGoValue` reads to resolve a variable/field initializer's disposition.
+ *
+ * Spec 70 Item 4 ("no AST outlives its file"): a package-scope `GoBinding` is
+ * threaded *across* files via `buildGoPackageBindings`, so its `value` may not
+ * hold a live tree-sitter node (which dies with the file's AST). This descriptor
+ * carries only the fields `classifyGoValue` consults — the node type, its text,
+ * and the `function`/`operand`/`type` named children it reads — projected
+ * recursively to a bounded depth (the classifier never reads past two named-field
+ * hops). It is the Go counterpart of the TypeScript `ValueDescriptor`
+ * (`receiverRoot.ts`).
+ */
+export interface GoValueDescriptor {
+    readonly type: string;
+    readonly text: string;
+    readonly function?: GoValueDescriptor | null;
+    readonly operand?: GoValueDescriptor | null;
+    readonly typeNode?: GoValueDescriptor | null;
+}
+/** A single Go binding: how a name is declared. */
+export interface GoBinding {
+    kind: GoBindingKind;
+    /** Import source path (kind === 'import'). */
+    source?: string;
+    /** Type-annotation text (variable / parameter / field). */
+    typeText?: string;
+    /** Return-type text (function / method) — `(*sql.DB, error)`. */
+    returnTypeText?: string;
+    /** Initializer / value expression (variable / field), serializable. */
+    value?: GoValueDescriptor;
+}
+/** Per-file resolution inputs the Go classifier reads. `adapter` and `sourceCode`
+ *  are optional: only the extraction half (`buildGoImportMap` / `buildGoBindingEnv`)
+ *  needs them — the classifier (`classifyGoRootIdentifier` / `classifyGoTypeText` /
+ *  `classifyGoValue`) is a pure function of the serializable maps, so
+ *  {@link classifyGoBindings} (the corpus-side, no-AST arm of
+ *  `buildGoWithinFileProvenance`) builds an env without them. */
+export interface GoResolutionEnv {
+    provenance: ReadonlyMap<string, ProvenanceEvidence>;
+    bindings: ReadonlyMap<string, GoBinding>;
+    /** package-name → import path (e.g. `sql` → `database/sql`). */
+    imports: ReadonlyMap<string, string>;
+    adapter?: LanguageAdapter;
+    sourceCode?: string;
+    /** Package-scope declarations from *other* files in the same Go package. */
+    packageBindings?: ReadonlyMap<string, GoBinding>;
+}
+/**
+ * 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 declare function buildGoImportMap(ast: AST, adapter: LanguageAdapter): Map<string, string>;
+/**
+ * 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 declare function buildGoBindingEnv(ast: AST, adapter: LanguageAdapter, sourceCode: string): Map<string, GoBinding>;
+/**
+ * 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 declare function buildGoPackageBindings(files: readonly {
+    ast: AST;
+    adapter: LanguageAdapter;
+}[]): Map<string, GoBinding>;
+/**
+ * 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 declare function buildGoFileBindings(ast: AST): Map<string, GoBinding>;
+/**
+ * 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 declare function classifyGoRootIdentifier(name: string, env: GoResolutionEnv, depth?: number): GoRootDisposition;
+/**
+ * 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 declare function classifyGoTypeText(typeText: string, env: GoResolutionEnv, depth: number): GoRootDisposition;
+/**
+ * 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 declare function describeGoUnprovenCause(root: string, env: GoResolutionEnv): string;
+/**
+ * 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 declare function buildGoWithinFileProvenance(ast: AST, adapter: LanguageAdapter, sourceCode: string, packageBindings?: ReadonlyMap<string, GoBinding>): Map<string, ProvenanceEvidence>;
+/**
+ * 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 declare function classifyGoBindings(imports: ReadonlyMap<string, string>, bindings: ReadonlyMap<string, GoBinding>, packageBindings?: ReadonlyMap<string, GoBinding>): Map<string, ProvenanceEvidence>;
+//# sourceMappingURL=goResolution.d.ts.map

package/dist/languages/go/goResolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goResolution.d.ts","sourceRoot":"","sources":["../../../src/languages/go/goResolution.ts"],"names":[],"mappings":"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"}