@sun-asterisk/sungen 3.2.6 → 3.2.7

package/src/exporters/xlsx-exporter.ts

@@ -1,12 +1,15 @@
 /**
- * Render the same rows/summary the CSV exporter produces into a styled .xlsx
- * workbook. Keeps the BM-2-901-13 layout but adds:
- *   - bold header row with filled background + white font
- *   - borders on the data region
- *   - text wrapping in Steps / Expected / Pre-condition / Test Data
- *   - frozen header so the first data rows stay aligned with the title row
- *   - sensible column widths
- *   - category-separator rows rendered as a filled bar spanning the table
+ * Node-side wrapper around the shared pure workbook builder
+ * (`xlsx-report-builder.ts` — the single source of truth for the BM-2-901-13
+ * report rendering, also bundled into the dashboard). This module keeps only:
+ *   - Node file I/O: `writeXlsx` + the `lockEmbeddedImages` post-process
+ *   - the CLI version lookup (`getPackageVersion`, fs-based) injected as
+ *     `opts.sungenVersion`
+ *   - thin adapters mapping core domain types (ScreenSummary / TestCaseRow /
+ *     LocaleSheet / ApiCatalogEntry) onto the builder input — pure field
+ *     mapping, no rendering logic.
+ * Public API is unchanged: `renderXlsx`, `renderXlsxMultiSheet`, `writeXlsx`,
+ * `buildApiDetailRows`, `addApiDetailSheet`, `ApiDetailContext`, `LocaleSheet`.
  */
 
 import * as fs from 'fs';
@@ -15,41 +18,21 @@ import ExcelJS from 'exceljs';
 import JSZip from 'jszip';
 import { ApiCatalogEntry, ApiDetailRow, ScreenSummary, TestCaseRow } from './types';
 import { getPackageVersion } from './package-info';
-import { SUN_LOGO_PNG_BASE64 } from './sun-logo';
 import { deliverableBasename } from './csv-exporter';
 import {
   extractApiCallOrder,
   extractCasesDataset,
   extractConcurrencyInvariant,
 } from './feature-parser';
+import {
+  buildApiDetailRows as buildApiDetailRowsPure,
+  buildSingleTestcaseWorkbook,
+  buildTestcaseWorkbook,
+  addApiDetailSheet,
+} from './xlsx-report-builder';
 
-const COL_COUNT = 16;
-const HEADER_FILL = 'FFD9D2E9'; // lavender — matches the summary-header band on row 6
-const HEADER_FONT = 'FF000000'; // black text reads better on the light lavender
-const META_FILL = 'FFDCE6F1'; // soft blue for meta rows
-const CATEGORY_FILL = 'FFD9D2E9'; // same lavender for group dividers (Accessing / GUI / Function)
-const BORDER_COLOR = 'FFBFBFBF';
-
-// Shared masthead + table styling (BM-2-901-13 header band, summary band, Overview table).
-const TIMES = 'Times New Roman';
-const ARIAL_FONT = 'Arial';
-const BLACK = { argb: 'FF000000' };
-const WHITE = { argb: 'FFFFFFFF' };
-const LAVENDER = { argb: 'FFD9D2E9' };
-const thinBlack = { style: 'thin' as const, color: BLACK };
-const allBordersBlack = { top: thinBlack, left: thinBlack, bottom: thinBlack, right: thinBlack };
-
-type AnyCell = ExcelJS.Cell;
-type AnyRow = ExcelJS.Row;
-
-function applyBorder(cell: AnyCell): void {
-  cell.border = {
-    top: { style: 'thin', color: { argb: BORDER_COLOR } },
-    left: { style: 'thin', color: { argb: BORDER_COLOR } },
-    bottom: { style: 'thin', color: { argb: BORDER_COLOR } },
-    right: { style: 'thin', color: { argb: BORDER_COLOR } },
-  };
-}
+// Re-exported unchanged — the implementation lives in the pure builder.
+export { addApiDetailSheet };
 
 /**
  * Optional context for the supplementary "API detail" worksheet.
@@ -69,14 +52,11 @@ export function renderXlsx(
   specLink: string,
   apiDetail?: ApiDetailContext,
 ): ExcelJS.Workbook {
-  const wb = new ExcelJS.Workbook();
-  wb.creator = 'sungen delivery';
-  wb.created = new Date();
-  addTestcaseSheet(wb, 'Testcases', summary, rows, specLink);
-  if (apiDetail) {
-    addApiDetailSheet(wb, apiDetail.rows);
-  }
-  return wb;
+  return buildSingleTestcaseWorkbook(
+    { sheetName: 'Testcases', summary, rows, specLink },
+    apiDetail,
+    { sungenVersion: getPackageVersion() },
+  );
 }
 
 /**
@@ -99,491 +79,16 @@ export interface LocaleSheet {
 }
 
 export function renderXlsxMultiSheet(sheets: LocaleSheet[]): ExcelJS.Workbook {
-  if (sheets.length === 0) {
-    throw new Error('renderXlsxMultiSheet requires at least one locale sheet');
-  }
-  const wb = new ExcelJS.Workbook();
-  wb.creator = 'sungen delivery';
-  wb.created = new Date();
-  // Overview first — a per-sheet roll-up (Passed/Failed/Pending/N/A/Remain/Total)
-  // plus a grand-total row, so QA sees the whole picture before the detail sheets.
-  addOverviewSheet(wb, sheets);
-  for (const s of sheets) {
-    addTestcaseSheet(wb, s.sheetName, s.summary, s.rows, s.specLink);
-  }
-  return wb;
-}
-
-/**
- * Render the shared BM-2-901-13 masthead (rows 1-4) onto a worksheet:
- * Sun* logo (A1:C3), TESTCASE title (D1:F3), No/Version/Issue-Date block
- * (G1:H3), company line (A4:F4), ISO line (G4:H4). Every sheet in a delivery
- * workbook — Overview, Auto, Manual — carries this same header band.
- */
-function renderReportHeaderBand(
-  wb: ExcelJS.Workbook,
-  ws: ExcelJS.Worksheet,
-  titleLabel: string,
-): void {
-  const issueDate = (() => {
-    const d = new Date();
-    return `${String(d.getDate()).padStart(2, '0')}/${String(d.getMonth() + 1).padStart(2, '0')}/${d.getFullYear()}`;
-  })();
-
-  // Ensure rows 1..4 exist before merging.
-  for (let r = 1; r <= 4; r++) ws.getRow(r);
-
-  ws.mergeCells('A1:C3');
-  ws.mergeCells('D1:F3');
-  ws.mergeCells('G1:H1');
-  ws.mergeCells('G2:H2');
-  ws.mergeCells('G3:H3');
-  ws.mergeCells('A4:F4');
-  ws.mergeCells('G4:H4');
-
-  // A1 (logo band, merged A1:C3) — border + embedded Sun* logo (base64 inline).
-  const a1 = ws.getCell('A1');
-  a1.alignment = { horizontal: 'center', vertical: 'middle' };
-  a1.border = allBordersBlack;
-
-  try {
-    const imageId = wb.addImage({
-      buffer: Buffer.from(SUN_LOGO_PNG_BASE64, 'base64') as unknown as ExcelJS.Buffer,
-      extension: 'png',
-    });
-    // Centre a fixed-size 90×51 logo inside A1:C3 using absolute EMU offsets.
-    ws.addImage(imageId, {
-      tl: { nativeCol: 0, nativeColOff: 1237500, nativeRow: 0, nativeRowOff: 42862 } as unknown as ExcelJS.Anchor,
-      ext: { width: 90, height: 51 },
-      editAs: 'oneCell',
-    } as unknown as ExcelJS.ImageRange);
-  } catch { /* logo is decorative — never block export */ }
-
-  // D1 (TESTCASE title)
-  const d1 = ws.getCell('D1');
-  d1.value = titleLabel;
-  d1.font = { bold: true, size: 18, name: TIMES };
-  d1.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
-  d1.border = allBordersBlack;
-
-  // G1 — No: BM-2-901-13
-  const g1 = ws.getCell('G1');
-  g1.value = 'No: BM-2-901-13';
-  g1.font = { size: 12, name: TIMES };
-  g1.alignment = { vertical: 'middle' };
-  g1.border = { top: thinBlack, left: thinBlack, right: thinBlack };
-
-  // G2 — Version
-  const g2 = ws.getCell('G2');
-  g2.value = `Version: ${getPackageVersion()}`;
-  g2.font = { size: 12, name: TIMES };
-  g2.alignment = { vertical: 'middle' };
-  g2.border = { left: thinBlack, right: thinBlack };
-
-  // G3 — Issue Date
-  const g3 = ws.getCell('G3');
-  g3.value = `Issue Date: ${issueDate}`;
-  g3.font = { size: 12, name: TIMES };
-  g3.alignment = { vertical: 'middle' };
-  g3.border = { left: thinBlack, right: thinBlack, bottom: thinBlack };
-
-  // A4 — SUN ASTERISK VIETNAM CO., LTD
-  const a4 = ws.getCell('A4');
-  a4.value = 'SUN ASTERISK VIETNAM CO., LTD';
-  a4.font = { bold: true, size: 10, name: TIMES };
-  a4.alignment = { vertical: 'middle' };
-  a4.border = allBordersBlack;
-
-  // G4 — ISO/IEC ...
-  const g4 = ws.getCell('G4');
-  g4.value = 'ISO/IEC 27001:2022 & ISO 9001:2015';
-  g4.font = { bold: true, size: 10, name: TIMES };
-  g4.alignment = { horizontal: 'right', vertical: 'middle', wrapText: true };
-  g4.border = allBordersBlack;
-}
-
-// ---------------------------------------------------------------------------
-// Overview sheet — the first tab in every multi-sheet delivery workbook.
-// Rolls up each testcase sheet's Passed/Failed/Pending/N/A/Remain/Total into
-// one summary table (+ a grand-total row) under the shared masthead. Reads
-// only each sheet's summary — never touches the detail sheets themselves.
-// ---------------------------------------------------------------------------
-
-/** Column headers for the Overview roll-up table (cols A..H). */
-const OVERVIEW_HEADERS = ['#', 'Sheet name', 'Passed', 'Failed', 'Pending', 'N/A', 'Remain', 'Total'];
-
-/**
- * Prepend an "Overview" worksheet summarizing every sheet in `sheets`.
- *
- * `Remain = Total − Passed − N/A` (i.e. Failed + Pending) so the number
- * reconciles with the "Remaining" cell in each detail sheet's summary band.
- */
-function addOverviewSheet(wb: ExcelJS.Workbook, sheets: LocaleSheet[]): void {
-  const ws = wb.addWorksheet('Overview');
-
-  // Table starts at column B row 7 (A is a thin left margin). Widths keep the
-  // A..H masthead readable AND the count columns tidy.
-  ws.columns = [
-    { width: 4 },   // A — left margin
-    { width: 6 },   // B — #
-    { width: 26 },  // C — Sheet name
-    { width: 13 },  // D — Passed
-    { width: 13 },  // E — Failed
-    { width: 13 },  // F — Pending
-    { width: 13 },  // G — N/A
-    { width: 13 },  // H — Remain
-    { width: 13 },  // I — Total
-  ];
-
-  const titleScreen = sheets[0]?.summary.screen ?? '';
-  renderReportHeaderBand(wb, ws, `${titleScreen.toUpperCase()} TESTCASE`);
-
-  // Roll-up table: header on row 7, first column B (index 2).
-  const HEADER_ROW = 7;
-  const FIRST_COL = 2; // column B
-  const headerRow = ws.getRow(HEADER_ROW);
-  headerRow.height = 20;
-  OVERVIEW_HEADERS.forEach((label, i) => {
-    const c = headerRow.getCell(FIRST_COL + i);
-    c.value = label;
-    c.font = { bold: true, size: 10, color: BLACK, name: ARIAL_FONT };
-    c.fill = { type: 'pattern', pattern: 'solid', fgColor: LAVENDER };
-    c.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
-    c.border = allBordersBlack;
-  });
-
-  const totals = { passed: 0, failed: 0, pending: 0, na: 0, remain: 0, total: 0 };
-
-  const writeDataRow = (rowIdx: number, values: ExcelJS.CellValue[], isTotal: boolean): void => {
-    const row = ws.getRow(rowIdx);
-    values.forEach((v, i) => {
-      const c = row.getCell(FIRST_COL + i);
-      c.value = v;
-      c.font = { bold: isTotal, size: 10, color: BLACK, name: ARIAL_FONT };
-      // The '#' + 'Sheet name' columns read left; the counts centre like the band.
-      c.alignment = { horizontal: i <= 1 ? 'left' : 'center', vertical: 'middle' };
-      c.border = allBordersBlack;
-      if (isTotal) c.fill = { type: 'pattern', pattern: 'solid', fgColor: LAVENDER };
-    });
-  };
-
-  // Each detail sheet carries a LIVE summary band (row 7): C7 Total · D7 Passed · E7 Failed ·
-  // F7 Pending · G7 N/A · H7 Remaining, all COUNTA/COUNTIF over the data area. The Overview
-  // REFERENCES those cells (`='<sheet>'!D7`) instead of freezing a number at export time — so when
-  // QA adds/edits/removes a row in the Auto or Manual sheet, the roll-up recomputes automatically.
-  const qname = (name: string): string => name.replace(/'/g, "''"); // Excel escapes ' by doubling
-  const ref = (name: string, cell: string, result: number): ExcelJS.CellFormulaValue =>
-    ({ formula: `'${qname(name)}'!${cell}`, result });
-
-  let rowIdx = HEADER_ROW + 1;
-  const firstDataRow = rowIdx;
-  sheets.forEach((s, i) => {
-    const su = s.summary;
-    const remain = Math.max(0, su.total - su.passed - su.na);
-    writeDataRow(rowIdx, [
-      i + 1,
-      s.sheetName,
-      ref(s.sheetName, 'D7', su.passed),
-      ref(s.sheetName, 'E7', su.failed),
-      ref(s.sheetName, 'F7', su.pending),
-      ref(s.sheetName, 'G7', su.na),
-      ref(s.sheetName, 'H7', remain),
-      ref(s.sheetName, 'C7', su.total),
-    ], false);
-    totals.passed += su.passed;
-    totals.failed += su.failed;
-    totals.pending += su.pending;
-    totals.na += su.na;
-    totals.remain += remain;
-    totals.total += su.total;
-    rowIdx += 1;
-  });
-  const lastDataRow = rowIdx - 1;
-
-  // Grand total = SUM of the per-sheet Overview cells (also live — recomputes with the references
-  // above). Overview count columns are D..I (Passed·Failed·Pending·N/A·Remain·Total).
-  const sumCol = (col: string, result: number): ExcelJS.CellFormulaValue =>
-    ({ formula: `SUM(${col}${firstDataRow}:${col}${lastDataRow})`, result });
-  writeDataRow(
-    rowIdx,
-    [
-      '', 'Total',
-      sumCol('D', totals.passed),
-      sumCol('E', totals.failed),
-      sumCol('F', totals.pending),
-      sumCol('G', totals.na),
-      sumCol('H', totals.remain),
-      sumCol('I', totals.total),
-    ],
-    true,
-  );
-}
-
-/**
- * Append one BM-2-901-13 testcase sheet to the given workbook. Sheet content
- * (layout, summary band, data rows, auto-filter, protection) is identical to
- * the single-sheet `renderXlsx` output — only the sheet name differs.
- */
-function addTestcaseSheet(
-  wb: ExcelJS.Workbook,
-  sheetName: string,
-  summary: ScreenSummary,
-  rows: TestCaseRow[],
-  specLink: string,
-): void {
-  const ws = wb.addWorksheet(sheetName, {
-    views: [{ state: 'frozen', ySplit: 0, xSplit: 0 }],
-  });
-
-  // -- Column widths matching template_report.xlsx (Sample sheet) --
-  ws.columns = [
-    { width: 20 },    // A — TC ID (wider to fit long flow IDs like FLOW-KUDO-…)
-    { width: 12.5 },  // B — Screen/Function
-    { width: 15.38 }, // C — Big item
-    { width: 16.25 }, // D — Medium item
-    { width: 17 },    // E — Test Object
-    { width: 25.5 },  // F — Pre-condition
-    { width: 24.88 }, // G — Test Data
-    { width: 50 },    // H — Steps (widened ~2× — steps are the longest cell)
-    { width: 41 },    // I — Expected results
-    { width: 12 },    // J — Priority
-    { width: 13.5 },  // K — Testcase type
-    { width: 15.88 }, // L — Test Result
-    { width: 13.5 },  // M — Executed Date
-    { width: 16.5 },  // N — Test Executor
-    { width: 23 },    // O — Test Environment
-    { width: 29 },    // P — Note
-  ];
-
-  // -- Top metadata band (rows 1-4) — shared BM-2-901-13 masthead --
-  renderReportHeaderBand(wb, ws, `${summary.screen.toUpperCase()} TESTCASE`);
-  // Materialize rows 5..8 so the summary band + row-9 spacer land at the right offsets.
-  for (let r = 5; r <= 8; r++) ws.getRow(r);
-
-  // -- Row 5: spacer (height auto-fit). --
-
-  // -- Row 6: Summary headers (cols C..H), lavender fill --
-  const sumLabels: Record<string, string> = {
-    C: 'Total TCs', D: 'Passed', E: 'Failed', F: 'Pending', G: 'N/A', H: 'Remaining',
-  };
-  for (const [col, label] of Object.entries(sumLabels)) {
-    const c = ws.getCell(`${col}6`);
-    c.value = label;
-    c.font = { bold: true, size: 10, color: BLACK, name: ARIAL_FONT };
-    c.fill = { type: 'pattern', pattern: 'solid', fgColor: LAVENDER };
-    c.alignment = { horizontal: 'center', vertical: 'top' };
-    c.border = allBordersBlack;
-  }
-  // No explicit height → Excel auto-fits this row's content.
-
-  // -- Row 7: Counts (cols C..H), live formulas referencing the data area --
-  // The data region begins at row 14 — the row immediately AFTER the column-header row (row 13).
-  // Start the ranges there (NOT row 15): the first category divider usually sits at row 14 with a
-  // BLANK col A (so COUNTA skips it), but a sheet whose first row after the header is real data —
-  // no leading divider — would be UNDER-counted by a range that started at 15. Row 14 covers both.
-  const COUNT_RANGE_START = 14;
-  const COUNT_RANGE_END = 10000;
-  const r7Values: Record<string, ExcelJS.CellValue> = {
-    C: { formula: `COUNTA(A${COUNT_RANGE_START}:A${COUNT_RANGE_END})`, result: summary.total } as ExcelJS.CellFormulaValue,
-    D: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Passed")`, result: summary.passed } as ExcelJS.CellFormulaValue,
-    E: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Failed")`, result: summary.failed } as ExcelJS.CellFormulaValue,
-    F: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Pending")`, result: summary.pending } as ExcelJS.CellFormulaValue,
-    G: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"N/A")`, result: summary.na } as ExcelJS.CellFormulaValue,
-    H: { formula: 'C7-D7-G7', result: summary.failed + summary.pending } as ExcelJS.CellFormulaValue,
-  };
-  for (const [col, val] of Object.entries(r7Values)) {
-    const c = ws.getCell(`${col}7`);
-    c.value = val;
-    c.font = { size: 10, color: BLACK, name: ARIAL_FONT };
-    c.fill = { type: 'pattern', pattern: 'solid', fgColor: WHITE };
-    c.alignment = { horizontal: 'center', vertical: 'top' };
-    c.border = allBordersBlack;
-    if (col === 'H') c.numFmt = '#,##0';
-  }
-  // No explicit height → Excel auto-fits.
-
-  // C8 has no value in the template but still needs a border so the band
-  // visually closes underneath "Total TCs".
-  const c8 = ws.getCell('C8');
-  c8.font = { size: 10, color: BLACK, name: ARIAL_FONT };
-  c8.fill = { type: 'pattern', pattern: 'solid', fgColor: WHITE };
-  c8.alignment = { horizontal: 'center', vertical: 'top' };
-  c8.border = allBordersBlack;
-
-  // -- Row 8: Percentages (cols D..H), formula = count / (Total − N/A) --
-  const r8Values: Record<string, ExcelJS.CellValue> = {
-    D: { formula: 'IFERROR(D7/(C7-G7),0)', result: summary.passed / Math.max(1, summary.total - summary.na) } as ExcelJS.CellFormulaValue,
-    E: { formula: 'IFERROR(E7/(C7-G7),0)', result: summary.failed / Math.max(1, summary.total - summary.na) } as ExcelJS.CellFormulaValue,
-    F: { formula: 'IFERROR(F7/(C7-G7),0)', result: summary.pending / Math.max(1, summary.total - summary.na) } as ExcelJS.CellFormulaValue,
-    G: { formula: 'IFERROR(G7/(C7-G7),0)', result: summary.na / Math.max(1, summary.total - summary.na) } as ExcelJS.CellFormulaValue,
-    H: { formula: 'IFERROR(H7/(C7-G7),0)', result: (summary.failed + summary.pending) / Math.max(1, summary.total - summary.na) } as ExcelJS.CellFormulaValue,
-  };
-  for (const [col, val] of Object.entries(r8Values)) {
-    const c = ws.getCell(`${col}8`);
-    c.value = val;
-    c.font = { size: 10, color: BLACK, name: ARIAL_FONT };
-    c.fill = { type: 'pattern', pattern: 'solid', fgColor: WHITE };
-    c.alignment = { horizontal: 'center', vertical: 'top' };
-    c.border = allBordersBlack;
-    c.numFmt = '0%';
-  }
-  // No explicit height → Excel auto-fits.
-
-  // After rows 1-8 are populated, append a blank row 9 spacer.
-  while (ws.rowCount < 9) ws.addRow([]);
-
-  const specRow = ws.addRow(['Spec/Design link:', specLink]);
-  specRow.getCell(1).font = { bold: true };
-  specRow.getCell(2).font = { color: { argb: 'FF1F4E78' }, underline: true };
-
-  ws.addRow([]); // spacer
-
-  const legendRow = ws.addRow(['*: Mandatory']);
-  legendRow.getCell(1).font = { italic: true, color: { argb: 'FF808080' } };
-
-  // -- Column header row (bold, filled, wrapped) --
-  const headerRow = ws.addRow([
-    'TC ID*',
-    'Screen/Function',
-    'Big item',
-    'Medium item',
-    'Test Object',
-    'Pre-condition',
-    'Test Data',
-    'Steps*',
-    'Expected results*',
-    'Priority',
-    'Testcase type',
-    'Test Result*',
-    'Executed Date*',
-    'Test Executor*',
-    'Test Environment',
-    'Note\n(Test evidence, DefectID, Actual result)',
-  ]);
-  headerRow.height = 38;
-  headerRow.eachCell((cell) => {
-    cell.font = { bold: true, color: { argb: HEADER_FONT } };
-    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: HEADER_FILL } };
-    cell.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
-    applyBorder(cell);
-  });
-
-  // No freeze — the whole sheet scrolls freely (the masthead + summary band + header scroll away
-  // with the data). QA asked for this so the wide Steps/Expected columns aren't pinned under a frozen
-  // header on smaller screens.
-  ws.views = [{ state: 'normal' }];
-
-  // -- Data rows grouped by category --
-  const order = ['Accessing', 'GUI', 'Function'];
-  const grouped = new Map<string, TestCaseRow[]>();
-  for (const r of rows) {
-    const g = grouped.get(r.category2) || [];
-    g.push(r);
-    grouped.set(r.category2, g);
-  }
-  const emittedGroups = new Set<string>();
-
-  function emitGroup(groupName: string, groupRows: TestCaseRow[]): void {
-    // Column A (TC ID) must stay TRULY blank on a divider — never write '' here. COUNTA counts
-    // empty-string cells, so an '' in A made the generated total (=COUNTA(A15:A…)) over-count by
-    // one per group divider when recalculated (e.g. in Google Sheets). Set only the group name in B;
-    // the lavender band still spans every column via the fill loop below (style only, no value).
-    const divider = ws.addRow([]);
-    divider.getCell(2).value = groupName;
-    divider.getCell(2).font = { bold: true };
-    divider.eachCell({ includeEmpty: false }, (cell) => {
-      cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: CATEGORY_FILL } };
-    });
-    // Fill the full width so the band spans the whole table
-    for (let i = 1; i <= COL_COUNT; i++) {
-      const c = divider.getCell(i);
-      c.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: CATEGORY_FILL } };
-      applyBorder(c);
-    }
-
-    for (const r of groupRows) {
-      const row = ws.addRow([
-        r.tcId,
-        '',
-        '',
-        '',
-        r.category1,
-        r.precondition,
-        r.testData,
-        r.steps,
-        r.expectedResults,
-        r.priority,
-        r.testcaseType,
-        r.testResult,
-        r.executedDate,
-        r.testExecutor,
-        r.testEnvironment,
-        r.note,
-      ]);
-      row.alignment = { vertical: 'top', wrapText: true };
-      row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
-        applyBorder(cell);
-        if (colNumber === 1) {
-          cell.font = { bold: true };
-        }
-        if (colNumber === 12) {
-          // Test Result — colour-code
-          const val = String(cell.value || '');
-          if (val === 'Passed') {
-            cell.font = { color: { argb: 'FF107C41' }, bold: true };
-          } else if (val === 'Failed') {
-            cell.font = { color: { argb: 'FFC00000' }, bold: true };
-          } else if (val === 'Pending') {
-            cell.font = { color: { argb: 'FF996D00' }, bold: true };
-          } else if (val === 'N/A') {
-            cell.font = { color: { argb: 'FF808080' } };
-          }
-        }
-      });
-    }
-  }
-
-  for (const groupName of order) {
-    const groupRows = grouped.get(groupName);
-    if (!groupRows || groupRows.length === 0) continue;
-    emittedGroups.add(groupName);
-    emitGroup(groupName, groupRows);
-  }
-  for (const [groupName, groupRows] of grouped.entries()) {
-    if (emittedGroups.has(groupName)) continue;
-    emitGroup(groupName, groupRows);
-  }
-
-  // Auto-filter on the header row so QA can filter by result / priority / category
-  ws.autoFilter = {
-    from: { row: headerRow.number, column: 1 },
-    to: { row: ws.rowCount, column: COL_COUNT },
-  };
-
-  // Sheet protection lets the picLocks on the embedded logo take effect
-  // (Excel honours image locks only when the sheet is protected). Empty
-  // password — QA can run Review → Unprotect Sheet if they need to edit.
-  // `objects: false` here is ExcelJS's inverted semantic that writes
-  // `objects="1"` in XML (= objects ARE locked).
-  (ws as unknown as { sheetProtection: object }).sheetProtection = {
-    sheet: true,
-    objects: false,
-    scenarios: false,
-  };
+  return buildTestcaseWorkbook(sheets, { sungenVersion: getPackageVersion() });
 }
 
-// ---------------------------------------------------------------------------
-// API detail sheet (api-kind units only)
-// Second worksheet appended after Testcases — never alters the Testcases sheet.
-// ---------------------------------------------------------------------------
-
-const API_DETAIL_HEADER_FILL = 'FF2E5984'; // dark blue header for differentiation
-const API_DETAIL_HEADER_FONT = 'FFFFFFFF'; // white text on dark header
-
 /**
  * Build ApiDetailRow[] from the apis.yaml catalog + feature-level annotations.
  * Called once per feature file for api-kind units in the delivery pipeline.
  *
+ * Delegates to the pure builder, injecting the feature-parser tag extractors
+ * (the builder cannot import feature-parser — it must stay browser-safe).
+ *
  * @param catalog   Parsed apis.yaml keyed by endpoint name
  * @param scenarios Scenario-level tag arrays from parseFeatureMetadata().scenarios
  */
@@ -591,138 +96,11 @@ export function buildApiDetailRows(
   catalog: Record<string, ApiCatalogEntry>,
   scenarios: Array<{ tags: string[] }>,
 ): ApiDetailRow[] {
-  const rows: ApiDetailRow[] = [];
-
-  for (const [endpointName, entry] of Object.entries(catalog)) {
-    const method = (entry.method ?? '').toUpperCase();
-    const endpoint = entry.path ?? endpointName;
-    const datasource = entry.datasource ?? '';
-
-    // Auth: look for @auth: tag in any scenario that calls this endpoint.
-    const authTags = scenarios.flatMap((s) => {
-      const calls = extractApiCallOrder(s.tags);
-      if (!calls.includes(endpointName)) return [];
-      return s.tags.filter((t) => t.startsWith('@auth:'));
-    });
-    const uniqueAuth = [...new Set(authTags.map((t) => t.slice('@auth:'.length)))];
-    const authDatasource = [datasource, ...uniqueAuth].filter(Boolean).join('; ');
-
-    // Request shape: compose from body + params + encoding.
-    const bodyStr = entry.body
-      ? `body: ${typeof entry.body === 'string' ? entry.body : JSON.stringify(entry.body)}`
-      : '';
-    const paramsArr = Array.isArray(entry.params) ? entry.params as string[] : [];
-    const paramsStr = paramsArr.length > 0 ? `params: [${paramsArr.join(', ')}]` : '';
-    const requestShape = [bodyStr, paramsStr].filter(Boolean).join('; ') || '—';
-
-    // Expected-status matrix: aggregate @cases dataset labels + expected status
-    // from scenarios that call this endpoint. Fall back to catalog expect.status.
-    const statusEntries: string[] = [];
-    for (const sc of scenarios) {
-      const calls = extractApiCallOrder(sc.tags);
-      if (!calls.includes(endpointName)) continue;
-      const dataset = extractCasesDataset(sc.tags);
-      if (dataset) {
-        // @cases dataset name as label — actual per-row statuses live in test-data.yaml
-        statusEntries.push(`@cases:${dataset}`);
-      }
-    }
-    // Show the catalog baseline status plus a pointer to any @cases matrix dataset (the per-row
-    // statuses live in test-data; resolving them into this cell is a later enrichment).
-    const catalogStatus = entry.expect?.status != null ? String(entry.expect.status) : '';
-    const expectedStatusMatrix =
-      [catalogStatus, ...new Set(statusEntries)].filter(Boolean).join('; ') || '—';
-
-    // Flow steps: ordered @api names from flow-tagged scenarios referencing this endpoint.
-    const flowStepsSet = new Set<string>();
-    for (const sc of scenarios) {
-      const calls = extractApiCallOrder(sc.tags);
-      if (!calls.includes(endpointName)) continue;
-      // All scenarios show their call order; flow scenarios show multi-step chains.
-      if (calls.length > 1) {
-        flowStepsSet.add(calls.join(' → '));
-      }
-    }
-    const flowSteps = [...flowStepsSet].join('; ') || '—';
-
-    // Concurrency invariant: from @concurrent scenarios calling this endpoint.
-    const concurrencyParts: string[] = [];
-    for (const sc of scenarios) {
-      const calls = extractApiCallOrder(sc.tags);
-      if (!calls.includes(endpointName)) continue;
-      const inv = extractConcurrencyInvariant(sc.tags);
-      if (inv) concurrencyParts.push(inv);
-    }
-    const concurrencyInvariant = concurrencyParts.join('; ') || '—';
-
-    rows.push({
-      endpoint,
-      method,
-      authDatasource,
-      requestShape,
-      expectedStatusMatrix,
-      flowSteps,
-      concurrencyInvariant,
-    });
-  }
-
-  return rows;
-}
-
-/**
- * Append a second "API detail" worksheet to the workbook.
- * Called only for api-kind units; no effect on the Testcases sheet or other sheets.
- *
- * Columns: Endpoint · Method · Auth/Datasource · Request shape ·
- *          Expected-status matrix · Flow steps · Concurrency invariant
- */
-export function addApiDetailSheet(wb: ExcelJS.Workbook, detailRows: ApiDetailRow[]): void {
-  const ws = wb.addWorksheet('API detail');
-  const ARIAL_FONT = 'Arial';
-
-  ws.columns = [
-    { header: 'Endpoint',                width: 35 },
-    { header: 'Method',                  width: 10 },
-    { header: 'Auth / Datasource',       width: 22 },
-    { header: 'Request shape',           width: 40 },
-    { header: 'Expected-status matrix',  width: 30 },
-    { header: 'Flow steps',              width: 40 },
-    { header: 'Concurrency invariant',   width: 35 },
-  ];
-
-  // Style the auto-generated header row (row 1).
-  const headerRow = ws.getRow(1);
-  headerRow.height = 30;
-  headerRow.eachCell((cell) => {
-    cell.font = { bold: true, color: { argb: API_DETAIL_HEADER_FONT }, name: ARIAL_FONT };
-    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: API_DETAIL_HEADER_FILL } };
-    cell.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
-    applyBorder(cell);
+  return buildApiDetailRowsPure(catalog, scenarios, {
+    extractApiCallOrder,
+    extractCasesDataset,
+    extractConcurrencyInvariant,
   });
-
-  ws.views = [{ state: 'frozen', ySplit: 1 }];
-
-  for (const r of detailRows) {
-    const row = ws.addRow([
-      r.endpoint,
-      r.method,
-      r.authDatasource,
-      r.requestShape,
-      r.expectedStatusMatrix,
-      r.flowSteps,
-      r.concurrencyInvariant,
-    ]);
-    row.alignment = { vertical: 'top', wrapText: true };
-    row.eachCell({ includeEmpty: true }, (cell) => {
-      applyBorder(cell);
-      cell.font = { name: ARIAL_FONT };
-    });
-  }
-
-  ws.autoFilter = {
-    from: { row: 1, column: 1 },
-    to: { row: ws.rowCount, column: 7 },
-  };
 }
 
 /**
@@ -753,7 +131,8 @@ export async function writeXlsx(
 /**
  * Post-process the workbook buffer: extend `<a:picLocks>` on every drawing
  * with `noMove`, `noResize`, `noSelect`. Combined with the sheet protection
- * above, the embedded logo can't be dragged, resized, or selected via the UI.
+ * set by the builder, the embedded logo can't be dragged, resized, or
+ * selected via the UI.
  */
 export async function lockEmbeddedImages(buffer: Buffer): Promise<Buffer> {
   const zip = await JSZip.loadAsync(buffer);
@@ -779,6 +158,3 @@ export async function lockEmbeddedImages(buffer: Buffer): Promise<Buffer> {
   }
   return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
 }
-
-void applyBorder;
-void ({} as AnyRow);