Matrix logo

Build, Test & Lint

The root Makefile workflow — building the Go modules, running race tests, the local CI gate, and golangci-lint setup.

The root Makefile drives every sibling Go module. Each module is independently go build/go testable with its own go.mod.

Toolchain

Go 1.22+

Every go.mod pins go 1.21; 1.22+ is recommended for local dev.

GNU make 4.x

Drives build, install, test, vet, and the CI gate.

Node 20+, Python 3.11+, uv

Needed for the MCP-server-driven flows.

Docker 24+ (buildx)

Needed only to build the daemon image.

Common targets

make build           # build all Go modules
make install         # drop the runnable CLIs into ./bin
make test            # go test -count=1 -race ./... per module
make vet             # go vet ./... per module
make ci              # gofmt-check + vet + tests (mirrors GitHub Actions)
make version         # print Go + golangci-lint + Docker versions

A clean make ci is the bar for opening a PR.

Linting

make lint-install    # installs golangci-lint (pinned to v1.61.0)
make lint

The lint config (.golangci.yml) narrows static analysis to bugs and correctness rather than style churn.

Test discipline

  • Don't weaken existing tests. Removing or skipping a test requires an explicit reason in the PR description.
  • Add tests for new behavior — at minimum a happy path plus one error path.
  • Cortex mutation paths need a Rebuild-after-mutation test (see cortex/rebuild_test.go).
  • MCL lexer/parser/validator changes need token + parser tests, and every new validator rule needs a green-path and red-path test.
  • Skill corpus: ./bin/mcl-validate skills/<slug>/SKILL.mtx; the mtx-corpus CI job validates every SKILL.mtx on each PR.
Contributing

Branching, commit conventions, and the PR process.