@sun-asterisk/sungen 3.2.6 → 3.2.7

package/dist/exporters/xlsx-report-builder.js

@@ -0,0 +1,653 @@
+"use strict";
+/**
+ * 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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_DETAIL_HEADER_FONT = exports.API_DETAIL_HEADER_FILL = exports.OVERVIEW_HEADERS = exports.allBordersBlack = exports.LAVENDER = exports.WHITE = exports.BLACK = exports.ARIAL_FONT = exports.TIMES = exports.BORDER_COLOR = exports.CATEGORY_FILL = exports.META_FILL = exports.HEADER_FONT = exports.HEADER_FILL = exports.COL_COUNT = void 0;
+exports.applyBorder = applyBorder;
+exports.renderReportHeaderBand = renderReportHeaderBand;
+exports.addOverviewSheet = addOverviewSheet;
+exports.addTestcaseSheet = addTestcaseSheet;
+exports.buildApiDetailRows = buildApiDetailRows;
+exports.addApiDetailSheet = addApiDetailSheet;
+exports.buildSingleTestcaseWorkbook = buildSingleTestcaseWorkbook;
+exports.buildTestcaseWorkbook = buildTestcaseWorkbook;
+const exceljs_1 = __importDefault(require("exceljs"));
+const sun_logo_1 = require("./sun-logo");
+exports.COL_COUNT = 16;
+exports.HEADER_FILL = 'FFD9D2E9'; // lavender — matches the summary-header band on row 6
+exports.HEADER_FONT = 'FF000000'; // black text reads better on the light lavender
+exports.META_FILL = 'FFDCE6F1'; // soft blue for meta rows
+exports.CATEGORY_FILL = 'FFD9D2E9'; // same lavender for group dividers (Accessing / GUI / Function)
+exports.BORDER_COLOR = 'FFBFBFBF';
+// Shared masthead + table styling (BM-2-901-13 header band, summary band, Overview table).
+exports.TIMES = 'Times New Roman';
+exports.ARIAL_FONT = 'Arial';
+exports.BLACK = { argb: 'FF000000' };
+exports.WHITE = { argb: 'FFFFFFFF' };
+exports.LAVENDER = { argb: 'FFD9D2E9' };
+const thinBlack = { style: 'thin', color: exports.BLACK };
+exports.allBordersBlack = { top: thinBlack, left: thinBlack, bottom: thinBlack, right: thinBlack };
+function applyBorder(cell) {
+    cell.border = {
+        top: { style: 'thin', color: { argb: exports.BORDER_COLOR } },
+        left: { style: 'thin', color: { argb: exports.BORDER_COLOR } },
+        bottom: { style: 'thin', color: { argb: exports.BORDER_COLOR } },
+        right: { style: 'thin', color: { argb: exports.BORDER_COLOR } },
+    };
+}
+/**
+ * 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, ws, titleLabel, sungenVersion) {
+    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 = exports.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_1.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 },
+            ext: { width: 90, height: 51 },
+            editAs: 'oneCell',
+        });
+    }
+    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: exports.TIMES };
+    d1.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
+    d1.border = exports.allBordersBlack;
+    // G1 — No: BM-2-901-13
+    const g1 = ws.getCell('G1');
+    g1.value = 'No: BM-2-901-13';
+    g1.font = { size: 12, name: exports.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: exports.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: exports.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: exports.TIMES };
+    a4.alignment = { vertical: 'middle' };
+    a4.border = exports.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: exports.TIMES };
+    g4.alignment = { horizontal: 'right', vertical: 'middle', wrapText: true };
+    g4.border = exports.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). */
+exports.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, sheets, sungenVersion) {
+    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;
+    exports.OVERVIEW_HEADERS.forEach((label, i) => {
+        const c = headerRow.getCell(FIRST_COL + i);
+        c.value = label;
+        c.font = { bold: true, size: 10, color: exports.BLACK, name: exports.ARIAL_FONT };
+        c.fill = { type: 'pattern', pattern: 'solid', fgColor: exports.LAVENDER };
+        c.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
+        c.border = exports.allBordersBlack;
+    });
+    const totals = { passed: 0, failed: 0, pending: 0, na: 0, remain: 0, total: 0 };
+    const writeDataRow = (rowIdx, values, isTotal) => {
+        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: exports.BLACK, name: exports.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 = exports.allBordersBlack;
+            if (isTotal)
+                c.fill = { type: 'pattern', pattern: 'solid', fgColor: exports.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) => name.replace(/'/g, "''"); // Excel escapes ' by doubling
+    const ref = (name, cell, result) => ({ 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, result) => ({ 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, sheetName, summary, rows, specLink, sungenVersion) {
+    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 = {
+        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: exports.BLACK, name: exports.ARIAL_FONT };
+        c.fill = { type: 'pattern', pattern: 'solid', fgColor: exports.LAVENDER };
+        c.alignment = { horizontal: 'center', vertical: 'top' };
+        c.border = exports.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 = {
+        C: { formula: `COUNTA(A${COUNT_RANGE_START}:A${COUNT_RANGE_END})`, result: summary.total },
+        D: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Passed")`, result: summary.passed },
+        E: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Failed")`, result: summary.failed },
+        F: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"Pending")`, result: summary.pending },
+        G: { formula: `COUNTIF(L${COUNT_RANGE_START}:L${COUNT_RANGE_END},"N/A")`, result: summary.na },
+        H: { formula: 'C7-D7-G7', result: summary.failed + summary.pending },
+    };
+    for (const [col, val] of Object.entries(r7Values)) {
+        const c = ws.getCell(`${col}7`);
+        c.value = val;
+        c.font = { size: 10, color: exports.BLACK, name: exports.ARIAL_FONT };
+        c.fill = { type: 'pattern', pattern: 'solid', fgColor: exports.WHITE };
+        c.alignment = { horizontal: 'center', vertical: 'top' };
+        c.border = exports.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: exports.BLACK, name: exports.ARIAL_FONT };
+    c8.fill = { type: 'pattern', pattern: 'solid', fgColor: exports.WHITE };
+    c8.alignment = { horizontal: 'center', vertical: 'top' };
+    c8.border = exports.allBordersBlack;
+    // -- Row 8: Percentages (cols D..H), formula = count / (Total − N/A) --
+    const r8Values = {
+        D: { formula: 'IFERROR(D7/(C7-G7),0)', result: summary.passed / Math.max(1, summary.total - summary.na) },
+        E: { formula: 'IFERROR(E7/(C7-G7),0)', result: summary.failed / Math.max(1, summary.total - summary.na) },
+        F: { formula: 'IFERROR(F7/(C7-G7),0)', result: summary.pending / Math.max(1, summary.total - summary.na) },
+        G: { formula: 'IFERROR(G7/(C7-G7),0)', result: summary.na / Math.max(1, summary.total - summary.na) },
+        H: { formula: 'IFERROR(H7/(C7-G7),0)', result: (summary.failed + summary.pending) / Math.max(1, summary.total - summary.na) },
+    };
+    for (const [col, val] of Object.entries(r8Values)) {
+        const c = ws.getCell(`${col}8`);
+        c.value = val;
+        c.font = { size: 10, color: exports.BLACK, name: exports.ARIAL_FONT };
+        c.fill = { type: 'pattern', pattern: 'solid', fgColor: exports.WHITE };
+        c.alignment = { horizontal: 'center', vertical: 'top' };
+        c.border = exports.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: exports.HEADER_FONT } };
+        cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: exports.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();
+    for (const r of rows) {
+        const g = grouped.get(r.category2) || [];
+        g.push(r);
+        grouped.set(r.category2, g);
+    }
+    const emittedGroups = new Set();
+    function emitGroup(groupName, groupRows) {
+        // 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: exports.CATEGORY_FILL } };
+        });
+        // Fill the full width so the band spans the whole table
+        for (let i = 1; i <= exports.COL_COUNT; i++) {
+            const c = divider.getCell(i);
+            c.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: exports.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: exports.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.sheetProtection = {
+        sheet: true,
+        objects: false,
+        scenarios: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// API detail sheet (api-kind units only)
+// Second worksheet appended after Testcases — never alters the Testcases sheet.
+// ---------------------------------------------------------------------------
+exports.API_DETAIL_HEADER_FILL = 'FF2E5984'; // dark blue header for differentiation
+exports.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)
+ */
+function buildApiDetailRows(catalog, scenarios, extractors) {
+    const { extractApiCallOrder, extractCasesDataset, extractConcurrencyInvariant } = extractors;
+    const rows = [];
+    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 : [];
+        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 = [];
+        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();
+        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 = [];
+        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
+ */
+function addApiDetailSheet(wb, detailRows) {
+    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: exports.API_DETAIL_HEADER_FONT }, name: ARIAL_FONT };
+        cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: exports.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.
+ */
+function buildSingleTestcaseWorkbook(sheet, apiDetail, opts) {
+    const wb = new exceljs_1.default.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`.
+ */
+function buildTestcaseWorkbook(sheets, opts) {
+    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_1.default.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;
+}
+//# sourceMappingURL=xlsx-report-builder.js.map