visualproof 0.0.0-stage → 0.1.0

package/dist/shared/editor.js

@@ -0,0 +1,64 @@
+// "Open in editor": a link from a declaration to its place in an editor, made from a URL template.
+// The server can be started with one (`--editor`), and a reader can set their own in the page (the
+// ? sheet), because what opens an editor depends on the machine the page is read on: VS Code on the
+// server itself (`vscode://file/{path}:{line}:{col}`), VS Code on a laptop reaching the server over
+// SSH (`vscode://vscode-remote/ssh-remote+HOST{path}:{line}`), or a web view of the repository
+// (`https://github.com/…/blob/main/{rel}#L{line}`).
+//
+// Placeholders: {path} is the file's absolute path on the server, {rel} its path in the project,
+// {line} and {col} where the declaration starts, both counted from 1. The paths are percent-encoded
+// where a URL needs it; the rest of the template is the owner's, and is left as written.
+export const PLACEHOLDERS = ["path", "rel", "line", "col"];
+/** Schemes that do something inside the page rather than open something outside it: a template
+ *  with one would run whatever it says the moment a reader clicks the link. */
+const REFUSED = new Set(["javascript", "data", "vbscript", "blob", "about"]);
+/** A place to try a template on, so that one which cannot make a URL is refused before anyone
+ *  clicks it. */
+const SAMPLE = { path: "/home/a b/Project/A#1.lean", rel: "A#1.lean", line: 12, col: 3 };
+/** Why `t` cannot be used as a template, or null when it can. */
+export function invalidTemplate(t) {
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(t);
+    if (!scheme)
+        return "Not a URL: it has to start with a scheme, like vscode:// or https://.";
+    if (REFUSED.has(scheme[1].toLowerCase()))
+        return `A ${scheme[1]}: link runs inside the page; it cannot open an editor.`;
+    if (/[\s\x00-\x1f\x7f]/.test(t))
+        return "A URL has no spaces in it; write a space as %20.";
+    for (const [, name] of t.matchAll(/\{([^{}]*)\}/g))
+        if (!PLACEHOLDERS.includes(name))
+            return `There is no {${name}}: the placeholders are {path}, {rel}, {line} and {col}.`;
+    if (!/\{(?:path|rel)\}/.test(t))
+        return "It names no file: put {path} (the file on the server) or {rel} (the file in the project) in it.";
+    if (expand(t, SAMPLE) === null)
+        return "This does not make a URL once the placeholders are filled in.";
+    return null;
+}
+/** A path as it may stand in a URL: percent-encoded, except for the slashes and the characters a
+ *  path may hold as they are. `?` and `#` would end the path, so they are encoded too. */
+function encodePath(p) {
+    return encodeURI(p).replace(/[?#]/g, (c) => encodeURIComponent(c));
+}
+function expand(t, p) {
+    try {
+        const out = t.replace(/\{(path|rel|line|col)\}/g, (_, name, at) => {
+            if (name === "line" || name === "col")
+                return String(Math.max(1, Math.trunc(name === "line" ? p.line : p.col) || 1));
+            const s = encodePath(name === "path" ? p.path : p.rel);
+            // `vscode://file/{path}` with an absolute path: one slash, not two, since `file//data/…`
+            // would name a host "data". A double slash (`file://{path}`) is the URL's own and stays.
+            if (name === "path" && s.startsWith("/") && t[at - 1] === "/" && t[at - 2] !== "/")
+                return s.slice(1);
+            return s;
+        });
+        new URL(out);
+        return out;
+    }
+    catch {
+        // a path with half a character in it (encodeURI throws), or no URL at all
+        return null;
+    }
+}
+/** The link to `place` that template `t` makes; null when the template cannot be used. */
+export function editorLink(t, place) {
+    return invalidTemplate(t) ? null : expand(t, place);
+}

package/dist/shared/excerpt.js

@@ -0,0 +1,87 @@
+// Which lines of a file are a declaration's source. When the file is the one the graph was read
+// from, its compiled place says so exactly (with the docstring and attributes above it). When the
+// file changed since, that place means nothing any more: the declaration is looked for by name in
+// the present text, and the reader is told it is not what was compiled.
+const DECL = /^\s*(?:@\[[^\]]*\]\s*)*(?:(?:private|protected|noncomputable|partial|unsafe|nonrec|scoped|local)\s+)*(?:theorem|lemma|def|abbrev|instance|structure|class|inductive|axiom|opaque|example|irreducible_def)\s+(\S+)/;
+/** a line that starts what comes after a declaration */
+const NEXT = /^(?:@\[|\/--|\/-!|--|#|(?:(?:private|protected|noncomputable|partial|unsafe|nonrec|scoped|local)\s+)*(?:theorem|lemma|def|abbrev|instance|structure|class|inductive|axiom|opaque|example|irreducible_def|namespace|section|end|open|variable|universe|attribute|set_option|mutual|macro|syntax|notation|infix|infixl|infixr|prefix|postfix|elab|deriving)\b)/;
+/** Pull what belongs to the declaration from directly above `line`: attribute lines, line
+ *  comments, and a whole docstring — never across a blank line, and never a line that has more on it
+ *  than attributes (`@[simp] theorem id_apply … := rfl` is the declaration before, not part of this
+ *  one; a blank line and that once let declarations show their neighbour's text, and record it as
+ *  what a reviewer judged). Lean's own range starts at the docstring already. */
+function withPreamble(lines, line) {
+    let start = line;
+    while (start > 0 && line - start < 40) {
+        const above = lines[start - 1];
+        if (/^\s*@\[[^\]]*\]\s*$/.test(above) || /^\s*--/.test(above)) {
+            start--;
+            continue;
+        }
+        // a docstring that ends right above: the whole of it, from its `/--`
+        if (/-\/\s*$/.test(above)) {
+            let k = start - 1;
+            while (k > 0 && line - k < 60 && !/^\s*\/-/.test(lines[k]))
+                k--;
+            if (/^\s*\/--/.test(lines[k])) {
+                start = k;
+                continue;
+            }
+        }
+        break;
+    }
+    return start;
+}
+/** The excerpt at the compiled place `range` = [line, column, endLine], 1-based lines. */
+export function compiledExcerpt(lines, range) {
+    const l0 = Math.max(0, range[0] - 1);
+    const l1 = Math.min(lines.length - 1, Math.max(l0, range[2] - 1));
+    return { start: withPreamble(lines, l0), end: l1 };
+}
+/** Where declaration `name` is in its file's `lines`: at its compiled place `range` when the file
+ *  is the text that was compiled, else found by name; null when it is not there any more. */
+export function excerptOf(lines, edited, name, range) {
+    return edited ? findExcerpt(lines, name, range[0]) : compiledExcerpt(lines, range);
+}
+/** A declaration's text in its file, as the source window shows it (with its context above it,
+ *  shared/context.ts, it is what an opinion records). `edited`: the file is not the text that
+ *  was compiled. */
+export function declarationText(lines, edited, name, range) {
+    const at = excerptOf(lines, edited, name, range);
+    return at && { text: lines.slice(at.start, at.end + 1).join("\n"), edited };
+}
+/** The declaration `name` looked for in `lines`, nearest `near` (a 1-based line) when several
+ *  match; null when it is not there. */
+export function findExcerpt(lines, name, near) {
+    const parts = name.split(".");
+    const short = parts[parts.length - 1].replace(/^«|»$/g, "");
+    const tail2 = parts.slice(-2).join(".");
+    let best = -1;
+    let bestScore = Infinity;
+    for (let i = 0; i < lines.length; i++) {
+        const m = DECL.exec(lines[i]);
+        if (!m)
+            continue;
+        const declared = m[1].replace(/[«»]/g, "");
+        // declared as `short` inside its namespace, or with part of its namespace in front
+        if (declared !== short && declared !== tail2.replace(/[«»]/g, "") && declared !== name && !name.endsWith("." + declared))
+            continue;
+        const score = near ? Math.abs(i + 1 - near) : i;
+        if (score < bestScore) {
+            bestScore = score;
+            best = i;
+        }
+    }
+    if (best < 0)
+        return null;
+    let end = best;
+    for (let i = best + 1; i < lines.length && i < best + 400; i++) {
+        if (NEXT.test(lines[i]))
+            break;
+        end = i;
+    }
+    // trailing blank lines are not the declaration
+    while (end > best && !lines[end].trim())
+        end--;
+    return { start: withPreamble(lines, best), end };
+}

package/dist/shared/graph.js

@@ -0,0 +1,16 @@
+// The data that crosses process boundaries: what the Lean extractor writes, and what the
+// server hands the page. Kept free of runtime code so both sides can import it.
+/** Edge sites, as bits. A reference "in a proof" sits in a subterm whose type is a Prop. A
+ *  reference "on grammar" is a statement or a body written with a syntax that only fixes the
+ *  grammar (a notation unit flagged `grammar`: `syntax`, `declare_syntax_cat`), or a rule's
+ *  dependency on the syntax it interprets: what the tree means is a rule's business, which a use
+ *  reaches on its own, so a TCB follows neither proofs nor grammar (TCBSpec.md, decision 2). */
+export const SITE_STMT = 1;
+export const SITE_BODY = 2;
+export const SITE_PROOF = 4;
+export const SITE_GRAMMAR = 8;
+/** The sites a TCB follows. */
+export const SITE_TCB = SITE_STMT | SITE_BODY;
+/** Which way of laying out produced a layout. Places remembered under another version (the
+ *  server's layout memory, places dropped in a browser) do not carry over. 2: dependency order. */
+export const LAYOUT_VERSION = 2;

package/dist/shared/items.js

@@ -0,0 +1,92 @@
+// A view's items (the owner's decision of 2026-10-11, AttachmentSpec decision 17): items belong to
+// views as declarations do. An item is a note of the project — among them the notes that carry the
+// library's files — and the Project holds every one. Any other view shows an item where it follows
+// from the view's scope (shared/noteplace.ts, `derivedWhy`: the declaration it is attached to on the
+// board — a reader's visitor counts, and a board of a past build reads it by that build's name (the
+// owner's decision of 2026-10-12) —, its cluster on the board, its cluster under the other clustering
+// on the board for a note on the ring, or a file it carries linked to what the board holds), or where
+// it was added to the view, unless it was taken out of it.
+//
+// What was added and what was taken out are two lists the view keeps beside its scope, never in
+// the scope's text (ViewSpec decision 25: titles stay short): `items: {add, remove}` in its record.
+// They are changed by a view operation, `item`, that puts a note in one list or in neither, shared
+// live as pins are and recorded by the timeline as a scope change is. The page and the agents' API
+// decide which list from what the scope gives (`itemOp`), as the canvas's menu writes a scope that
+// stays short: adding back what was taken out only takes it off the list that took it out, where
+// the scope gives it already, and taking out what was added only takes it off the list that added
+// it, where the scope does not give it. A note deleted, or made a view's own, leaves every list.
+import { MAX_PROJECT_NOTES } from "./projectnotes.js";
+import { validNoteId } from "./sticky.js";
+/** the most notes a list holds: every note of the project */
+export const MAX_ITEMS = MAX_PROJECT_NOTES;
+/** Which of view `items`'s lists holds note `id`, or null. */
+export function itemIn(items, id) {
+    if (!items)
+        return null;
+    return items.add.includes(id) ? "add" : items.remove.includes(id) ? "remove" : null;
+}
+/** Why an item operation cannot be taken, or null. */
+export function invalidItemOp(o) {
+    if (!validNoteId(o.note))
+        return "note";
+    return o.in === null || o.in === "add" || o.in === "remove" ? null : "in";
+}
+/** Apply an item operation to a view's record in place; true when anything changed. A list that
+ *  is full takes no more, and a record whose lists are both empty keeps none. */
+export function applyItemOp(v, o) {
+    const was = itemIn(v.items, o.note);
+    if (was === o.in)
+        return false;
+    const items = v.items ?? { add: [], remove: [] };
+    if (o.in && items[o.in].length >= MAX_ITEMS)
+        return false;
+    if (was)
+        items[was] = items[was].filter((id) => id !== o.note);
+    if (o.in)
+        items[o.in].push(o.note);
+    if (items.add.length || items.remove.length)
+        v.items = items;
+    else
+        delete v.items;
+    return true;
+}
+/** A view's lists as a file holds them, checked: an id that cannot be one is left out, as is one
+ *  named twice; none where both are empty. */
+export function cleanItems(raw) {
+    const r = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+    const seen = new Set();
+    const list = (x) => {
+        const out = [];
+        for (const id of Array.isArray(x) ? x : []) {
+            if (!validNoteId(id) || seen.has(id) || out.length >= MAX_ITEMS)
+                continue;
+            seen.add(id);
+            out.push(id);
+        }
+        return out;
+    };
+    const add = list(r.add);
+    const remove = list(r.remove);
+    return add.length || remove.length ? { items: { add, remove } } : {};
+}
+/** The operation that adds note `note` to a view (Add to view ▸, `to` "add") or takes it out of the
+ *  view (Remove from this view, `to` "remove"), `derived` saying whether the view's scope gives it:
+ *  added, it is in the view's add list only where the scope does not give it, and taken off its
+ *  remove list either way; taken out, it is on the remove list only where the scope gives it, and
+ *  off its add list either way. Null where the view is as asked already. */
+export function itemOp(items, note, to, derived) {
+    const want = to === "add" ? (derived ? null : "add") : derived ? "remove" : null;
+    return itemIn(items, note) === want ? null : { op: "item", note, in: want };
+}
+/** Whether a view shows a note after an item operation changed it from `was`: what the timeline
+ *  says of it — added (put on the add list, or taken off the remove list) or taken out. */
+export const itemShown = (was, o) => o.in === "add" || (o.in === null && was === "remove");
+/** The operations that take note `id` off every list of `views` that names it (a note deleted, or
+ *  made a view's own), by view. */
+export function dropItem(views, id) {
+    const out = [];
+    for (const v of views)
+        if (itemIn(v.items, id))
+            out.push({ view: v.id, op: { op: "item", note: id, in: null } });
+    return out;
+}

package/dist/shared/keys.js

@@ -0,0 +1,203 @@
+// Key declarations (ExportSpec decisions 1, 3 and 4): the members of a target's review that matter
+// for understanding it — the central definitions, the structures they are built on, the main theorem —
+// marked by people, or by agents at level full, per target; the target itself is always key. What each key declaration rests
+// on beyond itself (its support), and how the key declarations rest on one another (the key graph),
+// are pure functions of the graph, the review and the target's review set, over the same set and
+// edges the review queue walks (shared/reviewqueue.ts): the page, the agents' API and the exported
+// document (shared/doc/) all read them here.
+//
+// A member x that is not key is *supported by* a key declaration k when x is reachable from k
+// through members that are not key, along statement and body references. The key graph has an edge
+// from k₁ to k₂ when k₂ is reachable from k₁ that way. Two refinements keep "every member is
+// supported by some key declaration" true where the review set is more than what the target
+// reaches through its members:
+//
+// - a declaration of the project in the target's TCB that is trusted, by module or by name (a layer
+//   reviewed elsewhere), is not a member, but what it uses may be: the walk passes through it as
+//   through a member that is not key (the outside world never uses the project, so nothing else
+//   outside the set can lead back into it);
+// - a non-standard axiom the target rests on only through a proof is a member that no statement or
+//   body reaches: it is the target's support, as `viaProof` says.
+//
+// A review holds many members and a target a dozen key declarations: after one walk over the
+// target's TCB, each walk reads the edges of the members and of what it passes through, never the
+// whole graph's (the showcase's `Dim24.MainTheorem`: its TCB of 226 in 72 ms, its keys in 1 ms).
+import { keyMarks, statusOf } from "./review.js";
+import { TCB_SITES } from "./reviewqueue.js";
+/** The key declarations of `root` among the members of its review (`order`, the queue's order —
+ *  shared/reviewqueue.ts), in that order: the target, and each member marked key. A mark on
+ *  a declaration that has left the review (now trusted, or no longer in the TCB) is kept in the
+ *  review but counts for nothing until it is back. */
+export function keySet(g, d, root, order) {
+    const marked = new Set(keyMarks(d, g.nodes[root].name));
+    return order.filter((i) => i === root || marked.has(g.nodes[i].name));
+}
+/** `root`'s key graph over its review: `order` is the review's members in review order (the
+ *  queue's `order`). */
+export function keyGraph(g, d, root, order) {
+    const keys = keySet(g, d, root, order);
+    // the target is always key, also where the review does not hold it (a test, a graph read again)
+    if (!keys.includes(root))
+        keys.push(root);
+    const keyAt = new Map();
+    keys.forEach((k, j) => keyAt.set(k, j));
+    const position = new Map();
+    order.forEach((i, k) => position.set(i, k));
+    const member = (v) => position.has(v);
+    // what a walk may pass through besides members: the project's own declarations in the target's
+    // TCB that are not members, which only a trusted prefix keeps out of the review
+    const tcb = g.reach([root], TCB_SITES, "out");
+    const passable = (v) => member(v) || (tcb[v] === 1 && !g.isExt(v));
+    const supporters = new Map();
+    const support = keys.map(() => []);
+    const edges = new Set();
+    const K = keys.length;
+    const seen = new Int32Array(g.n).fill(-1);
+    for (let kj = 0; kj < K; kj++) {
+        const k = keys[kj];
+        seen[k] = kj;
+        const stack = [k];
+        while (stack.length) {
+            const u = stack.pop();
+            for (let e = g.outStart[u]; e < g.outStart[u + 1]; e++) {
+                if (!(g.outSite[e] & TCB_SITES))
+                    continue;
+                const v = g.outDst[e];
+                if (seen[v] === kj)
+                    continue;
+                seen[v] = kj;
+                const kv = keyAt.get(v);
+                // a key declaration is where a walk stops: what lies beyond it is its own support
+                if (kv !== undefined) {
+                    edges.add(kj * K + kv);
+                    continue;
+                }
+                if (!passable(v))
+                    continue;
+                if (member(v)) {
+                    const s = supporters.get(v);
+                    if (s)
+                        s.push(kj);
+                    else
+                        supporters.set(v, [kj]);
+                    support[kj].push(v);
+                }
+                stack.push(v);
+            }
+        }
+    }
+    // what no statement or body reaches: the target rests on it through a proof
+    const rootAt = keyAt.get(root);
+    const viaProof = [];
+    for (const i of order) {
+        if (keyAt.has(i) || supporters.has(i))
+            continue;
+        supporters.set(i, [rootAt]);
+        support[rootAt].push(i);
+        viaProof.push(i);
+    }
+    for (const s of support)
+        s.sort((a, b) => position.get(a) - position.get(b));
+    return {
+        root,
+        keys,
+        supporters,
+        support,
+        edges: [...edges].sort((a, b) => a - b).map((x) => [Math.floor(x / K), x % K]),
+        viaProof,
+    };
+}
+/** The key graph's edges to draw while the tool is the Keys step of Rests on and something is lit
+ *  (ViewSpec decision 20): of each key graph given — the focus's target's, or elsewhere every
+ *  target's, which makes the union over the targets whose key declarations are lit — the edges
+ *  whose two ends are lit, as [from, to] declarations, each once, in order. An edge from A to B
+ *  says that A rests on B through declarations that are not key. */
+export function litKeyEdges(kgs, lit) {
+    const out = new Map();
+    for (const kg of kgs) {
+        for (const [a, b] of kg.edges) {
+            const u = kg.keys[a], v = kg.keys[b];
+            if (lit(u) && lit(v))
+                out.set(`${u} ${v}`, [u, v]);
+        }
+    }
+    return [...out.values()].sort((x, y) => x[0] - y[0] || x[1] - y[1]);
+}
+/** How the declarations `xs` stand, by people's review status. */
+export function statusCounts(g, d, xs) {
+    const c = { total: 0, approved: 0, commented: 0, stale: 0, unreviewed: 0 };
+    for (const i of xs) {
+        c.total++;
+        const s = statusOf(d, g.nodes[i].name, g.nodes[i].hash);
+        if (s === "approved")
+            c.approved++;
+        else if (s === "commented")
+            c.commented++;
+        else if (s === "stale")
+            c.stale++;
+        else
+            c.unreviewed++;
+    }
+    return c;
+}
+/** The review's order with its key declarations first (ExportSpec decision 4): the key ones in
+ *  review order, then the rest in review order — how the agents' API lists a review set with
+ *  `key=first`. */
+export function keyFirst(order, isKey) {
+    return [...order.filter(isKey), ...order.filter((i) => !isKey(i))];
+}
+/** The key graph's layers, top-down (an index per key declaration, into `kg.keys`): the target at
+ *  0, each other one a layer below every key declaration that rests on it — the longest path from
+ *  the target, key declarations that rest on one another counted as one. A key declaration no
+ *  statement or body reaches (an axiom reached through a proof) is put just under the target. */
+export function keyLayers(kg) {
+    const K = kg.keys.length;
+    // reachability within the key graph: it is small (a dozen, a few dozen at most)
+    const reach = kg.keys.map(() => new Uint8Array(K));
+    for (const [a, b] of kg.edges)
+        reach[a][b] = 1;
+    for (let m = 0; m < K; m++)
+        for (let a = 0; a < K; a++)
+            if (reach[a][m])
+                for (let b = 0; b < K; b++)
+                    if (reach[m][b])
+                        reach[a][b] = 1;
+    // a component: those that reach one another, named by its first member
+    const comp = kg.keys.map((_, a) => {
+        for (let b = 0; b < a; b++)
+            if (reach[a][b] && reach[b][a])
+                return b;
+        return a;
+    });
+    const root = kg.keys.indexOf(kg.root);
+    const layer = new Array(K).fill(-1);
+    layer[root] = 0;
+    // longest path on the components, relaxed until nothing moves: at most K rounds
+    for (let round = 0; round <= K; round++) {
+        let moved = false;
+        for (const [a, b] of kg.edges) {
+            if (layer[a] < 0 || comp[a] === comp[b])
+                continue;
+            if (layer[b] < layer[a] + 1) {
+                layer[b] = layer[a] + 1;
+                moved = true;
+            }
+        }
+        // a component's members share its deepest layer
+        for (let a = 0; a < K; a++)
+            if (layer[a] >= 0 && layer[comp[a]] < layer[a])
+                (layer[comp[a]] = layer[a]), (moved = true);
+        for (let a = 0; a < K; a++)
+            if (layer[comp[a]] > layer[a])
+                (layer[a] = layer[comp[a]]), (moved = true);
+        if (!moved)
+            break;
+    }
+    return layer.map((l, a) => (l >= 0 ? l : a === root ? 0 : 1));
+}
+/** The key declarations top-down (indices into `kg.keys`): the target, then layer by layer, within
+ *  a layer the later in review order first — what rests on more comes before what it rests on. */
+export function topDown(kg) {
+    const layer = keyLayers(kg);
+    return kg.keys.map((_, a) => a).sort((a, b) => layer[a] - layer[b] || b - a);
+}