# Rules for coding agents

This file holds the rules for coding agents working in this repository.
`CONVENTIONS.md` defines the architecture. `REPO_POLICIES.md` defines the
repository standards. Both are copies of shared documents. Do not edit them
here.

## Before every commit

1. Run `make fmt`.
2. Run `make check`. It runs the tests and the linter in Docker, then the format
   check. All three must pass with no findings.

Never run `go test`, `golangci-lint` or `gofmt` directly. Use the `make` targets
instead, such as `make test` and `make lint`.

## Branches and pull requests

- Never commit to `main` or `next` directly. Every change is a pull request from
  a feature branch into `next`.
- Only the owner merges `next` into `main`.
- A pull request that closes an issue has the title `Description (closes #N)`.
- One logical change per commit.
- Commit messages are in the imperative mood and short.

## Code style

- Follow `CONVENTIONS.md`.
- Outside test files, every package has a package doc comment.
- Outside test files, every exported type, function and variable has a doc
  comment.
- JSON tags are camelCase. The HTTP API's `last_id`, `pow_token` and
  `hashcash_bits` stay as they are, each with a `//nolint:tagliatelle` comment.
- Prefer named constants to magic numbers. The `mnd` linter checks for them
  outside test files.
- No inline error handling such as `if err := f(); err != nil`. Assign the error
  on its own line, then test it.
- A `return` that follows another statement in its block has a blank line before
  it.
- A blank line between the embedded fields of a struct and its other fields.
- Outside test files, every blank import has a comment saying why it is there.

## Architecture

- The server uses `go.uber.org/fx` for dependency injection.
  `cmd/neoircd/main.go` lists its `fx` providers, such as `db.New` and
  `handlers.New`.
- Application packages live under `internal/`, one package per concern.
- `pkg/irc` holds the IRC command names and numeric reply codes.
- The `web` package embeds the built web client.
- Each exported `Handle…` method of `Handlers` returns an `http.HandlerFunc`.
- A request struct is defined inside the method that decodes it.
- The server uses the database only through the methods of `db.Database`.
- The database migrations live in `internal/db/schema/` and are embedded with
  `go:embed`.
- The database is SQLite, through the pure Go driver `modernc.org/sqlite`.

## Testing

- Prefer table-driven tests.
- Use `testing.T` helpers, not assertion libraries.
- A test file lives next to the code it tests and ends in `_test.go`.
- The linter requires each test file to be in the package's external test
  package, such as `handlers_test`. It allows `export_test.go` and files ending
  in `_internal_test.go` in the package itself.
- An `export_test.go` file gives the external tests access to the package's
  unexported code.

## Dependencies

- The required libraries are listed in `CONVENTIONS.md` §1.
- No new dependency without a reason given in the pull request.
- Prefer dependencies written in pure Go, which build without cgo.