FinFocus Development Workflow

Quick Reference

bash
1make build          # Build binary to bin/finfocus
2make test           # Unit tests (fast, default)
3make lint           # golangci-lint + markdownlint (5+ min, use extended timeout)
4make validate       # go mod tidy + go vet
5make test-race      # Race detector
6make test-integration  # Cross-component tests (10min timeout)
7make build-all      # Build binary + all plugins

Critical rules: Always run make lint and make test before claiming success. Never run git commit (user commits manually). Never modify .golangci.yml.

Adding a CLI Command

1. Create internal/cli/your_command.go
2. Follow constructor pattern:

go
1func NewYourCmd() *cobra.Command {
2    var flagVar string
3    cmd := &cobra.Command{
4        Use:   "your-command",
5        Short: "Description",
6        RunE: func(cmd *cobra.Command, args []string) error {
7            // Use cmd.Printf() not fmt.Printf()
8            return nil
9        },
10    }
11    cmd.Flags().StringVar(&flagVar, "flag", "", "description")
12    return cmd
13}

1. Register in parent command (e.g., root.go or cost.go)
2. Use RunE (not Run) for error handling
3. Defer cleanup immediately: defer cleanup()

Resource Processing Pipeline

All cost commands follow:

text
1ingest.LoadPulumiPlan(path) -> ingest.MapResources() -> registry.Open(ctx, adapter)
2  -> engine.GetProjectedCost/GetActualCost() -> engine.RenderResults(format, results)

Testing Standards

• Use testify/assert and testify/require exclusively (never manual if/t.Errorf)
• require.* for setup that must succeed; assert.* for value checks
• Table-driven tests for variations
• Package suffix _test for black-box testing
• t.TempDir() for temporary files (auto-cleanup)
• Capture output: cmd.SetOut(&buf) and cmd.SetErr(&buf)
• Target 80% coverage minimum, 95% for critical paths

See references/testing-patterns.md for detailed test patterns and examples.

Project Structure

See references/project-structure.md for the complete package map and key file locations.

Error Handling

• Wrap errors: fmt.Errorf("context: %w", err)
• Return early on errors
• Plugin failures don't stop processing (graceful degradation)
• Validation prefix: "VALIDATION: %v", plugin error prefix: "ERROR:"

Logging (zerolog)

go
1log := logging.FromContext(ctx)
2log.Debug().Ctx(ctx).Str("component", "engine").Msg("message")

Standard fields: trace_id, component, operation, duration_ms. Enable debug: --debug flag or FINFOCUS_LOG_LEVEL=debug.

Date Handling

Support both "2006-01-02" and RFC3339. Default --to to time.Now(). Validate ranges (to must be after from).

Output Formats

Three formats via --output flag: table (default), json, ndjson. Always use cmd.Printf() for testability.