Function synthesizeCallbackEdges

src/resolution/callback-synthesizer.ts:3596–3787

(
  queries: QueryBuilder,
  ctx: ResolutionContext,
  onProgress?: (done: number, total: number) => void,
  // A live resolver pool to fan the independent passes across (structural type
  // so this file never imports the pool — resolver-worker imports THIS file).
  // Null/omitted → the sequential path, byte-identical to the pool path.
  pool?: { runSynthPass(name: string): Promise<{ edges: Edge[]; ms: number }> } | null,
  // WAL-valve writer backstop (WalCheckpointValve.backpressure), called at
  // pool-idle points in the edge-insert loops below — the passes themselves
  // only read; every write in this function happens with the pool idle.
  backpressure?: () => Promise<void> | null
)

const FIXED_SYNTH_STEPS = 4;
export const SYNTH_PROGRESS_STEPS = SYNTH_PASSES.length + FIXED_SYNTH_STEPS;
export async function synthesizeCallbackEdges(
  queries: QueryBuilder,
  ctx: ResolutionContext,
  onProgress?: (done: number, total: number) => void,
  // A live resolver pool to fan the independent passes across (structural type
  // so this file never imports the pool — resolver-worker imports THIS file).
  // Null/omitted → the sequential path, byte-identical to the pool path.
  pool?: { runSynthPass(name: string): Promise<{ edges: Edge[]; ms: number }> } | null,
  // WAL-valve writer backstop (WalCheckpointValve.backpressure), called at
  // pool-idle points in the edge-insert loops below — the passes themselves
  // only read; every write in this function happens with the pool idle.
  backpressure?: () => Promise<void> | null
): Promise<number> {
  // Each sub-pass below is a whole-graph scan, and there are ~30 of them, all
  // running synchronously on the indexer's main thread. Their AGGREGATE can run
  // for well over a minute on a large repo — long enough for the #850 liveness
  // watchdog to SIGKILL the process mid-index (#1091), since its heartbeat lives
  // on this same thread. Yield between passes so the heartbeat can fire; a pass
  // that itself hangs (a real wedge) never reaches the next yield, so the
  // watchdog still catches that. See ./cooperative-yield.
  const yieldToLoop = createYielder();

  // Synthesis runs AFTER the resolution progress bar reaches 100%, so without
  // its own progress the UI freezes at "Resolving refs 100%" for the whole
  // tail — long enough on big repos that users conclude the index hung and
  // kill it. Report each completed pass; the caller surfaces it as its own
  // progress phase. Emit 0/total up front so the phase flips immediately.
  // Emissions are throttled to whole-percent movement (each consumes a UI
  // message); values may be fractional steps from within-pass reporting.
  let passesDone = 0;
  let lastPct = -1;
  const emit = (value: number): void => {
    if (!onProgress) return;
    const v = Math.min(value, SYNTH_PROGRESS_STEPS);
    const pct = Math.floor((v / SYNTH_PROGRESS_STEPS) * 100);
    if (pct === lastPct) return;
    lastPct = pct;
    onProgress(v, SYNTH_PROGRESS_STEPS);
  };
  // A single long pass otherwise parks the bar between steps; a pass that
  // takes this callback reports a 0..1 fraction of its own work, surfaced
  // here as fractional progress within its step.
  const subProgress = (fraction: number): void =>
    emit(passesDone + Math.max(0, Math.min(fraction, 1)));
  emit(0);

  // Per-pass wall-clock timing to stderr, opt-in via CODEGRAPH_SYNTH_TIMINGS
  // (=1: passes over 250ms; =all: every pass). This is the diagnostic that
  // located both the #1091/#1122 watchdog stalls and the #1212 OOM — keep it.
  const markT = { t: Date.now() };
  const __mark = (label: string): void => {
    const now = Date.now();
    const dt = now - markT.t;
    markT.t = now;
    if (process.env.CODEGRAPH_SYNTH_TIMINGS && (dt > 250 || process.env.CODEGRAPH_SYNTH_TIMINGS === 'all')) {
      console.error(`[synth-timing] ${label}: ${dt}ms`);
    }
    passesDone++;