# Conventions

## Language & Dependencies

- Target the latest stable Go release.
- **STRICT ALLOWLIST:** Only packages listed below may be imported. No exceptions.

### Approved Third-Party Packages

| Package | Use Case | Scope |
|---------|----------|-------|
| `github.com/goccy/go-yaml` | YAML parsing and AST inspection (subpkgs: `ast`, `parser`) | production |
| `github.com/google/go-cmp` | Test comparisons (`cmp.Diff`) | test only |

**Any import not in this table or the Go standard library is forbidden.**

Transitive dependencies of approved packages are automatically allowed.

To request a new dependency:
1. Open a PR that ONLY updates this table
2. Requires explicit approval from Aaron
3. After merge, a separate PR may use the package

*Enforcement: `scripts/check-deps.sh` parses this table — update only here.*

## Error Handling

- Return errors; never panic.
- Wrap errors with context using `fmt.Errorf("context: %w", err)`.
- Check all error returns.

## Testing

- Test every exported function.
- Use `net/http/httptest` for HTTP mocking.
- Table-driven tests where multiple inputs share the same assertion logic.
- Integration tests use build tags (`//go:build integration`).

## Style

- Keep functions short and focused.
- Prefer early returns over deep nesting.
- Meaningful variable names — no single-letter names outside loop indices.
- Comments explain *why*, not *what*.

## Process

- `go test ./...` must pass before commit.
- `go vet ./...` must pass before commit.
- Keep commits atomic and well-described.