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

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.

SECURITY.md

@@ -0,0 +1,41 @@
+# Security Notes
+
+This parser is intended to be small, streaming, and dependency-free. It now
+supports both borrowed and owned input streams.
+
+## Stream Lifetime
+
+`CsvParser(std::istream &)` borrows the stream. The caller must keep that stream
+alive for the full lifetime of the parser.
+
+For stored parsers or parser objects that outlive a local stream variable, use an
+owned stream:
+
+```cpp
+auto parser = aria::csv::CsvParser::from_file("data.csv");
+```
+
+or:
+
+```cpp
+std::unique_ptr<std::istream> input(new std::ifstream("data.csv"));
+aria::csv::CsvParser parser(std::move(input));
+```
+
+The owning constructor rejects null streams and failed streams.
+
+## Untrusted Input
+
+The parser is permissive by design. It does not currently reject malformed CSV
+such as unclosed quotes. For untrusted data pipelines that require validation,
+add a strict parsing layer or a future strict mode rather than relying on
+permissive parsing as validation.
+
+The parser stores the current field in memory. Very large fields can therefore
+consume large amounts of memory. Applications that accept untrusted CSV should
+enforce input-size limits at the application or stream layer.
+
+## Fuzzing
+
+Fuzz harnesses are available under `fuzz/` for libFuzzer and AFL++ style runs.
+Use them with ASan/UBSan when changing parser control flow.

benchmark/OPTIMIZATION.md

@@ -0,0 +1,127 @@
+# Optimization Workflow
+
+The goal is to make the parser faster without letting the implementation turn
+into clever, brittle code. Every optimization should carry both a speed result
+and a readability/maintenance result.
+
+## Baseline
+
+Build the optimization harness with release flags:
+
+```sh
+clang++ -std=c++11 -O2 -DNDEBUG -g -fno-omit-frame-pointer \
+  benchmark/optimize.cpp -I. -o /tmp/aria_csv_optimize
+```
+
+Run a baseline:
+
+```sh
+/tmp/aria_csv_optimize 7 | tee benchmark/baseline.csv
+```
+
+The harness prints CSV:
+
+```text
+workload,mode,bytes,iterations,best_ms,mb_per_s,checksum
+```
+
+Use the best time across iterations to reduce scheduler noise. Re-run the
+baseline before comparing a change if the machine load changed noticeably.
+
+## Workloads
+
+The harness generates four in-memory workloads:
+
+- `plain`: common unquoted rows with many ordinary fields.
+- `quoted`: quoted fields, escaped quotes, commas, and embedded newlines.
+- `wide`: many small columns per row.
+- `huge-fields`: fields larger than the parser's input buffer.
+
+Each workload runs through both public APIs:
+
+- `fields`: direct `next_field()` parsing.
+- `rows`: range iteration over rows.
+
+## Change Gate
+
+For each optimization, record:
+
+- the exact code change
+- baseline and after numbers
+- percent speed change per workload
+- test/fuzz/property status
+- readability score
+- decision: keep, revise, or revert
+
+Suggested readability score:
+
+- `1`: simpler than before
+- `2`: same complexity
+- `3`: slightly more complex but local and well named
+- `4`: noticeably harder to maintain
+- `5`: too clever for this project
+
+Default policy: keep only changes that improve at least one target workload by
+5% or more, do not regress any major workload by more than 2%, and score `3` or
+better on readability.
+
+Compare two runs with:
+
+```sh
+python3 benchmark/compare_results.py benchmark/baseline.csv benchmark/after.csv
+```
+
+The comparison script also checks that workload checksums did not change. A
+checksum change means the parser behavior changed or the benchmark changed, so
+the result is not a pure performance comparison.
+
+## Verification
+
+Before keeping a performance change, run:
+
+```sh
+cmake -S test -B /tmp/aria_csv_test
+cmake --build /tmp/aria_csv_test --parallel
+/tmp/aria_csv_test/parser_test
+
+cmake -S test -B /tmp/aria_csv_property -DARIA_CSV_ENABLE_PROPERTY_TESTS=ON
+cmake --build /tmp/aria_csv_property --parallel
+/tmp/aria_csv_property/parser_property_test
+
+clang++ -std=c++11 -Wall -Wextra -pedantic -I. \
+  -fsanitize=fuzzer-no-link,address,undefined \
+  -c fuzz/libfuzzer_parser.cpp -o /tmp/aria_csv_libfuzzer.o
+```
+
+Run the sampling profiler when a change meaningfully moves benchmark numbers:
+
+```sh
+clang++ -std=c++11 -O2 -g -fno-omit-frame-pointer \
+  benchmark/profile.cpp -I. -o /tmp/aria_csv_profile
+
+/tmp/aria_csv_profile benchmark/sample.csv 8000 &
+pid=$!
+sample "$pid" 3 1 -file /tmp/aria_csv_profile.sample.txt
+wait "$pid"
+```
+
+## Decision Record Template
+
+```md
+## YYYY-MM-DD: <change name>
+
+Hypothesis:
+
+Change:
+
+Benchmark:
+
+| workload | mode | baseline MB/s | after MB/s | delta |
+| --- | --- | ---: | ---: | ---: |
+
+Verification:
+
+Readability score:
+
+Decision:
+```

benchmark/PROFILING.md

@@ -0,0 +1,34 @@
+# Profiling
+
+The profiling driver keeps file I/O out of the hot path by reading the CSV once
+and reparsing the in-memory contents repeatedly. Build it with frame pointers and
+debug symbols so sampling profilers can produce useful call trees.
+
+## macOS sample
+
+```sh
+clang++ -std=c++11 -O2 -g -fno-omit-frame-pointer \
+  benchmark/profile.cpp -I. -o /tmp/aria_csv_profile
+
+/tmp/aria_csv_profile benchmark/sample.csv 100000 &
+pid=$!
+sample "$pid" 5 1 -file /tmp/aria_csv_profile.sample.txt
+wait "$pid"
+```
+
+The `sample` output is a call-tree profile that can be folded into flamegraph
+input with stackcollapse tools, or inspected directly for the hottest parser
+frames.
+
+## Linux perf
+
+```sh
+clang++ -std=c++11 -O2 -g -fno-omit-frame-pointer \
+  benchmark/profile.cpp -I. -o /tmp/aria_csv_profile
+
+perf record -F 997 -g -- /tmp/aria_csv_profile benchmark/sample.csv 100000
+perf report
+```
+
+For SVG flamegraphs, run Brendan Gregg's `stackcollapse-perf.pl` and
+`flamegraph.pl` on `perf script` output.