sheets-diff 2.2.0

Structured diff engine for Microsoft Excel .xlsx workbooks
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

//! Non-cell workbook object detection and coverage diagnostics (RFC-023).
//!
//! calamine 0.35 does not expose object content (charts, images, comments,
//! tables, pivot tables, hyperlinks, or data validation) through its public
//! API. What it does expose is:
//!   - `Sheet.typ: SheetType` — distinguishes WorkSheet, ChartSheet, MacroSheet, Vba
//!   - `Sheet.visible: SheetVisible`
//!
//! The policy for v2.2 is `WarnIfPresent` for non-worksheet sheet types and
//! a single coverage diagnostic explaining what is NOT compared. This prevents
//! a misleading "no differences" result when meaningful objects are present.

use calamine::{Reader, SheetType};

use crate::model::{
    Diagnostic, DiagnosticKind, DiagnosticLocation, DiffStage, Severity,
};
use crate::open::OpenedWorkbook;

// ---------------------------------------------------------------------------
// ObjectCompareMode (RFC-023 §6)
// ---------------------------------------------------------------------------

/// Controls how the presence of non-cell objects is handled.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum ObjectCompareMode {
    /// Ignore objects entirely — no diagnostics.
    Ignore,
    /// Emit a coverage warning when non-worksheet sheets or any object
    /// categories that cannot be compared are detected. Default.
    #[default]
    WarnIfPresent,
    /// Compare what is available; emit diagnostics for the rest.
    /// In v2.2 this behaves identically to `WarnIfPresent` because no
    /// object content API is available in calamine 0.35.
    CompareAvailable,
}

// ---------------------------------------------------------------------------
// Public entry point
// ---------------------------------------------------------------------------

/// Detect non-cell objects on both workbook sides and emit coverage diagnostics.
pub fn report_object_coverage(
    old_wb: &mut OpenedWorkbook,
    new_wb: &mut OpenedWorkbook,
    mode: ObjectCompareMode,
    diagnostics: &mut Vec<Diagnostic>,
) {
    if mode == ObjectCompareMode::Ignore {
        return;
    }

    detect_non_worksheet_sheets(old_wb, diagnostics);
    detect_non_worksheet_sheets(new_wb, diagnostics);

    // Emit a single blanket coverage note so consumers know what was NOT compared.
    emit_coverage_note(diagnostics);
}

// ---------------------------------------------------------------------------
// Non-worksheet sheet detection
// ---------------------------------------------------------------------------

fn detect_non_worksheet_sheets(wb: &mut OpenedWorkbook, diagnostics: &mut Vec<Diagnostic>) {
    for (index, sheet) in wb.reader.sheets_metadata().iter().enumerate() {
        let kind = match sheet.typ {
            SheetType::ChartSheet  => Some("chart sheet"),
            SheetType::MacroSheet  => Some("macro sheet"),
            SheetType::Vba         => Some("VBA module"),
            SheetType::DialogSheet => Some("dialog sheet"),
            SheetType::WorkSheet   => None, // ordinary — no warning needed
        };
        if let Some(kind_label) = kind {
            diagnostics.push(Diagnostic {
                severity: Severity::Warning,
                kind: DiagnosticKind::UnsupportedWorkbookFeature {
                    feature: kind_label.to_owned(),
                },
                location: DiagnosticLocation {
                    stage: DiffStage::Metadata,
                    sheet_order: Some(index),
                    sheet_name: Some(sheet.name.clone()),
                    address: None,
                },
                message: format!(
                    "sheet '{}' is a {} — content not compared \
                     (calamine 0.35 does not expose {} data)",
                    sheet.name, kind_label, kind_label
                ),
            });
        }
    }
}

// ---------------------------------------------------------------------------
// Blanket coverage note
// ---------------------------------------------------------------------------

fn emit_coverage_note(diagnostics: &mut Vec<Diagnostic>) {
    diagnostics.push(Diagnostic {
        severity: Severity::Info,
        kind: DiagnosticKind::UnsupportedWorkbookFeature {
            feature: "non-cell objects".to_owned(),
        },
        location: DiagnosticLocation {
            stage: DiffStage::Metadata,
            sheet_order: None,
            sheet_name: None,
            address: None,
        },
        message: "charts, images, comments, hyperlinks, tables, pivot tables, \
                  data validation, and conditional formatting are not compared \
                  in this version (calamine 0.35 does not expose object content)"
            .into(),
    });
}