CSVX Go Engine

The Go engine is the first implementation of the CSVX specification. It is intentionally specification-first: the engine must conform to CSVX behavior, but its internal architecture does not define the format.

Current scope

The initial package provides the Phase 1 foundation:

• CSVX ZIP package loading
• Manifest and workbook loading
• UTF-8 CSV sheet loading
• Optional .meta.json sheet metadata
• Typed metadata structures for columns, formulas, caches, styles, and validation
• Sparse cell metadata addressed by A1 coordinates
• Duplicate and unsafe ZIP entry rejection
• Package and extract CLI commands for developer workflows

Formula parsing, calculation, import/export, and full CLI operations will be added behind the same canonical workbook model. Package writing and extract/package round-trip support are now available for developer workflows.

Development rule

Each capability follows this sequence:

Specify → create conformance fixtures → implement → run tests

The specification repository is the authority:

../csvx-spec/

Package

workbook, err := csvx.Open("report.csvx")
if err != nil {
    return err
}
fmt.Println(workbook.Sheets[0].Records)

CSV is the canonical sheet data layer. Metadata that CSV cannot represent is stored in the matching .meta.json sidecar.

Commands

Run commands from the repository root:

Format

gofmt -w .

Formats all Go source files before committing.

Build

go build ./...

Builds every package in the module.

To build the CLI once it is added:

go build -o bin/csvx ./cmd/csvx

Test

go test ./...

Runs all unit and package tests.

Run tests with the race detector:

go test -race ./...

Run a specific test:

go test -run TestLoadCSVBackedWorkbook ./...

Coverage

go test -cover ./...
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Static analysis

go vet ./...

Run the CLI

Build the current CLI:

go build -o bin/csvx ./cmd/csvx

The currently supported commands are:

csvx --help
csvx version
csvx inspect report.csvx
csvx inspect ../csvx-spec/examples/minimal.csvx
csvx validate report.csvx
csvx validate ../csvx-spec/examples/minimal.csvx
csvx validate --json ../csvx-spec/examples/minimal.csvx
csvx package ../csvx-spec/examples/minimal.csvx --output minimal.csvx
csvx extract minimal.csvx --output minimal-extracted
csvx xlsx-inspect ../csvx-spec/examples/example.xlsx
csvx xlsx-inspect --json ../csvx-spec/examples/example.xlsx

Both .csvx ZIP files and unpacked CSVX package directories are accepted. The following commands are planned but not implemented yet:

csvx recalc report.csvx
csvx convert report.xlsx report.csvx
csvx convert report.csvx report.xlsx
csvx convert report.csvx report.csv

Dependency and module maintenance

go mod tidy
go list -m all
go version

go mod tidy should be run when imports change. Review its changes before committing.

Development workflow

1. Update the relevant specification in ../csvx-spec/.
2. Add or update a conformance fixture.
3. Implement the behavior in the engine.
4. Run gofmt, go vet, and go test ./....
5. Document any intentionally unsupported behavior.
6. Confirm that CSV data and metadata sidecars remain round-trip safe.

Do not treat engine behavior as a specification change without updating the specification repository.