@graview/core 0.1.53 → 0.1.55

package/dist/document/edit.js

@@ -14,9 +14,13 @@ const refusedFormat = (format, type) => {
     return `${sentence}; ${fix}`;
 };
 import { farEnd } from "./far-end.js";
+import { jobFindings, jobWorldOfDocument } from "../job-findings.js";
+import { JobSpec } from "./purpose-spec.js";
+import { aliasWord, documentAliasFindings } from "../alias-findings.js";
+import { withArticle } from "../schema/define-node.js";
 import { linkedRelationFindings } from "./linked-relation-findings.js";
 import { linkedRelationOfSpec, reachesAnotherApp } from "../schema/linked.js";
-import { ActSpec, EDGE_NAME, EdgeSpec, FIELD_NAME, FIELD_TYPES, FieldSpec, GrantSpec, KindSpec, NAME, RuleSpec, SightSpec, } from "./schema.js";
+import { ActSpec, ALIAS, MOST_ALIASES, EDGE_NAME, EdgeSpec, FIELD_NAME, FIELD_TYPES, FieldSpec, GrantSpec, KindSpec, NAME, RuleSpec, SightSpec, } from "./schema.js";
 import { SHIPPED_LENSES, isShippedLens, SHIPPED_LENS_NAMES, unknownLensOption, viewReference } from "../places.js";
 import { LENSES_THAT_LIST, listsRecords } from "../lenses-that-list.js";
 import { placeSlug, VIEW_REFERENCE } from "../views/types.js";
@@ -24,7 +28,7 @@ import { documentListFields, kindListFindings, kindListWords, listGroup, listSor
 import { computedOf, validateComputed } from "./computed.js";
 import { parseTemplate, templateBraces, TemplateError } from "./template-parse.js";
 import { validateViews, VIEW_SLOTS } from "./views.js";
-import { brandFindings, emojiIconSentence, subtitleSentence } from "./brand-check.js";
+import { brandFindings, emojiIconSentence, groundWords, subtitleSentence } from "./brand-check.js";
 import { darkLogoSentence, logoParts } from "./logo.js";
 import { emojiOf } from "../theme/marks.js";
 import { canonicalize } from "./canonical.js";
@@ -33,6 +37,7 @@ import { isRecord as isObject, respellDocument } from "./respell.js";
 import { refName } from "./compiled.js";
 import { localeSentence, timeZoneSentence } from "./diff.js";
 import { accentProblem } from "../theme/accent.js";
+import { groundProblem } from "../theme/ground-check.js";
 import { pageFieldFindings, pageNames, renamedOnPage, withoutOnPage } from "./page-fields.js";
 import { capitalize, listed as listOf } from "../capital.js";
 import { quoted } from "./quote.js";
@@ -81,6 +86,12 @@ export const EDIT_OPS = [
     "remove-grant",
     "add-sight",
     "remove-sight",
+    "set-purpose",
+    "add-job",
+    "edit-job",
+    "remove-job",
+    "add-alias",
+    "set-aliases",
 ];
 /** 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"]);
@@ -101,6 +112,7 @@ function buildShapes() {
     const edgeName = z.string().regex(EDGE_NAME, 'relation names are one camelCase word, like "tendedBy"');
     const actName = z.string().regex(NAME, 'act names are lower-case words joined by hyphens, like "mark-paid"');
     const lensTitle = z.string().min(1).max(80);
+    const jobName = z.string().regex(NAME, 'job names are lower-case words joined by hyphens, like "unbooked-soon"');
     return {
         "add-kind": z.object({ op: z.literal("add-kind"), kind: kindName, act: z.boolean().optional() }).passthrough(),
         "rename-kind": z.object({ op: z.literal("rename-kind"), kind: kindName, to: kindName, noun: z.string().min(1).max(40).optional(), plural: z.string().min(1).max(40).optional() }).strict(),
@@ -126,6 +138,8 @@ function buildShapes() {
             .object({
             op: z.literal("set-brand"),
             accent: z.union([z.string(), z.null()]).optional(),
+            // The page background (Roadmap f-brand-ground): one color, or one for each scheme; null for Graview's.
+            ground: z.union([z.string(), z.object({ light: z.string().optional(), dark: z.string().optional() }).strict(), z.null()]).optional(),
             name: z.union([z.string().min(1).max(60), z.null()]).optional(),
             currency: z.union([z.string(), z.null()]).optional(),
             locale: z.union([z.string(), z.null()]).optional(),
@@ -226,6 +240,28 @@ function buildShapes() {
         "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(),
+        // Who the app is for, in words (Roadmap f-app-jobs); null takes the sentence away.
+        "set-purpose": z.object({ op: z.literal("set-purpose"), for: z.union([z.string().min(1).max(300), z.null()]) }).strict(),
+        // A job as the document holds one (`purpose.jobs[]`), placed at `at` or last.
+        "add-job": z.object({ op: z.literal("add-job"), job: z.record(z.string(), z.unknown()), at: z.number().int().min(0).optional() }).strict(),
+        // A job by its name, each key given set, null clearing an optional one.
+        "edit-job": z
+            .object({
+            op: z.literal("edit-job"),
+            name: jobName,
+            ask: z.string().min(1).max(200).optional(),
+            kind: kindName.optional(),
+            where: z.union([z.string().min(1).max(2000), z.null()]).optional(),
+            sort: z.union([listKey, z.object({ by: listKey, direction: listDirection }).strict(), z.null()]).optional(),
+            act: z.union([actName, z.null()]).optional(),
+            roles: z.union([z.array(z.string().regex(NAME)).min(1).max(40), z.null()]).optional(),
+        })
+            .strict(),
+        "remove-job": z.object({ op: z.literal("remove-job"), name: jobName }).strict(),
+        // Another word people use for a kind, or for one of its fields (Roadmap f-learned-suggestions).
+        "add-alias": z.object({ op: z.literal("add-alias"), kind: kindName, field: fieldName.optional(), alias: z.string().min(1).max(40) }).strict(),
+        // All of a kind's or a field's other words at once; null or [] takes them away.
+        "set-aliases": z.object({ op: z.literal("set-aliases"), kind: kindName, field: fieldName.optional(), aliases: z.union([z.array(z.string().min(1).max(40)).max(MOST_ALIASES), z.null()]) }).strict(),
     };
 }
 let shapes;
@@ -538,7 +574,8 @@ class Editor {
      * set, null clears it, and what it does not name stays as it was. Each
      * is judged as `graview check` judges it — a mark that could act or load,
      * a face off the list — and an accent that does not read as given is
-     * refused with the pair, the ratio and a shade that would (FR-126).
+     * refused with the pair, the ratio and a shade that would (FR-126), as
+     * is a ground that ink, muted ink or the accent would not read on.
      */
     setBrand(i, e) {
         const brand = clone(this.doc.brand ?? {});
@@ -566,6 +603,24 @@ class Editor {
             brand["accent"] = e.accent;
             this.said.push(`The app's accent color becomes ${e.accent}.`);
         }
+        if (e.ground === null) {
+            if (brand["ground"] !== undefined)
+                this.said.push("The app's page background goes back to Graview's.");
+            delete brand["ground"];
+        }
+        else if (e.ground !== undefined) {
+            const accent = brand["accent"];
+            const refused = groundProblem(e.ground, accent);
+            const fixed = (ground, also = "") => `{"op": "set-brand", "ground": ${JSON.stringify(ground).replace(/","/g, '", "').replace(/":"/g, '": "')}${also}}`;
+            if (refused)
+                return this.fail(i, "ground", refused.sentence, refused.suggestion ? fixed(typeof e.ground === "string" ? refused.suggestion : { ...e.ground, [refused.scheme]: refused.suggestion }) : "pick a lighter color for the light scheme, a darker one for the dark");
+            // The accent the app keeps is judged on the new ground as it was on the old (FR-126).
+            const unread = accent ? accentProblem(accent, e.ground) : null;
+            if (unread)
+                return this.fail(i, "ground", unread.sentence, unread.suggestion ? fixed(e.ground, `, "accent": "${unread.suggestion}"`) : "pick another ground, or another accent");
+            brand["ground"] = e.ground;
+            this.said.push(groundWords(e.ground));
+        }
         if (e.currency === null) {
             delete brand["currency"];
             this.said.push("Money is said with no currency.");
@@ -924,7 +979,144 @@ class Editor {
             case "add-sight":
             case "remove-sight":
                 return this.policyEdit(i, e);
+            case "set-purpose":
+                return this.setPurpose(e);
+            case "add-job":
+                return this.addJob(i, e);
+            case "edit-job":
+                return this.editJob(i, e);
+            case "remove-job":
+                return this.removeJob(i, e.name);
+            case "add-alias":
+                return this.setAliases(i, e.kind, e.field, [...this.aliasesOf(e.kind, e.field), e.alias], e.alias);
+            case "set-aliases":
+                return this.setAliases(i, e.kind, e.field, e.aliases ?? []);
+        }
+    }
+    // ── other words for a kind or a field (Roadmap f-learned-suggestions) ──
+    aliasesOf(kind, field) {
+        const spec = this.doc.kinds[kind];
+        return (field ? spec?.fields?.[field]?.aliases : spec?.aliases) ?? [];
+    }
+    /**
+     * A kind's or a field's aliases, as words people search with: lower case,
+     * each once. Refused, in the checker's words, when one is not a word or is
+     * what something else in the app is already called. `added` is the one
+     * word `add-alias` gave, said alone.
+     */
+    setAliases(i, kind, field, given, added) {
+        const spec = this.kind(i, kind);
+        if (!spec)
+            return;
+        const target = field ? this.field(i, kind, field) : spec;
+        if (!target)
+            return;
+        const said = [...new Set(given.map(aliasWord))];
+        const at = added === undefined ? "aliases" : "alias";
+        for (const [n, word] of said.entries())
+            if (!ALIAS.test(word))
+                return this.fail(i, added === undefined ? `aliases.${n}` : at, `"${word}" is not a word people search with: one to three words of letters and digits`, 'like "supplier" or "wedding venue"');
+        if (said.length > MOST_ALIASES)
+            return this.fail(i, at, `at most ${MOST_ALIASES} other words for one ${field ? "field" : "kind"}`);
+        const before = target.aliases;
+        if (said.length === 0)
+            delete target.aliases;
+        else
+            target.aliases = said;
+        const wrong = documentAliasFindings(this.doc).filter((finding) => finding.path.startsWith(`kinds.${kind}${field ? `.fields.${field}` : ""}.aliases`));
+        if (wrong.length > 0) {
+            if (before === undefined)
+                delete target.aliases;
+            else
+                target.aliases = before;
+            return this.fail(i, at, wrong[0].message, wrong[0].fix);
         }
+        const whose = field ? `${kind}'s ${field}` : withArticle(spec.noun ?? words(kind));
+        if (added !== undefined)
+            this.said.push(`Search and the seat take “${aliasWord(added)}” as another word for ${whose}.`);
+        else
+            this.said.push(said.length === 0 ? `${capitalize(whose)} has no other words now.` : `Other words for ${whose}: ${listOf(said.map((word) => `“${word}”`))}.`);
+    }
+    // ── who the app is for, and what they come to do (Roadmap f-app-jobs) ──
+    setPurpose(e) {
+        const purpose = { ...(this.doc.purpose ?? {}) };
+        if (e.for === null)
+            delete purpose.for;
+        else
+            purpose.for = e.for;
+        this.keepPurpose(purpose);
+        this.said.push(e.for === null ? "The app no longer says whom it is for." : `The app says it is for ${quotedAtTheEnd(e.for)}`);
+    }
+    /** The purpose as it now stands, or none when it says nothing. */
+    keepPurpose(purpose) {
+        if (Array.isArray(purpose.jobs) && purpose.jobs.length === 0)
+            delete purpose.jobs;
+        if (Object.keys(purpose).length === 0)
+            delete this.doc.purpose;
+        else
+            this.doc.purpose = purpose;
+    }
+    /** The job a name names, or -1 having said why. */
+    jobIndex(i, name) {
+        const jobs = this.doc.purpose?.jobs ?? [];
+        const index = jobs.findIndex((job) => job.name === name);
+        if (index < 0)
+            this.fail(i, "name", `there is no job "${name}"${jobs.length > 0 ? `; the jobs are ${jobs.map((job) => `"${job.name}"`).join(", ")}` : ""}`);
+        return index;
+    }
+    /** A job placed among the others, judged as `graview check` judges it (`job-*`): kept only when nothing is wrong with it. */
+    placeJob(i, job, at, replacing) {
+        const jobs = [...(this.doc.purpose?.jobs ?? [])];
+        if (replacing)
+            jobs[at] = job;
+        else
+            jobs.splice(at, 0, job);
+        const wrong = jobFindings({ ...this.doc.purpose, jobs }, jobWorldOfDocument(this.doc)).filter((finding) => finding.index === at || (finding.code === "jobs-too-many" && !replacing) || (finding.code === "job-name-taken" && jobs[finding.index ?? -1]?.name === job.name));
+        for (const finding of wrong)
+            this.failAs(finding.code, i, finding.code === "jobs-too-many" ? "" : `job.${finding.key ?? ""}`, finding.message, finding.fix);
+        if (wrong.length > 0)
+            return false;
+        this.keepPurpose({ ...(this.doc.purpose ?? {}), jobs });
+        return true;
+    }
+    addJob(i, e) {
+        const parsed = JobSpec.safeParse(e.job);
+        if (!parsed.success)
+            return this.refuse(i, parsed.error.issues.map((issue) => ({ ...issue, path: ["job", ...issue.path] })), "a job");
+        const job = parsed.data;
+        const jobs = this.doc.purpose?.jobs ?? [];
+        if (!this.placeJob(i, job, Math.min(e.at ?? jobs.length, jobs.length), false))
+            return;
+        this.said.push(`A new job, ${quoted(job.ask)}: ${jobWords(this.doc, job)}.`);
+    }
+    editJob(i, e) {
+        const index = this.jobIndex(i, e.name);
+        if (index < 0)
+            return;
+        const job = { ...this.doc.purpose.jobs[index] };
+        const changed = ["ask", "kind", "where", "sort", "act", "roles"].filter((key) => e[key] !== undefined);
+        if (changed.length === 0)
+            return this.fail(i, "", "an edit-job names at least one of ask, kind, where, sort, act or roles to change", `{"op": "edit-job", "name": "${e.name}", "ask": "…"}`);
+        for (const key of changed) {
+            if (e[key] === null) {
+                if (key === "ask" || key === "kind")
+                    return this.fail(i, key, `a job always has its ${key}`);
+                delete job[key];
+            }
+            else
+                job[key] = e[key];
+        }
+        if (!this.placeJob(i, job, index, true))
+            return;
+        this.said.push(`The job "${job.name}", ${quoted(job.ask)}, is now ${jobWords(this.doc, job)}.`);
+    }
+    removeJob(i, name) {
+        const index = this.jobIndex(i, name);
+        if (index < 0)
+            return;
+        const [job] = this.doc.purpose.jobs.splice(index, 1);
+        this.keepPurpose({ ...this.doc.purpose });
+        this.said.push(`The job "${job.name}" (${quotedAtTheEnd(job.ask)}) is removed.`);
     }
     /** How a record's page orders and groups its facts (FR-148): judged as the compile judges `kinds.<kind>.page`. */
     setPageFields(i, e) {
@@ -2068,7 +2260,7 @@ class Editor {
                     gone.push(...this.dropComputed(other, name));
             }
         }
-        gone.push(...this.pruneViews(swept), ...this.pruneLenses(swept));
+        gone.push(...this.pruneViews(swept), ...this.pruneLenses(swept), ...this.pruneJobs(swept));
         // The arrangement names kinds (FR-80): a kind that is gone is no longer ordered or hidden, nor where the app opens.
         if (this.doc.pages) {
             for (const part of ["order", "hide", "primary"]) {
@@ -2534,6 +2726,13 @@ class Editor {
             else
                 delete rule.repairs;
         }
+        // A job asks the same question without it: only what people do next is let go.
+        for (const job of (this.doc.purpose?.jobs ?? [])) {
+            if (job.act !== act)
+                continue;
+            delete job.act;
+            gone.push(`what the job "${job.name}" does next`);
+        }
         return gone;
     }
     addRule(i, e) {
@@ -2563,6 +2762,9 @@ class Editor {
             for (const r of rule.repairs ?? [])
                 if (r.act === from)
                     r.act = to;
+        for (const job of (this.doc.purpose?.jobs ?? []))
+            if (job.act === from)
+                job.act = to;
     }
     // ── every place a name is said ──
     /**
@@ -2814,8 +3016,46 @@ class Editor {
             if (JSON.stringify(doc.pages) !== before)
                 touched.push("the pages");
         }
+        // Jobs (Roadmap f-app-jobs): what each is answered by, what its where reads, what it sorts by and the act it names.
+        for (const job of (doc.purpose?.jobs ?? [])) {
+            const before = JSON.stringify(job);
+            if (job.where !== undefined)
+                job.where = exprAt(job.where, new Set([job.kind]));
+            const by = typeof job.sort === "string" ? job.sort : job.sort?.by;
+            if (r.t === "field" && job.kind === r.kind && by === r.from)
+                job.sort = typeof job.sort === "string" ? r.to : { ...job.sort, by: r.to };
+            if (r.t === "kind" && job.kind === r.from)
+                job.kind = r.to;
+            if (job.act !== undefined && r.t === "kind")
+                job.act = renamedAct(job.act, r.from, r.to);
+            if (job.act !== undefined && (r.t === "kind" || r.t === "edge"))
+                job.act = renamedRelationAct(job.act, doc.kinds, r);
+            if (JSON.stringify(job) !== before)
+                touched.push(`the job "${job.name}"`);
+        }
         return touched;
     }
+    /** Jobs that can no longer be answered as asked go — a where that reads what is going, a kind that is gone — and an order by it is let go. */
+    pruneJobs(r) {
+        const purpose = this.doc.purpose;
+        if (!purpose?.jobs)
+            return [];
+        const gone = [];
+        purpose.jobs = purpose.jobs.filter((job) => {
+            if ((r.t === "kind" && job.kind === r.from) || exprMentions(this.doc, job.where, new Set([job.kind]), r)) {
+                gone.push(`the job "${job.name}"`);
+                return false;
+            }
+            const by = typeof job.sort === "string" ? job.sort : job.sort?.by;
+            if (r.t === "field" && job.kind === r.kind && by === r.from) {
+                delete job.sort;
+                gone.push(`the order of the job "${job.name}"`);
+            }
+            return true;
+        });
+        this.keepPurpose({ ...purpose });
+        return gone;
+    }
     /**
      * Remove what mentions a field or relation that is going: acts that write or walk
      * it, rules that judge it, view blocks that show it; templates that show it fall
@@ -2912,6 +3152,7 @@ class Editor {
             delete doc.rules;
         gone.push(...this.pruneViews(r));
         gone.push(...this.pruneLenses(r));
+        gone.push(...this.pruneJobs(r));
         return gone;
     }
     /** Computed fields being dropped, so a cycle among them ends. */
@@ -3116,6 +3357,16 @@ class Editor {
         return said;
     }
 }
+/** How a job is answered, in words: "answered by the vendors where status != 'booked', sorted by due, then book". */
+function jobWords(doc, job) {
+    const sort = typeof job.sort === "string" ? { by: job.sort, direction: "asc" } : job.sort;
+    return [
+        `answered by the ${pluralWords(doc, job.kind).toLowerCase()}${job.where ? ` where ${job.where}` : ""}`,
+        ...(sort ? [`sorted by ${sort.by}${sort.direction === "desc" ? ", highest first" : ""}`] : []),
+        ...(job.act ? [`then "${job.act}"`] : []),
+        ...(job.roles ? [`for ${listOf(job.roles)}`] : []),
+    ].join(", ");
+}
 /** What the people and the policy make together, as `graview check` judges it (`checkPeople`), said over the document. */
 function peopleProblems(doc, at) {
     const out = [];