@bilig/xlsx 0.164.0

package/dist/workbook-compatibility-report.js

@@ -0,0 +1,654 @@
+import { statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { readXlsxFormulaCacheCellsFromWorkbookCore } from './formula-cache-reader.js';
+import { writeSimpleXlsxWorkbook } from './simple-workbook-writer.js';
+import { readXlsxWorkbookCells } from './workbook-cell-reader.js';
+import { closeStreamingNativeWorkbookCore, openStreamingNativeWorkbookCore, scanStreamingNativeWorkbookCellStats, scanStreamingNativeWorkbookPackageParts, } from './streaming-native-workbook-core.js';
+import { readXlsxZipEntriesLazy } from './zip-reader.js';
+export const workbookCompatibilityReportSchemaVersion = 'bilig-workbook-compatibility-report.v1';
+const defaultInspectLimit = 'all';
+const defaultFileInspectLimit = 2000;
+const workbookCompatibilityReportBytesApiLimit = 1_000_000;
+const docsUrl = 'https://proompteng.github.io/bilig/workbook-compatibility-report.html';
+const volatileFunctionNames = ['TODAY', 'NOW', 'RAND', 'RANDBETWEEN', 'RANDARRAY', 'OFFSET', 'INDIRECT', 'SUBTOTAL', 'AGGREGATE'];
+const knownUnsupportedRiskFunctions = new Set([
+    'CALL',
+    'COPILOT',
+    'CUBEKPIMEMBER',
+    'CUBEMEMBER',
+    'CUBEMEMBERPROPERTY',
+    'CUBERANKEDMEMBER',
+    'CUBESET',
+    'CUBESETCOUNT',
+    'CUBEVALUE',
+    'DDE',
+    'DETECTLANGUAGE',
+    'FILTERXML',
+    'GOOGLEFINANCE',
+    'IMAGE',
+    'IMPORTDATA',
+    'IMPORTFEED',
+    'IMPORTHTML',
+    'IMPORTRANGE',
+    'IMPORTXML',
+    'INFO',
+    'PY',
+    'REGISTER.ID',
+    'RTD',
+    'SQL.REQUEST',
+    'STOCKHISTORY',
+    'TRANSLATE',
+    'WEBSERVICE',
+]);
+export function buildWorkbookCompatibilityReport(input, options = {}) {
+    const bytes = toUint8Array(input);
+    assertWorkbookCompatibilityReportBytesApiWithinLimit(bytes, 'buildWorkbookCompatibilityReport');
+    const rss = createWorkbookCompatibilityRssRecorder(options.maxRssBytes);
+    rss.recordPhase('bytes-api:start');
+    const fileName = options.fileName ?? 'workbook.xlsx';
+    const externalWorkbooks = options.externalWorkbooks ?? [];
+    const zip = readXlsxZipEntriesLazy(bytes);
+    rss.recordPhase('bytes-api:zip');
+    const workbook = readXlsxWorkbookCells(zip);
+    rss.recordPhase('bytes-api:cells');
+    const workbookParts = scanStreamingNativeWorkbookPackageParts({ zip });
+    rss.recordPhase('bytes-api:package-parts');
+    const cacheInspection = inspectWorkbookFormulaCaches(workbook, options.inspectLimit ?? defaultInspectLimit);
+    rss.recordPhase('bytes-api:formula-cache');
+    return buildWorkbookCompatibilityReportFromScans({
+        fileName,
+        externalWorkbookCount: externalWorkbooks.length,
+        workbook: {
+            sheetNames: workbook.sheets.map((sheet) => sheet.name),
+            nonEmptyCellCount: workbook.sheets.reduce((sum, sheet) => sum + sheet.cells.length, 0),
+        },
+        workbookParts,
+        cacheInspection,
+        diagnostics: {
+            inputBytes: bytes.byteLength,
+            maxObservedRssBytes: rss.maxObservedRssBytes,
+            ...(options.maxRssBytes === undefined ? {} : { maxRssBytes: options.maxRssBytes }),
+            phaseRssPeaks: rss.phaseRssPeaks,
+        },
+    });
+}
+export function buildWorkbookCompatibilityReportFromFile(inputPath, options = {}) {
+    const fileName = options.fileName ?? basename(inputPath);
+    const externalWorkbooks = options.externalWorkbooks ?? [];
+    const inspectLimit = options.inspectLimit ?? defaultFileInspectLimit;
+    const rss = createWorkbookCompatibilityRssRecorder(options.maxRssBytes);
+    const inputBytes = statSync(inputPath).size;
+    rss.recordPhase('file-api:start');
+    const core = openStreamingNativeWorkbookCore(inputPath);
+    try {
+        rss.recordPhase('file-api:open-core');
+        const workbook = scanStreamingNativeWorkbookCellStats(core);
+        rss.recordPhase('file-api:cell-stats');
+        const workbookParts = scanStreamingNativeWorkbookPackageParts(core);
+        rss.recordPhase('file-api:package-parts');
+        const cacheInspection = inspectWorkbookFormulaCacheScan(readXlsxFormulaCacheCellsFromWorkbookCore(core, {
+            inspectLimit,
+        }), inspectLimit);
+        rss.recordPhase('file-api:formula-cache');
+        return buildWorkbookCompatibilityReportFromScans({
+            fileName,
+            externalWorkbookCount: externalWorkbooks.length,
+            workbook,
+            workbookParts,
+            cacheInspection,
+            diagnostics: {
+                inputBytes,
+                maxObservedRssBytes: rss.maxObservedRssBytes,
+                ...(options.maxRssBytes === undefined ? {} : { maxRssBytes: options.maxRssBytes }),
+                phaseRssPeaks: rss.phaseRssPeaks,
+            },
+        });
+    }
+    finally {
+        closeStreamingNativeWorkbookCore(core);
+    }
+}
+function buildWorkbookCompatibilityReportFromScans(input) {
+    const { fileName, externalWorkbookCount, workbook, workbookParts, cacheInspection } = input;
+    const unsupportedFunctions = countNamedValues(cacheInspection.formulas.flatMap((entry) => knownUnsupportedFunctionNamesFromFormula(entry.formula)));
+    const volatileFunctions = countNamedValues(cacheInspection.formulas.flatMap((entry) => volatileFunctionNamesFromFormula(entry.formula)));
+    const diagnostics = buildWorkbookCompatibilityNativeDiagnostics({
+        ...input.diagnostics,
+        sheetCount: workbook.sheetNames.length,
+        inspectedFormulaCellCount: cacheInspection.inspectedFormulaCellCount,
+        formulaCellCount: cacheInspection.formulaCellCount,
+        unsupportedFormulaCellCount: cacheInspection.cacheStatusSummary.unsupportedRecalculation,
+        unsupportedFunctions,
+        workbookParts,
+    });
+    const report = {
+        schemaVersion: workbookCompatibilityReportSchemaVersion,
+        verified: true,
+        input: {
+            fileName,
+            externalWorkbookCount,
+            inspectLimit: cacheInspection.inspectionLimit,
+        },
+        workbook: {
+            sheetCount: workbook.sheetNames.length,
+            sheetNames: workbook.sheetNames,
+            nonEmptyCellCount: workbook.nonEmptyCellCount,
+            formulaCellCount: cacheInspection.formulaCellCount,
+            definedNameCount: workbookParts.definedNameCount,
+            tableCount: workbookParts.tableCount,
+            pivotTableCount: workbookParts.pivotTableCount,
+            chartCount: workbookParts.chartCount,
+            macroModuleCount: workbookParts.macroModuleCount,
+        },
+        findings: {
+            unsupportedFunctions,
+            externalLinks: {
+                count: workbookParts.externalLinkCount,
+                unresolvedCount: 0,
+                refreshedCount: 0,
+            },
+            macroModules: {
+                count: workbookParts.macroModuleCount,
+                byteLength: workbookParts.macroByteLength,
+            },
+            volatileFunctions,
+            pivotTables: {
+                count: workbookParts.pivotTableCount,
+                unsupportedCount: 0,
+                cacheOnlyCount: 0,
+            },
+            staleCachedFormulas: {
+                count: cacheInspection.staleCachedFormulaCount,
+            },
+            missingCachedFormulaValues: {
+                count: cacheInspection.cacheStatusSummary.missingCache,
+            },
+            unsupportedRecalculations: {
+                count: cacheInspection.cacheStatusSummary.unsupportedRecalculation,
+            },
+            warnings: cacheInspection.warnings,
+        },
+        cacheInspection: {
+            inspectedFormulaCellCount: cacheInspection.inspectedFormulaCellCount,
+            uninspectedFormulaCellCount: cacheInspection.uninspectedFormulaCellCount,
+            inspectionLimit: cacheInspection.inspectionLimit,
+            suggestedReads: cacheInspection.suggestedReads,
+        },
+        diagnostics,
+        commandSucceeded: true,
+        inspectionCompleted: true,
+        recalculationCompleted: false,
+        excelParity: 'not_proven',
+        limitations: [
+            'This report identifies workbook features that may require investigation before using Bilig in a service or agent workflow.',
+            'It is not an Excel compatibility certification.',
+            'It scans workbook package metadata and formula caches; use xlsx-cache-doctor for native recalculation proof.',
+            'It does not execute VBA, refresh pivots, refresh external data sources, or prove desktop Excel UI behavior.',
+        ],
+        next: {
+            docs: docsUrl,
+            command: `workbook-compatibility-report ${shellQuote(fileName)} --json`,
+        },
+    };
+    return {
+        ...report,
+        risk: buildRisk(report),
+    };
+}
+export function runWorkbookCompatibilityReportCli(args, context = {}) {
+    const commandName = context.commandName ?? 'workbook-compatibility-report';
+    const writeStdout = context.stdout ?? ((text) => process.stdout.write(text));
+    const writeStderr = context.stderr ?? ((text) => process.stderr.write(text));
+    try {
+        if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+            writeStdout(renderHelp(commandName));
+            return 0;
+        }
+        const options = parseCliArgs(args, commandName);
+        const fileName = options.mode === 'demo' ? 'bilig-workbook-compatibility-demo.xlsx' : basename(requireInputPath(options));
+        const externalWorkbooks = readExternalWorkbookReferenceInputs(options.externalWorkbooks);
+        const report = options.mode === 'demo'
+            ? buildWorkbookCompatibilityReport(buildWorkbookCompatibilityDemoBytes(), {
+                fileName,
+                ...(externalWorkbooks.length > 0 ? { externalWorkbooks } : {}),
+                ...(options.inspectLimit === undefined ? {} : { inspectLimit: options.inspectLimit }),
+            })
+            : buildWorkbookCompatibilityReportFromFile(requireInputPath(options), {
+                fileName,
+                ...(externalWorkbooks.length > 0 ? { externalWorkbooks } : {}),
+                ...(options.inspectLimit === undefined ? {} : { inspectLimit: options.inspectLimit }),
+            });
+        if (options.json) {
+            writeStdout(`${JSON.stringify(report, null, 2)}\n`);
+            return report.verified ? 0 : 1;
+        }
+        writeStdout(renderHumanReport(report));
+        return report.verified ? 0 : 1;
+    }
+    catch (error) {
+        writeStderr(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+export function buildWorkbookCompatibilityDemoBytes() {
+    return writeSimpleXlsxWorkbook({
+        sheets: [
+            {
+                name: 'Inputs',
+                cells: [
+                    { address: 'A1', row: 0, col: 0, value: 'Metric' },
+                    { address: 'B1', row: 0, col: 1, value: 'Value' },
+                    { address: 'A2', row: 1, col: 0, value: 'Units' },
+                    { address: 'B2', row: 1, col: 1, value: 40 },
+                    { address: 'A3', row: 2, col: 0, value: 'Price' },
+                    { address: 'B3', row: 2, col: 1, value: 1200 },
+                ],
+            },
+            {
+                name: 'Summary',
+                cells: [
+                    { address: 'A1', row: 0, col: 0, value: 'Metric' },
+                    { address: 'B1', row: 0, col: 1, value: 'Value' },
+                    { address: 'A2', row: 1, col: 0, value: 'Revenue' },
+                    { address: 'B2', row: 1, col: 1, formula: 'Inputs!B2*Inputs!B3', value: 60_000 },
+                    { address: 'A3', row: 2, col: 0, value: 'GeneratedAt' },
+                    { address: 'B3', row: 2, col: 1, formula: 'NOW()', value: 45_123 },
+                    { address: 'A4', row: 3, col: 0, value: 'CubeSales' },
+                    { address: 'B4', row: 3, col: 1, formula: 'CUBEVALUE("ThisWorkbookDataModel","[Measures].[Sales]")' },
+                ],
+            },
+        ],
+    });
+}
+function createWorkbookCompatibilityRssRecorder(maxRssBytes) {
+    const recorder = {
+        phaseRssPeaks: [],
+        maxObservedRssBytes: 0,
+        recordPhase(phase) {
+            const rssBytes = process.memoryUsage().rss;
+            recorder.maxObservedRssBytes = Math.max(recorder.maxObservedRssBytes, rssBytes);
+            recorder.phaseRssPeaks.push({ phase, rssBytes });
+            if (maxRssBytes !== undefined && rssBytes > maxRssBytes) {
+                throw new Error(`workbook compatibility report exceeded maxRssBytes during ${phase}: ${rssBytes} > ${maxRssBytes}`);
+            }
+        },
+    };
+    return recorder;
+}
+function buildWorkbookCompatibilityNativeDiagnostics(args) {
+    const unsupportedReason = workbookCompatibilityUnsupportedReason(args);
+    return {
+        engineMode: 'streaming-native',
+        fallbackUsed: false,
+        inputBytes: args.inputBytes,
+        phaseRssPeaks: args.phaseRssPeaks,
+        maxObservedRssBytes: args.maxObservedRssBytes,
+        ...(args.maxRssBytes === undefined ? {} : { maxRssBytes: args.maxRssBytes }),
+        sheetCount: args.sheetCount,
+        targetRowCount: args.inspectedFormulaCellCount,
+        editCount: 0,
+        readCount: args.inspectedFormulaCellCount,
+        formulaCounts: {
+            scannedFormulaCellCount: args.formulaCellCount,
+            targetedFormulaCellCount: args.inspectedFormulaCellCount,
+            evaluatedFormulaCellCount: 0,
+            patchedFormulaCacheCount: 0,
+            unsupportedFormulaCellCount: args.unsupportedFormulaCellCount,
+            nativeKernelFormulaCellCount: 0,
+            nativeKernelBatchCount: 0,
+        },
+        patchedCacheCount: 0,
+        ...(unsupportedReason === undefined ? {} : { unsupportedReason }),
+    };
+}
+function workbookCompatibilityUnsupportedReason(args) {
+    if (args.unsupportedFunctions.length > 0) {
+        return `unsupported functions: ${formatNamedCounts(args.unsupportedFunctions)}`;
+    }
+    if (args.unsupportedFormulaCellCount > 0) {
+        return `unsupported formula cache inspections: ${args.unsupportedFormulaCellCount.toString()}`;
+    }
+    if (args.workbookParts.externalLinkCount > 0) {
+        return `external workbook links: ${args.workbookParts.externalLinkCount.toString()}`;
+    }
+    if (args.workbookParts.macroModuleCount > 0) {
+        return `macro modules: ${args.workbookParts.macroModuleCount.toString()}`;
+    }
+    if (args.workbookParts.pivotTableCount > 0) {
+        return `pivot tables: ${args.workbookParts.pivotTableCount.toString()}`;
+    }
+    return undefined;
+}
+function inspectWorkbookFormulaCaches(workbook, inspectLimit) {
+    const formulas = workbook.sheets.flatMap((sheet) => sheet.cells.flatMap((cell) => cell.formula && cell.formula.trim().length > 0
+        ? [
+            {
+                target: `${sheet.name}!${cell.address}`,
+                formula: cell.formula.startsWith('=') ? cell.formula : `=${cell.formula}`,
+                hasCachedValue: cell.hasValue,
+            },
+        ]
+        : []));
+    const normalizedLimit = normalizeInspectLimit(inspectLimit);
+    const inspected = normalizedLimit === 'all' ? formulas : formulas.slice(0, normalizedLimit);
+    const missingCache = inspected.filter((entry) => !entry.hasCachedValue).length;
+    const unsupportedRecalculation = inspected.filter((entry) => knownUnsupportedFunctionNamesFromFormula(entry.formula).length > 0).length;
+    const staleCachedFormulaCount = inspected.filter((entry) => entry.hasCachedValue && volatileFunctionNamesFromFormula(entry.formula).length > 0).length;
+    const volatileFormulaCount = inspected.filter((entry) => volatileFunctionNamesFromFormula(entry.formula).length > 0).length;
+    const warnings = [
+        ...(volatileFormulaCount > 0
+            ? ['Volatile formulas were detected; cached formula values may depend on workbook calculation time.']
+            : []),
+        ...(unsupportedRecalculation > 0
+            ? ['Unsupported formula families were detected; use xlsx-cache-doctor or an oracle harness before trusting cached values.']
+            : []),
+    ].toSorted();
+    return {
+        formulaCellCount: formulas.length,
+        inspectedFormulaCellCount: inspected.length,
+        uninspectedFormulaCellCount: formulas.length - inspected.length,
+        inspectionLimit: normalizedLimit,
+        suggestedReads: inspected.map((entry) => entry.target),
+        staleCachedFormulaCount,
+        cacheStatusSummary: {
+            missingCache,
+            unsupportedRecalculation,
+        },
+        warnings,
+        formulas: inspected,
+    };
+}
+function inspectWorkbookFormulaCacheScan(scan, inspectLimit) {
+    const normalizedLimit = normalizeInspectLimit(inspectLimit);
+    const inspected = scan.cells.map((cell) => ({
+        target: cell.target,
+        formula: cell.formula,
+        hasCachedValue: cell.cachedValue !== undefined,
+    }));
+    const missingCache = inspected.filter((entry) => !entry.hasCachedValue).length;
+    const unsupportedRecalculation = inspected.filter((entry) => knownUnsupportedFunctionNamesFromFormula(entry.formula).length > 0).length;
+    const staleCachedFormulaCount = inspected.filter((entry) => entry.hasCachedValue && volatileFunctionNamesFromFormula(entry.formula).length > 0).length;
+    const volatileFormulaCount = inspected.filter((entry) => volatileFunctionNamesFromFormula(entry.formula).length > 0).length;
+    const warnings = [
+        ...(volatileFormulaCount > 0
+            ? ['Volatile formulas were detected; cached formula values may depend on workbook calculation time.']
+            : []),
+        ...(unsupportedRecalculation > 0
+            ? ['Unsupported formula families were detected; use xlsx-cache-doctor or an oracle harness before trusting cached values.']
+            : []),
+    ].toSorted();
+    return {
+        formulaCellCount: scan.formulaCellCount,
+        inspectedFormulaCellCount: inspected.length,
+        uninspectedFormulaCellCount: scan.formulaCellCount - inspected.length,
+        inspectionLimit: normalizedLimit,
+        suggestedReads: inspected.map((entry) => entry.target),
+        staleCachedFormulaCount,
+        cacheStatusSummary: {
+            missingCache,
+            unsupportedRecalculation,
+        },
+        warnings,
+        formulas: inspected,
+    };
+}
+function normalizeInspectLimit(limit) {
+    if (limit === 'all') {
+        return limit;
+    }
+    if (!Number.isInteger(limit) || limit < 1) {
+        return defaultInspectLimit;
+    }
+    return limit;
+}
+function buildRisk(report) {
+    const highReasons = [];
+    const mediumReasons = [];
+    if (report.findings.unsupportedFunctions.length > 0) {
+        highReasons.push(`unsupported functions: ${formatNamedCounts(report.findings.unsupportedFunctions)}`);
+    }
+    if (report.findings.externalLinks.count > 0) {
+        highReasons.push(`external workbook links: ${report.findings.externalLinks.count.toString()}`);
+    }
+    if (report.findings.macroModules.count > 0) {
+        highReasons.push(`VBA macro payloads preserved but not executed: ${report.findings.macroModules.count.toString()}`);
+    }
+    if (report.findings.pivotTables.unsupportedCount > 0) {
+        highReasons.push(`unsupported pivot tables: ${report.findings.pivotTables.unsupportedCount.toString()}`);
+    }
+    if (report.findings.pivotTables.count > 0) {
+        mediumReasons.push(`pivot tables require review: ${report.findings.pivotTables.count.toString()}`);
+    }
+    if (report.findings.volatileFunctions.length > 0) {
+        mediumReasons.push(`volatile functions: ${formatNamedCounts(report.findings.volatileFunctions)}`);
+    }
+    if (report.findings.staleCachedFormulas.count > 0) {
+        mediumReasons.push(`stale cached formulas: ${report.findings.staleCachedFormulas.count.toString()}`);
+    }
+    if (report.findings.missingCachedFormulaValues.count > 0) {
+        mediumReasons.push(`missing cached formula values: ${report.findings.missingCachedFormulaValues.count.toString()}`);
+    }
+    if (report.findings.unsupportedRecalculations.count > 0) {
+        mediumReasons.push(`unsupported recalculation results: ${report.findings.unsupportedRecalculations.count.toString()}`);
+    }
+    if (report.cacheInspection.uninspectedFormulaCellCount > 0) {
+        mediumReasons.push(`uninspected formula cells: ${report.cacheInspection.uninspectedFormulaCellCount.toString()}`);
+    }
+    if (report.findings.warnings.length > 0) {
+        mediumReasons.push(`import warnings: ${report.findings.warnings.length.toString()}`);
+    }
+    const reasons = highReasons.length > 0 ? highReasons : mediumReasons;
+    if (reasons.length === 0) {
+        return {
+            level: 'low',
+            reasons: ['No known workbook compatibility risk signals were detected by this report.'],
+        };
+    }
+    return {
+        level: highReasons.length > 0 ? 'high' : 'medium',
+        reasons,
+    };
+}
+function parseCliArgs(args, commandName) {
+    const demo = args.includes('--demo');
+    const inputPath = demo ? undefined : args[0];
+    if (!demo && (!inputPath || inputPath.startsWith('-'))) {
+        throw new Error('Expected input XLSX path or --demo');
+    }
+    const externalWorkbooks = [];
+    let inspectLimit;
+    let json = false;
+    for (let index = demo ? 0 : 1; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined) {
+            throw new Error(`Unexpected missing ${commandName} argument`);
+        }
+        switch (arg) {
+            case '--demo':
+                break;
+            case '--external-workbook':
+                externalWorkbooks.push({ path: requireNextArg(args, index, '--external-workbook') });
+                index += 1;
+                break;
+            case '--external-workbook-target':
+                externalWorkbooks.push({
+                    path: requireNextArg(args, index, '--external-workbook-target'),
+                    target: requireNextArg(args, index + 1, '--external-workbook-target target'),
+                });
+                index += 2;
+                break;
+            case '--inspect-limit':
+                inspectLimit = parseInspectLimit(requireNextArg(args, index, '--inspect-limit'));
+                index += 1;
+                break;
+            case '--json':
+                json = true;
+                break;
+            default:
+                throw new Error(`Unknown ${commandName} option: ${arg}`);
+        }
+    }
+    return {
+        mode: demo ? 'demo' : 'file',
+        inputPath,
+        externalWorkbooks,
+        ...(inspectLimit === undefined ? {} : { inspectLimit }),
+        json,
+    };
+}
+const emptyExternalWorkbookReferenceBytes = new Uint8Array(0);
+function readExternalWorkbookReferenceInputs(workbooks) {
+    return workbooks.map((workbook) => {
+        const stats = statSync(workbook.path);
+        if (!stats.isFile()) {
+            throw new Error(`External workbook is not a file: ${workbook.path}`);
+        }
+        return {
+            bytes: emptyExternalWorkbookReferenceBytes,
+            fileName: basename(workbook.path),
+            ...(workbook.target ? { target: workbook.target } : {}),
+        };
+    });
+}
+function assertWorkbookCompatibilityReportBytesApiWithinLimit(bytes, apiName) {
+    if (bytes.byteLength <= workbookCompatibilityReportBytesApiLimit) {
+        return;
+    }
+    throw new Error([
+        `${apiName} is small-workbook only for byte-buffer XLSX input: source is ${bytes.byteLength} bytes`,
+        `limit is ${workbookCompatibilityReportBytesApiLimit} bytes`,
+        'Use buildWorkbookCompatibilityReportFromFile() for file-backed streaming-native XLSX inspection.',
+    ].join('; '));
+}
+function knownUnsupportedFunctionNamesFromFormula(formula) {
+    return extractFormulaFunctionNames(formula).filter(isKnownUnsupportedRiskFunction);
+}
+function volatileFunctionNamesFromFormula(formula) {
+    const volatileNames = new Set(volatileFunctionNames);
+    return extractFormulaFunctionNames(formula).filter((name) => volatileNames.has(name));
+}
+function extractFormulaFunctionNames(formula) {
+    const stripped = formulaWithoutStringLiterals(formula);
+    const names = new Set();
+    for (const match of stripped.matchAll(/(?:^|[^A-Za-z0-9_.])([_A-Za-z][A-Za-z0-9_.]*)\s*\(/gu)) {
+        const rawName = match[1];
+        if (rawName) {
+            names.add(normalizeFormulaFunctionName(rawName));
+        }
+    }
+    return [...names].toSorted();
+}
+function formulaWithoutStringLiterals(formula) {
+    let stripped = '';
+    let index = 0;
+    while (index < formula.length) {
+        if (formula[index] !== '"') {
+            stripped += formula[index];
+            index += 1;
+            continue;
+        }
+        stripped += ' ';
+        index += 1;
+        while (index < formula.length) {
+            stripped += ' ';
+            if (formula[index] === '"' && formula[index + 1] === '"') {
+                index += 2;
+                continue;
+            }
+            if (formula[index] === '"') {
+                index += 1;
+                break;
+            }
+            index += 1;
+        }
+    }
+    return stripped;
+}
+function normalizeFormulaFunctionName(name) {
+    return name
+        .replace(/^_xlfn\./iu, '')
+        .replace(/^_xludf\./iu, '')
+        .toUpperCase();
+}
+function isKnownUnsupportedRiskFunction(name) {
+    return knownUnsupportedRiskFunctions.has(name) || name.startsWith('_XLD') || name.startsWith('_XLUDF') || name.startsWith('_XLL');
+}
+function countNamedValues(values) {
+    const counts = new Map();
+    for (const value of values) {
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([name, count]) => ({ name, count }))
+        .toSorted((left, right) => right.count - left.count || left.name.localeCompare(right.name));
+}
+function formatNamedCounts(counts) {
+    return counts.map((entry) => `${entry.name} (${entry.count.toString()})`).join(', ');
+}
+function renderHumanReport(report) {
+    return [
+        `Workbook analyzed. Risk level: ${report.risk.level.toUpperCase()}`,
+        'Findings:',
+        `- Unsupported functions: ${report.findings.unsupportedFunctions.length > 0 ? formatNamedCounts(report.findings.unsupportedFunctions) : '0'}`,
+        `- External links: ${report.findings.externalLinks.count.toString()}`,
+        `- Macro modules: ${report.findings.macroModules.count.toString()}`,
+        `- Pivot tables: ${report.findings.pivotTables.count.toString()}`,
+        `- Volatile functions: ${report.findings.volatileFunctions.length > 0 ? formatNamedCounts(report.findings.volatileFunctions) : '0'}`,
+        `- Formula cells: ${report.workbook.formulaCellCount.toString()}`,
+        `- Stale cached formulas: ${report.findings.staleCachedFormulas.count.toString()}`,
+        `- Missing cached formula values: ${report.findings.missingCachedFormulaValues.count.toString()}`,
+        'This report identifies workbook features that may require investigation before using Bilig in a service or agent workflow. It is not an Excel compatibility certification.',
+        '',
+    ].join('\n');
+}
+function renderHelp(commandName) {
+    return `Usage: ${commandName} <input.xlsx> [options]
+       ${commandName} --demo [--json]
+
+Inspect workbook features that may require investigation before using Bilig in a
+Node service or agent workflow. This is not an Excel compatibility certificate.
+
+Options:
+  --demo                  Generate an intentionally risky workbook and report on it.
+  --inspect-limit <all|n> Formula cells to recompute during inspection. Defaults to ${defaultFileInspectLimit.toString()} for file-backed reports and ${defaultInspectLimit} for --demo.
+  --external-workbook <path>
+                          Supply a companion XLSX for external-link cache refresh. Repeatable.
+  --external-workbook-target <path> <target>
+                          Supply a companion XLSX for an exact Excel link target. Repeatable.
+  --json                  Print the machine-readable JSON report.
+  --help, -h              Show this help.
+`;
+}
+function parseInspectLimit(raw) {
+    if (raw === 'all') {
+        return raw;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`Expected --inspect-limit to be "all" or a positive integer, received: ${raw}`);
+    }
+    return value;
+}
+function requireNextArg(args, index, option) {
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) {
+        throw new Error(`Expected value after ${option}`);
+    }
+    return value;
+}
+function requireInputPath(options) {
+    if (!options.inputPath) {
+        throw new Error('Expected input XLSX path');
+    }
+    return options.inputPath;
+}
+function shellQuote(value) {
+    return /^[A-Za-z0-9_./:=@-]+$/u.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function toUint8Array(input) {
+    if (input instanceof Uint8Array) {
+        return input;
+    }
+    return new Uint8Array(input);
+}
+//# sourceMappingURL=workbook-compatibility-report.js.map