README
¶
retrogolint - a linter for retrogolib projects
Installation
go install github.com/retroenv/retrogolint/cmd/retrogolint@latest
Requirements:
- Go 1.22 or later
Overview
Retrogolint is a Go static analyzer for projects built around retrogolib.
It checks retrogolib-specific logging conventions, testing style, collection usage, and code organization rules that are not covered by general-purpose Go linters.
Key Design Principles
- retrogolib-aware rules: Encodes conventions for retrogolib logging, assertions, collections, and package structure
- AST-based analysis: Uses Go's standard parser and AST model for deterministic checks
- CI-friendly output: Supports concise text output and structured JSON output
- Configurable scope: Enables rule/category selection, global exclusions, and per-rule exclusions
- Small command-line tool: Builds as a static CLI with no runtime service dependencies
Rule Coverage
Current Support
- Logging: Message capitalization, field casing, nil checks, zero-value loggers, formatting helpers, specialized fields, and eager field evaluation
- Testing: Manual assertion patterns that should use
retrogolib/assert - Collections: Set-like
map[K]boolandmap[K]struct{}patterns that should useretrogolib/set - Code quality: Top-level declaration order, parameter priority, and exported type stutter
codequality-funcorder also enforces that unexported dependency types are declared before the exported types that use them.
See docs/rules.md for the complete rule list.
Features
Command-Line Analysis
- Analyze files, directories, and Go package patterns such as
./... - Select rules by exact rule name or by category
- Filter reported violations by minimum severity
- Exclude test files, directories, and filename or relative path patterns
Configuration
- Read
.retrogolint.iniby default - Override file settings with command-line flags
- Configure global exclusions and per-rule exclusions
- See docs/configuration.md for the full configuration reference
Package Overview
├─ cmd/retrogolint command-line entry point
├─ docs configuration, rules, and development reference
├─ internal/analyzer package/file expansion and parallel AST analysis
├─ internal/cli command-line flag parsing and config merging
├─ internal/linterconfig configuration loading and exclusion rules
├─ internal/reporter text and JSON output formatting
├─ internal/rules built-in lint rule registry and implementations
├─ internal/violation shared violation and severity model
├─ internal/workflow high-level analysis orchestration
├─ testdata valid and invalid rule fixtures
Quick Start
CLI Usage
Analyze the current module:
retrogolint ./...
Analyze a package tree:
retrogolint ./internal/compiler/...
Output JSON for CI or tooling:
retrogolint -format json ./...
Run only logging rules:
retrogolint -rules logging ./...
Disable a rule or category:
retrogolint -disabled-rules collections-map-set ./...
Show command usage:
usage: retrogolint [options] [packages...]
Parameters:
-config string
Configuration file path (default: .retrogolint.ini)
Options:
-severity string
Minimum severity to report: error, warning, info (default: warning)
-rules string
Comma-separated list of rule categories to check (default: all rules)
-disabled-rules string
Comma-separated list of rules/categories to disable
-max-per-rule int
Maximum violations per rule (0 = unlimited)
-exclude-tests
Exclude test files from analysis
-exclude-dirs string
Comma-separated list of directories to exclude
-exclude-files string
Comma-separated list of filename or relative path patterns to exclude
-version
Show version information
Output options:
-format string
Output format: text, json (default: text)
Positional arguments:
packages...
packages to analyze
If no paths are provided, retrogolint analyzes ./....
Development
make build
make lint
make test
See docs/development.md for release checks and local development commands.
License
This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
retrogolint
command
Package main is the entry point for the retrogolint linter tool.
|
Package main is the entry point for the retrogolint linter tool. |
|
internal
|
|
|
analyzer
Package analyzer performs static analysis on Go source files.
|
Package analyzer performs static analysis on Go source files. |
|
cli
Package cli provides command-line interface parsing and configuration.
|
Package cli provides command-line interface parsing and configuration. |
|
linterconfig
Package linterconfig provides configuration management for the linter.
|
Package linterconfig provides configuration management for the linter. |
|
reporter
Package reporter provides formatters for outputting linting violations.
|
Package reporter provides formatters for outputting linting violations. |
|
reporter/formats/jsonreport
Package jsonreport holds the JSON reporter implementation for lint violations.
|
Package jsonreport holds the JSON reporter implementation for lint violations. |
|
reporter/formats/textreport
Package textreport holds the text reporter implementation for lint violations.
|
Package textreport holds the text reporter implementation for lint violations. |
|
rules
Package rules wires all lint rules and helpers into a single registry.
|
Package rules wires all lint rules and helpers into a single registry. |
|
rules/api
Package api exposes shared types and helpers used by the rules packages.
|
Package api exposes shared types and helpers used by the rules packages. |
|
rules/codequality
Package codequality contains rules for code quality and organization.
|
Package codequality contains rules for code quality and organization. |
|
rules/collections
Package collections contains rules for collection usage patterns.
|
Package collections contains rules for collection usage patterns. |
|
rules/logging/fields
Package loggingfields contains rules that validate logger field usage.
|
Package loggingfields contains rules that validate logger field usage. |
|
rules/logging/formatting
Package loggingformatting contains rules for log formatting, preferring dedicated helpers over fmt.
|
Package loggingformatting contains rules for log formatting, preferring dedicated helpers over fmt. |
|
rules/logging/message
Package loggingmessage contains rules that inspect log message content and nil checks.
|
Package loggingmessage contains rules that inspect log message content and nil checks. |
|
rules/logging/performance
Package loggingperformance contains rules that flag inefficient logging patterns.
|
Package loggingperformance contains rules that flag inefficient logging patterns. |
|
rules/testing
Package testing provides linting rules for test code patterns.
|
Package testing provides linting rules for test code patterns. |
|
violation
Package violation defines types for representing linting violations.
|
Package violation defines types for representing linting violations. |
|
workflow
Package workflow provides high-level orchestration of analysis operations.
|
Package workflow provides high-level orchestration of analysis operations. |
Click to show internal directories.
Click to hide internal directories.