Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.6 KB
Raw Blame
/**
 * Code edges (v0.20 Cathedral II call graph): one SQL implementation for both
 * engines (refactor wave 1, W1-core C13). Statement text is PostgresEngine's
 * master text (SQL-text golden `sql-text/code-edges.json`); PGLite runs the
 * same statements, except `getEdgesByChunk`, whose PGLite form differs in
 * behavior on master (one UNION with a shared LIMIT) and stays dialect-specific
 * in src/core/pglite-engine/code-edges.ts (docs/designs/refactor-wave-1/w1-inventory.md).
 *
 * Capability `maxBindParamsPerStatement`: PGLite's parameter bridge corrupts
 * the session past 32,767 binds, so bulk inserts split below 30,000 binds
 * there; Postgres (Infinity) keeps master's single statement per shape. The
 * inserts keep master's direct `unsafe` path (they were raw on master).
 * Reads were unscoped on master (EO4 inventory): `LegacyUnscopedRead`.
 */
import type { CodeEdgeInput, CodeEdgeResult } from '../types.ts';
import { currentCodeEdgeFilter } from '../code-intel/read-scope.ts';
import type { SqlExecutor } from './executor.ts';
import type { LegacyUnscopedRead } from './brands.ts';
import { joinFragments, renderFragment, sqlFragment, trustedSql, type SqlFragment } from './fragment.ts';

/** Rows per statement for a shape binding `bindsPerRow` params (Infinity = one statement). */
function rowsPerStatement(exec: SqlExecutor, bindsPerRow: number): number {
  return Math.floor(exec.capabilities.maxBindParamsPerStatement / bindsPerRow);
}

function* batches<T>(rows: T[], size: number): Generator<T[]> {
  if (!Number.isFinite(size)) { if (rows.length > 0) yield rows; return; }
  for (let offset = 0; offset < rows.length; offset += size) yield rows.slice(offset, offset + size);
}

export async function addCodeEdges(exec: SqlExecutor, edges: CodeEdgeInput[]): Promise<number> {
    if (edges.length === 0) return 0;
    let inserted = 0;
    const resolved = edges.filter(e => e.to_chunk_id != null);
    const unresolved = edges.filter(e => e.to_chunk_id == null);

    // Per-row placeholders with ::text::jsonb for edge_metadata. Bun SQL
    // mis-encodes jsonb[] array binds (double-encoded strings landed in
    // edge_metadata — the resolver then read `"{}"` scalars and 0 edges ever
    // resolved). ::text::jsonb per row is the codebase-wide safe shape.
    for (const batch of batches(resolved, rowsPerStatement(exec, 7))) {
      const values = joinFragments(batch.map(e => sqlFragment`(${e.from_chunk_id}::int, ${e.to_chunk_id as number}::int, ${e.from_symbol_qualified}, ${e.to_symbol_qualified}, ${e.edge_type}, ${JSON.stringify(e.edge_metadata ?? {})}::text::jsonb, ${e.source_id ?? 'default'})`), ', ');
      const { text, params } = renderFragment(sqlFragment`INSERT INTO code_edges_chunk
           (from_chunk_id, to_chunk_id, from_symbol_qualified, to_symbol_qualified, edge_type, edge_metadata, source_id)
         VALUES ${values}
         ON CONFLICT (from_chunk_id, to_chunk_id, edge_type) DO NOTHING`);
      inserted += (await exec.unsafe(text, params)).affectedRows;
    }

    for (const batch of batches(unresolved, rowsPerStatement(exec, 6))) {
      const values = joinFragments(batch.map(e => sqlFragment`(${e.from_chunk_id}::int, ${e.from_symbol_qualified}, ${e.to_symbol_qualified}, ${e.edge_type}, ${JSON.stringify(e.edge_metadata ?? {})}::text::jsonb, ${e.source_id ?? 'default'})`), ', ');
      const { text, params } = renderFragment(sqlFragment`INSERT INTO code_edges_symbol
           (from_chunk_id, from_symbol_qualified, to_symbol_qualified, edge_type, edge_metadata, source_id)
         VALUES ${values}
         ON CONFLICT (from_chunk_id, to_symbol_qualified, edge_type) DO NOTHING`);
      inserted += (await exec.unsafe(text, params)).affectedRows;
    }

    return inserted;
  }

export async function deleteCodeEdgesForChunks(exec: SqlExecutor, chunkIds: number[]): Promise<void> {
    if (chunkIds.length === 0) return;
    (await exec.run(sqlFragment`DELETE FROM code_edges_chunk WHERE from_chunk_id = ANY(${chunkIds}::int[]) OR to_chunk_id = ANY(${chunkIds}::int[])`)).rows;
    (await exec.run(sqlFragment`DELETE FROM code_edges_symbol WHERE from_chunk_id = ANY(${chunkIds}::int[])`)).rows;
  }

/**
 * #5439: `opts.chunkId` keys the read on chunk identity instead of the name.
 * Callers of a chunk: code_edges_chunk rows pointing at it plus
 * code_edges_symbol rows the resolver stamped with that resolved_chunk_id.
 * The source filter still applies, so a chunk id is only ever read inside
 * the caller's source.
 */
export async function getCallersOf(
  exec: LegacyUnscopedRead,
    qualifiedName: string,
    opts?: { sourceId?: string; allSources?: boolean; limit?: number; chunkId?: number },
  ): Promise<CodeEdgeResult[]> {
    const limit = Math.min(opts?.limit ?? 100, 500);
    const scopedSource: string | null =
      !opts?.allSources && opts?.sourceId ? opts.sourceId : null;
    const byChunk = typeof opts?.chunkId === 'number';
    const rows = (await exec.run(sqlFragment`
      SELECT id, from_chunk_id, to_chunk_id, from_symbol_qualified, to_symbol_qualified,
             edge_type, edge_metadata, source_id, true as resolved
        FROM code_edges_chunk
        WHERE ${byChunk ? sqlFragment`to_chunk_id = ${opts!.chunkId as number}::int` : sqlFragment`to_symbol_qualified = ${qualifiedName}`}
        AND ${trustedSql(currentCodeEdgeFilter('code_edges_chunk', true))}
        ${scopedSource ? sqlFragment`AND source_id = ${scopedSource}` : sqlFragment``}
      UNION ALL
      SELECT id, from_chunk_id, NULL::int as to_chunk_id, from_symbol_qualified, to_symbol_qualified,
             edge_type, edge_metadata, source_id, false as resolved
        FROM code_edges_symbol
        WHERE ${byChunk ? sqlFragment`(edge_metadata->>'resolved_chunk_id')::int = ${opts!.chunkId as number}::int` : sqlFragment`to_symbol_qualified = ${qualifiedName}`}
        AND ${trustedSql(currentCodeEdgeFilter('code_edges_symbol', false))}
        ${scopedSource ? sqlFragment`AND source_id = ${scopedSource}` : sqlFragment``}
      LIMIT ${limit}
    `)).rows;
    return rows.map(r => rowToCodeEdge(r as Record<string, unknown>));
  }

/** #5439: `opts.chunkId` reads the edges leaving that chunk (both tables) instead of the name's. */
export async function getCalleesOf(
  exec: LegacyUnscopedRead,
    qualifiedName: string,
    opts?: { sourceId?: string; allSources?: boolean; limit?: number; bareFallback?: boolean; chunkId?: number },
  ): Promise<CodeEdgeResult[]> {
    const limit = Math.min(opts?.limit ?? 100, 500);
    const scopedSource: string | null =
      !opts?.allSources && opts?.sourceId ? opts.sourceId : null;
    const run = async (fromPredicate: SqlFragment) => (await exec.run(sqlFragment`
      SELECT id, from_chunk_id, to_chunk_id, from_symbol_qualified, to_symbol_qualified,
             edge_type, edge_metadata, source_id, true as resolved
        FROM code_edges_chunk
        WHERE ${fromPredicate}
        AND ${trustedSql(currentCodeEdgeFilter('code_edges_chunk', true))}
        ${scopedSource ? sqlFragment`AND source_id = ${scopedSource}` : sqlFragment``}
      UNION ALL
      SELECT id, from_chunk_id, NULL::int as to_chunk_id, from_symbol_qualified, to_symbol_qualified,
             edge_type, edge_metadata, source_id, false as resolved
        FROM code_edges_symbol
        WHERE ${fromPredicate}
        AND ${trustedSql(currentCodeEdgeFilter('code_edges_symbol', false))}
        ${scopedSource ? sqlFragment`AND source_id = ${scopedSource}` : sqlFragment``}
      LIMIT ${limit}
    `)).rows;
    if (typeof opts?.chunkId === 'number') {
      return (await run(sqlFragment`from_chunk_id = ${opts.chunkId}::int`)).map(r => rowToCodeEdge(r as Record<string, unknown>));
    }
    let rows = await run(sqlFragment`from_symbol_qualified = ${qualifiedName}`);
    // #4670: opt-in bare-name fallback (both engines).
    // Opt-in; zero-row exact miss + delimiter-free input re-keys on the bare
    // content_chunks.symbol_name (exact, never LIKE).
    if (rows.length === 0 && opts?.bareFallback && !/[.#:]/.test(qualifiedName)) {
      rows = await run(sqlFragment`from_chunk_id IN (SELECT id FROM content_chunks WHERE symbol_name = ${qualifiedName})`);
    }
    return rows.map(r => rowToCodeEdge(r as Record<string, unknown>));
  }

export async function getEdgesByChunk(
  exec: LegacyUnscopedRead,
    chunkId: number,
    opts?: { direction?: 'in' | 'out' | 'both'; edgeType?: string; limit?: number },
  ): Promise<CodeEdgeResult[]> {
    const direction = opts?.direction ?? 'both';
    const limit = Math.min(opts?.limit ?? 50, 200);
    const typeFilter = opts?.edgeType;

    const chunkRows = (await exec.run(sqlFragment`
      SELECT id, from_chunk_id, to_chunk_id, from_symbol_qualified, to_symbol_qualified,
             edge_type, edge_metadata, source_id, true as resolved
        FROM code_edges_chunk
        WHERE
          ${direction === 'in' ? sqlFragment`to_chunk_id = ${chunkId}`
            : direction === 'out' ? sqlFragment`from_chunk_id = ${chunkId}`
            : sqlFragment`(from_chunk_id = ${chunkId} OR to_chunk_id = ${chunkId})`}
          ${typeFilter ? sqlFragment`AND edge_type = ${typeFilter}` : sqlFragment``}
        LIMIT ${limit}
    `)).rows;
    let symbolRows: unknown[] = [];
    if (direction !== 'in') {
      const sRows = (await exec.run(sqlFragment`
        SELECT id, from_chunk_id, NULL::int as to_chunk_id, from_symbol_qualified, to_symbol_qualified,
               edge_type, edge_metadata, source_id, false as resolved
          FROM code_edges_symbol
          WHERE from_chunk_id = ${chunkId}
            ${typeFilter ? sqlFragment`AND edge_type = ${typeFilter}` : sqlFragment``}
          LIMIT ${limit}
      `)).rows;
      symbolRows = [...sRows];
    }
    return [...chunkRows, ...symbolRows].map(r => rowToCodeEdge(r as Record<string, unknown>));
  }

/**
 * Shared by both engines' reads. `resolved` is true for a code_edges_chunk
 * row AND for a code_edges_symbol row the resolver stamped with
 * edge_metadata.resolved_chunk_id (gbrain-evals N13-2); to_chunk_id still
 * reports the stored column.
 */
export function rowToCodeEdge(row: Record<string, unknown>): CodeEdgeResult {
  const edgeMetadata = (row.edge_metadata as Record<string, unknown>) ?? {};
  return {
    id: row.id as number,
    from_chunk_id: row.from_chunk_id as number,
    to_chunk_id: row.to_chunk_id == null ? null : (row.to_chunk_id as number),
    from_symbol_qualified: (row.from_symbol_qualified as string) ?? '',
    to_symbol_qualified: (row.to_symbol_qualified as string) ?? '',
    edge_type: (row.edge_type as string) ?? '',
    edge_metadata: edgeMetadata,
    source_id: row.source_id == null ? null : (row.source_id as string),
    resolved: Boolean(row.resolved) || typeof edgeMetadata.resolved_chunk_id === 'number',
  };
}