@createiq/htmldiff 1.1.0 → 1.2.0-beta.0

package/dist/HtmlDiff.d.cts

@@ -1,4 +1,68 @@
+//#region src/Action.d.ts
+declare enum Action {
+  Equal = 0,
+  Delete = 1,
+  Insert = 2,
+  None = 3,
+  Replace = 4
+}
+//#endregion
+//#region src/Operation.d.ts
+declare class Operation {
+  action: Action;
+  startInOld: number;
+  endInOld: number;
+  startInNew: number;
+  endInNew: number;
+  constructor(action: Action, startInOld: number, endInOld: number, startInNew: number, endInNew: number);
+}
+//#endregion
 //#region src/HtmlDiff.d.ts
+/**
+ * Options for the `HtmlDiff.analyze` static helper.
+ *
+ * `useProjections` controls structural-tag normalisation:
+ *   - `undefined` → use the same heuristic as `build()` (per-call decision)
+ *   - `true` → force projection on (skipped if either side has no content)
+ *   - `false` → force projection off (diff runs on raw word arrays)
+ * Composers of multiple analyses (e.g. three-way diff) MUST pass the
+ * same explicit boolean to all calls so shared inputs tokenise
+ * identically across analyses.
+ *
+ * The remaining options mirror the per-instance fields on `HtmlDiff`
+ * itself — they exist on the options bag because `analyze` constructs
+ * the inner instance internally.
+ */
+interface AnalyzeOptions {
+  useProjections?: boolean;
+  blockExpressions?: readonly RegExp[];
+  repeatingWordsAccuracy?: number;
+  orphanMatchThreshold?: number;
+  ignoreWhitespaceDifferences?: boolean;
+}
+interface AnalyzeResult {
+  /** Word array the `operations` index into (projected or raw). */
+  readonly oldDiffWords: readonly string[];
+  readonly newDiffWords: readonly string[];
+  readonly operations: readonly Operation[];
+  /** Original WordSplitter output, before any projection. */
+  readonly oldOriginalWords: readonly string[];
+  readonly newOriginalWords: readonly string[];
+  /** Diff-index → original-word-index map; null when projections inactive. */
+  readonly oldContentToOriginal: readonly number[] | null;
+  readonly newContentToOriginal: readonly number[] | null;
+}
+/**
+ * Options for `HtmlDiff.executeThreeWay`. Same shape as `AnalyzeOptions`
+ * — the values flow unchanged into both internal `analyze` calls so V2's
+ * tokenisation stays symmetric. Aliased so future divergence in either
+ * direction lives in one place.
+ *
+ * `useProjections`: when undefined, `executeThreeWay` computes the
+ * decision as the conjunction of both pair-wise
+ * `evaluateProjectionApplicability` results.
+ */
+type ThreeWayOptions = AnalyzeOptions;
 declare class HtmlDiff {
   /**
    * This value defines balance between speed and memory utilization. The higher it is the faster it works and more memory consumes.
@@ -21,10 +85,20 @@ declare class HtmlDiff {
    * pathological input.
    */
   private static MaxTablePreprocessDepth;
+  /**
+   * Mirror cap for the three-way path. The 2-way `MaxTablePreprocessDepth`
+   * guards the recursion inside `executeWithContext`; the 3-way path has
+   * its own recursion (`executeThreeWay` → `preprocessTablesThreeWay` →
+   * `cellDiff` → `executeThreeWay`) which needs its own guard. Once the
+   * cap is reached, `executeThreeWay` skips table preprocessing and
+   * falls back to the word-level merge — same bail-out semantics as the
+   * 2-way path.
+   */
+  private static MaxThreeWayDepth;
   private content;
   private newText;
   private oldText;
-  private readonly tablePreprocessDepth;
+  private tablePreprocessDepth;
   private specialTagDiffStack;
   private newWords;
   private oldWords;
@@ -87,12 +161,71 @@ declare class HtmlDiff {
    * Initializes a new instance of the class.
    * @param oldText The old text.
    * @param newText The new text.
-   * @param tablePreprocessDepth Internal: nested-call depth for table
-   *   preprocessing. Callers should leave at default (0); the recursive
-   *   `diffCell` callback in TableDiff bumps it.
    */
-  constructor(oldText: string, newText: string, tablePreprocessDepth?: number);
-  static execute(oldText: string, newText: string, tablePreprocessDepth?: number): string;
+  constructor(oldText: string, newText: string);
+  static execute(oldText: string, newText: string): string;
+  /**
+   * Analyse a two-way diff and return its raw building blocks: the word
+   * arrays the diff ran against, the operations produced, the original
+   * (pre-projection) word arrays, and the mappings from diff-index back
+   * to original-word index when structural projection is active.
+   * Consumed by `executeThreeWay` so it can compose two diffs by walking
+   * their Operation streams.
+   *
+   * The caller is expected to coordinate `useProjections` symmetrically
+   * across composed analyses — if V1↔V2 projects but V2↔V3 doesn't,
+   * V2's "new" array in the first analysis won't equal V2's "old" array
+   * in the second. `evaluateProjectionApplicability` exposes the same
+   * heuristic `build()` uses internally, so the orchestrator can compute
+   * a single decision and pass it into every `analyze` call.
+   *
+   * Table preprocessing is skipped here. Placeholders mutate the input
+   * in ways that don't compose across two independent analyses; the
+   * 3-way orchestrator handles tables explicitly before calling analyze.
+   */
+  static analyze(oldText: string, newText: string, options?: AnalyzeOptions): AnalyzeResult;
+  /**
+   * Whether content-projection (structural-tag normalisation) would
+   * apply to this pair of inputs under `build()`'s default heuristic.
+   * Exposed so composers of multiple analyses can compute a symmetric
+   * decision before calling `analyze` — see `analyze`'s docstring for
+   * why symmetry matters.
+   */
+  static evaluateProjectionApplicability(oldText: string, newText: string): boolean;
+  /**
+   * Three-way HTML diff. Given V1 (the version Me last sent), V2 (the
+   * version CP sent back), and V3 (Me's current draft), produces a
+   * single attributed HTML output where CP's and Me's changes are
+   * distinguished by `data-author` ('cp' or 'me') and matching
+   * `class='diffins cp'` / `class='diffdel me'` etc. The "Me rejected
+   * CP's proposal" case (Me deleted text CP had inserted) gets a
+   * dedicated marker: `data-rejects='cp'` plus `class='... rejects-cp'`.
+   *
+   * Coordinates the symmetric-projection decision (D1) across both
+   * internal `analyze` calls so V2 tokenises identically on each side
+   * of the spine. When `useProjections` is left undefined, the decision
+   * is the conjunction of both pair-wise heuristics — project iff both
+   * pairs would project on their own. Pass an explicit boolean to
+   * override.
+   */
+  static executeThreeWay(v1: string, v2: string, v3: string, options?: ThreeWayOptions): string;
+  private static executeThreeWayWithDepth;
+  /**
+   * Drives a fresh `HtmlDiff` instance through `insertTag` for ins/del
+   * segments and pushes equal segments straight to its `content`
+   * buffer. Reusing the instance keeps the formatting-tag stack
+   * (`specialTagDiffStack`) coherent across segments — a `<strong>`
+   * opened in one segment and closed in another stays balanced.
+   */
+  private static emitSegments;
+  /**
+   * Internal entry point used by the table-cell recursion. Constructs an
+   * inner `HtmlDiff`, applies the caller's settings, and bumps the
+   * recursion depth — keeping the public constructor signature clean
+   * while still threading the configuration that's required for cell-
+   * level output to match the top-level call's behaviour.
+   */
+  private static executeWithContext;
   /**
    * Builds the HTML diff output
    * @return HTML diff markup
@@ -185,5 +318,6 @@ declare class HtmlDiff {
   private findMatchingBlocks;
   private findMatch;
 }
-export = HtmlDiff;
+//#endregion
+export { AnalyzeOptions, AnalyzeResult, ThreeWayOptions, HtmlDiff as default };
 //# sourceMappingURL=HtmlDiff.d.cts.map

package/dist/HtmlDiff.d.mts

@@ -1,4 +1,68 @@
+//#region src/Action.d.ts
+declare enum Action {
+  Equal = 0,
+  Delete = 1,
+  Insert = 2,
+  None = 3,
+  Replace = 4
+}
+//#endregion
+//#region src/Operation.d.ts
+declare class Operation {
+  action: Action;
+  startInOld: number;
+  endInOld: number;
+  startInNew: number;
+  endInNew: number;
+  constructor(action: Action, startInOld: number, endInOld: number, startInNew: number, endInNew: number);
+}
+//#endregion
 //#region src/HtmlDiff.d.ts
+/**
+ * Options for the `HtmlDiff.analyze` static helper.
+ *
+ * `useProjections` controls structural-tag normalisation:
+ *   - `undefined` → use the same heuristic as `build()` (per-call decision)
+ *   - `true` → force projection on (skipped if either side has no content)
+ *   - `false` → force projection off (diff runs on raw word arrays)
+ * Composers of multiple analyses (e.g. three-way diff) MUST pass the
+ * same explicit boolean to all calls so shared inputs tokenise
+ * identically across analyses.
+ *
+ * The remaining options mirror the per-instance fields on `HtmlDiff`
+ * itself — they exist on the options bag because `analyze` constructs
+ * the inner instance internally.
+ */
+interface AnalyzeOptions {
+  useProjections?: boolean;
+  blockExpressions?: readonly RegExp[];
+  repeatingWordsAccuracy?: number;
+  orphanMatchThreshold?: number;
+  ignoreWhitespaceDifferences?: boolean;
+}
+interface AnalyzeResult {
+  /** Word array the `operations` index into (projected or raw). */
+  readonly oldDiffWords: readonly string[];
+  readonly newDiffWords: readonly string[];
+  readonly operations: readonly Operation[];
+  /** Original WordSplitter output, before any projection. */
+  readonly oldOriginalWords: readonly string[];
+  readonly newOriginalWords: readonly string[];
+  /** Diff-index → original-word-index map; null when projections inactive. */
+  readonly oldContentToOriginal: readonly number[] | null;
+  readonly newContentToOriginal: readonly number[] | null;
+}
+/**
+ * Options for `HtmlDiff.executeThreeWay`. Same shape as `AnalyzeOptions`
+ * — the values flow unchanged into both internal `analyze` calls so V2's
+ * tokenisation stays symmetric. Aliased so future divergence in either
+ * direction lives in one place.
+ *
+ * `useProjections`: when undefined, `executeThreeWay` computes the
+ * decision as the conjunction of both pair-wise
+ * `evaluateProjectionApplicability` results.
+ */
+type ThreeWayOptions = AnalyzeOptions;
 declare class HtmlDiff {
   /**
    * This value defines balance between speed and memory utilization. The higher it is the faster it works and more memory consumes.
@@ -21,10 +85,20 @@ declare class HtmlDiff {
    * pathological input.
    */
   private static MaxTablePreprocessDepth;
+  /**
+   * Mirror cap for the three-way path. The 2-way `MaxTablePreprocessDepth`
+   * guards the recursion inside `executeWithContext`; the 3-way path has
+   * its own recursion (`executeThreeWay` → `preprocessTablesThreeWay` →
+   * `cellDiff` → `executeThreeWay`) which needs its own guard. Once the
+   * cap is reached, `executeThreeWay` skips table preprocessing and
+   * falls back to the word-level merge — same bail-out semantics as the
+   * 2-way path.
+   */
+  private static MaxThreeWayDepth;
   private content;
   private newText;
   private oldText;
-  private readonly tablePreprocessDepth;
+  private tablePreprocessDepth;
   private specialTagDiffStack;
   private newWords;
   private oldWords;
@@ -87,12 +161,71 @@ declare class HtmlDiff {
    * Initializes a new instance of the class.
    * @param oldText The old text.
    * @param newText The new text.
-   * @param tablePreprocessDepth Internal: nested-call depth for table
-   *   preprocessing. Callers should leave at default (0); the recursive
-   *   `diffCell` callback in TableDiff bumps it.
    */
-  constructor(oldText: string, newText: string, tablePreprocessDepth?: number);
-  static execute(oldText: string, newText: string, tablePreprocessDepth?: number): string;
+  constructor(oldText: string, newText: string);
+  static execute(oldText: string, newText: string): string;
+  /**
+   * Analyse a two-way diff and return its raw building blocks: the word
+   * arrays the diff ran against, the operations produced, the original
+   * (pre-projection) word arrays, and the mappings from diff-index back
+   * to original-word index when structural projection is active.
+   * Consumed by `executeThreeWay` so it can compose two diffs by walking
+   * their Operation streams.
+   *
+   * The caller is expected to coordinate `useProjections` symmetrically
+   * across composed analyses — if V1↔V2 projects but V2↔V3 doesn't,
+   * V2's "new" array in the first analysis won't equal V2's "old" array
+   * in the second. `evaluateProjectionApplicability` exposes the same
+   * heuristic `build()` uses internally, so the orchestrator can compute
+   * a single decision and pass it into every `analyze` call.
+   *
+   * Table preprocessing is skipped here. Placeholders mutate the input
+   * in ways that don't compose across two independent analyses; the
+   * 3-way orchestrator handles tables explicitly before calling analyze.
+   */
+  static analyze(oldText: string, newText: string, options?: AnalyzeOptions): AnalyzeResult;
+  /**
+   * Whether content-projection (structural-tag normalisation) would
+   * apply to this pair of inputs under `build()`'s default heuristic.
+   * Exposed so composers of multiple analyses can compute a symmetric
+   * decision before calling `analyze` — see `analyze`'s docstring for
+   * why symmetry matters.
+   */
+  static evaluateProjectionApplicability(oldText: string, newText: string): boolean;
+  /**
+   * Three-way HTML diff. Given V1 (the version Me last sent), V2 (the
+   * version CP sent back), and V3 (Me's current draft), produces a
+   * single attributed HTML output where CP's and Me's changes are
+   * distinguished by `data-author` ('cp' or 'me') and matching
+   * `class='diffins cp'` / `class='diffdel me'` etc. The "Me rejected
+   * CP's proposal" case (Me deleted text CP had inserted) gets a
+   * dedicated marker: `data-rejects='cp'` plus `class='... rejects-cp'`.
+   *
+   * Coordinates the symmetric-projection decision (D1) across both
+   * internal `analyze` calls so V2 tokenises identically on each side
+   * of the spine. When `useProjections` is left undefined, the decision
+   * is the conjunction of both pair-wise heuristics — project iff both
+   * pairs would project on their own. Pass an explicit boolean to
+   * override.
+   */
+  static executeThreeWay(v1: string, v2: string, v3: string, options?: ThreeWayOptions): string;
+  private static executeThreeWayWithDepth;
+  /**
+   * Drives a fresh `HtmlDiff` instance through `insertTag` for ins/del
+   * segments and pushes equal segments straight to its `content`
+   * buffer. Reusing the instance keeps the formatting-tag stack
+   * (`specialTagDiffStack`) coherent across segments — a `<strong>`
+   * opened in one segment and closed in another stays balanced.
+   */
+  private static emitSegments;
+  /**
+   * Internal entry point used by the table-cell recursion. Constructs an
+   * inner `HtmlDiff`, applies the caller's settings, and bumps the
+   * recursion depth — keeping the public constructor signature clean
+   * while still threading the configuration that's required for cell-
+   * level output to match the top-level call's behaviour.
+   */
+  private static executeWithContext;
   /**
    * Builds the HTML diff output
    * @return HTML diff markup
@@ -186,5 +319,5 @@ declare class HtmlDiff {
   private findMatch;
 }
 //#endregion
-export { HtmlDiff as default };
+export { AnalyzeOptions, AnalyzeResult, ThreeWayOptions, HtmlDiff as default };
 //# sourceMappingURL=HtmlDiff.d.mts.map