@adecore/merge 0.21.1 → 0.22.0

package/README.md

@@ -24,8 +24,8 @@ for (const [index, block] of blocks.entries()) {
 const text = joinLines(draftOf(blocks, answers).lines, shapeOf(ours));
 ```
 
-The fixed answer above represents a caller's completed decision. Unanswered draft conflicts use ours without markers; saving requires a separate unresolved check. Preserve text shape and verify input versions before writing. The host owns authorization, file access and stale-answer rejection.
+The answer in the example stands for a decision the caller already made. A draft takes ours, without markers, for every conflict that has no answer yet, so check for unresolved conflicts separately before saving. Keep the shape of the text, and check that the inputs are still the versions you read before writing. Authorization, file access and refusing a stale answer are the host's.
 
 Read the [overview](https://adecore.dev/merge/), [lines and diffs](https://adecore.dev/merge/lines) and [three-way merge](https://adecore.dev/merge/three-way).
 
-From the repository root, run `bun run --cwd packages/merge test`, `typecheck` or `build`. The isolated `test:memory` command checks bounded diff memory workloads. A source-relative example is in [examples/resolve-conflict.ts](./examples/resolve-conflict.ts).
+From the repository root, run `bun run --cwd packages/merge test`, `typecheck` or `build`. `test:memory` runs on its own and checks that a diff of two large files stays under 20 MB. [examples/resolve-conflict.ts](./examples/resolve-conflict.ts) is a whole example that imports the source.

package/dist/blocks.js

@@ -22,7 +22,7 @@ function delta(change) {
  * The three versions of a file as the stretches they agree and disagree on, in reading order. A
  * stretch is taken up by both sides at once only where their changes overlap in the base, or where
  * both added something in exactly the same place; anything else is one side's alone and merges
- * without asking. This is what every other function here counts, draws and resolves.
+ * without asking.
  */
 export function splitBlocks(base, ours, theirs) {
     const ourChanges = diffLines(base, ours);

package/dist/diff.js

@@ -1,16 +1,16 @@
-/*
- * How far apart two files may be before the exact walk costs more than the answer is worth. Past
- * this the two are answered as one stretch that differs whole, which reads as a single conflict
- * instead of a list nobody would work through anyway.
- */
+/* Past this edit distance two files are answered as one stretch that differs whole. */
 const MAX_DISTANCE = 4000;
 /* The walk keeps every STRIDE-th state and walks the rounds between two again on the way back: a
    state per round came to over a hundred megabytes at MAX_DISTANCE. */
 const STRIDE = 64;
+/* Whether a diagonal's furthest reach steps in from diagonal + 1 (an insert) rather than diagonal - 1 (a delete). */
+function cameDown(reach, offset, diagonal, distance) {
+    return diagonal === -distance || (diagonal !== distance && reach[offset + diagonal - 1] < reach[offset + diagonal + 1]);
+}
 /* One round of the walk: every diagonal of this distance taken as far as its lines match. True once the far corner is reached. */
 function extend(left, right, reach, offset, distance) {
     for (let diagonal = -distance; diagonal <= distance; diagonal += 2) {
-        const down = diagonal === -distance || (diagonal !== distance && reach[offset + diagonal - 1] < reach[offset + diagonal + 1]);
+        const down = cameDown(reach, offset, diagonal, distance);
         let x = down ? reach[offset + diagonal + 1] : reach[offset + diagonal - 1] + 1;
         let y = x - diagonal;
         while (x < left.length && y < right.length && left[x] === right[y]) {
@@ -42,7 +42,7 @@ function backtrack(left, right, saved, distance, offset) {
         for (; step > first; step -= 1) {
             const state = states[step - first];
             const diagonal = x - y;
-            const down = diagonal === -step || (diagonal !== step && state[offset + diagonal - 1] < state[offset + diagonal + 1]);
+            const down = cameDown(state, offset, diagonal, step);
             const previous = down ? diagonal + 1 : diagonal - 1;
             const prevX = state[offset + previous];
             const prevY = prevX - previous;

package/dist/resolve.js

@@ -50,10 +50,9 @@ function covers(base, outer, inner) {
     return added.every((line) => !base.includes(line) || inner.includes(line));
 }
 /*
- * What the wand makes of a conflict, or null for one that needs a person after all. It closes the
- * two nobody would think twice about: the sides that differ only in whitespace inside or after a
- * line, and the side that already holds every line of the other without putting back what the other
- * deleted. Anything else is a choice, and a wand that guesses at those is a wand nobody trusts twice.
+ * What the wand makes of a conflict, or null for one that needs a person after all. It closes only
+ * sides that differ in whitespace inside or after a line, and a side that already holds every line
+ * of the other without putting back what the other deleted. Anything else is a choice it never guesses.
  */
 export function wandLines(block) {
     if (block.kind !== 'conflict') {
@@ -72,9 +71,8 @@ export function wandLines(block) {
 }
 /*
  * A short name for the two sides of one block, so an answer written for it can be checked against
- * the block it lands on. Not a secret and not a digest anyone leans on: it only has to differ when
- * the stretch does, and it has to read the same on a daemon and in a browser, which rules out the
- * one hash a browser cannot take synchronously.
+ * the block it lands on. FNV-1a, not a digest: it has to read the same on a server and in a browser,
+ * and a browser has no synchronous crypto hash.
  */
 export function fingerprint(block) {
     let hash = 0x811c9dc5;
@@ -88,10 +86,8 @@ export function fingerprint(block) {
 }
 /*
  * The merged file to start from: everything that merges by itself is merged, and every conflict
- * holds our side until someone says otherwise. Never a conflict marker: what a person edits here is
- * a file that would compile, and the other side is a column away rather than a line below. Blocks
- * that have already been answered are passed in, which is how a proposal lands in a file nobody has
- * open.
+ * holds our side until someone says otherwise. Never a conflict marker, so what a person edits is a
+ * file that would compile. `answered` holds the lines of blocks already resolved, by block index.
  */
 export function draftOf(blocks, answered = new Map()) {
     const lines = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/merge",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Pure line diffs, three-way merge blocks and conflict resolution.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",

package/src/blocks.ts

@@ -40,7 +40,7 @@ function delta(change: Change): number {
  * The three versions of a file as the stretches they agree and disagree on, in reading order. A
  * stretch is taken up by both sides at once only where their changes overlap in the base, or where
  * both added something in exactly the same place; anything else is one side's alone and merges
- * without asking. This is what every other function here counts, draws and resolves.
+ * without asking.
  */
 export function splitBlocks(base: readonly string[], ours: readonly string[], theirs: readonly string[]): MergeBlock[] {
     const ourChanges = diffLines(base, ours);

package/src/diff.ts

@@ -9,11 +9,7 @@ export interface Change {
     otherEnd: number;
 }
 
-/*
- * How far apart two files may be before the exact walk costs more than the answer is worth. Past
- * this the two are answered as one stretch that differs whole, which reads as a single conflict
- * instead of a list nobody would work through anyway.
- */
+/* Past this edit distance two files are answered as one stretch that differs whole. */
 const MAX_DISTANCE = 4000;
 
 /* The walk keeps every STRIDE-th state and walks the rounds between two again on the way back: a
@@ -28,10 +24,15 @@ interface Move {
     y: number;
 }
 
+/* Whether a diagonal's furthest reach steps in from diagonal + 1 (an insert) rather than diagonal - 1 (a delete). */
+function cameDown(reach: Int32Array, offset: number, diagonal: number, distance: number): boolean {
+    return diagonal === -distance || (diagonal !== distance && reach[offset + diagonal - 1]! < reach[offset + diagonal + 1]!);
+}
+
 /* One round of the walk: every diagonal of this distance taken as far as its lines match. True once the far corner is reached. */
 function extend(left: readonly string[], right: readonly string[], reach: Int32Array, offset: number, distance: number): boolean {
     for (let diagonal = -distance; diagonal <= distance; diagonal += 2) {
-        const down = diagonal === -distance || (diagonal !== distance && reach[offset + diagonal - 1]! < reach[offset + diagonal + 1]!);
+        const down = cameDown(reach, offset, diagonal, distance);
         let x = down ? reach[offset + diagonal + 1]! : reach[offset + diagonal - 1]! + 1;
         let y = x - diagonal;
         while (x < left.length && y < right.length && left[x] === right[y]) {
@@ -64,7 +65,7 @@ function backtrack(left: readonly string[], right: readonly string[], saved: rea
         for (; step > first; step -= 1) {
             const state = states[step - first]!;
             const diagonal = x - y;
-            const down = diagonal === -step || (diagonal !== step && state[offset + diagonal - 1]! < state[offset + diagonal + 1]!);
+            const down = cameDown(state, offset, diagonal, step);
             const previous = down ? diagonal + 1 : diagonal - 1;
             const prevX = state[offset + previous]!;
             const prevY = prevX - previous;

package/src/resolve.ts

@@ -60,10 +60,9 @@ function covers(base: readonly string[], outer: readonly string[], inner: readon
 }
 
 /*
- * What the wand makes of a conflict, or null for one that needs a person after all. It closes the
- * two nobody would think twice about: the sides that differ only in whitespace inside or after a
- * line, and the side that already holds every line of the other without putting back what the other
- * deleted. Anything else is a choice, and a wand that guesses at those is a wand nobody trusts twice.
+ * What the wand makes of a conflict, or null for one that needs a person after all. It closes only
+ * sides that differ in whitespace inside or after a line, and a side that already holds every line
+ * of the other without putting back what the other deleted. Anything else is a choice it never guesses.
  */
 export function wandLines(block: MergeBlock): string[] | null {
     if (block.kind !== 'conflict') {
@@ -83,9 +82,8 @@ export function wandLines(block: MergeBlock): string[] | null {
 
 /*
  * A short name for the two sides of one block, so an answer written for it can be checked against
- * the block it lands on. Not a secret and not a digest anyone leans on: it only has to differ when
- * the stretch does, and it has to read the same on a daemon and in a browser, which rules out the
- * one hash a browser cannot take synchronously.
+ * the block it lands on. FNV-1a, not a digest: it has to read the same on a server and in a browser,
+ * and a browser has no synchronous crypto hash.
  */
 export function fingerprint(block: MergeBlock): string {
     let hash = 0x811c9dc5;
@@ -113,10 +111,8 @@ export interface MergeDraft {
 
 /*
  * The merged file to start from: everything that merges by itself is merged, and every conflict
- * holds our side until someone says otherwise. Never a conflict marker: what a person edits here is
- * a file that would compile, and the other side is a column away rather than a line below. Blocks
- * that have already been answered are passed in, which is how a proposal lands in a file nobody has
- * open.
+ * holds our side until someone says otherwise. Never a conflict marker, so what a person edits is a
+ * file that would compile. `answered` holds the lines of blocks already resolved, by block index.
  */
 export function draftOf(blocks: readonly MergeBlock[], answered: ReadonlyMap<number, readonly string[]> = new Map()): MergeDraft {
     const lines: string[] = [];