kessoku: Instructions file for Codex

Repository Guidelines — kessoku

Kessoku is a compile-time dependency injection library for Go that speeds up application startup through parallel dependency injection. Unlike google/wire which initialises services sequentially, Kessoku automatically executes independent providers in parallel. It generates optimised code at compile time with zero runtime overhead.

Agent configuration is managed via apm. Common conventions live in mazrean/apm-plackage/common; per-stack rules come from mazrean/apm-plackage/{go,goreleaser}. Run apm install locally.

Project Structure

• Go 1.24 workspace with main module github.com/mazrean/kessoku and tools module ./tools (go.work tracks both).
• Public API lives at the root (annotation.go); CLI entrypoint is cmd/kessoku/.
• Codegen engine sits under internal/kessoku/ (parser, graph, generator); CLI wiring lives in internal/config/.
• Utilities are in internal/pkg/; examples live in examples/; specs and checklists under specs/; built binaries land in bin/.

Common Commands

Build, test, lint, and release operations are consolidated as mise tasks in .mise.toml (run mise tasks to list them); CI calls these same tasks so local runs match CI exactly.

Every go-invoking task depends on the hidden work:sync task (go work use), which realigns the go directive in go.work with the workspace modules. Dependency-update PRs raise a module's go directive without touching go.work (e.g. a honnef.co/go/tools bump moves tools/go.mod to go 1.26.0 on its own), which otherwise breaks every go command with module tools listed in go.work file requires go >= X, but go.work lists go Y. work:sync fixes that before the command runs; commit the resulting go.work change with the update. Renovate handles its own PRs via postUpgradeTasks (see Tooling), so work:sync is the safety net for everything else.

# Build
mise run build                             # go build -o bin/kessoku ./cmd/kessoku

# Test
mise run test                              # go test -v ./...
mise run test:ci                           # go test -v -race -coverprofile=coverage.out ./internal/... (matches CI)
go test -v -run TestName ./...             # run a specific test
go test -v ./internal/kessoku/...          # run tests in a specific package

# Golden tests (code generation validation)
go test -v -run TestGoldenGeneration ./internal/kessoku/...   # run golden tests
mise run test:golden-update                # update golden files

# Lint (mandatory before commit)
mise run lint                              # go tool lint ./...
mise run lint:fix                          # auto-fix where possible

# Code generation
mise run generate                          # go generate ./...
go tool kessoku [files...]                 # direct codegen for specific files

# Wire migration
go tool kessoku migrate [patterns...] -o kessoku.go

# API compatibility check
mise run apicompat                         # go tool apicompat github.com/mazrean/kessoku@latest github.com/mazrean/kessoku

# Release
mise run release:snapshot                  # goreleaser release --snapshot --clean
mise run release:build                     # goreleaser build --clean --skip=validate (CI build job)
mise run release:publish                   # goreleaser release --clean --skip=validate (tag-triggered release)

# Everything mandatory before a commit
mise run check                             # fmt + test + lint