toolroll 0.9.92 → 0.9.94

package/dist/code-map-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/code-map-main.js

@@ -0,0 +1,48 @@
+/**
+ * The code map's parser process (code-map-parse.ts): a static read of blobs Toolroll fetched, in its own process, with a
+ * capped heap and output. It reads one JSON request on stdin and writes one JSON answer on stdout. `createSourceFile`
+ * only: no Program, checker or plugin; nothing from the repository is imported or run; resolution is against the paths
+ * in the request.
+ */
+import { compilerOptionsOf, extractFile, resolveAll } from "./code-extract.js";
+const ROOT = "/repo";
+const chunks = [];
+for await (const chunk of process.stdin)
+    chunks.push(chunk);
+const request = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+const compiler = (await import("typescript-parser")).default;
+const normal = (file) => { const parts = []; for (const part of file.split("/")) {
+    if (part === "" || part === ".")
+        continue;
+    if (part === "..")
+        parts.pop();
+    else
+        parts.push(part);
+} return `/${parts.join("/")}`; };
+const known = new Map(request.paths.map(path => [`${ROOT}/${path}`, {}]));
+for (const file of request.files)
+    known.set(`${ROOT}/${file.path}`, { text: file.text });
+if (request.tsconfig !== null)
+    known.set(`${ROOT}/tsconfig.json`, { text: request.tsconfig });
+const directories = new Set([ROOT]);
+for (const path of known.keys()) {
+    let at = path.lastIndexOf("/");
+    while (at > ROOT.length) {
+        const dir = path.slice(0, at);
+        if (directories.has(dir))
+            break;
+        directories.add(dir);
+        at = dir.lastIndexOf("/");
+    }
+}
+const { options, problem } = compilerOptionsOf(compiler, `${ROOT}/tsconfig.json`, request.tsconfig ?? undefined, ROOT);
+const resolveOne = resolveAll(compiler, ROOT, known, directories, options, normal);
+const facts = request.files.map(file => {
+    const fileName = `${ROOT}/${file.path}`;
+    const read = extractFile(compiler, fileName, file.text);
+    return {
+        path: file.path, parseFailed: read.parseFailed, exports: read.exports,
+        specifiers: read.specifiers.map(one => { const to = resolveOne(one.specifier, fileName); return { specifier: one.specifier, kind: one.kind, line: one.line, to: to === null ? null : to.slice(ROOT.length + 1) }; }),
+    };
+});
+process.stdout.write(`${JSON.stringify({ version: compiler.version, tsconfig: problem, facts })}\n`);

package/dist/code-map-read.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The one reader of the code map (docs/plans/code-map.md §4, §6): the lead tools, MCP, chat, the page and the CLI all come
+ * through here, so they can't drift. It checks the project's switch and the remote's identity on every read. A first
+ * answer pins the current version; later pages name that version and a cursor, so a refresh between pages never skips
+ * or repeats entries. Everything it returns came from the repository and is labelled untrusted.
+ */
+import { type Refresh, type VersionRow } from "./code-map-store.js";
+import { type CodeMap, type MapArea, type MapFile } from "./code-map-shape.js";
+import { type Store } from "./store.js";
+export declare const ANSWER_BYTES: number;
+export type MapStateName = "not-available" | "off" | "making" | "current" | "stale" | "couldnt-check" | "too-large" | "remote-changed" | "empty" | "no-main";
+export type MapStatus = {
+    state: MapStateName;
+    words: string;
+    version: VersionRow | null;
+    nextTry: string | null;
+    movedTo: string | null;
+    refresh: Refresh | null;
+};
+/** The project's map state, as every surface states it. `at` renders a time; tests and the CLI use the plain ISO. */
+export declare function codeMapStatus(store: Store, repo: string, now: Date, at?: (iso: string) => string): MapStatus;
+/** The verified map at a version of this project, or why not. Identity is checked on every read. */
+export declare function openMap(store: Store, repo: string, version?: number): {
+    ok: true;
+    map: CodeMap;
+    version: VersionRow;
+} | {
+    ok: false;
+    state: "off" | "remote-changed" | "none" | "gone" | "unavailable";
+    words: string;
+};
+export type AreaRow = {
+    id: string;
+    name: string;
+    files: number;
+    languages: string[];
+    tests: number;
+    uses: {
+        id: string;
+        count: number;
+    }[];
+    usedBy: {
+        id: string;
+        count: number;
+    }[];
+};
+export declare const areaRow: (map: CodeMap, area: MapArea) => AreaRow;
+export declare const areaRows: (map: CodeMap) => AreaRow[];
+export type AreaView = {
+    area: AreaRow;
+    entryPoints: string[];
+    external: string[];
+    files: MapFile[];
+};
+export declare function areaView(map: CodeMap, id: string): AreaView | null;
+export type FileView = {
+    file: MapFile;
+    imports: {
+        path: string;
+        kind: string;
+        line: number;
+    }[];
+    importedBy: {
+        path: string;
+        kind: string;
+        line: number;
+    }[];
+};
+/** Exact lookup in the stored version: a path is never resolved, joined or normalized. */
+export declare function fileView(map: CodeMap, path: string): FileView | null;
+export type SearchHit = {
+    kind: "file" | "name";
+    path: string;
+    name: string | null;
+    line: number | null;
+};
+export declare function searchMap(map: CodeMap, query: string, limit?: number): SearchHit[];
+export type MapView = "overview" | "area" | "file" | "search";
+export type MapQuestion = {
+    repo: string;
+    version?: number;
+    view: MapView;
+    id?: string;
+    query?: string;
+    cursor?: string;
+};
+export type MapAnswer = {
+    v: 1;
+    ok: true;
+    label: string;
+    repo: string;
+    version: number;
+    commit: string;
+    view: MapView;
+    header: Record<string, unknown>;
+    items: unknown[];
+    omitted: number;
+    cursor: string | null;
+} | {
+    v: 1;
+    ok: false;
+    state: string;
+    message: string;
+};
+/** The labelled answer to one question, at most `maxBytes`. The first page pins the version it read. */
+export declare function answerMap(store: Store, question: MapQuestion, maxBytes?: number): MapAnswer;

package/dist/code-map-read.js

@@ -0,0 +1,171 @@
+/**
+ * The one reader of the code map (docs/plans/code-map.md §4, §6): the lead tools, MCP, chat, the page and the CLI all come
+ * through here, so they can't drift. It checks the project's switch and the remote's identity on every read. A first
+ * answer pins the current version; later pages name that version and a cursor, so a refresh between pages never skips
+ * or repeats entries. Everything it returns came from the repository and is labelled untrusted.
+ */
+import { codeMapOn, currentVersion, digestOfUrl, readRefresh, readVersionMap, versionRow } from "./code-map-store.js";
+import { codeMapLabel } from "./code-map-shape.js";
+import { REFRESH_EVERY_MS } from "./code-map-build.js";
+import { remoteUrlProblem } from "./remote-main.js";
+import { trustedRemoteIdentity } from "./store.js";
+export const ANSWER_BYTES = 6 * 1024;
+const short = (commit) => commit.slice(0, 7);
+/** The project's map state, as every surface states it. `at` renders a time; tests and the CLI use the plain ISO. */
+export function codeMapStatus(store, repo, now, at = iso => iso) {
+    const identity = trustedRemoteIdentity(store, repo);
+    const refresh = readRefresh(store, repo);
+    const base = { version: null, nextTry: null, movedTo: null, refresh };
+    if (identity === null || remoteUrlProblem(identity.url) !== null)
+        return { ...base, state: "not-available", words: "This project has no remote Toolroll can read, so it has no code map." };
+    if (!codeMapOn(store, repo))
+        return { ...base, state: "off", words: "The code map is off for this project." };
+    const nextTry = refresh === null ? null : refresh.retryAfter ?? (refresh.lastCheckedAt === null ? null : new Date(Date.parse(refresh.lastCheckedAt) + REFRESH_EVERY_MS).toISOString());
+    const version = currentVersion(store, repo);
+    const when = nextTry === null ? "" : ` Next try at ${at(nextTry)}.`;
+    if (version !== null && (version.remoteDigest !== digestOfUrl(identity.url) || version.remoteRecord !== identity.record))
+        return { ...base, nextTry, state: "remote-changed", words: "The project's remote changed. A new map is on its way." };
+    if (version === null) {
+        if (refresh?.seen.state === "no-main")
+            return { ...base, nextTry, state: "no-main", words: `The remote has no main branch yet.${when}` };
+        if (refresh?.seen.state === "too-large")
+            return { ...base, nextTry, state: "too-large", words: `${refresh.lastError ?? "This repository is too large"}.${when}` };
+        if (refresh?.lastError != null)
+            return { ...base, nextTry, state: "couldnt-check", words: `Couldn't check main: ${withoutPrefix(refresh.lastError)}${when}` };
+        const earlier = store.handle.prepare("SELECT 1 FROM code_map_version WHERE repo = ? LIMIT 1").get(repo);
+        if (earlier !== undefined)
+            return { ...base, nextTry, state: "remote-changed", words: "The project's remote changed. A new map is on its way." };
+        return { ...base, nextTry, state: "making", words: "Making the first map." };
+    }
+    const held = { ...base, version, nextTry };
+    if (refresh?.seen.state === "too-large")
+        return { ...held, state: "too-large", words: `${refresh.lastError ?? "Main is too large to map"}. Showing the last map.${when}` };
+    if (refresh?.lastError != null)
+        return { ...held, state: "couldnt-check", words: `Couldn't check main: ${withoutPrefix(refresh.lastError)}${when}` };
+    if (refresh?.seen.commit != null && refresh.seen.commit !== version.commit)
+        return { ...held, state: "stale", movedTo: refresh.seen.commit, words: `Main has moved to ${short(refresh.seen.commit)}.${nextTry === null ? "" : ` The next check is at ${at(nextTry)}.`}` };
+    if (refresh?.seen.state === "empty")
+        return { ...held, state: "empty", words: "This repository is empty." };
+    return { ...held, state: "current", words: `Main at ${short(version.commit)}.` };
+}
+const withoutPrefix = (why) => { const clean = why.replace(/^couldn't read main: /, ""); return /[.!]$/.test(clean) ? clean : `${clean}.`; };
+/** The verified map at a version of this project, or why not. Identity is checked on every read. */
+export function openMap(store, repo, version) {
+    if (!codeMapOn(store, repo))
+        return { ok: false, state: "off", words: "the code map is off for this project" };
+    const identity = trustedRemoteIdentity(store, repo);
+    const row = version === undefined ? currentVersion(store, repo) : versionRow(store, version);
+    if (row === null)
+        return version === undefined ? { ok: false, state: "none", words: "there is no code map for this project yet" } : { ok: false, state: "gone", words: "the map changed; start again" };
+    if (row.repo !== repo)
+        return { ok: false, state: "gone", words: "the map changed; start again" };
+    if (identity === null || row.remoteDigest !== digestOfUrl(identity.url) || row.remoteRecord !== identity.record)
+        return { ok: false, state: "remote-changed", words: "the project's remote changed" };
+    const map = readVersionMap(store, row.id);
+    if (map === null)
+        return { ok: false, state: "unavailable", words: "the saved map couldn't be verified" };
+    return { ok: true, map, version: row };
+}
+const mainLanguages = (area) => Object.entries(area.languages).sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0)).slice(0, 3).map(([name]) => name);
+const connections = (map, id) => ({
+    uses: map.areaEdges.filter(one => one.from === id).sort((a, b) => b.count - a.count).map(one => ({ id: one.to, count: one.count })),
+    usedBy: map.areaEdges.filter(one => one.to === id).sort((a, b) => b.count - a.count).map(one => ({ id: one.from, count: one.count })),
+});
+export const areaRow = (map, area) => ({ id: area.id, name: area.name, files: area.files, languages: mainLanguages(area), tests: area.tests, ...connections(map, area.id) });
+export const areaRows = (map) => map.areas.map(area => areaRow(map, area));
+export function areaView(map, id) {
+    const area = map.areas.find(one => one.id === id);
+    if (area === undefined)
+        return null;
+    return { area: areaRow(map, area), entryPoints: area.entryPoints, external: map.external.find(one => one.area === id)?.packages ?? [], files: map.files.filter(one => one.area === id) };
+}
+/** Exact lookup in the stored version: a path is never resolved, joined or normalized. */
+export function fileView(map, path) {
+    const file = map.files.find(one => one.path === path);
+    if (file === undefined)
+        return null;
+    return { file, imports: map.edges.filter(one => one.from === path).map(one => ({ path: one.to, kind: one.kind, line: one.line })), importedBy: map.edges.filter(one => one.to === path).map(one => ({ path: one.from, kind: one.kind, line: one.line })) };
+}
+const wordsOf = (query) => query.toLowerCase().split(/\s+/).filter(Boolean).slice(0, 8);
+export function searchMap(map, query, limit = 500) {
+    const words = wordsOf(query);
+    if (words.length === 0)
+        return [];
+    const hits = [];
+    for (const file of map.files) {
+        const lower = file.path.toLowerCase();
+        if (words.every(word => lower.includes(word)))
+            hits.push({ kind: "file", path: file.path, name: null, line: null });
+        for (const symbol of file.symbols) {
+            const name = symbol.name.toLowerCase();
+            if (words.every(word => name.includes(word) || lower.includes(word)) && words.some(word => name.includes(word)))
+                hits.push({ kind: "name", path: file.path, name: symbol.name, line: symbol.line });
+        }
+        if (hits.length >= limit)
+            break;
+    }
+    return hits.slice(0, limit);
+}
+const refused = (state, message) => ({ v: 1, ok: false, state, message });
+const thinFile = (file) => ({ path: file.path, bytes: file.bytes, lang: file.lang, test: file.test, names: file.symbols.slice(0, 40).map(one => one.name), more: Math.max(0, file.symbols.length - 40) });
+/** The labelled answer to one question, at most `maxBytes`. The first page pins the version it read. */
+export function answerMap(store, question, maxBytes = ANSWER_BYTES) {
+    let offset = 0, pinned = question.version;
+    if (question.cursor !== undefined) {
+        const read = /^(\d+)\.(\d+)$/.exec(question.cursor);
+        if (read === null || (pinned !== undefined && Number(read[1]) !== pinned))
+            return refused("gone", "the map changed; start again");
+        pinned = Number(read[1]);
+        offset = Number(read[2]);
+    }
+    const opened = openMap(store, question.repo, pinned);
+    if (!opened.ok)
+        return refused(opened.state, opened.words);
+    const { map, version } = opened;
+    let header;
+    let items;
+    if (question.view === "overview") {
+        header = { counts: map.counts, packages: map.packages.map(one => ({ root: one.root, name: one.name, entryPoints: one.entryPoints.slice(0, 8) })).slice(0, 8), warnings: map.warnings };
+        items = areaRows(map).map(one => ({ ...one, uses: one.uses.slice(0, 8), usedBy: one.usedBy.slice(0, 8) }));
+    }
+    else if (question.view === "area") {
+        const view = question.id === undefined ? null : areaView(map, question.id);
+        if (view === null)
+            return refused("not-found", "no area with that id in this version");
+        header = { area: { ...view.area, uses: view.area.uses.slice(0, 12), usedBy: view.area.usedBy.slice(0, 12) }, entryPoints: view.entryPoints.slice(0, 12), external: view.external.slice(0, 30) };
+        items = view.files.map(thinFile);
+    }
+    else if (question.view === "file") {
+        const view = question.id === undefined ? null : fileView(map, question.id);
+        if (view === null)
+            return refused("not-found", "no file with that path in this version");
+        header = { path: view.file.path, area: view.file.area, bytes: view.file.bytes, lang: view.file.lang, state: view.file.state, test: view.file.test };
+        items = [...view.file.symbols.map(one => ({ exported: one.name, kind: one.kind, line: one.line })), ...view.imports.map(one => ({ imports: one.path, kind: one.kind, line: one.line })), ...view.importedBy.map(one => ({ importedBy: one.path, kind: one.kind, line: one.line }))];
+    }
+    else {
+        if (question.query === undefined || wordsOf(question.query).length === 0)
+            return refused("usage", "say what to search for");
+        header = { query: question.query.slice(0, 200) };
+        items = searchMap(map, question.query);
+    }
+    const answer = { v: 1, ok: true, label: codeMapLabel(version.commit), repo: question.repo, version: version.id, commit: version.commit, view: question.view, header, items: [], omitted: 0, cursor: null };
+    const size = () => Buffer.byteLength(JSON.stringify(answer));
+    // Room for the cursor it may need, and never more than the limit.
+    const budget = maxBytes - 48;
+    let at = offset;
+    for (; at < items.length; at++) {
+        answer.items.push(items[at]);
+        if (size() > budget) {
+            answer.items.pop();
+            // One item wider than a whole answer is skipped and counted, so paging always moves on.
+            if (answer.items.length === 0) {
+                answer.omitted++;
+                continue;
+            }
+            break;
+        }
+    }
+    if (at < items.length)
+        answer.cursor = `${version.id}.${at}`;
+    return answer;
+}

package/dist/code-map-report.d.ts

@@ -0,0 +1,37 @@
+import { type Store } from "./store.js";
+export declare const ENOUGH_FAMILIES = 10;
+export type Arm = "map" | "holdout";
+export type ArmReport = {
+    families: number;
+    notEligible: number;
+    complete: number;
+    stillRunning: number;
+    inWindow: number;
+    deliveredDifferently: number;
+    /** Per complete family; null with no known value. */
+    personRevisions: number | null;
+    firstCheckPassed: {
+        passed: number;
+        known: number;
+    };
+    apiUsd: number | null;
+    subscriptionTokens: number | null;
+    turns: number | null;
+    records: Record<string, number>;
+};
+export type CodeMapReport = {
+    v: 1;
+    repo: string;
+    asOf: string;
+    enrollUntil: string | null;
+    enough: boolean;
+    arms: Record<Arm, ArmReport>;
+};
+export declare function codeMapReport(store: Store, repo: string, now: Date): CodeMapReport;
+/** The rows every surface shows: a label and each arm's value. Below 10 complete families in an arm there is no comparison. */
+export declare function reportRows(report: CodeMapReport): {
+    label: string;
+    map: string;
+    holdout: string;
+}[];
+export declare const NOT_ENOUGH = "Not enough results yet.";

package/dist/code-map-report.js

@@ -0,0 +1,95 @@
+/**
+ * Builds with and without the map (docs/plans/code-map.md §7), by assigned arm. Run usage is overwritten in place, so no
+ * instant inside a run can be rebuilt: a run counts when it was admitted before its family's cutoff and has finished,
+ * and then its whole usage counts. Measures come from those runs, never route_record's totals, which grow until `closed`.
+ * People read this; nothing switches on it. Unknown is null, shown as —, never 0.
+ */
+import { firstCheckPassedOf, personRevisionsOf } from "./route-results.js";
+import { runAccounting } from "./store.js";
+export const ENOUGH_FAMILIES = 10;
+/** The family's counted runs: admitted before the cutoff. A run after it never counts. */
+function countedRuns(store, refs, cutoff) {
+    return refs.flatMap(ref => store.runsFor(ref)).filter(run => (run.role === "builder" || run.role === "repair") && Date.parse(run.startedAt) < cutoff).sort((a, b) => a.id - b.id);
+}
+function readFamily(store, row, now) {
+    const root = String(row["root_task"]), arm = String(row["arm"]), cutoff = Date.parse(String(row["observe_until"]));
+    const family = store.taskFamilyOf(root, null, true);
+    const versions = family !== null && family.problem === null ? family.versions : [];
+    const refs = versions.length > 0 ? versions.map(one => one.refId) : [store.refFor("built-in", root).id];
+    const runs = countedRuns(store, refs, cutoff);
+    const unfinished = runs.some(run => run.finishedAt === null);
+    const status = unfinished ? "still-running" : now.getTime() < cutoff ? "in-window" : "complete";
+    const ids = JSON.stringify(runs.map(run => run.id));
+    const cohort = store.handle.prepare("SELECT ineligible FROM run_cohort WHERE run IN (SELECT value FROM json_each(?)) ORDER BY run LIMIT 1").get(ids);
+    const eligible = cohort !== undefined && cohort["ineligible"] === null;
+    let apiMicrousd = 0, subscriptionTokens = 0, turns = 0;
+    for (const run of runs) {
+        if (run.providerStartedAt === null)
+            continue;
+        const accounting = runAccounting(store, run.id);
+        if (accounting === null || accounting.amount.kind === "unknown") {
+            apiMicrousd = null;
+            subscriptionTokens = null;
+        }
+        else if (accounting.amount.kind === "api") {
+            if (apiMicrousd !== null)
+                apiMicrousd += accounting.amount.microusd;
+        }
+        else if (subscriptionTokens !== null)
+            subscriptionTokens += (accounting.usage.in ?? 0) + (accounting.usage.out ?? 0);
+        if (run.agentTurns == null)
+            turns = null;
+        else if (turns !== null)
+            turns += run.agentTurns;
+    }
+    // A revision counts when it was filed before the cutoff; the root isn't one.
+    const filed = versions.filter(one => one.id !== root && Date.parse(one.createdAt) < cutoff).map(one => one.refId);
+    const states = store.handle.prepare("SELECT state FROM code_map_snapshot WHERE run IN (SELECT value FROM json_each(?))").all(ids).map(one => String(one["state"]));
+    const record = versions.length === 0 ? undefined : store.handle.prepare("SELECT state FROM route_record WHERE task_ref = ?").get(family.root.refId);
+    return { root, arm, eligible, status, revisions: personRevisionsOf(store, filed), firstCheck: firstCheckPassedOf(store, runs), apiMicrousd, subscriptionTokens, turns,
+        differently: states.some(state => state !== arm), record: record === undefined ? null : String(record["state"]) };
+}
+const mean = (values) => { const known = values.filter((one) => one !== null); return known.length === 0 ? null : known.reduce((a, b) => a + b, 0) / known.length; };
+function armReport(all) {
+    const eligible = all.filter(one => one.eligible);
+    const complete = eligible.filter(one => one.status === "complete");
+    const checks = complete.filter(one => one.firstCheck !== null);
+    const api = mean(complete.map(one => one.apiMicrousd));
+    const records = {};
+    for (const one of eligible)
+        if (one.record !== null)
+            records[one.record] = (records[one.record] ?? 0) + 1;
+    return {
+        families: all.length, notEligible: all.length - eligible.length, complete: complete.length, stillRunning: eligible.filter(one => one.status === "still-running").length, inWindow: eligible.filter(one => one.status === "in-window").length,
+        deliveredDifferently: eligible.filter(one => one.differently).length, personRevisions: mean(complete.map(one => one.revisions)),
+        firstCheckPassed: { passed: checks.filter(one => one.firstCheck === true).length, known: checks.length }, apiUsd: api === null ? null : api / 1_000_000,
+        subscriptionTokens: mean(complete.map(one => one.subscriptionTokens)), turns: mean(complete.map(one => one.turns)), records,
+    };
+}
+export function codeMapReport(store, repo, now) {
+    const rows = store.handle.prepare("SELECT root_task, arm, observe_until FROM code_map_family WHERE repo = ? ORDER BY root_task").all(repo);
+    const reads = rows.flatMap(row => readFamily(store, row, now) ?? []);
+    const arms = { map: armReport(reads.filter(one => one.arm === "map")), holdout: armReport(reads.filter(one => one.arm === "holdout")) };
+    const until = store.handle.prepare("SELECT code_map_enroll_until AS at FROM project WHERE path = ?").get(repo)?.["at"];
+    return { v: 1, repo, asOf: now.toISOString(), enrollUntil: typeof until === "string" ? until : null, enough: arms.map.complete >= ENOUGH_FAMILIES && arms.holdout.complete >= ENOUGH_FAMILIES, arms };
+}
+const number = (value, digits = 1) => (value === null ? "—" : value.toFixed(digits));
+/** The rows every surface shows: a label and each arm's value. Below 10 complete families in an arm there is no comparison. */
+export function reportRows(report) {
+    const both = (label, read) => ({ label, map: read(report.arms.map), holdout: read(report.arms.holdout) });
+    const counts = [
+        both("Builds enrolled", arm => String(arm.families)), both("Compared", arm => String(arm.complete)), both("Still running", arm => String(arm.stillRunning)),
+        both("Still in their window", arm => String(arm.inWindow)), both("Not eligible", arm => String(arm.notEligible)), both("Delivered differently", arm => String(arm.deliveredDifferently)),
+    ];
+    if (!report.enough)
+        return counts;
+    return [...counts,
+        both("Revisions by a person, per build", arm => number(arm.personRevisions, 2)),
+        both("First check passed", arm => (arm.firstCheckPassed.known === 0 ? "—" : `${arm.firstCheckPassed.passed} of ${arm.firstCheckPassed.known}`)),
+        both("API dollars, per build", arm => (arm.apiUsd === null ? "—" : `$${arm.apiUsd.toFixed(2)}`)),
+        both("Subscription tokens, per build", arm => number(arm.subscriptionTokens, 0)),
+        both("Turns, per build", arm => number(arm.turns, 1)),
+        both(`Result records as of ${report.asOf.slice(0, 10)}`, arm => Object.entries(arm.records).sort().map(([state, count]) => `${count} ${state}`).join(", ") || "—"),
+    ];
+}
+export const NOT_ENOUGH = "Not enough results yet.";

package/dist/code-map-shape.d.ts

@@ -0,0 +1,172 @@
+/**
+ * The generated code map's shape and the pure work of making it from a tree and parsed facts (docs/plans/code-map.md §1).
+ * No file text is stored: only names, lines, sizes and edges. Every name here came from the repository and is untrusted.
+ */
+export declare const CODE_MAP_VERSION = 1;
+export declare const EXTRACTOR_TAG = "map-v1";
+/** On every excerpt, answer and file. `<commit>` is the full commit the map was made from. */
+export declare const codeMapLabel: (commit: string) => string;
+export declare const LIMITS: {
+    readonly treeEntries: 50000;
+    readonly pathBytes: 1024;
+    readonly pathDepth: 32;
+    readonly fileBytes: number;
+    readonly filesRead: 20000;
+    readonly bytesRead: number;
+    readonly symbolsPerFile: 200;
+    readonly symbols: 200000;
+    readonly symbolChars: 200;
+    readonly edges: 300000;
+    readonly storedBytes: number;
+    readonly areas: 400;
+    readonly groupAbove: 40;
+    readonly groupAtLeast: 3;
+    readonly manifestBytes: number;
+    readonly parserOutput: number;
+    readonly parserHeapMb: 768;
+    readonly parserMs: 120000;
+};
+export type Lang = "ts" | "js" | "python" | "go" | "rust" | "java" | "kotlin" | "swift" | "ruby" | "php" | "c" | "cpp" | "csharp" | "shell" | "sql" | "docs" | "config" | "binary" | "other";
+export type FileState = "read" | "path-only" | "too-large" | "parse-error" | "withheld";
+export type MapSymbol = {
+    name: string;
+    kind: string;
+    line: number;
+};
+export type MapFile = {
+    path: string;
+    area: string;
+    kind: "file" | "exec" | "link" | "submodule";
+    bytes: number;
+    lang: Lang;
+    state: FileState;
+    test: string | null;
+    symbols: MapSymbol[];
+};
+export type MapEdge = {
+    from: string;
+    to: string;
+    kind: "imports" | "re-exports" | "dynamic-import";
+    line: number;
+};
+export type MapArea = {
+    id: string;
+    name: string;
+    root: string;
+    package: string;
+    files: number;
+    bytes: number;
+    languages: Partial<Record<Lang, number>>;
+    tests: number;
+    entryPoints: string[];
+};
+export type MapPackage = {
+    root: string;
+    name: string | null;
+    manifest: string | null;
+    entryPoints: string[];
+};
+export type MapCounts = {
+    entries: number;
+    files: number;
+    read: number;
+    pathOnly: number;
+    tooLarge: number;
+    parseErrors: number;
+    withheld: number;
+    links: number;
+    submodules: number;
+    vendored: number;
+};
+export type MapWarning = "symbols-truncated" | "edges-truncated" | "read-limit" | "areas-folded" | "tsconfig-extends" | "tsconfig-unreadable";
+export type CodeMapManifest = {
+    v: 1;
+    label: string;
+    repo: string;
+    commit: string;
+    remote: {
+        urlDigest: string;
+        record: number;
+    };
+    builtAt: string;
+    extractor: string;
+    counts: MapCounts;
+    packages: MapPackage[];
+    areas: MapArea[];
+    files: MapFile[];
+    areaEdges: {
+        from: string;
+        to: string;
+        count: number;
+    }[];
+    external: {
+        area: string;
+        packages: string[];
+    }[];
+    vendored: {
+        path: string;
+        files: number;
+        bytes: number;
+    }[];
+    warnings: MapWarning[];
+};
+export type CodeMapGraph = {
+    edges: MapEdge[];
+};
+export type CodeMap = CodeMapManifest & CodeMapGraph;
+export declare const CODE_FILE: RegExp;
+export declare const isParsedLanguage: (path: string) => boolean;
+/** The vendored or built folder a path sits under, as a path; null when it doesn't. */
+export declare function vendoredRoot(path: string): string | null;
+export declare function languageOf(path: string): Lang;
+/** A name with control characters, bidirectional controls or invalid UTF-8 (read as U+FFFD) is withheld. Secrets are
+ * scanned over the whole list at once (`secretLines`). */
+export declare const unsafeName: (name: string) => boolean;
+export type TreeEntry = {
+    path: string;
+    mode: string;
+    bytes: number;
+};
+export type FileFacts = {
+    exports: MapSymbol[];
+    imports: {
+        to: string;
+        kind: MapEdge["kind"];
+        line: number;
+    }[];
+    external: string[];
+    parseFailed: boolean;
+};
+export type BuildInput = {
+    repo: string;
+    commit: string;
+    remote: {
+        urlDigest: string;
+        record: number;
+    };
+    builtAt: string;
+    extractor: string;
+    /** Every tree entry whose name passed, vendored ones included. */
+    entries: readonly TreeEntry[];
+    /** Tree entries in all, withheld ones included. */
+    entryCount: number;
+    withheld: number;
+    /** path → what was parsed; a path missing here wasn't read. */
+    facts: ReadonlyMap<string, FileFacts>;
+    /** path → why a TS/JS file wasn't read. */
+    unread: ReadonlyMap<string, "too-large" | "path-only">;
+    /** package.json files' read values, by path. */
+    manifests: ReadonlyMap<string, {
+        name: string | null;
+        entries: string[];
+    }>;
+    warnings: readonly MapWarning[];
+};
+export declare function buildCodeMap(input: BuildInput): CodeMap;
+/** The bare package a specifier names (`@scope/x/y` → `@scope/x`); null for a relative, absolute, built-in or `#` one. */
+export declare function externalPackage(specifier: string): string | null;
+/** package.json's string `main`, `module`, `bin` and `exports` values; everything else is ignored. */
+export declare function manifestEntries(text: string): {
+    name: string | null;
+    entries: string[];
+} | null;