@sun-asterisk/sungen 3.2.6 → 3.2.8

package/src/exporters/xlsx-report-builder.ts

@@ -0,0 +1,806 @@
+/**
+ * Pure XLSX workbook builder — the single source of truth for the BM-2-901-13
+ * delivery report rendering, shared by the CLI exporter
+ * (`xlsx-exporter.ts`, Node) and the dashboard's in-browser exporter
+ * (`dashboard/src/lib/export.ts`, bundled via vite alias).
+ *
+ * BROWSER-SAFE: this module may import ONLY `exceljs` and `./sun-logo`.
+ * No `fs`, no `path`, no `./package-info` (version lookup is fs-based) and no
+ * `./feature-parser` (it transitively pulls the fs-reading gherkin parser).
+ * Anything environment-specific is injected by the caller:
+ *   - the sungen version string → `opts.sungenVersion` / `sungenVersion` param
+ *   - the tag-extractor helpers used by `buildApiDetailRows` → `TagExtractors`
+ *
+ * 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
+ *   - sensible column widths
+ *   - category-separator rows rendered as a filled bar spanning the table
+ */
+
+import ExcelJS from 'exceljs';
+import { SUN_LOGO_PNG_BASE64 } from './sun-logo';
+
+export const COL_COUNT = 16;
+export const HEADER_FILL = 'FFD9D2E9'; // lavender — matches the summary-header band on row 6
+export const HEADER_FONT = 'FF000000'; // black text reads better on the light lavender
+export const META_FILL = 'FFDCE6F1'; // soft blue for meta rows
+export const CATEGORY_FILL = 'FFD9D2E9'; // same lavender for group dividers (Accessing / GUI / Function)
+export const BORDER_COLOR = 'FFBFBFBF';
+
+// Shared masthead + table styling (BM-2-901-13 header band, summary band, Overview table).
+export const TIMES = 'Times New Roman';
+export const ARIAL_FONT = 'Arial';
+export const BLACK = { argb: 'FF000000' };
+export const WHITE = { argb: 'FFFFFFFF' };
+export const LAVENDER = { argb: 'FFD9D2E9' };
+const thinBlack = { style: 'thin' as const, color: BLACK };
+export const allBordersBlack = { top: thinBlack, left: thinBlack, bottom: thinBlack, right: thinBlack };
+
+type AnyCell = ExcelJS.Cell;
+
+export 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 } },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Builder input shapes — neutral, builder-local. Both the CLI's domain types
+// (ScreenSummary / TestCaseRow / LocaleSheet / ApiDetailRow / ApiCatalogEntry)
+// and the dashboard's snapshot types map structurally onto these; the adapters
+// on each side are pure field mappings, so no app domain type leaks in here.
+// ---------------------------------------------------------------------------
+
+/** Summary stats rendered into the sheet's summary band (rows 6-8). */
+export interface BuilderSummary {
+  screen: string;
+  total: number;
+  passed: number;
+  failed: number;
+  pending: number;
+  na: number;
+}
+
+/** One testcase data row (BM-2-901-13 columns A..P). All fields are strings. */
+export interface BuilderRow {
+  tcId: string;
+  category1: string;
+  category2: string;
+  precondition: string;
+  testData: string;
+  steps: string;
+  expectedResults: string;
+  priority: string;
+  testcaseType: string;
+  testResult: string;
+  executedDate: string;
+  testExecutor: string;
+  testEnvironment: string;
+  note: string;
+}
+
+/** One testcase worksheet: name + summary + data rows + spec link. */
+export interface BuilderSheet {
+  sheetName: string;            // e.g. "home-VI" or "home-EN" (or "Testcases")
+  summary: BuilderSummary;
+  rows: BuilderRow[];
+  specLink: string;
+}
+
+/** One row in the supplementary "API detail" worksheet. */
+export interface BuilderApiDetailRow {
+  endpoint: string;
+  method: string;
+  authDatasource: string;
+  requestShape: string;
+  expectedStatusMatrix: string;
+  flowSteps: string;
+  concurrencyInvariant: string;
+}
+
+/** The apis.yaml catalog fields `buildApiDetailRows` consumes. */
+export interface BuilderApiCatalogEntry {
+  method?: string;
+  path?: string;
+  datasource?: string;
+  body?: unknown;
+  params?: unknown;
+  expect?: { status?: number | string };
+}
+
+/**
+ * Tag-extractor helpers injected into `buildApiDetailRows`. Implemented by
+ * `feature-parser.ts` on the CLI side — injected (not imported) because that
+ * module transitively requires the fs-reading gherkin parser, which would
+ * break this module's browser-safety.
+ */
+export interface TagExtractors {
+  extractApiCallOrder(tags: string[]): string[];
+  extractCasesDataset(tags: string[]): string | null;
+  extractConcurrencyInvariant(tags: string[]): string;
+}
+
+/** Environment-specific options injected by the caller. */
+export interface WorkbookBuildOptions {
+  /** CLI/package version rendered into the masthead ("Version: x.y.z"). */
+  sungenVersion?: string;
+}
+
+/**
+ * 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.
+ */
+export function renderReportHeaderBand(
+  wb: ExcelJS.Workbook,
+  ws: ExcelJS.Worksheet,
+  titleLabel: string,
+  sungenVersion?: 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 {
+    // base64 form (not Buffer.from) keeps this module Buffer-free / browser-safe;
+    // ExcelJS decodes it to the identical PNG media bytes either way.
+    const imageId = wb.addImage({
+      base64: SUN_LOGO_PNG_BASE64,
+      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: ${sungenVersion ?? 'unknown'}`;
+  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). */
+export 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.
+ */
+export function addOverviewSheet(
+  wb: ExcelJS.Workbook,
+  sheets: BuilderSheet[],
+  sungenVersion?: string,
+): 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`, sungenVersion);
+
+  // 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.
+ */
+export function addTestcaseSheet(
+  wb: ExcelJS.Workbook,
+  sheetName: string,
+  summary: BuilderSummary,
+  rows: BuilderRow[],
+  specLink: string,
+  sungenVersion?: 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`, sungenVersion);
+  // 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, BuilderRow[]>();
+  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: BuilderRow[]): 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,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// API detail sheet (api-kind units only)
+// Second worksheet appended after Testcases — never alters the Testcases sheet.
+// ---------------------------------------------------------------------------
+
+export const API_DETAIL_HEADER_FILL = 'FF2E5984'; // dark blue header for differentiation
+export const API_DETAIL_HEADER_FONT = 'FFFFFFFF'; // white text on dark header
+
+/**
+ * Build BuilderApiDetailRow[] from the apis.yaml catalog + feature-level
+ * annotations. Called once per feature file for api-kind units in the delivery
+ * pipeline. The tag extractors are injected (see `TagExtractors`).
+ *
+ * @param catalog    Parsed apis.yaml keyed by endpoint name
+ * @param scenarios  Scenario-level tag arrays from parseFeatureMetadata().scenarios
+ * @param extractors Tag-parsing helpers (feature-parser on the CLI side)
+ */
+export function buildApiDetailRows(
+  catalog: Record<string, BuilderApiCatalogEntry>,
+  scenarios: Array<{ tags: string[] }>,
+  extractors: TagExtractors,
+): BuilderApiDetailRow[] {
+  const { extractApiCallOrder, extractCasesDataset, extractConcurrencyInvariant } = extractors;
+  const rows: BuilderApiDetailRow[] = [];
+
+  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: BuilderApiDetailRow[]): 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);
+  });
+
+  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 },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// High-level entry points — one call builds a whole workbook. These carry the
+// exact behavior of the CLI's `renderXlsx` / `renderXlsxMultiSheet`; the CLI
+// and dashboard wrappers only adapt their domain types and inject opts.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a single-sheet testcase workbook (plus an optional trailing
+ * "API detail" sheet). Mirrors the CLI's `renderXlsx` — the caller passes
+ * `sheetName: 'Testcases'` for the canonical single-sheet delivery.
+ */
+export function buildSingleTestcaseWorkbook(
+  sheet: BuilderSheet,
+  apiDetail?: { rows: BuilderApiDetailRow[] },
+  opts?: WorkbookBuildOptions,
+): ExcelJS.Workbook {
+  const wb = new ExcelJS.Workbook();
+  wb.creator = 'sungen delivery';
+  wb.created = new Date();
+  addTestcaseSheet(wb, sheet.sheetName, sheet.summary, sheet.rows, sheet.specLink, opts?.sungenVersion);
+  if (apiDetail) {
+    addApiDetailSheet(wb, apiDetail.rows);
+  }
+  return wb;
+}
+
+/**
+ * Build a multi-sheet testcase workbook: an Overview roll-up first, then one
+ * BM-2-901-13 sheet per entry. Mirrors the CLI's `renderXlsxMultiSheet`.
+ */
+export function buildTestcaseWorkbook(
+  sheets: BuilderSheet[],
+  opts?: WorkbookBuildOptions,
+): ExcelJS.Workbook {
+  if (sheets.length === 0) {
+    // Message kept verbatim from the original wrapper for behavior stability.
+    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, opts?.sungenVersion);
+  for (const s of sheets) {
+    addTestcaseSheet(wb, s.sheetName, s.summary, s.rows, s.specLink, opts?.sungenVersion);
+  }
+  return wb;
+}