@lotics/xlsx 0.1.0

package/src/xlsx_round_trip.test.ts

@@ -0,0 +1,279 @@
+// =============================================================================
+// xlsx round-trip — parse(real .xlsx) → export → parse → assert identical
+// =============================================================================
+//
+// Real-fixture round-trip coverage. The earlier round-trip suite in
+// `xlsx_writer.test.ts` only exercised in-memory model → write → parse,
+// so the parser → writer path was never tested with colors that come from
+// an OOXML source. The bug behind the "Debit Note shows black backgrounds"
+// regression lived exactly there: the parser stored colors as `rgb(r, g, b)`
+// CSS strings while the writer assumed `#RRGGBB` hex.
+//
+// These tests build a styled fixture via ExcelJS (so the colors take the
+// "real" path through the parser), then verify that:
+//   1. The parser normalizes colors to canonical `#RRGGBB`.
+//   2. The writer emits valid OOXML for those colors (`FFRRGGBB` ARGB),
+//      not garbled `FFrgb(r, g, b)`.
+//   3. Re-parsing the exported file yields the same model.
+//   4. Styles passthrough kicks in when no styles have been mutated.
+
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import ExcelJS from "exceljs";
+import { exportWorkbook } from "./xlsx_writer";
+import { parseExcelFromZip } from "./excel_parser";
+import { unzipXlsx } from "./ooxml_zip";
+import { loadWorkbookFromSnapshot } from "./workbook_model";
+
+async function buildStyledFixture(): Promise<ArrayBuffer> {
+  const wb = new ExcelJS.Workbook();
+  const ws = wb.addWorksheet("Sales");
+
+  // Title row: dark-blue background, white bold text, merged
+  ws.getCell("A1").value = "Q1 Report";
+  ws.getCell("A1").font = { bold: true, color: { argb: "FFFFFFFF" }, size: 16 };
+  ws.getCell("A1").fill = {
+    type: "pattern",
+    pattern: "solid",
+    fgColor: { argb: "FF003366" },
+  };
+  ws.mergeCells("A1:C1");
+
+  // Header row with gray background and dark text
+  ws.getCell("A2").value = "Product";
+  ws.getCell("B2").value = "Revenue";
+  ws.getCell("C2").value = "Margin";
+  for (const ref of ["A2", "B2", "C2"]) {
+    ws.getCell(ref).font = { bold: true, color: { argb: "FF333333" } };
+    ws.getCell(ref).fill = {
+      type: "pattern",
+      pattern: "solid",
+      fgColor: { argb: "FFF2F2F2" },
+    };
+  }
+
+  // Data rows
+  ws.getCell("A3").value = "Widget";
+  ws.getCell("B3").value = 1234.56;
+  ws.getCell("C3").value = 0.42;
+  ws.getCell("A4").value = "Gadget";
+  ws.getCell("B4").value = 789;
+  ws.getCell("C4").value = 0.31;
+
+  // Totals row: red text, cream background
+  ws.getCell("A5").value = "Total";
+  ws.getCell("A5").font = { bold: true, color: { argb: "FFCC0000" } };
+  ws.getCell("B5").value = 2023.56;
+  ws.getCell("B5").font = { bold: true, color: { argb: "FFCC0000" } };
+  for (const ref of ["A5", "B5", "C5"]) {
+    ws.getCell(ref).fill = {
+      type: "pattern",
+      pattern: "solid",
+      fgColor: { argb: "FFFFFBF0" },
+    };
+  }
+
+  const buffer = await wb.xlsx.writeBuffer();
+  return buffer as ArrayBuffer;
+}
+
+function unzipToEntries(bytes: Uint8Array): Record<string, Uint8Array> {
+  const ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  return unzipXlsx(ab as ArrayBuffer);
+}
+
+describe("xlsx round-trip — real fixture", () => {
+  it("parser normalizes solid fill colors to #RRGGBB", async () => {
+    const buffer = await buildStyledFixture();
+    const zip = unzipXlsx(buffer);
+    const parsed = parseExcelFromZip(zip);
+    const sheet = parsed.sheets[0];
+
+    const titleCell = sheet.rows.find((r) => r.index === 1)?.cells.find((c) => c.column === 1);
+    expect(titleCell?.style.backgroundColor).toBe("#003366");
+    expect(titleCell?.style.fontColor).toBe("#FFFFFF");
+
+    const headerCell = sheet.rows.find((r) => r.index === 2)?.cells.find((c) => c.column === 1);
+    expect(headerCell?.style.backgroundColor).toBe("#F2F2F2");
+    expect(headerCell?.style.fontColor).toBe("#333333");
+
+    const totalCell = sheet.rows.find((r) => r.index === 5)?.cells.find((c) => c.column === 1);
+    expect(totalCell?.style.fontColor).toBe("#CC0000");
+    expect(totalCell?.style.backgroundColor).toBe("#FFFBF0");
+  });
+
+  it("writer emits valid 8-char ARGB for solid fills (regression: not FFrgb(...))", async () => {
+    const buffer = await buildStyledFixture();
+    const zip = unzipXlsx(buffer);
+    const parsed = parseExcelFromZip(zip);
+    const wb = loadWorkbookFromSnapshot(parsed);
+
+    // Force a value mutation so we exit passthrough mode and exercise the
+    // styles XML rebuild path. Setting an existing cell's value with the
+    // same style should NOT dirty the registry, but we want to ensure the
+    // regen path itself produces valid colors when it does run.
+    wb.styles.dirty = true;
+
+    const exported = exportWorkbook(wb, zip);
+    const exportedZip = unzipToEntries(exported);
+    const stylesXml = new TextDecoder().decode(exportedZip["xl/styles.xml"]);
+
+    // No invalid `FFrgb(...)` substrings — the bug signature.
+    expect(stylesXml).not.toContain("FFrgb(");
+    // The original solid fill colors survive as proper 8-char ARGB.
+    expect(stylesXml).toContain("FF003366");
+    expect(stylesXml).toContain("FFF2F2F2");
+    expect(stylesXml).toContain("FFCC0000");
+    expect(stylesXml).toContain("FFFFFBF0");
+  });
+
+  it("re-parsing the exported file yields identical colors and merges", async () => {
+    const buffer = await buildStyledFixture();
+    const zip = unzipXlsx(buffer);
+    const parsed = parseExcelFromZip(zip);
+    const wb = loadWorkbookFromSnapshot(parsed);
+
+    // Force a regen to test the writer's color emission, not just passthrough.
+    wb.styles.dirty = true;
+
+    const exportedBytes = exportWorkbook(wb, zip);
+    const exportedZip = unzipToEntries(exportedBytes);
+    const reParsed = parseExcelFromZip(exportedZip);
+    const sheet = reParsed.sheets[0];
+
+    // Title fill survives parser → writer → parser.
+    const titleCell = sheet.rows.find((r) => r.index === 1)?.cells.find((c) => c.column === 1);
+    expect(titleCell?.style.backgroundColor).toBe("#003366");
+    expect(titleCell?.style.fontColor).toBe("#FFFFFF");
+
+    // Header background.
+    const headerCell = sheet.rows.find((r) => r.index === 2)?.cells.find((c) => c.column === 1);
+    expect(headerCell?.style.backgroundColor).toBe("#F2F2F2");
+
+    // Merged title range.
+    const merge = sheet.mergedCells.find((m) => m.startRow === 1 && m.startCol === 1);
+    expect(merge).toBeDefined();
+    expect(merge?.endRow).toBe(1);
+    expect(merge?.endCol).toBe(3);
+  });
+
+  it("passthrough mode skips styles regeneration on a value-only mutation", async () => {
+    const buffer = await buildStyledFixture();
+    const zip = unzipXlsx(buffer);
+    const parsed = parseExcelFromZip(zip);
+    const wb = loadWorkbookFromSnapshot(parsed);
+
+    // Sanity: parser → loadWorkbookFromSnapshot leaves the registry clean.
+    expect(wb.styles.dirty).toBe(false);
+
+    // Mutate a cell value via the fast path the placeholder engine uses.
+    const sheet = wb.sheets[0];
+    const titleCell = sheet.getCell("A1");
+    sheet.setWithStyleIndex("A1", "Q2 Report", titleCell!.styleIndex, titleCell!.numFmtCode, undefined, titleCell!.originalXfIndex);
+
+    // Still clean — no new style or numFmt was introduced.
+    expect(wb.styles.dirty).toBe(false);
+
+    const exported = exportWorkbook(wb, zip);
+    const exportedZip = unzipToEntries(exported);
+    const stylesXml = new TextDecoder().decode(exportedZip["xl/styles.xml"]);
+
+    // Passthrough: the bytes should be byte-identical to the original.
+    expect(stylesXml).toBe(new TextDecoder().decode(zip["xl/styles.xml"]));
+
+    // And re-parsing still resolves the title cell with the new value and
+    // the original styling (proves cell `s=` indexes survived passthrough).
+    const reParsed = parseExcelFromZip(exportedZip);
+    const reTitle = reParsed.sheets[0].rows.find((r) => r.index === 1)?.cells.find((c) => c.column === 1);
+    expect(reTitle?.value).toBe("Q2 Report");
+    expect(reTitle?.style.backgroundColor).toBe("#003366");
+    expect(reTitle?.style.fontColor).toBe("#FFFFFF");
+  });
+
+  it("styles dirty flag flips when a new style is interned", async () => {
+    const buffer = await buildStyledFixture();
+    const zip = unzipXlsx(buffer);
+    const parsed = parseExcelFromZip(zip);
+    const wb = loadWorkbookFromSnapshot(parsed);
+    expect(wb.styles.dirty).toBe(false);
+
+    // Intern a brand-new style — should flip dirty.
+    wb.styles.intern({ fontBold: true, backgroundColor: "#ABCDEF" });
+    expect(wb.styles.dirty).toBe(true);
+  });
+
+  // End-to-end validation against the actual customer template that
+  // surfaced the bug. Skipped if the file isn't present (developers without
+  // a local copy can still run the rest of the suite).
+  const debitNotePath = "/tmp/debit_note_template_v2.xlsx";
+  const hasDebitNote = fs.existsSync(debitNotePath);
+  it.skipIf(!hasDebitNote)("regenerates the real Debit Note template without the FFrgb(...) bug", () => {
+    const bytes = fs.readFileSync(debitNotePath);
+    const ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    const zip = unzipXlsx(ab);
+    const parsed = parseExcelFromZip(zip);
+    const wb = loadWorkbookFromSnapshot(parsed);
+
+    expect(wb.styles.dirty).toBe(false);
+
+    // Force the regen path so we exercise the writer's color emission, not
+    // just the passthrough fast path. (Passthrough is also tested above.)
+    wb.styles.dirty = true;
+    const exported = exportWorkbook(wb, zip);
+    const exportedZip = unzipToEntries(exported);
+    const stylesXml = new TextDecoder().decode(exportedZip["xl/styles.xml"]);
+
+    // The bug signature: never appears.
+    expect(stylesXml).not.toContain("FFrgb(");
+
+    // The original DebitNote palette survives intact.
+    expect(stylesXml).toContain("FF003366"); // header dark blue
+    expect(stylesXml).toContain("FFF2F2F2"); // light gray
+    expect(stylesXml).toContain("FFCC0000"); // alert red
+    expect(stylesXml).toContain("FFFFFBF0"); // cream
+  });
+
+  it("registerNumFmt flips dirty for unknown codes only", async () => {
+    const buffer = await buildStyledFixture();
+    const zip = unzipXlsx(buffer);
+    const parsed = parseExcelFromZip(zip);
+    const wb = loadWorkbookFromSnapshot(parsed);
+    expect(wb.styles.dirty).toBe(false);
+
+    // Already-known code: stays clean.
+    wb.styles.registerNumFmt("General");
+    expect(wb.styles.dirty).toBe(false);
+
+    // Brand-new code: dirties.
+    wb.styles.registerNumFmt('"$"#,##0.00');
+    expect(wb.styles.dirty).toBe(true);
+  });
+
+  it("preserves XML entities in formatCode across round-trip", async () => {
+    // `processEntities: false` means the parser returns attribute values with
+    // `&quot;`, `&amp;`, etc. still escaped; every parser site must decode them
+    // before storing in the model. Skipping the decode causes the writer to
+    // re-escape `&` → `&amp;`, producing `&amp;quot;` — Excel/LibreOffice then
+    // renders the literal garbage `&quot-&quot` where `"-"` should appear.
+    const wb = new ExcelJS.Workbook();
+    const ws = wb.addWorksheet("S");
+    ws.getCell("A1").value = 0;
+    ws.getCell("A1").numFmt = '#,##0;(#,##0);"-"';
+    const ab = (await wb.xlsx.writeBuffer()) as ArrayBuffer;
+
+    const zip = unzipXlsx(ab);
+    const parsed = parseExcelFromZip(zip);
+    const wbModel = loadWorkbookFromSnapshot(parsed);
+
+    // Parser surfaces the decoded code, not the escaped XML form.
+    const cellFmt = wbModel.sheets[0].cells.get("A1")?.numFmtCode;
+    expect(cellFmt).toBe('#,##0;(#,##0);"-"');
+
+    // Writer emits single-escaped XML, never double-escaped.
+    wbModel.styles.dirty = true;
+    const exported = exportWorkbook(wbModel, zip);
+    const stylesXml = new TextDecoder().decode(unzipToEntries(exported)["xl/styles.xml"]);
+    expect(stylesXml).toContain("&quot;-&quot;");
+    expect(stylesXml).not.toContain("&amp;quot;");
+  });
+});