Csv: add FillMissingColumnsWithNull option (issue #979)

Rows with fewer columns than the header used to throw
ColumnNotFoundException, which blocked processing files with
trailing optional fields. Adds a CsvConfiguration option that pads
missing columns with null instead, keeping the default behavior
unchanged.

Author: aasaa444

src/MiniExcel.Csv/CsvConfiguration.cs

@@ -12,6 +12,12 @@ public class CsvConfiguration : MiniExcelBaseConfiguration
     public string NewLine { get; set; } = "\r\n";
     public bool ReadLineBreaksWithinQuotes { get; set; } = true;
     public bool ReadEmptyStringAsNull { get; set; } = false;
+
+    /// <summary>
+    /// When true, rows with fewer columns than the header are padded with null values
+    /// instead of throwing a ColumnNotFoundException. Default is false.
+    /// </summary>
+    public bool FillMissingColumnsWithNull { get; set; } = false;
     public bool AlwaysQuote { get; set; } = false;
     public bool QuoteWhitespaces { get; set; } = true;
     public Func<string, string[]>? SplitFn { get; set; }

src/MiniExcel.Csv/CsvReader.cs

@@ -20,6 +20,10 @@ internal CsvReader(Stream stream, IMiniExcelConfiguration? configuration, bool l
         _config = configuration as CsvConfiguration ?? CsvConfiguration.Default;
     }
 
+    /// <summary>
+    /// Reads CSV rows as dynamic objects. When FillMissingColumnsWithNull is enabled,
+    /// rows with fewer columns than the header are padded with null values instead of throwing.
+    /// </summary>
     [CreateSyncVersion]
     public async IAsyncEnumerable<IDictionary<string, object?>> QueryAsync(bool hasHeaderRow, string? sheetName, string startCell, [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
@@ -67,7 +71,7 @@ internal CsvReader(Stream stream, IMiniExcelConfiguration? configuration, bool l
             var read = Split(finalRow);
 
             // invalid row check
-            if (read.Length < headRows.Count)
+            if (read.Length < headRows.Count && !_config.FillMissingColumnsWithNull)
             {
                 var colIndex = read.Length;
                 var headers = headRows.ToDictionary(x => x.Value, x => x.Key);

tests/MiniExcel.Csv.Tests/Issues/GithubIssuesTests.cs

@@ -8,6 +8,35 @@ public class GithubIssuesTests
     private readonly OpenXmlExporter _openXmlExporter = MiniExcel.Exporters.GetOpenXmlExporter();
     private readonly OpenXmlImporter _openXmlImporter = MiniExcel.Importers.GetOpenXmlImporter();
 
+    /// <summary>
+    /// Rows with fewer columns than the header throw by default; with
+    /// FillMissingColumnsWithNull enabled they are padded with null instead (issue #979).
+    /// </summary>
+    [Fact]
+    public async Task Issue979()
+    {
+        const string text = "A,B,C\n1,2\n";
+        using var path = AutoDeletingPath.Create(ExcelType.Csv);
+        File.WriteAllText(path.ToString(), text);
+
+        // default behavior: a row with fewer columns than the header throws
+        await Assert.ThrowsAsync<ColumnNotFoundException>(async () =>
+        {
+            await foreach (var _ in _csvImporter.QueryAsync(path.ToString(), hasHeaderRow: true)) { }
+        });
+
+        // with FillMissingColumnsWithNull, missing columns are padded with null
+        var config = new CsvConfiguration { FillMissingColumnsWithNull = true };
+        var rows = new List<dynamic>();
+        await foreach (var row in _csvImporter.QueryAsync(path.ToString(), hasHeaderRow: true, configuration: config))
+            rows.Add(row);
+
+        var casted = (IDictionary<string, object?>)rows[0];
+        Assert.Equal("1", casted["A"]?.ToString());
+        Assert.Equal("2", casted["B"]?.ToString());
+        Assert.Null(casted["C"]);
+    }
+
     // Support for Enum Mapping
     [Fact]
     public void Issue89()