Function explore

__tests__/explore-allocation-e2e.test.ts:84–133

* One explore call, reduced to what the allocation assertions need — plus the * CG-4 per-file diagnostic, which is where the SCORE and the RESERVATION live. * The instrument is observational (byte-identical output either way), so reading * it here measures the same response the agent would have r

(project: Project, query: string)

 * it here measures the same response the agent would have received.
 */
async function explore(project: Project, query: string) {
  // Outside the project root on purpose: a sidecar written INTO the indexed tree
  // is a new file the watcher can pick up mid-suite.
  const sidecar = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-alloc-diag-')), 'report.jsonl');
  const previous = process.env[DEBUG_ENV];
  process.env[DEBUG_ENV] = sidecar;
  let result;
  try {
    result = await project.handler.execute('codegraph_explore', { query });
  } finally {
    if (previous === undefined) delete process.env[DEBUG_ENV];
    else process.env[DEBUG_ENV] = previous;
  }
  const text = result.content?.[0]?.text ?? '';
  const bytes = attributeSourceBytes(text);
  const lines = fs.existsSync(sidecar)
    ? fs.readFileSync(sidecar, 'utf-8').trim().split('\n').filter(Boolean)
    : [];
  const report = JSON.parse(lines[lines.length - 1]!) as ExploreDiagnosticReport;
  fs.rmSync(path.dirname(sidecar), { recursive: true, force: true });
  const fileOf = (file: string) => report.files.find((f) => f.path === file);
  return {
    text,
    bytes,
    report,
    isError: result.isError === true,
    /** Relevance score the ranking pass gave this file. */
    score: (file: string) => fileOf(file)?.score ?? 0,
    /** Chars of source the allocator RESERVED for it, before anything rendered. */
    allowance: (file: string) => fileOf(file)?.allowance ?? 0,
    /** Which render path the loop took: `whole`, `clusters`, `focused`, `skeleton`. */
    render: (file: string) => fileOf(file)?.render ?? null,
    /**
     * Rank the ranking pass gave it (1 = the file the response leads with, and
     * the first the render loop reaches). Read off the record rather than from
     * the position in `report.files`, which the report re-sorts by delivered
     * bytes for legibility.
     */
    rank: (file: string) => fileOf(file)?.rank ?? -1,
    /** Total source bytes delivered across every rendered file. */
    sourceTotal: () => [...bytes.values()].reduce((sum, n) => sum + n, 0),
    /** Fraction of the WHOLE response this file's source occupies. */
    share: (file: string) => (bytes.get(file) ?? 0) / (text.length || 1),
    shareUnder: (prefix: string) => {
      let total = 0;
      for (const [file, n] of bytes) if (file.startsWith(prefix)) total += n;
      return total / (text.length || 1);
    },
  };
}

// ── 1. The self-query fixture's shape ───────────────────────────────────────