visualproof 0.0.0-stage → 0.1.0

package/dist/server/doctor.js

@@ -0,0 +1,186 @@
+// `visualproof doctor [<lean-project>]`: what this machine, and a project, need for VisualProof to
+// run, each checked, with what to do where it falls short. It changes nothing: it runs no Lake (in a
+// project's folder that would install its toolchain, and Lake may build), and makes no folder.
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { projectDirs, siteHolder } from "./dirs.js";
+import { ProjectError, openProject, targetsInWords } from "./project.js";
+export const run = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "pipe"] });
+    return r.error || r.status !== 0 ? null : `${r.stdout}${r.stderr}`;
+};
+/** The package's own file, read where both a checkout and the installed package have it. */
+function packageFile(rel) {
+    return join(import.meta.dirname, "..", "..", rel);
+}
+export function packageVersion() {
+    return JSON.parse(readFileSync(packageFile("package.json"), "utf8")).version;
+}
+function parseVersion(v) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(v);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function cmp(a, b) {
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    return 0;
+}
+/** Whether a version meets a range of the forms package.json's `engines` uses: alternatives
+ *  joined by `||`, each of `^x.y.z`, `>=x.y.z`, `<x.y.z`, joined by spaces. */
+export function satisfies(version, range) {
+    const v = parseVersion(version);
+    if (!v)
+        return false;
+    return range.split("||").some((alt) => alt.trim().split(/\s+/).every((part) => {
+        const m = /^(\^|>=|<|)(\d+\.\d+\.\d+)$/.exec(part);
+        if (!m)
+            return false;
+        const w = parseVersion(m[2]);
+        if (m[1] === "^")
+            return v[0] === w[0] && cmp(v, w) >= 0;
+        if (m[1] === ">=")
+            return cmp(v, w) >= 0;
+        if (m[1] === "<")
+            return cmp(v, w) < 0;
+        return cmp(v, w) === 0;
+    }));
+}
+/** A toolchain as elan names it: `leanprover/lean4:v4.33.1`, whether the project writes it so, or
+ *  as a bare version, or elan lists it as its folder's name (`leanprover--lean4---v4.33.1`). */
+export function toolchainName(t) {
+    const s = t.trim().replace(/\s+\(.*\)$/, "");
+    if (/^[\w.-]+--[\w.-]+---/.test(s))
+        return s.replace("---", ":").replace("--", "/");
+    return s.includes(":") ? s : `leanprover/lean4:${s.startsWith("v") ? s : `v${s}`}`;
+}
+/** The Lean versions supported (test/toolchains.json): the oldest, and the newest tested. */
+export function supportedToolchains() {
+    const t = JSON.parse(readFileSync(packageFile("test/toolchains.json"), "utf8"));
+    const newest = [...t.toolchains].sort((a, b) => cmp(parseVersion(a), parseVersion(b))).at(-1);
+    return { floor: t.floor, newest };
+}
+/** Where a toolchain stands: before the oldest supported, within what is tested, or after it. A
+ *  release candidate counts as its release. */
+export function toolchainSupport(toolchain, s = supportedToolchains()) {
+    const name = toolchainName(toolchain);
+    if (!name.startsWith("leanprover/lean4:"))
+        return "other";
+    const v = parseVersion(name);
+    if (!v)
+        return "other";
+    if (cmp(v, parseVersion(s.floor)) < 0)
+        return "old";
+    return cmp(v, parseVersion(s.newest)) > 0 ? "new" : "tested";
+}
+/** Whether a folder could be made and written here: it, or the nearest folder above it that is. */
+function writable(dir) {
+    let d = resolve(dir);
+    while (!existsSync(d) && dirname(d) !== d)
+        d = dirname(d);
+    try {
+        accessSync(d, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function install(what, platform) {
+    if (what === "poppler")
+        return platform === "darwin" ? "brew install poppler" : "install poppler-utils (Debian, Ubuntu: sudo apt install poppler-utils)";
+    return platform === "darwin" ? "install MacTeX, or brew install --cask mactex-no-gui" : "install TeX Live's XeLaTeX (Debian, Ubuntu: sudo apt install texlive-xetex texlive-latex-extra)";
+}
+export function doctor(o) {
+    const exec = o.run ?? run;
+    const node = o.node ?? process.versions.node;
+    const platform = o.platform ?? process.platform;
+    const checks = [];
+    const engines = JSON.parse(readFileSync(packageFile("package.json"), "utf8")).engines?.node ?? "";
+    checks.push(satisfies(node, engines)
+        ? { level: "ok", what: `Node ${node}` }
+        : { level: "fail", what: `Node ${node}: VisualProof needs ${engines.replace(/\s*\|\|\s*/g, " or ")}`, fix: "install a newer Node (https://nodejs.org), the current LTS" });
+    const elan = exec("elan", ["--version"]);
+    const installed = new Set((elan ? (exec("elan", ["toolchain", "list"]) ?? "") : "")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l && !/^no installed toolchains/i.test(l))
+        .map(toolchainName));
+    checks.push(elan
+        ? { level: "ok", what: `${elan.trim().split("\n")[0].replace(/\s+\(.*\)$/, "")}, ${installed.size} toolchain(s) installed` }
+        : { level: "fail", what: "elan not found: it runs each project's Lean and Lake", fix: "install elan: https://github.com/leanprover/elan" });
+    const poppler = ["pdfinfo", "pdftotext", "pdftoppm"].filter((p) => exec(p, ["-v"]) === null);
+    checks.push(poppler.length === 0
+        ? { level: "ok", what: `Poppler ${/version\s+([\d.]+)/.exec(exec("pdfinfo", ["-v"]) ?? "")?.[1] ?? ""}`.trimEnd() }
+        : { level: "warn", what: `Poppler: ${poppler.join(", ")} not found: the library cannot read PDFs`, fix: install("poppler", platform) });
+    const xelatex = exec("xelatex", ["--version"]);
+    checks.push(xelatex
+        ? { level: "ok", what: `XeLaTeX (${/TeX Live \d+|MiKTeX[^\s)]*/.exec(xelatex)?.[0] ?? "found"})` }
+        : { level: "info", what: "XeLaTeX not found: needed only for the printed document (Export)", fix: install("xelatex", platform) });
+    if (exec("git", ["--version"]) === null) {
+        checks.push({ level: "info", what: "git not found: builds are kept without their commit, and past sources only as the builds kept them" });
+    }
+    if (o.path === null)
+        return { checks, ready: null };
+    let project;
+    try {
+        project = openProject(o.path, o.roots, false);
+    }
+    catch (e) {
+        if (!(e instanceof ProjectError))
+            throw e;
+        checks.push({ level: "fail", what: e.message });
+        return { checks, ready: null };
+    }
+    const { root, toolchain, roots, libDir } = project;
+    const name = toolchainName(toolchain);
+    const support = toolchainSupport(name);
+    const range = supportedToolchains();
+    checks.push(support === "tested"
+        ? { level: "ok", what: `${name}: supported (${range.floor} to ${range.newest} are tested)` }
+        : support === "old"
+            ? { level: "fail", what: `${name}: older than ${range.floor}, the oldest Lean VisualProof reads`, fix: "update the project's toolchain, or use it with a Lean VisualProof supports" }
+            : support === "new"
+                ? { level: "warn", what: `${name}: newer than ${range.newest}, the newest tested; it probably works`, fix: "if the graph cannot be read, report it: https://github.com/LucianoXu/VisualProof/issues" }
+                : { level: "warn", what: `${name}: not a release of leanprover/lean4; VisualProof is tested on releases` });
+    if (elan && !installed.has(name)) {
+        checks.push({ level: "warn", what: `${name} is not installed: elan downloads it when VisualProof first runs Lake here`, fix: `elan toolchain install ${name}` });
+    }
+    const from = o.roots.length ? "--root" : existsSync(join(root, "lakefile.toml")) ? "lakefile.toml" : "lakefile.lean";
+    const missing = roots.filter((r) => !existsSync(join(libDir, ...r.split(".")) + ".olean"));
+    const mathlib = ["lakefile.toml", "lakefile.lean", "lake-manifest.json"].some((f) => existsSync(join(root, f)) && /mathlib/i.test(readFileSync(join(root, f), "utf8")));
+    checks.push(missing.length === 0
+        ? { level: "ok", what: `built: ${targetsInWords(project)} (from ${from})` }
+        : {
+            level: "fail",
+            what: `not built: ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ` and ${missing.length - 5} more` : ""} (${relative(root, join(libDir, ...missing[0].split("."))) + ".olean"} is missing; from ${from})`,
+            fix: `in ${root}: ${mathlib ? "lake exe cache get && " : ""}lake build${o.roots.length === 0 && from === "lakefile.lean" ? ", or name the modules to read with --root" : ""}`,
+        });
+    const dirs = projectDirs(root, o.site, o.cache);
+    for (const [what, dir] of [["site", dirs.site], ["cache", dirs.cache]]) {
+        if (!writable(dir))
+            checks.push({ level: "fail", what: `the ${what} ${dir} cannot be written`, fix: `give --${what} a folder of your own` });
+    }
+    const holder = siteHolder(dirs.site);
+    checks.push(holder === null
+        ? { level: "ok", what: `site ${dirs.site}` }
+        : { level: "info", what: `site ${dirs.site}: a server (process ${holder}) is serving it; another needs a --site of its own` });
+    const failed = checks.some((c) => c.level === "fail");
+    const args = [o.path, ...o.roots.flatMap((r) => ["--root", r]), ...(o.site ? ["--site", o.site] : []), ...(o.cache ? ["--cache", o.cache] : [])];
+    return { checks, ready: failed ? null : `visualproof serve ${args.map((a) => (/^[\w./:@%+=-]+$/.test(a) ? a : JSON.stringify(a))).join(" ")}` };
+}
+const MARK = { ok: "✓", fail: "✗", warn: "!", info: "·" };
+export function printReport(r, project) {
+    const lines = [`VisualProof ${packageVersion()}`];
+    for (const c of r.checks) {
+        lines.push(`  ${MARK[c.level]} ${c.what}`);
+        if (c.fix && c.level !== "ok")
+            lines.push(`      ${c.fix}`);
+    }
+    if (r.ready)
+        lines.push("", `Ready: ${r.ready}`);
+    else if (project === null && !r.checks.some((c) => c.level === "fail"))
+        lines.push("", "To check a project too: visualproof doctor <lean-project>");
+    return lines.join("\n");
+}

package/dist/server/events.js

@@ -0,0 +1,198 @@
+// The timeline (CollabSpec decision 5), as the server keeps it: one event per line in
+// `<site>/events.jsonl`, the last 90 days and at most 5,000 events. It notices what nobody records
+// by hand — a build that finished, files that failed or were fixed, `sorry` that came or went, and a
+// target's TCB that changed (with the opinions that went stale by it) — and is told of re-layouts,
+// of targets taken off and of prefixes trusted or no longer trusted (the review's state keeps the
+// trusted list, not who changed it), and of what agents do beside their advice: notes, layout
+// batches and their undoing (server/agent.ts), and of views saved, renamed, deleted and laid out
+// afresh (server/views.ts). Opinions, targets and key marks are in the review's logs
+// (server/review.ts); the page reads them from there.
+//
+// A target's TCB is compared with the one it had at the last graph, kept in
+// `<site>/tcb-baselines.json`, so a change made while the server was down is noticed when it
+// comes back.
+import { appendFileSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { byName, current } from "../shared/review.js";
+import { NAMES_LISTED, TcbIndex, tcbDiff } from "../shared/timeline.js";
+const KEEP = 5000;
+const KEEP_MS = 90 * 24 * 3600 * 1000;
+export class Timeline {
+    file;
+    baselineFile;
+    events = [];
+    send;
+    /** each file's state when no build was running, last time */
+    settled = null;
+    /** the graph on show, for TCBs */
+    index = null;
+    /** each target's TCB at the last graph; keyed by names, so without prototypes */
+    baselines = byName();
+    constructor(siteDir, send) {
+        this.send = send;
+        this.file = join(siteDir, "events.jsonl");
+        this.baselineFile = join(siteDir, "tcb-baselines.json");
+        if (existsSync(this.file)) {
+            const lines = readFileSync(this.file, "utf8").split("\n");
+            for (const l of lines) {
+                if (!l.trim())
+                    continue;
+                try {
+                    this.events.push(JSON.parse(l));
+                }
+                catch {
+                    // a line cut short (the server stopped while writing): left out
+                }
+            }
+            const kept = this.pruned();
+            if (kept.length !== this.events.length) {
+                this.events = kept;
+                this.rewrite();
+            }
+        }
+        try {
+            const raw = JSON.parse(readFileSync(this.baselineFile, "utf8"));
+            for (const [target, tcb] of Object.entries(raw && typeof raw === "object" ? raw : {})) {
+                if (!tcb || typeof tcb !== "object")
+                    continue;
+                const m = byName();
+                for (const [k, v] of Object.entries(tcb))
+                    if (typeof v === "string")
+                        m[k] = v;
+                this.baselines[target] = m;
+            }
+        }
+        catch {
+            // none yet, or unreadable: every target starts again from the TCB it has now
+        }
+    }
+    pruned() {
+        const after = Date.now() - KEEP_MS;
+        return this.events.filter((e) => Date.parse(e.at) >= after).slice(-KEEP);
+    }
+    rewrite() {
+        const tmp = `${this.file}.tmp-${process.pid}`;
+        writeFileSync(tmp, this.events.map((e) => JSON.stringify(e) + "\n").join(""));
+        renameSync(tmp, this.file);
+    }
+    /** Record an event, and tell every page. */
+    add(e) {
+        const full = { ...e, id: (this.events[this.events.length - 1]?.id ?? 0) + 1, at: new Date().toISOString() };
+        this.events.push(full);
+        appendFileSync(this.file, JSON.stringify(full) + "\n");
+        if (this.events.length > KEEP + 500) {
+            this.events = this.pruned();
+            this.rewrite();
+        }
+        this.send(full);
+        return full;
+    }
+    /** The build status, every time it changes: once no build runs, what changed since the last
+     *  quiet moment is one event. The first status after a start is where the comparison begins. */
+    buildStatus(b) {
+        if (b.active)
+            return;
+        const now = new Map(b.files.map((f) => [f.module, f]));
+        const was = this.settled;
+        this.settled = now;
+        if (!was)
+            return;
+        const failed = [], fixed = [], sorry = [], sorryGone = [];
+        let rebuilt = 0;
+        for (const [m, f] of now) {
+            const p = was.get(m);
+            if (f.builtAt && p?.builtAt !== f.builtAt)
+                rebuilt++;
+            if (f.state === "failed" && p?.state !== "failed")
+                failed.push(m);
+            if (p?.state === "failed" && (f.state === "ok" || f.state === "sorry"))
+                fixed.push(m);
+            if (f.state === "sorry" && p?.state !== "sorry")
+                sorry.push(m);
+            if (p?.state === "sorry" && f.state === "ok")
+                sorryGone.push(m);
+        }
+        if (failed.length || fixed.length || sorry.length || sorryGone.length || rebuilt)
+            this.add({ kind: "build", failed: failed.sort(), fixed: fixed.sort(), sorry: sorry.sort(), sorryGone: sorryGone.sort(), rebuilt });
+    }
+    /** A new graph: every target's TCB is compared with the one it had, and a change is an event.
+     *  `renamed`: the renames found against the build before (HistorySpec.md), old name → new: a
+     *  declaration renamed is the same one, neither removed nor added, and a target renamed keeps its
+     *  baseline. */
+    graphChanged(prep, review, renamed = new Map()) {
+        const meta = JSON.parse(gunzipSync(prep.metaGz).toString("utf8"));
+        const raw = gunzipSync(prep.edgesGz);
+        const edges = new Int32Array(new Uint8Array(raw).buffer);
+        this.index = new TcbIndex(meta.nodes, edges);
+        // a baseline kept before versions holds the kernel's hashes (server/versions.ts): one that is
+        // the kernel's hash of the content there now is that content's version
+        const kernel = new Map();
+        for (const v of meta.nodes)
+            if (v.kernel && v.hash)
+                kernel.set(v.name, v.kernel);
+        if (renamed.size) {
+            for (const t of Object.keys(this.baselines)) {
+                const b = this.baselines[t];
+                const now = byName();
+                for (const k of Object.keys(b))
+                    now[renamed.get(k) ?? k] = b[k];
+                delete this.baselines[t];
+                this.baselines[renamed.get(t) ?? t] = now;
+            }
+        }
+        for (const target of Object.keys(review.targets)) {
+            const root = this.index.byName.get(target);
+            if (root === undefined)
+                continue;
+            const now = this.index.tcb(root);
+            const before = Object.hasOwn(this.baselines, target) ? this.baselines[target] : null;
+            if (before)
+                for (const k of Object.keys(before))
+                    if (Object.hasOwn(now, k) && kernel.get(k) === before[k])
+                        before[k] = now[k];
+            this.baselines[target] = now;
+            if (!before)
+                continue;
+            const d = tcbDiff(before, now);
+            if (!d.added.length && !d.removed.length && !d.changed.length)
+                continue;
+            // opinions given on the version before, for what changed: stale now
+            let stale = 0;
+            for (const name of d.changed)
+                stale += current(review, name).filter((o) => o.hash && o.hash === before[name]).length;
+            this.add({
+                kind: "tcb",
+                target,
+                added: d.added.slice(0, NAMES_LISTED),
+                removed: d.removed.slice(0, NAMES_LISTED),
+                changed: d.changed.slice(0, NAMES_LISTED),
+                counts: { added: d.added.length, removed: d.removed.length, changed: d.changed.length },
+                stale,
+            });
+        }
+        this.saveBaselines();
+    }
+    /** The review changed: a new target starts from the TCB it has now. */
+    reviewChanged(review) {
+        if (!this.index)
+            return;
+        let added = false;
+        for (const target of Object.keys(review.targets)) {
+            if (Object.hasOwn(this.baselines, target))
+                continue;
+            const root = this.index.byName.get(target);
+            if (root === undefined)
+                continue;
+            this.baselines[target] = this.index.tcb(root);
+            added = true;
+        }
+        if (added)
+            this.saveBaselines();
+    }
+    saveBaselines() {
+        const tmp = `${this.baselineFile}.tmp-${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(this.baselines));
+        renameSync(tmp, this.baselineFile);
+    }
+}