documentation-hub 5.7.2

package/src/services/document/blanklines/__tests__/paragraphChecks.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Unit tests for paragraph check helper functions
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* globals jest, describe, it, expect */
+import {
+  isParagraphBlank,
+  startsWithBoldColon,
+  isCenteredBoldText,
+  isTextOnlyParagraph,
+  isTocParagraph,
+} from "../helpers/paragraphChecks";
+
+// Mock docxmlater classes
+jest.mock("docxmlater", () => {
+  class MockRun {
+    private text: string;
+    private formatting: any;
+    constructor(text: string = "", formatting: any = {}) {
+      this.text = text;
+      this.formatting = formatting;
+    }
+    getText() { return this.text; }
+    getFormatting() { return this.formatting; }
+  }
+
+  class MockHyperlink {
+    getText() { return "link text"; }
+  }
+
+  class MockImageRun extends MockRun {
+    getImageElement() { return {}; }
+  }
+
+  class MockShape {}
+  class MockTextBox {}
+  class MockField {}
+
+  class MockRevision {
+    private text: string;
+    private content: any[];
+    constructor(text: string = "", content: any[] = []) {
+      this.text = text;
+      this.content = content;
+    }
+    getText() { return this.text; }
+    getContent() { return this.content; }
+  }
+
+  class MockParagraph {
+    private content: any[];
+    private style: string;
+    private alignment: string;
+    private bookmarksStart: any[];
+    private bookmarksEnd: any[];
+
+    constructor(opts: {
+      content?: any[];
+      style?: string;
+      alignment?: string;
+      bookmarksStart?: any[];
+      bookmarksEnd?: any[];
+    } = {}) {
+      this.content = opts.content ?? [];
+      this.style = opts.style ?? "";
+      this.alignment = opts.alignment ?? "left";
+      this.bookmarksStart = opts.bookmarksStart ?? [];
+      this.bookmarksEnd = opts.bookmarksEnd ?? [];
+    }
+
+    getContent() { return this.content; }
+    getText() {
+      return this.content
+        .filter((c: any) => c.getText)
+        .map((c: any) => c.getText())
+        .join("");
+    }
+    getStyle() { return this.style; }
+    getAlignment() { return this.alignment; }
+    getBookmarksStart() { return this.bookmarksStart; }
+    getBookmarksEnd() { return this.bookmarksEnd; }
+    getRuns() { return this.content.filter((c: any) => c instanceof MockRun && !(c instanceof MockImageRun)); }
+  }
+
+  return {
+    Paragraph: MockParagraph,
+    Run: MockRun,
+    Hyperlink: MockHyperlink,
+    ImageRun: MockImageRun,
+    Shape: MockShape,
+    TextBox: MockTextBox,
+    Field: MockField,
+    Revision: MockRevision,
+  };
+});
+
+// Import mocked module — jest.mock is hoisted above imports by Jest
+import {
+  Paragraph, Run, Hyperlink, ImageRun, Shape, TextBox, Field, Revision,
+} from "docxmlater";
+
+describe("isParagraphBlank", () => {
+  it("should return true for empty paragraph", () => {
+    const para = new Paragraph({ content: [] });
+    expect(isParagraphBlank(para)).toBe(true);
+  });
+
+  it("should return true for paragraph with whitespace-only run", () => {
+    const para = new Paragraph({ content: [new Run("   ")] });
+    expect(isParagraphBlank(para)).toBe(true);
+  });
+
+  it("should return false for paragraph with text", () => {
+    const para = new Paragraph({ content: [new Run("Hello")] });
+    expect(isParagraphBlank(para)).toBe(false);
+  });
+
+  it("should return false for paragraph with hyperlink", () => {
+    const para = new Paragraph({ content: [new Hyperlink()] });
+    expect(isParagraphBlank(para)).toBe(false);
+  });
+
+  it("should return false for paragraph with ImageRun", () => {
+    const para = new Paragraph({ content: [new ImageRun()] });
+    expect(isParagraphBlank(para)).toBe(false);
+  });
+
+  it("should return false for paragraph with Shape", () => {
+    const para = new Paragraph({ content: [new Shape()] });
+    expect(isParagraphBlank(para)).toBe(false);
+  });
+
+  it("should return false for paragraph with TextBox", () => {
+    const para = new Paragraph({ content: [new TextBox()] });
+    expect(isParagraphBlank(para)).toBe(false);
+  });
+
+  it("should return false for paragraph with Field", () => {
+    const para = new Paragraph({ content: [new Field()] });
+    expect(isParagraphBlank(para)).toBe(false);
+  });
+
+  it("should return false for paragraph with non-empty Revision", () => {
+    const para = new Paragraph({ content: [new Revision("tracked text")] });
+    expect(isParagraphBlank(para)).toBe(false);
+  });
+
+  it("should return true for paragraph with bookmarks but no content (early return)", () => {
+    // Note: The function returns true for empty content before checking bookmarks.
+    // Bookmarks are only checked when content items exist but are all blank.
+    const para = new Paragraph({
+      content: [],
+      bookmarksStart: [{ id: 1 }],
+    });
+    expect(isParagraphBlank(para)).toBe(true);
+  });
+
+  it("should return false for paragraph with bookmarks and whitespace run", () => {
+    const para = new Paragraph({
+      content: [new Run("  ")],
+      bookmarksStart: [{ id: 1 }],
+    });
+    expect(isParagraphBlank(para)).toBe(false);
+  });
+
+  it("should return true for Revision with only whitespace", () => {
+    const para = new Paragraph({ content: [new Revision("  ")] });
+    expect(isParagraphBlank(para)).toBe(true);
+  });
+});
+
+describe("startsWithBoldColon", () => {
+  it("should return true for bold text with colon", () => {
+    const para = new Paragraph({
+      content: [new Run("Note:", { bold: true })],
+    });
+    expect(startsWithBoldColon(para)).toBe(true);
+  });
+
+  it("should return false for non-bold text with colon", () => {
+    const para = new Paragraph({
+      content: [new Run("Note:", { bold: false })],
+    });
+    expect(startsWithBoldColon(para)).toBe(false);
+  });
+
+  it("should return false for bold text without colon", () => {
+    const para = new Paragraph({
+      content: [new Run("Note", { bold: true })],
+    });
+    expect(startsWithBoldColon(para)).toBe(false);
+  });
+
+  it("should return false for empty paragraph", () => {
+    const para = new Paragraph({ content: [] });
+    expect(startsWithBoldColon(para)).toBe(false);
+  });
+});
+
+describe("isCenteredBoldText", () => {
+  it("should return true for centered bold paragraph", () => {
+    const para = new Paragraph({
+      content: [new Run("TITLE", { bold: true })],
+      alignment: "center",
+    });
+    expect(isCenteredBoldText(para)).toBe(true);
+  });
+
+  it("should return false for left-aligned bold paragraph", () => {
+    const para = new Paragraph({
+      content: [new Run("TITLE", { bold: true })],
+      alignment: "left",
+    });
+    expect(isCenteredBoldText(para)).toBe(false);
+  });
+
+  it("should return false for centered non-bold paragraph", () => {
+    const para = new Paragraph({
+      content: [new Run("TITLE", { bold: false })],
+      alignment: "center",
+    });
+    expect(isCenteredBoldText(para)).toBe(false);
+  });
+
+  it("should return false for empty paragraph", () => {
+    const para = new Paragraph({ content: [], alignment: "center" });
+    expect(isCenteredBoldText(para)).toBe(false);
+  });
+});
+
+describe("isTocParagraph", () => {
+  it('should return true for "TOC1" style', () => {
+    const para = new Paragraph({ style: "TOC1" });
+    expect(isTocParagraph(para)).toBe(true);
+  });
+
+  it('should return true for "toc2" style', () => {
+    const para = new Paragraph({ style: "toc2" });
+    expect(isTocParagraph(para)).toBe(true);
+  });
+
+  it('should return true for "toc 3" style', () => {
+    const para = new Paragraph({ style: "toc 3" });
+    expect(isTocParagraph(para)).toBe(true);
+  });
+
+  it("should return false for Normal style", () => {
+    const para = new Paragraph({ style: "Normal" });
+    expect(isTocParagraph(para)).toBe(false);
+  });
+
+  it("should return false for empty style", () => {
+    const para = new Paragraph({ style: "" });
+    expect(isTocParagraph(para)).toBe(false);
+  });
+});
+
+describe("isTextOnlyParagraph", () => {
+  it("should return true for paragraph with only text runs", () => {
+    const para = new Paragraph({
+      content: [new Run("Hello world")],
+    });
+    expect(isTextOnlyParagraph(para)).toBe(true);
+  });
+
+  it("should return false for blank paragraph", () => {
+    const para = new Paragraph({ content: [] });
+    expect(isTextOnlyParagraph(para)).toBe(false);
+  });
+
+  it("should return false for paragraph with image", () => {
+    const para = new Paragraph({ content: [new ImageRun()] });
+    expect(isTextOnlyParagraph(para)).toBe(false);
+  });
+
+  it("should return false for paragraph with shape", () => {
+    const para = new Paragraph({ content: [new Shape()] });
+    expect(isTextOnlyParagraph(para)).toBe(false);
+  });
+});

package/src/services/document/blanklines/helpers/blankLineInsertion.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared utilities for creating and inserting blank paragraphs.
+ * Encapsulates the repeated insert-or-mark pattern used across all phases.
+ */
+
+import { Document, Paragraph } from "docxmlater";
+import type { BlankLineOptions } from "../types";
+import { isParagraphBlank } from "./paragraphChecks";
+
+/**
+ * Creates a blank paragraph with the specified options.
+ */
+export function createBlankParagraph(options: BlankLineOptions): Paragraph {
+  const blankPara = Paragraph.create();
+  blankPara.setStyle(options.style);
+  if (options.spacingBefore !== undefined) {
+    blankPara.setSpaceBefore(options.spacingBefore);
+  }
+  blankPara.setSpaceAfter(options.spacingAfter);
+  if (options.lineSpacing !== undefined) {
+    blankPara.setLineSpacing(options.lineSpacing);
+  }
+  if (options.markAsPreserved) {
+    blankPara.setPreserved(true);
+  }
+  return blankPara;
+}
+
+/**
+ * Inserts a blank paragraph after the element at the given index,
+ * or marks the existing blank if one is already there.
+ *
+ * @returns 'added' if a new blank was inserted, 'marked' if existing was marked, 'skipped' if no action taken
+ */
+export function insertOrMarkBlankAfter(
+  doc: Document,
+  elementIndex: number,
+  options: BlankLineOptions
+): "added" | "marked" | "skipped" {
+  const nextElement = doc.getBodyElementAt(elementIndex + 1);
+
+  if (nextElement instanceof Paragraph && isParagraphBlank(nextElement)) {
+    // Mark existing blank as preserved
+    nextElement.setStyle(options.style);
+    if (options.markAsPreserved && !nextElement.isPreserved()) {
+      nextElement.setPreserved(true);
+      return "marked";
+    }
+    return "skipped";
+  } else {
+    // Insert new blank paragraph
+    const blankPara = createBlankParagraph(options);
+    doc.insertBodyElementAt(elementIndex + 1, blankPara);
+    return "added";
+  }
+}
+
+/**
+ * Inserts a blank paragraph before the element at the given index,
+ * or marks the existing blank if one is already there.
+ *
+ * @returns 'added' if a new blank was inserted, 'marked' if existing was marked, 'skipped' if no action taken
+ */
+export function insertOrMarkBlankBefore(
+  doc: Document,
+  elementIndex: number,
+  options: BlankLineOptions
+): "added" | "marked" | "skipped" {
+  if (elementIndex <= 0) return "skipped";
+
+  const prevElement = doc.getBodyElementAt(elementIndex - 1);
+
+  if (prevElement instanceof Paragraph && isParagraphBlank(prevElement)) {
+    // Mark existing blank as preserved
+    prevElement.setStyle(options.style);
+    if (options.markAsPreserved && !prevElement.isPreserved()) {
+      prevElement.setPreserved(true);
+      return "marked";
+    }
+    return "skipped";
+  } else {
+    // Insert new blank paragraph before the element
+    const blankPara = createBlankParagraph(options);
+    doc.insertBodyElementAt(elementIndex, blankPara);
+    return "added";
+  }
+}

package/src/services/document/blanklines/helpers/blankLineSnapshot.ts

@@ -0,0 +1,251 @@
+/**
+ * Blank Line Snapshot - Captures original blank line positions before processing.
+ *
+ * This module enables the "preserve original if no rule matches" approach.
+ * It records blank paragraph positions using content hashes of neighboring
+ * elements so positions can be re-located after processing shifts indices.
+ */
+
+import { Document, Paragraph, Table, TableCell, Revision } from "docxmlater";
+import { isParagraphBlank } from "./paragraphChecks";
+
+/**
+ * Hash of an element's key characteristics for matching after processing.
+ */
+interface ElementHash {
+  type: "paragraph" | "table" | "none";
+  textPrefix: string;
+  style: string;
+  hasNumbering: boolean;
+}
+
+interface BodyBlankPosition {
+  beforeHash: ElementHash;
+  afterHash: ElementHash;
+}
+
+interface CellBlankPosition {
+  /** Identification of the cell by its table's first-cell text + row/col */
+  cellId: string;
+  paraIndexInCell: number;
+  beforeHash: ElementHash;
+  afterHash: ElementHash;
+}
+
+export interface BlankLineSnapshot {
+  bodyBlanks: BodyBlankPosition[];
+  cellBlanks: CellBlankPosition[];
+}
+
+/**
+ * Gets text from a paragraph, falling back to Revision content when
+ * getText() returns empty (which happens for revision-wrapped paragraphs
+ * in preserve mode).
+ */
+function getParaText(para: Paragraph): string {
+  const text = para.getText() || "";
+  if (text) return text;
+
+  // Fallback: extract text from Revision elements (tracked insertions)
+  for (const item of para.getContent()) {
+    if (item instanceof Revision) {
+      const revText = item.getText() || "";
+      if (revText) return revText;
+    }
+  }
+  return "";
+}
+
+/**
+ * Computes a hash of an element for neighbor-matching.
+ */
+function hashElement(element: any): ElementHash {
+  if (!element) {
+    return { type: "none", textPrefix: "", style: "", hasNumbering: false };
+  }
+
+  if (element instanceof Paragraph) {
+    const text = getParaText(element);
+    return {
+      type: "paragraph",
+      textPrefix: text.substring(0, 50),
+      style: element.getStyle() || "",
+      hasNumbering: !!element.getNumbering(),
+    };
+  }
+
+  if (element instanceof Table) {
+    // Use first cell text as identifier
+    let firstCellText = "";
+    try {
+      const cell = element.getCell(0, 0);
+      if (cell) {
+        firstCellText = cell
+          .getParagraphs()
+          .map((p) => p.getText())
+          .join(" ")
+          .substring(0, 50);
+      }
+    } catch {
+      // Table may not have cells
+    }
+    return {
+      type: "table",
+      textPrefix: firstCellText,
+      style: "",
+      hasNumbering: false,
+    };
+  }
+
+  return { type: "none", textPrefix: "", style: "", hasNumbering: false };
+}
+
+/**
+ * Computes a hash for a paragraph within a cell.
+ */
+function hashParagraph(para: Paragraph | undefined): ElementHash {
+  if (!para) {
+    return { type: "none", textPrefix: "", style: "", hasNumbering: false };
+  }
+  const text = getParaText(para);
+  return {
+    type: "paragraph",
+    textPrefix: text.substring(0, 50),
+    style: para.getStyle() || "",
+    hasNumbering: !!para.getNumbering(),
+  };
+}
+
+/**
+ * Creates a cell identifier string for matching.
+ */
+function makeCellId(
+  tableIndex: number,
+  rowIndex: number,
+  colIndex: number,
+  tableFirstCellText: string
+): string {
+  return `t${tableIndex}_r${rowIndex}_c${colIndex}_${tableFirstCellText.substring(0, 20)}`;
+}
+
+/**
+ * Checks if two element hashes match (allowing minor differences).
+ */
+function hashesMatch(a: ElementHash, b: ElementHash): boolean {
+  if (a.type !== b.type) return false;
+  if (a.type === "none" && b.type === "none") return true;
+  // Match on text prefix and numbering state
+  return a.textPrefix === b.textPrefix && a.hasNumbering === b.hasNumbering;
+}
+
+/**
+ * Captures positions of all blank paragraphs in the document.
+ * Must be called BEFORE any processing modifies the document.
+ */
+export function captureBlankLineSnapshot(doc: Document): BlankLineSnapshot {
+  const bodyBlanks: BodyBlankPosition[] = [];
+  const cellBlanks: CellBlankPosition[] = [];
+
+  // Capture body-level blanks
+  const bodyCount = doc.getBodyElementCount();
+  for (let i = 0; i < bodyCount; i++) {
+    const element = doc.getBodyElementAt(i);
+    if (!(element instanceof Paragraph)) continue;
+    if (!isParagraphBlank(element)) continue;
+
+    const prev = i > 0 ? doc.getBodyElementAt(i - 1) : undefined;
+    const next =
+      i < bodyCount - 1 ? doc.getBodyElementAt(i + 1) : undefined;
+
+    bodyBlanks.push({
+      beforeHash: hashElement(prev),
+      afterHash: hashElement(next),
+    });
+  }
+
+  // Capture cell-level blanks
+  const tables = doc.getAllTables();
+  for (let ti = 0; ti < tables.length; ti++) {
+    const table = tables[ti];
+    let tableFirstCellText = "";
+    try {
+      const firstCell = table.getCell(0, 0);
+      if (firstCell) {
+        tableFirstCellText = firstCell
+          .getParagraphs()
+          .map((p) => p.getText())
+          .join(" ")
+          .substring(0, 20);
+      }
+    } catch {
+      // Skip
+    }
+
+    const rows = table.getRows();
+    for (let ri = 0; ri < rows.length; ri++) {
+      const cells = rows[ri].getCells();
+      for (let ci = 0; ci < cells.length; ci++) {
+        const cell = cells[ci];
+        const paras = cell.getParagraphs();
+        const cellId = makeCellId(ti, ri, ci, tableFirstCellText);
+
+        for (let pi = 0; pi < paras.length; pi++) {
+          if (!isParagraphBlank(paras[pi])) continue;
+
+          cellBlanks.push({
+            cellId,
+            paraIndexInCell: pi,
+            beforeHash: hashParagraph(paras[pi - 1]),
+            afterHash: hashParagraph(paras[pi + 1]),
+          });
+        }
+      }
+    }
+  }
+
+  return { bodyBlanks, cellBlanks };
+}
+
+/**
+ * Checks if a blank line existed at the given body position in the original document.
+ * Uses neighbor hashes to match positions after indices have shifted.
+ */
+export function wasOriginallyBlankAtBody(
+  snapshot: BlankLineSnapshot,
+  doc: Document,
+  index: number
+): boolean {
+  const prev = index > 0 ? doc.getBodyElementAt(index - 1) : undefined;
+  const next =
+    index < doc.getBodyElementCount() - 1
+      ? doc.getBodyElementAt(index + 1)
+      : undefined;
+
+  const prevHash = hashElement(prev);
+  const nextHash = hashElement(next);
+
+  return snapshot.bodyBlanks.some(
+    (b) => hashesMatch(b.beforeHash, prevHash) && hashesMatch(b.afterHash, nextHash)
+  );
+}
+
+/**
+ * Checks if a blank line existed at the given cell position in the original document.
+ */
+export function wasOriginallyBlankInCell(
+  snapshot: BlankLineSnapshot,
+  cell: TableCell,
+  paraIndex: number,
+  cellId: string
+): boolean {
+  const paras = cell.getParagraphs();
+  const prevHash = hashParagraph(paras[paraIndex - 1]);
+  const nextHash = hashParagraph(paras[paraIndex + 1]);
+
+  return snapshot.cellBlanks.some(
+    (b) =>
+      b.cellId === cellId &&
+      hashesMatch(b.beforeHash, prevHash) &&
+      hashesMatch(b.afterHash, nextHash)
+  );
+}