decidim 0.26.2 → 0.26.4

data/packages/webpacker/node_modules/diff-sequences/README.md

@@ -0,0 +1,404 @@
+# diff-sequences
+
+Compare items in two sequences to find a **longest common subsequence**.
+
+The items not in common are the items to delete or insert in a **shortest edit script**.
+
+To maximize flexibility and minimize memory, you write **callback** functions as configuration:
+
+**Input** function `isCommon(aIndex, bIndex)` compares items at indexes in the sequences and returns a truthy/falsey value. This package might call your function more than once for some pairs of indexes.
+
+- Because your function encapsulates **comparison**, this package can compare items according to `===` operator, `Object.is` method, or other criterion.
+- Because your function encapsulates **sequences**, this package can find differences in arrays, strings, or other data.
+
+**Output** function `foundSubsequence(nCommon, aCommon, bCommon)` receives the number of adjacent items and starting indexes of each common subsequence. If sequences do not have common items, then this package does not call your function.
+
+If N is the sum of lengths of sequences and L is length of a longest common subsequence, then D = N – 2L is the number of **differences** in the corresponding shortest edit script.
+
+[_An O(ND) Difference Algorithm and Its Variations_](http://xmailserver.org/diff2.pdf) by Eugene W. Myers is fast when sequences have **few** differences.
+
+This package implements the **linear space** variation with optimizations so it is fast even when sequences have **many** differences.
+
+## Usage
+
+To add this package as a dependency of a project, do either of the following:
+
+- `npm install diff-sequences`
+- `yarn add diff-sequences`
+
+To use `diff` as the name of the default export from this package, do either of the following:
+
+- `var diff = require('diff-sequences').default; // CommonJS modules`
+- `import diff from 'diff-sequences'; // ECMAScript modules`
+
+Call `diff` with the **lengths** of sequences and your **callback** functions:
+
+```js
+const a = ['a', 'b', 'c', 'a', 'b', 'b', 'a'];
+const b = ['c', 'b', 'a', 'b', 'a', 'c'];
+
+function isCommon(aIndex, bIndex) {
+  return a[aIndex] === b[bIndex];
+}
+function foundSubsequence(nCommon, aCommon, bCommon) {
+  // see examples
+}
+
+diff(a.length, b.length, isCommon, foundSubsequence);
+```
+
+## Example of longest common subsequence
+
+Some sequences (for example, `a` and `b` in the example of usage) have more than one longest common subsequence.
+
+This package finds the following common items:
+
+| comparisons of common items      | values     |            output arguments |
+| :------------------------------- | :--------- | --------------------------: |
+| `a[2] === b[0]`                  | `'c'`      | `foundSubsequence(1, 2, 0)` |
+| `a[4] === b[1]`                  | `'b'`      | `foundSubsequence(1, 4, 1)` |
+| `a[5] === b[3] && a[6] === b[4]` | `'b', 'a'` | `foundSubsequence(2, 5, 3)` |
+
+The “edit graph” analogy in the Myers paper shows the following common items:
+
+| comparisons of common items      | values     |
+| :------------------------------- | :--------- |
+| `a[2] === b[0]`                  | `'c'`      |
+| `a[3] === b[2] && a[4] === b[3]` | `'a', 'b'` |
+| `a[6] === b[4]`                  | `'a'`      |
+
+Various packages which implement the Myers algorithm will **always agree** on the **length** of a longest common subsequence, but might **sometimes disagree** on which **items** are in it.
+
+## Example of callback functions to count common items
+
+```js
+// Return length of longest common subsequence according to === operator.
+function countCommonItems(a, b) {
+  let n = 0;
+  function isCommon(aIndex, bIndex) {
+    return a[aIndex] === b[bIndex];
+  }
+  function foundSubsequence(nCommon) {
+    n += nCommon;
+  }
+
+  diff(a.length, b.length, isCommon, foundSubsequence);
+
+  return n;
+}
+
+const commonLength = countCommonItems(
+  ['a', 'b', 'c', 'a', 'b', 'b', 'a'],
+  ['c', 'b', 'a', 'b', 'a', 'c'],
+);
+```
+
+| category of items  |                expression | value |
+| :----------------- | ------------------------: | ----: |
+| in common          |            `commonLength` |   `4` |
+| to delete from `a` | `a.length - commonLength` |   `3` |
+| to insert from `b` | `b.length - commonLength` |   `2` |
+
+If the length difference `b.length - a.length` is:
+
+- negative: its absolute value is the minimum number of items to **delete** from `a`
+- positive: it is the minimum number of items to **insert** from `b`
+- zero: there is an **equal** number of items to delete from `a` and insert from `b`
+- non-zero: there is an equal number of **additional** items to delete from `a` and insert from `b`
+
+In this example, `6 - 7` is:
+
+- negative: `1` is the minimum number of items to **delete** from `a`
+- non-zero: `2` is the number of **additional** items to delete from `a` and insert from `b`
+
+## Example of callback functions to find common items
+
+```js
+// Return array of items in longest common subsequence according to Object.is method.
+const findCommonItems = (a, b) => {
+  const array = [];
+  diff(
+    a.length,
+    b.length,
+    (aIndex, bIndex) => Object.is(a[aIndex], b[bIndex]),
+    (nCommon, aCommon) => {
+      for (; nCommon !== 0; nCommon -= 1, aCommon += 1) {
+        array.push(a[aCommon]);
+      }
+    },
+  );
+  return array;
+};
+
+const commonItems = findCommonItems(
+  ['a', 'b', 'c', 'a', 'b', 'b', 'a'],
+  ['c', 'b', 'a', 'b', 'a', 'c'],
+);
+```
+
+| `i` | `commonItems[i]` | `aIndex` |
+| --: | :--------------- | -------: |
+| `0` | `'c'`            |      `2` |
+| `1` | `'b'`            |      `4` |
+| `2` | `'b'`            |      `5` |
+| `3` | `'a'`            |      `6` |
+
+## Example of callback functions to diff index intervals
+
+Instead of slicing array-like objects, you can adjust indexes in your callback functions.
+
+```js
+// Diff index intervals that are half open [start, end) like array slice method.
+const diffIndexIntervals = (a, aStart, aEnd, b, bStart, bEnd) => {
+  // Validate: 0 <= aStart and aStart <= aEnd and aEnd <= a.length
+  // Validate: 0 <= bStart and bStart <= bEnd and bEnd <= b.length
+
+  diff(
+    aEnd - aStart,
+    bEnd - bStart,
+    (aIndex, bIndex) => Object.is(a[aStart + aIndex], b[bStart + bIndex]),
+    (nCommon, aCommon, bCommon) => {
+      // aStart + aCommon, bStart + bCommon
+    },
+  );
+
+  // After the last common subsequence, do any remaining work.
+};
+```
+
+## Example of callback functions to emulate diff command
+
+Linux or Unix has a `diff` command to compare files line by line. Its output is a **shortest edit script**:
+
+- **c**hange adjacent lines from the first file to lines from the second file
+- **d**elete lines from the first file
+- **a**ppend or insert lines from the second file
+
+```js
+// Given zero-based half-open range [start, end) of array indexes,
+// return one-based closed range [start + 1, end] as string.
+const getRange = (start, end) =>
+  start + 1 === end ? `${start + 1}` : `${start + 1},${end}`;
+
+// Given index intervals of lines to delete or insert, or both, or neither,
+// push formatted diff lines onto array.
+const pushDelIns = (aLines, aIndex, aEnd, bLines, bIndex, bEnd, array) => {
+  const deleteLines = aIndex !== aEnd;
+  const insertLines = bIndex !== bEnd;
+  const changeLines = deleteLines && insertLines;
+  if (changeLines) {
+    array.push(getRange(aIndex, aEnd) + 'c' + getRange(bIndex, bEnd));
+  } else if (deleteLines) {
+    array.push(getRange(aIndex, aEnd) + 'd' + String(bIndex));
+  } else if (insertLines) {
+    array.push(String(aIndex) + 'a' + getRange(bIndex, bEnd));
+  } else {
+    return;
+  }
+
+  for (; aIndex !== aEnd; aIndex += 1) {
+    array.push('< ' + aLines[aIndex]); // delete is less than
+  }
+
+  if (changeLines) {
+    array.push('---');
+  }
+
+  for (; bIndex !== bEnd; bIndex += 1) {
+    array.push('> ' + bLines[bIndex]); // insert is greater than
+  }
+};
+
+// Given content of two files, return emulated output of diff utility.
+const findShortestEditScript = (a, b) => {
+  const aLines = a.split('\n');
+  const bLines = b.split('\n');
+  const aLength = aLines.length;
+  const bLength = bLines.length;
+
+  const isCommon = (aIndex, bIndex) => aLines[aIndex] === bLines[bIndex];
+
+  let aIndex = 0;
+  let bIndex = 0;
+  const array = [];
+  const foundSubsequence = (nCommon, aCommon, bCommon) => {
+    pushDelIns(aLines, aIndex, aCommon, bLines, bIndex, bCommon, array);
+    aIndex = aCommon + nCommon; // number of lines compared in a
+    bIndex = bCommon + nCommon; // number of lines compared in b
+  };
+
+  diff(aLength, bLength, isCommon, foundSubsequence);
+
+  // After the last common subsequence, push remaining change lines.
+  pushDelIns(aLines, aIndex, aLength, bLines, bIndex, bLength, array);
+
+  return array.length === 0 ? '' : array.join('\n') + '\n';
+};
+```
+
+## Example of callback functions to format diff lines
+
+Here is simplified code to format **changed and unchanged lines** in expected and received values after a test fails in Jest:
+
+```js
+// Format diff with minus or plus for change lines and space for common lines.
+const formatDiffLines = (a, b) => {
+  // Jest depends on pretty-format package to serialize objects as strings.
+  // Unindented for comparison to avoid distracting differences:
+  const aLinesUn = format(a, {indent: 0 /*, other options*/}).split('\n');
+  const bLinesUn = format(b, {indent: 0 /*, other options*/}).split('\n');
+  // Indented to display changed and unchanged lines:
+  const aLinesIn = format(a, {indent: 2 /*, other options*/}).split('\n');
+  const bLinesIn = format(b, {indent: 2 /*, other options*/}).split('\n');
+
+  const aLength = aLinesIn.length; // Validate: aLinesUn.length === aLength
+  const bLength = bLinesIn.length; // Validate: bLinesUn.length === bLength
+
+  const isCommon = (aIndex, bIndex) => aLinesUn[aIndex] === bLinesUn[bIndex];
+
+  // Only because the GitHub Flavored Markdown doc collapses adjacent spaces,
+  // this example code and the following table represent spaces as middle dots.
+  let aIndex = 0;
+  let bIndex = 0;
+  const array = [];
+  const foundSubsequence = (nCommon, aCommon, bCommon) => {
+    for (; aIndex !== aCommon; aIndex += 1) {
+      array.push('-·' + aLinesIn[aIndex]); // delete is minus
+    }
+    for (; bIndex !== bCommon; bIndex += 1) {
+      array.push('+·' + bLinesIn[bIndex]); // insert is plus
+    }
+    for (; nCommon !== 0; nCommon -= 1, aIndex += 1, bIndex += 1) {
+      // For common lines, received indentation seems more intuitive.
+      array.push('··' + bLinesIn[bIndex]); // common is space
+    }
+  };
+
+  diff(aLength, bLength, isCommon, foundSubsequence);
+
+  // After the last common subsequence, push remaining change lines.
+  for (; aIndex !== aLength; aIndex += 1) {
+    array.push('-·' + aLinesIn[aIndex]);
+  }
+  for (; bIndex !== bLength; bIndex += 1) {
+    array.push('+·' + bLinesIn[bIndex]);
+  }
+
+  return array;
+};
+
+const expected = {
+  searching: '',
+  sorting: {
+    ascending: true,
+    fieldKey: 'what',
+  },
+};
+const received = {
+  searching: '',
+  sorting: [
+    {
+      descending: false,
+      fieldKey: 'what',
+    },
+  ],
+};
+
+const diffLines = formatDiffLines(expected, received);
+```
+
+If N is the sum of lengths of sequences and L is length of a longest common subsequence, then N – L is length of an array of diff lines. In this example, N is 7 + 9, L is 5, and N – L is 11.
+
+|  `i` | `diffLines[i]`                     | `aIndex` | `bIndex` |
+| ---: | :--------------------------------- | -------: | -------: |
+|  `0` | `'··Object {'`                     |      `0` |      `0` |
+|  `1` | `'····"searching": "",'`           |      `1` |      `1` |
+|  `2` | `'-···"sorting": Object {'`        |      `2` |          |
+|  `3` | `'-·····"ascending": true,'`       |      `3` |          |
+|  `4` | `'+·····"sorting": Array ['`       |          |      `2` |
+|  `5` | `'+·······Object {'`               |          |      `3` |
+|  `6` | `'+·········"descending": false,'` |          |      `4` |
+|  `7` | `'··········"fieldKey": "what",'`  |      `4` |      `5` |
+|  `8` | `'········},'`                     |      `5` |      `6` |
+|  `9` | `'+·····],'`                       |          |      `7` |
+| `10` | `'··}'`                            |      `6` |      `8` |
+
+## Example of callback functions to find diff items
+
+Here is simplified code to find changed and unchanged substrings **within adjacent changed lines** in expected and received values after a test fails in Jest:
+
+```js
+// Return diff items for strings (compatible with diff-match-patch package).
+const findDiffItems = (a, b) => {
+  const isCommon = (aIndex, bIndex) => a[aIndex] === b[bIndex];
+
+  let aIndex = 0;
+  let bIndex = 0;
+  const array = [];
+  const foundSubsequence = (nCommon, aCommon, bCommon) => {
+    if (aIndex !== aCommon) {
+      array.push([-1, a.slice(aIndex, aCommon)]); // delete is -1
+    }
+    if (bIndex !== bCommon) {
+      array.push([1, b.slice(bIndex, bCommon)]); // insert is 1
+    }
+
+    aIndex = aCommon + nCommon; // number of characters compared in a
+    bIndex = bCommon + nCommon; // number of characters compared in b
+    array.push([0, a.slice(aCommon, aIndex)]); // common is 0
+  };
+
+  diff(a.length, b.length, isCommon, foundSubsequence);
+
+  // After the last common subsequence, push remaining change items.
+  if (aIndex !== a.length) {
+    array.push([-1, a.slice(aIndex)]);
+  }
+  if (bIndex !== b.length) {
+    array.push([1, b.slice(bIndex)]);
+  }
+
+  return array;
+};
+
+const expectedDeleted = ['"sorting": Object {', '"ascending": true,'].join(
+  '\n',
+);
+const receivedInserted = [
+  '"sorting": Array [',
+  'Object {',
+  '"descending": false,',
+].join('\n');
+
+const diffItems = findDiffItems(expectedDeleted, receivedInserted);
+```
+
+| `i` | `diffItems[i][0]` | `diffItems[i][1]` |
+| --: | ----------------: | :---------------- |
+| `0` |               `0` | `'"sorting": '`   |
+| `1` |               `1` | `'Array [\n'`     |
+| `2` |               `0` | `'Object {\n"'`   |
+| `3` |              `-1` | `'a'`             |
+| `4` |               `1` | `'de'`            |
+| `5` |               `0` | `'scending": '`   |
+| `6` |              `-1` | `'tru'`           |
+| `7` |               `1` | `'fals'`          |
+| `8` |               `0` | `'e,'`            |
+
+The length difference `b.length - a.length` is equal to the sum of `diffItems[i][0]` values times `diffItems[i][1]` lengths. In this example, the difference `48 - 38` is equal to the sum `10`.
+
+| category of diff item | `[0]` |      `[1]` lengths | subtotal |
+| :-------------------- | ----: | -----------------: | -------: |
+| in common             |   `0` | `11 + 10 + 11 + 2` |      `0` |
+| to delete from `a`    |  `–1` |            `1 + 3` |     `-4` |
+| to insert from `b`    |   `1` |        `8 + 2 + 4` |     `14` |
+
+Instead of formatting the changed substrings with escape codes for colors in the `foundSubsequence` function to save memory, this example spends memory to **gain flexibility** before formatting, so a separate heuristic algorithm might modify the generic array of diff items to show changes more clearly:
+
+| `i` | `diffItems[i][0]` | `diffItems[i][1]` |
+| --: | ----------------: | :---------------- |
+| `6` |              `-1` | `'true'`          |
+| `7` |               `1` | `'false'`         |
+| `8` |               `0` | `','`             |
+
+For expected and received strings of serialized data, the result of finding changed **lines**, and then finding changed **substrings** within adjacent changed lines (as in the preceding two examples) sometimes displays the changes in a more intuitive way than the result of finding changed substrings, and then splitting them into changed and unchanged lines.

data/packages/webpacker/node_modules/diff-sequences/build/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+declare type IsCommon = (aIndex: number, // caller can assume: 0 <= aIndex && aIndex < aLength
+bIndex: number) => boolean;
+declare type FoundSubsequence = (nCommon: number, // caller can assume: 0 < nCommon
+aCommon: number, // caller can assume: 0 <= aCommon && aCommon < aLength
+bCommon: number) => void;
+export declare type Callbacks = {
+    foundSubsequence: FoundSubsequence;
+    isCommon: IsCommon;
+};
+export default function diffSequence(aLength: number, bLength: number, isCommon: IsCommon, foundSubsequence: FoundSubsequence): void;
+export {};