Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (57 loc) · 3.92 KB

AGENTS.md

File metadata and controls

75 lines (57 loc) · 3.92 KB
Raw

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
go build -o ./cmd/shutter/shutter ./cmd/shutter  # 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)                              │
│  └─ 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
  • Execution order: Ignore patterns run first, then scrubbers

Module Structure

  • Root module (go.mod): Main library and TUI - Go 1.24.0+
  • Root module: Library and TUI dependencies; lazy module loading keeps the TUI optional for library consumers
  • /editor/tree-sitter-snapshot/: Tree-sitter grammar for snapshot format (Node.js/Rust/Python/Swift bindings)