@graview/core 0.1.27 → 0.1.28

package/dist/document/edit.js

@@ -5,7 +5,7 @@ import { error } from "./findings.js";
 import { coerce } from "./migrate.js";
 import { outsideRange, rangeWords } from "./range.js";
 import { farEnd } from "./far-end.js";
-import { ActSpec, EDGE_NAME, EdgeSpec, FIELD_NAME, FIELD_TYPES, FieldSpec, KindSpec, NAME, RuleSpec, } from "./schema.js";
+import { ActSpec, EDGE_NAME, EdgeSpec, FIELD_NAME, FIELD_TYPES, FieldSpec, GrantSpec, KindSpec, NAME, RuleSpec, SightSpec, } from "./schema.js";
 import { SHIPPED_LENSES, isShippedLens, SHIPPED_LENS_NAMES } from "../places.js";
 import { placeSlug } from "../views/types.js";
 import { computedOf, validateComputed } from "./computed.js";
@@ -18,7 +18,9 @@ import { isRecord as isObject, respellDocument } from "./respell.js";
 import { refName } from "./compiled.js";
 import { accentProblem } from "../theme/accent.js";
 import { pageFieldFindings, pageNames, renamedOnPage, withoutOnPage } from "./page-fields.js";
-import { capitalize } from "../capital.js";
+import { capitalize, listed as listOf } from "../capital.js";
+import { quoted } from "./quote.js";
+import { FIRST_GRANT, FIRST_SIGHT, grantBody, grantGone, grantSentence, NO_GRANT_LEFT, NO_SIGHT_LEFT, peopleKinds, peopleSentence, nounWords, pluralWords as pluralOf, sightGone, sightSentence, sightWords, whoWords } from "./policy-words.js";
 /** The ops, for tool schemas and the guide. */
 export const EDIT_OPS = [
     "add-kind",
@@ -52,6 +54,11 @@ export const EDIT_OPS = [
     "set-home",
     "arrange-pages",
     "set-computed",
+    "set-people",
+    "add-grant",
+    "remove-grant",
+    "add-sight",
+    "remove-sight",
 ];
 /** Words the rule language keeps: a field or relation renamed to one could not be named in a rule. */
 const KEYWORDS = new Set(["and", "or", "not", "in", "where", "true", "false", "null"]);
@@ -150,6 +157,12 @@ const SHAPES = {
         description: z.union([z.string().min(1).max(500), z.null()]).optional(),
     })
         .strict(),
+    // Who the people are, and who may do and see what (FR-170): a grant and a sight as the document holds one.
+    "set-people": z.object({ op: z.literal("set-people"), kind: kindName, people: z.boolean() }).strict(),
+    "add-grant": z.object({ op: z.literal("add-grant") }).passthrough(),
+    "remove-grant": z.object({ op: z.literal("remove-grant") }).passthrough(),
+    "add-sight": z.object({ op: z.literal("add-sight") }).passthrough(),
+    "remove-sight": z.object({ op: z.literal("remove-sight") }).passthrough(),
 };
 const NONE = new Set();
 const clone = (v) => structuredClone(v);
@@ -785,6 +798,13 @@ class Editor {
                 return this.arrangePages(i, e);
             case "set-computed":
                 return this.setComputed(i, e);
+            case "set-people":
+                return this.setPeople(i, e);
+            case "add-grant":
+            case "remove-grant":
+            case "add-sight":
+            case "remove-sight":
+                return this.policyEdit(i, e);
         }
     }
     /** How a record's page orders and groups its facts (FR-148): judged as the compile judges `kinds.<kind>.page`. */
@@ -1136,6 +1156,120 @@ class Editor {
         else
             this.said.push(`${plural}' "${name}" is ${next.label ? `shown as "${next.label}"` : "shown by its name"}${next.description ? `, described as "${next.description}"` : ""}.`);
     }
+    // ── who the people are, and who may do and see what (FR-170) ──
+    /** The last edit that changed the people or the policy: where what they make together is judged. */
+    lastPolicyEdit = -1;
+    failAs(code, i, path, message, fix) {
+        this.findings.push(error(code, `edits.${i}${path ? `.${path}` : ""}`, message, fix));
+    }
+    setPeople(i, e) {
+        const spec = this.kind(i, e.kind);
+        if (!spec)
+            return;
+        this.lastPolicyEdit = i;
+        const already = (spec.people === true) === e.people;
+        if (e.people && !already) {
+            // Exactly one kind is the people: a principal's id is a record of it, never of one of two.
+            const other = peopleKinds(this.doc.kinds)[0];
+            if (other)
+                return this.failAs("people-ambiguous", i, "kind", `${pluralOf(this.doc.kinds, other)} are already the people who sign in, and an app has one kind for them`, `{"op": "set-people", "kind": "${other}", "people": false} first, in the same change`);
+            spec.people = true;
+        }
+        else if (!e.people)
+            delete spec.people;
+        this.said.push(peopleSentence(this.doc.kinds, e.kind, e.people, already));
+    }
+    /** A grant or a sight as the document holds one, or undefined having said why not. */
+    policyPart(i, e, sight) {
+        const { op: _op, ...rest } = e;
+        const parsed = (sight ? SightSpec : GrantSpec).safeParse(rest);
+        if (!parsed.success)
+            return void this.refuse(i, parsed.error.issues, sight ? "a sight" : "a grant");
+        return parsed.data;
+    }
+    policyEdit(i, e) {
+        const sight = e.op === "add-sight" || e.op === "remove-sight";
+        const part = this.policyPart(i, e, sight);
+        if (!part)
+            return;
+        this.lastPolicyEdit = i;
+        if (e.op === "remove-grant" || e.op === "remove-sight")
+            return this.removePolicyPart(i, part, sight);
+        // What it names is the app's: its kinds, and a grant's acts (a kind's derived edit and remove among them).
+        if (!sight && Array.isArray(part.kinds) && part.kinds.length === 0)
+            return this.fail(i, "kinds", "a grant on no kind gives nothing", "leave kinds out for every kind, or name the kinds it is on");
+        for (const [n, kind] of (Array.isArray(part.kinds) ? part.kinds : []).entries()) {
+            if (!this.doc.kinds[kind])
+                return this.failAs(sight ? "sight-kind" : "edit", i, `kinds.${n}`, `"${kind}" is not a kind this app has; it has ${Object.keys(this.doc.kinds).join(", ")}`);
+        }
+        if (!sight && part.mutations !== "*") {
+            for (const [n, act] of part.mutations.entries()) {
+                const derived = /^(?:edit|remove)-(.+)$/.exec(act);
+                if (this.doc.acts?.[act] || (derived && this.doc.kinds[derived[1]]))
+                    continue;
+                return this.failAs("grant-act", i, `mutations.${n}`, `"${act}" is not an act this app has`, `one of ${[...Object.keys(this.doc.acts ?? {}), ...Object.keys(this.doc.kinds).flatMap((kind) => [`edit-${kind}`, `remove-${kind}`])].join(", ")}`);
+            }
+        }
+        const said = [];
+        // A role the app has not declared becomes one of its roles, where it declares them.
+        if (Array.isArray(this.doc.roles) && part.roles !== "*") {
+            for (const role of part.roles) {
+                if (this.doc.roles.includes(role))
+                    continue;
+                this.doc.roles.push(role);
+                said.push(`${capitalize(whoWords([role]))} is a new role.`);
+            }
+        }
+        if (!this.doc.policy) {
+            // No policy permits everything; a sight alone would take every act away, so its policy says everyone may still do them.
+            const everything = { roles: "*", mutations: "*" };
+            this.doc.policy = { grants: sight ? [everything] : [] };
+            said.push(FIRST_GRANT, ...(sight ? [grantSentence(this.doc, everything)] : []));
+        }
+        if (sight) {
+            if (!this.doc.policy.sees?.length)
+                said.push(FIRST_SIGHT);
+            (this.doc.policy.sees ??= []).push(part);
+            said.push(sightSentence(this.doc, part));
+        }
+        else {
+            this.doc.policy.grants.push(part);
+            said.push(grantSentence(this.doc, part));
+        }
+        this.said.push(...said);
+    }
+    /**
+     * A GRANT OR A SIGHT, NAMED BY WHAT IT SAYS. A chat names one the way it
+     * would say it — "the grant that lets everyone take back a vote" — so a
+     * removal names it by its keys: roles and acts (or kinds) in any order,
+     * and any other key it gives must match too. Never by its place in the
+     * list, which another change can move.
+     */
+    removePolicyPart(i, part, sight) {
+        const list = (sight ? this.doc.policy?.sees : this.doc.policy?.grants) ?? [];
+        const sameSet = (a, b) => a === b || (Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x) => b.includes(x)));
+        const keys = sight ? ["own", "via"] : ["kinds", "self", "ownEnd", "describe"];
+        const matches = list.filter((one) => sameSet(one.roles, part.roles) &&
+            (sight ? sameSet(one.kinds, part.kinds) : sameSet(one.mutations, part.mutations)) &&
+            keys.every((key) => part[key] === undefined || (typeof part[key] === "boolean" ? (one[key] ?? false) === part[key] : key === "kinds" ? sameSet(one[key] ?? "*", part[key]) : one[key] === part[key])));
+        const what = sight ? "sight" : "grant";
+        const say = (one) => (sight ? `${whoWords(one.roles)} ${sightWords(this.doc, one)}` : grantBody(this.doc, one));
+        if (matches.length === 0) {
+            const there = list.map(say);
+            return this.fail(i, "", `no ${what} ${sight ? "shows" : "says"} ${say(part)}${there.length ? `; the ${what}s ${sight ? "show" : "say"} ${there.length > 1 ? `${there.slice(0, -1).join("; ")}; and ${there.at(-1)}` : there[0]}` : `; the app has no ${what}s`}`);
+        }
+        if (matches.length > 1)
+            return this.fail(i, "", `${matches.length} ${what}s ${sight ? "show" : "say"} ${say(part)}`, `say ${sight ? "own or via" : "ownEnd, self, kinds or describe"} as the one to remove says them`);
+        const gone = matches[0];
+        list.splice(list.indexOf(gone), 1);
+        this.said.push(sight ? sightGone(this.doc, gone) : grantGone(this.doc, gone));
+        if (sight && list.length === 0) {
+            delete this.doc.policy.sees;
+            this.said.push(NO_SIGHT_LEFT);
+        }
+        else if (!sight && list.length === 0)
+            this.said.push(NO_GRANT_LEFT);
+    }
     // ── kinds ──
     addKind(i, e) {
         const { op: _op, kind, act, ...rest } = e;
@@ -1228,6 +1362,11 @@ class Editor {
             return;
         if (Object.keys(this.doc.kinds).length === 1)
             return this.fail(i, "kind", "an app keeps at least one kind");
+        // The last sight gone would show everyone everything, every other kind included: the policy's to change first, as a relation a sight reads is.
+        const sees = this.doc.policy?.sees ?? [];
+        if (sees.length > 0 && sees.every((sight) => sight.kinds.every((k) => k === kind))) {
+            return this.fail(i, "kind", `every sight shows only ${pluralWords(this.doc, kind)}, so with them gone everyone would see everything`, `remove those sights first, in the same change ({"op": "remove-sight", …}), which says so`);
+        }
         const gone = [];
         /*
          * The relations it declares go with it — and so does what walks them
@@ -1262,8 +1401,8 @@ class Editor {
         for (const [name, act] of Object.entries(this.doc.acts ?? {})) {
             const on = asArray(act.on);
             if (act.creates === kind || (act.effects ?? []).some((x) => x.create === kind) || (on.includes(kind) && on.length === 1)) {
+                gone.push(titled("act", name, act));
                 this.removeActQuietly(name);
-                gone.push(`act ${name}`);
             }
             else if (on.includes(kind))
                 act.on = on.filter((k) => k !== kind);
@@ -1271,7 +1410,7 @@ class Editor {
         for (const [name, rule] of Object.entries(this.doc.rules ?? {})) {
             if (rule.over === kind || exprMentions(this.doc, rule.when, rule.over === "graph" ? NONE : new Set([rule.over]), { t: "kind", from: kind, to: "\u0000" }) || exprMentions(this.doc, rule.require, rule.over === "graph" ? NONE : new Set([rule.over]), { t: "kind", from: kind, to: "\u0000" })) {
                 delete this.doc.rules[name];
-                gone.push(`rule ${name}`);
+                gone.push(titled("rule", name, rule));
             }
         }
         if (this.doc.views?.[kind] && !Array.isArray(this.doc.views[kind])) {
@@ -1279,9 +1418,21 @@ class Editor {
             if (Object.keys(this.doc.views).length === 0)
                 delete this.doc.views;
         }
-        for (const g of this.doc.policy?.grants ?? [])
-            if (Array.isArray(g.kinds))
-                g.kinds = g.kinds.filter((k) => k !== kind);
+        /*
+         * A grant no longer names the kind, nor its derived edit and remove; one
+         * left naming no kind or no act gives nothing, and goes, as a grant does
+         * whose last act is removed — kept, it read as a grant on every kind.
+         */
+        if (this.doc.policy) {
+            const derived = [`edit-${kind}`, `remove-${kind}`];
+            this.doc.policy.grants = this.doc.policy.grants.flatMap((g) => {
+                const kinds = Array.isArray(g.kinds) ? g.kinds.filter((k) => k !== kind) : g.kinds;
+                const mutations = Array.isArray(g.mutations) ? g.mutations.filter((m) => !derived.includes(m) || this.doc.acts?.[m]) : g.mutations;
+                if ((Array.isArray(g.kinds) && g.kinds.length > 0 && kinds.length === 0) || (Array.isArray(mutations) && mutations.length === 0))
+                    return [];
+                return [{ ...g, ...(kinds !== undefined ? { kinds } : {}), mutations }];
+            });
+        }
         if (this.doc.policy?.sees) {
             this.doc.policy.sees = this.doc.policy.sees.map((s) => ({ ...s, kinds: s.kinds.filter((k) => k !== kind) })).filter((s) => s.kinds.length > 0);
             if (this.doc.policy.sees.length === 0)
@@ -1319,7 +1470,7 @@ class Editor {
         for (const f of [...this.fills])
             if (f.kind === kind)
                 this.fills.splice(this.fills.indexOf(f), 1);
-        this.said.push(`The ${kind} kind is removed, and every ${kind} with it${gone.length ? `; so are ${listOf(gone)}` : ""}.`);
+        this.said.push(`The ${kind} kind is removed, and every ${kind} with it${gone.length ? `; so ${gone.length === 1 ? "is" : "are"} ${listOf(gone)}` : ""}.`);
     }
     // ── fields ──
     addField(i, e) {
@@ -1679,7 +1830,7 @@ class Editor {
                 continue;
             const kept = rule.repairs.filter((r) => r.act !== act);
             if (kept.length !== rule.repairs.length)
-                gone.push(`the "${rule.repairs.find((r) => r.act === act)?.label ?? act}" repair of rule ${name}`);
+                gone.push(`the "${rule.repairs.find((r) => r.act === act)?.label ?? act}" repair of ${titled("rule", name, rule)}`);
             if (kept.length > 0)
                 rule.repairs = kept;
             else
@@ -2035,14 +2186,14 @@ class Editor {
                 }
             }
             if (uses) {
-                gone.push(`act ${name}`, ...this.removeActQuietly(name));
+                gone.push(titled("act", name, act), ...this.removeActQuietly(name));
             }
         }
         for (const [name, rule] of Object.entries(doc.rules ?? {})) {
             const ctx = rule.over === "graph" ? NONE : new Set([rule.over]);
             if (exprMentions(doc, rule.when, ctx, r) || exprMentions(doc, rule.require, ctx, r) || templateMentions(doc, rule.says, ctx, r)) {
                 delete doc.rules[name];
-                gone.push(`rule ${name}`);
+                gone.push(titled("rule", name, rule));
             }
         }
         if (doc.rules && Object.keys(doc.rules).length === 0)
@@ -2242,6 +2393,70 @@ class Editor {
         return said;
     }
 }
+/** What the people and the policy make together, as `graview check` judges it (`checkPeople`), said over the document. */
+function peopleProblems(doc, at) {
+    const out = [];
+    const kinds = doc.kinds;
+    const people = peopleKinds(kinds);
+    const policy = doc.policy;
+    const reads = policy?.sees?.some((sight) => sight.via !== undefined) ? "a sight via a relation" : policy?.grants.some((grant) => grant.ownEnd) ? "a grant held to a person's own end of a link" : undefined;
+    if (people.length === 0 && reads)
+        out.push(error("people-unsaid", at, `${reads} reads each person's own record, and no kind is the people who sign in`, '{"op": "set-people", "kind": "<the kind whose records are the people>", "people": true}'));
+    for (const sight of policy?.sees ?? []) {
+        const via = sight.via;
+        if (via === undefined)
+            continue;
+        const from = Object.keys(kinds).filter((kind) => kinds[kind].edges?.[via]);
+        if (from.length === 0) {
+            out.push(error("sight-via-unknown-edge", at, `no kind has a relation ${quoted(via)}, so a sight via it shows nothing`, `name a relation that joins ${listOf(sight.kinds.map((kind) => pluralOf(kinds, kind)))} to the people`));
+            continue;
+        }
+        if (people.length === 0)
+            continue;
+        const reaches = (target) => from.some((kind) => {
+            const to = kinds[kind].edges[via].to;
+            return to === "*" || to.includes(target);
+        });
+        for (const kind of sight.kinds) {
+            if ((from.includes(kind) && people.some(reaches)) || (people.some((one) => from.includes(one)) && reaches(kind)))
+                continue;
+            out.push(error("sight-via-misses-people", at, `${quoted(via)} never joins ${pluralOf(kinds, kind)} to ${pluralOf(kinds, people[0])}, so the sight shows no ${nounOf(doc, kind)} to anyone`, `name a relation between ${nounOf(doc, kind)} and ${nounOf(doc, people[0])}, or say own: true`));
+        }
+    }
+    for (const grant of policy?.grants ?? []) {
+        if (!grant.ownEnd)
+            continue;
+        if (grant.mutations === "*") {
+            out.push(error("grant-own-end-without-link", at, "a grant held to a person's own end of a link names every act, and most link nothing", "name the acts it holds: the ones that connect or sever"));
+            continue;
+        }
+        for (const name of grant.mutations) {
+            const ends = linkEnds(doc.acts?.[name]);
+            if (ends === "far")
+                continue;
+            const title = quoted(doc.acts?.[name]?.title ?? name);
+            out.push(ends === "near"
+                ? error("grant-own-end-without-link", at, `${title} takes no record at the other end of what it links, so a grant held to a person's own end of it is never met`, 'take the record at its far end as an argument, or say "$me" there and drop ownEnd')
+                : error("grant-own-end-without-link", at, `${title} connects and severs nothing, so a grant held to a person's own end of a link has no end to hold`, "hold it with self: true for the subject, or name an act that connects or severs"));
+        }
+    }
+    return out;
+}
+/** Whether an act links, and whether it takes the record at the far end of a link as an argument: "far", "near" (only its subject, "$me" or what it made) or "none". */
+function linkEnds(act) {
+    if (!act)
+        return "none";
+    if (act.connects || act.severs)
+        return "far";
+    const own = new Set(["subject", "me", "new", ...(act.effects ?? []).flatMap((e) => (e.create && e.as ? [e.as] : []))]);
+    const links = (act.effects ?? []).filter((e) => e.connect || e.sever);
+    if (links.length === 0)
+        return "none";
+    return links.some((e) => [e.from, e.to].some((end) => {
+        const ref = refName(end);
+        return ref !== undefined && !own.has(ref);
+    })) ? "far" : "near";
+}
 /** A `$name` reference or bare argument name in a guard, renamed (for an argument that followed its field). */
 function rewriteBinding(source, from, to) {
     try {
@@ -2263,7 +2478,6 @@ function swapToken(name, from, to) {
     }
     return name;
 }
-const listOf = (xs) => (xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`);
 /** Map every block of a view, nested ones included; a block mapped to null is dropped. */
 function mapBlocks(blocks, f) {
     const out = [];
@@ -2284,13 +2498,12 @@ function mapBlocks(blocks, f) {
     return out;
 }
 // ── words for what changed ───────────────────────────────────────────────────
+/** An act or a rule that goes with something, as a person reads it: 'the act "Draw a match"', by its id only when it has no title. */
+const titled = (what, name, spec) => `the ${what} "${spec.title ?? name}"`;
 const withA = (noun) => `${/^[aeiou]/i.test(noun) ? "an" : "a"} ${noun}`;
-const nounOf = (doc, kind) => doc.kinds[kind]?.noun ?? words(kind);
+const nounOf = (doc, kind) => nounWords(doc.kinds, kind);
 /** A kind's plural as a person reads it: "packages", "people and teams". */
-function pluralWords(doc, kind) {
-    const plural = doc.kinds[kind]?.plural;
-    return plural ? plural.charAt(0).toLowerCase() + plural.slice(1) : `${words(kind)}s`;
-}
+const pluralWords = (doc, kind) => pluralOf(doc.kinds, kind);
 /** The kinds a lens binds, for saying where it stands. */
 function kindsBound(lens) {
     const bindings = lens["bindings"];
@@ -2545,6 +2758,20 @@ export function editDocument(document, edits, options = {}) {
     });
     if (editor.findings.length > 0)
         return { ok: false, findings: editor.findings };
+    /*
+     * WHAT THE PEOPLE AND THE POLICY MAKE TOGETHER, judged once the change is
+     * whole (FR-170): moving the people from one kind to another is two edits,
+     * and the first alone leaves a sight reading nobody. What the change made
+     * wrong is refused at its last such edit; what was wrong before is not
+     * this change's to answer for.
+     */
+    if (editor.lastPolicyEdit >= 0) {
+        const at = `edits.${editor.lastPolicyEdit}`;
+        const before = new Set(peopleProblems(current, at).map((finding) => finding.message));
+        const made = peopleProblems(editor.doc, at).filter((finding) => !before.has(finding.message));
+        if (made.length > 0)
+            return { ok: false, findings: made };
+    }
     /*
      * THE TOOL INTERFACE MOVED, AND SAYS SO (FR-34). A derived act is named for
      * its kind and asks for its fields by name, so a rename changes what an