CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7Act is a tool to run GitHub Actions locally. It reads `.github/workflows/` files, builds an execution plan, and uses Docker to run containers for each action. Written in Go 1.24+.
8 
9## Common Commands
10 
11- `make build` — build binary to `dist/local/act`
12- `make test` — run `go test ./...` and the act CLI
13- `make lint-go` — run `golangci-lint run`
14- `make format` — run `go fmt ./...`
15- `make tidy` — run `go mod tidy`
16- `make pr` — full PR checklist: tidy, format-all, lint, test
17- `go test ./pkg/runner/...` — run tests for a single package
18- `go test ./pkg/runner/ -run TestRunEvent` — run a single test
19 
20## Architecture
21 
22### Execution Flow
23 
241. **CLI** (`cmd/root.go`) — Cobra-based CLI parses flags into an `Input` struct
252. **Planner** (`pkg/model/planner.go`) — parses workflow YAML into a `Plan` containing `Stage`s (serial) with `Run`s (parallel jobs)
263. **Runner** (`pkg/runner/runner.go`) — converts the Plan into composable `Executor` chains
274. **RunContext** (`pkg/runner/run_context.go`) — holds all state for a job execution (env vars, matrix, containers, expressions)
285. **Steps** (`pkg/runner/step.go`) — each step type (action, docker, script) implements the `step` interface
29 
30### Core Abstraction: Executor Pattern
31 
32The `Executor` type (`pkg/common/executor.go`) is a `func(ctx context.Context) error` used throughout the codebase. Executors compose via:
33 
34- `.Then()`, `.Finally()`, `.OnError()` — chaining
35- `NewPipelineExecutor()` — serial execution
36- `NewParallelExecutor()` — parallel execution
37- `.If()`, `.IfNot()` — conditional execution
38 
39### Key Packages
40 
41- **`pkg/model/`** — workflow YAML parsing, plan creation, action definitions
42- **`pkg/runner/`** — core execution engine, expression evaluation, step types (local/remote/docker/composite actions, reusable workflows)
43- **`pkg/container/`** — Docker API wrapper, container and host execution environments
44- **`pkg/common/`** — Executor pattern, context utilities, logging
45- **`pkg/exprparser/`** — GitHub Actions `${{ }}` expression language interpreter
46- **`pkg/artifacts/`** and **`pkg/artifactcache/`** — artifact upload/download and caching server
47 
48## Linting Rules
49 
50Configured in `.golangci.yml`:
51 
52- Use `errors` from stdlib, not `github.com/pkg/errors`
53- Use `github.com/sirupsen/logrus` (aliased as `log`), not stdlib `log`
54- Use `github.com/stretchr/testify` for tests, not `gotest.tools/v3`
55- Max cyclomatic complexity: 20
56- Import aliases enforced: `logrus` → `log`, `testify/assert` → `assert`
57 
58## Testing
59 
60- Tests use `testify/assert` and `testify/mock`
61- Table-driven tests are common in `pkg/model/` and `pkg/exprparser/`
62- Test fixtures live in `testdata/` directories alongside their packages
63- `pkg/runner/testdata/` contains extensive sample GitHub Actions workflows used as integration test fixtures
64