Improve Excel preflight and report evidence

Author: PrzemyslawKlys

Directory.Build.targets

@@ -11,9 +11,9 @@
     <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
   </PropertyGroup>
 
-  <!-- Examples are executable documentation. Keep samples focused on API usage rather than nullable ceremony. -->
+  <!-- Examples are executable documentation. Keep nullable enabled so annotated samples do not emit CS8632 noise. -->
   <PropertyGroup Condition="'$(MSBuildProjectName)' == 'OfficeIMO.Examples'">
     <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
-    <Nullable>disable</Nullable>
+    <Nullable>enable</Nullable>
   </PropertyGroup>
 </Project>

Docs/officeimo.excel.large-workbook-guidance.md

@@ -43,6 +43,20 @@ formulas.EnsureAllHaveCachedResults();
 
 Use `EnsureNoAdvancedFeatures()` only for workflows that must avoid preserve-only package content such as custom XML, macros, slicers, timelines, embedded packages, or external workbook relationships.
 
+For workflow routing, prefer the capability preflight API over ad hoc feature-name checks:
+
+```csharp
+ExcelFeatureReport features = document.InspectFeatures();
+
+features.EnsureCan(ExcelPreflightCapability.EditCellValues);
+
+if (!features.Can(ExcelPreflightCapability.ExportPdfReport)) {
+    File.WriteAllText("excel-preflight.md", features.ToMarkdown());
+}
+```
+
+`ExcelPreflightCapability` covers readback, cell-value edits, structure-changing edits, cached formula reads, OfficeIMO formula calculation, template binding, and first-party PDF report export. This is intentionally separate from benchmark guidance and does not require benchmark runs in CI.
+
 ## Measuring A Change
 
 Use the benchmark harness for repeatable local evidence:

OfficeIMO.Examples/Excel/FeaturePreflight.cs

@@ -0,0 +1,39 @@
+using System;
+using System.IO;
+using OfficeIMO.Excel;
+
+namespace OfficeIMO.Examples.Excel {
+    /// <summary>
+    /// Demonstrates workflow-level feature preflight before read, edit, template, or PDF operations.
+    /// </summary>
+    public static class FeaturePreflight {
+        public static void Example(string folderPath, bool openExcel) {
+            Console.WriteLine("[*] Excel - Feature preflight");
+            string filePath = Path.Combine(folderPath, "FeaturePreflight.xlsx");
+
+            using (ExcelDocument document = ExcelDocument.Create(filePath)) {
+                ExcelSheet sheet = document.AddWorkSheet("Report");
+                sheet.CellValue(1, 1, "Name");
+                sheet.CellValue(1, 2, "Score");
+                sheet.CellValue(2, 1, "Alpha");
+                sheet.CellValue(2, 2, 10d);
+                sheet.CellValue(3, 1, "Beta");
+                sheet.CellValue(3, 2, 20d);
+                sheet.CellFormula(4, 2, "SUM(B2:B3)");
+                document.Calculate();
+                document.Save(openExcel);
+            }
+
+            using (ExcelDocument document = ExcelDocument.Load(filePath, readOnly: true)) {
+                ExcelFeatureReport report = document.InspectFeatures();
+
+                foreach (ExcelPreflightCapability capability in Enum.GetValues(typeof(ExcelPreflightCapability))) {
+                    Console.WriteLine($"{capability}: {(report.Can(capability) ? "ready" : "blocked")}");
+                    foreach (string diagnostic in report.GetCapabilityDiagnostics(capability)) {
+                        Console.WriteLine("  - " + diagnostic);
+                    }
+                }
+            }
+        }
+    }
+}

OfficeIMO.Examples/Excel/ReportWorkflow.cs

@@ -0,0 +1,71 @@
+using DocumentFormat.OpenXml.Spreadsheet;
+using OfficeIMO.Excel;
+using OfficeIMO.Excel.Pdf;
+using PdfCore = OfficeIMO.Pdf;
+
+namespace OfficeIMO.Examples.Excel {
+    /// <summary>
+    /// Demonstrates a template-to-report workflow with formulas, charts, pivots, preflight, and PDF export.
+    /// </summary>
+    public static class ReportWorkflow {
+        public static void Example(string folderPath, bool openExcel) {
+            Console.WriteLine("[*] Excel - Report workflow");
+            string workbookPath = Path.Combine(folderPath, "ExcelReportWorkflow.xlsx");
+            string pdfPath = Path.Combine(folderPath, "ExcelReportWorkflow.pdf");
+
+            using (ExcelDocument document = ExcelDocument.Create(workbookPath, "Report")) {
+                ExcelSheet sheet = document.Sheets[0];
+                sheet.Cell(1, 1, "{{ReportTitle}}");
+                sheet.Cell(2, 1, "Region");
+                sheet.Cell(2, 2, "Revenue");
+                sheet.Cell(2, 3, "Cost");
+                sheet.Cell(2, 4, "Margin");
+                sheet.Cell(3, 1, "East");
+                sheet.Cell(3, 2, 120);
+                sheet.Cell(3, 3, 50);
+                sheet.CellFormula(3, 4, "B3-C3");
+                sheet.Cell(4, 1, "West");
+                sheet.Cell(4, 2, 90);
+                sheet.Cell(4, 3, 40);
+                sheet.CellFormula(4, 4, "B4-C4");
+
+                document.ApplyTemplate(new {
+                    ReportTitle = "Executive revenue report"
+                });
+                document.Calculate();
+
+                sheet.AddTable("A2:D4", hasHeader: true, name: "RevenueData", style: OfficeIMO.Excel.TableStyle.TableStyleMedium4);
+                sheet.AddChartFromRange("A2:D4", row: 6, column: 1, widthPixels: 420, heightPixels: 240,
+                    type: ExcelChartType.ColumnClustered, title: "Revenue and Margin");
+                sheet.AddPivotTable(
+                    sourceRange: "A2:D4",
+                    destinationCell: "F2",
+                    name: "RevenuePivot",
+                    rowFields: new[] { "Region" },
+                    dataFields: new[] { new ExcelPivotDataField("Revenue", DataConsolidateFunctionValues.Sum, "Total Revenue") },
+                    pivotStyleName: "PivotStyleMedium9");
+
+                ExcelFeatureReport report = document.InspectFeatures();
+                if (!report.Can(ExcelPreflightCapability.ExportPdfReport)) {
+                    Console.WriteLine("[!] Excel-to-PDF export is blocked:");
+                    foreach (string diagnostic in report.GetCapabilityDiagnostics(ExcelPreflightCapability.ExportPdfReport)) {
+                        Console.WriteLine("  - " + diagnostic);
+                    }
+                    return;
+                }
+
+                document.Save(false);
+                document.SaveAsPdf(pdfPath, new ExcelPdfSaveOptions {
+                    IncludeSheetHeadings = false,
+                    HeaderRowCount = 1,
+                    PageSize = new PdfCore.PageSize(560, 520),
+                    Margins = PdfCore.PageMargins.Uniform(24)
+                });
+
+                if (openExcel) {
+                    document.Open(workbookPath, true);
+                }
+            }
+        }
+    }
+}

OfficeIMO.Examples/OfficeIMO.Examples.csproj

@@ -11,6 +11,7 @@
 
     <ItemGroup>
         <ProjectReference Include="..\\OfficeIMO.Excel\\OfficeIMO.Excel.csproj" />
+        <ProjectReference Include="..\\OfficeIMO.Excel.Pdf\\OfficeIMO.Excel.Pdf.csproj" />
         <ProjectReference Include="..\\OfficeIMO.Excel.GoogleSheets\\OfficeIMO.Excel.GoogleSheets.csproj" />
         <ProjectReference Include="..\\OfficeIMO.GoogleWorkspace\\OfficeIMO.GoogleWorkspace.csproj" />
         <ProjectReference Include="..\\OfficeIMO.Pdf\\OfficeIMO.Pdf.csproj" />

OfficeIMO.Examples/Program.cs

@@ -319,6 +319,10 @@ static void Main(string[] args) {
             // Excel.ReadPresetsAndHelpers.Example(folderPath, false);
             // // Excel/Read for PowerShell consumption (emits JSON rows)
             // Excel.ReadForPowerShell.Example(folderPath, false);
+            // // Excel/Feature preflight for read/edit/template/PDF workflow routing
+            // Excel.FeaturePreflight.Example(folderPath, false);
+            // // Excel/Report workflow with template, formulas, chart, pivot, preflight, and PDF
+            // Excel.ReportWorkflow.Example(folderPath, false);
             // // Excel/PowerShell-style round trip: write → read → modify → write → JSON
             // Excel.PowerShellRoundTrip.Example(folderPath, false);
             // // Excel/Headers + Footers + Properties

OfficeIMO.Excel/ExcelFeatureReport.Preflight.cs

@@ -0,0 +1,228 @@
+namespace OfficeIMO.Excel {
+    /// <summary>
+    /// Workflow-level OfficeIMO.Excel operation categories covered by feature preflight checks.
+    /// </summary>
+    public enum ExcelPreflightCapability {
+        /// <summary>Read worksheet data, tables, and typed rows from the workbook.</summary>
+        ReadWorkbookData,
+
+        /// <summary>Edit existing cell values while preserving package parts OfficeIMO does not fully author yet.</summary>
+        EditCellValues,
+
+        /// <summary>Perform structure-changing edits such as adding/removing sheets, tables, drawings, pivots, or relationships.</summary>
+        EditWorkbookStructure,
+
+        /// <summary>Use cached formula values for reads, export, or downstream reporting.</summary>
+        UseCachedFormulaValues,
+
+        /// <summary>Calculate workbook formulas through OfficeIMO's lightweight evaluator.</summary>
+        CalculateFormulas,
+
+        /// <summary>Bind data into an Excel template and save the generated workbook.</summary>
+        BindTemplate,
+
+        /// <summary>Export a report workbook through the first-party OfficeIMO Excel-to-PDF path.</summary>
+        ExportPdfReport
+    }
+
+    public sealed partial class ExcelFeatureReport {
+        /// <summary>
+        /// True when OfficeIMO can attempt read-oriented workbook data operations.
+        /// </summary>
+        public bool CanReadWorkbookData => UnsupportedFeatures.Count == 0;
+
+        /// <summary>
+        /// True when OfficeIMO can attempt cell-value edits without known unsupported package features.
+        /// </summary>
+        public bool CanEditCellValues => UnsupportedFeatures.Count == 0;
+
+        /// <summary>
+        /// True when OfficeIMO can attempt structure-changing workbook edits without preserve-only or unsupported feature blockers.
+        /// </summary>
+        public bool CanEditWorkbookStructure => !HasAdvancedFeatures;
+
+        /// <summary>
+        /// True when cached formula values can be trusted for read/export workflows.
+        /// </summary>
+        public bool CanUseCachedFormulaValues =>
+            FindFeatureCount("Missing formula caches") == 0 &&
+            FindFeatureCount("Formula dependency issues") == 0;
+
+        /// <summary>
+        /// True when OfficeIMO's lightweight evaluator can calculate all discovered formulas without known dependency issues.
+        /// </summary>
+        public bool CanCalculateFormulas =>
+            FindFeatureCount("Unsupported formulas") == 0 &&
+            FindFeatureCount("Formula dependency issues") == 0;
+
+        /// <summary>
+        /// True when template binding can be attempted without preserve-only or unsupported advanced package features.
+        /// </summary>
+        public bool CanBindTemplate => !HasAdvancedFeatures;
+
+        /// <summary>
+        /// True when the workbook is suitable for the first-party report-grade Excel-to-PDF export path.
+        /// </summary>
+        public bool CanExportPdfReport =>
+            !HasAdvancedFeatures &&
+            CanUseCachedFormulaValues;
+
+        /// <summary>
+        /// Returns true when the requested workflow-level capability can be attempted for this workbook.
+        /// </summary>
+        /// <param name="capability">The OfficeIMO.Excel workflow capability to check.</param>
+        public bool Can(ExcelPreflightCapability capability) {
+            switch (capability) {
+                case ExcelPreflightCapability.ReadWorkbookData:
+                    return CanReadWorkbookData;
+                case ExcelPreflightCapability.EditCellValues:
+                    return CanEditCellValues;
+                case ExcelPreflightCapability.EditWorkbookStructure:
+                    return CanEditWorkbookStructure;
+                case ExcelPreflightCapability.UseCachedFormulaValues:
+                    return CanUseCachedFormulaValues;
+                case ExcelPreflightCapability.CalculateFormulas:
+                    return CanCalculateFormulas;
+                case ExcelPreflightCapability.BindTemplate:
+                    return CanBindTemplate;
+                case ExcelPreflightCapability.ExportPdfReport:
+                    return CanExportPdfReport;
+                default:
+                    throw new ArgumentOutOfRangeException(nameof(capability), capability, "Unsupported Excel preflight capability.");
+            }
+        }
+
+        /// <summary>
+        /// Throws with workflow-specific diagnostics when the requested capability cannot be attempted for this workbook.
+        /// </summary>
+        /// <param name="capability">The OfficeIMO.Excel workflow capability that must be available.</param>
+        /// <returns>The current feature report for fluent guard usage.</returns>
+        public ExcelFeatureReport EnsureCan(ExcelPreflightCapability capability) {
+            if (Can(capability)) {
+                return this;
+            }
+
+            IReadOnlyList<string> diagnostics = GetCapabilityDiagnostics(capability);
+            string detail = diagnostics.Count == 0
+                ? "No additional diagnostics were reported."
+                : string.Join("; ", diagnostics);
+            throw new InvalidOperationException($"Excel preflight capability '{capability}' is not available: {detail}");
+        }
+
+        /// <summary>
+        /// Returns operation-specific diagnostics explaining why a workflow-level capability is blocked, or an empty list when it can be attempted.
+        /// </summary>
+        /// <param name="capability">The OfficeIMO.Excel workflow capability to explain.</param>
+        public IReadOnlyList<string> GetCapabilityDiagnostics(ExcelPreflightCapability capability) {
+            if (Can(capability)) {
+                return Array.Empty<string>();
+            }
+
+            var messages = new List<string>();
+            switch (capability) {
+                case ExcelPreflightCapability.ReadWorkbookData:
+                    AddUnsupportedDiagnostics(messages, "Workbook data reads are blocked by unsupported workbook features.");
+                    break;
+                case ExcelPreflightCapability.EditCellValues:
+                    AddUnsupportedDiagnostics(messages, "Cell-value edits are blocked by unsupported workbook features.");
+                    break;
+                case ExcelPreflightCapability.EditWorkbookStructure:
+                    AddUnsupportedDiagnostics(messages, "Structure-changing edits are blocked by unsupported workbook features.");
+                    AddPreservedDiagnostics(messages, "Structure-changing edits should not be attempted while preserve-only workbook features are present.");
+                    break;
+                case ExcelPreflightCapability.UseCachedFormulaValues:
+                    AddFormulaDiagnostics(messages, requireCachedValues: true, requireSupportedFormulas: false);
+                    break;
+                case ExcelPreflightCapability.CalculateFormulas:
+                    AddFormulaDiagnostics(messages, requireCachedValues: false, requireSupportedFormulas: true);
+                    break;
+                case ExcelPreflightCapability.BindTemplate:
+                    AddUnsupportedDiagnostics(messages, "Template binding is blocked by unsupported workbook features.");
+                    AddPreservedDiagnostics(messages, "Template binding should not be attempted while preserve-only workbook features are present unless the workflow has explicit preservation coverage for those parts.");
+                    break;
+                case ExcelPreflightCapability.ExportPdfReport:
+                    AddUnsupportedDiagnostics(messages, "Excel-to-PDF report export is blocked by unsupported workbook features.");
+                    AddPreservedDiagnostics(messages, "Excel-to-PDF report export does not render preserve-only workbook features.");
+                    AddFormulaDiagnostics(messages, requireCachedValues: true, requireSupportedFormulas: false);
+                    break;
+                default:
+                    throw new ArgumentOutOfRangeException(nameof(capability), capability, "Unsupported Excel preflight capability.");
+            }
+
+            if (messages.Count == 0) {
+                AddDistinct(messages, "The requested Excel workflow is not available for this workbook.");
+            }
+
+            return messages.AsReadOnly();
+        }
+
+        private void AddUnsupportedDiagnostics(List<string> messages, string fallbackMessage) {
+            if (UnsupportedFeatures.Count == 0) {
+                return;
+            }
+
+            AddDistinct(messages, fallbackMessage);
+            AddFeatureDiagnostics(messages, UnsupportedFeatures);
+        }
+
+        private void AddPreservedDiagnostics(List<string> messages, string fallbackMessage) {
+            if (PreservedFeatures.Count == 0) {
+                return;
+            }
+
+            AddDistinct(messages, fallbackMessage);
+            AddFeatureDiagnostics(messages, PreservedFeatures);
+        }
+
+        private void AddFormulaDiagnostics(List<string> messages, bool requireCachedValues, bool requireSupportedFormulas) {
+            if (requireSupportedFormulas) {
+                AddFeatureDiagnostics(messages, FindFeatures("Unsupported formulas"));
+            }
+
+            if (requireCachedValues) {
+                AddFeatureDiagnostics(messages, FindFeatures("Missing formula caches"));
+            }
+
+            AddFeatureDiagnostics(messages, FindFeatures("Formula dependency issues"));
+        }
+
+        private static void AddFeatureDiagnostics(List<string> messages, IEnumerable<ExcelFeatureFinding> findings) {
+            foreach (ExcelFeatureFinding finding in findings) {
+                AddDistinct(messages, FormatCapabilityFinding(finding));
+            }
+        }
+
+        private static string FormatCapabilityFinding(ExcelFeatureFinding finding) {
+            string message = $"{finding.Name} ({finding.Count}, {finding.SupportLevel}): {finding.Note}";
+            if (finding.Details.Count == 0) {
+                return message;
+            }
+
+            const int maxDetails = 3;
+            string details = string.Join("; ", finding.Details.Take(maxDetails));
+            if (finding.Details.Count > maxDetails) {
+                details += $"; +{finding.Details.Count - maxDetails} more";
+            }
+
+            return message + " [" + details + "]";
+        }
+
+        private int FindFeatureCount(string featureName) {
+            return FindFeatures(featureName).Sum(feature => feature.Count);
+        }
+
+        private static void AddDistinct(List<string> messages, string message) {
+            if (string.IsNullOrWhiteSpace(message)) {
+                return;
+            }
+
+            for (int i = 0; i < messages.Count; i++) {
+                if (string.Equals(messages[i], message, StringComparison.Ordinal)) {
+                    return;
+                }
+            }
+
+            messages.Add(message);
+        }
+    }
+}