ADR-0053: Declarative and Functional String Validation Invariants
Status
Accepted
Context
Across complex systems, imperative and procedural validation patterns such as:
if strings.TrimSpace(value) == "" {
return fmt.Errorf("field %s cannot be empty", fieldName)
}
recur repeatedly throughout command handlers, data parsing layers, and API adapters. This pattern introduces unnecessary boilerplate, increases cognitive overhead, and is prone to inconsistent formatting and omission of whitespace trimming.
To maintain clean, concise, and functional Go code, input validation must transition from procedural conditional checks to declarative, zero-allocation helper functions. Furthermore, the repository verification engine requires an automated static analysis rule to detect and flag legacy imperative patterns.
Decision
-
Declarative Validation Functions (
pkg/strutil&pkg/stringutil): - ProvideErrorOnBlank(val, format string, args ...any) error:- Checks if trimmed string is empty.
- Formats error message with optional format arguments if blank; returns
nilif non-blank. - Zero allocations on the non-blank happy path.
- Provide
RequireNonBlank(val, name string) error: - Emits standardized
<name> cannot be blankerror. - Provide pure predicates
IsBlank(s string) boolandIsNonBlank(s string) bool. - Expose identical signatures in
pkg/stringutilas forwarding aliases topkg/strutil.
-
Automated Verification Rule in
zqk-vet: - ImplementCheckImperativeBlankValidationAST checker underhygiene/anti_pattern_blank_check. - Scan Go ASTs forstrings.TrimSpace(...) == ""conditions returning error constructors (fmt.Errorf,errors.New,errfmt.Newf). - Flag occurrences as actionable warnings during localzqk-vetchecks and pre-push verification gates. -
Incremental Migration: - Establish warning-level severity during initial rollout to prevent breaking existing build workflows. - Gradually migrate legacy procedural checks to functional calls during normal development cycles.
Consequences
- Positive:
- Consistent error formatting and mandatory whitespace trimming across all validation paths.
- Reduced boilerplate and declarative code structure.
- Proactive static analysis guidance preventing anti-pattern recurrence.
- Negative:
- Requires developer awareness of the helper API across teams and autonomous subagent seats.