@matrixreq/htmldiff 1.5.0 → 2.0.0

package/README.md

@@ -145,6 +145,48 @@ Limitations:
 - The recursion depth is capped at 10 levels as a backstop against deep
   nesting. Opted-in elements beyond the cap are rendered as their after version.
 
+### Tables
+
+Tables are compared as structures before the flat diff runs. A table with its own
+`data-htmldiff-id` takes part only when it also carries `data-htmldiff-inner-diff`, like every
+other element with an identity: without the inner-id it is one unit, shown as it is or replaced
+whole. The same goes for a table inside such an element. The two documents' top level
+tables are paired (by their own `data-htmldiff-id` when they have one, otherwise by the values
+they hold; a table in the other's place is the same table only when the two still share half of
+what the smaller one holds, or when both are generated tables, see below), each pair is aligned
+column by column and row by row, and a merged table takes the place of the after version's
+table. A table without a partner is kept whole, so the flat diff wraps it as added or deleted:
+
+- an added or deleted row is a whole row with the class `table-row-added` or
+  `table-row-deleted`,
+- an added or deleted column marks every one of its cells (and its `<col>`, when the table has
+  a `<colgroup>`) with `table-cell-added` or `table-cell-deleted`,
+- a kept cell holds the diff of its content, with the usual `<ins>`/`<del>` tags,
+- a row that keeps less than half of its content, or a column no kept row agrees with, is
+  deleted and added instead of diffed; so is a moved row or column,
+- merged cells (`rowspan`, `colspan`) are kept. A row that a kept group (a merged cell and the
+  rows it spans) lost or gained goes under the group's kept rows and carries the change on its
+  cells (`table-cell-deleted` / `table-cell-added`), not on the row: the group's cell, sitting on
+  the group's first kept row, spans it like any other row of the group. A view that hides the
+  changed cells then hides nothing the span counts on, so the layout holds. A whole group that
+  one version has is added or deleted row by row.
+- in a table without such a statement, a change of its merged cells (a cell merged, split, a
+  span grown or shrunk) makes it another table: both versions are kept whole.
+
+The diff reads nothing else from the content. A producer that knows what a row is about says
+so by giving the cells an identity with `data-htmldiff-id`. 
+When both versions carry such cells, those alone pair the rows: the same
+identities are the same row, whatever its other cells say, and they get cell diffs; other
+identities are another row, deleted and added whole. The identity sits on the cell, not on
+the row, because such cells often span several rows: the rows under a spanning cell never
+contain it, yet they belong to it, and an id on the cell is inherited by every row it spans,
+where an id on each `<tr>` would have to be composed and repeated by the producer. A cell id
+also says which cells name the row and which are content.
+
+Both versions of a pair get the same `data-htmldiff-id` (`redline-table-<n>` unless the table
+had one), a table only one version has gets one of its own, so the flat diff keeps every table
+whole and emits the merged table as it is. The styling of the classes is up to the consumer.
+
 ### Example
 
 JavaScript:
@@ -198,14 +240,40 @@ description please see API documentation above.
 
 ## Development
 
-After cloning the repository run `npm i` or `npm install` to install the necessary 
-dependencies. A run of `npm run make` creates the JavaScript output file. 
-`npm run lint` checks the TypeScript sources with TSLint. `npm test` runs all the
-tests from the `test` directory. `npm run testsample` diffs the HTML sample files 
-from the directory `sample` and logs the result to the console.
-
-The command line interface of htmldiff is developed in TypeScript so you have to run
-`npm run make` once to create the JavaScript output file.
+After cloning the repository run `npm install` to install the dependencies.
+
+Everything is TypeScript. The library lives in `src/` and is compiled to CommonJS in `js/`
+(`js/htmldiff.js` is the entry point, `js/htmldiff.d.ts` the typings); `js/` is what gets
+published.
+
+- `src/htmldiff.ts` is the facade: it runs the table pass, then the flat diff.
+- `src/constants.ts` names the attributes the diff reads, `data-htmldiff-id` and
+  `data-htmldiff-inner-diff`: the contract between a producer of HTML and the diff.
+- `src/core/` is the flat diff, one module per stage: `atomicTags` (which elements are one
+  token), `tokens` (tokenizing and token keys), `matching` (matching blocks), `operations`
+  (insert, delete, replace, equal), `rendering` (ins/del markup and the recursive inner
+  diff) and `diff` (the pipeline).
+- `src/tables/` is the structural table pass, one class per concern: `Cell`, `Row` and
+  `Table` are the model, `TableVersion` a table as the alignment reads it, `SequenceAligner`,
+  `ColumnAligner`, `RowAligner` and `TableAligner` decide what is the same, `MergedCells`
+  handles spans, `TableMerger` writes the merged table and `TableRedlining` is the pass
+  itself. `html.ts`, `similarity.ts` and `helpers.ts` are plain helper functions.
+
+Tests are TypeScript too, run by mocha through `ts-node`. Every module and class has a spec
+next to it (`src/**/*.spec.ts`, left out of the build); the end to end specs that go through
+`diff()` itself live in `test/`.
+
+Scripts:
+
+- `npm run build` compiles `src/` to `js/`.
+- `npm test` builds, type-checks sources and specs, then runs the specs.
+- `npm run lint` checks sources and specs with ESLint.
+- `npm run verify` does all of that in one go and compiles the CLI; `npm publish` runs it first
+  (`prepublishOnly`), so nothing unbuilt or untested can be published. `npm install` in a clone
+  builds `js/` as well (`prepare`).
+- `npm run make` builds the library and the command line interface, `htmldiff-cli.ts`.
+- `npm run testsample` diffs the HTML sample files from the directory `sample` and logs the
+  result to the console.
 
 
 ## Credits

package/js/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const HTMLDIFF_ID_ATTRIBUTE = "data-htmldiff-id";
+export declare const INNER_DIFF_ATTRIBUTE = "data-htmldiff-inner-diff";
+export declare const INNER_DIFF_ATOMIC_TAGS_ATTRIBUTE = "data-htmldiff-inner-diff-atomic-tags";

package/js/constants.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INNER_DIFF_ATOMIC_TAGS_ATTRIBUTE = exports.INNER_DIFF_ATTRIBUTE = exports.HTMLDIFF_ID_ATTRIBUTE = void 0;
+exports.HTMLDIFF_ID_ATTRIBUTE = "data-htmldiff-id";
+exports.INNER_DIFF_ATTRIBUTE = "data-htmldiff-inner-diff";
+exports.INNER_DIFF_ATOMIC_TAGS_ATTRIBUTE = "data-htmldiff-inner-diff-atomic-tags";

package/js/core/atomicTags.d.ts

@@ -0,0 +1,10 @@
+export declare const defaultAtomicTagsRegExp: RegExp;
+export declare const defaultInnerDiffAtomicTagsRegExp: RegExp;
+export declare const noAtomicTagsRegExp: RegExp;
+export declare const dataHtmlDiffIdRegExp: RegExp;
+export declare const dataHtmlDiffInnerDiffRegExp: RegExp;
+export declare const dataHtmlDiffInnerDiffAtomicTagsRegExp: RegExp;
+export declare function getAtomicTagsRegExp(): RegExp;
+export declare function setAtomicTagsRegExp(regExp: RegExp): void;
+export declare function buildAtomicTagsRegExp(atomicTags: string): RegExp;
+export declare function isStartOfAtomicTag(word: string): string | null;

package/js/core/atomicTags.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStartOfAtomicTag = exports.buildAtomicTagsRegExp = exports.setAtomicTagsRegExp = exports.getAtomicTagsRegExp = exports.dataHtmlDiffInnerDiffAtomicTagsRegExp = exports.dataHtmlDiffInnerDiffRegExp = exports.dataHtmlDiffIdRegExp = exports.noAtomicTagsRegExp = exports.defaultInnerDiffAtomicTagsRegExp = exports.defaultAtomicTagsRegExp = void 0;
+const constants_1 = require("../constants");
+exports.defaultAtomicTagsRegExp = new RegExp("^<(iframe|object|math|svg|script|video|head|style|a)[\\s/>]");
+exports.defaultInnerDiffAtomicTagsRegExp = new RegExp("^<(iframe|object|math|svg|script|video|head|style)[\\s/>]");
+exports.noAtomicTagsRegExp = /^<(?!)/;
+exports.dataHtmlDiffIdRegExp = new RegExp(`^<([a-z-]+)(?:[^>"']|"[^"]*"|'[^']*')*\\s${constants_1.HTMLDIFF_ID_ATTRIBUTE}=["']?((?:.(?!["']?\\s+(?:\\S+)=|\\s*\\/?[>"']))*.)["']?`);
+exports.dataHtmlDiffInnerDiffRegExp = new RegExp(`^<[^>]*\\s${constants_1.INNER_DIFF_ATTRIBUTE}(?:\\s*=\\s*["']?([^"'\\s/>]*)|(?=[\\s/>]))`);
+exports.dataHtmlDiffInnerDiffAtomicTagsRegExp = new RegExp(`^<[^>]*\\s${constants_1.INNER_DIFF_ATOMIC_TAGS_ATTRIBUTE}\\s*=\\s*["']([^"']*)["']`);
+let atomicTagsRegExp = exports.defaultAtomicTagsRegExp;
+function getAtomicTagsRegExp() {
+    return atomicTagsRegExp;
+}
+exports.getAtomicTagsRegExp = getAtomicTagsRegExp;
+function setAtomicTagsRegExp(regExp) {
+    atomicTagsRegExp = regExp;
+}
+exports.setAtomicTagsRegExp = setAtomicTagsRegExp;
+function buildAtomicTagsRegExp(atomicTags) {
+    return new RegExp("^<(" + atomicTags.replace(/\s*/g, "").replace(/,/g, "|") + ")[\\s/>]");
+}
+exports.buildAtomicTagsRegExp = buildAtomicTagsRegExp;
+function isStartOfAtomicTag(word) {
+    const result = atomicTagsRegExp.exec(word) || exports.dataHtmlDiffIdRegExp.exec(word);
+    return result ? result[1] : null;
+}
+exports.isStartOfAtomicTag = isStartOfAtomicTag;

package/js/core/diff.d.ts

@@ -0,0 +1,2 @@
+import { ContentDiff } from "./rendering";
+export declare const diffCore: ContentDiff;

package/js/core/diff.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffCore = void 0;
+const operations_1 = require("./operations");
+const rendering_1 = require("./rendering");
+const tokens_1 = require("./tokens");
+const diffCore = (before, after, className, dataPrefix) => {
+    if (before === after)
+        return before;
+    const beforeTokens = (0, tokens_1.htmlToTokens)(before);
+    const afterTokens = (0, tokens_1.htmlToTokens)(after);
+    const ops = (0, operations_1.calculateOperations)(beforeTokens, afterTokens);
+    return (0, rendering_1.renderOperations)(beforeTokens, afterTokens, ops, exports.diffCore, dataPrefix, className);
+};
+exports.diffCore = diffCore;

package/js/core/matching.d.ts

@@ -0,0 +1,27 @@
+import { Token } from "./tokens";
+export interface Segment {
+    beforeTokens: Token[];
+    afterTokens: Token[];
+    beforeMap: TokenMap;
+    afterMap: TokenMap;
+    beforeIndex: number;
+    afterIndex: number;
+}
+export declare type TokenMap = Record<string, number[]>;
+export declare class Match {
+    segment: Segment;
+    length: number;
+    startInBefore: number;
+    startInAfter: number;
+    endInBefore: number;
+    endInAfter: number;
+    segmentStartInBefore: number;
+    segmentStartInAfter: number;
+    segmentEndInBefore: number;
+    segmentEndInAfter: number;
+    constructor(startInBefore: number, startInAfter: number, length: number, segment: Segment);
+}
+export declare function createMap(tokens: Token[]): TokenMap;
+export declare function findBestMatch(segment: Segment): Match | null;
+export declare function createSegment(beforeTokens: Token[], afterTokens: Token[], beforeIndex: number, afterIndex: number): Segment;
+export declare function findMatchingBlocks(segment: Segment): Match[];

package/js/core/matching.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findMatchingBlocks = exports.createSegment = exports.findBestMatch = exports.createMap = exports.Match = void 0;
+class Match {
+    segment;
+    length;
+    startInBefore;
+    startInAfter;
+    endInBefore;
+    endInAfter;
+    segmentStartInBefore;
+    segmentStartInAfter;
+    segmentEndInBefore;
+    segmentEndInAfter;
+    constructor(startInBefore, startInAfter, length, segment) {
+        this.segment = segment;
+        this.length = length;
+        this.startInBefore = startInBefore + segment.beforeIndex;
+        this.startInAfter = startInAfter + segment.afterIndex;
+        this.endInBefore = this.startInBefore + this.length - 1;
+        this.endInAfter = this.startInAfter + this.length - 1;
+        this.segmentStartInBefore = startInBefore;
+        this.segmentStartInAfter = startInAfter;
+        this.segmentEndInBefore = this.segmentStartInBefore + this.length - 1;
+        this.segmentEndInAfter = this.segmentStartInAfter + this.length - 1;
+    }
+}
+exports.Match = Match;
+function createMap(tokens) {
+    return tokens.reduce((map, token, index) => {
+        if (map[token.key]) {
+            map[token.key].push(index);
+        }
+        else {
+            map[token.key] = [index];
+        }
+        return map;
+    }, Object.create(null));
+}
+exports.createMap = createMap;
+function compareMatches(m1, m2) {
+    if (m2.endInBefore < m1.startInBefore && m2.endInAfter < m1.startInAfter) {
+        return -1;
+    }
+    if (m2.startInBefore > m1.endInBefore && m2.startInAfter > m1.endInAfter) {
+        return 1;
+    }
+    return 0;
+}
+class MatchBinarySearchTree {
+    root = null;
+    add(value) {
+        const node = { value, left: null, right: null };
+        let current = this.root;
+        if (!current) {
+            this.root = node;
+            return;
+        }
+        for (;;) {
+            const position = compareMatches(current.value, value);
+            if (position === -1) {
+                if (current.left) {
+                    current = current.left;
+                }
+                else {
+                    current.left = node;
+                    break;
+                }
+            }
+            else if (position === 1) {
+                if (current.right) {
+                    current = current.right;
+                }
+                else {
+                    current.right = node;
+                    break;
+                }
+            }
+            else {
+                break;
+            }
+        }
+    }
+    toArray() {
+        function inOrder(node, nodes) {
+            if (node) {
+                inOrder(node.left, nodes);
+                nodes.push(node.value);
+                inOrder(node.right, nodes);
+            }
+            return nodes;
+        }
+        return inOrder(this.root, []);
+    }
+}
+function findBestMatch(segment) {
+    const beforeTokens = segment.beforeTokens;
+    const afterMap = segment.afterMap;
+    let lastSpace = null;
+    let bestMatch = null;
+    for (let beforeIndex = 0; beforeIndex < beforeTokens.length; beforeIndex++) {
+        let lookBehind = false;
+        const remainingTokens = beforeTokens.length - beforeIndex;
+        if (bestMatch && remainingTokens < bestMatch.length) {
+            break;
+        }
+        const beforeToken = beforeTokens[beforeIndex];
+        if (beforeToken.key === " ") {
+            lastSpace = beforeIndex;
+            continue;
+        }
+        if (lastSpace === beforeIndex - 1) {
+            lookBehind = true;
+        }
+        const afterTokenLocations = afterMap[beforeToken.key];
+        if (!afterTokenLocations) {
+            continue;
+        }
+        for (const afterIndex of afterTokenLocations) {
+            const bestMatchLength = bestMatch ? bestMatch.length : 0;
+            const match = getFullMatch(segment, beforeIndex, afterIndex, bestMatchLength, lookBehind);
+            if (match && match.length > bestMatchLength) {
+                bestMatch = match;
+            }
+        }
+    }
+    return bestMatch;
+}
+exports.findBestMatch = findBestMatch;
+function getFullMatch(segment, beforeStart, afterStart, minLength, lookBehind) {
+    const beforeTokens = segment.beforeTokens;
+    const afterTokens = segment.afterTokens;
+    const minBeforeIndex = beforeStart + minLength;
+    const minAfterIndex = afterStart + minLength;
+    if (minBeforeIndex >= beforeTokens.length || minAfterIndex >= afterTokens.length) {
+        return undefined;
+    }
+    if (minLength) {
+        const nextBeforeWord = beforeTokens[minBeforeIndex].key;
+        const nextAfterWord = afterTokens[minAfterIndex].key;
+        if (nextBeforeWord !== nextAfterWord) {
+            return undefined;
+        }
+    }
+    let searching = true;
+    let currentLength = 1;
+    let beforeIndex = beforeStart + currentLength;
+    let afterIndex = afterStart + currentLength;
+    while (searching && beforeIndex < beforeTokens.length && afterIndex < afterTokens.length) {
+        const beforeWord = beforeTokens[beforeIndex].key;
+        const afterWord = afterTokens[afterIndex].key;
+        if (beforeWord === afterWord) {
+            currentLength++;
+            beforeIndex = beforeStart + currentLength;
+            afterIndex = afterStart + currentLength;
+        }
+        else {
+            searching = false;
+        }
+    }
+    if (lookBehind && beforeStart > 0 && afterStart > 0) {
+        const prevBeforeKey = beforeTokens[beforeStart - 1].key;
+        const prevAfterKey = afterTokens[afterStart - 1].key;
+        if (prevBeforeKey === " " && prevAfterKey === " ") {
+            beforeStart--;
+            afterStart--;
+            currentLength++;
+        }
+    }
+    return new Match(beforeStart, afterStart, currentLength, segment);
+}
+function createSegment(beforeTokens, afterTokens, beforeIndex, afterIndex) {
+    return {
+        beforeTokens,
+        afterTokens,
+        beforeMap: createMap(beforeTokens),
+        afterMap: createMap(afterTokens),
+        beforeIndex,
+        afterIndex,
+    };
+}
+exports.createSegment = createSegment;
+function findMatchingBlocks(segment) {
+    const matches = new MatchBinarySearchTree();
+    const segments = [segment];
+    while (segments.length) {
+        const current = segments.pop();
+        const match = findBestMatch(current);
+        if (match && match.length) {
+            if (match.segmentStartInBefore > 0 && match.segmentStartInAfter > 0) {
+                const leftBeforeTokens = current.beforeTokens.slice(0, match.segmentStartInBefore);
+                const leftAfterTokens = current.afterTokens.slice(0, match.segmentStartInAfter);
+                segments.push(createSegment(leftBeforeTokens, leftAfterTokens, current.beforeIndex, current.afterIndex));
+            }
+            const rightBeforeTokens = current.beforeTokens.slice(match.segmentEndInBefore + 1);
+            const rightAfterTokens = current.afterTokens.slice(match.segmentEndInAfter + 1);
+            const rightBeforeIndex = current.beforeIndex + match.segmentEndInBefore + 1;
+            const rightAfterIndex = current.afterIndex + match.segmentEndInAfter + 1;
+            if (rightBeforeTokens.length && rightAfterTokens.length) {
+                segments.push(createSegment(rightBeforeTokens, rightAfterTokens, rightBeforeIndex, rightAfterIndex));
+            }
+            matches.add(match);
+        }
+    }
+    return matches.toArray();
+}
+exports.findMatchingBlocks = findMatchingBlocks;

package/js/core/operations.d.ts

@@ -0,0 +1,10 @@
+import { Token } from "./tokens";
+export declare type OperationAction = "equal" | "insert" | "delete" | "replace";
+export interface Operation {
+    action: OperationAction;
+    startInBefore: number;
+    endInBefore: number | null;
+    startInAfter: number;
+    endInAfter: number | null;
+}
+export declare function calculateOperations(beforeTokens: Token[], afterTokens: Token[]): Operation[];

package/js/core/operations.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateOperations = void 0;
+const matching_1 = require("./matching");
+function calculateOperations(beforeTokens, afterTokens) {
+    if (!beforeTokens)
+        throw new Error("Missing beforeTokens");
+    if (!afterTokens)
+        throw new Error("Missing afterTokens");
+    let positionInBefore = 0;
+    let positionInAfter = 0;
+    const operations = [];
+    const segment = (0, matching_1.createSegment)(beforeTokens, afterTokens, 0, 0);
+    const matches = (0, matching_1.findMatchingBlocks)(segment);
+    matches.push(new matching_1.Match(beforeTokens.length, afterTokens.length, 0, segment));
+    for (let index = 0; index < matches.length; index++) {
+        const match = matches[index];
+        let actionUpToMatchPositions = "none";
+        if (positionInBefore === match.startInBefore) {
+            if (positionInAfter !== match.startInAfter) {
+                actionUpToMatchPositions = "insert";
+            }
+        }
+        else {
+            actionUpToMatchPositions = "delete";
+            if (positionInAfter !== match.startInAfter) {
+                actionUpToMatchPositions = "replace";
+            }
+        }
+        if (actionUpToMatchPositions !== "none") {
+            operations.push({
+                action: actionUpToMatchPositions,
+                startInBefore: positionInBefore,
+                endInBefore: actionUpToMatchPositions !== "insert" ? match.startInBefore - 1 : null,
+                startInAfter: positionInAfter,
+                endInAfter: actionUpToMatchPositions !== "delete" ? match.startInAfter - 1 : null,
+            });
+        }
+        if (match.length !== 0) {
+            operations.push({
+                action: "equal",
+                startInBefore: match.startInBefore,
+                endInBefore: match.endInBefore,
+                startInAfter: match.startInAfter,
+                endInAfter: match.endInAfter,
+            });
+        }
+        positionInBefore = match.endInBefore + 1;
+        positionInAfter = match.endInAfter + 1;
+    }
+    const postProcessed = [];
+    let lastOp = { action: "none" };
+    function isSingleWhitespace(op) {
+        if (op.action !== "equal") {
+            return false;
+        }
+        if (op.endInBefore - op.startInBefore !== 0) {
+            return false;
+        }
+        return /^\s$/.test(String(beforeTokens.slice(op.startInBefore, op.endInBefore + 1)));
+    }
+    for (let i = 0; i < operations.length; i++) {
+        const op = operations[i];
+        if (lastOp.action === "replace" &&
+            (isSingleWhitespace(op) || op.action === "replace")) {
+            lastOp.endInBefore = op.endInBefore;
+            lastOp.endInAfter = op.endInAfter;
+        }
+        else {
+            postProcessed.push(op);
+            lastOp = op;
+        }
+    }
+    return postProcessed;
+}
+exports.calculateOperations = calculateOperations;

package/js/core/rendering.d.ts

@@ -0,0 +1,25 @@
+import { Operation } from "./operations";
+import { Token } from "./tokens";
+export declare type ContentDiff = (before: string, after: string, className?: string | null, dataPrefix?: string | null) => string;
+interface TokenSegment {
+    isWrappable: boolean;
+    tokens: string[];
+}
+export declare class TokenWrapper {
+    private readonly tokens;
+    private readonly notes;
+    constructor(tokens: string[]);
+    combine(mapFn: (segment: TokenSegment) => string, tagFn: (openingTag: string) => string): string;
+}
+export declare function wrap(tag: string, content: string[], opIndex: number, dataPrefix?: string | null, className?: string | null): string;
+export declare function isInnerDiffToken(tokenString: string): boolean;
+export declare function findOpeningTagEnd(tokenString: string): number;
+export interface SplitToken {
+    openingTag: string;
+    innerHtml: string;
+    closingTag: string;
+}
+export declare function splitAtomicTokenString(tokenString: string): SplitToken | null;
+export declare function renderInnerDiff(beforeString: string, afterString: string, diffContent: ContentDiff, dataPrefix?: string | null, className?: string | null): string;
+export declare function renderOperations(beforeTokens: Token[], afterTokens: Token[], operations: Operation[], diffContent: ContentDiff, dataPrefix?: string | null, className?: string | null): string;
+export {};