# CLAUDE.md

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

## Project Overview

This is the CUE language repository. CUE (Configure, Unify, Execute) is a general-purpose, strongly typed constraint-based language for data templating, validation, code generation, and scripting.

## Common Development Commands

### Running the "cue" command

```bash
# Build and run ./cmd/cue via a cached binary
go tool cue

# Or build and install it in $PATH.
go install ./cmd/cue
```

### Testing

```bash
# Run all tests
# Any change to the repo should run all tests to ensure correctness.
go test ./...

# Run tests for a specific package
go test ./internal/core/adt

# Run a specific test function
go test -run TestEvalV3 ./internal/core/adt

# Run a specific sub-test
go test -run TestScript/eval_concrete ./cmd/cue/cmd

# Update golden test files (when output changes are expected)
CUE_UPDATE=1 go test ./...

# Run tests with race detector
go test -race ./...
```

### Code Quality

```bash
# Run go vet (catches common mistakes)
go vet ./...

# Run staticcheck (more comprehensive static analysis)
go tool -modfile=internal/tools.mod staticcheck ./...

# Format code (CUE uses standard Go formatting)
go fmt ./...
```

## Code Architecture

### Core Language Implementation
- `/cue/` - Core CUE language implementation
  - `ast/` - Abstract Syntax Tree
  - `parser/` - Language parser
  - `load/` - Package loading and imports
  - `format/` - Code formatting
- `/internal/core/` - Core evaluation engine
  - `adt/` - Core data structures and algorithms
  - `compile/` - Compilation logic
  - `dep/` - Dependency analysis
  - `export/` - Export functionality

### Command-Line Tool
- `/cmd/cue/` - CLI implementation for all CUE commands (eval, export, import, fmt, vet, mod, etc.)

### Standard Library
- `/pkg/` - Built-in packages (crypto, encoding, math, net, path, strings, etc.)

### Format Support
- `/encoding/` - Encoders/decoders for JSON, YAML, TOML, Protobuf, OpenAPI, JSON Schema

### Testing Infrastructure
- **Test Format**: Uses `.txtar` (text archive) files containing input files and expected outputs
- **Test Organization**: Unit tests alongside code (`*_test.go`), integration tests in `testdata/` directories
- **Testscript Framework**: Command-line integration tests in `/cmd/cue/cmd/testdata/script/`

## Key Development Patterns

### Working with Tests
- Tests use the `.txtar` format which contains both input and expected output in a single file
- Use `TestX` functions in test files for debugging individual test cases
- The `CUE_UPDATE=1` environment variable updates golden files with actual output
- Prefer adding test cases to an existing txtar file that is appropriate for the type of reproducer

### Contribution Model
- Single commit per PR/CL model
- Uses `git codereview` workflow for managing changes
- Runs `cueckoo runtrybot [CL|commit]` to kick off CI testing.
- Requires DCO (Developer Certificate of Origin) sign-off
- Both GitHub PRs and GerritHub CLs are supported
- Changes should be linked to a GitHub issue (except trivial changes)

### Module Information
- Module: `cuelang.org/go`
- Requires Go 1.25 or later
- Uses Go modules for dependency management

### Important Conventions
- Don't update copyright years in existing files
- Follow existing code style and patterns in the package you're modifying
- Check neighboring files for framework choices and conventions
- Use existing libraries and utilities rather than assuming new dependencies

## Rules to follow

These rules MUST be followed at all times:
- Do not use commands like `cat` to read or write files; read and write files directly
- Do not write to temporary folders like /tmp; place all temporary files under the current directory
- Do not use env vars like CUE_DEBUG for debug prints; print unconditionally, and remove them when done
- Do not "go build" binaries; use commands like "go tool cue" or "go run ./cmd/cue" instead
- When adding a regression test for a bug fix, ensure that the test fails without the fix
