canopycms 0.12.0 → 0.12.1

package/dist/git-manager.js

@@ -1763,6 +1763,36 @@ export class GitManager {
             throw err;
         }
     }
+    /**
+     * The text of the blob `sha`, `'too-large'` when it is over `maxBytes`, or `undefined` when this
+     * clone has no such blob. Any other failure throws.
+     */
+    async readBlob(sha, maxBytes) {
+        if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha))
+            return undefined;
+        let sizeText;
+        try {
+            sizeText = (await this.git.raw(['cat-file', '-s', '--end-of-options', sha])).trim();
+        }
+        catch (err) {
+            // LC_ALL=C (gitChildEnv), so git's own wording is stable to match.
+            if (/could not get object info|Not a valid object name/.test(getErrorMessage(err))) {
+                return undefined;
+            }
+            throw err;
+        }
+        // simple-git resolves "" when git exits non-zero without writing to stderr, so anything but
+        // digits is a failed read rather than an empty blob.
+        if (!/^\d+$/.test(sizeText))
+            throw new Error(`git cat-file -s ${sha} printed no size`);
+        const size = Number(sizeText);
+        if (size > maxBytes)
+            return 'too-large';
+        const text = await this.git.raw(['cat-file', 'blob', '--end-of-options', sha]);
+        if (size > 0 && text === '')
+            throw new Error(`git cat-file blob ${sha} printed nothing`);
+        return text;
+    }
     async ensureAuthor(author) {
         const config = (await this.git.listConfig());
         // Verify this is a CanopyCMS-managed workspace before setting author

package/dist/item-keys.d.ts

@@ -12,6 +12,14 @@ export declare const ITEM_KEY = "_key";
 export declare const isItemKey: (value: unknown) => value is string;
 /** A new random item key: 12 Base58 characters. */
 export declare function mintItemKey(): string;
+/**
+ * True for a key with the shape {@link contentKey} gives, `h` and a 53-bit hash in at most 10
+ * Base58 digits (`-2` and on for a repeat): one a read wrote down. A key {@link mintItemKey}
+ * minted is 12 digits long, so it never has this shape.
+ */
+export declare const hasContentKeyShape: (key: string) => boolean;
+/** True for a key a read or {@link mintItemKey} wrote, never one a person typed, such as `faq`. */
+export declare const hasMachineKeyShape: (key: string) => boolean;
 /**
  * How `withItemKeys` keys an item that lacks a usable key, or repeats one an earlier item of its
  * list holds:
@@ -31,6 +39,11 @@ type ListField = ObjectFieldConfig | BlockFieldConfig;
 export declare function withItemKeys(fields: readonly FieldConfig[], data: Record<string, unknown>, fill: ItemKeyFill): Record<string, unknown>;
 /** `item`, a copy about to join `field`'s list, with fresh keys for it and every item inside it. */
 export declare function withFreshItemKeys<T>(field: ListField, item: T): T;
+/**
+ * The key a read gives each item of a list, as `withItemKeys` with `content` does: its own usable
+ * key, else a hash of its content. Undefined for an item that isn't a record.
+ */
+export declare const itemKeysAsRead: (items: readonly unknown[]) => Array<string | undefined>;
 /**
  * The keys of the list items on `canopyPath` in `value`, outermost first: what a new field thread
  * stores to name them. Undefined when an item on the path has no usable key or the path isn't

package/dist/item-keys.js

@@ -40,6 +40,14 @@ function contentKey(item) {
     } while (n > 0);
     return `h${out}`;
 }
+/**
+ * True for a key with the shape {@link contentKey} gives, `h` and a 53-bit hash in at most 10
+ * Base58 digits (`-2` and on for a repeat): one a read wrote down. A key {@link mintItemKey}
+ * minted is 12 digits long, so it never has this shape.
+ */
+export const hasContentKeyShape = (key) => /^h[1-9A-HJ-NP-Za-km-z]{1,10}(-\d+)?$/.test(key);
+/** True for a key a read or {@link mintItemKey} wrote, never one a person typed, such as `faq`. */
+export const hasMachineKeyShape = (key) => hasContentKeyShape(key) || /^[1-9A-HJ-NP-Za-km-z]{12}$/.test(key);
 const isListField = (field) => field.type === 'block' || (field.type === 'object' && !!field.list);
 /**
  * `data` with every object-list item and block keyed, each unique in its list, nested lists
@@ -72,6 +80,22 @@ export function withFreshItemKeys(field, item) {
     return keyList(field, [item], 'fresh')[0];
 }
 function keyList(field, items, fill) {
+    const keys = listKeys(items, fill);
+    let changed = false;
+    const out = items.map((item, i) => {
+        if (!isPlainRecord(item))
+            return item;
+        let next = keyInside(field, item, fill);
+        if (keys[i] !== item[ITEM_KEY])
+            next = { ...next, [ITEM_KEY]: keys[i] };
+        if (next !== item)
+            changed = true;
+        return next;
+    });
+    return changed ? out : items;
+}
+/** The key each record of `items` ends with under `fill`; undefined for an item that isn't one. */
+function listKeys(items, fill) {
     const held = new Set();
     if (fill !== 'fresh') {
         for (const item of items) {
@@ -80,27 +104,25 @@ function keyList(field, items, fill) {
         }
     }
     const kept = new Set();
-    let changed = false;
-    const out = items.map((item) => {
+    return items.map((item) => {
         if (!isPlainRecord(item))
-            return item;
-        let next = keyInside(field, item, fill);
+            return undefined;
         const own = item[ITEM_KEY];
         if (fill !== 'fresh' && isItemKey(own) && !kept.has(own)) {
             kept.add(own);
+            return own;
         }
-        else {
-            const key = fill === 'content' ? unheld(contentKey(item), held) : mintItemKey();
-            held.add(key);
-            kept.add(key);
-            next = { ...next, [ITEM_KEY]: key };
-        }
-        if (next !== item)
-            changed = true;
-        return next;
+        const key = fill === 'content' ? unheld(contentKey(item), held) : mintItemKey();
+        held.add(key);
+        kept.add(key);
+        return key;
     });
-    return changed ? out : items;
 }
+/**
+ * The key a read gives each item of a list, as `withItemKeys` with `content` does: its own usable
+ * key, else a hash of its content. Undefined for an item that isn't a record.
+ */
+export const itemKeysAsRead = (items) => listKeys(items, 'content');
 /** `key`, or with a suffix when another item of the list already holds it (identical items). */
 function unheld(key, held) {
     let out = key;

package/dist/merge/conflict-path.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Names a place in a merged entry the way the "Show changes" drawer (`editor/entry-diff.ts`) names
+ * its changes, so a conflict and the drawer's change at the same place share `key` and
+ * `dataPath`: a field the schema knows joins the key with `.`, one it doesn't with `?`, a list item
+ * is named by its key as a read gives it, and a block's data is a `blockData` step.
+ */
+import type { FieldConfig } from '../config/index.js';
+import type { DataPathSegment } from '../editor/entry-diff.js';
+export declare const LOCATION_CONFLICT_KEY = "@location";
+/**
+ * A step the merge took: a record's member, a merged list's item by its place, or, for an item no
+ * longer in the merged list, the key naming it.
+ */
+export type RawSegment = {
+    field: string;
+} | {
+    index: number;
+} | {
+    item: string;
+};
+/**
+ * `at`, a path through `read` (the merged data as a read gives it, so items carry the keys the
+ * drawer names them by), as the drawer's key and data path. The drawer goes into a record the
+ * schema describes, an object list's items and a block whose template resolves; anywhere else it
+ * shows the whole value, so a deeper path is named there: `depth` is how many steps of `at` the
+ * name covers. `field` is the schema's field at the end of the whole path, when the schema reaches
+ * that far.
+ */
+export declare function describePath(fields: readonly FieldConfig[] | undefined, read: unknown, at: readonly RawSegment[]): {
+    key: string;
+    dataPath: DataPathSegment[];
+    depth: number;
+    field?: FieldConfig;
+};
+/**
+ * The drawer's key for the place `dataPath` names in `read`, under `fields`: how a conflict the
+ * worker recorded without the entry's schema, which names an unknown field with `?`, is named with
+ * it. A path deeper than the drawer goes is named where the drawer stops.
+ */
+export declare function keyOfDataPath(fields: readonly FieldConfig[], read: unknown, dataPath: readonly DataPathSegment[]): string;

package/dist/merge/conflict-path.js

@@ -0,0 +1,128 @@
+/**
+ * Names a place in a merged entry the way the "Show changes" drawer (`editor/entry-diff.ts`) names
+ * its changes, so a conflict and the drawer's change at the same place share `key` and
+ * `dataPath`: a field the schema knows joins the key with `.`, one it doesn't with `?`, a list item
+ * is named by its key as a read gives it, and a block's data is a `blockData` step.
+ */
+import { itemKeysAsRead } from '../item-keys.js';
+import { flattenGroupFields } from '../utils/flatten-group-fields.js';
+import { isBlockStructuralKey } from '../validation/block-structural-keys.js';
+import { isPlainRecord } from '../validation/field-traversal.js';
+export const LOCATION_CONFLICT_KEY = '@location';
+const fieldNamed = (scope, name) => scope && flattenGroupFields(scope).find((f) => f.name === name);
+const member = (node, name) => isPlainRecord(node) && Object.prototype.hasOwnProperty.call(node, name) ? node[name] : undefined;
+const readKeys = new WeakMap();
+/** The key a read gives each item of `items`, worked out once per list. */
+const keysOf = (items) => {
+    let keys = readKeys.get(items);
+    if (!keys)
+        readKeys.set(items, (keys = itemKeysAsRead(items)));
+    return keys;
+};
+/**
+ * `at`, a path through `read` (the merged data as a read gives it, so items carry the keys the
+ * drawer names them by), as the drawer's key and data path. The drawer goes into a record the
+ * schema describes, an object list's items and a block whose template resolves; anywhere else it
+ * shows the whole value, so a deeper path is named there: `depth` is how many steps of `at` the
+ * name covers. `field` is the schema's field at the end of the whole path, when the schema reaches
+ * that far.
+ */
+export function describePath(fields, read, at) {
+    let key = '';
+    const dataPath = [];
+    let scope = fields ?? [];
+    let list;
+    let mode = 'record';
+    let field;
+    let node = read;
+    let n = 0;
+    walk: for (; n < at.length; n++) {
+        const segment = at[n];
+        if (mode === 'list') {
+            if ('field' in segment)
+                break;
+            const items = Array.isArray(node) ? node : [];
+            const itemKey = 'item' in segment ? segment.item : (keysOf(items)[segment.index] ?? String(segment.index));
+            key = `${key}.${itemKey}`;
+            dataPath.push({ item: itemKey });
+            node = 'index' in segment ? items[segment.index] : undefined;
+            field = undefined;
+            if (list?.type === 'object') {
+                scope = list.fields ?? [];
+                mode = 'record';
+            }
+            else {
+                mode = 'block';
+            }
+            continue;
+        }
+        if (!('field' in segment))
+            break;
+        if (mode === 'block') {
+            // A block item: canonical `{ template, value }`, or inline `{ _type, ...data }`.
+            const template = member(node, 'template');
+            const inline = member(node, '_type');
+            const name = typeof template === 'string' ? template : inline;
+            const templateFields = list.templates.find((t) => t.name === name)?.fields;
+            if (!templateFields || isBlockStructuralKey(segment.field))
+                break;
+            dataPath.push({ blockData: true });
+            scope = templateFields;
+            mode = 'record';
+            if (typeof template === 'string') {
+                if (segment.field !== 'value')
+                    break;
+                node = member(node, 'value');
+                continue;
+            }
+        }
+        const name = segment.field;
+        field = fieldNamed(scope, name);
+        key = field ? (key ? `${key}.${name}` : name) : `${key}?${name}`;
+        dataPath.push({ field: name });
+        node = member(node, name);
+        if (!field) {
+            n++;
+            break walk;
+        }
+        if (field.type === 'object' && !field.list) {
+            scope = field.fields ?? [];
+        }
+        else if (field.type === 'object' || field.type === 'block') {
+            list = field;
+            mode = 'list';
+        }
+        else {
+            n++;
+            break walk;
+        }
+    }
+    return { key, dataPath, depth: n, ...(n === at.length && field && { field }) };
+}
+/**
+ * The drawer's key for the place `dataPath` names in `read`, under `fields`: how a conflict the
+ * worker recorded without the entry's schema, which names an unknown field with `?`, is named with
+ * it. A path deeper than the drawer goes is named where the drawer stops.
+ */
+export function keyOfDataPath(fields, read, dataPath) {
+    const at = [];
+    let node = read;
+    for (const segment of dataPath) {
+        if ('field' in segment) {
+            at.push({ field: segment.field });
+            node = member(node, segment.field);
+        }
+        else if ('item' in segment) {
+            const items = Array.isArray(node) ? node : [];
+            const index = keysOf(items).indexOf(segment.item);
+            at.push(index >= 0 ? { index } : { item: segment.item });
+            node = index >= 0 ? items[index] : undefined;
+        }
+        else if (typeof member(node, 'template') === 'string') {
+            // A canonical block's data is its `value`; an inline block's is the item itself.
+            at.push({ field: 'value' });
+            node = member(node, 'value');
+        }
+    }
+    return describePath(fields, read, at).key;
+}

package/dist/merge/diff3.d.ts

@@ -0,0 +1,27 @@
+/**
+ * diff3 over sequences of strings: where the base and the branch each changed the ancestor, as
+ * regions that are either one version's run of elements or a run both sides changed. Built on
+ * jsdiff's Myers diff, which stays fast on long input with many equal elements (blank lines, a
+ * repeated tag), where an LCS by candidate lists grows with the cube of the length on such input.
+ */
+/** A run `[start, end)` of one version. */
+type Span = [number, number];
+export type Diff3Region = {
+    stable: true;
+    side: 'ancestor' | 'base' | 'branch';
+    span: Span;
+} | {
+    stable: false;
+    ancestor: Span;
+    base: Span;
+    branch: Span;
+};
+/** The pairs of equal elements a Myers diff keeps, in order; undefined when it ran out of time. */
+export declare function commonPairs(x: readonly string[], y: readonly string[]): Array<[number, number]> | undefined;
+/**
+ * The regions of a three-way merge of `base` and `branch` from `ancestor`, in order: hunks of the
+ * two sides that overlap or touch in the ancestor make one unstable region, as in GNU diff3 and
+ * git. Undefined when a diff ran out of time.
+ */
+export declare function diff3Regions(ancestor: readonly string[], base: readonly string[], branch: readonly string[]): Diff3Region[] | undefined;
+export {};

package/dist/merge/diff3.js

@@ -0,0 +1,113 @@
+/**
+ * diff3 over sequences of strings: where the base and the branch each changed the ancestor, as
+ * regions that are either one version's run of elements or a run both sides changed. Built on
+ * jsdiff's Myers diff, which stays fast on long input with many equal elements (blank lines, a
+ * repeated tag), where an LCS by candidate lists grows with the cube of the length on such input.
+ */
+import { diffArrays } from 'diff';
+/** How long one two-way diff may take before the caller treats the value as one whole. */
+const DIFF_TIMEOUT_MS = 500;
+/** Where `changed` differs from `ancestor`, as hunks; undefined when the diff ran out of time. */
+function hunks(ancestor, changed, side) {
+    const changes = diffArrays([...ancestor], [...changed], { timeout: DIFF_TIMEOUT_MS });
+    if (!changes)
+        return undefined;
+    const out = [];
+    let [o, x] = [0, 0];
+    let open;
+    for (const change of changes) {
+        const count = change.count ?? change.value.length;
+        if (!change.added && !change.removed) {
+            open = undefined;
+            o += count;
+            x += count;
+            continue;
+        }
+        if (!open) {
+            open = { side, ancestor: [o, o], changed: [x, x] };
+            out.push(open);
+        }
+        if (change.removed)
+            open.ancestor[1] = o += count;
+        else
+            open.changed[1] = x += count;
+    }
+    return out;
+}
+/** The pairs of equal elements a Myers diff keeps, in order; undefined when it ran out of time. */
+export function commonPairs(x, y) {
+    const changes = diffArrays([...x], [...y], { timeout: DIFF_TIMEOUT_MS });
+    if (!changes)
+        return undefined;
+    const pairs = [];
+    let [i, j] = [0, 0];
+    for (const change of changes) {
+        const count = change.count ?? change.value.length;
+        if (change.added)
+            j += count;
+        else if (change.removed)
+            i += count;
+        else
+            for (let n = 0; n < count; n++)
+                pairs.push([i++, j++]);
+    }
+    return pairs;
+}
+/**
+ * The regions of a three-way merge of `base` and `branch` from `ancestor`, in order: hunks of the
+ * two sides that overlap or touch in the ancestor make one unstable region, as in GNU diff3 and
+ * git. Undefined when a diff ran out of time.
+ */
+export function diff3Regions(ancestor, base, branch) {
+    const baseHunks = hunks(ancestor, base, 'base');
+    const branchHunks = hunks(ancestor, branch, 'branch');
+    if (!baseHunks || !branchHunks)
+        return undefined;
+    const all = [...baseHunks, ...branchHunks].sort((p, q) => p.ancestor[0] - q.ancestor[0]);
+    const regions = [];
+    let at = 0;
+    const advanceTo = (end) => {
+        if (end > at)
+            regions.push({ stable: true, side: 'ancestor', span: [at, end] });
+        at = Math.max(at, end);
+    };
+    for (let n = 0; n < all.length;) {
+        const first = all[n];
+        const [start] = first.ancestor;
+        let end = first.ancestor[1];
+        const group = [first];
+        for (n++; n < all.length && all[n].ancestor[0] <= end; n++) {
+            end = Math.max(end, all[n].ancestor[1]);
+            group.push(all[n]);
+        }
+        advanceTo(start);
+        if (group.length === 1) {
+            const { side, changed } = first;
+            if (changed[1] > changed[0])
+                regions.push({ stable: true, side, span: changed });
+        }
+        else {
+            // Each side's run: its own hunks' extent, widened by the ancestor lines it left alone at
+            // the edges of the region.
+            const sideSpan = (side) => {
+                const own = group.filter((h) => h.side === side);
+                if (own.length === 0)
+                    return [start, end];
+                const lo = Math.min(...own.map((h) => h.changed[0]));
+                const hi = Math.max(...own.map((h) => h.changed[1]));
+                const oLo = Math.min(...own.map((h) => h.ancestor[0]));
+                const oHi = Math.max(...own.map((h) => h.ancestor[1]));
+                return [lo - (oLo - start), hi + (end - oHi)];
+            };
+            regions.push({
+                stable: false,
+                ancestor: [start, end],
+                base: sideSpan('base'),
+                branch: sideSpan('branch'),
+            });
+        }
+        at = Math.max(at, end);
+    }
+    advanceTo(ancestor.length);
+    return regions;
+}

package/dist/merge/entry-merge.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 type { ContentFormat, FieldConfig } from '../config/index.js';
+import type { DataPathSegment } from '../editor/entry-diff.js';
+import { type TextConflictRegion } from './text-merge.js';
+/** One version of an entry: its raw data, its md/mdx body, and its entry type (from its name). */
+export interface MergeSide {
+    data: Record<string, unknown>;
+    body?: string;
+    entryType?: string;
+}
+export interface EntryMergeInput {
+    format: ContentFormat;
+    ancestor: MergeSide;
+    base: MergeSide;
+    branch: MergeSide;
+    /** The branch's entry type's fields, when the caller has them. */
+    fields?: readonly FieldConfig[];
+}
+/**
+ * - `changed`: changed differently on both sides, or added on both with different values;
+ * - `removed-on-base`: the base removed it and the branch changed it;
+ * - `removed-by-you`: the branch removed it and the base changed it.
+ */
+export type FieldConflictKind = 'changed' | 'removed-on-base' | 'removed-by-you';
+export interface FieldConflict {
+    /** The drawer's `EntryChange.key` for this place: list items named by key. */
+    key: string;
+    dataPath: DataPathSegment[];
+    /**
+     * Where each version holds this place, as a read of that version names it: a list item the merge
+     * paired with another side's can read under another key there, as one in a list a side left
+     * keyless does. Absent for a version without the place.
+     */
+    sidePaths: SidePaths;
+    kind: FieldConflictKind;
+    /** A whole list item or block, rather than a field's value. */
+    item?: true;
+    /** Each version's value; absent where that version doesn't have it. */
+    ancestor?: unknown;
+    base?: unknown;
+    branch?: unknown;
+    /** Long text: the regions both sides changed; the rest of the text merged. */
+    regions?: TextConflictRegion[];
+    /** The line merge of an mdx body or field did not parse, so the whole value is the conflict. */
+    unparseable?: true;
+}
+/** Each version's own data path to a place. */
+export interface SidePaths {
+    ancestor?: DataPathSegment[];
+    base?: DataPathSegment[];
+    branch?: DataPathSegment[];
+}
+/**
+ * A list item whose key the merge changed from the branch's to the base's: the branch's comment
+ * threads that name `from` inside the items `within` (the branch's keys, outermost first) now
+ * name `to`.
+ */
+export interface KeyRemap {
+    within: string[];
+    from: string;
+    to: string;
+}
+export type EntryMergeResult = {
+    kind: 'merged';
+    data: Record<string, unknown>;
+    body?: string;
+    conflicts: FieldConflict[];
+    keyRemaps: KeyRemap[];
+}
+/** The entry type changed on one side and the content on the other: no field merge applies. */
+ | {
+    kind: 'entry-conflict';
+    reason: 'entry-type';
+};
+export declare function mergeEntry({ format, ancestor, base, branch, fields, }: EntryMergeInput): EntryMergeResult;
+/**
+ * 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 declare function mergeCollectionMeta(ancestor: Record<string, unknown>, base: Record<string, unknown>, branch: Record<string, unknown>): {
+    data: Record<string, unknown>;
+    conflicts: FieldConflict[];
+};