Validator Error Format Policy

Validator Error Format Policy

Comprehensive guide for error reporting and formatting in klaudiush validators.

Error Format Structure

Validators return `*validator.Result` with these fields:

type Result struct {
    Passed      bool                      // Whether validation passed
    Message     string                    // Human-readable error message
    Details     map[string]string         // Additional contextual information
    ShouldBlock bool                      // Whether to block the operation
    Reference   validator.Reference       // Error documentation URL
    FixHint     string                    // Short fix suggestion
}

**Key semantics:**

• Passed=true → validation passed (any other state ignored)
• Passed=false + ShouldBlock=true → deny (JSON permissionDecision: "deny")
• Passed=false + ShouldBlock=false → allow with warning (JSON permissionDecision: "allow")

Reference System

References are URLs that uniquely identify error types: `https://klaudiu.sh/e/{CODE}`

type Reference string

const ReferenceBaseURL = "https://klaudiu.sh/e"

// Example references
RefGitNoSignoff   Reference = "https://klaudiu.sh/e/GIT001"
RefGitMissingFlags Reference = "https://klaudiu.sh/e/GIT010"
RefShellcheck     Reference = "https://klaudiu.sh/e/FILE001"

Reference Methods

• Code() - Extracts error code: "GIT001" from full URL
• Category() - Extracts category prefix: "GIT", "FILE", "SEC"
• String() - Returns full URL

Error Code Organization

**GIT001-GIT025**: Git operations

• GIT001: Missing signoff (-s)
• GIT002: Missing GPG sign (-S)
• GIT003: No staged files
• GIT004: Commit title issues
• GIT005: Commit body line length
• GIT006: Infrastructure scope misuse (feat(ci) instead of ci(...))
• GIT007: Missing remote
• GIT008: Missing branch
• GIT009: File doesn't exist
• GIT010: Missing required flags
• GIT011: PR reference in commit
• GIT012: Claude attribution
• GIT013: Invalid conventional commit
• GIT014: Forbidden pattern
• GIT015: Signoff identity mismatch
• GIT016: List formatting issues
• GIT017: Merge commit validation failure
• GIT018: Missing signoff in merge body
• GIT019: Blocked files in git add (e.g., tmp/*)
• GIT020: Branch naming violations (spaces, uppercase, patterns)
• GIT021: --no-verify flag not allowed
• GIT022: Kong org push to origin remote blocked
• GIT023: PR validation failure (title, body, markdown, or labels)
• GIT024: Remote doesn't exist for git fetch
• GIT025: Push to blocked remote

**FILE001-FILE010**: File validation

• FILE001: Shellcheck failure
• FILE002: Terraform fmt failure
• FILE003: Tflint failure
• FILE004: Actionlint failure
• FILE005: Markdown linting failure
• FILE006: Gofumpt formatting failure
• FILE007: Ruff Python validation failure
• FILE008: Oxlint JavaScript/TypeScript validation failure
• FILE009: Rustfmt formatting failure
• FILE010: Linter ignore directives detected

**SEC001-SEC005**: Security

-