@graview/core 0.1.27 → 0.1.29

package/dist/import/rows.js

@@ -0,0 +1,584 @@
+import { isArchived } from "../graph/archived.js";
+import { nameKey } from "../labels.js";
+import { mintId, slug } from "../mutations/define-mutation.js";
+import { nodeRefArgs } from "../mutations/node-ref.js";
+import { article, counted, fieldWords, labelOf, nounOf, pluralOf } from "../schema/define-node.js";
+import { edgeWords, valueWords } from "../schema/value-words.js";
+import { actingAs } from "../permissions/policy.js";
+import { FIELD_SIGHT } from "../permissions/sight.js";
+import { seesEveryRecord } from "../seen.js";
+import { problemsMoved } from "../store.js";
+import { andList, coerceCell, orList, splitCell } from "./coerce.js";
+import { ImportMappingError, readMapping, fieldSpecFor } from "./mapping.js";
+/** Cells that mean "nothing here" in a column of numbers, dates or choices. */
+const BLANK = new Set(["n/a", "na", "-", "—", "–", "null", "none", "tbd", "?"]);
+const isBlank = (value) => value === undefined || value === null || (typeof value === "string" && value.trim().length === 0);
+/** Says what a row would do: preview `importRows`. */
+export function previewImport(store, kind, rows, mapping, options) {
+    return importRows(store, kind, rows, mapping, { ...options, preview: true });
+}
+export function importRows(store, kind, rows, mapping, options) {
+    const schema = store.schema;
+    const by = options.by;
+    // A field the importer may not see is one it may not fill: its column is refused as one naming no field (Roadmap f-field-sight).
+    const columns = readMapping(schema, kind, mapping, FIELD_SIGHT.keptFrom?.(store, by)?.({ id: "\u0000new", kind }));
+    const definition = schema.definition(kind);
+    const noun = nounOf(definition, kind);
+    const preview = options.preview === true;
+    const { header, records } = tabulate(rows);
+    const absent = columns.filter((column) => !header.includes(column.column)).map((column) => `No column is called ${column.column}.`);
+    if (absent.length > 0 && records.length > 0)
+        throw new ImportMappingError(absent);
+    const ignored = header.filter((column) => !columns.some((one) => one.column === column));
+    const forbidden = policyRefusal(store, kind, noun, by);
+    /** The importer's own view: what a one-to-one link already holds is judged by what they see (FR-55). */
+    const seen = store.seenBy(by);
+    const mayLink = linking(store, by);
+    const taken = new Set();
+    /** The rows planned so far, by their label's key: a later row may link to one. */
+    const plannedByName = new Map();
+    /** Far records whose one link of a relation this import has already given. */
+    const filled = new Set();
+    const outcomes = [];
+    const planned = [];
+    const say = sentences(preview);
+    /**
+     * The links a row makes from or to the record `id` — a new one, or under
+     * `match` one already there (`existing`): a link it already has is no
+     * change, and the one link of a relation to one that it holds to another
+     * record is replaced — said where the importer sees it, taken quietly
+     * where they do not (FR-55).
+     */
+    const linksFor = (id, cells, existing) => {
+        const reasons = [];
+        const links = [];
+        const edges = [];
+        /** Links a hidden record held that a one-to-one link this row makes takes, as an act's `setSingleSource` takes them (FR-55). */
+        const replaced = [];
+        /** Links of a relation to one the importer sees, which the row's link replaces. */
+        const severed = [];
+        for (const column of columns) {
+            if (column.as !== "relation")
+                continue;
+            const raw = cells[column.column];
+            if (isBlank(raw))
+                continue;
+            const text = String(raw).trim();
+            const named = column.direction === "out" && column.one ? [text] : namesIn(store, column, text, by);
+            if (column.direction === "out" && column.one && named.length > 1) {
+                reasons.push(`${column.column} names ${named.length}, and ${article(noun)} ${noun} links to one`);
+                continue;
+            }
+            for (const name of named) {
+                const found = resolve(store, column, name, by, plannedByName);
+                if (!found.ok) {
+                    reasons.push(found.why);
+                    continue;
+                }
+                if (found.id === id) {
+                    reasons.push(`it names itself under ${column.column}`);
+                    continue;
+                }
+                const edge = column.direction === "out" ? { kind: column.relation, from: id, to: found.id } : { kind: column.relation, from: found.id, to: id };
+                if (edges.some((one) => one.kind === edge.kind && one.from === edge.from && one.to === edge.to))
+                    continue;
+                // The record already holds it: nothing to make.
+                if (existing && seen.graph.out(edge.from, edge.kind).some((one) => one.id === edge.to))
+                    continue;
+                // Made by the acts that make such a link, as a press on one would be: a grant's kinds, its own end, an agent's `may`.
+                const refusal = mayLink(column.relation, found.id, found.kind);
+                if (refusal) {
+                    reasons.push(refusal);
+                    continue;
+                }
+                if (column.direction === "in" && column.one) {
+                    const holds = seen.graph.out(found.id, column.relation).length > 0 || filled.has(`${column.relation} ${found.id}`);
+                    if (holds) {
+                        reasons.push(`${found.label} already has its one “${edgeWords(schema, found.kind, column.relation, "out")}”`);
+                        continue;
+                    }
+                    // One the importer may not see holds it: taken, and said to nobody, as an act setting a single source takes it.
+                    replaced.push(...store.graph.outEdges(found.id, column.relation));
+                }
+                if (existing && column.direction === "out" && column.one) {
+                    // The one it had goes: said where the importer sees it, taken quietly where they do not.
+                    for (const held of store.graph.outEdges(id, column.relation))
+                        (seen.graph.getNode(held.to) ? severed : replaced).push(held);
+                }
+                edges.push(edge);
+                links.push({ relation: column.relation, direction: column.direction, id: found.id, label: found.label });
+            }
+        }
+        return { reasons, links, edges, replaced, severed };
+    };
+    const match = options.match === undefined ? undefined : matcher(store, seen, definition, kind, options.match, header, columns, options.dayFirst === true);
+    /** Records rows above already change, by id, and the row that does. */
+    const changing = new Map();
+    const editAct = store.allMutations().find((mutation) => mutation.derived?.kind === kind && mutation.derived.act === "edit");
+    const updated = [];
+    for (const { row, cells } of records) {
+        if (forbidden && !match) {
+            outcomes.push({ row, made: false, action: "refuse", links: [], refused: [forbidden], sentence: say.refused(row, [forbidden]) });
+            continue;
+        }
+        const reasons = [];
+        const fields = {};
+        for (const column of columns) {
+            if (column.as !== "field")
+                continue;
+            const raw = cells[column.column];
+            if (isBlank(raw))
+                continue;
+            const loose = column.spec.type !== "string" && column.spec.type !== "text" && column.spec.type !== "boolean";
+            if (loose && typeof raw === "string" && BLANK.has(raw.trim().toLowerCase()))
+                continue;
+            const read = coerceCell(column.spec, raw, column.column, {
+                ...(options.dayFirst ? { dayFirst: true } : {}),
+                optionWords: (option) => valueWords(definition, column.field, option),
+            });
+            if (!read.ok) {
+                reasons.push(read.why);
+                continue;
+            }
+            const fits = column.schema.safeParse(read.value);
+            if (!fits.success) {
+                reasons.push(`“${String(raw).trim()}” under ${column.column} does not fit: ${fits.error?.issues?.[0]?.message ?? "the field refuses it"}`);
+                continue;
+            }
+            fields[column.field] = fits.data;
+        }
+        /*
+         * THE RECORD THE ROW ALREADY IS, under `match`: found, the row changes
+         * it — only what the row has — rather than making a second one.
+         */
+        if (match) {
+            const found = match(cells, fields, row, plannedByName);
+            if (found.why) {
+                outcomes.push({ row, made: false, action: "refuse", links: [], refused: [...reasons, found.why], sentence: say.refused(row, [...reasons, found.why]) });
+                continue;
+            }
+            if (found.node) {
+                const node = found.node;
+                const label = labelOf(definition, node) || node.id;
+                const before = changing.get(node.id);
+                if (before !== undefined)
+                    reasons.push(`row ${before} above already changes ${label}`);
+                const changes = [];
+                for (const [field, value] of Object.entries(fields)) {
+                    // The value it was found by, written as the sheet spells it, is the same value: no change.
+                    if (same(node[field], value) || (found.by === field && typeof value === "string" && typeof node[field] === "string" && nameKey(value) === nameKey(node[field])))
+                        continue;
+                    changes.push({ field, from: node[field], to: value });
+                    if (!(editAct?.writes ?? []).includes(field))
+                        reasons.push(`${fieldWords(definition, field)} is not something “${editAct?.title ?? `Change the ${noun}`}” changes, so a sheet cannot change it`);
+                }
+                if (reasons.length === 0 && changes.length > 0) {
+                    try {
+                        schema.parseNode({ ...node, ...fields });
+                    }
+                    catch (error) {
+                        reasons.push(...issuesSaid(definition, error));
+                    }
+                    const verdict = store.permits({ name: editAct.name, args: { id: node.id, ...Object.fromEntries(changes.map((change) => [change.field, change.to])) } }, by);
+                    if (!verdict.ok)
+                        reasons.push(verdict.refusal.message);
+                }
+                const linked = linksFor(node.id, cells, true);
+                reasons.push(...linked.reasons);
+                if (reasons.length > 0) {
+                    outcomes.push({ row, made: false, action: "refuse", links: [], refused: reasons, sentence: say.refused(row, reasons) });
+                    continue;
+                }
+                changing.set(node.id, row);
+                for (const edge of linked.edges)
+                    if (edge.to === node.id)
+                        filled.add(`${edge.kind} ${edge.from}`);
+                const changed = changes.length > 0 || linked.edges.length > 0;
+                if (changed)
+                    updated.push({ id: node.id, label, changes, links: linked.links, edges: linked.edges, severed: linked.severed, replaced: linked.replaced });
+                const words = changes.map((change) => `${fieldWords(definition, change.field)}: ${valueSaid(definition, change.field, change.from)} → ${valueSaid(definition, change.field, change.to)}`);
+                outcomes.push({ row, made: false, action: changed ? "change" : "leave", id: node.id, label, fields, changes, links: linked.links, refused: [], sentence: changed ? say.changed(row, label, words, linked.links) : say.left(row, label) });
+                continue;
+            }
+            if (forbidden) {
+                outcomes.push({ row, made: false, action: "refuse", links: [], refused: [forbidden], sentence: say.refused(row, [forbidden]) });
+                continue;
+            }
+        }
+        const shape = definition.fields.shape ?? {};
+        for (const field of Object.keys(shape)) {
+            if (fields[field] !== undefined)
+                continue;
+            if (definition.defaults && Object.hasOwn(definition.defaults, field)) {
+                fields[field] = definition.defaults[field];
+                continue;
+            }
+            const spec = fieldSpecFor(definition, field)?.spec;
+            if (!spec?.required)
+                continue;
+            const mapped = columns.find((column) => column.as === "field" && column.field === field);
+            // A reason of its own only where the cell was blank: a cell that could not be read has said so already.
+            if (mapped && !isBlank(cells[mapped.column]))
+                continue;
+            reasons.push(`it has no ${fieldWords(definition, field)}, which every ${noun} needs`);
+        }
+        if (reasons.length === 0) {
+            try {
+                Object.assign(fields, withoutIds(schema.parseNode({ ...fields, id: "import", kind })));
+            }
+            catch (error) {
+                reasons.push(...issuesSaid(definition, error));
+            }
+        }
+        const label = labelFor(definition, kind, fields, row);
+        const id = reasons.length === 0 ? mint(store, seen, by, taken, kind, label) : `import:${row}`;
+        const { links, edges, replaced } = (() => {
+            const linked = linksFor(id, cells, false);
+            reasons.push(...linked.reasons);
+            return linked;
+        })();
+        if (reasons.length > 0) {
+            outcomes.push({ row, made: false, action: "refuse", links: [], refused: reasons, sentence: say.refused(row, reasons) });
+            continue;
+        }
+        taken.add(id);
+        for (const edge of edges)
+            if (edge.to === id)
+                filled.add(`${edge.kind} ${edge.from}`);
+        const key = nameKey(label);
+        plannedByName.set(key, [...(plannedByName.get(key) ?? []), { id, kind, label }]);
+        planned.push({ node: { ...fields, id, kind }, edges, replaced, label });
+        outcomes.push({ row, made: true, action: "make", id, label, fields, links, refused: [], sentence: say.made(row, label, links) });
+    }
+    const made = planned.length;
+    const changed = updated.length;
+    const unchanged = outcomes.filter((one) => one.action === "leave").length;
+    const linked = [...planned, ...updated].reduce((sum, one) => sum + one.edges.length, 0);
+    const refused = outcomes.length - made - changed - unchanged;
+    const result = { kind, rows: outcomes, made, changed, unchanged, linked, refused, ignored, sentence: say.totals(outcomes.length, counted(schema, kind, made), linked, refused, match ? { changed, unchanged } : undefined) };
+    if (preview || made + changed === 0)
+        return { ...result, kept: false };
+    const batchIntent = options.intent ?? (changed === 0 ? `Import ${counted(schema, kind, made)}` : made === 0 ? `Change ${counted(schema, kind, changed)} from a sheet` : `Import ${counted(schema, kind, made)} and change ${changed}`);
+    const via = options.via ?? "import";
+    /** The edits, through the kind's own edit act; and the links a found record gains, beside them in the batch. */
+    const edits = updated.filter((one) => one.changes.length > 0).map((one) => ({ name: editAct.name, args: { id: one.id, ...Object.fromEntries(one.changes.map((change) => [change.field, change.to])) } }));
+    const relinked = updated.filter((one) => one.edges.length > 0).map((one) => ({
+        primitives: [...[...one.severed, ...one.replaced].map((edge) => ({ op: "remove-edge", edge })), ...one.edges.map((edge) => ({ op: "add-edge", edge }))],
+        author: options.by,
+        intent: `Link ${one.label} to ${andList(one.links.map((link) => link.label))}`,
+        batchIntent,
+        via,
+    }));
+    const appended = planned.map((one) => ({
+        primitives: [{ op: "add-node", node: one.node }, ...one.edges.map((edge) => ({ op: "add-edge", edge })), ...one.replaced.map((edge) => ({ op: "remove-edge", edge }))],
+        author: options.by,
+        intent: `Add ${article(noun)} ${noun}: ${one.label}`,
+        batchIntent,
+        via,
+    }));
+    const patches = updated.filter((one) => one.changes.length > 0).map((one) => ({
+        primitives: [{ op: "patch-node", id: one.id, before: Object.fromEntries(one.changes.map((change) => [change.field, change.from])), after: Object.fromEntries(one.changes.map((change) => [change.field, change.to])) }],
+        author: options.by,
+        intent: `Change ${one.label}`,
+        batchIntent,
+        via,
+    }));
+    if (options.admit) {
+        const at = store.log.length;
+        const ops = [...patches, ...appended, ...relinked].map((one, index) => ({
+            id: `import:${index + 1}`,
+            seq: at + index,
+            batch: options.batch ?? "import",
+            mutation: null,
+            inverse: [...one.primitives].reverse(),
+            reads: [],
+            writes: [...new Set(one.primitives.map((primitive) => ("node" in primitive ? primitive.node.id : primitive.op === "add-edge" ? primitive.edge.from : "")))],
+            at: "",
+            ...one,
+        }));
+        const size = store.graph.size;
+        const taken = planned.reduce((sum, one) => sum + one.replaced.length, 0) + updated.reduce((sum, one) => sum + one.replaced.length + one.severed.length, 0);
+        options.admit({
+            ops,
+            primitives: [...patches, ...appended, ...relinked].flatMap((one) => one.primitives),
+            added: { nodes: made, edges: linked },
+            removed: { nodes: 0, edges: taken },
+            changed: { nodes: edits.length },
+            nodesAfter: size.nodes + made,
+            edgesAfter: size.edges + linked - taken,
+        });
+    }
+    const before = store.violations();
+    /*
+     * ONE BATCH, ONE UNDO. The edits go through the store's own path — the
+     * edit act's checks, its sentence, the policy asked again — and what the
+     * rows make and link is appended under the same batch after them.
+     */
+    const edited = edits.length > 0 ? store.applyAll(edits, { author: options.by, via, intent: batchIntent, ...(options.batch === undefined ? {} : { batch: options.batch }) }).ops : [];
+    const batch = edited[0]?.batch ?? options.batch;
+    const rest = [...appended, ...relinked];
+    const ops = [...edited, ...(rest.length > 0 ? store.append(rest, batch === undefined ? {} : { batch }) : [])];
+    const { introduces } = problemsMoved(store.allInvariants(), before, store.violations());
+    return { ...result, kept: true, batch: ops[0].batch, ops, introduces };
+}
+/** The header and the record rows, each numbered as the sheet numbers it, blank rows left out. */
+function tabulate(rows) {
+    if (rows.length === 0)
+        return { header: [], records: [] };
+    if (Array.isArray(rows[0])) {
+        const header = rows[0].map((cell) => String(cell ?? "").trim());
+        const records = rows.slice(1).flatMap((cells, index) => {
+            const list = cells;
+            if (list.every(isBlank))
+                return [];
+            return [{ row: index + 2, cells: Object.fromEntries(header.map((column, at) => [column, list[at]])) }];
+        });
+        return { header, records };
+    }
+    const header = [];
+    for (const row of rows)
+        for (const column of Object.keys(row))
+            if (!header.includes(column))
+                header.push(column);
+    const records = rows.flatMap((cells, index) => (Object.values(cells).every(isBlank) ? [] : [{ row: index + 2, cells: { ...cells } }]));
+    return { header, records };
+}
+/**
+ * Why this importer may not add the kind at all, or nothing. Asked of the
+ * acts that create it — who may bring one into being by hand may bring
+ * one in from a sheet — as the store asks them, the agent's `may` and the
+ * policy's grants alike. A kind no act creates is the host's to import
+ * where no policy is declared, and nobody's where one is.
+ */
+function policyRefusal(store, kind, noun, by) {
+    if (store.modules.disabledKinds.has(kind))
+        return `${capital(store.schema.tryDefinition(kind)?.plural ?? `${noun}s`)} belong to a module this workspace has turned off.`;
+    const creators = store.allMutations().filter((mutation) => !mutation.derived && (mutation.creates ?? []).includes(kind));
+    if (creators.length === 0)
+        return store.policy === undefined && by.kind !== "agent" ? undefined : `Nothing in this app adds ${article(noun)} ${noun}, so none can be imported.`;
+    let first;
+    for (const creator of creators) {
+        const verdict = store.permits({ name: creator.name, args: {} }, by);
+        if (verdict.ok)
+            return undefined;
+        first ??= verdict.refusal.message;
+    }
+    return first;
+}
+const capital = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+/** The names one cell gives: the whole cell when it names a record, else its parts. */
+function namesIn(store, column, text, by) {
+    const whole = store.resolveRef({ name: column.column, kinds: column.kinds }, text, by);
+    if (whole.ok)
+        return [text];
+    const parts = splitCell(text);
+    return parts.length > 1 ? parts : [text];
+}
+/** A name, resolved as an act resolves it, under the importer's sight; failing that, among the rows this import makes. */
+function resolve(store, column, name, by, planned) {
+    const found = store.resolveRef({ name: column.column, kinds: column.kinds }, name, by);
+    if (found.ok)
+        return { ok: true, id: found.id, label: found.label, kind: String(store.graph.getNode(found.id).kind) };
+    if (found.reason === "ambiguous") {
+        const labels = [...new Set(found.candidates.map((candidate) => candidate.label))];
+        return { ok: false, why: `“${name}” under ${column.column} could be ${labels.length <= 5 ? orList(labels) : `any of ${labels.length} records`}` };
+    }
+    const here = (planned.get(nameKey(name)) ?? []).filter((one) => column.kinds.includes(one.kind));
+    if (here.length === 1)
+        return { ok: true, ...here[0] };
+    if (here.length > 1)
+        return { ok: false, why: `“${name}” under ${column.column} could be any of the ${here.length} rows above it so called` };
+    const nouns = [...new Set(column.kinds.map((one) => nounOf(store.schema.tryDefinition(one), one)))];
+    return { ok: false, why: `no ${nouns.length <= 3 ? orList(nouns) : "record"} is called “${name}”` };
+}
+/** What the record will be called: its kind's label, else its first words, else the row. */
+function labelFor(definition, kind, fields, row) {
+    /*
+     * A kind's label reads its own fields — `(node) => node.label`, as every
+     * scaffolded kind's does — and a sheet need not hold them: an inspection
+     * is named by the act that makes it, not by a column. Said nothing, or
+     * thrown, it is named the way a row with no name is (W-196).
+     */
+    let said;
+    try {
+        said = labelOf(definition, { id: "", kind, ...fields });
+    }
+    catch {
+        said = undefined;
+    }
+    if (typeof said === "string" && said.trim().length > 0)
+        return said.trim();
+    const words = Object.values(fields).find((value) => typeof value === "string" && value.trim().length > 0);
+    return words?.trim() ?? `${nounOf(definition, kind)} from row ${row}`;
+}
+/**
+ * An id as the importer's own act's `freshId` would mint it: `<kind>:<label>`,
+ * numbered past one they see — and, for a kind they may not see every record
+ * of, their own (FR-55), so the id says nothing of a record kept from them.
+ */
+function mint(store, seen, by, taken, kind, label) {
+    return mintId(`${kind}:${slug(label)}`, {
+        seen: (id) => seen.graph.has(id) || taken.has(id),
+        held: (id) => store.graph.has(id) || taken.has(id),
+        limited: !seesEveryRecord(store, by)(kind),
+        me: actingAs(by).id,
+    });
+}
+/**
+ * WHETHER THE IMPORTER MAY MAKE A LINK, asked of the acts that make links of
+ * its relation (their `connects`) as a press on one would be: the record at
+ * the far end handed to the argument that takes it, so a grant's kinds, a
+ * `self` grant, an own-end grant and an agent's `may` all answer as they
+ * would. Where no policy is declared a person may link anything, as they may
+ * make anything; where one is, a relation no act makes is linked by nobody.
+ * Answers the refusal in words, or undefined.
+ */
+function linking(store, by) {
+    const asked = new Map();
+    return (relation, far, farKind) => {
+        const key = `${relation}\u0000${far}`;
+        if (asked.has(key))
+            return asked.get(key);
+        let answer;
+        if (store.policy !== undefined || by.kind === "agent") {
+            const linkers = store.allMutations().filter((mutation) => !mutation.derived && (mutation.connects ?? []).includes(relation));
+            if (linkers.length === 0) {
+                if (store.policy !== undefined)
+                    answer = `nothing in this app links ${linkWords(store, relation, farKind)} that way, so none can be imported`;
+            }
+            else {
+                for (const linker of linkers) {
+                    const subject = linker.subject?.arg;
+                    const takes = (kinds) => kinds.includes("*") || kinds.includes(farKind);
+                    const refs = nodeRefArgs(linker.input);
+                    const at = refs.find((ref) => ref.name !== subject && takes(ref.kinds))?.name ?? (subject !== undefined && refs.some((ref) => ref.name === subject && takes(ref.kinds)) ? subject : undefined);
+                    const verdict = store.permits({ name: linker.name, args: at === undefined ? {} : { [at]: far } }, by);
+                    if (verdict.ok) {
+                        answer = undefined;
+                        break;
+                    }
+                    answer ??= verdict.refusal.message;
+                }
+            }
+        }
+        asked.set(key, answer);
+        return answer;
+    };
+}
+/** "a vendor to a tag": the two ends of a relation, as a sentence says them. */
+function linkWords(store, relation, farKind) {
+    const owner = store.schema.definitions.find((definition) => Object.hasOwn((definition.edges ?? {}), relation));
+    const far = nounOf(store.schema.tryDefinition(farKind), farKind);
+    if (!owner)
+        return `anything to ${article(far)} ${far}`;
+    const near = nounOf(owner, owner.kind);
+    return `${article(near)} ${near} to ${article(far)} ${far}`;
+}
+function withoutIds(node) {
+    const { id: _id, kind: _kind, ...fields } = node;
+    return fields;
+}
+/** A parse's issues, each by the field's words. */
+function issuesSaid(definition, error) {
+    const issues = error.issues;
+    if (!issues || issues.length === 0)
+        return [error instanceof Error ? error.message : String(error)];
+    return issues.map((issue) => {
+        const field = typeof issue.path?.[0] === "string" ? issue.path[0] : undefined;
+        return field ? `${fieldWords(definition, field)} does not fit: ${issue.message ?? "the field refuses it"}` : (issue.message ?? "it does not fit");
+    });
+}
+function sentences(preview) {
+    const rows = (n) => `${n} ${n === 1 ? "row" : "rows"}`;
+    const links = (n) => `${n} ${n === 1 ? "link" : "links"}`;
+    return {
+        made: (row, label, linked) => `Row ${row} ${preview ? "would make" : "made"} ${label}${linked.length > 0 ? `, linked to ${andList(linked.map((link) => link.label))}` : ""}.`,
+        changed: (row, label, words, linked) => `Row ${row} ${preview ? "would change" : "changed"} ${label}${words.length > 0 ? ` (${words.join("; ")})` : ""}${linked.length > 0 ? `, ${words.length > 0 ? "and links it" : "linking it"} to ${andList(linked.map((link) => link.label))}` : ""}.`,
+        left: (row, label) => `Row ${row} ${preview ? "would leave" : "left"} ${label} as is.`,
+        refused: (row, reasons) => `Row ${row} ${preview ? "would be" : "was"} refused: ${reasons.join("; ")}${/[.!?]$/.test(reasons.at(-1) ?? "") ? "" : "."}`,
+        totals: (count, made, linked, refused, matched) => `${capital(rows(count))}: ${made} ${preview ? "would be made" : "made"}` +
+            (matched && matched.changed > 0 ? `, ${matched.changed} ${preview ? "would be changed" : "changed"}` : "") +
+            (matched && matched.unchanged > 0 ? `, ${matched.unchanged} ${preview ? "would be left as is" : "left as is"}` : "") +
+            `${linked > 0 ? `, with ${links(linked)}` : ""}${refused > 0 ? `; ${rows(refused)} ${preview ? "would be" : refused === 1 ? "was" : "were"} refused` : ""}.`,
+    };
+}
+/** The same value, as a record holds it and as a row reads it. */
+const same = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
+/** A value as a sentence says it: a choice by its words, nothing as "nothing". */
+function valueSaid(definition, field, value) {
+    if (value === undefined || value === null || value === "")
+        return "nothing";
+    if (typeof value === "string")
+        return fieldSpecFor(definition, field)?.spec.type === "enum" ? (valueWords(definition, field, value) ?? value) : value;
+    if (Array.isArray(value))
+        return value.map((one) => valueSaid(definition, field, one)).join(", ");
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+/**
+ * HOW A ROW FINDS ITS RECORD (`ImportOptions.match`): by what the row would
+ * call it, or by one column's value against one field, among the live
+ * records of the kind the importer sees. Two that answer are said rather
+ * than guessed between; an archived one says so, and is not changed; a row
+ * that names one a row above makes is said too, rather than made twice.
+ */
+function matcher(store, seen, definition, kind, match, header, columns, dayFirst) {
+    const noun = nounOf(definition, kind);
+    const plural = pluralOf(store.schema, kind).toLowerCase();
+    if (match !== "label") {
+        const problems = [];
+        if (!header.includes(match.column))
+            problems.push(`No column is called ${match.column}, which the import matches by.`);
+        if (!fieldSpecFor(definition, match.field))
+            problems.push(`The import matches by “${match.field}”, which ${article(noun)} ${noun} has no field called.`);
+        if (problems.length > 0)
+            throw new ImportMappingError(problems);
+    }
+    const records = seen.graph.nodesOfKind(kind, { archived: "all" });
+    const keyOf = (value) => (typeof value === "string" ? nameKey(value) : JSON.stringify(value));
+    const named = (node) => labelOf(definition, node) || node.id;
+    return (cells, fields, row, planned) => {
+        let wanted;
+        let said;
+        if (match === "label") {
+            // What the row would call the record: nothing it says, nothing to find.
+            if (Object.keys(fields).length === 0)
+                return {};
+            wanted = labelFor(definition, kind, fields, row);
+            said = String(wanted);
+        }
+        else {
+            const raw = cells[match.column];
+            if (isBlank(raw))
+                return {};
+            const mapped = columns.find((column) => column.as === "field" && column.column === match.column && column.field === match.field);
+            if (mapped) {
+                if (fields[match.field] === undefined)
+                    return {};
+                wanted = fields[match.field];
+            }
+            else {
+                const read = coerceCell(fieldSpecFor(definition, match.field).spec, raw, match.column, { ...(dayFirst ? { dayFirst: true } : {}) });
+                if (!read.ok)
+                    return { why: read.why };
+                wanted = read.value;
+            }
+            said = String(raw).trim();
+        }
+        const key = keyOf(wanted);
+        const found = records.filter((node) => keyOf(match === "label" ? named(node) : node[match.field]) === key);
+        const live = found.filter((node) => !isArchived(node));
+        if (live.length === 1) {
+            const node = live[0];
+            const by = match === "label" ? Object.keys(fields).find((field) => typeof node[field] === "string" && nameKey(node[field]) === key) : match.field;
+            return { node, ...(by ? { by } : {}) };
+        }
+        if (live.length > 1)
+            return { why: `${live.length} ${plural} answer to “${said}”, and a row changes one` };
+        if (found.length > 0)
+            return { why: `${named(found[0])} is archived; bring it back first, and the row will change it` };
+        if (match === "label" && (planned.get(nameKey(said)) ?? []).some((one) => one.kind === kind))
+            return { why: `a row above already makes ${said}` };
+        return {};
+    };
+}
+//# sourceMappingURL=rows.js.map