visualproof 0.0.0-stage → 0.1.0

package/dist/shared/lostfound.js

@@ -0,0 +1,150 @@
+// The lost-and-found (HistorySpec decisions 12–14, the owner's of 2026-10-09): what people and agents
+// said and marked of a declaration the graph no longer has — an opinion with its comment, a target
+// mark, a key mark, a pin on a view, a note's mention of it — that no rename in force carried to a
+// new name. Nothing is deleted when a declaration goes: what was said of it waits here, under the
+// name it was said of, until someone attaches it to a declaration of the graph (a move, HistorySpec
+// decision 9) or archives it, which only hides it.
+//
+// The entries are computed, never stored: from the review and the views as they are, against the
+// graph on show. Each is keyed by what it is and where, so that the same thing is the same entry on
+// every page and in the archive (server/lostfound.ts), which is the one thing kept:
+//
+//   opinion:<name>#<by>@<at>        an opinion (the reference comments use, shared/comment.ts)
+//   target:<name>                   a target mark
+//   key:<target>#<name>             a key mark, lost where either name is gone
+//   pin:<view>:<mode>:<name>        a declaration's pin on a view, under one way of clustering
+//   note:<view>:<note id>:<name>    a note's mention of a full name in backticks
+//   link:<link id>                  a link into the library (AttachmentSpec decision 6), its
+//                                   declaration gone, or its cluster (listed as `ns(P)`, `file(P)`)
+//   move:<migration id>             a migration (server/renames.ts), listed beside the lost
+//
+// This file is what the server and the pages share: the entries, their keys, and the shape of the
+// answer the server gives (GET /api/history/lost).
+import { opinionRef } from "./comment.js";
+import { CLUSTER_MODES } from "./places.js";
+import { viewTitle } from "./views.js";
+/** The order the kinds are listed in, under one name. */
+const KIND_ORDER = ["target", "key", "opinion", "link", "note", "pin"];
+/** A name as a note writes one in full between backticks: a dotted or plain Lean name, nothing
+ *  that reads as code (spaces, operators). */
+const NAME_LIKE = /^[\p{L}_«][^\s`(){}[\],;:=+*<>|&^%$#@~"/\\]*$/u;
+export const lostKey = {
+    opinion: (name, by, at) => opinionRef(name, by, at),
+    target: (name) => `target:${name}`,
+    key: (target, name) => `key:${target}#${name}`,
+    pin: (view, mode, name) => `pin:${view}:${mode}:${name}`,
+    note: (view, note, name) => `note:${view}:${note}:${name}`,
+    link: (id) => `link:${id}`,
+    move: (id) => `move:${id}`,
+};
+/** Every entry of the lost-and-found: what the review (`d`) and the views hold of a name the graph
+ *  on show does not have (`has`). A note's mention counts where its name is not in the graph, no
+ *  rename in force leads from it to one that is (`d.renamed`), and it was a declaration (`known`:
+ *  the history had it; without a history, a dotted name). `pinWho` says who dropped a pin, where
+ *  the caller knows (the server does; pages are not told); `titleOf` what a view is called (the
+ *  server's titles know the graph's names). A view kept at a past build is a board of that build
+ *  (HistorySpec decision 19): a pin or a mention of a declaration its build had is not lost
+ *  (`atBuild`). Sorted by name, then kind, then time. */
+export function lostEntries(d, views, has, known = (n) => n.includes("."), pinWho = () => null, titleOf = (v) => viewTitle(v), atBuild = () => false, notes = [], hasCluster = null) {
+    const out = [];
+    const who = (x) => ({
+        by: x.by,
+        ...(x.agent ? { agent: true } : {}),
+        ...(x.person ? { person: x.person } : {}),
+        at: x.at,
+    });
+    for (const [name, ops] of Object.entries(d.opinions)) {
+        if (has(name))
+            continue;
+        for (const o of ops) {
+            // an archiving made while the writer went by another name is kept under that name's key
+            const was = o.person && Object.hasOwn(d.people, o.person) ? d.people[o.person].was.filter((n) => n !== o.by) : [];
+            out.push({
+                key: lostKey.opinion(name, o.by, o.at),
+                kind: "opinion",
+                name,
+                ...who(o),
+                verdict: o.verdict,
+                ...(o.comment ? { comment: o.comment } : {}),
+                ...(was.length ? { aliases: was.map((n) => lostKey.opinion(name, n, o.at)) } : {}),
+            });
+        }
+    }
+    for (const [name, t] of Object.entries(d.targets))
+        if (!has(name))
+            out.push({ key: lostKey.target(name), kind: "target", name, ...who(t) });
+    // a key mark is lost where the declaration marked is gone (as a member), or its target (as a
+    // target's own); it is listed under the member's name where that is gone
+    for (const [target, marks] of Object.entries(d.keys))
+        for (const [member, m] of Object.entries(marks))
+            if (!has(member) || !has(target))
+                out.push({ key: lostKey.key(target, member), kind: "key", name: has(member) ? target : member, ...who(m), target, member });
+    // a link whose declaration is gone (a move would have carried it), or whose cluster is: listed
+    // under the declaration's name, or under the cluster as its subject names it
+    for (const l of d.links ?? []) {
+        const m = /^(decl|ns|file)\((.+)\)$/s.exec(l.subject);
+        if (!m)
+            continue;
+        const gone = m[1] === "decl" ? !has(m[2]) : hasCluster !== null && !hasCluster(m[1], m[2]);
+        if (!gone)
+            continue;
+        const f = d.files && Object.hasOwn(d.files, l.file) ? d.files[l.file] : null;
+        out.push({ key: lostKey.link(l.id), kind: "link", name: m[1] === "decl" ? m[2] : l.subject, ...who(l), link: l.id, label: l.label, ...(f ? { fileTitle: f.title } : {}) });
+    }
+    // the names each name became, through the renames in force: a note may name one before its rename
+    const ahead = new Map();
+    for (const [to, from] of Object.entries(d.renamed ?? {}))
+        ahead.set(from, to);
+    const leads = (name) => {
+        let n = name;
+        for (let k = 0; k < 1000 && ahead.has(n); k++) {
+            n = ahead.get(n);
+            if (has(n))
+                return true;
+        }
+        return false;
+    };
+    /** the mentions in a note's text of names that are gone, each an entry */
+    const mentions = (n, view, title, gone) => {
+        const names = new Set();
+        for (const m of n.text.matchAll(/`([^`\n]+)`/g))
+            names.add(m[1]);
+        for (const name of names) {
+            if (!NAME_LIKE.test(name) || has(name) || leads(name) || !known(name) || !gone(name))
+                continue;
+            out.push({ key: lostKey.note(view, n.id, name), kind: "note", name, ...who(n), view, title, note: n.id, text: n.text });
+        }
+    };
+    // the project's notes (AttachmentSpec decision 13): view "", on no board of a past build
+    for (const n of notes)
+        mentions(n, "", "", () => true);
+    for (const v of views) {
+        const title = titleOf(v);
+        for (const mode of CLUSTER_MODES)
+            for (const name of Object.keys(v.pins[mode].nodes)) {
+                if (has(name) || atBuild(v, name))
+                    continue;
+                const w = pinWho(v.id, mode, name);
+                out.push({ key: lostKey.pin(v.id, mode, name), kind: "pin", name, by: w?.by ?? null, ...(w?.agent ? { agent: true } : {}), at: w?.at ?? "", view: v.id, title, mode });
+            }
+        for (const n of v.notes ?? [])
+            mentions(n, v.id, title, (name) => !atBuild(v, name));
+    }
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return out.sort((a, b) => cmp(a.name, b.name) || KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind) || cmp(a.at, b.at) || cmp(a.key, b.key));
+}
+/** What a migration carried, as words: "2 opinions, a target mark, 3 pins". */
+export function carriedText(c) {
+    const n = (k, one, many = `${one}s`) => (k ? (k === 1 ? `1 ${one}` : `${k} ${many}`) : "");
+    const parts = [
+        n(c.opinions, "opinion"),
+        n(c.targets, "target mark"),
+        n(c.keys, "key mark"),
+        n(c.links ?? 0, "link"),
+        n(c.reviewViews, "target's view", "targets' views"),
+        n(c.pins, "pin"),
+        n(c.notes, "note"),
+        n(c.scopes, "view's scope", "views' scopes"),
+    ].filter(Boolean);
+    return parts.length ? parts.join(", ") : "nothing said of it: its identity alone";
+}

package/dist/shared/moves.js

@@ -0,0 +1,243 @@
+// Moves (HistorySpec.md, the owner's decisions of 2026-10-09): what was said about a declaration
+// follows it to another name. A move is an event of the review's logs, appended like any other and
+// never rewritten: replayed, it carries the opinions given on `from` (their comments with them), its
+// target mark and the key marks on it — as a declaration of a target's review, and as a target —
+// over to `to`. Each thing carried keeps the names it was on before (`was`), so that undoing a move,
+// an un-move (`on: false`), takes back exactly what that move carried and leaves what was said of
+// `to` since. A move the server found as a rename, or one a person made onto a declaration that
+// appeared as the other went, also says that `to` *is* `from` renamed (`rename`): the version of
+// whatever refers to it is then made with `from`'s identity (TCBSpec decision 3), so that renaming
+// it stales nothing. Since 2026-10-11 a move carries the links on the declaration too
+// (AttachmentSpec decision 6): a link on `decl(from)` is on `decl(to)` after it, its `was` saying
+// where it was. Moving a note's mention, a pin or a view's scope is the views' business
+// (server/views.ts); this file is what the server and the pages replay.
+//
+// Declarations are keyed by name; every object keyed by names here has no prototype, as in
+// shared/review.ts.
+/** A declaration as a link's subject names it (shared/library.ts, declSubject). */
+const declOf = (name) => `decl(${name})`;
+const own = (o, k) => Object.hasOwn(o, k);
+const noProto = () => Object.create(null);
+const byTime = (xs) => xs.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+/** One move replayed onto a review. */
+export function applyMove(d, e) {
+    if (e.from === e.to)
+        return;
+    if (e.on)
+        carry(d, e.from, e.to);
+    else
+        takeBack(d, e.from, e.to);
+    if (!e.rename)
+        return;
+    const links = (d.renamed ??= noProto());
+    if (e.on) {
+        // renamed back (`to` is where `from` came from): `to` is itself again, and `from` is no one's
+        if (identityIn(links, e.from) === e.to) {
+            delete links[e.to];
+            delete links[e.from];
+        }
+        else
+            links[e.to] = e.from;
+    }
+    else if (own(links, e.to) && links[e.to] === e.from)
+        delete links[e.to];
+}
+function carry(d, from, to) {
+    const moved = (x) => ({ ...x, was: [...(x.was ?? []), from] });
+    if (own(d.opinions, from)) {
+        const os = d.opinions[from].map(moved);
+        delete d.opinions[from];
+        d.opinions[to] = byTime([...(own(d.opinions, to) ? d.opinions[to] : []), ...os]);
+    }
+    if (own(d.targets, from)) {
+        if (!own(d.targets, to))
+            d.targets[to] = moved(d.targets[from]);
+        delete d.targets[from];
+    }
+    // a key mark on it, in each target's review
+    for (const t of Object.keys(d.keys)) {
+        const ks = d.keys[t];
+        if (!own(ks, from))
+            continue;
+        if (!own(ks, to))
+            ks[to] = moved(ks[from]);
+        delete ks[from];
+    }
+    // its own key marks, as a target
+    if (own(d.keys, from)) {
+        const ks = (own(d.keys, to) ? d.keys[to] : (d.keys[to] = noProto()));
+        for (const [n, m] of Object.entries(d.keys[from]))
+            if (n !== to && !own(ks, n))
+                ks[n] = { ...m, wasOf: [...(m.wasOf ?? []), from] };
+        delete d.keys[from];
+    }
+    // the links on it, in the order they were made
+    if (d.links)
+        d.links = d.links.map((l) => (l.subject === declOf(from) ? { ...moved(l), subject: declOf(to) } : l));
+}
+function takeBack(d, from, to) {
+    const came = (x) => x.was?.[x.was.length - 1] === from;
+    const back = (x) => {
+        const was = x.was.slice(0, -1);
+        const y = { ...x };
+        if (was.length)
+            y.was = was;
+        else
+            delete y.was;
+        return y;
+    };
+    if (own(d.opinions, to)) {
+        const all = d.opinions[to];
+        const os = all.filter(came);
+        if (os.length) {
+            const stay = all.filter((o) => !came(o));
+            if (stay.length)
+                d.opinions[to] = stay;
+            else
+                delete d.opinions[to];
+            d.opinions[from] = byTime([...(own(d.opinions, from) ? d.opinions[from] : []), ...os.map(back)]);
+        }
+    }
+    if (own(d.targets, to) && came(d.targets[to])) {
+        if (!own(d.targets, from))
+            d.targets[from] = back(d.targets[to]);
+        delete d.targets[to];
+    }
+    for (const t of Object.keys(d.keys)) {
+        const ks = d.keys[t];
+        if (!own(ks, to) || !came(ks[to]))
+            continue;
+        if (!own(ks, from))
+            ks[from] = back(ks[to]);
+        delete ks[to];
+    }
+    if (own(d.keys, to)) {
+        const ks = d.keys[to];
+        const marks = Object.entries(ks).filter(([, m]) => m.wasOf?.[m.wasOf.length - 1] === from);
+        if (marks.length) {
+            const into = own(d.keys, from) ? d.keys[from] : (d.keys[from] = noProto());
+            for (const [n, m] of marks) {
+                const wasOf = m.wasOf.slice(0, -1);
+                const y = { ...m };
+                if (wasOf.length)
+                    y.wasOf = wasOf;
+                else
+                    delete y.wasOf;
+                if (!own(into, n))
+                    into[n] = y;
+                delete ks[n];
+            }
+            if (!Object.keys(ks).length)
+                delete d.keys[to];
+        }
+    }
+    if (d.links)
+        d.links = d.links.map((l) => (l.subject === declOf(to) && came(l) ? { ...back(l), subject: declOf(from) } : l));
+}
+/** The identity of a unit's name under the renames in force (`renamed`: `to` → `from`): the first
+ *  name it had, followed back through each rename. */
+export function identityIn(renamed, name) {
+    if (!renamed)
+        return name;
+    let n = name;
+    // a chain is as long as the renames of one declaration; a loop cannot be made (applyMove), but a
+    // log edited by hand could hold one
+    for (let k = 0; k < 1000 && own(renamed, n); k++) {
+        const p = renamed[n];
+        if (p === name)
+            break;
+        n = p;
+    }
+    return n;
+}
+/** Whether a move would change nothing: nothing to carry or take back, and no identity to link or
+ *  unlink. Such a request writes nothing. */
+export function moveIsIdle(d, e) {
+    if (e.from === e.to)
+        return true;
+    const came = (x) => x.was?.[x.was.length - 1] === e.from;
+    const links = d.renamed ?? noProto();
+    if (e.on) {
+        const carries = own(d.opinions, e.from) || own(d.targets, e.from) || own(d.keys, e.from) || Object.values(d.keys).some((ks) => own(ks, e.from)) || !!d.links?.some((l) => l.subject === declOf(e.from));
+        return !carries && (!e.rename || (own(links, e.to) && links[e.to] === e.from));
+    }
+    const back = (own(d.opinions, e.to) && d.opinions[e.to].some(came)) ||
+        (own(d.targets, e.to) && came(d.targets[e.to])) ||
+        Object.values(d.keys).some((ks) => own(ks, e.to) && came(ks[e.to])) ||
+        (own(d.keys, e.to) && Object.values(d.keys[e.to]).some((m) => m.wasOf?.[m.wasOf.length - 1] === e.from)) ||
+        !!d.links?.some((l) => l.subject === declOf(e.to) && came(l));
+    return !back && !(e.rename && own(links, e.to) && links[e.to] === e.from);
+}
+/** A move's line, read: the event, or why it is not one. */
+export function readMove(o, at, by, agent) {
+    const str = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
+    if (!str(o.from, 2000))
+        return "from";
+    if (!str(o.to, 2000))
+        return "to";
+    if (o.from === o.to)
+        return "a move to the same name";
+    if (typeof o.on !== "boolean")
+        return "on";
+    if (o.rename !== undefined && o.rename !== true)
+        return "rename";
+    if (o.auto !== undefined && !str(o.auto, 200))
+        return "auto";
+    if (o.snap !== undefined && !(Number.isInteger(o.snap) && o.snap > 0))
+        return "snap";
+    return {
+        op: "move",
+        at,
+        by,
+        from: o.from,
+        to: o.to,
+        on: o.on,
+        ...(o.rename ? { rename: true } : {}),
+        ...(o.auto !== undefined ? { auto: o.auto } : {}),
+        ...(o.snap !== undefined ? { snap: o.snap } : {}),
+        ...(agent ? { agent: true } : {}),
+    };
+}
+/** A view's scope with declaration `from` named `to` instead: in `decl(…)`, the roots of a closure,
+ *  and the targets of `key(…)`. The same object where it does not name it. */
+export function renameInQuery(q, from, to) {
+    const names = (xs) => (xs.includes(from) ? [...new Set(xs.map((x) => (x === from ? to : x)))] : xs);
+    switch (q.op) {
+        case "decl": {
+            const n = names(q.names);
+            return n === q.names ? q : { ...q, names: n };
+        }
+        case "tcb":
+        case "uses":
+        case "usedBy": {
+            if (q.of === "selection")
+                return q;
+            if (Array.isArray(q.of)) {
+                const n = names(q.of);
+                return n === q.of ? q : { ...q, of: n };
+            }
+            const of = renameInQuery(q.of, from, to);
+            return of === q.of ? q : { ...q, of };
+        }
+        case "key": {
+            if (q.of === "targets")
+                return q;
+            const n = names(q.of);
+            return n === q.of ? q : { ...q, of: n };
+        }
+        case "and":
+        case "or":
+        case "except": {
+            const a = renameInQuery(q.a, from, to);
+            const b = renameInQuery(q.b, from, to);
+            return a === q.a && b === q.b ? q : { ...q, a, b };
+        }
+        default:
+            return q;
+    }
+}
+/** A note's text with declaration `from`, written in full between backticks, named `to` instead
+ *  (`` `A.f` `` → `` `A.g` ``); the same text where it does not mention it so. */
+export function renameInNote(text, from, to) {
+    return text.includes("`" + from + "`") ? text.split("`" + from + "`").join("`" + to + "`") : text;
+}