Known Limitations
SQLC Config Parsing
Section titled “SQLC Config Parsing”YAML Library Divergence
Section titled “YAML Library Divergence”sqlc uses gopkg.in/yaml.v3 to parse its config files. gogenfilter uses github.com/go-faster/yaml — a 2–3x faster, actively maintained fork. Both implement the YAML 1.2 spec and produce identical results for the flat struct unmarshaling used here. This is an intentional choice: the upstream go-yaml/yaml repository is archived (April 2025) and yaml.v3 has known CVEs.
No KnownFields(true) Validation
Section titled “No KnownFields(true) Validation”gogenfilter does not reject unknown YAML fields in sqlc.yaml. A typo in a field name (e.g., engien instead of engine) will silently produce zero output directories instead of returning an error. This is acceptable because the same typo would also break sqlc itself, so the user discovers it during code generation.
No Environment Variable Substitution
Section titled “No Environment Variable Substitution”sqlc reads SQLC_AUTH_TOKEN from the environment after parsing. gogenfilter does not perform environment variable substitution. This has no impact on output directory detection — sqlc’s addEnvVars only handles cloud authentication, not output paths.
Config Discovery Skips Hidden Directories
Section titled “Config Discovery Skips Hidden Directories”gogenfilter skips hidden directories (.*), node_modules, and vendor during config file discovery. If a project stores its sqlc.yaml inside a hidden directory (e.g., .sqlc/sqlc.yaml), it will not be discovered. Projects with non-standard config locations should pass explicit paths to FindSQLCConfigs.
Dual Config File Tolerance
Section titled “Dual Config File Tolerance”If both sqlc.yaml and sqlc.yml exist in the same directory, gogenfilter parses both and merges their output directories. sqlc itself would reject this as ambiguous. Over-filtering (more files caught) is safer than under-filtering.
No sqlc_tools.yaml Support
Section titled “No sqlc_tools.yaml Support”sqlc supports sqlc_tools.yaml for procedural code generation tooling. gogenfilter only discovers sqlc.yaml and sqlc.yml. The tools config does not define Go code generation output directories, so this has no impact on detection.
General Detection
Section titled “General Detection”Filename-Based Detection Is Heuristic
Section titled “Filename-Based Detection Is Heuristic”Phase 1 detection (filename patterns) uses naming conventions from each generator. For example, sqlc files often end in .sql.go, and protobuf files end in .pb.go. These are strong signals but not guarantees. A hand-written file matching these patterns would be a false positive. Phase 2 (content-based) verification catches most of these.
Content Detection Requires File Reads
Section titled “Content Detection Requires File Reads”Phase 2 detection reads file contents to check for // Code generated by markers and generator-specific patterns. This adds I/O cost but is necessary for accuracy. Files that don’t match any filename pattern and don’t contain generation markers will not be filtered.
oapi-codegen Has No Filename Heuristic
Section titled “oapi-codegen Has No Filename Heuristic”oapi-codegen generates *.gen.go files, but this extension is used by many generators. Adding it as a phase 1 pattern would cause false positives. oapi-codegen is detected purely by content ("oapi-codegen" marker in the file).