294 lines
10 KiB
Markdown
294 lines
10 KiB
Markdown
# Go Jdenticon - Development Guide for Claude Code
|
||
|
||
## Project Overview
|
||
|
||
Go Jdenticon is a Go library for generating highly recognizable identicons - geometric avatar images generated deterministically from any input string. This is a Go port of the JavaScript library [Jdenticon](https://github.com/dmester/jdenticon).
|
||
|
||
**Critical Achievement**: This implementation maintains **byte-for-byte identical SVG output** with the JavaScript reference implementation through careful algorithm replication.
|
||
|
||
## Key Features
|
||
|
||
- Renders identicons as PNG or SVG with no external dependencies
|
||
- Generates consistent, deterministic identicons from any input string
|
||
- Highly customizable color themes and styling options
|
||
- Command-line tool included for standalone usage
|
||
- **JavaScript reference compatibility** - produces identical output to the original JavaScript library
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
go-jdenticon/
|
||
jdenticon/ # Public API package
|
||
config.go # Public configuration options
|
||
generate.go # Main API functions
|
||
hash.go # Hash computation and parsing
|
||
reference_test.go # JavaScript compatibility tests
|
||
internal/
|
||
engine/ # Core generation logic
|
||
generator.go # Main generation algorithm (CRITICAL FILE)
|
||
shapes.go # Shape rendering with transforms
|
||
color.go # Color theme generation
|
||
config.go # Internal configuration
|
||
layout.go # Grid layout system
|
||
transform.go # Coordinate transformations
|
||
renderer/ # Output rendering
|
||
renderer.go # Base renderer interface
|
||
svg.go # SVG output (maintains z-order!)
|
||
png.go # PNG output using Go imaging
|
||
cmd/jdenticon/ # Command-line tool
|
||
jdenticon-js/ # JavaScript reference implementation
|
||
example_usage.go # Demo and testing
|
||
```
|
||
|
||
## Build & Test Commands
|
||
|
||
```bash
|
||
# Run all tests
|
||
go test ./jdenticon ./internal/...
|
||
|
||
# Run specific test packages
|
||
go test ./jdenticon
|
||
go test ./internal/engine
|
||
go test ./internal/renderer
|
||
|
||
# Run JavaScript compatibility tests (CRITICAL)
|
||
go test ./jdenticon -run TestJavaScriptReferenceCompatibility
|
||
|
||
# Build command-line tool
|
||
go build -o jdenticon cmd/jdenticon/main.go
|
||
|
||
# Generate demo avatars
|
||
go run example_usage.go
|
||
|
||
# Quick test with visualization
|
||
go run quick_test.go
|
||
```
|
||
|
||
## Core Algorithm Architecture
|
||
|
||
### Generation Flow (internal/engine/generator.go)
|
||
|
||
The generation algorithm follows this exact sequence to match JavaScript:
|
||
|
||
1. **Hash Parsing**: Extract values from specific positions in SHA1 hash
|
||
- Positions 2,3: Side shape selection
|
||
- Positions 4,5: Corner shape selection
|
||
- Position 1: Center shape selection
|
||
- Position 0: Main hue value
|
||
|
||
2. **Shape Selection**: Use hard-coded position arrays (NOT layout engine)
|
||
```go
|
||
positions := [][]int{{1, 0}, {2, 0}, {2, 3}, {1, 3}, {0, 1}, {3, 1}, {3, 2}, {0, 2}}
|
||
```
|
||
|
||
3. **Color Generation**: Create theme colors from hue with specific lightness ranges
|
||
|
||
4. **Shape Rendering**: Process in exact order:
|
||
- Outer shapes (sides + corners) with rotations
|
||
- Center shapes with incremental rotation when no rotation hash
|
||
|
||
### Critical Implementation Details
|
||
|
||
#### Shape Selection Algorithm (generator.go:67-95)
|
||
```go
|
||
// CRITICAL: Use exact hash positions to match JavaScript
|
||
sideShapeIndex := parseHex(hash, 2, 1) % len(outerShapes)
|
||
cornerShapeIndex := parseHex(hash, 4, 1) % len(outerShapes)
|
||
centerShapeIndex := parseHex(hash, 1, 1) % len(centerShapes)
|
||
```
|
||
|
||
#### Transform Application (generator.go:125-135)
|
||
```go
|
||
// Center shapes: increment rotation per position when no rotation hash
|
||
if rotationHashIndex == -1 {
|
||
transformRotation = i % 4
|
||
} else {
|
||
transformRotation = parseHex(hash, rotationHashIndex, 1) % 4
|
||
}
|
||
```
|
||
|
||
#### Z-Order Rendering (renderer/svg.go)
|
||
**CRITICAL**: SVG renderer preserves insertion order, NOT alphabetical:
|
||
```go
|
||
// Maintain colorOrder to preserve z-order
|
||
for _, color := range r.colorOrder {
|
||
// Render in insertion order
|
||
}
|
||
```
|
||
|
||
## JavaScript Reference Compatibility
|
||
|
||
### ⚠️ CRITICAL REQUIREMENT ⚠️
|
||
|
||
**THE `jdenticon/reference_test.go` FILE MUST ALWAYS PASS**
|
||
|
||
This is the **MOST IMPORTANT** test in the entire codebase. It validates that our Go implementation produces byte-for-byte identical SVG output to the JavaScript reference implementation.
|
||
|
||
**NEVER commit code that breaks this test. NEVER merge PRs with failing reference tests.**
|
||
|
||
### Reference Files Location
|
||
- JavaScript reference SVGs: `jdenticon-js/test/`
|
||
- Go compatibility test: `jdenticon/reference_test.go`
|
||
|
||
### Test Cases
|
||
The compatibility test validates three critical cases:
|
||
1. `"test-hash"` at 64px
|
||
2. `"example1@gmail.com"` at 64px
|
||
3. `"example2@yahoo.com"` at 64px
|
||
|
||
**These tests MUST pass** - they verify byte-for-byte identical SVG output.
|
||
|
||
### Running the Critical Test
|
||
```bash
|
||
# Run ONLY the reference compatibility test
|
||
go test ./jdenticon -run TestJavaScriptReferenceCompatibility -v
|
||
|
||
# This test MUST show:
|
||
# === RUN TestJavaScriptReferenceCompatibility/test-hash_@
|
||
# --- PASS: TestJavaScriptReferenceCompatibility/test-hash_@ (0.00s)
|
||
# === RUN TestJavaScriptReferenceCompatibility/example1@gmail.com_@
|
||
# --- PASS: TestJavaScriptReferenceCompatibility/example1@gmail.com_@ (0.00s)
|
||
# === RUN TestJavaScriptReferenceCompatibility/example2@yahoo.com_@
|
||
# --- PASS: TestJavaScriptReferenceCompatibility/example2@yahoo.com_@ (0.00s)
|
||
```
|
||
|
||
### If the Reference Test Fails
|
||
1. **STOP DEVELOPMENT** - Do not proceed with other changes
|
||
2. Investigate what changed in the generation algorithm
|
||
3. Check hash parsing positions in `generator.go`
|
||
4. Verify shape selection and rendering order
|
||
5. Check SVG z-order in `renderer/svg.go`
|
||
6. Compare against JavaScript implementation line by line
|
||
7. **DO NOT** change the reference files to match Go output
|
||
8. **FIX** the Go implementation to match JavaScript exactly
|
||
|
||
### Key Compatibility Requirements
|
||
|
||
1. **Hash Parsing**: Must use identical positions as JavaScript
|
||
2. **Shape Order**: Must render in same sequence (outer shapes, then center)
|
||
3. **Position Arrays**: Must use hard-coded JavaScript positions, not computed layout
|
||
4. **Transform Logic**: Center shape rotation must increment when no rotation hash
|
||
5. **Circle Interface**: Uses top-left + size (not center + radius)
|
||
6. **Z-Order**: SVG elements must maintain insertion order
|
||
|
||
## Common Development Patterns
|
||
|
||
### Adding New Shape Types
|
||
1. Update shape arrays in `generator.go`
|
||
2. Implement rendering in `shapes.go`
|
||
3. Add transform support if needed
|
||
4. **Always run compatibility tests**
|
||
|
||
### Modifying Color Generation
|
||
1. Changes in `internal/engine/color.go`
|
||
2. Ensure lightness ranges match JavaScript exactly
|
||
3. Test with variety of hue values
|
||
|
||
### Renderer Changes
|
||
1. Update base interface in `renderer/renderer.go`
|
||
2. Implement in both SVG and PNG renderers
|
||
3. **Critical**: Maintain z-order in SVG renderer
|
||
|
||
## Testing Strategy
|
||
|
||
### Unit Tests
|
||
- Each component has comprehensive unit tests
|
||
- Focus on boundary conditions and edge cases
|
||
- All tests should pass consistently
|
||
|
||
### Integration Tests
|
||
- `reference_test.go` - **MOST CRITICAL** - JavaScript compatibility
|
||
- `integration_test.go` - Visual regression testing
|
||
- PNG checksum validation for consistency
|
||
|
||
### Manual Testing
|
||
- Run `example_usage.go` to generate various avatar types
|
||
- Verify visual output matches expectations
|
||
- Test edge cases (empty strings, long inputs, special characters)
|
||
|
||
## Configuration System
|
||
|
||
### Public API (jdenticon/config.go)
|
||
```go
|
||
type Config struct {
|
||
Hue float64 // Color hue (0.0-1.0)
|
||
Saturation float64 // Color saturation (0.0-1.0)
|
||
Lightness float64 // Color lightness (0.0-1.0)
|
||
BackgroundColor string // Hex color or empty for transparent
|
||
Padding float64 // Padding as percentage (0.0-0.5)
|
||
}
|
||
```
|
||
|
||
### Internal Configuration (internal/engine/config.go)
|
||
- More detailed color ranges and restrictions
|
||
- Validation logic for all parameters
|
||
- Builder pattern for complex configurations
|
||
|
||
## Error Handling Patterns
|
||
|
||
1. **Input Validation**: Validate size > 0, hash format, config ranges
|
||
2. **Graceful Degradation**: Default to safe values for invalid inputs
|
||
3. **Clear Error Messages**: Provide actionable error information
|
||
4. **No Panics**: Always return errors, never panic in library code
|
||
|
||
## Performance Considerations
|
||
|
||
1. **Caching**: Generator caches theme colors for repeated use
|
||
2. **Memory Management**: Reuse objects where possible
|
||
3. **PNG Generation**: Uses efficient Go imaging library
|
||
4. **SVG Generation**: String builder for optimal performance
|
||
|
||
## Debugging & Troubleshooting
|
||
|
||
### Visual Debug Tools
|
||
- `example_usage.go` - Generates multiple test cases
|
||
- `quick_test.go` - Quick visualization
|
||
- Generated avatars saved as PNG/SVG files
|
||
|
||
### Common Issues
|
||
1. **Compatibility Test Failures**: Usually indicates algorithm change
|
||
2. **Color Inconsistency**: Check hue/lightness calculations
|
||
3. **Shape Positioning**: Verify transform application
|
||
4. **Z-Order Problems**: Check SVG renderer color ordering
|
||
|
||
### Debug Hash Extraction
|
||
Use the hash parsing utilities to understand how values are extracted:
|
||
```go
|
||
parseHex(hash, position, octets) // Extract specific hash segments
|
||
```
|
||
|
||
## Future Development Guidelines
|
||
|
||
1. **Maintain Compatibility**: Always run reference tests after changes
|
||
2. **Follow Go Conventions**: Use standard Go patterns and idioms
|
||
3. **Test Coverage**: Add tests for any new functionality
|
||
4. **Documentation**: Update this guide for significant changes
|
||
5. **Performance**: Profile before optimizing, measure impact
|
||
|
||
## Dependencies
|
||
|
||
- **Standard Library Only**: No external dependencies for core functionality
|
||
- **Testing**: Uses standard Go testing framework
|
||
- **Command Line**: Uses standard `flag` package
|
||
|
||
## API Usage Examples
|
||
|
||
### Basic Generation
|
||
```go
|
||
icon := jdenticon.Generate("user@example.com", 200)
|
||
svg := icon.ToSVG()
|
||
png := icon.ToPNG()
|
||
```
|
||
|
||
### With Custom Configuration
|
||
```go
|
||
config := &jdenticon.Config{
|
||
Hue: 0.3,
|
||
Saturation: 0.7,
|
||
Lightness: 0.5,
|
||
Padding: 0.1,
|
||
}
|
||
icon := jdenticon.GenerateWithConfig("user@example.com", 200, config)
|
||
```
|
||
|
||
This implementation successfully achieves JavaScript reference compatibility while maintaining clean Go idioms and comprehensive test coverage. |