Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.
TypeScript ai-sdkclaude-codeclicode-searchcodexcoding-agentscontext-retrievaldeveloper-toolsjevsemantic-searchtypescriptvercel-ai-gateway
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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([]);+});