goidiomatic

README

go-idiomatic

A pedagogical Go-idiom linter. Rules beyond gopls and golangci-lint, aimed at the layer of feedback you want when learning Go: "this compiles, but it isn't how Go is usually written." Part of the CivNode Training semantic engine.

Apache-2.0 licensed. No runtime dependencies outside golang.org/x/tools/go/analysis.

Install

Library:

go get github.com/CivNode/go-idiomatic@latest

Standalone linter:

go install github.com/CivNode/go-idiomatic/cmd/go-idiomatic@latest
go-idiomatic ./...

Library usage

import goidiomatic "github.com/CivNode/go-idiomatic"

score, findings, err := goidiomatic.Score(src, goidiomatic.DefaultRules())

Score returns an integer on [0, 100] plus every finding. The score starts at 100 and deducts per severity: 15 for Error, 7 for Warn, 2 for Info, floored at 0.

Rules (v0.1.0)

ID	Severity	What it catches
prefer-range-int	info	for i := 0; i < len(xs); i++ where for i := range xs would do
errors-is-as	warn	err.Error() == "..." or err == someErr; use errors.Is / errors.As
any-over-empty-interface	info	interface{} on a Go 1.18+ target; suggests any
context-first-arg	warn	functions where context.Context is not the first argument
no-sleep-for-coordination	error	time.Sleep inside a function that also uses channels or context.Context

Each rule ships with golden fixtures under rules/testdata/src/<fixture>/.

Adding a rule

1. Drop a new file in rules/, implementing the Rule interface.
2. Add it to rules.All.
3. Add testdata/src/<name>_ok/ok.go and testdata/src/<name>_bad/bad.go fixtures, using // want ... comments on lines that must flag.
4. Write a test with analysistest.Run plus a few in-memory rules.Run unit tests for the edge cases.
5. make lint test must stay clean.

Status

v0.1.0 ships the five rules above with >= 85% coverage on the rules package. Future tiers extend the ruleset and add fixers.

Documentation

Overview

Package goidiomatic is a pedagogical Go-idiom linter.

Rules live under the rules/ subpackage. Each rule implements the Rule interface and ships with golden fixtures under rules/testdata/<id>/ (ok.go for code that must not flag, bad.go for code that must flag).

The Score function aggregates rule findings into a 0..100 score, deducting per severity level.

See https://github.com/CivNode/go-idiomatic for details.

Index

• Constants
• type Finding
  • func Score(src []byte, ruleset []Rule) (int, []Finding, error)
• type Fix
• type Rule
  • func DefaultRules() []Rule
• type Severity
• type TextEdit

Constants

const (
	Info  = rules.Info
	Warn  = rules.Warn
	Error = rules.Error
)

Severity levels re-exported from the rules package so callers can write goidiomatic.Error etc. without importing the subpackage directly.

Types

type Finding

type Finding = rules.Finding

Finding is one hit on a Rule.

func Score

func Score(src []byte, ruleset []Rule) (int, []Finding, error)

Score parses src, runs each rule against it, and returns an aggregate score on [0, 100] plus all findings. The score starts at 100 and deducts 15 per Error, 7 per Warn, 2 per Info, floored at 0.

Score is deliberately single-file and loader-free so callers can grade snippets straight from memory. For package-level analysis use the analyzer exposed by the rules package with the standard analysis driver instead.

type Fix

type Fix = rules.Fix

Fix is an optional suggested edit attached to a Finding.

type Rule

type Rule = rules.Rule

Rule is a single pedagogical check.

func DefaultRules

func DefaultRules() []Rule

DefaultRules returns the built-in ruleset in a stable order. The returned slice is a fresh copy; callers may reorder or extend it without affecting future calls.

type Severity

type Severity = rules.Severity

Severity grades how strong a finding is.

type TextEdit

type TextEdit = rules.TextEdit

TextEdit is a single replacement in source.