Guidance for AI coding agents (Claude Code, Copilot, Cursor, Codex, etc.) working in this repository.
Human contributors: see CONTRIBUTING.md and DEVELOPING.md first — this file is a complement, not a replacement.
revive is a fast, configurable, extensible Go linter.
It parses Go source via go/ast (+ go/types for typed rules), runs a configurable set of rules, and emits findings through pluggable formatters.
Top-level packages:
cli/— command-line entry point (main.godefers tocli.RunRevive), plus the end-to-end CLI tests (e2e_test.go,package cli_test) and their fixtures incli/testdata/.lint/— core linter engine, rule interfaces (Rule,ConfigurableRule),File,Failure,Severity, and the in-memoryConfigtypes.rule/— one file per rule (100+ rules). Untyped rules also listed inuntyped.toml.formatter/— output formatters (default, json, sarif, stylish, friendly, …).config/— config file loading (TOML), defaults, and the registries of available rules and formatters.revivelib/— programmatic API for embedding revive.test/— rule tests, one_test.goper rule.testdata/— Go source fixtures consumed by rule tests.internal/— helpers not part of the public API.
Before writing Go, read .github/instructions/go.instructions.md.
It is the single source of truth for naming, error handling, concurrency, testing style, and modern Go (1.21+) idioms that this project expects.
Do not duplicate or contradict it here.
In addition to that file:
- The project targets the Go version in
go.mod(currentlygo 1.26.0). Use stdlib features available at that version (min/max,slices,maps,cmp.Or,errors.Join, range-over-int,slog, etc.) instead of hand-rolled equivalents. revivelints itself. Code must passrevive --config revive.toml ./...andgolangci-lint run. See.golangci.ymlfor the strict config.
All workflows go through the Makefile:
make build # builds ./revive with version ldflags
make test # go test -v -race ./...
make lint # revive + golangci-lint
make fmt # golangci-lint fmt
make tidy # go mod tidy -diff (fails on drift)
make all # test + lint + buildRun a single rule's tests:
go test -run TestUnusedParam ./test/...Run the end-to-end CLI tests:
go test -run TestRevive ./cli/These run revive as a subprocess, so they cover what unit tests cannot: exit codes, flag parsing, and output on stdout/stderr.
- The test binary re-executes itself as revive: with
REVIVE_E2E_RUN_REVIVE=1set it callsRunRevive()instead of running tests. - Fixtures live in
cli/testdata/(clean.gohas no failures,bad.gohas two) and the subprocess runs in that directory.HOME,USERPROFILEandXDG_CONFIG_HOMEpoint at temp dirs, so a localrevive.tomlcannot change the result, and a case can write its own config there with thehomeConfigandxdgConfigfields to cover default config discovery. - To cover another flag, exit code, or config error, add a case to the table in
TestReviveinstead of a new test function.
Logging during local runs: set REVIVE_LOG_LEVEL (debug|info|warn|error) — logs go to stderr. See DEVELOPING.md.
The canonical example is rule/argument_limit.go with test/argument_limit_test.go.
The full checklist — identifier, file and type naming, interfaces, failures, typed vs untyped, registration, tests, and documentation —
lives in .github/instructions/rule.instructions.md; it is the single source of truth
for rule development and is also what GitHub Copilot applies when reviewing pull requests. Follow it item by item.
Implement lint.Formatter:
Format(<-chan lint.Failure, lint.Config) (string, error)
Name() stringPlace the implementation in formatter/<name>.go, append it to allFormatters in config/config.go
(so config.GetFormatter can find it), and add a row to the formatters table in README.md.
README.md and RULES_DESCRIPTIONS.md are linted by markdownlint-cli2,
have generated tables of contents (markdown-toc), and have code snippets formatted by mdsf.
If you edit them, run the three tools listed in DEVELOPING.md §Lint Markdown files —
CI will reject hand-edited TOCs and unformatted snippets.
Use ```go for Go code. Use ```golang only for snippets that are intentionally non-compilable.
Line length in this and other Markdown files is capped at 150 characters (200 inside code blocks); wrap accordingly.
- Star the repository before contributing — it helps the project and shows your support.
- Match the existing commit style (see
git log): conventional-style prefixes such asfeature:,fix:,fix(deps):,chore(deps):, often followed by#<PR>. - Keep PRs focused and atomic. Open an issue first for non-trivial changes — see CONTRIBUTING.md.
- The PR template lives at
.github/PULL_REQUEST_TEMPLATE.md; fill in motivation, test coverage, and link the originating issue. - Run
make alllocally before pushing. CI runs the same checks plus Markdown lint, TOC check, andmdsf verify.
- Don't silence lint findings with
//nolintor// revive:disableto make CI green — fix the underlying code instead. Suppressions need a justification comment and reviewer approval. - Don't relax thresholds in
.golangci.ymlorrevive.tomlto avoid fixing a finding. - Don't add a dependency without a strong reason;
revivedeliberately keeps its dependency tree small. Rungo mod tidyafterwards. - Don't introduce assertion libraries (
testify,gomega, …) — the project uses the standardtestingpackage by design. - Don't reformat or restructure files unrelated to the change. Keep diffs reviewable.
- Don't edit generated TOCs in
README.md/RULES_DESCRIPTIONS.mdby hand. - Don't let
Configurekeep state from a previous call: rules are singletons and may be configured more than once, so reset every configurable field to its default before reading the arguments, even on the empty-arguments early return. - Don't add a rule to
untyped.tomlunless you've verified it really doesn't touch type info — getting this wrong silently breaks the untyped fast path.
| Need | File / dir |
|---|---|
| Go style and idioms | .github/instructions/go.instructions.md |
| Rule checklist (PR review) | .github/instructions/rule.instructions.md |
| Build / test / lint commands | Makefile, DEVELOPING.md |
| How to write a rule (worked example) | rule/argument_limit.go + test/argument_limit_test.go |
Rule interfaces, File, Failure |
lint/ |
| Default config bundles | defaults.toml, revive.toml |
| User-facing rule docs | RULES_DESCRIPTIONS.md |
| CLI flags & behavior | cli/ |
| Programmatic embedding | revivelib/ |