canopycms 0.12.0 → 0.13.0

package/dist/merge/entry-merge.js

@@ -0,0 +1,876 @@
+/**
+ * Three-way merge of one entry, field by field: the version the branch started from (ancestor),
+ * the base branch's version now (base), and the branch's own (branch). A value changed on one side
+ * takes that change; a value changed alike on both takes it once; a value changed differently on
+ * both is a conflict, and the merged entry holds the branch's value there until a person chooses.
+ *
+ * Pure and client-safe. Schema-light: the input is the RAW parsed data (`parseEntryParts`), never
+ * filtered by a schema, so a key the schema doesn't know merges like any other and a base's schema
+ * migration survives. The schema, when given, only names conflicts as the "Show changes" drawer
+ * names its changes.
+ */
+import { ITEM_KEY, isItemKey, itemKeysAsRead } from '../item-keys.js';
+import { findBodyFieldName } from '../utils/body-field.js';
+import { entryAsRead } from '../utils/calendar-day.js';
+import { parseMarkdownBody } from '../utils/markdown-parse.js';
+import { isPlainRecord } from '../validation/field-traversal.js';
+import { describePath } from './conflict-path.js';
+import { diff3Regions } from './diff3.js';
+import { alignToAncestor, isNewIdentity, mergeOrder, pairNewItems } from './list-alignment.js';
+import { mergeText } from './text-merge.js';
+import { exactToken, isEmptyValue, sameValue, valueToken } from './value-equality.js';
+const ROOT = {
+    segments: [],
+    places: { o: [], a: [], b: [] },
+    placeTrail: [],
+    trail: [],
+    branchKeys: [],
+    item: false,
+    asRead: { a: undefined, b: undefined },
+};
+/** `places` one step on: `step` gives each side's segment, or none where that side lacks it. */
+const placesOn = (places, step) => {
+    const on = (side) => {
+        const segment = step(side);
+        const place = places[side];
+        return place && segment ? [...place, segment] : undefined;
+    };
+    return { o: on('o'), a: on('a'), b: on('b') };
+};
+const child = (at, segment, versions) => {
+    const inside = (v) => 'field' in segment && isPlainRecord(v) ? member(v, segment.field) : undefined;
+    const places = placesOn(at.places, () => segment);
+    return {
+        segments: [...at.segments, segment],
+        places,
+        placeTrail: [...at.placeTrail, places],
+        trail: [...at.trail, versions],
+        branchKeys: at.branchKeys,
+        item: false,
+        asRead: { a: inside(at.asRead.a), b: inside(at.asRead.b) },
+    };
+};
+/** `record`'s own member `name`: never one it inherits, and `__proto__` as a member. */
+const member = (record, name) => Object.getOwnPropertyDescriptor(record, name)?.value;
+/** Sets `name` as an own member, so `__proto__` is a member like any other. */
+const setMember = (record, name, value) => {
+    Object.defineProperty(record, name, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+};
+const isRecordList = (value) => Array.isArray(value) && value.every(isPlainRecord);
+/** A list of plain values (tags): no records or lists inside, which merge only as a whole. */
+const isPlainList = (value) => Array.isArray(value) && !value.some((v) => isPlainRecord(v) || Array.isArray(v));
+const asList = (value) => (Array.isArray(value) ? value : []);
+const usableKey = (item) => isPlainRecord(item) && isItemKey(item[ITEM_KEY]) ? item[ITEM_KEY] : undefined;
+const versions = (o, a, b) => ({
+    ...(o !== undefined && { ancestor: o }),
+    ...(a !== undefined && { base: a }),
+    ...(b !== undefined && { branch: b }),
+});
+/** A block item whose template one side changed: the whole item is one value. */
+const templateChanged = (o, a, b) => {
+    const discriminator = (v, key) => (isPlainRecord(v) ? v[key] : undefined);
+    return ['template', '_type'].some((key) => discriminator(o, key) !== discriminator(a, key) ||
+        discriminator(o, key) !== discriminator(b, key));
+};
+const kindOf = (a, b) => isEmptyValue(a) ? 'removed-on-base' : isEmptyValue(b) ? 'removed-by-you' : 'changed';
+function conflict(o, a, b, at, walk) {
+    walk.conflicts.push({
+        at: at.segments,
+        places: at.places,
+        placeTrail: at.placeTrail,
+        trail: at.trail,
+        kind: kindOf(a, b),
+        ...(at.item && { item: true }),
+        ...versions(o, a, b),
+    });
+}
+/**
+ * Records and lists always merge member by member and item by item, even where two sides compare
+ * equal: equality ignores item keys, and taking one side's whole record or list would drop the
+ * keys the other side's items carry, and the comment threads anchored on them.
+ */
+function mergeValue(o, a, b, at, walk) {
+    const absentOrEmpty = o === undefined || isEmptyValue(o);
+    if (isPlainRecord(a) && isPlainRecord(b) && (isPlainRecord(o) || absentOrEmpty)) {
+        if (!(at.item && templateChanged(o, a, b)))
+            return mergeRecord(o, a, b, at, walk);
+    }
+    else if (isRecordList(a) && isRecordList(b) && (isRecordList(o) || absentOrEmpty)) {
+        const merged = mergeList(o, a, b, at, walk);
+        if (merged)
+            return merged;
+    }
+    return mergeLeaf(o, a, b, at, walk);
+}
+/**
+ * A side left exactly as the ancestor had it yields to the other side, byte for byte, before any
+ * looser equality decides, so `merge(O, A, O)` is A and `merge(O, O, B)` is B.
+ */
+function mergeLeaf(o, a, b, at, walk) {
+    if (exactToken(o) === exactToken(b))
+        return a;
+    if (exactToken(o) === exactToken(a) || sameValue(a, b) || sameValue(o, a))
+        return b;
+    if (sameValue(o, b))
+        return a;
+    const empty = o === undefined || isEmptyValue(o);
+    if (isPlainList(a) && isPlainList(b) && (isPlainList(o) || empty)) {
+        const merged = mergeScalarList(asList(o), a, b);
+        if (merged)
+            return merged;
+    }
+    else if (typeof a === 'string' &&
+        typeof b === 'string' &&
+        (typeof o === 'string' || empty) &&
+        `${typeof o === 'string' ? o : ''}${a}${b}`.includes('\n')) {
+        const merged = mergeText(typeof o === 'string' ? o : '', a, b);
+        if (merged) {
+            const text = {
+                at: at.segments,
+                places: at.places,
+                placeTrail: at.placeTrail,
+                versions: { o, a, b },
+            };
+            if (merged.regions.length > 0) {
+                text.conflict = {
+                    at: at.segments,
+                    places: at.places,
+                    placeTrail: at.placeTrail,
+                    trail: at.trail,
+                    kind: 'changed',
+                    ...versions(o, a, b),
+                    regions: merged.regions,
+                };
+                walk.conflicts.push(text.conflict);
+            }
+            walk.texts.push(text);
+            return merged.text;
+        }
+    }
+    conflict(o, a, b, at, walk);
+    return b;
+}
+/**
+ * diff3 over a list of plain values (tags). Values both sides inserted at the same place are all
+ * kept ({@link insertedByBoth}), since an insertion loses nothing; any other overlap is undefined,
+ * a whole-field conflict.
+ */
+function mergeScalarList(o, a, b) {
+    const lists = { ancestor: o, base: a, branch: b };
+    const [oT, aT, bT] = [o, a, b].map((list) => list.map(valueToken));
+    const regions = diff3Regions(oT, aT, bT);
+    if (!regions)
+        return undefined;
+    const out = [];
+    for (const region of regions) {
+        if (region.stable) {
+            out.push(...lists[region.side].slice(...region.span));
+            continue;
+        }
+        const [aPart, bPart] = [a.slice(...region.base), b.slice(...region.branch)];
+        const [aTokens, bTokens] = [aT.slice(...region.base), bT.slice(...region.branch)];
+        if (aTokens.length === bTokens.length && aTokens.every((t, n) => t === bTokens[n])) {
+            out.push(...bPart);
+        }
+        else if (region.ancestor[0] === region.ancestor[1]) {
+            out.push(...insertedByBoth(aPart, aTokens, bPart, bTokens));
+        }
+        else {
+            return undefined;
+        }
+    }
+    return withoutExtraRepeats(out, a, b);
+}
+/**
+ * `merged` holding each value no more often than the side holding it most: a value both sides
+ * added at different places is one value, at the first place.
+ */
+function withoutExtraRepeats(merged, a, b) {
+    const count = (list) => {
+        const counts = new Map();
+        for (const v of list)
+            counts.set(valueToken(v), (counts.get(valueToken(v)) ?? 0) + 1);
+        return counts;
+    };
+    const [inA, inB] = [count(a), count(b)];
+    const kept = new Map();
+    return merged.filter((v) => {
+        const token = valueToken(v);
+        const n = (kept.get(token) ?? 0) + 1;
+        kept.set(token, n);
+        return n <= Math.max(inA.get(token) ?? 0, inB.get(token) ?? 0);
+    });
+}
+/** True when `x` appears in `y` in order, not necessarily side by side. */
+const isSubsequence = (x, y) => {
+    let n = 0;
+    for (const token of y)
+        if (token === x[n])
+            n++;
+    return n === x.length;
+};
+/**
+ * Values both sides inserted at one place: the side whose insert holds the other's in order,
+ * else the base's then the branch's, each repeat of a base value counted once.
+ */
+function insertedByBoth(aPart, aTokens, bPart, bTokens) {
+    if (isSubsequence(aTokens, bTokens))
+        return [...bPart];
+    if (isSubsequence(bTokens, aTokens))
+        return [...aPart];
+    const fromBase = new Map();
+    for (const token of aTokens)
+        fromBase.set(token, (fromBase.get(token) ?? 0) + 1);
+    const rest = bPart.filter((_, n) => {
+        const left = fromBase.get(bTokens[n]) ?? 0;
+        if (left === 0)
+            return true;
+        fromBase.set(bTokens[n], left - 1);
+        return false;
+    });
+    return [...aPart, ...rest];
+}
+function mergeRecord(o, a, b, at, walk) {
+    const ancestor = isPlainRecord(o) ? o : {};
+    const out = {};
+    for (const name of new Set([...Object.keys(b), ...Object.keys(a), ...Object.keys(ancestor)])) {
+        if (name === ITEM_KEY)
+            continue;
+        const [om, am, bm] = [member(ancestor, name), member(a, name), member(b, name)];
+        const v = mergeValue(om, am, bm, child(at, { field: name }, { o: om, a: am, b: bm }), walk);
+        if (v !== undefined)
+            setMember(out, name, v);
+    }
+    // A list item's key is chosen by its list; any other record's is carried.
+    const key = member(b, ITEM_KEY) ?? member(a, ITEM_KEY);
+    if (!at.item && key !== undefined)
+        setMember(out, ITEM_KEY, key);
+    return out;
+}
+/**
+ * Items are matched across the three versions by identity (`list-alignment.ts`), merged item by
+ * item, and ordered by `mergeOrder`. A matched item takes the base's key, else, when the base
+ * changed it, the key the base's version reads under, else the branch's: the merged file converges
+ * on the base's keys. An item neither side keyed gets no key. An item
+ * removed on one side and changed on the other is an item conflict, and the branch's state holds.
+ */
+function mergeList(o, a, b, at, walk, namedBy) {
+    const O = asList(o);
+    const identities = namedBy === undefined
+        ? identifyByKey(O, a, b, walk.ancestorKeys, walk.movedKeys)
+        : identifyByName(O, a, b, namedBy);
+    // A list too far apart to align in time, or whose items can't all be told apart, is one value.
+    // So is one with an item not clearly new or old, unless the other side holds the ancestor's
+    // items as they were: that side is the ancestor item for item, and the changed side's list is
+    // the merge whichever the item is.
+    if (!identities)
+        return undefined;
+    let { aIds, bIds, aByPlace, bByPlace } = identities;
+    const { oKeys } = identities;
+    if (identities.unsure) {
+        // By place, unless a key the side holds names another ancestor item: alike items reordered.
+        const asAncestor = (side) => side.length === O.length &&
+            sameValue(O, side) &&
+            side.every((item, n) => {
+                const key = usableKey(item);
+                return key === undefined || key === oKeys[n] || !oKeys.includes(key);
+            });
+        if (asAncestor(a))
+            [aIds, aByPlace] = [oKeys, new Set()];
+        else if (asAncestor(b))
+            [bIds, bByPlace] = [oKeys, new Set()];
+        else
+            return undefined;
+    }
+    const readList = (v, raw) => Array.isArray(v) && v.length === raw.length ? v : raw;
+    const [aRead, bRead] = [readList(at.asRead.a, a), readList(at.asRead.b, b)];
+    const [aReadKeys, bReadKeys] = [itemKeysAsRead(aRead), itemKeysAsRead(bRead)];
+    const held = new Set([...a, ...b].flatMap((item) => usableKey(item) ?? []));
+    const index = (ids) => new Map(ids.map((id, n) => [id, n]));
+    const [oAt, aAt, bAt] = [index(oKeys), index(aIds), index(bIds)];
+    // An item kept whole from one side keeps its key, so it claims the key before any merged item
+    // picks one: a merged item never takes a key another item of the merged list holds.
+    const used = new Set();
+    const out = [];
+    const keep = (item) => {
+        const key = usableKey(item);
+        if (key !== undefined)
+            used.add(key);
+        out.push(item);
+    };
+    const keyLater = [];
+    for (const id of mergeOrder(oKeys, aIds, bIds)) {
+        const i = isNewIdentity(id) ? undefined : oAt.get(id);
+        const ja = aAt.get(id);
+        const jb = bAt.get(id);
+        const [oi, ai, bi] = [
+            i === undefined ? undefined : O[i],
+            ja === undefined ? undefined : a[ja],
+            jb === undefined ? undefined : b[jb],
+        ];
+        const itemVersions = { o: oi, a: ai, b: bi };
+        const itemPlaces = placesOn(at.places, (side) => {
+            const index = { o: i, a: ja, b: jb }[side];
+            return index === undefined ? undefined : { index };
+        });
+        const itemAt = {
+            segments: [...at.segments, { index: out.length }],
+            places: itemPlaces,
+            placeTrail: [...at.placeTrail, itemPlaces],
+            trail: [...at.trail, itemVersions],
+            branchKeys: [...at.branchKeys, (jb !== undefined && bReadKeys[jb]) || id],
+            item: true,
+            asRead: {
+                a: ja === undefined ? undefined : aRead[ja],
+                b: jb === undefined ? undefined : bRead[jb],
+            },
+        };
+        if (i !== undefined && ja === undefined && jb === undefined)
+            continue;
+        if (i !== undefined && ja === undefined) {
+            if (sameValue(oi, bi))
+                continue;
+            conflict(oi, ai, bi, itemAt, walk);
+        }
+        else if (i !== undefined && jb === undefined) {
+            if (sameValue(oi, ai))
+                continue;
+            // Named as the drawer names it once the merge lands, comparing the base with the branch:
+            // by the key the base's version reads under.
+            const named = (ja !== undefined && aReadKeys[ja]) || id;
+            conflict(oi, ai, bi, { ...itemAt, segments: [...at.segments, { item: named }] }, walk);
+            continue;
+        }
+        if (ja === undefined || jb === undefined) {
+            keep(ja === undefined ? bi : ai);
+            continue;
+        }
+        // Matched by place alone, it may be another item: one side's change stands whole, two conflict.
+        const placeOnly = aByPlace.has(ja) || bByPlace.has(jb);
+        if (placeOnly && !sameValue(ai, bi)) {
+            const [aChanged, bChanged] = [!sameValue(oi, ai), !sameValue(oi, bi)];
+            if (aChanged && bChanged)
+                conflict(oi, ai, bi, itemAt, walk);
+            // The base's item stands in the branch's place: the branch's threads follow it there.
+            const from = bReadKeys[jb];
+            if (aChanged && !bChanged && from !== undefined && !walk.ambiguous(at.branchKeys, from)) {
+                walk.pendingRemaps.push({ at: itemAt.segments, within: at.branchKeys, from });
+            }
+            keep(aChanged && !bChanged ? ai : bi);
+            continue;
+        }
+        const merged = mergeValue(oi, ai, bi, itemAt, walk);
+        // A keyless item the base changed takes the key the base's version reads under, which the
+        // next sync's ancestor names it by, never the branch's read key for content it no longer has.
+        // Never onto a key another item of either version holds as its own, nor for a branch key that
+        // names items in two lists alike: a remap could not tell them apart (see Walk.ambiguous).
+        const baseKey = aReadKeys[ja];
+        const rekey = oi !== undefined &&
+            usableKey(bi) !== undefined &&
+            !sameValue(oi, ai) &&
+            baseKey !== undefined &&
+            (!held.has(baseKey) || baseKey === usableKey(bi)) &&
+            (bReadKeys[jb] === undefined || !walk.ambiguous(at.branchKeys, bReadKeys[jb]));
+        const keys = { base: rekey ? baseKey : undefined, branchRead: bReadKeys[jb] };
+        const place = out.push(merged) - 1;
+        keyLater.push(() => {
+            const keyed = withListKey(merged, ai, bi, keys, used, at, walk);
+            // An item left with no key reads under a hash of its merged content: the branch's threads
+            // follow it there, once the merged entry reads.
+            if (usableKey(keyed) === undefined &&
+                keys.branchRead !== undefined &&
+                !walk.ambiguous(at.branchKeys, keys.branchRead)) {
+                walk.pendingRemaps.push({
+                    at: itemAt.segments,
+                    within: at.branchKeys,
+                    from: keys.branchRead,
+                });
+            }
+            out[place] = keyed;
+        });
+    }
+    for (const key of keyLater)
+        key();
+    return out;
+}
+function identifyByKey(O, a, b, inEntry, moved) {
+    const oKeys = itemKeysAsRead(O).map((key, i) => key ?? `${i}`);
+    const aligned = alignToAncestor(a, O, oKeys, 'a', inEntry, moved.a, b);
+    const bAligned = alignToAncestor(b, O, oKeys, 'b', inEntry, moved.b, a);
+    if (!aligned || !bAligned)
+        return undefined;
+    const known = new Set(oKeys);
+    pairNewItems(a, aligned.ids, b, bAligned.ids, (key) => inEntry.has(key) && !known.has(key));
+    return {
+        oKeys,
+        aIds: aligned.ids,
+        bIds: bAligned.ids,
+        aByPlace: aligned.byPlace,
+        bByPlace: bAligned.byPlace,
+        unsure: aligned.unsure || bAligned.unsure,
+    };
+}
+/**
+ * Identities by the string member `name`. A version with an item that has no name, or a name two
+ * items share, leaves no way to tell its items apart: undefined, and the list is one value.
+ */
+function identifyByName(O, a, b, name) {
+    const ids = (items) => {
+        const names = items.map((item) => (isPlainRecord(item) ? member(item, name) : undefined));
+        const distinct = new Set(names);
+        const usable = names.every((n) => typeof n === 'string' && !isNewIdentity(n));
+        return usable && distinct.size === names.length ? names : undefined;
+    };
+    const [oKeys, aIds, bIds] = [ids(O), ids(a), ids(b)];
+    if (!oKeys || !aIds || !bIds)
+        return undefined;
+    const none = new Set();
+    return { oKeys, aIds, bIds, aByPlace: none, bByPlace: none, unsure: false };
+}
+/** `merged` with the key its list gives it, recording the remap when the branch's key changes. */
+function withListKey(merged, ai, bi, keys, used, at, walk) {
+    if (!isPlainRecord(merged))
+        return merged;
+    const branchReadKey = keys.branchRead;
+    const key = [usableKey(ai) ?? keys.base, usableKey(bi)].find((k) => k !== undefined && !used.has(k));
+    if (key === undefined) {
+        const carried = isPlainRecord(bi) ? bi[ITEM_KEY] : undefined;
+        return carried === undefined ? merged : { ...merged, [ITEM_KEY]: carried };
+    }
+    used.add(key);
+    if (branchReadKey !== undefined &&
+        branchReadKey !== key &&
+        !walk.ambiguous(at.branchKeys, branchReadKey)) {
+        walk.keyRemaps.push({ within: at.branchKeys, from: branchReadKey, to: key });
+    }
+    return { ...merged, [ITEM_KEY]: key };
+}
+/** A version's data with its md/mdx body under the body field, as a read gives the form. */
+const withBody = (side, bodyName) => side.body === undefined ? side.data : { ...side.data, [bodyName]: side.body };
+const mdxParses = (text) => parseMarkdownBody(text, 'mdx') !== undefined;
+const sameContent = (x, y) => sameValue(x.data, y.data) && (x.body ?? '') === (y.body ?? '');
+function mergeBody(o, a, b, format, at, walk) {
+    if (a === b || o === a)
+        return b;
+    if (o === b)
+        return a;
+    const merged = mergeText(o, a, b);
+    if (!merged) {
+        conflict(o, a, b, at, walk);
+        return b;
+    }
+    const { text, regions } = merged;
+    const parses = (body) => format !== 'mdx' || mdxParses(body);
+    if (!parses(text) && parses(a) && parses(b)) {
+        walk.conflicts.push({
+            at: at.segments,
+            places: at.places,
+            kind: 'changed',
+            ...versions(o, a, b),
+            unparseable: true,
+        });
+        return b;
+    }
+    if (regions.length > 0) {
+        walk.conflicts.push({
+            at: at.segments,
+            places: at.places,
+            kind: 'changed',
+            ...versions(o, a, b),
+            regions,
+        });
+    }
+    return text;
+}
+export function mergeEntry({ format, ancestor, base, branch, fields, }) {
+    if (base.entryType !== branch.entryType) {
+        const baseRetyped = base.entryType !== ancestor.entryType;
+        const branchRetyped = branch.entryType !== ancestor.entryType;
+        const unchanged = baseRetyped ? branch : base;
+        if (baseRetyped && branchRetyped)
+            return { kind: 'entry-conflict', reason: 'entry-type' };
+        if (!sameContent(ancestor, unchanged))
+            return { kind: 'entry-conflict', reason: 'entry-type' };
+        const retyped = baseRetyped ? base : branch;
+        return {
+            kind: 'merged',
+            data: retyped.data,
+            ...(retyped.body !== undefined && { body: retyped.body }),
+            conflicts: [],
+            keyRemaps: [],
+        };
+    }
+    const ancestorKeys = new Set();
+    visitItems(ancestor.data, (_item, key) => ancestorKeys.add(key));
+    // Each list by the own keys of the items enclosing it, as a parent's read key changes with its
+    // content and its own key does not; by its field path alone where the ancestor has no such
+    // parent, as for a keyless parent a side edited and then keyed.
+    const exact = new Map();
+    const byField = new Map();
+    const parents = new Set();
+    const field = (list) => list.replace(/\[[^\]]*\]/g, '[]');
+    // A keyless ancestor item by its place, and by the key a side's first save gave it.
+    for (const keylessByRead of [false, true]) {
+        visitByOwnKey(ancestor.data, (_item, read, list, at) => {
+            exact.set(list, (exact.get(list) ?? new Set()).add(read));
+            byField.set(field(list), (byField.get(field(list)) ?? new Set()).add(read));
+            parents.add(at);
+        }, keylessByRead);
+    }
+    const movedIn = (data) => {
+        const keys = new Set();
+        visitByOwnKey(data, (item, _read, list) => {
+            const own = usableKey(item);
+            if (own === undefined)
+                return;
+            const parent = list.slice(0, list.lastIndexOf(']') + 1);
+            const there = parent === '' || parents.has(parent) ? exact.get(list) : byField.get(field(list));
+            if (!there?.has(own))
+                keys.add(own);
+        });
+        return keys;
+    };
+    const asRead = (side) => (fields ? entryAsRead(fields, side.data) : side.data);
+    const root = { ...ROOT, asRead: { a: asRead(base), b: asRead(branch) } };
+    const walk = {
+        conflicts: [],
+        keyRemaps: [],
+        pendingRemaps: [],
+        texts: [],
+        ancestorKeys,
+        movedKeys: { a: movedIn(base.data), b: movedIn(branch.data) },
+        ambiguous: ambiguityOf(root.asRead.b, fields !== undefined),
+    };
+    const data = mergeRecord(ancestor.data, base.data, branch.data, root, walk);
+    if (fields)
+        undoUnparseableMdx(fields, data, walk);
+    flagItemsMovedAway(ancestor.data, base.data, branch.data, data, walk);
+    const hasBody = [ancestor, base, branch].some((side) => side.body !== undefined);
+    const bodyName = findBodyFieldName(fields ?? []);
+    const body = hasBody
+        ? mergeBody(ancestor.body ?? '', base.body ?? '', branch.body ?? '', format, child(ROOT, { field: bodyName }, { o: ancestor.body, a: base.body, b: branch.body }), walk)
+        : undefined;
+    const read = fields ? entryAsRead(fields, data) : data;
+    for (const { at, within, from } of walk.pendingRemaps) {
+        const last = at.at(-1);
+        const list = valueAt(read, at.slice(0, -1));
+        const to = last && 'index' in last && Array.isArray(list) ? itemKeysAsRead(list)[last.index] : undefined;
+        if (to !== undefined && to !== from)
+            walk.keyRemaps.push({ within, from, to });
+    }
+    return {
+        kind: 'merged',
+        data,
+        ...(body !== undefined && { body }),
+        conflicts: named(walk.conflicts, fields, read, {
+            o: withBody(ancestor, bodyName),
+            a: withBody(base, bodyName),
+            b: withBody(branch, bodyName),
+        }),
+        keyRemaps: walk.keyRemaps,
+    };
+}
+/**
+ * {@link Walk.ambiguous} for `branch`, as read. A schema's read keys each list a thread can name,
+ * so only keyed items count; with no schema, every list's items count by their read keys.
+ */
+function ambiguityOf(branch, schemaRead) {
+    const seen = new Map();
+    const name = (within, key) => JSON.stringify([...within, key]);
+    const visit = (node, within) => {
+        if (Array.isArray(node)) {
+            const readKeys = schemaRead ? [] : itemKeysAsRead(node);
+            node.forEach((item, n) => {
+                const key = schemaRead ? usableKey(item) : readKeys[n];
+                if (key === undefined)
+                    return;
+                seen.set(name(within, key), (seen.get(name(within, key)) ?? 0) + 1);
+                visit(item, [...within, key]);
+            });
+        }
+        else if (isPlainRecord(node)) {
+            for (const value of Object.values(node))
+                visit(value, within);
+        }
+    };
+    visit(branch, []);
+    return (within, key) => (seen.get(name(within, key)) ?? 0) > 1;
+}
+/**
+ * Each item in `data`, at any depth, by the key a read gives it, so a keyless item is found by its
+ * content; null for a key held more than once in the entry.
+ */
+function keyedItems(data) {
+    const found = new Map();
+    visitItems(data, (item, key, list, at) => {
+        for (const name of [key, contentName(item)]) {
+            found.set(name, found.has(name) ? null : { item, list, at });
+        }
+    });
+    return found;
+}
+/** An item's content as a name, so an item a side moved without its key is still found. */
+const contentName = (item) => `${ITEM_KEY}:${valueToken(item)}`;
+/**
+ * Each list item of `node` with its read key, its list's path and its own: enclosing items by own
+ * key, else by place, or with `keylessByRead` by read key.
+ */
+function visitByOwnKey(node, onItem, keylessByRead = false, list = '') {
+    if (Array.isArray(node)) {
+        const reads = itemKeysAsRead(node);
+        node.forEach((item, index) => {
+            const own = usableKey(item);
+            const read = reads[index];
+            // A key a list holds twice names only its first holder.
+            const name = own !== undefined && own === read ? own : keylessByRead ? read : undefined;
+            const at = `${list}[${name ?? `#${index}`}]`;
+            if (read !== undefined)
+                onItem(item, read, list, at);
+            visitByOwnKey(item, onItem, keylessByRead, at);
+        });
+    }
+    else if (isPlainRecord(node)) {
+        for (const [name, value] of Object.entries(node)) {
+            visitByOwnKey(value, onItem, keylessByRead, `${list}.${name}`);
+        }
+    }
+}
+/** Calls `onItem` for every record in a list in `node`, with its read key, list and path. */
+function visitItems(node, onItem, at = [], list = '') {
+    if (Array.isArray(node)) {
+        const keys = itemKeysAsRead(node);
+        node.forEach((item, index) => {
+            const key = keys[index];
+            const itemAt = [...at, { index }];
+            if (key !== undefined)
+                onItem(item, key, list, itemAt);
+            visitItems(item, onItem, itemAt, `${list}[${key ?? `#${index}`}]`);
+        });
+    }
+    else if (isPlainRecord(node)) {
+        for (const [name, value] of Object.entries(node)) {
+            visitItems(value, onItem, [...at, { field: name }], `${list}.${name}`);
+        }
+    }
+}
+/**
+ * Lists merge one at a time, so an item one side moved to another list survives there although
+ * the other side removed it, or is there twice when the other side changed it in its old place.
+ * An item the merged entry holds in another list than the ancestor did, which a side no longer has
+ * anywhere (by its key as read, so a keyless item by its content), or a keyed item the entry now
+ * holds twice, is an item conflict.
+ */
+function flagItemsMovedAway(ancestor, base, branch, merged, walk) {
+    const [o, a, b] = [keyedItems(ancestor), keyedItems(base), keyedItems(branch)];
+    const named = new Set(walk.conflicts.map((c) => JSON.stringify(c.at)));
+    const seen = new Set();
+    visitItems(merged, (item, key, list, at) => {
+        // A keyed item is found by its key alone: another item reading alike is not it. A keyless
+        // one, by its content too, which finds an item a side moved without its key.
+        const keyed = usableKey(item) !== undefined;
+        const content = contentName(item);
+        const find = (found) => found.has(key) || keyed ? found.get(key) : found.get(content);
+        const holds = (found) => found.has(key) || (!keyed && found.has(content));
+        const [inO, inA, inB] = [find(o), find(a), find(b)];
+        // A side holding it twice copied it: no move to judge.
+        if (inA === null || inB === null)
+            return;
+        const twice = keyed && seen.has(key);
+        seen.add(key);
+        const moved = inO && inO.list !== list;
+        const kind = twice
+            ? 'changed'
+            : moved && !holds(a)
+                ? 'removed-on-base'
+                : moved && !holds(b)
+                    ? 'removed-by-you'
+                    : undefined;
+        if (!kind || named.has(JSON.stringify(at)))
+            return;
+        walk.conflicts.push({
+            at,
+            places: { o: inO?.at, a: inA?.at, b: inB?.at },
+            kind,
+            item: true,
+            ...versions(inO?.item, inA?.item, inB?.item),
+        });
+    });
+}
+/**
+ * The conflicts as the drawer names them. Where the drawer shows a whole value (an image, a field
+ * the schema doesn't know) a conflict inside it is lifted to that value: its versions become the
+ * whole value's, and the conflicts inside it are one. The merged entry keeps what merged there.
+ */
+function named(conflicts, fields, read, sides) {
+    const seen = new Set();
+    const out = [];
+    const asRead = (side) => fields && isPlainRecord(side) ? entryAsRead(fields, side) : side;
+    const reads = { o: asRead(sides.o), a: asRead(sides.a), b: asRead(sides.b) };
+    for (const { at, places, placeTrail, trail, ...rest } of conflicts) {
+        const { key, dataPath, depth } = describePath(fields, read, at);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        // Each version's own path to where its value below was taken: its place, or its place at the
+        // step the name stops at when the merge's trail gave the whole value, or the merged path when
+        // the whole value was found by member names alone. A version without the item a conflict names
+        // is named by the list it holds, one step short of `dataPath`, which says it lacks the item. A
+        // side naming the place at another depth offers none.
+        const prefix = at.slice(0, depth);
+        const byName = prefix.every((segment) => 'field' in segment);
+        const placeOf = (side) => depth === at.length
+            ? places[side]
+            : trail?.[depth - 1]
+                ? placeTrail?.[depth - 1]?.[side]
+                : byName
+                    ? prefix
+                    : undefined;
+        const describe = (side, place) => {
+            const named = describePath(fields, reads[side], place);
+            return named.depth === place.length ? named.dataPath : undefined;
+        };
+        const sidePath = (side) => {
+            const place = placeOf(side);
+            if (place)
+                return describe(side, place);
+            const list = depth === at.length && rest.item ? placeTrail?.[at.length - 2]?.[side] : undefined;
+            const holder = list && describe(side, list);
+            const missing = dataPath.at(-1);
+            return holder && missing && 'item' in missing ? holder : undefined;
+        };
+        const [ancestor, base, branch] = [sidePath('o'), sidePath('a'), sidePath('b')];
+        const sidePaths = {
+            ...(ancestor && { ancestor }),
+            ...(base && { base }),
+            ...(branch && { branch }),
+        };
+        if (depth === at.length) {
+            out.push({ key, dataPath, sidePaths, ...rest });
+            continue;
+        }
+        // The whole value's versions: from the merge's own trail, else by member names when the way
+        // there passes no list item (whose place differs between versions), else none to offer.
+        const whole = trail?.[depth - 1] ??
+            (byName
+                ? { o: valueAt(sides.o, prefix), a: valueAt(sides.a, prefix), b: valueAt(sides.b, prefix) }
+                : undefined);
+        out.push({
+            key,
+            dataPath,
+            sidePaths,
+            kind: whole ? kindOf(whole.a, whole.b) : 'changed',
+            ...(!('field' in at[depth - 1]) && { item: true }),
+            ...(whole && versions(whole.o, whole.a, whole.b)),
+        });
+    }
+    return out;
+}
+/** The value at `at` in `data`. */
+function valueAt(data, at) {
+    let node = data;
+    for (const segment of at) {
+        node =
+            'index' in segment
+                ? asList(node)[segment.index]
+                : 'field' in segment && isPlainRecord(node)
+                    ? member(node, segment.field)
+                    : undefined;
+    }
+    return node;
+}
+/** The member at `at` in `data`, which the merge built along every such path, set to `value`. */
+function setAt(data, at, value) {
+    const holder = valueAt(data, at.slice(0, -1));
+    const last = at.at(-1);
+    if (last && 'field' in last && isPlainRecord(holder))
+        setMember(holder, last.field, value);
+}
+/**
+ * An `mdx` field whose line merge does not parse, where both sides' texts do: the branch's text
+ * goes back in, and the whole field is one conflict, as for an mdx body.
+ */
+function undoUnparseableMdx(fields, data, walk) {
+    for (const text of walk.texts) {
+        if (describePath(fields, data, text.at).field?.type !== 'mdx')
+            continue;
+        const { o, a, b } = text.versions;
+        if (mdxParses(String(valueAt(data, text.at))) || !mdxParses(a) || !mdxParses(b))
+            continue;
+        setAt(data, text.at, b);
+        const whole = {
+            at: text.at,
+            places: text.places,
+            placeTrail: text.placeTrail,
+            trail: text.conflict?.trail,
+            kind: 'changed',
+            ...versions(o, a, b),
+            unparseable: true,
+        };
+        const at = text.conflict ? walk.conflicts.indexOf(text.conflict) : -1;
+        if (at === -1)
+            walk.conflicts.push(whole);
+        else
+            walk.conflicts[at] = whole;
+    }
+}
+/**
+ * `a` (the base's) and `b` (the branch's), both changed from `o`, merged as ordered sets of
+ * distinct values: each side's adds and removes apply, and the order is `mergeOrder`'s. Nothing
+ * conflicts: a set entry has no content to change.
+ */
+function mergeOrderedSet(o, a, b) {
+    const ids = (list) => [...new Set(list.map(valueToken))];
+    const [oIds, aIds, bIds] = [ids(o), ids(a), ids(b)];
+    const value = new Map([...o, ...a, ...b].map((v) => [valueToken(v), v]));
+    const [inO, inA, inB] = [new Set(oIds), new Set(aIds), new Set(bIds)];
+    return mergeOrder(oIds, aIds, bIds)
+        .filter((id) => (inO.has(id) ? inA.has(id) && inB.has(id) : inA.has(id) || inB.has(id)))
+        .map((id) => value.get(id));
+}
+/**
+ * Three-way merge of a collection's `.collection.json`: `order` as an ordered set of content IDs,
+ * so two branches that each add an entry both keep theirs; `entries` matched by `name`; every
+ * other member by the entry rules.
+ */
+export function mergeCollectionMeta(ancestor, base, branch) {
+    const walk = {
+        conflicts: [],
+        keyRemaps: [],
+        pendingRemaps: [],
+        texts: [],
+        ancestorKeys: new Set(),
+        movedKeys: { a: new Set(), b: new Set() },
+        ambiguous: () => false,
+    };
+    const data = {};
+    for (const name of new Set([
+        ...Object.keys(branch),
+        ...Object.keys(base),
+        ...Object.keys(ancestor),
+    ])) {
+        const [o, a, b] = [member(ancestor, name), member(base, name), member(branch, name)];
+        const at = child(ROOT, { field: name }, { o, a, b });
+        const lists = [o, a, b].every((v) => v === undefined || Array.isArray(v));
+        let v;
+        if (name === 'order' && lists && !sameValue(o, b) && !sameValue(o, a)) {
+            v = mergeOrderedSet(asList(o), asList(a), asList(b));
+        }
+        else if (name === 'entries' && [o, a, b].every((x) => x === undefined || isRecordList(x))) {
+            v = mergeList(o, asList(a), asList(b), at, walk, 'name') ?? mergeLeaf(o, a, b, at, walk);
+        }
+        else {
+            v = mergeValue(o, a, b, at, walk);
+        }
+        if (v !== undefined)
+            setMember(data, name, v);
+    }
+    return {
+        data,
+        conflicts: named(walk.conflicts, undefined, data, { o: ancestor, a: base, b: branch }),
+    };
+}