visualproof 0.1.0 → 0.3.0

package/dist/shared/doc/outline.js

@@ -0,0 +1,45 @@
+// The document's outline (ExportSpec decision 18, the linear form): what the document of a view
+// prints, in its order, without the text — its sections, numbered as the PDF numbers them, the
+// declarations and the notes in each, and the notes attached to a declaration after it. The page
+// draws the board as this outline (web/src/linear.ts); it is made from the same plan and the same
+// order the document is (shared/doc/sections.ts, shared/doc/order.ts), so that the two agree.
+import { orderDoc } from "./order.js";
+/** A note's first words: its first line, Markdown marks taken out, at most 60 characters. */
+export function firstWords(text) {
+    const line = text.split("\n").find((l) => l.trim()) ?? "";
+    const plain = line.replace(/[*_`#>]+/g, "").replace(/\s+/g, " ").trim();
+    return plain.length > 60 ? `${plain.slice(0, 59).trimEnd()}…` : plain;
+}
+/** The outline of the document of `plan` (of graph `g`) in the order of the board `spots` gives. */
+export function outlineOf(plan, g, spots) {
+    const order = orderDoc(plan, g, spots);
+    const note = (k) => {
+        const n = spots.notes[k];
+        return { t: "note", id: n.note.id, kind: n.kind, words: firstWords(n.note.text) };
+    };
+    const item = (p, prefix, at) => {
+        if (p.t === "note")
+            return note(p.k);
+        if (p.t === "decl") {
+            const ks = order.attached.get(p.i);
+            return { t: "decl", name: g.nodes[p.i].name, ...(ks?.length ? { notes: ks.map(note) } : {}) };
+        }
+        return section(p.s, prefix, at);
+    };
+    // numbered as the PDF numbers its headings (shared/doc/latex.ts): the first three levels, each
+    // within the one above; a paragraph-level heading has none
+    const section = (o, prefix, at) => {
+        const p = o.plan;
+        at.k++;
+        const number = p.level < 4 ? (prefix ? `${prefix}.${at.k}` : `${at.k}`) : null;
+        const inner = { k: 0 };
+        const items = o.items.map((x) => item(x, p.level < 3 ? (number ?? "") : "", inner));
+        return { t: "section", key: p.key, keys: [...p.keys], title: p.title, number, level: p.level, items };
+    };
+    const top = { k: 0 };
+    return {
+        items: order.items.map((x) => item(x, "", top)),
+        count: { declarations: plan.count, sections: plan.sectionCount },
+        ...(spots.fresh ? { fresh: true } : {}),
+    };
+}

package/dist/shared/keys.js

@@ -21,7 +21,7 @@
 //
 // 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).
+// whole graph's (Sphere-Packing-Lean'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 —

package/dist/shared/lostfound.js

@@ -64,6 +64,7 @@ export function lostEntries(d, views, has, known = (n) => n.includes("."), pinWh
                 kind: "opinion",
                 name,
                 ...who(o),
+                ...(o.recordedBy ? { recordedBy: o.recordedBy } : {}),
                 verdict: o.verdict,
                 ...(o.comment ? { comment: o.comment } : {}),
                 ...(was.length ? { aliases: was.map((n) => lostKey.opinion(name, n, o.at)) } : {}),

package/dist/shared/moves.js

@@ -209,7 +209,8 @@ export function renameInQuery(q, from, to) {
         }
         case "tcb":
         case "uses":
-        case "usedBy": {
+        case "usedBy":
+        case "refs": {
             if (q.of === "selection")
                 return q;
             if (Array.isArray(q.of)) {

package/dist/shared/pastgraph.js

@@ -21,6 +21,13 @@ export const PAST_GHOST = 1;
 export const PAST_CHANGED = 4;
 /** renamed since: shown under its name then */
 export const PAST_RENAMED = 8;
+/** The git commit of a past build; none where it is not known, or only guessed. Its source is the
+ *  project's, which the page has now (web/src/main.ts, GET /api/git). */
+function gitThen(commit) {
+    if (!commit || commit.guessed)
+        return { git: undefined };
+    return { git: { source: null, commit: commit.hash, branch: commit.branch, ...(commit.dirty ? { dirty: true } : {}) } };
+}
 /** The past graph of snapshot `snap` (its declarations and its edges, as /graph's parts give them),
  *  marked by `diff` (from it to the latest), with the project's description of `now`. */
 export function pastGraph(snap, edges, now, diff) {
@@ -33,7 +40,8 @@ export function pastGraph(snap, edges, now, diff) {
     const meta = {
         schema: 1,
         layoutVersion: now.meta.layoutVersion,
-        project: { ...now.meta.project, extractedAt: snap.snapshot.at },
+        // the commit of that build, where it is known
+        project: { ...now.meta.project, extractedAt: snap.snapshot.at, ...gitThen(snap.snapshot.commit) },
         modules: snap.modules.map((m) => ({ name: m.name, file: null, imports: m.imports })),
         nodes,
         projectCount: P,

package/dist/shared/query.js

@@ -8,7 +8,7 @@
 //
 // The text form, left to right:
 //
-//   all | selection | decl(A, B) | tcb(A) | uses(A, B) | usedBy(selection)
+//   all | selection | decl(A, B) | tcb(A) | uses(A, B) | usedBy(selection) | refs(A)
 //   tcb(ns(Fermat42) except external)   a closure of the set a query holds
 //   ns(Fermat42)                 declarations whose name is under the prefix
 //   file(Mathlib.NumberTheory)   declarations of the modules under the prefix
@@ -27,7 +27,7 @@ import { adviceOf, keyMarks, STANDARD_AXIOMS, statusOf, trusted, under } from ".
 export const KINDS = ["theorem", "def", "abbrev", "instance", "structure", "class", "inductive", "opaque", "axiom", "quot", "constructor", "recursor", "notation", "unknown"];
 export const STATUSES = ["unreviewed", "approved", "commented", "stale"];
 const VERDICTS = ["approve", "comment"];
-const CLOSURES = ["tcb", "uses", "usedBy"];
+const CLOSURES = ["tcb", "uses", "usedBy", "refs"];
 const PLAIN = ["all", "selection", "trusted", "external", "sorry", "nonstandard"];
 const COMBINATORS = ["and", "or", "except"];
 /** words for the same thing, read as the first */
@@ -38,10 +38,11 @@ export const LIGHT = {
     plain: { op: "selection" },
     tcb: { op: "tcb", of: "selection" },
     deps: { op: "uses", of: "selection" },
+    refs: { op: "refs", of: "selection" },
     apps: { op: "usedBy", of: "selection" },
 };
-/** Which closure each closure word is, as the graph computes it (shared/viewgraph.ts). */
-const CLOSURE_MODE = { tcb: "tcb", uses: "deps", usedBy: "apps" };
+/** Which walk of the graph each closure word is (shared/viewgraph.ts); `refs` is one step. */
+const CLOSURE_MODE = { tcb: "tcb", uses: "deps", usedBy: "apps", refs: "refs" };
 // ---------------------------------------------------------------- how large a query may be
 /** How large a query may be: one set of bounds for its text and its JSON form, checked when either
  *  is read (parseQuery, cleanQuery), so that what one form takes the other takes too — a scope
@@ -61,7 +62,7 @@ export const QUERY_LIMITS = {
     names: 2_000,
     /** characters of one name or prefix */
     name: 2_000,
-    /** closures (tcb, uses, usedBy), each a walk of the graph; each target of a `key(…)` counts as
+    /** closures (tcb, uses, usedBy, refs), each a walk of the graph; each target of a `key(…)` counts as
      *  one too, since its review set is walked to keep only the marks still in it. `key(targets)`
      *  counts as one: how many targets there are is the project's, not the query's, and every
      *  `key(targets)` of a query shares the same walks (evaluateIn) */
@@ -88,6 +89,7 @@ export function beyondLimits(q) {
             case "tcb":
             case "uses":
             case "usedBy":
+            case "refs":
                 closures++;
                 if (x.of !== "selection" && !Array.isArray(x.of)) {
                     terms++;
@@ -131,7 +133,7 @@ export function beyondLimits(q) {
     if (longest > L.name)
         return `a name in the query is longer than ${L.name.toLocaleString("en")} characters`;
     if (closures > L.closures)
-        return `the query has ${closures} closures (tcb, uses, usedBy), more than ${L.closures}`;
+        return `the query has ${closures} closures (tcb, uses, usedBy, refs), more than ${L.closures}`;
     const length = printQuery(q).length;
     if (length > L.text)
         return `the query is ${length.toLocaleString("en")} characters long as printed, more than ${L.text.toLocaleString("en")}`;
@@ -286,7 +288,7 @@ function parse(text) {
         }
         const w = keyword(t);
         if (w === null)
-            throw new QueryError(t.t === "string" ? "a quoted name stands only inside decl(…), tcb(…), uses(…) or usedBy(…)" : `${t.t} is out of place`, t.at);
+            throw new QueryError(t.t === "string" ? "a quoted name stands only inside decl(…), tcb(…), uses(…), usedBy(…) or refs(…)" : `${t.t} is out of place`, t.at);
         if (++terms > QUERY_LIMITS.terms)
             throw new QueryError(`the query has more than ${QUERY_LIMITS.terms.toLocaleString("en")} parts`, t.at);
         k++;
@@ -338,7 +340,7 @@ function parse(text) {
             return { op: "status", statuses: choose(args(), STATUSES, "status") };
         if (w === "advice")
             return { op: "advice", verdicts: choose(args(), VERDICTS, "advice") };
-        throw new QueryError(`${text1(t)} is not a word of the query language (all, tcb, uses, usedBy, decl, key, ns, file, trusted, external, kind, status, advice, sorry, nonstandard)`, t.at);
+        throw new QueryError(`${text1(t)} is not a word of the query language (all, tcb, uses, usedBy, refs, decl, key, ns, file, trusted, external, kind, status, advice, sorry, nonstandard)`, t.at);
     };
     const expr = () => {
         let q = atom();
@@ -376,7 +378,8 @@ export function printQuery(q) {
             return `key(${q.of === "targets" ? "targets" : q.of.map((t) => (t === "targets" ? JSON.stringify(t) : arg(t))).join(", ")})`;
         case "tcb":
         case "uses":
-        case "usedBy": {
+        case "usedBy":
+        case "refs": {
             if (q.of === "selection" || Array.isArray(q.of))
                 return `${q.op}(${q.of === "selection" ? "selection" : q.of.map(arg).join(", ")})`;
             // a query of one plain word would read as a name
@@ -461,7 +464,8 @@ function readJson(x, why = false) {
                 return names(o.of) ? { op: "key", of: [...o.of] } : null;
             case "tcb":
             case "uses":
-            case "usedBy": {
+            case "usedBy":
+            case "refs": {
                 if (o.of === "selection")
                     return { op: o.op, of: "selection" };
                 if (o.of && typeof o.of === "object" && !Array.isArray(o.of)) {
@@ -531,7 +535,7 @@ export function namesIn(q) {
             x.names.forEach((n) => out.add(n));
         else if (x.op === "key" && x.of !== "targets")
             x.of.forEach((n) => out.add(n));
-        else if (x.op === "tcb" || x.op === "uses" || x.op === "usedBy") {
+        else if (x.op === "tcb" || x.op === "uses" || x.op === "usedBy" || x.op === "refs") {
             if (Array.isArray(x.of))
                 x.of.forEach((n) => out.add(n));
             else if (x.of !== "selection")
@@ -549,7 +553,7 @@ export function namesIn(q) {
 export function readsReview(q) {
     if (q.op === "trusted" || q.op === "status" || q.op === "advice" || q.op === "key")
         return true;
-    if ((q.op === "tcb" || q.op === "uses" || q.op === "usedBy") && q.of !== "selection" && !Array.isArray(q.of))
+    if ((q.op === "tcb" || q.op === "uses" || q.op === "usedBy" || q.op === "refs") && q.of !== "selection" && !Array.isArray(q.of))
         return readsReview(q.of);
     if (q.op === "and" || q.op === "or" || q.op === "except")
         return readsReview(q.a) || readsReview(q.b);
@@ -563,6 +567,7 @@ export function withSelection(q, names) {
         case "tcb":
         case "uses":
         case "usedBy":
+        case "refs":
             if (q.of === "selection")
                 return { op: q.op, of: [...names] };
             return Array.isArray(q.of) ? q : { op: q.op, of: withSelection(q.of, names) };
@@ -647,6 +652,8 @@ export function describe(q) {
             return `TCB of ${roots(q.of)}`;
         case "uses":
             return `what ${roots(q.of)} uses`;
+        case "refs":
+            return `what ${roots(q.of)} uses directly`;
         case "usedBy":
             return `what uses ${roots(q.of)}`;
         case "ns":
@@ -759,7 +766,8 @@ function evaluateIn(q, ctx, walks) {
             return out;
         case "tcb":
         case "uses":
-        case "usedBy": {
+        case "usedBy":
+        case "refs": {
             const key = `${q.op}\u0000${q.of === "selection" ? "\u0001" : Array.isArray(q.of) ? JSON.stringify(q.of) : printQuery(q.of)}`;
             let walked = walks.get(key);
             if (!walked) {

package/dist/shared/review.js

@@ -40,6 +40,7 @@
 // Declarations are keyed by name, and a name can be anything Lean allows: `toString`,
 // `constructor`, even `__proto__`. Every object keyed by names here has no prototype (`byName`),
 // is read with Object.hasOwn, and is never spread or assigned into a plain object.
+import { validName } from "./collab.js";
 import { applyLibrary, invalidLibrary, isLibraryOp, libraryEventOf, libraryFromJson, libraryNoChange, readLibraryEvent, renamePerson } from "./library.js";
 import { applyMove, moveIsIdle, readMove } from "./moves.js";
 export const DEFAULT_TRUSTED = ["Batteries", "Init", "Lean", "Mathlib", "Std"];
@@ -102,6 +103,19 @@ export function invalid(r) {
         return "agent";
     if (o.person !== undefined && (!validPersonId(o.person) || o.agent))
         return "person";
+    // an opinion recorded for someone else (ReviewSpec decision 8): a person's, for another person
+    if (o.for !== undefined || o.forPerson !== undefined) {
+        if (o.op !== "opinion")
+            return "only an opinion is recorded for someone else";
+        if (o.agent)
+            return "an agent records for no one";
+        if (typeof o.for !== "string" || !validName(o.for.trim()))
+            return "for";
+        if (o.forPerson !== undefined && !validPersonId(o.forPerson))
+            return "forPerson";
+        if (o.for.trim() === o.by.trim() || (o.forPerson !== undefined && o.forPerson === o.person))
+            return "an opinion of one's own is recorded as one's own";
+    }
     switch (o.op) {
         case "opinion":
             if (o.verdict !== "approve" && o.verdict !== "comment")
@@ -153,6 +167,12 @@ export function eventOf(d, r, toolchain, now) {
     switch (r.op) {
         case "opinion": {
             const e = { op: "opinion", name: r.name, by, ...person, verdict: r.verdict, at: now, toolchain };
+            // recorded for someone else (ReviewSpec decision 8)
+            if (r.for?.trim()) {
+                e.for = r.for.trim();
+                if (r.forPerson)
+                    e.forPerson = r.forPerson;
+            }
             if (r.comment?.trim())
                 e.comment = r.comment.trim();
             if (r.agent)
@@ -160,7 +180,7 @@ export function eventOf(d, r, toolchain, now) {
             // the text matters only to an opinion that can go stale, one bound to a version
             if (r.hash) {
                 e.hash = r.hash;
-                const was = (Object.hasOwn(d.opinions, r.name) ? d.opinions[r.name] : []).findLast((p) => author(p) === author(e));
+                const was = (Object.hasOwn(d.opinions, r.name) ? d.opinions[r.name] : []).findLast((p) => author(p) === voice(e));
                 const same = was?.hash === r.hash ? judgedOn(d, r.name, was) : null;
                 if (r.text !== undefined && !(same?.of === "source" && same.text === r.text))
                     e.text = r.text;
@@ -212,8 +232,8 @@ export function applyEvent(d, e) {
         case "name":
             return;
         case "opinion": {
-            const { op: _op, name, ...o } = e;
-            (Object.hasOwn(d.opinions, name) ? d.opinions[name] : (d.opinions[name] = [])).push(o);
+            const { op: _op, name, for: forName, forPerson, ...o } = e;
+            (Object.hasOwn(d.opinions, name) ? d.opinions[name] : (d.opinions[name] = [])).push(forName === undefined ? o : recordedFor(d, o, forName, forPerson));
             return;
         }
         case "target":
@@ -256,15 +276,27 @@ function named(d, id, name) {
     if (p?.name === name)
         return;
     if (!p) {
-        d.people[id] = { name, was: [] };
+        // first seen after opinions were recorded for them (decision 8): those show under this name,
+        // the names they were written under kept, so that a quote of one still finds it
+        const was = new Set();
+        for (const ops of Object.values(d.opinions))
+            for (const o of ops)
+                if (o.person === id && o.by !== name) {
+                    was.add(o.by);
+                    o.by = name;
+                }
+        d.people[id] = { name, was: [...was] };
         return;
     }
     p.was = [...p.was.filter((n) => n !== p.name && n !== name), p.name];
     p.name = name;
     for (const ops of Object.values(d.opinions))
-        for (const o of ops)
+        for (const o of ops) {
             if (o.person === id)
                 o.by = name;
+            if (o.recordedBy?.person === id)
+                o.recordedBy.by = name;
+        }
     for (const t of Object.values(d.targets))
         if (t.person === id)
             t.by = name;
@@ -351,6 +383,20 @@ export function readEvent(raw, agentLog, personLog = null) {
             }
             if (e.text !== undefined && e.statement !== undefined)
                 return "a text and a statement";
+            // recorded for someone else (ReviewSpec decision 8): a person's line, for another person
+            if (o.for !== undefined || o.forPerson !== undefined) {
+                if (agentLog)
+                    return "an agent's opinion recorded for someone else";
+                if (typeof o.for !== "string" || !validName(o.for))
+                    return "for";
+                if (o.forPerson !== undefined && !validPersonId(o.forPerson))
+                    return "forPerson";
+                if (o.for === by || (o.forPerson !== undefined && o.forPerson === personLog))
+                    return "an opinion recorded for its own writer";
+                e.for = o.for;
+                if (o.forPerson !== undefined)
+                    e.forPerson = o.forPerson;
+            }
             if (agentLog)
                 e.agent = true;
             return e;
@@ -503,6 +549,17 @@ export function problemsText(ps) {
 function author(o) {
     return o.person ? `link ${o.person}` : (o.agent ? "agent " : "person ") + o.by;
 }
+/** Whose an opinion line is: theirs it was recorded for (ReviewSpec decision 8), else its writer's. */
+function voice(e) {
+    return e.for === undefined ? author(e) : author({ by: e.for, verdict: e.verdict, at: e.at, ...(e.forPerson ? { person: e.forPerson } : {}) });
+}
+/** An opinion recorded for someone else (ReviewSpec decision 8), as the review holds it: theirs —
+ *  under their latest name where they are invited — saying who recorded it. */
+function recordedFor(d, o, forName, forPerson) {
+    const { by, person, ...rest } = o;
+    const name = forPerson && Object.hasOwn(d.people, forPerson) ? d.people[forPerson].name : forName;
+    return { ...rest, by: name, ...(forPerson ? { person: forPerson } : {}), recordedBy: { by, ...(person ? { person } : {}) } };
+}
 /** Each author's latest opinion on a declaration, people's or agents': a new one replaces their
  *  earlier one. */
 function latest(d, name, agents) {

package/dist/shared/sharesnap.js

@@ -105,7 +105,8 @@ export const SNAPSHOT_FORMS = {
     lostFound: same("lostFound"),
     colouring: same("scheme"),
     edges: same("edges"),
-    proofEdges: same("proofEdges"),
+    linear: same("linear"),
+    artwork: same("artwork"),
 };
 /** The snapshot of where a page is (`v`, as presence carries it: the registry's parts, read by the
  *  page), as a link carries it after `snap=`. */

package/dist/shared/titles.js

@@ -224,6 +224,8 @@ function said(q, N) {
             return `TCB of ${roots(q.of, N)}`;
         case "uses":
             return `what ${roots(q.of, N)} uses`;
+        case "refs":
+            return `what ${roots(q.of, N)} uses directly`;
         case "usedBy":
             return `what uses ${roots(q.of, N)}`;
         case "ns":

package/dist/shared/viewgraph.js

@@ -9,6 +9,7 @@ export const MODE_SITES = {
     plain: ALL_SITES,
     tcb: SITE_STMT | SITE_BODY,
     deps: ALL_SITES,
+    refs: ALL_SITES,
     apps: ALL_SITES,
 };
 export class Graph {
@@ -69,6 +70,20 @@ export class Graph {
     isExt(i) {
         return i >= this.projectCount;
     }
+    /** `from` and what is one edge from it, along edges whose sites meet `sites`. */
+    step(from, sites, dir) {
+        const seen = new Uint8Array(this.n);
+        const start = dir === "out" ? this.outStart : this.inStart;
+        const adj = dir === "out" ? this.outDst : this.inSrc;
+        const site = dir === "out" ? this.outSite : this.inSite;
+        for (const u of from) {
+            seen[u] = 1;
+            for (let e = start[u]; e < start[u + 1]; e++)
+                if (site[e] & sites)
+                    seen[adj[e]] = 1;
+        }
+        return seen;
+    }
     /** Everything reachable from `from` (included) along edges whose sites meet `sites`. */
     reach(from, sites, dir) {
         const seen = new Uint8Array(this.n);
@@ -108,6 +123,9 @@ export class Graph {
                 return this.reach(focus, MODE_SITES.tcb, "out");
             case "deps":
                 return this.reach(focus, ALL_SITES, "out");
+            // Direct: what it uses directly, one step (ViewSpec decision 20, the owner's decision of 2026-10-14)
+            case "refs":
+                return this.step(focus, ALL_SITES, "out");
             case "apps":
                 return this.reach(focus, ALL_SITES, "in");
         }