Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

Select snapshot evidence with additive context and partial failure retention

David Zhangb6be112f1d55
diff --git a/packages/core/src/selection.ts b/packages/core/src/selection.ts
new file mode 100644
index 0000000..5639cfe
--- /dev/null
+++ b/packages/core/src/selection.ts
@@ -0,0 +1,239 @@
+import { EvaluationFailure } from "./gateway";
+import { evidenceRequest, type Evidence } from "./requests";
+import {
+ inspect,
+ pythonNeighborhood,
+ sourceForUnit,
+ type Range,
+ type Snapshot,
+ type SourceUnit,
+} from "./source";
+import type { Evaluator, FileEvidence, ReadingLead } from "./types";
+
+type EvidenceRange = Range & { sourceByteStart?: number; sourceByteEnd?: number };
+type Span = { start: number; end: number };
+const sourceUnitBytes = 24_000;
+export type SelectionResult = {
+ file: FileEvidence;
+ issues: Array<{ kind: string; count: number }>;
+};
+
+function mergeSpans(spans: Span[]): Span[] {
+ const merged: Span[] = [];
+ for (const span of spans
+ .filter((span) => span.end > span.start)
+ .sort((a, b) => a.start - b.start || a.end - b.end)) {
+ const last = merged.at(-1);
+ if (last && span.start <= last.end) last.end = Math.max(last.end, span.end);
+ else merged.push({ ...span });
+ }
+ return merged;
+}
+
+/** Classify declarations once per pass; rendering always expands selected evidence, never prior rendering. */
+export async function selectFile(
+ snapshot: Snapshot,
+ query: string,
+ score: number,
+ evaluator: Evaluator,
+ selectedEvidence?: Evidence[],
+ previous?: FileEvidence,
+): Promise<SelectionResult> {
+ const issues = new Map<string, number>();
+ const warn = (kind: string) => issues.set(kind, (issues.get(kind) ?? 0) + 1);
+ if (
+ previous &&
+ (previous.path !== snapshot.path || previous.contentHash !== snapshot.contentHash)
+ ) {
+ warn("changed");
+ previous = undefined;
+ }
+ const lines = snapshot.source.split("\n"),
+ bytes = Buffer.from(snapshot.source),
+ offsets = [0];
+ for (const line of lines)
+ offsets.push(Math.min(bytes.length, offsets.at(-1)! + Buffer.byteLength(line) + 1));
+ function spanForRange(range: EvidenceRange): Span {
+ return {
+ start: range.sourceByteStart ?? offsets[range.startLine - 1]!,
+ end: range.sourceByteEnd ?? offsets[range.endLine]!,
+ };
+ }
+ function lineAt(byte: number) {
+ let low = 0,
+ high = lines.length;
+ while (low + 1 < high) {
+ const middle = Math.floor((low + high) / 2);
+ if (offsets[middle]! <= byte) low = middle;
+ else high = middle;
+ }
+ return low + 1;
+ }
+ function rangeForSpan(span: Span): EvidenceRange {
+ const startLine = lineAt(span.start),
+ endLine = lineAt(Math.max(span.start, span.end - 1));
+ return {
+ startLine,
+ endLine,
+ ...(span.start !== offsets[startLine - 1] || span.end !== offsets[endLine]
+ ? { sourceByteStart: span.start, sourceByteEnd: span.end }
+ : {}),
+ };
+ }
+ function partialLine(unit: SourceUnit) {
+ return (
+ unit.sourceByteStart !== offsets[unit.range.startLine - 1] ||
+ unit.sourceByteEnd !== offsets[unit.range.endLine]
+ );
+ }
+ const syntax = await inspect(snapshot, { maxUnitBytes: sourceUnitBytes });
+ const selected: Span[] = (previous?.selected ?? []).map(spanForRange);
+ const leads = new Map<string, ReadingLead>();
+ function addLead(lead: ReadingLead) {
+ const key = JSON.stringify([lead.name, lead.range]);
+ const old = leads.get(key);
+ if (!old || lead.score > old.score) leads.set(key, lead);
+ }
+ for (const lead of previous?.leads ?? []) addLead({ ...lead, range: { ...lead.range } });
+ const groups: SourceUnit[][] = [];
+ let pending: SourceUnit[] = [];
+ for (const unit of syntax.units) {
+ if (
+ pending.length &&
+ (pending.length >= 8 || unit.sourceByteEnd - pending[0]!.sourceByteStart > 14000)
+ ) {
+ groups.push(pending);
+ pending = [];
+ }
+ pending.push(unit);
+ }
+ if (pending.length) groups.push(pending);
+ for (const group of groups) {
+ const first = Math.max(1, group[0]!.range.startLine - 8),
+ last = Math.min(lines.length, group.at(-1)!.range.endLine + 8);
+ const oversizedContext = [...lines.slice(0, 20), ...lines.slice(first - 1, last)].some(
+ (line) => Buffer.byteLength(line) > sourceUnitBytes,
+ );
+ // Line-only windows cannot describe a partial giant line; send only the parser's bounded byte spans.
+ const context =
+ group.some(partialLine) || oversizedContext
+ ? group
+ .map(
+ (unit) =>
+ `Source lines ${unit.range.startLine}-${unit.range.endLine}; source bytes ${unit.sourceByteStart}-${unit.sourceByteEnd}:\n${sourceForUnit(snapshot, unit)}`,
+ )
+ .join("\n")
+ : bytes.length <= 16000
+ ? snapshot.source
+ : `Opening context:\n${lines.slice(0, 20).join("\n")}\nSource lines ${first}-${last}:\n${lines.slice(first - 1, last).join("\n")}`;
+ const request = evidenceRequest(
+ query,
+ snapshot.path,
+ context,
+ group.map((unit) => ({ name: unit.name, ...unit.range })),
+ selectedEvidence,
+ );
+ try {
+ const answers = await evaluator.evaluate(request);
+ const values = group.map((unit, index) => {
+ const value = answers[`q${index}`];
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1)
+ throw new EvaluationFailure("provider");
+ return { unit, value };
+ });
+ for (const { unit, value } of values) {
+ if (value > 0.5) selected.push({ start: unit.sourceByteStart, end: unit.sourceByteEnd });
+ if (value > 0.25 && !unit.name.endsWith(".context"))
+ addLead({
+ name: unit.name,
+ range: rangeForSpan({ start: unit.sourceByteStart, end: unit.sourceByteEnd }),
+ score: value,
+ });
+ }
+ } catch (error) {
+ if (!(error instanceof EvaluationFailure)) throw error;
+ warn(error.kind);
+ if (error.kind !== "provider") break;
+ }
+ }
+ const chosen = mergeSpans(selected),
+ wholeRanges: Range[] = [],
+ rendered: Span[] = [];
+ for (const span of chosen) {
+ const range = rangeForSpan(span);
+ if (range.sourceByteStart !== undefined) rendered.push(span);
+ else wholeRanges.push(range);
+ }
+ const neighborhood = wholeRanges.length ? await pythonNeighborhood(snapshot, wholeRanges) : [];
+ const windows = [...wholeRanges, ...neighborhood].map((range) => ({
+ startLine: Math.max(1, range.startLine - 3),
+ endLine: Math.min(lines.length, range.endLine + 3),
+ }));
+ for (const window of windows) {
+ let changed = true;
+ while (changed) {
+ changed = false;
+ for (const comment of syntax.comments) {
+ const before =
+ comment.endLine < window.startLine &&
+ lines.slice(comment.endLine, window.startLine - 1).every((line) => !line.trim());
+ const after =
+ comment.startLine > window.endLine &&
+ lines.slice(window.endLine, comment.startLine - 1).every((line) => !line.trim());
+ if (
+ (comment.startLine <= window.endLine && comment.endLine >= window.startLine) ||
+ before ||
+ after
+ ) {
+ const start = Math.min(window.startLine, comment.startLine),
+ end = Math.max(window.endLine, comment.endLine);
+ if (start !== window.startLine || end !== window.endLine) {
+ window.startLine = start;
+ window.endLine = end;
+ changed = true;
+ }
+ }
+ }
+ }
+ let segmentStart = offsets[window.startLine - 1]!;
+ for (let line = window.startLine; line <= window.endLine; line++) {
+ const start = offsets[line - 1]!,
+ end = offsets[line]!;
+ // An adjacent selected declaration must not accidentally include an unselected giant line.
+ if (end - start > sourceUnitBytes) {
+ rendered.push({ start: segmentStart, end: start });
+ for (const span of chosen)
+ if (span.start < end && span.end > start)
+ rendered.push({ start: Math.max(span.start, start), end: Math.min(span.end, end) });
+ segmentStart = end;
+ }
+ }
+ rendered.push({ start: segmentStart, end: offsets[window.endLine]! });
+ }
+ const output = mergeSpans(rendered);
+ const file: FileEvidence = {
+ path: snapshot.path,
+ contentHash: snapshot.contentHash,
+ score,
+ roles: [...(previous?.roles ?? [])],
+ leads: [...leads.values()].sort(
+ (a, b) =>
+ a.range.startLine - b.range.startLine ||
+ a.range.endLine - b.range.endLine ||
+ a.name.localeCompare(b.name),
+ ),
+ selected: chosen.map(rangeForSpan),
+ rendered: output.map(rangeForSpan),
+ excerpts: output.map((span) => {
+ const range = rangeForSpan(span),
+ partial = range.sourceByteStart !== undefined;
+ return {
+ range,
+ source: bytes.subarray(span.start, span.end).toString("utf8"),
+ ...(partial ? { sourceByteStart: span.start, sourceByteEnd: span.end, partial: true } : {}),
+ };
+ }),
+ sourceOmitted: false,
+ };
+ return { file, issues: [...issues].map(([kind, count]) => ({ kind, count })) };
+}
diff --git a/packages/core/test/selection.test.ts b/packages/core/test/selection.test.ts
new file mode 100644
index 0000000..1eadf02
--- /dev/null
+++ b/packages/core/test/selection.test.ts
@@ -0,0 +1,240 @@
+import { expect, test } from "bun:test";
+import { selectFile } from "../src/selection";
+import { EvaluationFailure, type EvaluationRequest } from "../src/gateway";
+import type { Evaluator } from "../src/types";
+import type { Declaration } from "../src/requests";
+
+function evaluator(
+ score: (declaration: Declaration, request: EvaluationRequest) => number,
+): Evaluator {
+ return {
+ requests: 0,
+ async evaluate(request) {
+ const declarations = (request.state as { declarations: Declaration[] }).declarations;
+ return Object.fromEntries(
+ declarations.map((declaration, index) => [`q${index}`, score(declaration, request)]),
+ );
+ },
+ };
+}
+
+test("selected source and optional leads retain distinct meanings and exact original coordinates", async () => {
+ const source =
+ "// explanation\r\nexport function selected() {\r\n return 'é';\r\n}\r\n" +
+ "\r\n".repeat(10) +
+ "export function lead() { return 0; }\r\n";
+ const snapshot = { path: "example.ts", contentHash: "same snapshot", source };
+ const result = await selectFile(
+ snapshot,
+ "behavior",
+ 0.9,
+ evaluator((d) => (d.name === "selected" ? 0.8 : 0.4)),
+ );
+ expect(result.issues).toEqual([]);
+ expect(result.file.selected).toEqual([{ startLine: 2, endLine: 4 }]);
+ expect(result.file.leads.map((lead) => ({ name: lead.name, score: lead.score }))).toEqual([
+ { name: "selected", score: 0.8 },
+ { name: "lead", score: 0.4 },
+ ]);
+ expect(result.file.excerpts[0]!.source).toBe(source.split("\n").slice(0, 7).join("\n") + "\n");
+ expect(result.file.excerpts.some((excerpt) => excerpt.source.includes("function lead"))).toBe(
+ false,
+ );
+});
+
+test("strict thresholds keep .context out of leads without conflating it with source", async () => {
+ const source =
+ "class Example {\n alpha() { return 1; }\n beta() { return 2; }\n gamma() { return 3; }\n}\n";
+ const result = await selectFile(
+ { path: "thresholds.ts", contentHash: "x", source },
+ "q",
+ 0.8,
+ evaluator((d) =>
+ d.name.endsWith(".context")
+ ? 0.9
+ : d.name.endsWith("alpha")
+ ? 0.5
+ : d.name.endsWith("beta")
+ ? 0.25
+ : 0.26,
+ ),
+ );
+ expect(result.file.selected).toEqual([{ startLine: 1, endLine: 1 }]);
+ expect(result.file.leads.map((lead) => lead.name)).toEqual(["Example.alpha", "Example.gamma"]);
+});
+
+test("Python neighbors are rendering context and follow-up passes do not expand that context again", async () => {
+ const method = (name: string) =>
+ ` def ${name}(self):\n a = 1\n b = 2\n c = 3\n d = 4\n e = 5\n return a + b + c + d + e\n\n`;
+ const source =
+ "class Example:\n" + ["before", "target", "after", "unrelated", "later"].map(method).join("");
+ const snapshot = { path: "example.py", contentHash: "python", source };
+ const first = await selectFile(
+ snapshot,
+ "target behavior",
+ 0.9,
+ evaluator((d) => (d.name === "Example.target" ? 0.9 : 0)),
+ );
+ expect(first.issues).toEqual([]);
+ expect(first.file.selected).toEqual([{ startLine: 10, endLine: 16 }]);
+ expect(first.file.excerpts[0]!.source).toContain("def before");
+ expect(first.file.excerpts[0]!.source).toContain("def after");
+ first.file.roles = ["implementation"];
+ const evidence = [
+ { path: "test_example.py", startLine: 1, endLine: 1, source: "Example.target()" },
+ ];
+ let calls = 0;
+ const second = await selectFile(
+ snapshot,
+ "target behavior",
+ 0.9,
+ evaluator((_d, request) => {
+ calls++;
+ expect((request.state as { selectedEvidence: unknown }).selectedEvidence).toEqual(evidence);
+ expect(request.questions.q0!.instructions).toContain(
+ "exact symbol, fixture object, or event handler explicitly referenced",
+ );
+ return 0;
+ }),
+ evidence,
+ first.file,
+ );
+ expect(calls).toBeGreaterThan(0);
+ expect(second.file.excerpts).toEqual(first.file.excerpts);
+ expect(second.file.selected).toEqual(first.file.selected);
+ expect(second.file.roles).toEqual(["implementation"]);
+});
+
+test("provider failures retain successful groups and fatal failures stop subsequent groups", async () => {
+ const source = Array.from({ length: 20 }, (_, i) => `function f${i}() { return ${i}; }\n`).join(
+ "",
+ );
+ for (const kind of ["provider", "authentication", "request-limit", "cancelled"] as const) {
+ let calls = 0;
+ const fake: Evaluator = {
+ requests: 0,
+ async evaluate(request) {
+ calls++;
+ if (calls === 2) throw new EvaluationFailure(kind);
+ return Object.fromEntries(Object.keys(request.questions).map((key) => [key, 0.9]));
+ },
+ };
+ const result = await selectFile(
+ { path: "many.ts", contentHash: "many", source },
+ "q",
+ 0.9,
+ fake,
+ );
+ expect(result.issues).toEqual([{ kind, count: 1 }]);
+ expect(calls).toBe(kind === "provider" ? 3 : 2);
+ expect(result.file.selected).toEqual(
+ kind === "provider"
+ ? [
+ { startLine: 1, endLine: 8 },
+ { startLine: 17, endLine: 20 },
+ ]
+ : [{ startLine: 1, endLine: 8 }],
+ );
+ }
+});
+
+test("partial giant lines stay byte-bounded in requests, selections and additive passes", async () => {
+ const source = "é".repeat(18000) + "TARGET" + "z".repeat(75000) + "\n";
+ const snapshot = { path: "large.txt", contentHash: "large", source };
+ const first = await selectFile(
+ snapshot,
+ "TARGET",
+ 0.8,
+ evaluator((_d, request) => {
+ const context = (request.state as { source: string }).source;
+ expect(Buffer.byteLength(context)).toBeLessThan(25000);
+ return context.includes("TARGET") ? 0.9 : 0;
+ }),
+ );
+ expect(first.file.selected).toEqual([
+ { startLine: 1, endLine: 1, sourceByteStart: 24000, sourceByteEnd: 48000 },
+ ]);
+ const excerpt = first.file.excerpts[0]!;
+ expect(excerpt.source).toBe(Buffer.from(source).subarray(24000, 48000).toString("utf8"));
+ expect(excerpt).toMatchObject({ partial: true, sourceByteStart: 24000, sourceByteEnd: 48000 });
+ const second = await selectFile(
+ snapshot,
+ "TARGET",
+ 0.8,
+ evaluator(() => 0),
+ [{ path: "other.txt", startLine: 1, endLine: 1, source: "TARGET" }],
+ first.file,
+ );
+ expect(second.file.selected).toEqual(first.file.selected);
+ expect(second.file.excerpts).toEqual(first.file.excerpts);
+});
+
+test("malformed group answers stay unknown without discarding previous successes", async () => {
+ const source =
+ "function first() { return 1; }\n" + "\n".repeat(10) + "function second() { return 2; }\n";
+ const snapshot = { path: "a.ts", contentHash: "same", source };
+ const first = await selectFile(
+ snapshot,
+ "q",
+ 0.8,
+ evaluator((d) => (d.name === "first" ? 0.9 : 0)),
+ );
+ const broken: Evaluator = {
+ requests: 0,
+ async evaluate() {
+ return { q0: 0.9 };
+ },
+ };
+ const second = await selectFile(
+ snapshot,
+ "q",
+ 0.8,
+ broken,
+ [{ path: "other.ts", startLine: 1, endLine: 1, source: "first()" }],
+ first.file,
+ );
+ expect(second.issues).toEqual([{ kind: "provider", count: 1 }]);
+ expect(second.file.selected).toEqual(first.file.selected);
+ expect(second.file.excerpts).toEqual(first.file.excerpts);
+});
+
+test("ordinary large-source requests retain the frozen opening and eight-line window", async () => {
+ const source =
+ ("//" + "x".repeat(500) + "\n").repeat(40) + "function target() {\n return 1;\n}\n";
+ const lines = source.split("\n");
+ let captured: EvaluationRequest | undefined;
+ await selectFile(
+ { path: "context.ts", contentHash: "context", source },
+ "q",
+ 0.8,
+ evaluator((_d, request) => {
+ captured = request;
+ return 0;
+ }),
+ );
+ expect(captured!.state).toMatchObject({
+ source: `Opening context:\n${lines.slice(0, 20).join("\n")}\nSource lines 33-44:\n${lines.slice(32, 44).join("\n")}`,
+ declarations: [{ name: "target", startLine: 41, endLine: 43 }],
+ });
+});
+
+test("previous evidence from changed bytes is discarded explicitly", async () => {
+ const old = await selectFile(
+ { path: "a.ts", contentHash: "old", source: "function old() {return 1;}\n" },
+ "q",
+ 0.9,
+ evaluator(() => 0.9),
+ );
+ const next = await selectFile(
+ { path: "a.ts", contentHash: "new", source: "function next() {return 2;}\n" },
+ "q",
+ 0.9,
+ evaluator(() => 0),
+ [],
+ old.file,
+ );
+ expect(next.issues).toEqual([{ kind: "changed", count: 1 }]);
+ expect(next.file.selected).toEqual([]);
+ expect(next.file.leads).toEqual([]);
+ expect(next.file.excerpts).toEqual([]);
+});