CSV-Blueprint: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

CSV Blueprint is a CLI tool for validating CSV files based on customizable YAML schemas. It provides over 330+ validation rules that can be applied to individual cells or entire columns, with support for parallel processing and multiple output formats.

Core Architecture

The project follows a modular architecture with clear separation of concerns:

• CLI Layer: src/Commands/ - Command classes for different operations (ValidateCsv, CreateSchema, etc.)
• Schema Engine: src/Schema.php - Core schema definition and parsing
• Validation Rules: src/Rules/ - Two types of validation rules:
  • Cell/ - Individual cell validation rules (~90 rules)
  • Aggregate/ - Column-wide aggregate validation rules (~44 rules)
• CSV Processing: src/Csv/ - CSV file handling and column management
• Workers: src/Workers/ - Parallel processing implementation
• Validators: src/Validators/ - Validation orchestration and error reporting

Key Components

• Schema Definition: YAML-based schemas define validation rules for CSV columns
• Rule System: Extensible rule system with AbstractRule base class
• Error Reporting: Multiple output formats (table, text, GitHub Actions, etc.)
• Parallel Processing: Multi-threaded validation for large files
• CLI Interface: Built with Symfony Console components

Team Collaboration & Use Cases

Contract-Based Workflow

CSV Blueprint schemas serve as a data contract between teams (similar to Swagger/OpenAPI for APIs). Recommended approach: maintain schemas and fixtures in a dedicated repository shared between Data Engineers and Backend Engineers.

Recommended schema repository structure:

schemas/
  ├── exports/           # Schemas for outgoing data
  │   └── *.yml
  └── imports/           # Schemas for incoming data
      └── *.yml
fixtures/
  └── *.csv              # Sample files for testing