Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Error Codes Reference

GoGreement reports violations using structured error codes. Each code identifies a specific type of violation and can be used with the @ignore annotation to suppress false positives.

Code Structure

Error codes follow the format: [CATEGORY][NUMBER]

  • Category: 2-4 letter prefix identifying the annotation (e.g., IMM, CTOR, TONL, PKGO, IMPL)
  • Number: Two-digit sequential number within the category (e.g., 01, 02)

Example: IMM01 = Immutable category, violation type 01

All Error Codes

IMM - Immutable Violations

Violations of @immutable annotations. These can be suppressed with @ignore.

CodeDescriptionExample
IMM01Field of immutable type is being assignedpoint.X = 10
IMM02Compound assignment to immutable fieldpoint.X += 5, count *= 2
IMM03Increment/decrement of immutable fieldpoint.X++, count--
IMM04Index assignment to immutable collectionobj.items[0] = value, obj.dict["key"] = val

Suppress with:

  • // @ignore IMM - All immutability checks
  • // @ignore IMM01 - Specific check only

Documentation: @immutable

CTOR - Constructor Violations

Violations of @constructor annotations. These can be suppressed with @ignore.

CodeDescriptionExample
CTOR01Composite literal used outside allowed constructor functionsdb := Database{}
CTOR02new() call used outside allowed constructor functionsdb := new(Database)
CTOR03Variable declaration creates zero-initialized instance outside allowed constructor functionsvar db Database

Suppress with:

  • // @ignore CTOR - All constructor checks
  • // @ignore CTOR01 - Specific check only

Documentation: @constructor

TONL - TestOnly Violations

Violations of @testonly annotations. These can be suppressed with @ignore.

CodeDescriptionExample
TONL01TestOnly type used outside test contextvar mock MockService in production code
TONL02TestOnly function called outside test contextCreateMock() in production code
TONL03TestOnly method called outside test contextservice.ResetForTesting() in production code

Suppress with:

  • // @ignore TONL - All testonly checks
  • // @ignore TONL01 - Specific check only

Documentation: @testonly

PKGO - PackageOnly Violations

Violations of @packageonly annotations. These can be suppressed with @ignore.

CodeDescriptionExample
PKGO01PackageOnly type used outside allowed packagesvar helper InternalHelper in unauthorized package
PKGO02PackageOnly function called outside allowed packagesExecuteAdminCommand() in unauthorized package
PKGO03PackageOnly method called outside allowed packagesrepo.InsertTestData() in unauthorized package

Suppress with:

  • // @ignore PKGO - All packageonly checks
  • // @ignore PKGO01 - Specific check only

Documentation: @packageonly

IMPL - Implements Violations

Violations of @implements annotations. These can be suppressed with @ignore.

CodeDescriptionExample
IMPL01Package not found in importsUsing @implements pkg.Interface without importing pkg
IMPL02Interface not found in packageInterface name doesn't exist or is misspelled
IMPL03Missing or incorrect methodsType doesn't implement all required methods with correct signatures

Suppress with:

  • // @ignore IMPL - All implements checks
  • // @ignore IMPL01 - Specific check only

Documentation: @implements

Using Error Codes

With @ignore Annotation

Suppress specific violations in your code:

// Suppress specific code
// @ignore IMM01
point.X = 10

// Suppress multiple codes
// @ignore IMM01, CTOR02
func unsafeOperation() {
    point.X = 10
    db := new(Database)
}

// Suppress entire category
// @ignore IMM
func batchUpdate() {
    // All IMM* codes suppressed
}

// Suppress all violations
// @ignore ALL
func debugFunction() {
    // Everything suppressed
}

With Command-Line Flags

Exclude checks globally across your project:

# Exclude all immutability checks
gogreement --config.exclude-checks=IMM ./...

# Exclude specific codes
gogreement --config.exclude-checks=IMM01,CTOR02,TONL03 ./...

# Exclude multiple categories
gogreement --config.exclude-checks=IMM,TONL ./...

With Environment Variables

Set project-wide defaults:

export GOGREEMENT_EXCLUDE_CHECKS=IMM01,CTOR
gogreement ./...

Code Hierarchy

Codes follow a hierarchical structure for suppression:

ALL
├── IMM (Immutable)
│   ├── IMM01 (Field assignment)
│   ├── IMM02 (Compound assignment)
│   ├── IMM03 (Increment/decrement)
│   └── IMM04 (Index assignment)
├── CTOR (Constructor)
│   ├── CTOR01 (Composite literal)
│   ├── CTOR02 (new() call)
│   └── CTOR03 (Var declaration)
├── TONL (TestOnly)
│   ├── TONL01 (Type usage)
│   ├── TONL02 (Function call)
│   └── TONL03 (Method call)
├── PKGO (PackageOnly)
│   ├── PKGO01 (Type usage)
│   ├── PKGO02 (Function call)
│   └── PKGO03 (Method call)
└── IMPL (Implements)
    ├── IMPL01 (Package not found)
    ├── IMPL02 (Interface not found)
    └── IMPL03 (Missing methods)

When you suppress a code at any level, all codes below it are also suppressed:

  • @ignore ALL → Suppresses everything
  • @ignore IMM → Suppresses IMM01, IMM02, IMM03, IMM04
  • @ignore IMM01 → Suppresses only IMM01

Quick Reference by Annotation

AnnotationDescriptionCodes
@immutablePrevents field mutationsIMM01, IMM02, IMM03, IMM04
@constructorRestricts object creationCTOR01, CTOR02, CTOR03
@testonlyLimits to test filesTONL01, TONL02, TONL03
@packageonlyLimits to specific packagesPKGO01, PKGO02, PKGO03
@implementsVerifies interface implementationIMPL01, IMPL02, IMPL03

Error Message Format

GoGreement error messages include the error code for easy reference:

path/to/file.go:15:2: IMM01 - Field of immutable type is being assigned
path/to/file.go:23:5: CTOR01 - Composite literal used outside allowed constructor functions
path/to/file.go:45:10: TONL02 - TestOnly function called outside test context

Best Practices

1. Be Specific

Use the most specific code possible when suppressing:

// ✅ Good
// @ignore IMM01
point.X = 10

// ❌ Too broad
// @ignore ALL
point.X = 10

2. Document Suppressions

Always explain why you're suppressing a check:

// @ignore IMM01
// REASON: Performance-critical path, avoiding allocations
// TODO: Refactor to use copy-on-write
cache.data[key] = value

3. Prefer Fixing Over Suppressing

Suppression should be the exception, not the rule:

// ❌ Bad: Suppressing instead of fixing
// @ignore IMM
type Point struct { X, Y int }

// ✅ Good: Fix the architecture
// Remove @immutable if mutation is required
type Point struct { X, Y int }

4. Review Suppressions Regularly

Periodically search for @ignore in your codebase and review whether suppressions are still needed.

See Also