Contributing

Setup

git clone https://github.com/annavetech/annave-cli-golang
cd annave-cli-golang

# Build
go build ./cmd/annave

# Run tests
go test ./...

# Run a command locally
go run ./cmd/annave log analyze --help

Go 1.24 or later is required. No C dependencies, no Docker required for local development.

Running tests

# All tests
go test ./...

# Single package, verbose
go test -v ./internal/log/...

# Single test function
go test -v -run TestAnalyzer_Analyze ./internal/log/...

# Race detector
go test -race ./...

Code style

• SPDX header on every .go file: // Copyright 2026 Anna Veretennykova + // SPDX-License-Identifier: Apache-2.0
• Comments only when the reason is non-obvious — not what the code does, but why
• No mocks for filesystem, Kubernetes API, or AWS SDK in tests. Tests call domain logic directly or use real fixtures
• gofmt is the formatter. go vet ./... must pass
• Error codes must be added to messages.yaml before use in Go code — no hardcoded message strings
• Every command must support --format plain|json|table. Plain is always the default

Adding a new module

See the Architecture page for the full walkthrough. Short version:

1. Create internal/<module>/domain/domain.go — result types, no external imports
2. Create internal/<module>/port/port.go — one interface
3. Create the adapter under internal/<module>/<adapter>/
4. Create cmd/annave/cmd/<module>.go (parent command) and cmd/annave/cmd/<module>_<subcommand>.go
5. Add configurable limits to internal/shared/config/limits.yaml
6. Add new error codes to internal/shared/config/messages.yaml
7. Write a test that exercises the adapter with a real fixture

Adding a security or infra rule

Rule IDs are sequential within their prefix. Use the next available ID: SECRET001–SECRET012, GO001–GO010, TS001–TS005, K8S001–K8S008, TF001–TF005, HELM001–HELM005, K8S101–K8S106.

Write a test that triggers the new rule with a minimal fixture. A false-positive test (similar-looking code that should not match) is also useful.

Submitting a pull request

1. Fork and create a branch from main
2. Make your changes. go build ./... and go test ./... must pass.
3. Add a test for any new behaviour
4. Open a PR against main. Describe what the change does and why.
5. Do not bump the version in cmd/annave/cmd/root.go — that is done at release time

Versioning

ANNÁVE CLI follows Semantic Versioning. The version is set in cmd/annave/cmd/root.go.

Reporting bugs

Open an issue on GitHub. Include:

• The command you ran (with flags, but redact any secrets)
• The full error output
• OS and Go version (go version)
• A minimal reproduction if possible