CLAUDE.md#

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

Project Overview#

Shutter is a snapshot testing library for Go, inspired by Rust's insta and Gleam's birdie. It provides functions for capturing test output as snapshots and tools for reviewing snapshot changes.

Build Commands#

# Build the TUI binary
just build

# Run tests with coverage
just test

# Clean snapshots and run tests
just clean-test

# Run the TUI review tool (after building)
just review

# Run CLI review tool
just cli

Direct Go commands:

go test ./...                                    # Run all tests
go test ./... -run TestName                      # Run specific test
go test -v ./internal/transform/...              # Run tests in specific package
cd ./cmd/shutter && go build -o shutter ./main.go  # Build TUI

Architecture#

┌─────────────────────────────────────────────────────────────────┐
│  Public API (shutter.go)                                        │
│  Snap() | SnapMany() | SnapString() | SnapJSON()                │
├─────────────────────────────────────────────────────────────────┤
│  Options (scrubbers.go, ignore.go)                              │
│  Scrubbers: text transformation before snapshot                 │
│  IgnorePatterns: field removal (SnapJSON only)                  │
├─────────────────────────────────────────────────────────────────┤
│  Internal Modules                                               │
│  ├─ internal/snapshots/ - Core comparison logic                 │
│  ├─ internal/files/     - Snapshot file I/O (YAML headers)      │
│  ├─ internal/transform/ - JSON ignore pattern application       │
│  ├─ internal/diff/      - Histogram diff algorithm              │
│  ├─ internal/pretty/    - Formatting and display boxes          │
│  └─ internal/review/    - Review workflow logic                 │
├─────────────────────────────────────────────────────────────────┤
│  Review Tools                                                   │
│  ├─ cmd/shutter/ - TUI (Bubbletea) - separate go.mod            │
│  └─ cmd/cli/     - CLI review tool                              │
└─────────────────────────────────────────────────────────────────┘

Data flow: Test Value → Pretty format (utter) → Ignore Patterns → Scrubbers → Snapshot file

Snapshot storage: __snapshots__/ directories contain YAML-header files with metadata (title, test_name, file_name, version) followed by --- delimiter and content.

Key Design Decisions#

Option interface pattern: Scrubber and IgnorePattern both implement Option for type-safe compile-time separation
IgnorePatterns only work with SnapJSON() - using them with Snap/SnapMany/SnapString returns an error
TUI is a separate Go module (cmd/shutter/) to keep Bubbletea dependencies optional
Execution order: Ignore patterns run first, then scrubbers

Module Structure#

Root module (go.mod): Main library - Go 1.23.12+
TUI module (cmd/shutter/go.mod): Separate module with Bubbletea dependencies - Go 1.25.2
/editor/tree-sitter-snapshot/: Tree-sitter grammar for snapshot format (Node.js/Rust/Python/Swift bindings)

Configure Feed