Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

9.0 KB
Raw Blame
/**
 * Where the concept pass cuts its synthesis batches, and what that costs
 * (`src/context/batches.ts`).
 *
 * Every batch is cached under a key derived from the files it holds, so a boundary
 * that moves is a re-synthesis — a metered LLM call the user pays for again. Cut by
 * running size (which is what this replaces) one summary growing by a few hundred
 * characters moved every later boundary, so the next build after any edit
 * re-synthesized most of the graph. These tests pin the property that replaced it:
 * the plan is a function of the file PATHS, so only the batches around a change can
 * move.
 */
import { test } from "node:test";
import assert from "node:assert/strict";
import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { buildContext } from "../src/context/build.js";
import { BATCH_CHAR_BUDGET, planSynthesis, type SynthesisBatch } from "../src/context/batches.js";
import { contentHash } from "../src/util/id.js";
import { tmpRepo, PassthroughSummarizer } from "./helpers.js";
import type { FileSummary, Synthesizer } from "../src/index.js";

const FILES = 200;
/** Summary length per file. ~2k is what a real per-file summary runs to, and it
 *  puts the stride at 16 files, so a 200-file repo is a dozen-odd batches. */
const SUMMARY_CHARS = 2000;
/** How much one edited file's summary changes by. Deliberately MORE than one file's
 *  summary: under a size-driven cut, a change smaller than that cannot move a
 *  boundary at all, and a test that cannot tell the two rules apart is not a guard
 *  against the regression. */
const EDIT_CHARS = SUMMARY_CHARS + 2500;

function fileBody(i: number, chars = SUMMARY_CHARS): string {
  return `export const v${i} = ${i};\n// ${"x".repeat(chars)}\n`;
}

/** A repo of numbered files, so the path-sorted order is the numeric order. */
function makeRepo(tag: string, count = FILES): string {
  const dir = tmpRepo(tag);
  mkdirSync(join(dir, "src"), { recursive: true });
  for (let i = 0; i < count; i++) {
    writeFileSync(join(dir, "src", `mod-${String(i).padStart(3, "0")}.ts`), fileBody(i));
  }
  return dir;
}

/** The plan for a repo as it stands: cache key → the paths in that batch. */
function planOf(dir: string): Map<string, string[]> {
  const summaries: FileSummary[] = [];
  const hashByPath = new Map<string, string>();
  for (const name of readdirSync(join(dir, "src")).sort((a, b) => a.localeCompare(b))) {
    const rel = `src/${name}`;
    const code = readFileSync(join(dir, rel), "utf8");
    summaries.push({ path: rel, summary: code });
    hashByPath.set(rel, contentHash(code));
  }
  return new Map(planSynthesis(summaries, hashByPath).map((b: SynthesisBatch) => [b.key, b.files.map((f) => f.path)]));
}

/**
 * The invariant: re-planning is LOCAL. A batch's files only change if a boundary
 * appeared or disappeared next to the change, so the batches whose keys move are
 * the one the change lands in and the two either side of it — and nothing further
 * out. A size-driven cut breaks this for every batch after the change; a rule that
 * re-strides on a changed mean breaks it for all of them.
 *
 * `touched` may or may not exist in `before` (a removal, an insertion), so the
 * batches it can disturb are found by bracketing its place in the path order.
 */
function assertLocalReplan(before: Map<string, string[]>, after: Map<string, string[]>, touched: string): void {
  const order = [...before.keys()];
  const lastBefore = [...order].reverse().find((k) => before.get(k)![before.get(k)!.length - 1] < touched);
  const at = lastBefore === undefined ? 0 : order.indexOf(lastBefore);
  const near = order.slice(Math.max(0, at - 1), at + 2);
  const neighbourhood = new Set(near.flatMap((k) => before.get(k)!));

  const invalidated = order.filter((k) => !after.has(k));
  const fresh = [...after.keys()].filter((k) => !before.has(k));
  for (const k of invalidated) {
    assert.ok(near.includes(k), `${invalidated.length} batches were invalidated, outside the ones holding ${touched}`);
  }
  for (const k of fresh) {
    for (const path of after.get(k)!) {
      assert.ok(
        neighbourhood.has(path) || path === touched,
        `${path} landed in a new batch well away from ${touched}`,
      );
    }
  }
  assert.ok(
    invalidated.length + fresh.length <= 3,
    `one change at ${touched} moved ${invalidated.length + fresh.length} of ${order.length} batches; ` +
      `a size-driven cut moves the rest`,
  );
}

const chars = (batch: SynthesisBatch): number =>
  batch.files.reduce((n, f) => n + f.path.length + f.summary.length + 8, 0);

test("a one-file edit re-plans only the batch that holds it", () => {
  const dir = makeRepo("batch-edit");
  try {
    const before = planOf(dir);
    assert.ok(before.size >= 8, `need several batches for this to say anything, got ${before.size}`);

    // One rewritten file, whose summary is a good deal longer than it was.
    const touched = "src/mod-100.ts";
    writeFileSync(join(dir, touched), fileBody(100, EDIT_CHARS));

    const after = planOf(dir);
    assertLocalReplan(before, after, touched);
    assert.equal(
      [...before.keys()].filter((k) => !after.has(k)).length,
      1,
      "a summary that changed must not disturb the batch after it, or the next one either",
    );
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test("adding a file re-plans only the batches around it", () => {
  const dir = makeRepo("batch-add");
  try {
    const before = planOf(dir);
    // Sorts between mod-100 and mod-101, so a size-driven cut would push every
    // boundary after it along — which is the cost this removes.
    const added = "src/mod-100z.ts";
    writeFileSync(join(dir, added), fileBody(0));

    assertLocalReplan(before, planOf(dir), added);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test("removing a file re-plans only the batches around it", () => {
  const dir = makeRepo("batch-remove");
  try {
    const before = planOf(dir);
    const gone = "src/mod-042.ts";
    rmSync(join(dir, gone));

    assertLocalReplan(before, planOf(dir), gone);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test("every batch stays under the char budget unless it is one oversized file", () => {
  const dir = makeRepo("batch-budget");
  try {
    const summaries: FileSummary[] = [];
    const hashByPath = new Map<string, string>();
    for (const name of readdirSync(join(dir, "src")).sort((a, b) => a.localeCompare(b))) {
      const rel = `src/${name}`;
      summaries.push({ path: rel, summary: readFileSync(join(dir, rel), "utf8") });
      hashByPath.set(rel, "h");
    }
    for (const batch of planSynthesis(summaries, hashByPath)) {
      assert.ok(
        batch.files.length === 1 || chars(batch) <= BATCH_CHAR_BUDGET,
        `a ${batch.files.length}-file batch of ${chars(batch)} chars is over the ${BATCH_CHAR_BUDGET} budget`,
      );
    }
    // One file bigger than the whole budget is its own batch rather than a
    // truncated neighbour's problem.
    const huge: FileSummary[] = [...summaries, { path: "src/huge.ts", summary: "x".repeat(BATCH_CHAR_BUDGET * 2) }];
    const plan = planSynthesis(huge, new Map([["src/huge.ts", "h"]]));
    const hugeBatch = plan.find((b) => b.files.some((f) => f.path === "src/huge.ts"));
    assert.ok(hugeBatch, "the oversized file must still be synthesized");
    assert.ok(
      hugeBatch.files.every((f) => f.path === "src/huge.ts" || chars(hugeBatch) <= BATCH_CHAR_BUDGET),
      "an oversized file must not drag neighbours over the budget",
    );
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test("a re-build after a one-file edit re-synthesizes one batch, not the graph", async () => {
  const dir = makeRepo("batch-e2e");
  let calls = 0;
  const synthesizer: Synthesizer = {
    async synthesize(files) {
      calls++;
      return files.map((f) => ({ name: f.path, type: "file", summary: "s", sources: [f.path], links: [] }));
    },
  };
  const orig = console.error;
  console.error = () => {};
  try {
    const first = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });
    assert.ok(first.batches >= 8, `need several batches for this to say anything, got ${first.batches}`);
    const cold = calls;
    assert.equal(cold, first.batches);

    calls = 0;
    const warm = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });
    assert.equal(calls, 0, "an unchanged repo spends nothing");
    assert.equal(warm.batches, first.batches);

    calls = 0;
    writeFileSync(join(dir, "src", "mod-100.ts"), fileBody(100, EDIT_CHARS));
    const after = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });
    assert.equal(after.batches, first.batches);
    assert.ok(
      calls >= 1 && calls <= 2,
      `one edited file of ${first.batches} batches cost ${calls} synthesis calls; it must cost its own batch`,
    );
  } finally {
    console.error = orig;
    rmSync(dir, { recursive: true, force: true });
  }
});