If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/JoshClose/CsvHelper shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 11mo ago

• Last commit 11mo ago
• 15 active contributors
• Other licensed
• CI configured
• ⚠ Slowing — last commit 11mo ago
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live JoshClose/CsvHelper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JoshClose/CsvHelper.

What it runs against: a local clone of JoshClose/CsvHelper — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in JoshClose/CsvHelper | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 346 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JoshClose/CsvHelper. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JoshClose/CsvHelper.git
#   cd CsvHelper
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of JoshClose/CsvHelper and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "JoshClose/CsvHelper(\\.git)?\\b" \\
  && ok "origin remote is JoshClose/CsvHelper" \\
  || miss "origin remote is not JoshClose/CsvHelper (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CsvHelper.sln" \\
  && ok "CsvHelper.sln" \\
  || miss "missing critical file: CsvHelper.sln"
test -f ".github/workflows/ci.yaml" \\
  && ok ".github/workflows/ci.yaml" \\
  || miss "missing critical file: .github/workflows/ci.yaml"
test -f "GitVersion.yml" \\
  && ok "GitVersion.yml" \\
  || miss "missing critical file: GitVersion.yml"
test -f "README.markdown" \\
  && ok "README.markdown" \\
  || miss "missing critical file: README.markdown"
test -f "docs-src/CsvHelper.DocsGenerator/Program.cs" \\
  && ok "docs-src/CsvHelper.DocsGenerator/Program.cs" \\
  || miss "missing critical file: docs-src/CsvHelper.DocsGenerator/Program.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 346 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~316d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/JoshClose/CsvHelper"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

CsvHelper is a high-performance .NET library for reading and writing CSV files with automatic type conversion and custom class object mapping. It handles RFC 4180 CSV parsing with pluggable formatters, type converters, and class maps to bind CSV columns to strongly-typed C# properties—eliminating boilerplate for common data import/export workflows. Monolithic solution structure (CsvHelper.sln) with a core library (inferred from 1.5M C# LOC and single top-level project), documentation generator in docs-src/CsvHelper.DocsGenerator/ (with reflection-based Infos/, Generators/, and Formatters subdirectories for HTML/XML doc extraction), and published static docs in docs/ built via build-docs.cmd.

.NET developers (C# primarily) building data pipelines, ETL processes, or applications that need to ingest/export CSV data without manual parsing; particularly those working with enterprise systems, data migrations, or reporting features who want type-safe, high-throughput CSV handling.

Production-ready and actively maintained. The repo shows extensive CI/CD via .github/workflows/ (ci.yaml, publish.yaml, git-version.yaml), comprehensive test coverage expectations per CONTRIBUTING.md, and dual licensing (MS-PL/Apache 2.0). Recent GitHub Actions pipelines and open collective sponsorships (including AWS FOSS backing) indicate continued investment.

Low risk for established use cases; single maintainer (JoshClose) is the primary author, which could slow response on edge cases. The codebase is stable (~1.5M LOC C#) with no obvious dependency bloat visible in the file list. Main risk: breaking changes between major versions—check the changelog before upgrading if you rely on internal APIs or undocumented behavior.

Active maintenance with GitHub Actions workflows for CI, GitVersion-based semantic versioning, and NuGet package publishing. The presence of FUNDING.yml, Open Collective integration, and AWS FOSS sponsorship badge suggest ongoing feature parity and production stabilization work, though specific PR/milestone details are not visible in the file list.

Clone and build: git clone https://github.com/JoshClose/CsvHelper.git && cd CsvHelper && dotnet build CsvHelper.sln. Run tests via dotnet test. View docs locally by running build-docs.cmd (Windows batch file) or examine docs/ folder for published HTML documentation.

Daily commands: This is a library, not an application. For development: dotnet build CsvHelper.sln compiles the library. For documentation: run build-docs.cmd on Windows. To use in a project: dotnet add package CsvHelper or NuGet Package Manager Install-Package CsvHelper.

• CsvHelper.sln — Master solution file defining all projects and build configuration; essential entry point for understanding project structure.
• .github/workflows/ci.yaml — CI/CD pipeline defining automated testing and validation; critical for understanding code quality gates and deployment process.
• GitVersion.yml — Semantic versioning configuration; controls version assignment for releases and package distribution.
• README.markdown — Primary documentation and project mission statement; defines the library's purpose, installation, and documentation links.
• docs-src/CsvHelper.DocsGenerator/Program.cs — Documentation generation entry point; demonstrates how API docs are automatically generated from the codebase.

• CsvReader (TextReader, IEnumerable, ClassMap) — Parses CSV text from stream, yields individual records as string arrays or strongly-typed objects
  • Failure mode: Malformed CSV (unclosed quotes, incorrect delimiters) → parsing exception; missing columns → null reference
• CsvWriter (TextWriter, IEnumerable, ClassMap) — Serializes .NET objects to CSV text stream, applies quoting/escaping rules, manages headers
  • Failure mode: Invalid type conversion (object type not supported) → converter exception; stream closed → I/O exception
• ClassMap / ClassMap<T> (Reflection, Expression trees) — Declarative mapping rules between CSV columns and object properties; supports auto-mapping, custom converters, validation
  • Failure mode: Missing required properties → validation error; circular class references → infinite recursion
• TypeConverter (ITypeConverter interface, CultureInfo) — Converts between CSV string values and .NET types; extensible for custom types
  • Failure mode: Unsupported type or invalid string format → conversion exception with source value in message
• CsvConfiguration (CultureInfo, Encoding, fluent builder pattern) — Global settings for delimiter, encoding, quote handling, culture; applies to all readers/writers in scope
  • Failure mode: Incompatible settings (e.g., null delimiter) → runtime exception; locale mismatch → incorrect number/date parsing

• Developer code → CsvReader/CsvWriter — Creates reader/writer with TextReader/TextWriter and optional ClassMap<T>
• CsvReader → CSV text stream — Reads line-by-line from file or network stream
• CSV parser → ClassMap resolver — Parsed CSV row (string array) matched against column mappings
• ClassMap + TypeConverter → Object instance — String values converted to .NET types, assigned to object properties

Add a new class mapping configuration example

1. Create a new markdown or HTML file in docs/examples/configuration/class-maps/ with your example scenario (docs/examples/configuration/class-maps/[feature-name]/index.html)
2. Document the mapping configuration using CsvHelper's fluent ClassMap API (docs/examples/configuration/class-maps/[feature-name]/index.html)
3. Add a link to your new example in the class-maps index page (docs/examples/configuration/class-maps/index.html)
4. Regenerate documentation using build-docs.cmd to integrate into the site (build-docs.cmd)

Add a new reading/writing example

1. Create example directory in docs/examples/reading/ or docs/examples/writing/ with scenario name (docs/examples/reading/[scenario-name]/index.html)
2. Provide code sample showing CsvReader or CsvWriter usage for your use case (docs/examples/reading/[scenario-name]/index.html)
3. Link from the parent reading/writing index page (docs/examples/reading/index.html)
4. Run build-docs.cmd to regenerate and validate the documentation site (build-docs.cmd)

Update version and release new NuGet package

1. Update GitVersion.yml with new major/minor/patch version targets (GitVersion.yml)
2. Commit changes to master branch; git-version.yaml workflow auto-tags the commit (.github/workflows/git-version.yaml)
3. Tag triggers publish.yaml workflow which builds and publishes to NuGet.org (.github/workflows/publish.yaml)
4. Verify package appears at https://www.nuget.org/packages/CsvHelper (README.markdown)

• .NET/C# (multi-target framework) — CsvHelper is a .NET library, so the entire codebase is C#; multi-targeting ensures compatibility with .NET Framework, .NET Core, and .NET 5+
• GitHub Actions CI/CD — Provides native integration with GitHub repos for automated build, test, and NuGet publication workflows without external CI services
• GitVersion semantic versioning — Automates version calculation from git tags and branch conventions, eliminating manual version bumping errors
• XML documentation comments + code generator — Extracts XML docs from source code and auto-generates HTML API reference, keeping docs synchronized with code

• Auto-generated documentation from XML comments

  • Why: Ensures documentation always matches code; no stale docs
  • Consequence: Documentation quality depends on developer discipline writing clear XML comments; cannot add freeform narrative as easily

• Dual licensing (MS-PL)

  • Why: Allows broad adoption in both open-source and proprietary projects
  • Consequence: Complexity for users who need to comply with license terms; less restrictive than GPL but more complex than MIT

• Separate docs-src generator rather than inline wiki

  • Why: Produces professional HTML API docs that mirror .NET's own documentation style
  • Consequence: Adds build step complexity; requires running build-docs.cmd to preview changes locally

• Does not support binary or proprietary CSV variants; strictly RFC 4180 compliant text format
• Does not provide real-time streaming CSVs over HTTP/WebSocket; file-based only
• Does not include database connectors or ORM integration; CSV ↔ object mapping only
• Does not validate CSV schemas or enforce data quality constraints at parse time

No env vars or external services required for local development—just .NET SDK. Windows batch file for docs (build-docs.cmd)—use WSL or cross-platform alternative on Linux/Mac if needed. ReSharper dotsettings included (inferred from CONTRIBUTING.md); recommend using ReSharper or Rider to auto-format, or manually match existing code style to pass PR review. Single-commit PR requirement is strict—squash before submitting. XML comment documentation required for public APIs—missing docs may block doc generation.

• RFC 4180 CSV Specification — CsvHelper implements RFC 4180 compliance for CSV parsing/writing; understanding the spec (quoted fields, escape sequences, CRLF handling) is essential to predict edge case behavior and contribute parser fixes.
• Type Conversion & Type Converters — CsvHelper's core power is mapping CSV strings to .NET types via pluggable ITypeConverter interface; learning how custom converters work is key to extending the library for domain-specific types (dates, enums, UUIDs, etc.).
• Class Mapping & Reflection-Based ORM — CsvHelper uses reflection to bind CSV column headers/indices to C# class properties via ClassMap<T>; understanding how property detection, naming conventions, and type binding work is necessary for custom mapping logic.
• Streaming & Memory-Efficient Parsing — CsvHelper is optimized for large files via forward-only streaming (not loading entire CSV into memory); understanding buffering, record enumeration, and reader state is critical for performance tuning and contributing optimization PRs.
• XML Documentation Comments & Reflection-Based Doc Generation — The docs-src/CsvHelper.DocsGenerator/ tool auto-extracts XML comments via .NET reflection to generate static HTML docs; contributing to CsvHelper requires writing proper XML doc comments (/// summary, /// param, /// remarks) for all public APIs.
• Semantic Versioning & GitVersion-Based Release Automation — CsvHelper uses GitVersion (configured in GitVersion.yml) for automatic version bumping and NuGet publishing via CI/CD; understanding SemVer and how commit messages drive versions helps maintainers and users track breaking changes.
• Culture & Locale-Aware Formatting — CSV parsing must handle locale-specific formats (decimal separators, date formats, currency); CsvHelper provides culture awareness in type converters—important for international data pipelines and understanding why hardcoded format strings fail.

• ServiceStack/ServiceStack.Text — Alternative .NET CSV and data serialization library; direct competitor with different API design and philosophy.
• microsoft/CsvParser — Microsoft's lightweight CSV parser; reference for standards compliance and comparison of feature scope vs. CsvHelper's richness.
• frankhale/machine.specifications — Testing framework commonly used in .NET open-source projects; relevant for understanding test patterns if CsvHelper uses BDD-style assertions.
• dotnet/runtime — Core .NET runtime and BCL; CsvHelper depends on standard .NET APIs and may track breaking changes or new type converter opportunities in each release.
• xunit/xunit — Popular unit testing framework in .NET ecosystem; likely test harness for CsvHelper's test suite based on CONTRIBUTING.md emphasis on comprehensive tests.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for CsvHelper.DocsGenerator

The docs-src/CsvHelper.DocsGenerator directory contains critical documentation generation logic (AssemblyGenerator, TypeGenerator, NamespaceGenerator, etc.) but there's no visible test project for this subsystem. This is high-value because broken documentation generation would go undetected, and contributors modifying these generators need test coverage to ensure correctness.

• [ ] Create a new test project (e.g., CsvHelper.Tests.DocsGenerator) parallel to docs-src/CsvHelper.DocsGenerator
• [ ] Add unit tests for docs-src/CsvHelper.DocsGenerator/Generators/ classes covering basic generation, edge cases, and XML doc parsing
• [ ] Add unit tests for docs-src/CsvHelper.DocsGenerator/Formatters/ (HtmlFormatter, XmlDocFormatter) to ensure output format consistency
• [ ] Integrate test project into CsvHelper.sln and CI/CD pipeline (.github/workflows/ci.yaml)

Implement automated API documentation validation in CI pipeline

The repo has docs-src/CsvHelper.DocsGenerator tooling and a docs/ output folder, but .github/workflows/ci.yaml likely doesn't verify that generated documentation is up-to-date or properly built. This prevents stale API docs from being committed, which is critical for a library where users rely on accurate API references.

• [ ] Review current .github/workflows/ci.yaml to identify missing documentation build steps
• [ ] Add a CI workflow step that runs CsvHelper.DocsGenerator and compares output against committed docs/ folder
• [ ] Configure the workflow to fail if docs are out-of-sync with source code, forcing contributors to regenerate
• [ ] Document the process in README.markdown under a 'Contributing' section

Add end-to-end integration tests for real-world CSV scenarios

While the file structure suggests unit tests exist, there's no visible integration test folder that validates CSV parsing/writing across complex real-world scenarios (e.g., quoted fields with newlines, escaped delimiters, BOM handling, encoding edge cases). This catches regressions that unit tests miss and builds confidence for library users.

• [ ] Create tests/CsvHelper.Tests.Integration/ directory with test CSV files in tests/data/ (malformed CSVs, Unicode files, large files, RFC 4180 edge cases)
• [ ] Write integration tests validating round-trip parsing and writing of these CSV files
• [ ] Add tests for configuration scenarios documented in docs/examples/configuration/ (class-maps, attributes, custom converters)
• [ ] Integrate into ci.yaml workflow to run on every commit

• Add type converter tests for edge cases in CSV parsing (e.g., null values, empty strings, locale-specific decimal separators) in whichever test project handles type converters—check CONTRIBUTING.md for test structure and add regression tests for any reported converter bugs.
• Expand documentation HTML formatter in docs-src/CsvHelper.DocsGenerator/Formatters/HtmlFormatter.cs to include examples and usage patterns for each public type—mirror the pattern in XmlDocFormatter.cs and ensure generated docs reference real use-case snippets.
• Add integration tests for RFC 4180 edge cases (quoted fields, escaped quotes, CRLF vs LF line endings) to ensure compliance—structure per CONTRIBUTING.md (1 test per behavior) and verify the main reader/writer handles all spec variants correctly.

CsvHelper is a well-maintained open-source CSV parsing library with a solid security posture. No critical vulnerabilities were identified in the analyzed file structure. The codebase follows standard .NET library conventions with documented configuration and CI/CD pipeline through GitHub Actions. Minor recommendations include implementing security headers for the documentation site and ensuring proper error handling in the documentation generation tools. As a parsing library focused on CSV operations, SQL injection and XSS risks are minimal since it primarily handles data transformation rather than direct database or web interactions. Dependencies should be regularly updated through NuGet package management (standard practice not visible in provided files but recommended).

• Low · Missing Security Headers in Documentation — docs/ directory and .github/workflows/publish.yaml. The docs directory appears to be hosted as a static site without explicit security header configuration visible. Documentation sites should include security headers like Content-Security-Policy, X-Content-Type-Options, and X-Frame-Options. Fix: Configure security headers in the hosting platform (GitHub Pages, CDN, or web server). Add a _headers file or configure the hosting provider to include security headers.
• Low · Potential Information Disclosure via Error Details — docs-src/CsvHelper.DocsGenerator/. The DocsGenerator tool processes and outputs API documentation, which while useful, could inadvertently expose internal implementation details if error handling or validation is insufficient. Fix: Ensure proper validation and sanitization of input data in the DocsGenerator. Implement error handling that doesn't expose stack traces or sensitive information in generated documentation.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.