canopycms 0.12.0 → 0.13.0

package/dist/merge/text-merge.js

@@ -0,0 +1,59 @@
+/**
+ * Line-level three-way merge of long text: a multi-line string, or an md/mdx body. Each side's
+ * changes apply where the other left the lines alone; lines both sides changed differently are a
+ * conflict region. Never writes conflict markers: in a region, the merged text holds the branch's
+ * lines, and the region records all three versions for the person who resolves it.
+ */
+import { diff3Regions } from './diff3.js';
+/** `text` as lines, its one line break at the very end apart. */
+const split = (text) => {
+    const endBreak = text.endsWith('\n');
+    const rest = endBreak ? text.slice(0, -1) : text;
+    return { lines: rest === '' && !endBreak ? [] : rest.split('\n'), endBreak };
+};
+const sameLines = (x, y) => x.length === y.length && x.every((line, i) => line === y[i]);
+/**
+ * `base` and `branch`, both changed from `ancestor`, merged line by line. A line break at the very
+ * end, which a serializer may add or drop by itself, is merged on its own and never makes a
+ * conflict: the side that changed it wins, or the branch in a text with conflicts. Undefined when
+ * the texts are too far apart to diff in time: the caller then treats each version as one whole.
+ */
+export function mergeText(ancestor, base, branch) {
+    const o = split(ancestor);
+    const a = split(base);
+    const b = split(branch);
+    const regions = diff3Regions(o.lines, a.lines, b.lines);
+    if (!regions)
+        return undefined;
+    const versions = { ancestor: o.lines, base: a.lines, branch: b.lines };
+    const out = [];
+    const conflicts = [];
+    for (const region of regions) {
+        if (region.stable) {
+            out.push(...versions[region.side].slice(...region.span));
+            continue;
+        }
+        const [oLines, aLines, bLines] = [
+            o.lines.slice(...region.ancestor),
+            a.lines.slice(...region.base),
+            b.lines.slice(...region.branch),
+        ];
+        if (sameLines(aLines, bLines)) {
+            out.push(...bLines);
+            continue;
+        }
+        conflicts.push({
+            ancestor: oLines.join('\n'),
+            base: aLines.join('\n'),
+            branch: bLines.join('\n'),
+            line: out.length,
+            lines: bLines.length,
+            baseLines: aLines.length,
+        });
+        out.push(...bLines);
+    }
+    // A conflicted text holds the branch's lines, so it holds the branch's end too.
+    const endBreak = conflicts.length > 0 || o.endBreak === a.endBreak ? b.endBreak : a.endBreak;
+    const body = out.join('\n');
+    return { text: endBreak ? `${body}\n` : body, regions: conflicts };
+}

package/dist/merge/value-equality.d.ts

@@ -0,0 +1,18 @@
+/**
+ * When two content values count as the same, for every comparison of entry versions: the "Show
+ * changes" drawer (`editor/entry-diff.ts`) and the field merge (`entry-merge.ts`) both use it, so a
+ * value the drawer calls unchanged is one the merge never calls a conflict.
+ */
+/** Absent, null, `''`, `[]`, or a record holding nothing but those and an item key. */
+export declare const isEmptyValue: (value: unknown) => boolean;
+/** `value` without item keys and empty members, so equal content compares equal. */
+export declare const normalizedValue: (value: unknown) => unknown;
+/** A string naming `value` exactly: equal for two values exactly when they hold the same. */
+export declare const exactToken: (value: unknown) => string;
+/**
+ * A string naming `value` up to {@link sameValue}: two values share a token exactly when they are
+ * the same, so a sequence of values can be aligned as a sequence of strings.
+ */
+export declare const valueToken: (value: unknown) => string;
+/** The same content: item keys and empty members aside, and every empty value alike. */
+export declare const sameValue: (a: unknown, b: unknown) => boolean;

package/dist/merge/value-equality.js

@@ -0,0 +1,50 @@
+/**
+ * When two content values count as the same, for every comparison of entry versions: the "Show
+ * changes" drawer (`editor/entry-diff.ts`) and the field merge (`entry-merge.ts`) both use it, so a
+ * value the drawer calls unchanged is one the merge never calls a conflict.
+ */
+import { ITEM_KEY } from '../item-keys.js';
+import { isPlainRecord } from '../validation/field-traversal.js';
+/** `value`'s own members, `__proto__` included as a member like any other. */
+const members = (value) => Object.entries(value);
+/** Absent, null, `''`, `[]`, or a record holding nothing but those and an item key. */
+export const isEmptyValue = (value) => value === undefined ||
+    value === null ||
+    value === '' ||
+    (Array.isArray(value) && value.length === 0) ||
+    (isPlainRecord(value) && members(value).every(([k, v]) => k === ITEM_KEY || isEmptyValue(v)));
+/** `value` without item keys and empty members, so equal content compares equal. */
+export const normalizedValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(normalizedValue);
+    if (!isPlainRecord(value))
+        return value;
+    return Object.fromEntries(members(value)
+        .filter(([k, v]) => k !== ITEM_KEY && !isEmptyValue(v))
+        .map(([k, v]) => [k, normalizedValue(v)]));
+};
+/** A string naming `value` exactly: equal for two values exactly when they hold the same. */
+export const exactToken = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(exactToken).join(',')}]`;
+    if (value instanceof Date)
+        return `D${value.getTime()}`;
+    if (isPlainRecord(value)) {
+        const sorted = members(value).sort(([x], [y]) => (x < y ? -1 : x > y ? 1 : 0));
+        return `{${sorted.map(([k, v]) => `${JSON.stringify(k)}:${exactToken(v)}`).join(',')}}`;
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number')
+        return Object.is(value, -0) ? '0' : String(value);
+    if (typeof value === 'bigint')
+        return `${value}n`;
+    return String(value);
+};
+/**
+ * A string naming `value` up to {@link sameValue}: two values share a token exactly when they are
+ * the same, so a sequence of values can be aligned as a sequence of strings.
+ */
+export const valueToken = (value) => isEmptyValue(value) ? '' : exactToken(normalizedValue(value));
+/** The same content: item keys and empty members aside, and every empty value alike. */
+export const sameValue = (a, b) => valueToken(a) === valueToken(b);

package/dist/merge-conflicts.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The conflicts the worker's merges found on a branch and nobody has resolved yet:
+ * `.canopy-meta/merge-conflicts.json` in the branch clone, never committed, one record per entry.
+ * The working tree holds the author's value at each one (merge/entry-merge.ts), so nothing here is
+ * needed to read the branch; it is what says which values a person still has to choose.
+ *
+ * `branch.json` `conflictFiles` is derived from it: the content IDs it names, none for a clone with
+ * no such file (`reconcileMergeConflicts`, worker/github-commits.ts).
+ *
+ * Writers run under the comment store's three layers (comment-store.ts): the in-process mutex, the
+ * cross-host lockfile, then version OCC. The worker writes it holding the branch's provisioning and
+ * content-write locks.
+ */
+import type { DataPathSegment } from './editor/entry-diff.js';
+import type { FieldConflictKind, KeyRemap, SidePaths } from './merge/entry-merge.js';
+import type { ContentId } from './paths/types.js';
+import type { ConflictStatus } from './types.js';
+/** A record field naming where the entry is, which both sides moved to different places. */
+export { LOCATION_CONFLICT_KEY } from './merge/conflict-path.js';
+/** Blob ids of the versions a merge compared; absent where that version had no file. */
+export interface MergeSides {
+    ancestor?: string;
+    base?: string;
+    branch?: string;
+}
+/**
+ * - `fields`: values changed differently on both sides, listed in `fields`;
+ * - `deleted-on-base`: the base deleted the entry and the branch changed it; the branch's stands;
+ * - `deleted-on-branch`: the branch deleted it and the base changed it; it stays deleted;
+ * - `unreadable`: a version that can't be merged field by field (it does not parse, is over the
+ *   size cap, changed its entry type, or is not an entry at all); the branch's file stands.
+ */
+export type MergeConflictKind = 'fields' | 'deleted-on-base' | 'deleted-on-branch' | 'unreadable';
+export interface MergeConflictField {
+    /** `entry-diff.ts`' `EntryChange.key` for the place, or {@link LOCATION_CONFLICT_KEY}. */
+    key: string;
+    dataPath: DataPathSegment[];
+    /**
+     * Where each of `sides`' versions holds the value, as a read of that version names it
+     * (merge/entry-merge.ts `FieldConflict.sidePaths`); `ancestor`'s is the first ancestor's.
+     */
+    sidePaths: SidePaths;
+    kind: FieldConflictKind;
+    item?: true;
+    /** Long text, merged by line: the regions both sides changed come from the three blobs. */
+    text?: true;
+    /** The merge that last found it. */
+    mergeSha: string;
+    /**
+     * The ancestor of the merge that first found it, which is what the author started from, and the
+     * base and branch of the merge that last found it.
+     */
+    sides: MergeSides;
+}
+export interface MergeConflictEntry {
+    /** Where the entry is in the merged tree, or was for one the branch deleted. */
+    path: string;
+    /** The merge that last changed this record. */
+    mergeSha: string;
+    kind: MergeConflictKind;
+    sides: MergeSides;
+    /** For `fields`, never empty. */
+    fields?: MergeConflictField[];
+    /**
+     * The record as it stood before `mergeSha` changed it, kept until the branch holds that merge:
+     * a merge recorded and then never landed gives the record back. Absent once it lands, and for a
+     * record that merge created.
+     */
+    previous?: MergeConflictEntry;
+}
+/** Item keys a merge changed, which the branch's comment threads take once it holds the merge. */
+interface PendingRemap {
+    mergeSha: string;
+    /** The logical path the threads name the entry by. */
+    entryPath: string;
+    remaps: KeyRemap[];
+}
+/** What the file holds. */
+export interface MergeConflictState {
+    entries: Record<string, MergeConflictEntry>;
+    remaps?: PendingRemap[];
+    /**
+     * The merge this worker is landing: written before it reaches `remote.git`, cleared once the
+     * clone holds it, or once neither the clone nor `remote.git` does; a clone whose ref can't be read
+     * keeps it. The one commit a clone left
+     * behind its own published merge may catch up with.
+     */
+    landing?: Landing;
+    /**
+     * A record that didn't parse was set aside: which conflicts it held is lost, so Submit and Approve
+     * wait ({@link assertNoOpenConflicts}) until an admin releases the branch. A later merge does not:
+     * it takes the set-aside merge as merged, so the lost choices would read as the branch's own.
+     * {@link MergeConflictStore.update} keeps it through a change that leaves it out.
+     */
+    held?: Held;
+}
+interface Held {
+    /** The name the unparseable file was moved aside to, in `.canopy-meta`. */
+    aside: string;
+    at: string;
+}
+interface Landing {
+    mergeSha: string;
+    /** For a merge of GitHub's commits, the paths whose values the branch kept over them. */
+    keptOverGitHub?: string[];
+}
+export interface MergeConflictsFile extends MergeConflictState {
+    version: number;
+    writeId?: string;
+}
+/** What one merge found for one entry, before it has a commit to name. */
+export interface FoundEntryConflict {
+    contentId: ContentId;
+    path: string;
+    kind: MergeConflictKind;
+    sides: MergeSides;
+    fields?: Array<Omit<MergeConflictField, 'mergeSha' | 'sides'>>;
+}
+/**
+ * merge-conflicts.json names another format than this module reads, `found`. It is left as it is,
+ * unlike a file that doesn't parse: a worker of that format reads it, and its choices would be lost
+ * if it were set aside. The worker's next merge refuses it too, so the branch shows as failing to
+ * take its base in until the file is dealt with.
+ */
+export declare class MergeConflictsFileFormatError extends Error {
+    readonly found: number;
+    constructor(found: number);
+}
+/** merge-conflicts.json is there but is not a record this module wrote. */
+export declare class MergeConflictsFileMalformedError extends Error {
+    constructor(detail: string);
+}
+/**
+ * `existing` with what one merge, `mergeSha`, found. An entry this merge found no conflict in keeps
+ * its record: its value is still the author's, which this merge took as the branch's own change.
+ * A field found again keeps the ancestor it was first found against, and that ancestor's path, so
+ * the person still sees what they started from, and takes this merge's base and branch. An
+ * entry-level conflict replaces the entry's record; an `unreadable` record stands against fields
+ * found later, taking this merge's base and branch. `paths` moves the kept records of entries this
+ * merge moved. Every record this merge changes keeps the one it replaced as `previous`. Pure.
+ */
+export declare function withFoundConflicts(existing: Readonly<Record<string, MergeConflictEntry>>, found: readonly FoundEntryConflict[], mergeSha: string, paths?: ReadonlyMap<string, string>): Record<string, MergeConflictEntry>;
+/** The item keys one merge changed in one entry, which the entry's records follow. */
+export interface EntryKeyRemaps {
+    contentId?: string;
+    remaps: readonly KeyRemap[];
+}
+/**
+ * `entries` with the item keys a merge, `mergeSha`, changed renamed in the conflicts on record,
+ * as the branch's comment threads are, so a conflict found again under the new key is the same
+ * one. A record this renames keeps the one it replaced as `previous`, so a merge that never lands
+ * gives the old keys back. Pure.
+ */
+export declare function withRemappedItemKeys(entries: Readonly<Record<string, MergeConflictEntry>>, remaps: readonly EntryKeyRemaps[], mergeSha: string): Record<string, MergeConflictEntry>;
+/**
+ * `entries` as the branch's history has them: a record whose `mergeSha` fails `holds` gives back the
+ * one it replaced, or goes when it replaced none, and a record whose merge the branch holds drops
+ * the one it replaced. A field whose own merge fails `holds` goes too, and an entry with no field
+ * left. Pure.
+ */
+export declare function withoutMergesGone(entries: Readonly<Record<string, MergeConflictEntry>>, holds: (mergeSha: string) => boolean): Record<string, MergeConflictEntry>;
+/** A field conflict a person resolved, named as the record names it. */
+export interface ResolvedFieldConflict {
+    mergeSha: string;
+    key: string;
+}
+/**
+ * `entries` without the fields of `contentId`'s record that `resolved` names, each by its own
+ * `mergeSha` and `key`, and without the record once no field is left. A pair the record no longer
+ * holds, as after a newer merge found that field again, is left out of `cleared`. A record left with
+ * fields keeps its `previous`; a record left with none goes with it, since a merge keeps every field
+ * the record it replaced held, so those were resolved too. Pure.
+ */
+export declare function withoutResolvedFields(entries: Readonly<Record<string, MergeConflictEntry>>, contentId: string, resolved: readonly ResolvedFieldConflict[]): {
+    entries: Record<string, MergeConflictEntry>;
+    cleared: ResolvedFieldConflict[];
+};
+/**
+ * `entries` without `contentId`'s entry-level record, when `mergeSha` is the merge that last changed
+ * it; null when it is not there, or a later merge changed it. Pure.
+ */
+export declare function withoutEntryConflict(entries: Readonly<Record<string, MergeConflictEntry>>, contentId: string, mergeSha: string): Record<string, MergeConflictEntry> | null;
+/** How many choices `entries` leave a person: each field conflict, and each entry-level one. */
+export declare function openConflictCount(entries: Readonly<Record<string, MergeConflictEntry>>): number;
+/** What `branch.json` holds for `entries`: the content IDs with a conflict open, sorted. */
+export declare function conflictFilesOf(entries: Readonly<Record<string, MergeConflictEntry>>): {
+    conflictStatus: ConflictStatus;
+    conflictFiles: ContentId[];
+};
+/**
+ * A submit or approval refused while the branch has conflicts open, `count` of them, or with none
+ * it can count (`count` null): a record that doesn't parse, which the worker's next cycle sets aside
+ * and holds; one held after that (`held`); or one of another format, left until a developer deals
+ * with it.
+ */
+export declare class OpenMergeConflictsError extends Error {
+    readonly count: number | null;
+    /** The record was set aside as unparseable, so which conflicts are open is lost. */
+    readonly held: boolean;
+    constructor(count: number | null, 
+    /** The record was set aside as unparseable, so which conflicts are open is lost. */
+    held?: boolean);
+}
+/**
+ * Throws {@link OpenMergeConflictsError} while `branchRoot`'s record holds a conflict, is held after
+ * one was set aside, or does not parse. A clone with no record has none open.
+ */
+export declare function assertNoOpenConflicts(branchRoot: string): Promise<void>;
+/** A branch clone's merge-conflicts.json. */
+export declare class MergeConflictStore {
+    private readonly settleMs?;
+    private readonly filePath;
+    constructor(branchRoot: string, settleMs?: number | undefined);
+    /** Whether the clone has a record at all. */
+    exists(): Promise<boolean>;
+    /**
+     * Copy a file that does not parse as a record aside, and replace it with a new one that is
+     * `held`, as which conflicts were open is lost with it. Resolves the copy's path, or null when
+     * the file parses by the time the locks are held, as another call may have set it aside.
+     * The new record is written beside the file and renamed over it, so a worker killed at any step
+     * leaves a record that still refuses the gate: the damaged one, or the held one.
+     */
+    quarantine(): Promise<string | null>;
+    /** The record, or null when the clone has none. Throws on a file that does not parse as one. */
+    read(): Promise<MergeConflictsFile | null>;
+    /**
+     * Replace what the file holds with what `change` makes of it, under the module's locks. `change`
+     * gets null when there is no file yet, and returns null to write nothing; a `held` it leaves out
+     * stays. Resolves what was written, or null.
+     */
+    update(change: (current: MergeConflictState | null) => MergeConflictState | null): Promise<MergeConflictState | null>;
+}