JQ Error Handling Patterns

This rule applies to files matching the patterns above.

# JQ Error Handling Patterns

## Rule
All jq filters processing external data MUST handle missing fields, unexpected types, and malformed input. Use try-catch, the alternative operator (//), and input validation.

## Good Examples
```bash
# Validate required fields exist
jq '
  if (.name | type) != "string" then
    error("name must be a string")
  elif (.age | type) != "number" then
    error("age must be a number")
  else
    {name: .name, age: .age}
  end
' input.json

# Safe nested access with defaults
jq '{
  host: (.database.host // "localhost"),
  port: (.database.port // 5432),
  name: (.database.name // error("database.name is required"))
}' config.json

# Try-catch for unreliable data
jq '[.events[] | try {
  date: (.timestamp | fromdateiso8601 | strftime("%Y-%m-%d")),
  type: .event_type
}]' events.json

# Handle both array and object input
jq '
  if type == "array" then .[]
  elif type == "object" then .
  else error("expected array or object, got " + type)
  end
  | .name
' input.json
```

## Bad Examples
```bash
# BAD: No error handling — crashes on missing fields
jq '.data.users[0].address.city' response.json
# Fails if any intermediate field is null

# BAD: Silent null propagation hides bugs
jq '.users[] | .profile.avatar_url' data.json
# Returns null for users without profile — is that correct?

# BAD: No type checking on API responses
jq '.results | length' api_response.json
# Crashes if .results is null or not an array
```

## Enforcement
- Test jq filters with edge cases: empty arrays, null fields, wrong types
- Use `// error("message")` for required fields instead of silent null
- Wrap external API response processing in try-catch blocks