Constable is a static analysis tool for Go.
Its first goal is to provide opt-in semantic checks that help developers state and enforce code contracts that Go does not currently express in the type system.
The long-term goal is for these checks to be usable from the command line, test suites, CI, and gopls.
The initial check verifies a function is nonmutating,
//constable:nonmutating
func Example(arg *Config) Result {
// The function must not mutate caller-visible state through its arguments.
}For this project, "nonmutating" means that a function does not mutate any arguments from the caller's perspective.
That includes the receiver for receiver functions (methods).
The name, nonmutating, is inspired by the mutating keyword in Swift; see Modifying Value Types from Within Instance Methods.
The definition of "nonmutating" does not imply more general immutability nor does it imply lack of side effects.
- Build analyzers on top of
golang.org/x/tools/go/analysis. - Keep checks independently usable, testable, and composable.
- Design analyzer output so it can be consumed by
goplsdiagnostics. - Start with one focused check:
//constable:nonmutatingon functions and methods. - Use Go SSA where it provides better semantic information than AST-only inspection.
- Prefer precise, explainable diagnostics over broad but noisy warnings.
- Proving broader side-effect freedom beyond caller-visible argument mutation.
- Detecting every possible mutation through aliases.
- Enforcing nonmutation across goroutine, reflection, unsafe, cgo, or assembly boundaries with complete precision.
The project should follow the shape used by common Go analysis tools such as Staticcheck: small analyzers, a shared internal framework where needed, and thin entry points for command-line or editor integration.
Proposed package layout:
cmd/constable/
Main command-line entry point.
internal/analysis/nonmutating/
The initial //constable:nonmutating analyzer.
internal/directive/
Parsing and validation for //constable: directives.
internal/report/
Shared diagnostic helpers if multiple analyzers later need them.
internal/testdata/
Analyzer test fixtures following go/analysis analysistest conventions.
The first implementation can be smaller than this layout if some packages are not yet useful. The important boundary is that analyzer logic should not be coupled to the command-line entry point.
Each check should be implemented as a *analysis.Analyzer.
The command-line tool can use singlechecker while there is only one analyzer and move to multichecker when more checks are added.
Expected flow:
- Load packages through the standard analysis driver.
- Parse
//constable:directives from function and method declarations. - For each recognized directive, run the corresponding analyzer logic.
- Emit diagnostics through
analysis.Pass.Reportwith stable, actionable messages.
The analyzer should avoid defining its own package loading, type checking, or diagnostic protocol unless the standard go/analysis path proves insufficient.
Directive comments use the constable namespace:
//constable:nonmutating
func F() {}Initial parsing rules:
- A directive applies to the immediately following function or method declaration.
- A directive begins with
//constable:. - Use Go struct tag syntax after
//constable:for directive options; see reflect.StructTag. The sturct tag key refers to the check name, e.g.,nonmutating. The value can be parsed specific to the check's options (if any) but typically is a simple comma-separated list of options. Ideally, we should tolerate omitting the:""part of the struct tag if there are no options. - The first directive name is
nonmutating. - Unknown directives should produce a diagnostic once directive parsing exists.
The proposed syntax leaves room for new, future checks:
//constable:nonmutating othercheck:"safe,strict"The nonmutating analyzer verifies that annotated functions do not mutate state that is visible to the caller through parameters or method receivers.
Examples that should be reported:
//constable:nonmutating
func MutatesPointer(p *int) {
*p = 1
}
//constable:nonmutating
func MutatesSlice(s []int) {
s[0] = 1
}
//constable:nonmutating
func MutatesMap(m map[string]int) {
m["x"] = 1
}
type Counter struct{ n int }
//constable:nonmutating
func (c *Counter) Inc() {
c.n++
}
type Buffer struct{ data []byte }
//constable:nonmutating
func (b Buffer) ClearFirstByte() {
b.data[0] = 0
}Examples that should be allowed:
//constable:nonmutating
func ReadsPointer(p *int) int {
return *p
}
//constable:nonmutating
func MutatesLocal() int {
x := 0
x++
return x
}
//constable:nonmutating
func ReassignsParameter(p *int) {
p = nil // Does not mutate the caller's pointed-to value.
}
type Count struct{ n int }
//constable:nonmutating
func (c Count) Increment() Count {
c.n++ // Mutates only the receiver copy.
return c
}The check should initially focus on direct caller-visible mutations:
- Assigning through a pointer parameter or pointer receiver.
- Assigning to fields reachable through a pointer parameter or pointer receiver.
- Assigning to slice elements reachable from a parameter.
- Assigning to map entries reachable from a parameter.
- Calling built-ins that mutate parameter-backed values, such as
deleteon a map parameter. - Passing parameter-reachable mutable state to known-mutating operations when they can be identified with confidence.
The check should be conservative about uncertain cases. Depending on the final policy, uncertain cases may either be reported as unsupported or ignored until a more precise model exists.
SSA is likely the right representation for the core mutation analysis because it makes data flow and memory operations more explicit than raw AST traversal.
golang.org/x/tools/go/analysis/passes/buildssa can provide SSA for the current package to analyzers.
The nonmutating analyzer should depend on buildssa.Analyzer and inspect the SSA function corresponding to each annotated declaration.
Likely implementation outline:
- Find annotated
*ast.FuncDeclnodes. - Resolve each declaration to its
*types.Funcobject. - Find the corresponding
*ssa.Functionfrom thebuildssaresult. - Mark SSA values that originate from parameters and receivers.
- Track aliases derived from those values where practical.
- Report stores, map updates, field updates, slice element updates, and relevant built-ins when their target is parameter-derived caller-visible state.
SSA concepts likely to matter:
*ssa.Parameteridentifies function parameters and receivers.*ssa.Storerepresents memory writes.*ssa.FieldAddr,*ssa.IndexAddr, and related address-producing instructions can identify writes into fields, arrays, and slices.*ssa.MapUpdaterepresents map entry mutation.*ssa.Callmay need summary information to understand whether a callee can mutate its arguments.*ssa.Allochelps distinguish local allocations from caller-provided memory.
The first version should not attempt to reproduce Go's escape analysis. Escape analysis answers allocation-placement questions; this analyzer answers whether caller-visible state is mutated. Escape analysis and SSA alias information can inspire the implementation, but the check should remain independent and explainable.
The initial version can be intraprocedural with limited call handling. That means it analyzes the body of the annotated function directly and reports obvious mutations in that body.
Future versions can add summaries for functions:
- Which parameters may be mutated.
- Whether a function is annotated
//constable:nonmutatingand already checked. - Whether a known standard-library function mutates an argument.
- Whether calls through interfaces or function values are unknown.
This summary model will matter for code such as:
//constable:nonmutating
func F(p *int) {
G(p)
}
func G(p *int) {
*p = 1
}The first version should decide whether to ignore this, report it as an unknown mutation risk, or only report it when G is available and analyzable.
Diagnostics should be specific and located at the mutation site when possible.
Example messages:
//constable:nonmutating function mutates pointer parameter p//constable:nonmutating method mutates receiver c//constable:nonmutating function mutates map parameter m//constable:nonmutating function deletes from map parameter m
Diagnostics should avoid claiming more than the analyzer has proven. If a case is uncertain, the message should say so explicitly or the analyzer should remain silent until the policy is clear.
Use golang.org/x/tools/go/analysis/analysistest for analyzer tests.
Test data should include positive and negative examples with // want comments.
Initial test categories:
- Directive parsing and attachment to function declarations.
- Direct pointer mutation.
- Receiver mutation.
- Struct field mutation through pointer parameters.
- Slice element mutation.
- Map update and delete.
- Local-only mutation that should not be reported.
- Parameter reassignment that should not be reported.
- Unsupported or uncertain cases, once policy is decided.
As the analyzer grows, tests should separate behavior-preserving refactors from new detection behavior so review stays manageable.
The first command should run the analyzer over packages in the same style as other Go analysis tools:
constable ./...While there is only one analyzer, singlechecker.Main(nonmutating.Analyzer) is enough.
When additional checks exist, switch to multichecker.Main(...).
The command-line tool should be thin.
Analyzer configuration, directive parsing, and diagnostic behavior should live outside cmd/.
gopls can consume analyzers built on go/analysis, which is the main reason to use that package from the beginning.
To keep that path open:
- Keep analyzers deterministic and package-local unless explicitly designed otherwise.
- Avoid depending on command-line-only behavior.
- Keep diagnostics stable and precise.
- Avoid expensive whole-program work in the default analyzer path.
- Make any future configuration explicit and serializable.
The first integration milestone should be a normal analyzer that can run under standard Go analysis drivers.
Direct gopls integration can wait until the check is useful and well tested.
These questions should be resolved incrementally as implementation begins:
- Should
//constable:options use struct-tag syntax, Go directive-style syntax, or a simpler custom syntax? - Should unknown
//constable:directives be diagnostics, ignored comments, or reserved for future tools? - Should
//constable:nonmutatingforbid mutation of package globals, or only mutation of caller-visible argument and receiver state? - How should calls to unanalyzed functions be handled: ignored, reported as uncertain, or controlled by a strict mode?
- Should calls to methods on parameter-derived values be assumed mutating when the receiver is mutable?
- How should interface calls and function values be modeled?
- Should mutation through
unsafe, reflection, cgo, or assembly be reported as unsupported in annotated functions? - Should appending to a slice parameter be considered mutation only when it writes to the existing backing array, or always treated as caller-visible?
- Should the analyzer permit mutations to data reachable from parameters if the function can prove the data was freshly allocated inside the function?
- The project name and module path are
constableandgithub.com/nnutter/constable.
The first milestone is a minimal but real analyzer:
- Create a Go module.
- Add a
nonmutatinganalyzer usinggo/analysisandbuildssa. - Parse
//constable:nonmutatingcomments on function and method declarations. - Detect direct pointer, receiver, slice, and map mutations in annotated functions.
- Add analyzer tests for the supported cases and explicit non-cases.
- Add a thin command-line entry point using
singlechecker.
This milestone should prioritize a small, reviewable implementation over a broad nonmutation model.