Release 0.0.6

- check for error wrapping related methods
- support for Go 1.26 new and errrors.AsType
- make variable heuristic optional
- copy flags from detect to errortype
- move suggestion logic to analyzer

Signed-off-by: Oliver Eikemeier <[email protected]>

Author: eikemeier

.custom-gcl.yaml

@@ -1,5 +1,5 @@
 ---
-version: v2.4.0
+version: v2.5.0
 
 name: golangci-lint
 destination: .

.github/workflows/test.yml

@@ -39,13 +39,11 @@ jobs:
       - name: 🧸 golangci-lint
         uses: golangci/golangci-lint-action@4afd733a84b1f43292c63897423277bb7f4313a9  # v8.0.0
         with:
-          version: v2.4.0
+          version: v2.5.0
       - name: 🔨 Test
         run: |
           (cd ./internal/analyze/testdata && go mod download)
           go test -coverprofile=cover.out ./...
-        env:
-          GOEXPERIMENT: aliastypeparams
       - name: 🧑🏻‍💻 codecov
         uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7  # v5.5.1
         if: ${{ matrix.update-meta }}

.gitignore

@@ -10,6 +10,7 @@
 !/.mockery.yaml
 !/.pre-commit-config.yaml
 !/.prettierrc.yaml
+!/.woodpecker/
 !/.yamlfmt
 !/.yamllint
 /bazel-*

.golangci.yaml

@@ -65,6 +65,27 @@ linters:
       exclude-functions:
         - (*os.File).Close
         - (io/fs.File).Close
+    goheader:
+      values:
+        const:
+          AUTHOR: Oliver Eikemeier
+          RANGE: "2025"
+      template: |-
+        Copyright {{ RANGE }} {{ AUTHOR }}. All Rights Reserved.
+
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+
+            http://www.apache.org/licenses/LICENSE-2.0
+
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+
+        SPDX-License-Identifier: Apache-2.0
     govet:
       enable-all: true
       disable:
@@ -94,9 +115,6 @@ linters:
         - name: error-strings
         - name: errorf
         - name: exported
-        - name: file-header
-          arguments:
-            - "Copyright 2025 Oliver Eikemeier. All Rights Reserved."
         - name: increment-decrement
         - name: indent-error-flow
         - name: range

.pre-commit-config.yaml

@@ -14,6 +14,6 @@ repos:
     hooks:
       - id: markdownlint-cli2
   - repo: https://github.com/golangci/golangci-lint
-    rev: v2.4.0
+    rev: v2.5.0
     hooks:
       - id: golangci-lint

.woodpecker/test.yaml

@@ -0,0 +1,19 @@
+---
+when:
+  - event: push
+    branch: [main, dev]
+
+matrix:
+  GO_VERSION:
+    - 1.25
+    - 1.24
+
+steps:
+  - name: test
+    image: golang:${GO_VERSION}
+    environment:
+      GOTOOLCHAIN: local
+    commands:
+      - go mod download && (cd ./internal/analyze/testdata && go mod download)
+      - echo "🔨 Testing on $(go version):"
+      - go test ./...

README.md

@@ -5,6 +5,7 @@
 [![CodeQL](https://github.com/fillmore-labs/errortype/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/fillmore-labs/errortype/actions/workflows/github-code-scanning/codeql)
 [![Coverage](https://codecov.io/gh/fillmore-labs/errortype/branch/main/graph/badge.svg?token=MMLHL14ZP6)](https://codecov.io/gh/fillmore-labs/errortype)
 [![Go Report Card](https://goreportcard.com/badge/fillmore-labs.com/errortype)](https://goreportcard.com/report/fillmore-labs.com/errortype)
+[![Codeberg CI](https://ci.codeberg.org/api/badges/15305/status.svg?branch=main)](https://ci.codeberg.org/repos/15305)
 [![License](https://img.shields.io/github/license/fillmore-labs/errortype)](https://www.apache.org/licenses/LICENSE-2.0)
 
 `errortype` is a Go static analysis tool (linter) that helps prevent subtle bugs in error handling and other areas. It
@@ -69,8 +70,9 @@ Usage: `errortype [-flag] [package]`
 - **-c** `<N>`: Display N lines of context around each issue (default: -1 for no context, 0 for only the offending
   line).
 - **-test**: Analyze test files in addition to source files (default: true).
-- **-heuristics**: (Experimental) List of heuristics used (default: “usage,receivers”, “off” to disable).
-- **-trace**: (Experimental) Output information for result tracing.
+- **-heuristics**: `<list>` (Experimental) List of heuristics used (default: “var,usage,receivers”, “off” to disable).
+- **-tracetypes**: `<regex>` (Experimental) Trace error type detection in packages with names matching the regular
+  expression.
 
 ## Inconsistent Error Type Usage
 
@@ -135,7 +137,15 @@ The linter determines an error type's intended use _(pointer vs. value)_ by anal
 1. **Overrides** (the highest priority): User-defined overrides (see [below](#override-file)) are applied, overriding
    any detected usage.
 
-2. **Package-Level Variable Assignments**: If present, `var _ error = ...` assignments are used as explicit declarations
+2. **`Unwrap` related methods**: If present, `Is`, `As` and `Unwrap` methods with pointer receiver would be not visible
+   from a value usage. If an error type would be used as a value, methods with pointer receivers are not in its
+   [method set](https://go.dev/ref/spec#Method_sets).
+
+   ```go
+   func (e *PointerError) Unwrap error { /* ...*/ } // Unwrap is only visible from error(&PointerError{}).
+   ```
+
+3. **Package-Level Variable Assignments**: If present, `var _ error = ...` assignments are used as explicit declarations
    of intent.
 
    ```go
@@ -144,7 +154,7 @@ The linter determines an error type's intended use _(pointer vs. value)_ by anal
    var _ error = (*PointerError)(nil) // Determines PointerError is a "pointer" type.
    ```
 
-3. **Usage Within Functions**: If still undecided, the linter analyzes usage within top-level functions (in `return`
+4. **Usage Within Functions**: If still undecided, the linter analyzes usage within top-level functions (in `return`
    statements or type assertions). Consistent usage can determine the type.
 
    ```go
@@ -155,7 +165,7 @@ The linter determines an error type's intended use _(pointer vs. value)_ by anal
 
    Note: This heuristic is a fallback and should not be relied upon for defining a type's contract.
 
-4. **Consistent Method Receivers** (lowest priority): As a final heuristic, if all methods on a type have a consistent
+5. **Consistent Method Receivers** (lowest priority): As a final heuristic, if all methods on a type have a consistent
    receiver (all-value or all-pointer), that style is used.
 
 ### Designing Linter-Friendly Packages
@@ -181,21 +191,8 @@ var (
 
 ### Overriding Detected Types
 
-When the linter reports types from an imported package that have ambiguous or inconsistent usage, you can guide the
-linter in two ways:
-
-1. **Local Overrides**: For a one-off fix within a single package, add a `var` block to a source file in that package.
-   This overrides the detected usage for that type _within this package only_.
-
-   ```go
-   // In your code, force a specific usage for an imported type.
-   var _ error = imported.ValueError{}
-
-   var _ error = (*imported.PointerError)(nil)
-   ```
-
-2. **Global Override File**: For project-wide overrides, use an `errortypes.yaml` file, see
-   _[“Override File”](#override-file)_.
+When the linter reports ambiguous or inconsistent usage from types of an imported package that you can not change, you
+can guide the linter with an override file, see _[“Override File”](#override-file)_.
 
 ## Pointless Comparisons
 
@@ -377,6 +374,12 @@ specific problems.
 - **`et:emb` (Embedded/Ambiguous Usage)**: The linter could not determine if an error is a pointer or value type. This
   can be resolved with an [override](#overriding-detected-types).
 
+- **`et:var` (Variable Mismatch)**: An error type is assigned incorrectly in a
+  [variable declaration](https://go.dev/ref/spec#Variable_declarations) starting with `Err` or `err`.
+
+- **`et:rcv` (Receiver Mismatch)**: An `Unwrap` related method on a value error should be implemented with a value
+  receiver, not a pointer, otherwise it wouldn't be visible.
+
 ### Pointer Comparison Issues
 
 - **`et:cmp` (Pointless Error Comparison)**: A pointer is compared against the address of a newly created value in
@@ -458,7 +461,10 @@ specific problems.
   type implementing `error`). This is also flagged by the standard Go
   [`errorsas`](https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/errorsas) linter.
 
-- **`et:auc` (Unchecked Type Assert)**: An unchecked type assert might lead to a run-time panic on a wrapped error.
+- **`et:sig` (Wrong Signature)**: An `Unwrap` related method has the wrong signature. This is also flagged by the
+  standard Go [`stdmethods`](https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/stdmethods) linter.
+
+- **`et:uca` (Unchecked Type Assert)**: An unchecked type assert might lead to a run-time panic on a wrapped error.
 
   ```go
     if err.(*net.AddrError).Err == "missing port in address" { /* ... */ }
@@ -474,15 +480,15 @@ Add a file `.custom-gcl.yaml` to your source with
 
 ```yaml
 ---
-version: v2.4.0
+version: v2.5.0
 
 name: golangci-lint
 destination: .
 
 plugins:
   - module: fillmore-labs.com/errortype
     import: fillmore-labs.com/errortype/gclplugin
-    version: v0.0.5
+    version: v0.0.6
 ```
 
 then run `golangci-lint custom` from your project root. You get a custom `golangci-lint` executable that can be

analyzer/analyzer.go

@@ -17,67 +17,18 @@
 package analyzer
 
 import (
-	"reflect"
-
 	"golang.org/x/tools/go/analysis"
-	"golang.org/x/tools/go/analysis/passes/inspect"
 
 	"fillmore-labs.com/errortype/detect"
-	"fillmore-labs.com/errortype/internal/analyze"
-)
-
-// Documentation constants.
-const (
-	Name = "errortype"
-	Doc  = `errortype is a Go static analysis tool that helps prevent subtle bugs in error handling.
-
-It performs two main checks:
-
-1. Inconsistent Error Type Usage: It analyzes function returns, type assertions,
-   and calls to functions like errors.As to ensure that custom error types
-   are used consistently as either pointers or values.
-
-2. Pointless Pointer Comparisons: It detects comparisons of pointers against
-   the address of a newly created value (e.g., 'ptr == &MyStruct{}'), which
-   are almost always incorrect.
-
-For inconsistent error type usage, it automatically determines the correct usage
-for most error types but may require a configuration file for ambiguous cases.`
-
-	URL = "https://pkg.go.dev/fillmore-labs.com/errortype/analyzer"
 )
 
 // New creates a new instance of the errortype analyzer.
-// It allows for programmatic configuration using [Option]s, which is useful
+// It allows for programmatic configuration using [Options], which is useful
 // for integrating the analyzer into other tools. For command-line use, the
 // pre-configured [Analyzer] variable is typically sufficient.
 func New(opts ...Option) *analysis.Analyzer {
-	o := makeOptions(opts)
-
-	if o.DetectTypes == nil {
-		o.DetectTypes = detect.New()
-	}
-
-	a := &analysis.Analyzer{
-		Name:       Name,
-		Doc:        Doc,
-		URL:        URL,
-		Run:        o.Run,
-		Requires:   []*analysis.Analyzer{inspect.Analyzer, o.DetectTypes},
-		ResultType: reflect.TypeFor[analyze.Result](),
-	}
-
-	a.Flags.BoolVar(&o.StyleCheck, "style-check", o.StyleCheck, "check for confusing uses of errors.As")
-
-	a.Flags.BoolVar(&o.CheckIs, "check-is", o.CheckIs,
-		`suppress compare diagnostic on errors.Is if the compared type has an "Is(error) bool" method`)
-
-	a.Flags.BoolVar(&o.DeepIsCheck, "deep-is-check", o.DeepIsCheck, `diagnose all "Unwrap" functions in "Is" methods, not only on target`)
-
-	a.Flags.BoolVar(&o.UncheckedAssert, "unchecked-assert", o.UncheckedAssert, `report unchecked type asserts on errors`)
-
-	return a
+	return makeOptions(opts).Analyzer()
 }
 
-// Analyzer is a pre-configured *analysis.Analyzer for detecting and enforcing consistent error type usage in Go programs.
+// Analyzer is a pre-configured *[analysis.Analyzer] for detecting and enforcing consistent error type usage in Go programs.
 var Analyzer = New(WithDetectTypes(detect.Analyzer))

analyzer/options.go

@@ -35,7 +35,7 @@ func makeOptions(opts Options) *analyze.Options {
 // Option configures specific behavior of a [New] errortype [analysis.Analyzer].
 type Option interface {
 	apply(opts *analyze.Options)
-	SlogAttr() slog.Attr
+	LogAttr() slog.Attr
 }
 
 // Options is a list of [Option] values that also satisfies the [Option] interface.
@@ -51,28 +51,28 @@ func (o Options) apply(opts *analyze.Options) {
 func (o Options) LogValue() slog.Value {
 	as := make([]slog.Attr, 0, len(o))
 	for _, opt := range o {
-		as = append(as, opt.SlogAttr())
+		as = append(as, opt.LogAttr())
 	}
 
 	return slog.GroupValue(as...)
 }
 
-// SlogAttr returns a [slog.Attr] for logging.
-func (o Options) SlogAttr() slog.Attr {
+// LogAttr returns a [slog.Attr] for logging.
+func (o Options) LogAttr() slog.Attr {
 	return slog.Any("options", o)
 }
 
 // WithDetectTypes sets a custom *[analysis.Analyzer] for detecting error types.
-func WithDetectTypes(detecttypes *analysis.Analyzer) Option {
-	return detectTypesOption{detecttypes: detecttypes}
+func WithDetectTypes(detectTypes *analysis.Analyzer) Option {
+	return detectTypesOption{detectTypes: detectTypes}
 }
 
-type detectTypesOption struct{ detecttypes *analysis.Analyzer }
+type detectTypesOption struct{ detectTypes *analysis.Analyzer }
 
-func (o detectTypesOption) apply(opts *analyze.Options) { opts.DetectTypes = o.detecttypes }
+func (o detectTypesOption) apply(opts *analyze.Options) { opts.DetectTypes = o.detectTypes }
 
-func (o detectTypesOption) SlogAttr() slog.Attr {
-	return slog.String("detect", o.detecttypes.Name)
+func (o detectTypesOption) LogAttr() slog.Attr {
+	return slog.String("detect", o.detectTypes.Name)
 }
 
 // WithStyleCheck is an [Option] to configure the style check.
@@ -82,7 +82,7 @@ type styleCheckOption struct{ styleCheck bool }
 
 func (o styleCheckOption) apply(opts *analyze.Options) { opts.StyleCheck = o.styleCheck }
 
-func (o styleCheckOption) SlogAttr() slog.Attr {
+func (o styleCheckOption) LogAttr() slog.Attr {
 	return slog.Bool("styleCheck", o.styleCheck)
 }
 
@@ -97,13 +97,13 @@ type checkIsOption struct{ checkIs bool }
 
 func (o checkIsOption) apply(opts *analyze.Options) { opts.CheckIs = o.checkIs }
 
-func (o checkIsOption) SlogAttr() slog.Attr {
+func (o checkIsOption) LogAttr() slog.Attr {
 	return slog.Bool("checkIs", o.checkIs)
 }
 
 // WithDeepIsCheck is an [Option] to configure `Is` method analysis.
 // If deepIsCheck is true, the analyzer will flag every method calling `Unwrap`.
-// The default behavior is to flag only applications to `target“.
+// The default behavior is to flag only applications to `target`.
 func WithDeepIsCheck(deepIsCheck bool) Option {
 	return deepIsCheckOption{deepIsCheck: deepIsCheck}
 }
@@ -112,7 +112,7 @@ type deepIsCheckOption struct{ deepIsCheck bool }
 
 func (o deepIsCheckOption) apply(opts *analyze.Options) { opts.DeepIsCheck = o.deepIsCheck }
 
-func (o deepIsCheckOption) SlogAttr() slog.Attr {
+func (o deepIsCheckOption) LogAttr() slog.Attr {
 	return slog.Bool("deepIsCheck", o.deepIsCheck)
 }
 
@@ -125,6 +125,6 @@ type uncheckedAssertOption struct{ uncheckedAssert bool }
 
 func (o uncheckedAssertOption) apply(opts *analyze.Options) { opts.UncheckedAssert = o.uncheckedAssert }
 
-func (o uncheckedAssertOption) SlogAttr() slog.Attr {
+func (o uncheckedAssertOption) LogAttr() slog.Attr {
 	return slog.Bool("uncheckedAssert", o.uncheckedAssert)
 }

analyzer/options_test.go

@@ -78,7 +78,7 @@ func TestLogValue(t *testing.T) {
 
 			var sb strings.Builder
 			logger := slog.New(slog.NewJSONHandler(&sb, nil))
-			logger.LogAttrs(t.Context(), slog.LevelInfo, "test", tt.option.SlogAttr())
+			logger.LogAttrs(t.Context(), slog.LevelInfo, "test", tt.option.LogAttr())
 
 			got := sb.String()
 			if !strings.Contains(got, tt.expected) {