Skip to content
gogenfilter

Changelog

Unreleased

Section titled “Unreleased”

Nothing yet.

v3.4.0 — 2026-08-05

Section titled “v3.4.0 — 2026-08-05”

Added

Section titled “Added”
  • FilterDetailedAndContent API — Like FilterDetailed but also returns the file content read during phase-2 detection. Content is nil when no read occurred (disabled filter, include/exclude pattern match, phase-1 filename match, or no content-check detectors enabled). When non-nil, the content was read exactly once from the filter’s filesystem and can be reused by callers for post-detection logic (e.g., classifying a ReasonGeneric hit into a specific generator category) without a double-read. Purely additive; no breaking changes to existing methods.

v3.3.3 — 2026-08-05

Section titled “v3.3.3 — 2026-08-05”

Fixed

Section titled “Fixed”
  • Content-only detection for filename-gated generators — SQLC, Templ, GoEnum, and Protobuf detectors had filename gates baked into their checkContent functions, making phase-2 content detection ineffective for files with non-standard names (e.g., a sqlc-generated repository.go instead of models.go). Content-only wrappers (checkSQLCContent, checkTemplContent, checkGoEnumContent, checkProtobufContent) now use specific generation comment markers ("Code generated by sqlc", "Code generated by templ", etc.). The public Is*Generated functions remain filename-gated for backward compatibility.
  • flake.nix package description — Corrected from “Go struct field filter code generator” (copy-paste error from an unrelated project) to “Go library for detecting and filtering auto-generated code files”.

Added

Section titled “Added”
  • Dynamic Open Graph image generation — Per-page OG images via astro-og-canvas at /og/[...slug].
  • Content-only detection test suite — filter_content_only_test.go verifying misnamed generated files are caught by content, public Is*Generated functions still require correct filenames, and content-only checks produce no false positives on regular code.

Changed

Section titled “Changed”
  • Generator docs alignment — Updated templ and protobuf content detection descriptions in generators.mdx to match actual markers (Code generated by templ, Code generated by protoc-gen-go) instead of generic patterns.

v3.3.2 — 2026-07-26

Section titled “v3.3.2 — 2026-07-26”

Added

Section titled “Added”
  • RELEASING.md — Full release runbook: quality gates, CHANGELOG sync, version bump, tag, push, verify, rollback procedure.
  • Color system ADR (docs/adr/001-color-system.md) — Decision record for the warm-stone + 3-color accent system (cyan/amber/emerald), WCAG AA contrast decisions, and a step-by-step guide for adding new accent colors.
  • Gendocs integration test (cmd/gendocs/integration_test.go) — End-to-end test running go generate ./..., verifying all 5 output files contain expected content, and checking idempotency via git diff --exit-code.
  • Gendocs unit tests — Idempotency proofs (TestReplaceSectionIsIdempotent, TestReplaceSectionInlineIsIdempotent) and phantom-column regression guard (TestGeneratedTablesHaveNoPhantomColumns).
  • Markdown link checker (scripts/check-markdown-links.py) — Validates all internal (relative) markdown links repo-wide; wired into CI as a quality gate.
  • markdownRow helper in gendocs — Joins table cells with proper pipe escaping, structurally preventing the || phantom-column bug at the helper level.
  • formatMarkdownTable helper in gendocs — Dynamic column-width calculation for all 4 markdown table outputs, replacing 3 hardcoded width constants (mdxNameWidth, mdxFilenameWidth, detectionFuncWidth).
  • stripEmptyScriptHash() in CSP fix script — Removes the SHA-256 hash of an empty string from script-src (generated internally by Astro, present on all built pages).
  • Gendocs workflow section in CONTRIBUTING.md — Documents the detectors table as single source of truth, how to run gendocs, the 5 output files, and the websiteMetadata requirement.
  • Nix flake app descriptions — meta.description on all 10 flake apps, eliminating nix flake check warnings.
  • DOMAIN_LANGUAGE.md expanded — Added v3.2 entities (ScanResult, GeneratedFile, Exclusion, ExclusionPattern, ScanProject, DetectReasonFile, FilterWithContent) and v3.3 entities (DetectorDoc, AllDetectorDocs, AllFilterOptions, AllFilterReasons, AllGeneratorOptions).
  • Archived stale planning docs — Moved docs/planning/2026-05-* to docs/status/archive/; removed empty docs/planning/ directory.

Fixed

Section titled “Fixed”
  • Broken OG image generation — param: "slug" option wrongly removed from OGImageRoute() during astro-og-canvas 0.13 migration; restored (was causing PrerenderDynamicEndpointPathCollide build error, blocking all website builds).
  • 3 website color-token bugs — (1) --color-accent-dim light mode was rgba(8,145,178,0.1) (old accent) instead of rgba(14,116,144,0.1) (current accent #0e7490); (2) --color-border light mode was cool zinc (rgba(228,228,231,...)) on a warm-stone palette, changed to rgba(231,229,228,...); (3) --color-code-comment dead token (0 references outside CSS) deleted.
  • Newsletter CSP violation — Inline onsubmit handler moved to Astro <script> block (bundled as external module, covered by script-src 'self').
  • Starlight meta description — Updated from stale “Detect and filter auto-generated Go code files” to current “Stop linting code no human wrote” positioning.
  • nix flake check — 3 latent bugs — (1) stale vendorHash after go.sum change; (2) non-hermetic test (os.ReadFile("README.md") fails in Nix sandbox, fixed with //go:embed); (3) README.md missing from lib.fileset.unions source set.
  • Stale md-go-validator vendorHash — Updated in flake.nix to match current go.sum.
  • Gendocs README table alignment — Tables were unaligned (cells not padded to column width); formatMarkdownTable dynamically calculates column widths from the widest cell in each column.
  • Dependents page GitHub API 401 — Added 401 to rate-limit handling branch (was only catching 403); unauthenticated builds now degrade gracefully.
  • errorCodeMatches refactor — Three Is() methods in errors.go now share an errorCodeMatches(code, target) helper that matches via the ErrorCoder interface, replacing three concrete type assertions.
  • Committed gendocs build binary untracked — The 3.5 MB compiled gendocs binary was accidentally committed to git; untracked and added to .gitignore.

Changed

Section titled “Changed”
  • Gendocs: all 4 table generators refactored to use formatMarkdownTable (README generators table, README filter options table, detection.mdx per-generator table, generators.mdx detection table).
  • GITHUB_TOKEN wired into website CI — npm run build step passes GITHUB_TOKEN for authenticated GitHub API calls on the dependents page (30 req/min vs 10 unauthenticated).
  • Lighthouse CI assertions — Correctness checks (errors-in-console, redirects, inspector-issues, viewport, image-aspect-ratio) upgraded from warn to error.
  • AGENTS.md policies revised — Removed “keep only 3 most recent reports” rule in favor of relevance/age-based pruning guidance; added 6 new Gotchas (Nix quality gates, sandbox testing, vendorHash maintenance, theme split-brain, astro-og-canvas param, BuildFlow auto-commit behavior).
  • Markdown link checker wired into CI — New “Check internal markdown links” step in .github/workflows/ci.yml.

v3.3.1 — 2026-07-24

Section titled “v3.3.1 — 2026-07-24”

Added

Section titled “Added”
  • README table consistency test (readme_test.go) — Validates that all markdown tables in README.md have consistent column counts. Regression guard for the gendocs || phantom-column corruption that produced broken tables.
  • Nix flake configuration — Reproducible development environments via flake.nix with flake-parts architecture and treefmt-nix for formatting.

Fixed

Section titled “Fixed”
  • README.md generator and filter-options tables — Rendered with phantom empty columns caused by a || formatting bug in gendocs (cmd/gendocs/main.go). Tables now render correctly.
  • 3 integration tests — Failed after testdata/templ/page_templ.go was accidentally deleted; fixture restored from git history.
  • Benchmark CI workflow — Failed because GOEXPERIMENT=jsonv2 was missing (required by cmd/gendocs, which imports encoding/json/v2).
  • Firebase deploy in Website CI — Failed due to bash quote mangling when passing the service account JSON via echo "${{ secrets.X }}". Switched to the env: + printf '%s' pattern.

Changed

Section titled “Changed”
  • Inlined isGeneratedBy helper — The unexported isGeneratedBy(content, generator) function was inlined at all 5 call sites in detection.go, removing an unnecessary indirection layer.
  • Simplified slice construction in scan.go — dirBasedExclusions and ExclusionPaths switched from pre-allocated indexed assignment to idiomatic append pattern.
  • Removed unused filenameNone constant in cmd/gendocs/main.go (dead code flagged by static analysis).
  • Website visual design overhaul — Three-color accent system (cyan/amber/emerald), funnel logo mark, dracula syntax highlighting theme, expanded call-to-action sections, and WCAG AA color contrast pass across all surfaces.

v3.3.0 — 2026-07-09

Section titled “v3.3.0 — 2026-07-09”

Added

Section titled “Added”
  • AllDetectorDocs() function — Returns structured documentation metadata for all detectors, derived from the detectors table. Used by gendocs to generate documentation artifacts.
  • DetectorDoc struct — Exported struct with Option, Reason, URL, FilenameDetection, ContentDetection, IsFuncName, HasFilenamePhase, HasContentPhase fields.
  • isFuncName field on detector struct — Records the exported Is*Generated function name for each detector, consumed by gendocs for the detection.mdx function table.
  • doc.go — Dedicated package documentation file (standard Go convention), moved from types.go.
  • Individual doc comments on all 21 FilterReason constants and all 8 sentinel error variables.
  • Documentation generation pipeline (cmd/gendocs) — A Go binary that reads the detectors table from detection.go and generates generators.json, README tables, generators.mdx detection table + tool count, detection.mdx per-generator function table, and doc.go generator list. Run via go generate ./.... CI enforces freshness with git diff --exit-code.
  • CI docs freshness job — Fails when generated docs are stale. Runs go generate ./... and checks git diff --exit-code on all generated files.
  • websiteMetadata validation — gendocs fails at build time if a detector lacks website presentation data, making drift impossible when adding new generators.
  • Website Scan API reference page — Documents ScanProject, ScanResult, GeneratedFile, Exclusion, ExclusionPaths, ExclusionPattern() (9 previously undocumented exported symbols).
  • Website API docs for DetectReasonFile/DetectReasonFileFS, FilterWithContent/FilterDetailedWithContent, FilterResult struct + methods, SQLCOperation type + constants.
  • Missing doc.go in 3 testdata directories (handwritten, wire, templ).

Fixed

Section titled “Fixed”
  • Compile-breaking code examples — Package doc and NewFilter examples showed WithFilterOptions passed inline to NewFilter, but WithFilterOptions returns (FilterConfig, error). All examples now show the correct two-step pattern.
  • IsGenericGenerated doc — Said “go generate”, actually catches any generator using the standard “Code generated by” comment.
  • getFilenameBasedReasonWithTrace doc — Named wrong function (copy-paste error).
  • FilterConfig type doc — Clarified closure semantics; was misleading about error handling.
  • README mockgen description — Claimed _mock.go / mock_ prefix; actually _mock.go suffix only (mock_ belongs to mockery).
  • README gqlgen description — Claimed filename detection; actually content-only (filename matcher is nil).
  • Website SQLCConfigError.Operation type — Documented as string, actually SQLCOperation since v3.1.0.
  • Website IsGqlgenGenerated description — Claimed filename + content; actually content-only.

Changed

Section titled “Changed”
  • generators.ts — Rewritten from 50-line hand-maintained array to thin wrapper importing generated generators.json.
  • README.md — Generator and filter options tables now generated between gendocs marker comments.
  • generators.mdx — Detection table and tool count now generated between gendocs marker comments.
  • detection.mdx — Per-generator function table now generated between gendocs marker comments.
  • doc.go — Generator list now generated between gendocs marker comments.
  • CONTRIBUTING.md — Updated “Adding a New Generator Detector” section with gendocs workflow steps.
  • CI path filters — Added website/** and doc.go to push/PR triggers so docs freshness runs on any relevant change.
  • .golangci.yaml Go version aligned to 1.26.4 (was 1.26.3).
  • AGENTS.md Key Source Files table updated with doc.go, scan.go, correct detector/constant counts.

v3.2.0 — 2026-06-11

Section titled “v3.2.0 — 2026-06-11”

Added

Section titled “Added”
  • DetectReasonFile / DetectReasonFileFS — Two-phase detection in one call (filename + content)
  • FilterWithContent / FilterDetailedWithContent — Filter methods accepting pre-read content to avoid double I/O
  • ScanProject — Walk fs.FS, detect all generated files, return structured ScanResult with per-generator lists and exclusion patterns
  • ExclusionPattern() on FilterReason — Get regex patterns for generators with consistent filename conventions
  • 7 new detector entries (18 total): mockery, ent, gqlgen, easyjson, msgp, counterfeiter, go-swagger
  • 7 new Is*Generated functions and 7 new FilterOption/FilterReason constants
  • FilterResult.Is(reason) — Ergonomic reason check
  • String() on GeneratedFile, Exclusion, ScanResult — Debug/logging ergonomics
  • ExclusionPaths() — Extract regex pattern strings from exclusions for golangci-lint

Changed

Section titled “Changed”
  • ExclusionPattern() allocation-free — Package-level var avoids map allocation per call
  • detectReasonFromMap empty content guard — Skips content check when content is empty

Fixed

Section titled “Fixed”
  • Absolute paths in content-based detection — os.DirFS rejects absolute paths; added readFile fallback to os.ReadFile
  • ScanProject ignored custom filesystems — Internal Filter now receives WithFS()
  • mockgen/mockery prefix overlap — mockery exclusively owns mock_ prefix; mockgen only matches _mock.go
  • msgp ExclusionPattern false positives — _gen.go$ would exclude wire_gen.go; removed from exclusion map

v3.1.0 — 2026-06-04

Section titled “v3.1.0 — 2026-06-04”

Added

Section titled “Added”
  • SQLCOperation typed constants — SQLCConfigError.Operation is now SQLCOperation instead of string, providing compile-time type safety for sqlc error handling. Five exported constants: OpSQLCFind, OpSQLCWalk, OpSQLCRead, OpSQLCCollect, OpSQLCParse.
  • ExampleWithExcludePatterns_vendorAndTestdata — runnable example demonstrating vendor/testdata exclusion patterns.

Changed

Section titled “Changed”
  • Breaking: SQLCConfigError.Operation field type — string → SQLCOperation. Callers constructing SQLCConfigError directly must use SQLCOperation constants instead of raw strings.
  • Detection markers extracted to named constants — All content detection strings (sqlcGenerateComment, templComponent, goEnumComment, mockgenGeneratorName, etc.) and filename suffixes (protobufFilenameSuffixes, sqlcCodePatternMarkers) are now named constants/vars instead of inline literals.
  • errorPrefixFmt constant — Branded error prefix "[gogenfilter:%s] " extracted from repeated inline format strings.
  • filteredResult/notFilteredResult removed — Helper functions replaced with inline FilterResult struct literals in detectReasonFSWithTrace.
  • Go 1.26.3 — go.mod updated.

Fixed

Section titled “Fixed”
  • Double-wrapped sqlcFindError — FindSQLCConfigs returned sqlcFindError(path, err) which itself wrapped err, causing the same error to appear twice in the unwrap chain.

v3.0.2 — 2026-05-25

Section titled “v3.0.2 — 2026-05-25”

Changed

Section titled “Changed”
  • Trace/non-trace detection unified — *WithTrace variants are now canonical implementations; non-trace versions are thin wrappers. Eliminates the biggest source of code duplication.
  • coverage_test.go dissolved — Tests moved to their natural test files (errors_test.go, filter_test.go, pattern_test.go, sqlc_test.go, project_test.go).
  • Test string literals centralized — Repeated test constants extracted to testhelpers/constants.go and named constants in testdata_test.go.
  • FilterResult construction DRYed up — filteredResult() and notFilteredResult() helpers eliminate repetitive struct literal construction.
  • Error system simplified — Removed errorCodeDefs table, AllErrorCodes(), CodeHelp(), Helper interface, CodeEqual[T] generic. Kept ErrorCode, ErrorCoder, sentinel errors, branded prefix.
  • Phantom types removed — StartPath, ConfigPath, Operation, ErrorMessage replaced with plain string fields.
  • Detection helpers unexported — MatchesSQLCFilename, HasSQLCContent, HasSQLCCodePatterns → unexported. Use DetectReason() or Filter.
  • codeGeneratedPrefix moved to detection.go — Only used there, not in types.go.
  • matchAnyContentPattern renamed → matchesAnyContentPattern for consistency.
  • Filter.String() improved — Better debug output showing options, include, and exclude patterns.
  • parseV1AsV2 cleaned up — Removed zero-value noise from struct construction.
  • validatable interface removed — Dead code in production.
  • Plausible analytics removed from website — Tightened Content Security Policy.
  • Flake configuration improved — Better nix build setup.
  • Release workflow added — Tag-based GitHub release with automated tests, lint, and release notes.

Fixed

Section titled “Fixed”
  • Website CI: checkout path parameter placement
  • Website CI: private repo access fallback
  • Benchmark CI: missing gh-pages branch
  • Lighthouse CI: budgets+assertions conflict
  • Node.js 20 deprecation — updated actions/setup-go@v5 → @v6

v3.0.1 — 2026-05-04

Section titled “v3.0.1 — 2026-05-04”

Added

Section titled “Added”
  • DetectReasonReader(filePath string, r io.Reader, opts ...FilterOption) (FilterReason, error) — detection from an io.Reader
  • Filter(filePath string) (bool, error) — replaces ShouldFilter with cleaner name
  • FilterResult struct with Filtered, Reason, Path, Trace fields
  • FilterDetailed(filePath string) (FilterResult, error) — detailed result with trace info
  • FilterPathsDetailed(paths []string) ([]FilterResult, error) — batch detailed results
  • AllGeneratorOptions() — enumerate detector options (excludes FilterAll)
  • FilterResult.String() — human-readable representation
  • Filter.FilterReasons() — returns the FilterReason values this filter will detect
  • Filter.String() — human-readable debug representation of filter state
  • Module path /v3 suffix for Go module convention compliance

Changed

Section titled “Changed”
  • ShouldFilter renamed to Filter — the method ShouldFilter(filePath string) (bool, error) is now Filter(filePath string) (bool, error).
  • Enabled() and Disabled() removed — filter is enabled by passing options to NewFilter(); NewFilter() with no args is disabled.
  • Breaking: Cause field renamed to Err on all error types — follows Go stdlib convention (os.PathError.Err, net.OpError.Err).
  • Breaking: FilterOption.Reason() returns (FilterReason, bool) — no panics on FilterAll.
  • Breaking: WithFilterOptions returns (FilterConfig, error) — returns *FilterConfigError for invalid options instead of panicking.
  • Breaking: NewFilter returns (*Filter, error) — uses errors.Join() to aggregate config errors.
  • IsValid() methods derived from tables
  • SQLC patterns consolidated
  • WithFilterOptions reuses optionsMap
  • slog dependency removed
  • IsEnabled() derives state from configuration
  • errors.AsType[T] migration complete — Go 1.26 exclusively

Fixed

Section titled “Fixed”
  • Silent misconfiguration — NewFilter(WithFilterOptions(FilterAll)) now works without Enabled()
  • Leaky fs.FS abstraction — detectReasonFS no longer falls back to os.ReadFile for custom filesystems
  • Website CI checkout path parameter placement
  • Lighthouse CI budgets+assertions conflict

Removed

Section titled “Removed”
  • Metrics system — Metrics, MetricsMixin, FilterStats, GetStats, FilteredBy, FilteredFiles, TotalFiltered, WithMetricsCap. Stats aggregation is the caller’s responsibility.
  • Phantom types — StartPath, ConfigPath, Operation, ErrorMessage. All error struct fields are now plain string.
  • Context methods — FilterContext, FilterDetailedContext, FilterPathsContext. They promised cancellation over synchronous I/O.
  • Error system over-engineering — errorCodeDefs table, AllErrorCodes(), CodeHelp(), Helper interface, CodeEqual[T] generic, Causable interface.
  • Detection helpers unexported — MatchesSQLCFilename, HasSQLCContent, HasSQLCCodePatterns.
  • TotalFilesChecked phantom type
  • os.ReadFile fallback in detectReasonFS
  • warnMultipleSQLCConfigs function and all slog usage
  • sqlcConfigError() bridge function
  • MustFilter / MustShouldFilter panic-on-error variant
  • Plausible analytics

v3.0.0 — 2026-05-04

Section titled “v3.0.0 — 2026-05-04”

Added

Section titled “Added”
  • FilterPaths(paths []string) ([]bool, error) — batch filtering; returns partial results on error
  • FilterConfigError type — returned when invalid filter options are provided; implements ErrorCoder and Unwrap
  • ErrInvalidFilterOption sentinel error — for errors.Is() matching
  • CodeInvalidFilterOption error code — for programmatic error handling

Changed

Section titled “Changed”
  • Breaking: WithFilterOptions returns (FilterConfig, error) — previously panicked on invalid options
  • Breaking: NewFilter returns (*Filter, error) — previously returned *Filter only
  • Breaking: FilterConfig returns error — config functions now return error to support validation
  • Breaking: Enabled() and Disabled() removed — filter is enabled when options are provided

Fixed

Section titled “Fixed”
  • Silent misconfiguration — NewFilter(WithFilterOptions(FilterAll)) without Enabled() silently did nothing; now passing options automatically enables the filter

[0.1.0] — 2026-04-04

Section titled “[0.1.0] — 2026-04-04”

Added

Section titled “Added”
  • Initial release
  • Two-phase detection: filename-based (zero I/O) then content-based
  • 11 generator detectors: sqlc, templ, go-enum, protobuf, oapi-codegen, deepcopy-gen, wire, moq, mockgen, stringer, generic
  • Functional options API: WithFilterOptions(), WithFS(), WithIncludePatterns(), WithExcludePatterns()
  • fs.FS abstraction for testing
  • SQLC config discovery
  • Glob pattern matching with ** support
  • Branded error types with sentinel errors