canopycms 0.12.0 → 0.13.0

package/dist/worker/field-merge.js

@@ -0,0 +1,729 @@
+import path from 'node:path';
+import { parse as yamlParse } from 'yaml';
+import { entryLogicalPathOfFile, extractIdFromFilename } from '../content-id-index.js';
+import { ITEM_KEY } from '../item-keys.js';
+import { parseEntryParts } from '../content-listing.js';
+import { mergeCollectionMeta, mergeEntry, } from '../merge/entry-merge.js';
+import { rekeyAsMerged } from '../merge/rekey.js';
+import { exactToken } from '../merge/value-equality.js';
+import { LOCATION_CONFLICT_KEY, } from '../merge-conflicts.js';
+import { normalizeFilesystemPath } from '../paths/normalize.js';
+import { serializeFrontmatter, serializeYaml } from '../utils/content-serialize.js';
+import { getErrorMessage } from '../utils/error.js';
+import { escapeForLog } from '../utils/escape-text.js';
+import { isPlainRecord } from '../validation/field-traversal.js';
+import { serializeJson } from '../utils/json-source-splice.js';
+import { parseTypedFilename } from '../utils/typed-filename.js';
+import { runGit } from './git-process.js';
+import { workerLogWarn } from './log.js';
+import { sharedRepoProcessOptions } from './shared-repo-git.js';
+/** The size cap "Show changes" reads with: a bigger version is not merged field by field. */
+const MAX_MERGE_BYTES = 1024 * 1024;
+const REGULAR_FILE = /^100(644|755)$/;
+const FORMATS = ['md', 'mdx', 'json', 'yaml'];
+const formatOf = (file) => {
+    const ext = path.posix.extname(file);
+    return FORMATS.find((f) => (f === 'yaml' ? ext === '.yaml' : ext === `.${f}`));
+};
+/** The unit a path belongs to, by its key, or null for a path the engine never decides. */
+function unitKeyOf(file, root, collectionIdOf) {
+    if (entryLogicalPathOfFile(file, root) !== null) {
+        const parsed = parseTypedFilename(path.posix.basename(file));
+        return parsed ? { key: `id:${parsed.id}`, id: parsed.id } : null;
+    }
+    const below = file.startsWith(`${root}/`) ? file.slice(root.length + 1).split('/') : null;
+    if (!below || below.at(-1) !== '.collection.json')
+        return null;
+    if (below.slice(0, -1).some((s) => s.startsWith('.') || s === '_ids_'))
+        return null;
+    const collection = collectionIdOf(file);
+    return { key: collection ? `meta:${collection}` : `meta-at:${file}` };
+}
+/** `diff-tree --raw` from `from` to `to`, without rename detection: each path's two files. */
+export async function changedFiles(git, from, to) {
+    const out = await git.raw([
+        'diff-tree',
+        '-r',
+        '-z',
+        '--no-renames',
+        '--raw',
+        '--end-of-options',
+        from,
+        to,
+    ]);
+    const fields = out.split('\0');
+    const changes = [];
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        const match = /^:(\d{6}) (\d{6}) ([0-9a-f]+) ([0-9a-f]+) ([A-Z])\d*$/.exec(fields[i]);
+        if (!match)
+            throw new Error(`Unreadable git diff-tree entry: ${JSON.stringify(fields[i])}`);
+        const [, beforeMode, afterMode, beforeOid, afterOid, status] = match;
+        const file = fields[i + 1];
+        changes.push({
+            path: file,
+            ...(status !== 'A' && { before: { path: file, oid: beforeOid, mode: beforeMode } }),
+            ...(status !== 'D' && { after: { path: file, oid: afterOid, mode: afterMode } }),
+        });
+    }
+    return changes;
+}
+/**
+ * Where each collection directory a merge touches ends up, by its collection ID. A directory's
+ * parent and its own name are settled apart, each as a field is: the branch's change, else the
+ * base's. So a parent one side renamed and a child the other side renamed both come through, and
+ * only both sides changing the same one differently is a move apart. A directory one version
+ * holds at two places is left where each file has it.
+ */
+class CollectionMoves {
+    constructor() {
+        this.at = {
+            ancestor: new Map(),
+            base: new Map(),
+            branch: new Map(),
+        };
+        /** Collection directories each side moved into the other: no tree holds both moves. */
+        this.cyclic = false;
+    }
+    note(version, file) {
+        const segments = file.split('/');
+        let parent = '';
+        for (let k = 0; k < segments.length - 1; k++) {
+            const id = extractIdFromFilename(segments[k]);
+            if (!id) {
+                parent = parent.startsWith('id:')
+                    ? `${parent}/${segments[k]}`
+                    : segments.slice(0, k + 1).join('/');
+                continue;
+            }
+            const here = { parent, name: segments[k] };
+            const known = this.at[version].get(id);
+            const same = known && known.parent === here.parent && known.name === here.name;
+            this.at[version].set(id, known === undefined || same ? here : null);
+            parent = `id:${id}`;
+        }
+    }
+    /** Each side's place for `id`'s directory, when every version that has one has just one. */
+    versions(id) {
+        const [o, a, b] = ['ancestor', 'base', 'branch'].map((v) => this.at[v].get(id));
+        if (o === null || a === null || b === null)
+            return undefined;
+        return { o, a, b };
+    }
+    settle(id) {
+        const v = this.versions(id);
+        if (!v)
+            return undefined;
+        const pick = (part) => {
+            const [o, a, b] = [v.o?.[part], v.a?.[part], v.b?.[part]];
+            if (b !== undefined && b !== o)
+                return b;
+            if (a !== undefined && a !== o)
+                return a;
+            return o ?? b ?? a;
+        };
+        const [parent, name] = [pick('parent'), pick('name')];
+        return parent !== undefined && name !== undefined ? { parent, name } : undefined;
+    }
+    /** The path `id`'s directory ends up at, or undefined where that can't be told. */
+    final(id, seen = new Set()) {
+        if (seen.has(id)) {
+            this.cyclic = true;
+            return undefined;
+        }
+        const dir = this.settle(id);
+        if (!dir)
+            return undefined;
+        if (!dir.parent.startsWith('id:'))
+            return dir.parent ? `${dir.parent}/${dir.name}` : dir.name;
+        const [parentId, ...below] = dir.parent.slice(3).split('/');
+        const parent = this.final(parentId, new Set([...seen, id]));
+        return parent === undefined ? undefined : [parent, ...below, dir.name].join('/');
+    }
+    /** Whether both sides moved `id`'s directory, changing its parent or its name differently. */
+    movedApart(id) {
+        const v = this.versions(id);
+        if (!v?.o || !v.a || !v.b)
+            return false;
+        const { o, a, b } = v;
+        return ['parent', 'name'].some((part) => a[part] !== o[part] && b[part] !== o[part] && a[part] !== b[part]);
+    }
+    /** `file` in the collection directories it is in, each where it ends up. */
+    place(file) {
+        const segments = file.split('/');
+        for (let k = segments.length - 2; k >= 0; k--) {
+            const id = extractIdFromFilename(segments[k]);
+            const dir = id ? this.final(id) : undefined;
+            if (dir)
+                return [dir, ...segments.slice(k + 1)].join('/');
+        }
+        return file;
+    }
+}
+/** The units both sides' changes touch, keyed as {@link unitKeyOf} keys them. */
+async function collectUnits(args, root, moves) {
+    const { git, ancestor, head, other } = args;
+    const units = new Map();
+    for (const [side, to] of [
+        ['base', other],
+        ['branch', head],
+    ]) {
+        for (const change of await changedFiles(git, ancestor, to)) {
+            const { before, after } = change;
+            if (before)
+                moves.note('ancestor', change.path);
+            if (after)
+                moves.note(side, change.path);
+            const at = unitKeyOf(change.path, root, args.collectionIdOf);
+            if (!at)
+                continue;
+            let unit = units.get(at.key);
+            if (!unit) {
+                unit = {
+                    kind: at.key.startsWith('id:') ? 'entry' : 'meta',
+                    ...(at.id && { id: at.id }),
+                    changed: {},
+                    touched: { base: false, branch: false },
+                    removed: { base: new Set(), branch: new Set() },
+                    ambiguous: false,
+                };
+                units.set(at.key, unit);
+            }
+            if (before) {
+                if (unit.ancestor && unit.ancestor.path !== before.path)
+                    unit.ambiguous = true;
+                unit.ancestor = before;
+                if (!after)
+                    unit.removed[side].add(change.path);
+            }
+            if (after) {
+                if (unit.changed[side])
+                    unit.ambiguous = true;
+                unit.changed[side] = after;
+            }
+            unit.touched[side] = true;
+            for (const file of [before, after]) {
+                if (file && !REGULAR_FILE.test(file.mode))
+                    unit.ambiguous = true;
+            }
+            if (change.path.includes('\uFFFD'))
+                unit.ambiguous = true;
+        }
+    }
+    // A side with a file for the unit at a new path, which kept the ancestor's, copied it.
+    for (const unit of units.values()) {
+        for (const side of ['base', 'branch']) {
+            const file = unit.changed[side];
+            const kept = unit.ancestor && !unit.removed[side].has(unit.ancestor.path);
+            if (file && unit.ancestor && file.path !== unit.ancestor.path && kept)
+                unit.ambiguous = true;
+        }
+    }
+    return units;
+}
+/** One side's file, as it stands after that side's changes. */
+const sideFile = (unit, side) => unit.touched[side] ? unit.changed[side] : unit.ancestor;
+/** What git's merge holds for each unit: path to file. */
+async function gitsFiles(args, root, units) {
+    const held = new Map();
+    for (const [key, unit] of units) {
+        held.set(key, new Map(unit.ancestor ? [[unit.ancestor.path, unit.ancestor]] : []));
+    }
+    for (const change of await changedFiles(args.git, args.ancestor, args.mergedTree)) {
+        const at = unitKeyOf(change.path, root, args.collectionIdOf);
+        const files = at && held.get(at.key);
+        if (!files)
+            continue;
+        if (change.before)
+            files.delete(change.path);
+        if (change.after)
+            files.set(change.path, change.after);
+    }
+    return held;
+}
+/** A blob's text, or undefined when it is too large or not UTF-8. */
+async function readText(git, oid) {
+    const size = parseInt((await git.raw(['cat-file', '-s', '--end-of-options', oid])).trim(), 10);
+    if (!Number.isInteger(size) || size > MAX_MERGE_BYTES)
+        return undefined;
+    const text = await git.raw(['cat-file', 'blob', '--end-of-options', oid]);
+    return Buffer.byteLength(text, 'utf8') === size && !text.includes('\uFFFD') ? text : undefined;
+}
+/**
+ * Whether `text` holds a record at its top level, as an entry's data must: the store reads any
+ * other JSON or YAML as no data at all, which would make every version alike.
+ */
+function holdsRecord(text, format) {
+    if (format === 'json')
+        return isPlainRecord(JSON.parse(text));
+    if (format !== 'yaml')
+        return true;
+    const value = yamlParse(text);
+    return value === null || value === undefined || isPlainRecord(value);
+}
+/** One version of an entry, parsed as `ContentStore.read` parses it, or undefined if it can't be. */
+async function readEntry(git, file, format) {
+    const text = await readText(git, file.oid);
+    if (text === undefined)
+        return undefined;
+    try {
+        if (!holdsRecord(text, format))
+            return undefined;
+        const { data, body } = parseEntryParts(text, format);
+        // A copy: gray-matter's cache hands every reader of the same text one object.
+        const side = { data: structuredClone(data) };
+        if (body !== undefined)
+            side.body = body;
+        const type = parseTypedFilename(path.posix.basename(file.path))?.type;
+        if (type !== undefined)
+            side.entryType = type;
+        return { file, text, side };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The branch's fields for the entry type a file stores, when the schema snapshot has them. */
+function fieldsFor(flatSchema, file, root) {
+    const logical = entryLogicalPathOfFile(file, root);
+    const type = parseTypedFilename(path.posix.basename(file))?.type;
+    if (!flatSchema || logical === null || type === undefined)
+        return undefined;
+    const collection = logical.slice(0, logical.lastIndexOf('/'));
+    const item = flatSchema.find((i) => i.type === 'entry-type' && i.parentPath === collection && i.name === type);
+    return item?.type === 'entry-type' ? item.schema : undefined;
+}
+const sameContent = (x, y) => exactToken(x.data) === exactToken(y.data) && x.body === y.body;
+/** Text for merged entry data, written onto `onto` (the base's file) to keep its formatting. */
+function serializeEntry(format, merged, onto) {
+    if (format === 'json')
+        return serializeJson(merged.data, onto);
+    if (format === 'yaml')
+        return serializeYaml(merged.data, onto);
+    return serializeFrontmatter(merged.body ?? '', merged.data, onto, format);
+}
+const blobSides = (unit) => {
+    const [ancestor, base, branch] = [unit.ancestor, sideFile(unit, 'base'), sideFile(unit, 'branch')];
+    return {
+        ...(ancestor && { ancestor: ancestor.oid }),
+        ...(base && { base: base.oid }),
+        ...(branch && { branch: branch.oid }),
+    };
+};
+const recordFields = (conflicts) => conflicts.map(({ key, dataPath, sidePaths, kind, item, regions, unparseable }) => ({
+    key,
+    dataPath,
+    sidePaths,
+    kind,
+    ...(item && { item }),
+    ...((regions !== undefined || unparseable) && { text: true }),
+}));
+/** The entry's place, which no version holds a value for. */
+const LOCATION = {
+    key: LOCATION_CONFLICT_KEY,
+    dataPath: [],
+    sidePaths: {},
+    kind: 'changed',
+};
+/** Whether `text` reads back as `merged`, item keys and all. */
+function readsAs(text, format, merged) {
+    try {
+        if (!holdsRecord(text, format))
+            return false;
+        const back = parseEntryParts(text, format);
+        return sameContent({ data: back.data, ...(back.body !== undefined && { body: back.body }) }, merged);
+    }
+    catch {
+        return false;
+    }
+}
+/** `value` with every item key dropped, and nothing else changed. */
+const withoutItemKeys = (value) => {
+    if (Array.isArray(value))
+        return value.map(withoutItemKeys);
+    if (!isPlainRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([name]) => name !== ITEM_KEY)
+        .map(([name, v]) => [name, withoutItemKeys(v)]));
+};
+/**
+ * Whether two versions of one entry file under `contentRoot` differ in item keys alone: what a
+ * re-key changes. False for anything else, a file's mode or path included.
+ */
+export async function differsInItemKeysOnly(git, x, y, contentRoot) {
+    const format = formatOf(y.path);
+    if (!format || x.path !== y.path || x.mode !== y.mode)
+        return false;
+    if (entryLogicalPathOfFile(y.path, normalizeFilesystemPath(contentRoot)) === null)
+        return false;
+    const [a, b] = await Promise.all([readEntry(git, x, format), readEntry(git, y, format)]);
+    return (!!a &&
+        !!b &&
+        a.side.body === b.side.body &&
+        exactToken(withoutItemKeys(a.side.data)) === exactToken(withoutItemKeys(b.side.data)));
+}
+class Resolver {
+    constructor(args, moves) {
+        this.args = args;
+        this.moves = moves;
+        this.root = normalizeFilesystemPath(args.contentRoot);
+        this.options = {
+            ...sharedRepoProcessOptions(args.clonePath, 'worktree'),
+            inactivityTimeoutMs: args.timeoutMs,
+        };
+    }
+    async write(text, like, at) {
+        // `--no-filters`: no clean filter from the clone's attributes runs.
+        const oid = (await runGit(['hash-object', '-w', '--no-filters', '--stdin'], {
+            ...this.options,
+            stdin: text,
+        })).trim();
+        if (!/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(oid))
+            throw new Error('git hash-object printed no id');
+        return { path: at, oid, mode: like.mode };
+    }
+    /**
+     * The file for a merged value at `at`, keeping the most of what each side wrote that the value
+     * does not carry, such as a developer's comments and formatting: git's clean merge, else the
+     * base's file, else the value written onto the base's file, else the branch's file, else the
+     * value written plain. A text must read back as the value. Undefined when none does.
+     */
+    async bytesFor(c, at) {
+        const mode = c.branch.mode;
+        if (c.git?.path === at) {
+            const text = await readText(this.args.git, c.git.oid);
+            if (text !== undefined && c.reads(text))
+                return c.git;
+        }
+        if (c.isBase)
+            return { ...c.base.file, path: at, mode };
+        const serialized = c.serialize(c.base.text);
+        // The serializer writes some lines with `\n` alone: a base written with `\r\n` keeps them.
+        const crlf = /\r\n/.test(c.base.text) && !/(^|[^\r])\n/.test(c.base.text);
+        for (const onBase of crlf ? [serialized.replace(/\r?\n/g, '\r\n'), serialized] : [serialized]) {
+            if (c.reads(onBase))
+                return this.write(onBase, c.branch, at);
+        }
+        if (c.isBranch)
+            return { ...c.branch, path: at };
+        const plain = c.serialize(undefined);
+        return c.reads(plain) ? this.write(plain, c.branch, at) : undefined;
+    }
+    /**
+     * Where both sides' versions of a unit go: each side's path with every collection directory
+     * either side moved moved too. Where only one side moved the file, there; else the branch's
+     * place. Both moving it apart, or both adding it apart, is a location conflict.
+     */
+    placeOf(o, a, b) {
+        const [oAt, aAt, bAt] = [
+            o && this.moves.place(o.path),
+            this.moves.place(a.path),
+            this.moves.place(b.path),
+        ];
+        const moved = {
+            base: oAt !== undefined && aAt !== oAt,
+            branch: oAt !== undefined && bAt !== oAt,
+        };
+        return {
+            at: moved.base && !moved.branch ? aAt : bAt,
+            apart: aAt !== bAt && (oAt === undefined || (moved.base && moved.branch)),
+        };
+    }
+    /**
+     * An entry both sides changed. A version that can't be read or doesn't match the others' format
+     * leaves git's merge where git merged it, and the branch's file where git could not. An entry
+     * type changed on one side, a merge that throws, or merged text that doesn't read back keeps the
+     * branch's file, an entry-level conflict, whatever git made of it.
+     */
+    async entry(unit, gitClean, gitFile) {
+        const { git } = this.args;
+        const [o, a, b] = [unit.ancestor, sideFile(unit, 'base'), sideFile(unit, 'branch')];
+        const sides = blobSides(unit);
+        if (!a && !b)
+            return {};
+        if (!a && b) {
+            const at = this.moves.place(b.path);
+            return { file: { ...b, path: at }, conflict: { path: at, kind: 'deleted-on-base', sides } };
+        }
+        if (a && !b) {
+            return { conflict: { path: this.moves.place(a.path), kind: 'deleted-on-branch', sides } };
+        }
+        if (!a || !b)
+            return null;
+        const { at, apart } = this.placeOf(o, a, b);
+        // The branch's whole file is the branch's version of the entry, so it keeps the branch's name.
+        const keepBranch = () => {
+            const own = this.moves.place(b.path);
+            return { file: { ...b, path: own }, conflict: { path: own, kind: 'unreadable', sides } };
+        };
+        if (a.oid === b.oid && !apart)
+            return { file: { ...b, path: at } };
+        const format = formatOf(b.path);
+        if (!format || [o, a].some((f) => f && formatOf(f.path) !== format)) {
+            return gitClean ? null : keepBranch();
+        }
+        const [oSide, aSide, bSide] = await Promise.all([o, a, b].map((f) => (f ? readEntry(git, f, format) : undefined)));
+        if (!aSide || !bSide || (o && !oSide))
+            return gitClean ? null : keepBranch();
+        const fields = fieldsFor(this.args.flatSchema, b.path, this.root);
+        let result;
+        try {
+            result = mergeEntry({
+                format,
+                ancestor: oSide?.side ?? { data: {} },
+                base: aSide.side,
+                branch: bSide.side,
+                ...(fields && { fields }),
+            });
+        }
+        catch (err) {
+            workerLogWarn(`  could not merge ${escapeForLog(b.path)} field by field: ${getErrorMessage(err)}`);
+            return keepBranch();
+        }
+        if (result.kind === 'entry-conflict')
+            return keepBranch();
+        const found = [...recordFields(result.conflicts), ...(apart ? [LOCATION] : [])];
+        const merged = result;
+        const file = await this.bytesFor({
+            ...(gitClean && gitFile && { git: gitFile }),
+            base: { file: a, text: aSide.text },
+            branch: b,
+            isBase: sameContent(aSide.side, merged),
+            isBranch: sameContent(bSide.side, merged),
+            reads: (text) => {
+                try {
+                    if (!holdsRecord(text, format))
+                        return false;
+                    const back = parseEntryParts(text, format);
+                    return sameContent({ data: back.data, ...(back.body !== undefined && { body: back.body }) }, merged);
+                }
+                catch {
+                    return false;
+                }
+            },
+            serialize: (onto) => serializeEntry(format, merged, onto),
+        }, at);
+        if (!file) {
+            workerLogWarn(`  the merge of ${escapeForLog(b.path)} does not read back as merged`);
+            return keepBranch();
+        }
+        return {
+            file,
+            ...(found.length > 0 && { conflict: { path: at, kind: 'fields', sides, fields: found } }),
+            ...(merged.keyRemaps.length > 0 && { remaps: merged.keyRemaps }),
+        };
+    }
+    /** In {@link FieldMergeArgs.rekeyOnly}: git's merged entry under the field merge's item keys. */
+    async rekeyed(unit, gitFile) {
+        const { git } = this.args;
+        const [o, a, b] = [unit.ancestor, sideFile(unit, 'base'), sideFile(unit, 'branch')];
+        if (!a || !b || !gitFile || a.oid === b.oid)
+            return null;
+        const format = formatOf(gitFile.path);
+        if (!format || [o, a, b].some((f) => f && formatOf(f.path) !== format))
+            return null;
+        const [oSide, aSide, bSide, gitSide] = await Promise.all([o, a, b, gitFile].map((f) => (f ? readEntry(git, f, format) : undefined)));
+        if (!aSide || !bSide || !gitSide || (o && !oSide))
+            return null;
+        const fields = fieldsFor(this.args.flatSchema, b.path, this.root);
+        let result;
+        try {
+            result = mergeEntry({
+                format,
+                ancestor: oSide?.side ?? { data: {} },
+                base: aSide.side,
+                branch: bSide.side,
+                ...(fields && { fields }),
+            });
+        }
+        catch {
+            return null;
+        }
+        if (result.kind !== 'merged' || result.conflicts.length > 0)
+            return null;
+        if (result.body !== gitSide.side.body)
+            return null;
+        const data = rekeyAsMerged(gitSide.side.data, result.data);
+        if (!isPlainRecord(data) || exactToken(data) === exactToken(gitSide.side.data))
+            return null;
+        const merged = { data, ...(result.body !== undefined && { body: result.body }) };
+        const file = await this.bytesFor({
+            base: { file: gitFile, text: gitSide.text },
+            branch: gitFile,
+            isBase: false,
+            isBranch: false,
+            reads: (text) => readsAs(text, format, merged),
+            serialize: (onto) => serializeEntry(format, merged, onto),
+        }, gitFile.path);
+        if (!file)
+            return null;
+        return { file, ...(result.keyRemaps.length > 0 && { remaps: result.keyRemaps }) };
+    }
+    /** A `.collection.json` both sides changed and both still have; else git's rule. */
+    async collectionMeta(unit, gitClean, gitFile) {
+        const { git } = this.args;
+        const [o, a, b] = [unit.ancestor, sideFile(unit, 'base'), sideFile(unit, 'branch')];
+        const sides = blobSides(unit);
+        // Deleted on one side and changed on the other, as for an entry: the branch's side stands.
+        if (o && (!a || !b)) {
+            if (!a && !b)
+                return {};
+            const contentId = this.args.collectionIdOf((b ?? a ?? o).path);
+            if (!contentId)
+                return null;
+            if (b) {
+                const at = this.moves.place(b.path);
+                return { file: { ...b, path: at }, conflict: { path: at, kind: 'deleted-on-base', sides } };
+            }
+            return {
+                conflict: { path: this.moves.place((a ?? o).path), kind: 'deleted-on-branch', sides },
+            };
+        }
+        if (!o || !a || !b)
+            return null;
+        const parse = async (file) => {
+            const text = await readText(git, file.oid);
+            if (text === undefined)
+                return undefined;
+            try {
+                const json = JSON.parse(text);
+                return isPlainRecord(json) ? { text, json } : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const [oJson, aJson, bJson] = await Promise.all([o, a, b].map(parse));
+        if (!oJson || !aJson || !bJson)
+            return null;
+        const merged = mergeCollectionMeta(oJson.json, aJson.json, bJson.json);
+        // The directory moved apart on both sides: it goes where the branch put it.
+        const dirId = extractIdFromFilename(path.posix.basename(path.posix.dirname(b.path)));
+        const apart = dirId !== null && this.moves.movedApart(dirId);
+        const at = this.moves.place(b.path);
+        const fields = [...recordFields(merged.conflicts), ...(apart ? [LOCATION] : [])];
+        const contentId = this.args.collectionIdOf(at);
+        if (fields.length > 0 && !contentId) {
+            workerLogWarn(`  ${escapeForLog(at)} keeps this branch's values where both changed them`);
+        }
+        const token = exactToken(merged.data);
+        const file = await this.bytesFor({
+            ...(gitClean && gitFile && { git: gitFile }),
+            base: { file: a, text: aJson.text },
+            branch: b,
+            isBase: exactToken(aJson.json) === token,
+            isBranch: exactToken(bJson.json) === token,
+            reads: (text) => {
+                try {
+                    return exactToken(JSON.parse(text)) === token;
+                }
+                catch {
+                    return false;
+                }
+            },
+            serialize: (onto) => serializeJson(merged.data, onto),
+        }, at);
+        if (!file)
+            return null;
+        return {
+            file,
+            ...(fields.length > 0 &&
+                contentId && { conflict: { path: at, kind: 'fields', sides, fields } }),
+        };
+    }
+}
+/** Two sets of a unit's files hold the same thing. */
+function sameFiles(held, wanted) {
+    if (!wanted)
+        return held.size === 0;
+    const at = held.get(wanted.path);
+    return held.size === 1 && at?.oid === wanted.oid && at.mode === wanted.mode;
+}
+/**
+ * Decide every entry file and `.collection.json` the merge touches. Nothing is staged here: the
+ * result says which blobs replace git's, and which conflicts a person must resolve.
+ */
+export async function resolveFieldMerge(args) {
+    const moves = new CollectionMoves();
+    const resolver = new Resolver(args, moves);
+    const root = normalizeFilesystemPath(args.contentRoot);
+    const units = await collectUnits(args, root, moves);
+    const held = await gitsFiles(args, root, units);
+    const result = {
+        updates: new Map(),
+        covered: new Set(),
+        conflicts: [],
+        keyRemaps: [],
+        paths: new Map(),
+    };
+    for (const [key, unit] of units) {
+        if (unit.ambiguous)
+            continue;
+        const gitHeld = held.get(key) ?? new Map();
+        const paths = new Set([
+            ...[unit.ancestor, sideFile(unit, 'base'), sideFile(unit, 'branch')].flatMap((f) => f ? [f.path] : []),
+            ...gitHeld.keys(),
+        ]);
+        const gitClean = ![...paths].some((p) => args.conflicted.has(p));
+        const only = gitHeld.size === 1 ? [...gitHeld.values()][0] : undefined;
+        let resolution;
+        if (args.rekeyOnly) {
+            if (unit.kind !== 'entry' || !unit.touched.base || !unit.touched.branch)
+                continue;
+            resolution = await resolver.rekeyed(unit, only);
+            if (resolution === null)
+                continue;
+        }
+        else if (unit.touched.base && unit.touched.branch) {
+            resolution =
+                unit.kind === 'entry'
+                    ? await resolver.entry(unit, gitClean, only)
+                    : await resolver.collectionMeta(unit, gitClean, only);
+            if (resolution === null)
+                continue;
+        }
+        else {
+            const file = sideFile(unit, unit.touched.base ? 'base' : 'branch');
+            // The one side's file, where git put it if git kept it whole, else where the collection
+            // directories it is in ended up.
+            const kept = file && only?.oid === file.oid && only.mode === file.mode;
+            const from = kept ? only : file;
+            resolution = { file: from && { ...from, path: moves.place(from.path) } };
+        }
+        for (const p of paths)
+            result.covered.add(p);
+        if (!sameFiles(gitHeld, resolution.file)) {
+            for (const p of gitHeld.keys())
+                result.updates.set(p, null);
+            for (const p of paths) {
+                if (args.conflicted.has(p))
+                    result.updates.set(p, null);
+            }
+            if (resolution.file)
+                result.updates.set(resolution.file.path, resolution.file);
+        }
+        const recordId = unit.id ?? (resolution.file && args.collectionIdOf(resolution.file.path));
+        if (recordId && resolution.file)
+            result.paths.set(recordId, resolution.file.path);
+        if (unit.id && resolution.conflict) {
+            result.conflicts.push({ contentId: unit.id, ...resolution.conflict });
+        }
+        else if (unit.kind === 'meta' && resolution.conflict) {
+            const contentId = args.collectionIdOf(resolution.conflict.path);
+            if (contentId)
+                result.conflicts.push({ contentId, ...resolution.conflict });
+        }
+        const branchFile = sideFile(unit, 'branch');
+        const entryPath = branchFile && entryLogicalPathOfFile(branchFile.path, root);
+        if (resolution.remaps && entryPath) {
+            result.keyRemaps.push({
+                entryPath,
+                ...(unit.id && { contentId: unit.id }),
+                remaps: resolution.remaps,
+            });
+        }
+    }
+    if (moves.cyclic)
+        result.unsettled = 'collection directories moved into each other';
+    return result;
+}