visualproof 0.0.0-stage → 0.2.0

package/dist/server/export.js

@@ -0,0 +1,420 @@
+// The exported document, compiled (ExportSpec decision 6): a .tex made by shared/doc/latex.ts,
+// typeset by XeLaTeX with the style file and the fonts this repository holds (assets/latex/,
+// assets/fonts/). Typesetting takes seconds for a large document, so a request starts a job and
+// is answered at once; the page asks how the job is doing and fetches the PDF once it is done.
+//
+// XeLaTeX runs in a temporary directory of its own under the project's cache, never in the project:
+// with -no-shell-escape (no program is ever run), -halt-on-error, nothing read from the terminal,
+// TeX's paranoid file access (openin_any=p, openout_any=p: nothing read or written by an absolute
+// path or outside that directory, beyond TeX's own trees), and a time limit after which it is
+// killed. The .tex itself holds nothing a reader wrote that LaTeX would read as a command (its
+// escaping, shared/doc/latex.ts); these are a second wall. The directory goes once the run is over,
+// whatever happened.
+//
+// A document is known by a hash of its .tex and the style file: the same request again is the same
+// job, running or done, and a done one is kept in a cache of the last few under the project's cache
+// (`export/cache/<hash>/`), so that a reader downloading the sources after the PDF, or a second
+// reader asking for the same document, does not typeset it again. Its figures (the images and clips
+// its notes carry, server/figures.ts) are written beside it in `figures/` before XeLaTeX runs, kept
+// with it in the cache and in the sources' zip; their names say what they are drawn from, so the
+// .tex names them too.
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { deflateRawSync } from "node:zlib";
+/** The repository's assets: the style file and the fonts it loads. */
+const ASSETS = resolve(import.meta.dirname, "..", "assets");
+export const STYLE_FILE = join(ASSETS, "latex", "visualproof.sty");
+export const FONTS_DIR = join(ASSETS, "fonts");
+/** How many runs of XeLaTeX one document may take: the second resolves page references and the
+ *  bookmarks; a third only where the second moved a page break. */
+const MAX_RUNS = 3;
+/** How much of XeLaTeX's log a failed job keeps, in characters: its end, where the error is. */
+const LOG_TAIL = 4000;
+/** What stands in for a figure that could not be made: a white pixel, so that the rest still prints
+ *  and the job's notes say which. */
+const BLANK_PNG = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mP4//8/AAX+Av4zEpUUAAAAAElFTkSuQmCC", "base64");
+/** A figure's name as the .tex gives it (shared/doc/latex.ts, figureAsset): nothing else is written. */
+const FIGURE_NAME = /^(?:fig|clip)-[0-9a-z-]{1,200}\.(?:png|jpg)$/;
+export class Exporter {
+    dir;
+    cacheDir;
+    timeoutMs;
+    xelatex;
+    maxCached;
+    concurrent;
+    jobs = new Map();
+    /** the jobs' ends, for whoever waits on one */
+    ends = new Map();
+    running = 0;
+    queue = [];
+    found = null;
+    constructor(cacheDir, o = {}) {
+        this.dir = join(cacheDir, "export");
+        this.cacheDir = join(this.dir, "cache");
+        this.timeoutMs = o.timeoutMs ?? 120_000;
+        this.xelatex = o.xelatex ?? "xelatex";
+        this.maxCached = o.maxCached ?? 20;
+        this.concurrent = o.concurrent ?? 2;
+    }
+    /** Whether XeLaTeX can be run here: asked once. */
+    available() {
+        if (this.found === null) {
+            const r = spawnSync(this.xelatex, ["--version"], { stdio: "ignore", timeout: 10_000 });
+            this.found = r.status === 0;
+        }
+        return this.found;
+    }
+    /** The style file as it is now: part of what names a document, so that a changed style typesets
+     *  again. */
+    style() {
+        return readFileSync(STYLE_FILE, "utf8");
+    }
+    /** Typeset `tex`: the job that does it, at once — the one already running or done for the same
+     *  document, else a new one. `notes`: what the job says besides the document (`ExportJob.notes`).
+     *  `figures`: the files the .tex includes from `figures/`, made when it is typeset. */
+    compile(tex, notes = [], figures = []) {
+        const sty = this.style();
+        const id = createHash("sha256").update(tex).update("\u0000").update(sty).digest("hex").slice(0, 32);
+        const note = (j) => {
+            if (notes.length)
+                j.notes = [...notes];
+            else
+                delete j.notes;
+            return j;
+        };
+        const known = this.jobs.get(id);
+        if (known && known.state !== "failed")
+            return note(known);
+        const kept = this.fromCache(id);
+        if (kept) {
+            this.remember(note(kept));
+            this.ends.set(id, Promise.resolve(kept));
+            return kept;
+        }
+        const job = note({ id, state: "running", at: new Date().toISOString() });
+        this.remember(job);
+        this.ends.set(id, this.turn().then(async () => {
+            try {
+                await this.run(job, tex, sty, figures);
+            }
+            catch (e) {
+                job.state = "failed";
+                job.error = e instanceof Error ? e.message : String(e);
+            }
+            finally {
+                this.running--;
+                this.queue.shift()?.();
+            }
+            return job;
+        }));
+        return job;
+    }
+    /** A job by its id: one this server knows, or one the cache holds. */
+    job(id) {
+        if (!/^[0-9a-f]{32}$/.test(id))
+            return null;
+        const j = this.jobs.get(id) ?? this.fromCache(id);
+        if (j)
+            this.remember(j);
+        return j;
+    }
+    /** The job once it is over. */
+    wait(id) {
+        return this.ends.get(id) ?? Promise.resolve(this.job(id));
+    }
+    /** A file of a done job: the PDF, the .tex, the style file, or a zip of everything needed to
+     *  typeset it again (the .tex, the style file, the fonts, a README). Null where the job is not
+     *  done, or no longer in the cache. */
+    file(id, what) {
+        const j = this.job(id);
+        if (!j || j.state !== "done")
+            return null;
+        const at = join(this.cacheDir, id);
+        try {
+            switch (what) {
+                case "pdf":
+                    return { body: readFileSync(join(at, "doc.pdf")), type: "application/pdf", name: "visualproof-export.pdf" };
+                case "tex":
+                    return { body: readFileSync(join(at, "doc.tex")), type: "application/x-tex; charset=utf-8", name: "visualproof-export.tex" };
+                case "sty":
+                    return { body: readFileSync(join(at, "visualproof.sty")), type: "application/x-tex; charset=utf-8", name: "visualproof.sty" };
+                case "zip": {
+                    const file = join(at, "sources.zip");
+                    if (!existsSync(file))
+                        writeFileSync(file, this.sources(at));
+                    return { body: readFileSync(file), type: "application/zip", name: "visualproof-export-sources.zip" };
+                }
+            }
+        }
+        catch {
+            // gone from the cache meanwhile
+            return null;
+        }
+    }
+    /** A turn to typeset: at most `concurrent` at once, the rest in order. */
+    turn() {
+        if (this.running < this.concurrent) {
+            this.running++;
+            return Promise.resolve();
+        }
+        return new Promise((ok) => this.queue.push(() => {
+            this.running++;
+            ok();
+        }));
+    }
+    /** Keep a job among those this server knows, the last hundred. */
+    remember(j) {
+        this.jobs.delete(j.id);
+        this.jobs.set(j.id, j);
+        while (this.jobs.size > 100) {
+            const first = this.jobs.keys().next().value;
+            this.jobs.delete(first);
+            this.ends.delete(first);
+        }
+    }
+    /** A done job the cache holds, as a job. */
+    fromCache(id) {
+        try {
+            const meta = JSON.parse(readFileSync(join(this.cacheDir, id, "job.json"), "utf8"));
+            if (!existsSync(join(this.cacheDir, id, "doc.pdf")))
+                return null;
+            return { id, state: "done", at: meta.at, pages: meta.pages, ms: meta.ms, runs: meta.runs, cached: true, ...(meta.notes?.length ? { notes: meta.notes } : {}) };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Typeset in a directory of its own, as often as the log asks (at most MAX_RUNS), then keep
+     *  the result in the cache. The directory goes whatever happens. */
+    async run(job, tex, sty, figures = []) {
+        mkdirSync(this.dir, { recursive: true });
+        const tmp = mkdtempSync(join(this.dir, "run-"));
+        const start = Date.now();
+        try {
+            writeFileSync(join(tmp, "doc.tex"), tex);
+            writeFileSync(join(tmp, "visualproof.sty"), sty);
+            // the fonts as the style file loads them, from fonts/ beside the document
+            symlinkSync(FONTS_DIR, join(tmp, "fonts"), "dir");
+            // the figures the .tex includes; one that cannot be made is a blank, and the job says which
+            if (figures.length)
+                mkdirSync(join(tmp, "figures"));
+            const failed = [];
+            for (const f of figures) {
+                if (!FIGURE_NAME.test(f.name))
+                    continue;
+                let bytes;
+                try {
+                    bytes = await f.make();
+                }
+                catch (e) {
+                    failed.push(`${f.name} (${e instanceof Error ? e.message : String(e)})`);
+                    bytes = BLANK_PNG;
+                }
+                writeFileSync(join(tmp, "figures", f.name), bytes);
+            }
+            if (failed.length)
+                job.notes = [...(job.notes ?? []), `${failed.length === 1 ? "A figure" : `${failed.length} figures`} could not be drawn and ${failed.length === 1 ? "is" : "are"} left blank: ${failed.join("; ")}.`];
+            let log = "";
+            let runs = 0;
+            for (;;) {
+                runs++;
+                const left = this.timeoutMs - (Date.now() - start);
+                const r = await this.xetex(tmp, left);
+                log = readLog(tmp);
+                if (r === "timeout")
+                    throw Object.assign(new Error(`Typesetting took longer than ${Math.round(this.timeoutMs / 1000)} s and was stopped.`), { log });
+                if (r !== 0 || !existsSync(join(tmp, "doc.pdf")))
+                    throw Object.assign(new Error(firstError(log) ?? `XeLaTeX failed (exit ${r}).`), { log });
+                if (runs >= MAX_RUNS || !rerun(log))
+                    break;
+            }
+            const at = join(this.cacheDir, job.id);
+            mkdirSync(at, { recursive: true });
+            for (const f of ["doc.pdf", "doc.tex", "visualproof.sty"])
+                writeFileSync(join(at, f), readFileSync(join(tmp, f)));
+            if (figures.length)
+                cpSync(join(tmp, "figures"), join(at, "figures"), { recursive: true });
+            job.state = "done";
+            job.pages = pagesOf(log) ?? undefined;
+            job.runs = runs;
+            job.ms = Date.now() - start;
+            writeFileSync(join(at, "job.json"), JSON.stringify({ at: job.at, pages: job.pages, ms: job.ms, runs, ...(job.notes ? { notes: job.notes } : {}) }));
+            this.prune();
+        }
+        catch (e) {
+            job.state = "failed";
+            job.error = e instanceof Error ? e.message : String(e);
+            const log = e.log;
+            if (log)
+                job.log = log.slice(-LOG_TAIL);
+            job.ms = Date.now() - start;
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+    /** One run of XeLaTeX on doc.tex in `cwd`: its exit code, or "timeout" when it was killed. */
+    xetex(cwd, timeoutMs) {
+        return new Promise((ok) => {
+            if (timeoutMs <= 0)
+                return ok("timeout");
+            const p = spawn(this.xelatex, ["-no-shell-escape", "-halt-on-error", "-interaction=nonstopmode", "doc.tex"], {
+                cwd,
+                // TeX's paranoid file access; and a log whose lines are not wrapped, so that it reads back
+                env: { ...process.env, openin_any: "p", openout_any: "p", shell_escape: "f", max_print_line: "10000" },
+                stdio: ["ignore", "ignore", "ignore"],
+            });
+            let killed = false;
+            const timer = setTimeout(() => {
+                killed = true;
+                p.kill("SIGKILL");
+            }, timeoutMs);
+            p.on("error", () => {
+                clearTimeout(timer);
+                ok(127);
+            });
+            p.on("close", (code) => {
+                clearTimeout(timer);
+                ok(killed ? "timeout" : (code ?? 1));
+            });
+        });
+    }
+    /** Keep the newest `maxCached` documents of the cache; the rest go. */
+    prune() {
+        let entries;
+        try {
+            entries = readdirSync(this.cacheDir).map((d) => ({ dir: join(this.cacheDir, d), t: statSync(join(this.cacheDir, d)).mtimeMs }));
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => b.t - a.t);
+        for (const e of entries.slice(this.maxCached))
+            rmSync(e.dir, { recursive: true, force: true });
+    }
+    /** The zip of a cached document's sources: what anyone needs to typeset it again. */
+    sources(at) {
+        const files = [
+            { name: "doc.tex", data: readFileSync(join(at, "doc.tex")) },
+            { name: "visualproof.sty", data: readFileSync(join(at, "visualproof.sty")) },
+            { name: "README.txt", data: Buffer.from(README, "utf8") },
+        ];
+        const figures = join(at, "figures");
+        if (existsSync(figures))
+            for (const f of readdirSync(figures).sort())
+                files.push({ name: `figures/${f}`, data: readFileSync(join(figures, f)) });
+        for (const f of readdirSync(FONTS_DIR).sort())
+            files.push({ name: `fonts/${f}`, data: readFileSync(join(FONTS_DIR, f)) });
+        return zip(files);
+    }
+}
+const README = `This is a document VisualProof exported, as LaTeX.
+
+Typeset it with XeLaTeX, twice (the second run resolves page references and bookmarks):
+
+    xelatex doc.tex
+    xelatex doc.tex
+
+doc.tex holds the content only, as semantic macros (\\vpPart, \\begin{vpDecl}, \\vpFullName, \\begin{vpCode}, ...).
+How it looks is visualproof.sty's: change it, replace it, or load a package of your own after it
+and \\renewcommand what you want different. Its head lists every macro a document uses.
+
+fonts/ holds JuliaMono (SIL Open Font License, fonts/LICENSE-JuliaMono.txt), the code's font, which
+visualproof.sty loads from there. figures/, where there is one, holds the images and the clips of
+papers the document's notes carry. The text is set in Libertinus (TeX Live), or Latin Modern where
+Libertinus is not installed.
+`;
+/** XeLaTeX's log, as far as there is one. */
+function readLog(dir) {
+    try {
+        return readFileSync(join(dir, "doc.log"), "latin1");
+    }
+    catch {
+        return "";
+    }
+}
+/** Whether the log asks for another run: references or labels not yet resolved. */
+export function rerun(log) {
+    return /Rerun to get|Label\(s\) may have changed|There were undefined references|Rerun LaTeX|rerunfilecheck Warning: File .* has changed/.test(log);
+}
+/** How many pages the log says were written. */
+export function pagesOf(log) {
+    const m = /Output written on .*?\((\d+) pages?/.exec(log.replace(/\n/g, ""));
+    return m ? Number(m[1]) : null;
+}
+/** The first error in a log, in a line: TeX's `! …`. */
+function firstError(log) {
+    const m = /^! (.*)$/m.exec(log);
+    return m ? `XeLaTeX: ${m[1].slice(0, 300)}` : null;
+}
+// ---------------------------------------------------------------- a zip, without a dependency
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+/** CRC-32, as zip files check their entries with. */
+export function crc32(b) {
+    let c = 0xffffffff;
+    for (let i = 0; i < b.length; i++)
+        c = CRC_TABLE[(c ^ b[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** A zip archive of `files`, each deflated, its name in UTF-8; dated now, as DOS times go. */
+export function zip(files) {
+    const d = new Date();
+    const time = (d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1);
+    const date = ((d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate();
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const f of files) {
+        const name = Buffer.from(f.name, "utf8");
+        const packed = deflateRawSync(f.data, { level: 9 });
+        const crc = crc32(f.data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6); // the name is UTF-8
+        local.writeUInt16LE(8, 8); // deflate
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(date, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(packed.length, 18);
+        local.writeUInt32LE(f.data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0x0800, 8);
+        central.writeUInt16LE(8, 10);
+        central.writeUInt16LE(time, 12);
+        central.writeUInt16LE(date, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(packed.length, 20);
+        central.writeUInt32LE(f.data.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        // no extra field, no comment, disk 0, no attributes
+        central.writeUInt32LE(offset, 42);
+        locals.push(local, name, packed);
+        centrals.push(central, name);
+        offset += local.length + name.length + packed.length;
+    }
+    const dir = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(files.length, 8);
+    end.writeUInt16LE(files.length, 10);
+    end.writeUInt32LE(dir.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, dir, end]);
+}

package/dist/server/extract.js

@@ -0,0 +1,204 @@
+// Run the Lean extractor against a project, or reuse its last result when nothing it reads has
+// changed.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+export const EXTRACTOR = join(dirname(fileURLToPath(import.meta.url)), "..", "extractor", "Extract.lean");
+/** The usage pass's worker (server/usage.ts). */
+export const USAGE = join(dirname(fileURLToPath(import.meta.url)), "..", "extractor", "Usage.lean");
+/** Mixed into the fingerprint. Bumped when extractions filed before must not be reused, even under
+ *  the current Extract.lean's fingerprint: a server started before an update of the extractor runs
+ *  the binary it built at start, and files that binary's output under the new source's
+ *  fingerprint. 2: axiom sets reach through theorems' proofs. 3: a declaration Lean generated
+ *  from a command (`gen`) names the declaration that command writes. 4: units — a declaration
+ *  Lean generated from a command folds into the one that command writes (`also`), with its
+ *  references, axioms and hash; instances of classes whose instances are all equal are left out
+ *  of TCBs as proofs are (TCBSpec.md, decisions 1, 3 and 5). 5: meta-level declarations are
+ *  units, and syntax extension commands units of kind `notation` (decision 2). 6: grammar leaves
+ *  the TCB (the grammar site), notation units are named after what they declare or interpret. 7:
+ *  every unit has a name of its own — a declaration two modules list is taken once, local notation
+ *  is qualified with its module's last part, and a name still shared is numbered. 8: each unit's
+ *  shape and references, which versions are made from (server/versions.ts). */
+const EXTRACTION_VERSION = 8;
+/** A fingerprint of everything the extraction depends on: the extractor itself, the toolchain,
+ *  the roots, and every .olean of the project (path, size, mtime). Dependencies are pinned by
+ *  lake-manifest.json, so it stands in for their builds. */
+export function fingerprint(p) {
+    const h = createHash("sha256");
+    h.update(`extraction ${EXTRACTION_VERSION}\0`);
+    h.update(readFileSync(EXTRACTOR));
+    h.update(p.toolchain + "\0" + p.roots.join(",") + "\0");
+    const manifest = join(p.root, "lake-manifest.json");
+    if (existsSync(manifest))
+        h.update(readFileSync(manifest));
+    const walk = (dir) => {
+        const ents = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1));
+        for (const ent of ents) {
+            const f = join(dir, ent.name);
+            if (ent.isDirectory())
+                walk(f);
+            else if (ent.name.endsWith(".olean")) {
+                const st = statSync(f);
+                h.update(`${relative(p.libDir, f)}\0${st.size}\0${st.mtimeMs}\n`);
+            }
+        }
+    };
+    walk(p.libDir);
+    return h.digest("hex").slice(0, 16);
+}
+export const EXTRACT_PROGRAM = { dir: "extractor", source: EXTRACTOR, exe: "vp-extract", root: "Extract" };
+export const USAGE_PROGRAM = { dir: "usage", source: USAGE, exe: "vp-usage", root: "Usage" };
+const built = new Map();
+export function leanProgram(prog, toolchain, leanRoot, log) {
+    const source = readFileSync(prog.source);
+    const hash = createHash("sha256").update(source).digest("hex").slice(0, 12);
+    const key = [prog.exe, toolchain, hash, leanRoot].join("\0");
+    let p = built.get(key);
+    if (p)
+        return p;
+    p = new Promise((resolveP) => {
+        const parent = join(leanRoot, prog.dir, toolchain.replace(/[^A-Za-z0-9.]+/g, "-"));
+        const dir = join(parent, hash);
+        const bin = join(dir, ".lake", "build", "bin", prog.exe);
+        if (existsSync(bin))
+            return resolveP(bin);
+        mkdirSync(parent, { recursive: true });
+        const work = mkdtempSync(join(parent, `${hash}.tmp-`));
+        writeFileSync(join(work, `${prog.root}.lean`), source);
+        writeFileSync(join(work, "lean-toolchain"), toolchain + "\n");
+        writeFileSync(join(work, "lakefile.toml"), `name = "${prog.exe.replace(/-/g, "")}"\n\n[[lean_exe]]\nname = "${prog.exe}"\nroot = "${prog.root}"\nsupportInterpreter = true\n`);
+        log(`building ${prog.exe} for ${toolchain}…`);
+        const child = spawn("lake", ["build", prog.exe], { cwd: work, stdio: ["ignore", "pipe", "pipe"] });
+        let tail = "";
+        child.stdout.on("data", (b) => (tail = (tail + b).slice(-2000)));
+        child.stderr.on("data", (b) => (tail = (tail + b).slice(-2000)));
+        let finished = false;
+        const done = (ok) => {
+            // a child that failed to start may report both `error` and `close`
+            if (finished)
+                return;
+            finished = true;
+            if (ok) {
+                try {
+                    renameSync(work, dir);
+                }
+                catch {
+                    // another server moved its build of the same source into place first
+                }
+            }
+            else
+                log(`could not build ${prog.exe}:\n${tail}`);
+            rmSync(work, { recursive: true, force: true });
+            resolveP(existsSync(bin) ? bin : null);
+        };
+        child.on("error", () => done(false));
+        child.on("close", (code) => done(code === 0 && existsSync(join(work, ".lake", "build", "bin", prog.exe))));
+    });
+    built.set(key, p);
+    return p;
+}
+/** The extractor, compiled (`leanProgram`); null when it could not be, and it is interpreted. */
+export function extractorBinary(toolchain, leanRoot, log) {
+    return leanProgram(EXTRACT_PROGRAM, toolchain, leanRoot, log);
+}
+/** `lake env` puts the project's own toolchain and package paths in place, so the extractor
+ *  always matches the .olean format it reads. */
+function runExtractor(p, out, opts, log) {
+    return new Promise((resolveP, reject) => {
+        const tail_ = ["--cache", opts.cache, "--salt", opts.salt];
+        const args = opts.bin
+            ? ["env", opts.bin, out, p.libDir, ...p.roots, ...tail_]
+            : ["env", "lean", "--run", EXTRACTOR, out, p.libDir, ...p.roots, ...tail_];
+        const child = spawn("lake", args, { cwd: p.root, stdio: ["ignore", "pipe", "pipe"] });
+        let tail = "";
+        const onData = (buf) => {
+            const text = buf.toString();
+            tail = (tail + text).slice(-4000);
+            for (const line of text.split("\n"))
+                if (line.trim())
+                    log(line);
+        };
+        child.stdout.on("data", onData);
+        child.stderr.on("data", onData);
+        child.on("error", (e) => reject(new Error(`could not start lake: ${e.message}`)));
+        child.on("close", (code) => {
+            if (code === 0)
+                return resolveP();
+            const missing = tail.match(/object file '[^']*' of module (\S+) does not exist/);
+            if (missing) {
+                return reject(new Error(`the build is incomplete: ${missing[1]} has no .olean. A \`lake build\` is running or ` +
+                    "failed; VisualProof reads only what a finished build left behind. Retry when it is done."));
+            }
+            // modules a project never imports together (two versions of one file, a library of reference
+            // statements beside its proofs): Lean cannot import them into one environment
+            const clash = tail.match(/import (\S+) failed, environment already contains '([^']+)' from (\S+)/);
+            if (clash) {
+                return reject(new Error(`${clash[1]} and ${clash[3]} cannot be read together: both declare ${clash[2]}. Read fewer: ` +
+                    "`--root` names the libraries or modules to read (repeatable)."));
+            }
+            reject(new Error(`extractor exited with ${code}:\n${tail}`));
+        });
+    });
+}
+/** Keep the newest `keep` files of a cache directory that match `pattern`; a live session
+ *  writes one extraction per build and would otherwise fill the disk. */
+export function prune(dir, pattern, keep) {
+    try {
+        const files = readdirSync(dir)
+            .filter((f) => pattern.test(f))
+            .map((f) => ({ f, t: statSync(join(dir, f)).mtimeMs }))
+            .sort((a, b) => b.t - a.t);
+        for (const { f } of files.slice(keep))
+            unlinkSync(join(dir, f));
+    }
+    catch {
+        // pruning is housekeeping; never a reason to fail
+    }
+}
+/** A saved extraction, served as it is: for a snapshot of a project that is not on this
+ *  machine, or not built right now. */
+export function loadSaved(file) {
+    const text = readFileSync(file, "utf8");
+    return {
+        graph: JSON.parse(text),
+        fingerprint: createHash("sha256").update(text).digest("hex").slice(0, 16),
+        at: statSync(file).mtime.toISOString(),
+        cached: true,
+    };
+}
+/** An extraction the project's cache already holds, by fingerprint. */
+export function cachedExtraction(cacheDir, fp) {
+    const file = join(cacheDir, "extract", `${fp}.json`);
+    if (!existsSync(file))
+        return null;
+    return { graph: JSON.parse(readFileSync(file, "utf8")), fingerprint: fp, at: statSync(file).mtime.toISOString(), cached: true };
+}
+export async function extract(p, dirs, log) {
+    const fp = fingerprint(p);
+    const dir = join(dirs.cache, "extract");
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${fp}.json`);
+    if (existsSync(file)) {
+        return {
+            graph: JSON.parse(readFileSync(file, "utf8")),
+            fingerprint: fp,
+            at: statSync(file).mtime.toISOString(),
+            cached: true,
+        };
+    }
+    const tmp = `${file}.tmp`;
+    const bin = await extractorBinary(p.toolchain, dirs.lean, log);
+    // the per-module cache is only valid for one extractor, toolchain and set of dependencies
+    const salt = createHash("sha256")
+        .update(readFileSync(EXTRACTOR))
+        .update(p.toolchain)
+        .update(existsSync(join(p.root, "lake-manifest.json")) ? readFileSync(join(p.root, "lake-manifest.json")) : "")
+        .digest("hex")
+        .slice(0, 16);
+    await runExtractor(p, tmp, { bin, cache: join(dirs.cache, "modules"), salt }, log);
+    renameSync(tmp, file);
+    prune(dir, /^[0-9a-f]{16}\.json$/, 3);
+    return { graph: JSON.parse(readFileSync(file, "utf8")), fingerprint: fp, at: new Date().toISOString(), cached: false };
+}