@remnic/coding-graph 9.3.759

package/src/semantic/semantic-query.ts

@@ -0,0 +1,173 @@
+/**
+ * semantic_query — natural-language retrieval over the symbol graph
+ * (issue #1556 PR3 component).
+ *
+ * Embed the query via the host provider / EmbeddingFallback
+ * (`mode: "lookup"`), top-k symbols by cosine, hydrate each hit with
+ * graph context (defining file, direct callers/callees).
+ *
+ * Rule 34 — degradation matrix. Provider missing / timeout / malformed
+ * vector (`normalizeHostEmbeddingVector` returns null) → three distinct
+ * `{ok:false}` codes, never an empty result masquerading as "no matches".
+ * When the provider is available but returns zero hits, `ok:true` with
+ * empty hits is the honest answer.
+ */
+
+
+import type { HostEmbeddingProvider } from "@remnic/core/host-embedding-provider";
+import {
+  EmbeddingProviderUnavailableError,
+  EmbeddingTimeoutError,
+} from "@remnic/core/embedding-fallback";
+import { normalizeHostEmbeddingVector } from "@remnic/core/host-embedding-provider";
+
+import type { GraphStore } from "../graph-store.js";
+import type { SemanticConfig } from "./config.js";
+import { cosineSimilarity } from "./minhash.js";
+import { modelIdFor } from "./vectors.js";
+import type { SemanticQueryHit, SemanticQueryOutcome } from "./types.js";
+
+/**
+ * Input to {@link semanticQuery}.
+ */
+export interface SemanticQueryInput {
+  readonly store: GraphStore;
+  readonly provider: HostEmbeddingProvider | undefined;
+  readonly repoRoot: string;
+  readonly config: SemanticConfig;
+  readonly query: string;
+  readonly limit?: number;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Default top-k for semantic_query.
+ */
+export const DEFAULT_SEMANTIC_QUERY_LIMIT = 10;
+
+/**
+ * Run a semantic query: embed → top-k → hydrate.
+ *
+ * Degradation matrix (rule 34):
+ *   - !config.enabled              → { ok:false, code:"semantic_disabled" }
+ *   - no provider                  → { ok:false, code:"provider_unavailable" }
+ *   - provider throws timeout      → { ok:false, code:"provider_timeout" }
+ *   - provider returns null/malformed → { ok:false, code:"malformed_vector" }
+ *   - no vectors in table          → { ok:false, code:"no_vectors" }
+ *   - ok but zero hits             → { ok:true, hits:[] }
+ */
+export async function semanticQuery(input: SemanticQueryInput): Promise<SemanticQueryOutcome> {
+  const { store, provider, repoRoot, config, query, signal } = input;
+  // Closed store is a distinct degradation (rule 34) — do not treat it as
+  // an empty vectors table that returns 'no_vectors' (cursor Bugbot:
+  // 'Closed store reports success').
+  if (store.isClosed) {
+    return { ok: false, code: "store_closed" };
+  }
+  if (!config.enabled) {
+    return { ok: false, code: "semantic_disabled" };
+  }
+  if (query.length === 0) {
+    return { ok: false, code: "invalid_query", message: "query must be non-empty" };
+  }
+  if (!provider) {
+    return { ok: false, code: "provider_unavailable" };
+  }
+
+  // Embed the query (lookup mode — short timeout budget).
+  let raw: ArrayLike<number> | null;
+  try {
+    raw = await provider.embed(query, { signal, inputType: "query" });
+  } catch (error) {
+    if (error instanceof EmbeddingTimeoutError) {
+      return { ok: false, code: "provider_timeout" };
+    }
+    if (error instanceof EmbeddingProviderUnavailableError) {
+      return { ok: false, code: "provider_unavailable" };
+    }
+    // Unknown provider error → treat as unavailable (the provider is broken).
+    // Do NOT include the raw error message (may leak paths/stacks to clients).
+    return { ok: false, code: "provider_unavailable" };
+  }
+  const queryVec = normalizeHostEmbeddingVector(raw);
+  if (!queryVec || queryVec.length === 0) {
+    return { ok: false, code: "malformed_vector" };
+  }
+  const queryF32 = new Float32Array(queryVec);
+
+  // Brute-force cosine over all vectors for this model.
+  const modelId = modelIdFor(provider);
+  // Wrap the store read so a transient SQLite error (SQLITE_BUSY / CORRUPT)
+  // maps to a tagged db_error instead of escaping semanticQuery (#1680).
+  let rows: readonly ReturnType<typeof store.readAllSymbolVectors>[number][];
+  try {
+    rows = store.readAllSymbolVectors(modelId);
+  } catch {
+    return { ok: false, code: "db_error" };
+  }
+  if (rows.length === 0) {
+    return { ok: false, code: "no_vectors" };
+  }
+
+  // Validate limit: NaN/Infinity/non-numeric must not produce a NaN/Infinity
+  // slice (#1680). NaN → slice(0, NaN) returns no hits; Infinity → every row.
+  // Coerce to a finite positive integer, falling back to the default.
+  const rawLimit = input.limit;
+  const limit = (typeof rawLimit === "number" && Number.isFinite(rawLimit) && rawLimit > 0)
+    ? Math.max(1, Math.floor(rawLimit))
+    : DEFAULT_SEMANTIC_QUERY_LIMIT;
+  // Only score vectors whose dimensionality matches the query embedding.
+  // cosineSimilarity compares over the SHORTER length, so a row from a
+  // different model size would otherwise get a misleading partial-overlap
+  // score and rank incorrectly instead of being excluded (cursor Bugbot:
+  // 'Mismatched embedding lengths scored').
+  const queryDims = queryF32.length;
+  const scored = rows
+    .filter((r) => r.dims === queryDims)
+    .map((r) => ({
+      nodeId: r.nodeId,
+      qualifiedName: r.qualifiedName,
+      filePath: r.filePath,
+      kind: r.kind,
+      dims: r.dims,
+      score: cosineSimilarity(queryF32, r.vector),
+    }))
+    .filter((r) => Number.isFinite(r.score))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+
+  // Hydrate each hit with graph context (callers/callees + snippet).
+  const hits: SemanticQueryHit[] = [];
+  for (const h of scored) {
+    const neighbors = store.readNeighborsByNodeId(h.nodeId);
+    let snippet = "";
+    try {
+      // Hydrate by the exact node id from the vector row, not the
+      // qualified name — a name duplicated across files would otherwise
+      // hit 'ambiguous_name' and leave the snippet empty even though the
+      // vector row identified the precise node (chatgpt-codex-connector
+      // P2: 'Hydrate snippets by node id as well').
+      const snippetResult = await store.snippetFor({ nodeId: h.nodeId, repoRoot });
+      if (snippetResult.ok) snippet = snippetResult.text;
+    } catch {
+      // snippetFor returns tagged failures, not throws — this is defensive.
+    }
+    hits.push({
+      qualifiedName: h.qualifiedName,
+      filePath: h.filePath,
+      kind: h.kind,
+      score: h.score,
+      snippet,
+      callers: neighbors.callers,
+      callees: neighbors.callees,
+    });
+  }
+
+  return { ok: true, hits };
+}
+
+/**
+ * Read a short snippet (first ~20 lines) from a file for hydration. The
+ * full source span is available via store.snippetFor; here we just want
+ * enough context for the agent to orient.
+ */