Skip to main content

sheetkit_core/output/
csv.rs

1use crate::cell::CellValue;
2use crate::error::{Error, Result};
3use crate::output::budget::OutputBudget;
4use crate::resource::ResourceOperation;
5use crate::rich_text::RichTextRun;
6use crate::utils::constants::{MAX_COLUMNS, MAX_ROWS};
7
8/// Maximum bytes returned by one CSV serialization.
9///
10/// This ceiling is deliberately finite and cannot be raised by callers.
11pub const MAX_CSV_OUTPUT_BYTES: u64 = 64 * 1024 * 1024;
12
13/// Policy for text that spreadsheet applications may interpret as a formula.
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
15pub enum CsvFormulaPolicy {
16    /// Prefix formula-capable textual fields with an apostrophe.
17    #[default]
18    SpreadsheetSafe,
19    /// Preserve textual fields byte-for-byte for non-spreadsheet exchange.
20    RawExchange,
21}
22
23/// Serializes sparse typed rows as spreadsheet-safe CSV.
24///
25/// The result is staged completely before it is returned. Records are
26/// separated by LF without a trailing terminator. Formula cells export their
27/// expressions regardless of cached results, and formula-capable textual
28/// fields are neutralized before quoting.
29/// Row and column coordinates must be in-grid, strictly increasing, and unique.
30pub fn serialize_csv(rows: &[(u32, Vec<(u32, CellValue)>)]) -> Result<Vec<u8>> {
31    serialize_csv_with_policy(rows, CsvFormulaPolicy::SpreadsheetSafe)
32}
33
34/// Serializes sparse typed rows as RFC 4180 CSV with an explicit policy.
35///
36/// Select [`CsvFormulaPolicy::RawExchange`] only for consumers that will not
37/// interpret fields as spreadsheet formulas.
38/// Row and column coordinates must be in-grid, strictly increasing, and unique.
39pub fn serialize_csv_with_policy(
40    rows: &[(u32, Vec<(u32, CellValue)>)],
41    formula_policy: CsvFormulaPolicy,
42) -> Result<Vec<u8>> {
43    serialize_csv_with_limit(rows, formula_policy, MAX_CSV_OUTPUT_BYTES)
44}
45
46fn serialize_csv_with_limit(
47    rows: &[(u32, Vec<(u32, CellValue)>)],
48    formula_policy: CsvFormulaPolicy,
49    limit: u64,
50) -> Result<Vec<u8>> {
51    let mut budget = OutputBudget::new(ResourceOperation::Export, limit);
52    serialize_csv_with_reserve(rows, formula_policy, |output, bytes| {
53        budget.reserve(output, bytes)
54    })
55}
56
57fn serialize_csv_with_reserve(
58    rows: &[(u32, Vec<(u32, CellValue)>)],
59    formula_policy: CsvFormulaPolicy,
60    mut reserve: impl FnMut(&mut Vec<u8>, u64) -> Result<()>,
61) -> Result<Vec<u8>> {
62    let Some(max_column) = validate_csv_coordinates(rows)? else {
63        return Ok(Vec::new());
64    };
65
66    let output_bytes = measure_csv_output(rows, max_column, formula_policy);
67    let mut output = Vec::new();
68    reserve(&mut output, output_bytes)?;
69
70    for (row_index, (_, cells)) in rows.iter().enumerate() {
71        if row_index > 0 {
72            output.push(b'\n');
73        }
74        let mut cell_index = 0usize;
75        for column in 1..=max_column {
76            if column > 1 {
77                output.push(b',');
78            }
79
80            while cells
81                .get(cell_index)
82                .is_some_and(|(cell_column, _)| *cell_column < column)
83            {
84                cell_index += 1;
85            }
86            if let Some((cell_column, value)) = cells.get(cell_index) {
87                if *cell_column == column {
88                    append_field(&mut output, value, formula_policy);
89                    cell_index += 1;
90                }
91            }
92        }
93    }
94
95    debug_assert_eq!(u64::try_from(output.len()).ok(), Some(output_bytes));
96    Ok(output)
97}
98
99fn measure_csv_output(
100    rows: &[(u32, Vec<(u32, CellValue)>)],
101    max_column: u32,
102    formula_policy: CsvFormulaPolicy,
103) -> u64 {
104    let separators = u64::try_from(rows.len().saturating_sub(1)).unwrap_or(u64::MAX);
105    let structural_per_row = u64::from(max_column.saturating_sub(1));
106    let mut output_bytes = structural_per_row
107        .saturating_mul(u64::try_from(rows.len()).unwrap_or(u64::MAX))
108        .saturating_add(separators);
109    for (_, cells) in rows {
110        for (_, value) in cells {
111            let field = CsvField::from_cell(value);
112            let mut stats = FieldStats::default();
113            field.for_each_segment(|segment| stats.observe(segment));
114            output_bytes = output_bytes.saturating_add(
115                stats.output_bytes(
116                    formula_policy == CsvFormulaPolicy::SpreadsheetSafe
117                        && field.is_textual()
118                        && stats
119                            .first_significant
120                            .is_some_and(is_formula_trigger_character),
121                ),
122            );
123        }
124    }
125    output_bytes
126}
127
128fn validate_csv_coordinates(rows: &[(u32, Vec<(u32, CellValue)>)]) -> Result<Option<u32>> {
129    let mut previous_row = 0u32;
130    let mut max_column = None;
131
132    for (row, cells) in rows {
133        if *row == 0 || *row > MAX_ROWS {
134            return Err(Error::InvalidRowNumber(*row));
135        }
136        if *row <= previous_row {
137            return Err(Error::Internal(
138                "CSV row coordinates must be strictly increasing and unique".to_string(),
139            ));
140        }
141        previous_row = *row;
142
143        let mut previous_column = 0u32;
144        for (column, _) in cells {
145            if *column == 0 || *column > MAX_COLUMNS {
146                return Err(Error::InvalidColumnNumber(*column));
147            }
148            if *column <= previous_column {
149                return Err(Error::Internal(
150                    "CSV column coordinates must be strictly increasing and unique".to_string(),
151                ));
152            }
153            previous_column = *column;
154            max_column = Some(max_column.unwrap_or(0).max(*column));
155        }
156    }
157
158    Ok(max_column)
159}
160
161enum CsvField<'a> {
162    Borrowed { text: &'a str, textual: bool },
163    Owned { text: String, textual: bool },
164    Rich(&'a [RichTextRun]),
165    Formula(&'a str),
166}
167
168impl<'a> CsvField<'a> {
169    fn from_cell(value: &'a CellValue) -> Self {
170        match value {
171            CellValue::Formula { expr, .. } => Self::Formula(expr),
172            CellValue::Empty => Self::Borrowed {
173                text: "",
174                textual: false,
175            },
176            CellValue::Bool(value) => Self::Borrowed {
177                text: if *value { "TRUE" } else { "FALSE" },
178                textual: false,
179            },
180            CellValue::Number(_) | CellValue::Date(_) => Self::Owned {
181                text: value.to_string(),
182                textual: false,
183            },
184            CellValue::String(text) => Self::Borrowed {
185                text,
186                textual: true,
187            },
188            CellValue::Error(text) => Self::Borrowed {
189                text,
190                textual: !is_excel_error_token(text),
191            },
192            CellValue::RichString(runs) => Self::Rich(runs),
193        }
194    }
195
196    fn for_each_segment(&self, mut visit: impl FnMut(&str)) {
197        match self {
198            Self::Borrowed { text, .. } => visit(text),
199            Self::Owned { text, .. } => visit(text),
200            Self::Rich(runs) => {
201                for run in *runs {
202                    visit(&run.text);
203                }
204            }
205            Self::Formula(expression) => {
206                visit("=");
207                visit(expression);
208            }
209        }
210    }
211
212    fn is_textual(&self) -> bool {
213        match self {
214            Self::Borrowed { textual, .. } | Self::Owned { textual, .. } => *textual,
215            Self::Rich(_) | Self::Formula(_) => true,
216        }
217    }
218}
219
220#[derive(Default)]
221struct FieldStats {
222    content_bytes: u64,
223    quote_count: u64,
224    needs_quotes: bool,
225    first_significant: Option<char>,
226}
227
228impl FieldStats {
229    fn observe(&mut self, segment: &str) {
230        self.content_bytes = self
231            .content_bytes
232            .saturating_add(u64::try_from(segment.len()).unwrap_or(u64::MAX));
233        self.quote_count = self.quote_count.saturating_add(
234            u64::try_from(segment.bytes().filter(|byte| *byte == b'"').count()).unwrap_or(u64::MAX),
235        );
236        self.needs_quotes |= segment
237            .bytes()
238            .any(|byte| matches!(byte, b',' | b'"' | b'\r' | b'\n'));
239        if self.first_significant.is_none() {
240            self.first_significant = segment
241                .chars()
242                .find(|character| !is_formula_leading_character(*character));
243        }
244    }
245
246    fn output_bytes(&self, neutralized: bool) -> u64 {
247        let neutralizer = u64::from(neutralized);
248        let structural = if self.needs_quotes { 2 } else { 0 };
249        self.content_bytes
250            .checked_add(self.quote_count)
251            .and_then(|value| value.checked_add(neutralizer))
252            .and_then(|value| value.checked_add(structural))
253            .unwrap_or(u64::MAX)
254    }
255}
256
257fn append_field(output: &mut Vec<u8>, value: &CellValue, formula_policy: CsvFormulaPolicy) {
258    let field = CsvField::from_cell(value);
259    let mut stats = FieldStats::default();
260    field.for_each_segment(|segment| stats.observe(segment));
261    let neutralized = formula_policy == CsvFormulaPolicy::SpreadsheetSafe
262        && field.is_textual()
263        && stats
264            .first_significant
265            .is_some_and(is_formula_trigger_character);
266    if stats.needs_quotes {
267        output.push(b'"');
268    }
269    if neutralized {
270        output.push(b'\'');
271    }
272    field.for_each_segment(|segment| append_segment(output, segment, stats.needs_quotes));
273    if stats.needs_quotes {
274        output.push(b'"');
275    }
276}
277
278fn append_segment(output: &mut Vec<u8>, segment: &str, quoted: bool) {
279    if !quoted {
280        output.extend_from_slice(segment.as_bytes());
281        return;
282    }
283
284    let mut start = 0usize;
285    for (index, byte) in segment.bytes().enumerate() {
286        if byte == b'"' {
287            output.extend_from_slice(&segment.as_bytes()[start..index]);
288            output.extend_from_slice(b"\"\"");
289            start = index + 1;
290        }
291    }
292    output.extend_from_slice(&segment.as_bytes()[start..]);
293}
294
295fn is_formula_leading_character(character: char) -> bool {
296    character.is_whitespace() || character.is_control() || character == '\u{feff}'
297}
298
299fn is_formula_trigger_character(character: char) -> bool {
300    matches!(character, '=' | '+' | '-' | '@')
301}
302
303pub(crate) fn is_excel_error_token(value: &str) -> bool {
304    matches!(
305        value,
306        "#NULL!"
307            | "#DIV/0!"
308            | "#VALUE!"
309            | "#REF!"
310            | "#NAME?"
311            | "#NUM!"
312            | "#N/A"
313            | "#GETTING_DATA"
314            | "#SPILL!"
315            | "#CALC!"
316            | "#FIELD!"
317            | "#BLOCKED!"
318            | "#UNKNOWN!"
319            | "#CONNECT!"
320            | "#BUSY!"
321            | "#PYTHON!"
322    )
323}
324
325#[cfg(test)]
326mod tests {
327    use super::*;
328    use crate::resource::ResourceDimension;
329
330    fn one_cell(value: &str) -> Vec<(u32, Vec<(u32, CellValue)>)> {
331        vec![(1, vec![(1, CellValue::String(value.to_string()))])]
332    }
333
334    fn metadata(error: Error) -> crate::ResourceLimitError {
335        let Error::ResourceLimitExceeded(metadata) = error else {
336            panic!("expected resource limit error");
337        };
338        metadata
339    }
340
341    #[test]
342    fn exact_output_limit_succeeds_and_plus_one_is_rejected() {
343        let rows = one_cell("a");
344        assert_eq!(
345            serialize_csv_with_limit(&rows, CsvFormulaPolicy::SpreadsheetSafe, 1).unwrap(),
346            b"a"
347        );
348
349        let error =
350            serialize_csv_with_limit(&rows, CsvFormulaPolicy::SpreadsheetSafe, 0).unwrap_err();
351        let metadata = metadata(error);
352        assert_eq!(metadata.limit(), 0);
353        assert_eq!(metadata.observed(), 1);
354        assert_eq!(metadata.operation(), ResourceOperation::Export);
355        assert_eq!(metadata.category(), crate::ResourceCategory::Output);
356        assert_eq!(metadata.dimension(), ResourceDimension::OutputBytes);
357        assert_eq!(metadata.stage(), Some(crate::ResourceStage::Serialize));
358    }
359
360    #[test]
361    fn formula_cells_export_expressions_regardless_of_cached_results() {
362        let rows = vec![
363            (
364                1,
365                vec![(
366                    1,
367                    CellValue::Formula {
368                        expr: "1+1".to_string(),
369                        result: Some(Box::new(CellValue::Number(2.0))),
370                    },
371                )],
372            ),
373            (
374                2,
375                vec![(
376                    1,
377                    CellValue::Formula {
378                        expr: "2+2".to_string(),
379                        result: None,
380                    },
381                )],
382            ),
383        ];
384
385        assert_eq!(
386            serialize_csv(&rows).unwrap(),
387            b"'=1+1\n'=2+2",
388            "default CSV bytes must match the Node and CLI contract"
389        );
390        assert_eq!(
391            serialize_csv_with_policy(&rows, CsvFormulaPolicy::RawExchange).unwrap(),
392            b"=1+1\n=2+2"
393        );
394    }
395
396    #[test]
397    fn rejection_returns_no_partial_output_value() {
398        let rows = one_cell("=dangerous");
399        assert!(serialize_csv_with_limit(&rows, CsvFormulaPolicy::SpreadsheetSafe, 1).is_err());
400    }
401
402    #[test]
403    fn serialization_reserves_the_exact_output_once_before_emission() {
404        let rows = vec![(
405            1,
406            (1..=4_096)
407                .map(|column| (column, CellValue::String("value".to_string())))
408                .collect(),
409        )];
410        let mut reserve_calls = Vec::new();
411
412        let output = serialize_csv_with_reserve(
413            &rows,
414            CsvFormulaPolicy::SpreadsheetSafe,
415            |output, bytes| {
416                reserve_calls.push(bytes);
417                output
418                    .try_reserve_exact(usize::try_from(bytes).unwrap())
419                    .map_err(|_| Error::Internal("test allocation failed".to_string()))
420            },
421        )
422        .unwrap();
423
424        assert_eq!(reserve_calls, [u64::try_from(output.len()).unwrap()]);
425    }
426}