Harden parser lifetime, EOF handling, and validation tooling

Keep the existing streaming C++11 parser API and permissive CSV behavior while tightening correctness and production validation.

Parser changes:\n- Fix EOF handling for trailing empty fields, empty quoted fields, and empty fields at EOF.\n- Fix position() accounting so it tracks consumed parser position instead of buffered chunk size.\n- Add an owning std::unique_ptr<std::istream> constructor and CsvParser::from_file(path).\n- Preserve the borrowed std::istream& constructor for compatibility.\n- Reject null owned streams and failed input streams early.\n- Improve common payload parsing by appending contiguous field spans instead of pushing every byte individually.

Validation and release tooling:\n- Add regression tests for EOF, position, and stream ownership behavior.\n- Add RapidCheck property tests.\n- Add AFL-style, libFuzzer, and deterministic sanitizer mutation fuzz harnesses.\n- Add GitHub Actions CI for tests, fuzz smoke builds, and benchmark harness checks.\n- Add security notes and benchmark/profiling workflow docs.

Compatibility:\n- Existing CsvParser(std::istream&) usage continues to work.\n- Default parsing remains permissive.\n- No strict mode or size limits are enabled by default.

Author: AriaFallah

.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure unit tests
+        run: cmake -S test -B test/out
+
+      - name: Build unit tests
+        run: cmake --build test/out --parallel
+
+      - name: Run unit tests
+        run: ./test/out/parser_test
+
+      - name: Configure property tests
+        run: cmake -S test -B test/property-out -DARIA_CSV_ENABLE_PROPERTY_TESTS=ON
+
+      - name: Build property tests
+        run: cmake --build test/property-out --parallel
+
+      - name: Run property tests
+        run: ./test/property-out/parser_property_test
+
+  fuzz-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build AFL-compatible harness
+        run: clang++ -std=c++11 -Wall -Wextra -pedantic -I. fuzz/afl_parser.cpp -o /tmp/aria_csv_afl_parser
+
+      - name: Build libFuzzer harness
+        run: clang++ -std=c++11 -Wall -Wextra -pedantic -I. -fsanitize=fuzzer,address,undefined fuzz/libfuzzer_parser.cpp -o /tmp/aria_csv_libfuzzer
+
+      - name: Configure CMake fuzz targets
+        run: cmake -S . -B /tmp/aria_csv_fuzz_build -DARIA_CSV_BUILD_FUZZERS=ON
+
+      - name: Build CMake AFL-compatible fuzz target
+        run: cmake --build /tmp/aria_csv_fuzz_build --target aria_csv_afl_fuzzer --parallel
+
+      - name: Run libFuzzer smoke test
+        run: |
+          mkdir -p /tmp/aria_csv_corpus
+          cp test/data/*.csv /tmp/aria_csv_corpus/
+          /tmp/aria_csv_libfuzzer /tmp/aria_csv_corpus -runs=1000
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build benchmark harnesses
+        run: |
+          clang++ -std=c++11 -Wall -Wextra -pedantic -I. -c benchmark/cpp/main.cpp -o /tmp/aria_csv_benchmark.o
+          clang++ -std=c++11 -Wall -Wextra -pedantic -I. -c benchmark/profile.cpp -o /tmp/aria_csv_profile.o
+          clang++ -std=c++11 -Wall -Wextra -pedantic -I. -c benchmark/optimize.cpp -o /tmp/aria_csv_optimize.o
+
+      - name: Run optimization harness smoke test
+        run: |
+          clang++ -std=c++11 -O2 -DNDEBUG -I. benchmark/optimize.cpp -o /tmp/aria_csv_optimize
+          /tmp/aria_csv_optimize 1 | tee /tmp/aria_csv_optimize_a.csv
+          /tmp/aria_csv_optimize 1 | tee /tmp/aria_csv_optimize_b.csv
+          python3 benchmark/compare_results.py /tmp/aria_csv_optimize_a.csv /tmp/aria_csv_optimize_b.csv

ARCHITECTURE.md

@@ -0,0 +1,131 @@
+# Architecture
+
+`CsvParser` is a small streaming parser. It reads bytes from a `std::istream`,
+keeps a fixed-size input buffer, and exposes parsed data through `next_field()`
+or the row iterator.
+
+## Main Pieces
+
+```text
++----------------------+     +----------------------+     +----------------------+
+| User code            |     | CsvParser            |     | std::istream         |
+|----------------------|     |----------------------|     |----------------------|
+| next_field()         | --> | parser state machine | --> | file/string/stdin    |
+| for (row : parser)   |     | input buffer         |     | borrowed or owned    |
+| position()           |     | field buffer         |     |                      |
++----------------------+     +----------------------+     +----------------------+
+```
+
+The parser can either borrow a stream or own one:
+
+```text
++----------------------+     +----------------------+
+| Borrowed stream      |     | Owned stream         |
+|----------------------|     |----------------------|
+| CsvParser(istream&)  |     | CsvParser(unique_ptr)|
+| caller owns stream   |     | parser owns stream   |
+| caller manages life  |     | safe for stored use  |
++----------------------+     +----------------------+
+```
+
+`CsvParser::from_file(path)` is a convenience wrapper around the owned-stream
+case.
+
+## Data Flow
+
+```text
++--------------+     +--------------+     +--------------+     +--------------+
+| input stream | --> | input buffer | --> | next_field() | --> | Field        |
+| read()       |     | 128 KiB      |     | CSV states   |     | DATA/ROW/END |
++--------------+     +--------------+     +--------------+     +--------------+
+                              |                   |
+                              |                   v
+                              |            +--------------+
+                              +----------> | field buffer |
+                                           | std::string  |
+                                           +--------------+
+```
+
+The row iterator is built on top of `next_field()`:
+
+```text
++--------------+     +--------------+     +----------------------+
+| next_field() | --> | iterator     | --> | vector<string> row   |
+| field events |     | row builder  |     | reused between rows  |
++--------------+     +--------------+     +----------------------+
+```
+
+## Parser States
+
+```text
++----------------+       quote        +-------------------+
+| START_OF_FIELD | -----------------> | IN_QUOTED_FIELD   |
++----------------+                    +-------------------+
+        |                                      |
+        | normal char                          | quote
+        v                                      v
++----------------+       delimiter    +-------------------+
+| IN_FIELD       | -----------------> | IN_ESCAPED_QUOTE  |
++----------------+                    +-------------------+
+        |                                      |
+        | newline                              | delimiter/newline
+        v                                      v
++----------------+                    +-------------------+
+| END_OF_ROW     | -----------------> | START_OF_FIELD    |
++----------------+                    +-------------------+
+```
+
+`EMPTY` is the terminal state after CSV end.
+
+## Field Scanning
+
+The state machine still owns the CSV rules. The scanner has a small optimization
+for ordinary field text: once it knows it is inside an unquoted or quoted field,
+it copies contiguous field characters as a range until the next structural
+character.
+
+```text
+Unquoted field:
+
+abc,def
+^^^
+copy chars until comma or row terminator
+
+Quoted field:
+
+"abc,def"
+ ^^^^^^^
+copy chars until quote
+```
+
+That is what the helper names mean:
+
+```text
+has_unquoted_field_chars()     more ordinary unquoted bytes are buffered
+append_unquoted_field_chars()  append them to the current field
+has_quoted_field_chars()       more quoted bytes are buffered
+append_quoted_field_chars()    append them to the current field
+```
+
+The optimization does not change the public API. It only avoids appending one
+character at a time when the next several bytes are known to be field contents.
+
+## Empty Lines
+
+An empty line is a row boundary, not an empty data field.
+
+```text
+Input bytes:        \n\n
+next_field():       ROW_END
+next_field():       ROW_END
+next_field():       CSV_END
+```
+
+An empty field still returns `DATA`:
+
+```text
+Input bytes:        ,
+next_field():       DATA("")
+next_field():       DATA("")
+next_field():       CSV_END
+```

CMakeLists.txt

@@ -1,8 +1,11 @@
-project(AriaCsvParser)
 cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+project(AriaCsvParser)
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 
+option(ARIA_CSV_BUILD_FUZZERS "Build parser fuzz targets" OFF)
+option(ARIA_CSV_BUILD_LIBFUZZER "Build the libFuzzer parser target" OFF)
+
 add_library(${PROJECT_NAME} INTERFACE)
 
 set_target_properties(${PROJECT_NAME} PROPERTIES
@@ -16,7 +19,8 @@ target_include_directories( ${PROJECT_NAME}
                 )
 
 install(TARGETS ${PROJECT_NAME}
-        EXPORT ${PROJECT_NAME}Targets)
+        EXPORT ${PROJECT_NAME}Targets
+        PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 
 install(EXPORT ${PROJECT_NAME}Targets
     NAMESPACE AriaCsvParser::
@@ -34,4 +38,8 @@ configure_package_config_file(Config.cmake.in
 install(FILES
     ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake
     DESTINATION lib/cmake/${PROJECT_NAME}
-    )
+    )
+
+if(ARIA_CSV_BUILD_FUZZERS)
+    add_subdirectory(fuzz)
+endif()

README.md

@@ -20,6 +20,23 @@ or you can read from `stdin`
 CsvParser parser(std::cin);
 ```
 
+The parser can also own the input stream, which is safer when the parser needs
+to outlive the scope where the stream is created.
+
+```cpp
+auto parser = CsvParser::from_file("some_file.csv");
+```
+
+or
+
+```cpp
+std::unique_ptr<std::istream> input(new std::ifstream("some_file.csv"));
+CsvParser parser(std::move(input));
+```
+
+When using the `std::istream&` constructor, the caller must keep the stream alive
+for at least as long as the parser.
+
 Moreover, you can configure the parser by chaining configuration methods like
 
 ```cpp
@@ -72,7 +89,7 @@ int main() {
     auto field = parser.next_field();
     switch (field.type) {
       case FieldType::DATA:
-        std::cout << *field.data << " | ";
+        std::cout << field.data << " | ";
         break;
       case FieldType::ROW_END:
         std::cout << std::endl;
@@ -92,4 +109,21 @@ reporting things like progress through a file. You can use
 
 ## Testing
 
-Run `cmake -B out && cmake --build out && ./out/parser_test` in test dir
+Run the unit tests with:
+
+```sh
+cmake -S test -B test/out
+cmake --build test/out
+./test/out/parser_test
+```
+
+Property tests are opt-in and use RapidCheck:
+
+```sh
+cmake -S test -B test/out -DARIA_CSV_ENABLE_PROPERTY_TESTS=ON
+cmake --build test/out
+./test/out/parser_property_test
+```
+
+Fuzz targets live in `fuzz/`. See `fuzz/README.md` for libFuzzer and AFL++
+commands.