gogenfilter

gogenfilter

A Go library for detecting and filtering auto-generated code files. Designed for linters, static analysis tools, and code quality tools that need to skip generated output.

Supported Generators

Features

• Two-phase detection: Filename-based first (zero I/O), then content-based (reads file)
• Functional options API: Clean, composable configuration
• Custom patterns: Include/exclude patterns with ** glob support
• Thread-safe metrics: Track what was filtered and why
• SQLC config discovery: Parse sqlc.yaml/sqlc.yml to find output directories
• fs.FS abstraction: Pluggable filesystem for testing

Install

go get github.com/LarsArtmann/gogenfilter

Quick Start

package main

import (
    "fmt"
    "github.com/LarsArtmann/gogenfilter"
)

func main() {
    f := gogenfilter.NewFilter(
        gogenfilter.Enabled(),
        gogenfilter.WithFilterOptions(gogenfilter.FilterAll),
    )

    filtered, err := f.ShouldFilter("db/models.go")
    if err != nil {
        panic(err)
    }

    if filtered {
        fmt.Println("skipping generated file")
    }

    stats := f.GetStats()
    fmt.Printf("Checked: %d, Filtered: %d\n",
        stats.TotalFilesChecked, stats.TotalFiltered())
}

Configuration

NewFilter accepts functional options:

// Filter all known generated code
gogenfilter.NewFilter(
    gogenfilter.Enabled(),
    gogenfilter.WithFilterOptions(gogenfilter.FilterAll),
)

// Filter specific generators only
gogenfilter.NewFilter(
    gogenfilter.Enabled(),
    gogenfilter.WithFilterOptions(gogenfilter.FilterSQLC, gogenfilter.FilterTempl),
)

// With include/exclude patterns
gogenfilter.NewFilter(
    gogenfilter.Enabled(),
    gogenfilter.WithFilterOptions(gogenfilter.FilterAll),
    gogenfilter.WithIncludePatterns("pkg/**", "internal/*.go"),
    gogenfilter.WithExcludePatterns("**/*.pb.go", "mocks/*"),
)

// With custom filesystem (for testing)
gogenfilter.NewFilter(
    gogenfilter.Enabled(),
    gogenfilter.WithFilterOptions(gogenfilter.FilterAll),
    gogenfilter.WithFS(myFS),
)

// Disabled filter (passes everything through)
gogenfilter.NewFilter(gogenfilter.Disabled())

Filter Options

Pattern Matching

Include and exclude patterns support two wildcards:

Rules

• Include patterns restrict the scope: only files matching at least one include pattern are checked for generated code. All other files are immediately filtered (skipped). If no include patterns are set, all files are considered.
• Exclude patterns broaden the scope: files matching any exclude pattern are always filtered, regardless of generated-code detection.
• Patterns without / match against the filename only: *.pb.go matches any/path/user.pb.go
• Patterns with / match against the full path: internal/*.go matches internal/handler.go
• **/ at the start matches at any depth: \*_/mocks/_.gomatchespkg/mocks/service.go
• /** at the end matches anything under a directory: generated/\*\*matchesgenerated/a/b/c.go
• /**/ in the middle bridges any number of segments: src/\*\*/test.gomatchessrc/pkg/test.go

Examples

gogenfilter.NewFilter(
    gogenfilter.Enabled(),
    gogenfilter.WithIncludePatterns("pkg/**"),         // everything under pkg/
    gogenfilter.WithExcludePatterns("**/*.pb.go"),      // any .pb.go at any depth
)

Detection Functions

Use low-level detection directly without the Filter struct:

// Check by filename + content (both phases)
gogenfilter.IsSQLCGenerated("db/models.go", content)
gogenfilter.IsTemplGenerated("page_templ.go", content)
gogenfilter.IsGoEnumGenerated("status_enum.go", content)
gogenfilter.IsProtobufGenerated("user.pb.go", content)
gogenfilter.IsOapiGenerated("petstore.gen.go", content)
gogenfilter.IsDeepcopyGenerated("zz_generated.deepcopy.go", content)
gogenfilter.IsWireGenerated("wire_gen.go", content)
gogenfilter.IsMoqGenerated("service_moq.go", content)
gogenfilter.IsMockgenGenerated("service_mock.go", content)
gogenfilter.IsStringerGenerated("status_string.go", content)
gogenfilter.IsGenericGenerated("any_file.go", content)

// Check by filename only (zero I/O)
gogenfilter.MatchesSQLCFilename("db/query.sql.go") // true

// Check content patterns
gogenfilter.HasSQLCContent(content)
gogenfilter.HasSQLCCodePatterns(content)

// Combined detection with variadic options
reason := gogenfilter.DetectReason("file.go", content,
    gogenfilter.FilterSQLC,
    gogenfilter.FilterTempl,
    gogenfilter.FilterGeneric,
)

SQLC Config Discovery

configs, err := gogenfilter.FindSQLCConfigs([]string{"./..."})
dirs, err := gogenfilter.GetSQLOutputDirs([]string{"."})

Metrics

f := gogenfilter.NewFilter(
    gogenfilter.Enabled(),
    gogenfilter.WithFilterOptions(gogenfilter.FilterAll),
)

filtered, _ := f.ShouldFilter("db/models.go")
filtered, _ = f.ShouldFilter("page_templ.go")
filtered, _ = f.ShouldFilter("main.go")

stats := f.GetStats()
// stats.TotalFilesChecked == 3
// stats.FilteredBy(gogenfilter.ReasonSQLC) == 1
// stats.FilteredBy(gogenfilter.ReasonTempl) == 1
// stats.TotalFiltered() == 2

License

MIT