fix(csv): keep exported cell values literal in spreadsheet imports (#7227)

Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>

Author: kah-ja

app/common/src/main/java/stirling/software/common/util/CsvSanitizer.java

@@ -0,0 +1,69 @@
+package stirling.software.common.util;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Pattern;
+
+import lombok.experimental.UtilityClass;
+
+/**
+ * Keeps CSV cell values literal when the file is opened in a spreadsheet application.
+ *
+ * <p>CSV quoting protects the record structure only. Excel, LibreOffice Calc and Google Sheets
+ * strip the surrounding quotes on import and evaluate a cell that starts with {@code =}, {@code +},
+ * {@code -} or {@code @} as a formula. Cell values taken from a document a user supplied are
+ * therefore prefixed with a single quote, which spreadsheets read as "the rest of this cell is
+ * text". Leading whitespace, including the tab and carriage return that spreadsheets discard before
+ * evaluating, is skipped when looking for the trigger character.
+ *
+ * <p>Values that are a number with optional sign, group separators and decimal point stay
+ * untouched: they cannot reference a cell or call a function, and prefixing them would turn the
+ * numeric columns of an extracted table into text.
+ */
+@UtilityClass
+public class CsvSanitizer {
+
+    private static final String FORMULA_TRIGGERS = "=+-@";
+
+    private static final String TEXT_PREFIX = "'";
+
+    private static final Pattern PLAIN_NUMBER = Pattern.compile("[-+]?[0-9]+(?:[.,][0-9]+)*");
+
+    /**
+     * Prefixes a cell value with a single quote when a spreadsheet would otherwise read it as a
+     * formula.
+     *
+     * @param value the cell value, may be null
+     * @return the value as literal text, null and empty input returned unchanged
+     */
+    public String sanitizeCell(String value) {
+        if (value == null || value.isEmpty()) {
+            return value;
+        }
+        String candidate = value.stripLeading();
+        if (candidate.isEmpty() || FORMULA_TRIGGERS.indexOf(candidate.charAt(0)) < 0) {
+            return value;
+        }
+        if (PLAIN_NUMBER.matcher(candidate).matches()) {
+            return value;
+        }
+        return TEXT_PREFIX + value;
+    }
+
+    /**
+     * Applies {@link #sanitizeCell(String)} to every cell of a record.
+     *
+     * @param row the record, may be null
+     * @return a new list holding the sanitized cells, null input returned unchanged
+     */
+    public List<String> sanitizeRow(List<String> row) {
+        if (row == null) {
+            return row;
+        }
+        List<String> sanitized = new ArrayList<>(row.size());
+        for (String cell : row) {
+            sanitized.add(sanitizeCell(cell));
+        }
+        return sanitized;
+    }
+}

app/common/src/test/java/stirling/software/common/util/CsvSanitizerTest.java

@@ -0,0 +1,61 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+class CsvSanitizerTest {
+
+    @ParameterizedTest
+    @ValueSource(
+            strings = {
+                "=SUM(A1:A2)",
+                "+HYPERLINK(\"http://example.com\")",
+                "-WEBSERVICE(\"http://example.com\")",
+                "@SUM(1+1)",
+                " =SUM(A1:A2)",
+                "\t=SUM(A1:A2)",
+                "\r@SUM(1+1)"
+            })
+    void prefixesValuesASpreadsheetWouldEvaluate(String value) {
+        assertEquals("'" + value, CsvSanitizer.sanitizeCell(value));
+    }
+
+    @ParameterizedTest
+    @ValueSource(
+            strings = {
+                "Alice",
+                "1234",
+                "-42",
+                "-1,234.56",
+                "+0.5",
+                " -42",
+                "total = 12",
+                "a=b",
+                "   "
+            })
+    void leavesPlainTextAndNumbersUnchanged(String value) {
+        assertEquals(value, CsvSanitizer.sanitizeCell(value));
+    }
+
+    @Test
+    void handlesNullAndEmptyValues() {
+        assertNull(CsvSanitizer.sanitizeCell(null));
+        assertEquals("", CsvSanitizer.sanitizeCell(""));
+        assertNull(CsvSanitizer.sanitizeRow(null));
+    }
+
+    @Test
+    void sanitizesEveryCellOfARecord() {
+        List<String> row = Arrays.asList("=SUM(A1:A2)", "Alice", null, "-42");
+
+        assertEquals(
+                Arrays.asList("'=SUM(A1:A2)", "Alice", null, "-42"), CsvSanitizer.sanitizeRow(row));
+    }
+}

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ExtractCSVController.java

@@ -35,6 +35,7 @@
 import stirling.software.common.model.tool.ToolFormat;
 import stirling.software.common.model.tool.ToolIO;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.util.CsvSanitizer;
 import stirling.software.common.util.GeneralUtils;
 import stirling.software.common.util.WebResponseUtils;
 
@@ -73,7 +74,7 @@ public ResponseEntity<?> pdfToCsv(@ModelAttribute PDFWithPageNums request) throw
                     StringWriter sw = new StringWriter();
                     try (CSVPrinter printer = format.print(sw)) {
                         for (List<String> row : fragments.get(i).rawRows()) {
-                            printer.printRecord(row);
+                            printer.printRecord(CsvSanitizer.sanitizeRow(row));
                         }
                     }
                     csvEntries.add(

app/core/src/main/java/stirling/software/SPDF/controller/api/form/FormFillController.java

@@ -43,6 +43,7 @@
 
 import stirling.software.common.model.FormFieldWithCoordinates;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.util.CsvSanitizer;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.FormUtils;
 import stirling.software.common.util.TempFile;
@@ -280,7 +281,11 @@ public ResponseEntity<byte[]> extractCsv(
                 csvWriter.writeNext(header);
 
                 for (FormUtils.FormFieldInfo field : fields) {
-                    csvWriter.writeNext(new String[] {field.name(), field.value()});
+                    csvWriter.writeNext(
+                            new String[] {
+                                CsvSanitizer.sanitizeCell(field.name()),
+                                CsvSanitizer.sanitizeCell(field.value())
+                            });
                 }
             }
 

app/core/src/test/java/stirling/software/SPDF/controller/api/converters/ExtractCSVControllerMoreTest.java

@@ -193,6 +193,31 @@ void loadFailurePropagates() throws Exception {
         }
     }
 
+    @Test
+    @DisplayName("cells a spreadsheet would evaluate are written as literal text")
+    void formulaCellsAreQuoted() throws Exception {
+        PDFWithPageNums request = new PDFWithPageNums();
+        request.setFileInput(pdf("table.pdf"));
+        request.setPageNumbers("all");
+
+        when(pdfDocumentFactory.load(request)).thenReturn(docWithPages(1));
+        when(tabulaTableParser.parse(any(PDDocument.class), eq(1)))
+                .thenReturn(
+                        List.of(
+                                fragment(
+                                        List.of(
+                                                List.of("=SUM(A1:A2)", "@SUM(1+1)"),
+                                                List.of("Alice", "-42")))));
+
+        ResponseEntity<?> response = controller.pdfToCsv(request);
+
+        String body = response.getBody().toString();
+        assertThat(body).contains("\"'=SUM(A1:A2)\"").contains("\"'@SUM(1+1)\"");
+        assertThat(body).doesNotContain("\"=SUM(A1:A2)\"").doesNotContain("\"@SUM(1+1)\"");
+        // Text and numeric cells keep their original form.
+        assertThat(body).contains("\"Alice\"").contains("\"-42\"");
+    }
+
     @Test
     @DisplayName("single table CSV body is quote-wrapped per the EXCEL/QuoteMode.ALL format")
     void csvBodyIsQuoted() throws Exception {

app/core/src/test/java/stirling/software/SPDF/controller/api/form/FormFillControllerTest.java

@@ -10,10 +10,12 @@
 import java.io.IOException;
 import java.nio.file.Files;
 
+import org.apache.pdfbox.cos.COSName;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.apache.pdfbox.pdmodel.PDPage;
 import org.apache.pdfbox.pdmodel.common.PDRectangle;
 import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDTextField;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Nested;
@@ -87,6 +89,16 @@ private PDDocument createMinimalPdf() {
         return doc;
     }
 
+    private PDDocument createPdfWithTextField(String name, String value) {
+        PDDocument doc = createMinimalPdf();
+        PDAcroForm acroForm = doc.getDocumentCatalog().getAcroForm();
+        PDTextField field = new PDTextField(acroForm);
+        field.setPartialName(name);
+        field.getCOSObject().setString(COSName.V, value);
+        acroForm.getFields().add(field);
+        return doc;
+    }
+
     private byte[] pdfBytes() throws IOException {
         try (PDDocument doc = createMinimalPdf();
                 ByteArrayOutputStream baos = new ByteArrayOutputStream()) {
@@ -183,6 +195,19 @@ void validPdfNullData() throws Exception {
             assertThat(csv).contains("Field Name");
         }
 
+        @Test
+        @DisplayName("keeps a field value a spreadsheet would evaluate as literal text")
+        void formulaFieldValueIsQuoted() throws Exception {
+            MockMultipartFile file = pdfFile();
+            PDDocument doc = createPdfWithTextField("note", "=SUM(A1:A2)");
+            when(pdfDocumentFactory.load(eq(file), eq(true))).thenReturn(doc);
+
+            ResponseEntity<byte[]> response = controller.extractCsv(file, null);
+
+            String csv = new String(response.getBody());
+            assertThat(csv).contains("\"'=SUM(A1:A2)\"").doesNotContain("\"=SUM(A1:A2)\"");
+        }
+
         @Test
         @DisplayName("throws for null file")
         void nullFile() {