196 lines (165 loc) · 22.5 KB

Features

Updated: 2026-08-10 Version: v3.4.0+ (unreleased: config-aware sqlc detection, header-only scanning, FileReadError) Source: Code audit of all source files + website features

Core Detection

Feature	Status	Details
sqlc detection	FULLY_FUNCTIONAL	Filename patterns (`.sql.go` suffix) + content markers (`Code generated by sqlc`, `sqlc` + `versions:`, code patterns like `sqlc.Arg`) + config-aware phase 1.5*: lazily parses `sqlc.yaml`/`sqlc.yml` and classifies `models.go`, `db.go`, `querier.go`, `batch.go`, `copyfrom.go` in declared output dirs as sqlc-generated even without a header comment
templ detection	FULLY_FUNCTIONAL	`_templ.go` suffix + `templ.Component` or `Render(ctx context.Context, w io.Writer)` content
go-enum detection	FULLY_FUNCTIONAL	`_enum.go` suffix + `Code generated by go-enum` content
protobuf detection	FULLY_FUNCTIONAL	`.pb.go` / `_grpc.pb.go` suffix + `Code generated by` content
oapi-codegen detection	FULLY_FUNCTIONAL	Content marker `oapi-codegen` (no filename heuristic)
deepcopy-gen detection	FULLY_FUNCTIONAL	`zz_generated.*` prefix + `Code generated by deepcopy-gen` content
wire detection	FULLY_FUNCTIONAL	`wire_gen.go` suffix + `Code generated by Wire` content
moq detection	FULLY_FUNCTIONAL	`_moq.go` suffix + `Code generated by moq` content
mockgen detection	FULLY_FUNCTIONAL	`_mock.go` suffix + `Code generated by MockGen` content
stringer detection	FULLY_FUNCTIONAL	Content marker `Code generated by "stringer"`
mockery detection	FULLY_FUNCTIONAL	`mock_` prefix + `Code generated by mockery` content (exclusive ownership of mock_ prefix)
ent detection	FULLY_FUNCTIONAL	`Code generated by ent` / `Code generated by entc` content
gqlgen detection	FULLY_FUNCTIONAL	Content marker `Code generated by github.com/99designs/gqlgen` (no filename heuristic — `generated.go` too generic)
easyjson detection	FULLY_FUNCTIONAL	`_easyjson.go` suffix + `Code generated by easyjson` content
msgp detection	FULLY_FUNCTIONAL	Content marker `Code generated by github.com/tinylib/msgp` (no filename heuristic — `_gen.go` too generic)
counterfeiter detection	FULLY_FUNCTIONAL	`fake_` prefix + `Code generated by counterfeiter` content
go-swagger detection	FULLY_FUNCTIONAL	Content marker `Code generated by go-swagger`
Generic fallback detection	FULLY_FUNCTIONAL	Any `// Code generated by` comment per go.dev/s/generatedcode

Filter API

Feature	Status	Details
Functional options API	FULLY_FUNCTIONAL	`NewFilter(WithFilterOptions(FilterAll))` — enabled when options/patterns provided
Enable/disable toggle	FULLY_FUNCTIONAL	Implicit: `NewFilter()` = disabled, `NewFilter(WithFilterOptions(...))` = enabled
Selective generator filtering	FULLY_FUNCTIONAL	`WithFilterOptions(FilterSQLC, FilterTempl, ...)`
FilterAll expansion	FULLY_FUNCTIONAL	Expands to all specific + generic detectors
Custom filesystem	FULLY_FUNCTIONAL	`WithFS(fs.FS)` for testability with `fstest.MapFS`
Include patterns	FULLY_FUNCTIONAL	`WithIncludePatterns("*/pkg/.go")` — whitelist scope
Exclude patterns	FULLY_FUNCTIONAL	`WithExcludePatterns("*/.pb.go")` — always filter matches
Filter immutability	FULLY_FUNCTIONAL	Filter is immutable after `NewFilter` construction
Filter with error	FULLY_FUNCTIONAL	`(bool, error)` — propagates I/O errors
FilterResult struct	FULLY_FUNCTIONAL	`Filtered`, `Reason`, `Path`, `Trace` fields for structured results
FilterDetailed()	FULLY_FUNCTIONAL	`(FilterResult, error)` with trace info — additive API alongside `Filter()`
FilterPathsDetailed()	FULLY_FUNCTIONAL	Batch `([]FilterResult, error)` with trace info
AllGeneratorOptions()	FULLY_FUNCTIONAL	Enumerate detector options (excludes `FilterAll`)
FilterOption.Reason()	FULLY_FUNCTIONAL	Returns `(FilterReason, bool)` — no panics
FilterReasons()	FULLY_FUNCTIONAL	Returns enabled reasons
IsEnabled()	FULLY_FUNCTIONAL	Reports filter state
String() debugging	FULLY_FUNCTIONAL	Human-readable filter state

Pattern Matching

Feature	Status	Details
Glob `*` wildcard	FULLY_FUNCTIONAL	Matches non-separator characters
Glob `**` wildcard	FULLY_FUNCTIONAL	Matches zero+ path segments via doublestar/v4
Glob `?` wildcard	FULLY_FUNCTIONAL	Matches single character
Filename-only patterns	FULLY_FUNCTIONAL	Patterns without `/` match against basename
Absolute path handling	FULLY_FUNCTIONAL	Auto-prepends `**/` for relative patterns

Detection API (Low-Level)

Feature	Status	Details
DetectReason (no I/O)	FULLY_FUNCTIONAL	Filename + content, caller provides content
DetectReasonReader	FULLY_FUNCTIONAL	From `io.Reader`, reads content internally
DetectReasonFile	FULLY_FUNCTIONAL	Two-phase detection (filename + content) in one call
DetectReasonFileFS	FULLY_FUNCTIONAL	Same with pluggable `fs.FS`
FilterWithContent	FULLY_FUNCTIONAL	Avoid double I/O by passing pre-read content
FilterDetailedWithContent	FULLY_FUNCTIONAL	Same with trace info
FilterDetailedAndContent	FULLY_FUNCTIONAL	Lazy read + return content, no double-read
Individual Is* functions	FULLY_FUNCTIONAL	18 exported `Is*Generated` functions
ScanProject	FULLY_FUNCTIONAL	Walk `fs.FS`, detect all generated files
ExclusionPattern()	FULLY_FUNCTIONAL	Get regex pattern for a generator's filenames

SQLC Config Discovery

Feature	Status	Details
Find SQLC configs (OS)	FULLY_FUNCTIONAL	`FindSQLCConfigs` walks directories + parents
Find SQLC configs (fs.FS)	FULLY_FUNCTIONAL	`FindSQLCConfigsFS` — pluggable filesystem
Parse sqlc.yaml	FULLY_FUNCTIONAL	YAML parsing with `go-faster/yaml`
Extract output dirs (OS)	FULLY_FUNCTIONAL	`GetSQLOutputDirs`
Extract output dirs (fs.FS)	FULLY_FUNCTIONAL	`GetSQLOutputDirsFS`
Parent directory search	FULLY_FUNCTIONAL	Searches up to 3 levels for sqlc config
Skip hidden/vendor dirs	FULLY_FUNCTIONAL	Skips `.*`, `node_modules`, `vendor`

Content Scanning

Feature	Status	Details
Header-only content scan	FULLY_FUNCTIONAL	Content detection searches only the header (before `package` clause), per Go generated-code spec. Prevents false positives.
Config-aware SQLC detection	FULLY_FUNCTIONAL	Phase 1.5: parses sqlc configs, maps output dirs to accepted filenames. Cached via `atomic.Pointer`. Eliminates false positives on common names outside configured dirs.

Error System

Feature	Status	Details
Branded errors	FULLY_FUNCTIONAL	`[gogenfilter:<code>]` prefix on all errors
9 error codes	FULLY_FUNCTIONAL	Project root (2) + Filter config (1) + File read (1) + SQLC config (5)
9 sentinel errors	FULLY_FUNCTIONAL	`Err*` vars for `errors.Is` matching
ErrorCoder interface	FULLY_FUNCTIONAL	`ErrorCode() ErrorCode` for programmatic access
Unwrap chains	FULLY_FUNCTIONAL	Inner errors accessible via `errors.AsType`
`FileReadError` type	FULLY_FUNCTIONAL	All file I/O during detection returns branded `*FileReadError` (code `file_read`, sentinel `ErrFileRead`). Single branding point: `readFile`.

Type Safety

Feature	Status	Details
FilterOption string type	FULLY_FUNCTIONAL	With `IsValid()`, `String()`, `Reason() (FilterReason, bool)`
FilterReason string type	FULLY_FUNCTIONAL	With `IsValid()`, `String()`
ErrorCode string type	FULLY_FUNCTIONAL	With `String()`

Testing

Feature	Status	Details
Table-driven tests	FULLY_FUNCTIONAL	All test files use table-driven patterns
Parallel tests	FULLY_FUNCTIONAL	`t.Parallel()` throughout
Integration tests	FULLY_FUNCTIONAL	Real generated files via `//go:embed testdata`
Fuzz tests	FULLY_FUNCTIONAL	`FuzzMatchPattern`, `FuzzDetectReason`
Property tests	FULLY_FUNCTIONAL	`testing/quick` for idempotency/pattern invariants
Benchmark tests	FULLY_FUNCTIONAL	All hot paths benchmarked
Concurrent tests	FULLY_FUNCTIONAL	100-goroutine `Filter` test
Edge case tests	FULLY_FUNCTIONAL	Empty path, unicode, long names, nil FS
Runnable examples	FULLY_FUNCTIONAL	`Example*` functions in `example_test.go`
Generic test helpers	FULLY_FUNCTIONAL	`assertErrorType[T]`, `boolTestCase[T]`, `runBoolTableTest[T]`
BDD specs	FULLY_FUNCTIONAL	~120 Ginkgo specs (`bdd_test.go` + `bdd_extended_test.go`)
README table test	FULLY_FUNCTIONAL	`readme_test.go` — validates markdown table column consistency
Gendocs integration	FULLY_FUNCTIONAL	`cmd/gendocs/integration_test.go` — end-to-end `go generate` + idempotency

CI/CD

Feature	Status	Details
GitHub Actions CI	FULLY_FUNCTIONAL	Test, build, vet, lint, govulncheck on push/PR to master
Race detector	FULLY_FUNCTIONAL	`go test -race` in CI
Coverage threshold	FULLY_FUNCTIONAL	98% threshold in CI (library at 98.4%)
golangci-lint v2	FULLY_FUNCTIONAL	Comprehensive config in `.golangci.yaml` (uses `gomodguard_v2`)
Code duplication	FULLY_FUNCTIONAL	`art-dupl` (pinned v0.1.0) in CI
Docs freshness	FULLY_FUNCTIONAL	`go generate ./... && git diff --exit-code` enforced in CI
govulncheck	FULLY_FUNCTIONAL	Vulnerability scan in CI
Website deployment	FULLY_FUNCTIONAL	Firebase Hosting via `website.yml`
Benchmark tracking	FULLY_FUNCTIONAL	`benchmark.yml` pushes to `gh-pages`
Release workflow	FULLY_FUNCTIONAL	`release.yml` — tag-based GitHub Release
Lighthouse CI	PARTIALLY_FUNCTIONAL	`lighthouserc.json` configured; assertions advisory (warnings); `LHCI_GITHUB_APP_TOKEN` not configured — no status checks

Gitignore-Aware Filtering

Feature	Status	Details
Native `.gitignore` parsing	REJECTED	Out of scope — gogenfilter detects generated code, `.gitignore` is broader (build artifacts, secrets, IDE configs). Would require alpha dependency (`go-git/v6`) and blur identity.
`WithExcludePatterns` alternative	FULLY_FUNCTIONAL	`WithExcludePatterns("vendor/", "/testdata/**")` covers 80%+ of gitignore-like exclusions with zero extra deps.
Composition pattern documented	FULLY_FUNCTIONAL	Guide: `guides/gitignore-pre-filtering/` — shows how to pre-filter with external gitignore libraries before passing to gogenfilter.

Project Root Discovery

Feature	Status	Details
FindProjectRoot	FULLY_FUNCTIONAL	Searches parent dirs for marker files
Configurable markers	FULLY_FUNCTIONAL	`[]string{"go.mod", "sqlc.yaml", ...}`
Depth limit	FULLY_FUNCTIONAL	`maxProjectRootDepth = 10`
Error reporting	FULLY_FUNCTIONAL	`ProjectRootError` with code, path, markers

Website

Feature	Status	Details
Astro v7 + Starlight	FULLY_FUNCTIONAL	Marketing/docs site in `website/` (migrated from v6)
Landing page	FULLY_FUNCTIONAL	Hero ("Stop linting code no human wrote"), before/after linter proof, 3-color accent system, funnel logo
Dracula syntax theme	FULLY_FUNCTIONAL	Vivid highlighting in docs; CSP hardened (`fix-csp.mjs` strips hash sources so `unsafe-inline` works)
Dependents page	FULLY_FUNCTIONAL	Build-time GitHub code search for public users
Starlight docs	FULLY_FUNCTIONAL	PageFind search; API reference via pkg.go.dev
Firebase Hosting	FULLY_FUNCTIONAL	Configured via `firebase.json`; deploys on push to master
WCAG AA contrast	FULLY_FUNCTIONAL	Audited across all surfaces, both themes; `--color-on-accent` token pattern

Documentation Generation Pipeline

Feature	Status	Details
`cmd/gendocs` generator	FULLY_FUNCTIONAL	Derives docs from the `detectors` table — single source of truth; `formatMarkdownTable` provides dynamic column-width alignment
`generators.json`	FULLY_FUNCTIONAL	18-entry data file consumed by Astro components
README tables	FULLY_FUNCTIONAL	Generated between `<!-- gendocs:*:start/end -->` markers
`generators.mdx` table/count	FULLY_FUNCTIONAL	Generated between `{/* gendocs::start/end /}` MDX markers (incl. inline tool count via `replaceSectionInline`)
`detection.mdx` table	FULLY_FUNCTIONAL	Per-generator `Is*Generated` function table, generated
`doc.go` generator list	FULLY_FUNCTIONAL	Generated between `// gendocs:*:start/end` markers
`websiteMetadata` validation	FULLY_FUNCTIONAL	gendocs fails at build time if a detector lacks presentation data — drift impossible
Detector doc metadata	FULLY_FUNCTIONAL	`url`, `filenameDesc`, `contentDesc`, `isFuncName` on each detector; powers `AllDetectorDocs()`

Developer Environment

Feature	Status	Details
Nix flake	FULLY_FUNCTIONAL	`flake.nix` with flake-parts architecture + treefmt-nix formatting
Reproducible builds	FULLY_FUNCTIONAL	`nix build`, `nix run .#test`, `nix run .#lint`