feat: Add JSON schema generation and validation for digger.yml (#2541)

[joshuamkite-nfb]

Add JSON Schema Generation Tool for digger.yml

Fixes #2541

Summary

Implements an automated JSON Schema generation tool for digger.yml configuration files, addressing documentation drift issues identified in #2541. The tool generates schema from Go structs in the code, ensuring the schema stays synchronized with the codebase.

Changes

Core Implementation

• Schema Generator (libs/digger_config/cmd/schema-gen/): Standalone Go tool that generates JSON Schema from DiggerConfigYaml struct
• Generated Schema (libs/digger_config/digger-schema.json): Complete JSON Schema with type validation, enum constraints, and field descriptions
• Makefile Targets: schema-generate, schema-validate, schema-check for schema maintenance
• Schema Tests (libs/digger_config/schema_test.go): Validation tests for enum values, defaults, and required fields

CI/CD Integration

• GitHub Actions (.github/workflows/libs_test.yml): Added schema-check step to validate schema on every PR
• Error Messages: Actionable error messages with remediation steps (e.g., "Run: make schema-generate")

Documentation

• Developer Docs:
  • libs/digger_config/cmd/schema-gen/README.md - Tool usage and development guide
  • libs/digger_config/README.md - Library overview with schema maintenance workflow
• User Docs (docs/ce/reference/digger.yml.mdx):
  • Added IDE support tip with schema URL
  • Fixed comment_render_mode enum values: detailed → group_by_module
  • Added reference to JSON Schema as authoritative source

Technical Details

Dependencies Added (scoped to schema-gen tool only):

• github.com/invopop/jsonschema v0.13.0 - Schema generation via reflection
• github.com/wk8/go-ordered-map/v2 v2.1.8 - Ordered property maps (transitive)

Key Features:

• Uses Go reflection to automatically capture all struct fields
• Respects yaml: struct tags for field naming
• Adds enum constraints from code constants (e.g., CommentRenderModeBasic)
• Validates schema matches Go structs in CI
• Follows existing Makefile patterns (.PHONY, GOWORK=off)

Testing

Unit Tests

cd libs/digger_config
make schema-check
# ✓ Schema validation passed
# ✓ All schema tests passed

Production Config Validation

The generated schema was validated against 3 real production digger.yml files from active repositories:

• ✓ foo/digger.yml (1007 lines, Terragrunt config with 100+ projects)
• ✓ bar/digger.yml (68 lines, OpenTofu config with staging/production workflows)
• ✓ baz/digger.yml (46 lines, multi-environment configuration)

All production configs validated successfully, confirming the schema accurately represents real-world usage patterns.

All existing tests pass. Schema validation now runs in CI on every PR.

Benefits

1. Prevents Documentation Drift: Schema auto-generated from code, eliminating manual sync issues
2. IDE Support: Developers get autocomplete and validation in VS Code, JetBrains IDEs
3. Early Error Detection: Invalid configurations caught before commit/CI
4. Single Source of Truth: Go structs are the authoritative source, schema reflects reality
5. CI Enforcement: Schema validation in GitHub Actions prevents outdated schemas from merging

Migration Notes

None required. This is a new tool that doesn't affect existing functionality.

Future Work

• Publish schema to https://docs.opentaco.dev/schemas/digger.yml.json
• Consider auto-generating parts of reference docs from schema
• Add pre-commit hook for local schema validation

---

🧠 AI Usage Details:

This PR was developed with assistance from Claude (Anthropic) under human direction.

Human Direction:

• Overall solution architecture and approach
• Validation strategy against production configs
• Repository conventions and house style requirements
• Integration points (CI/CD, documentation structure)
• Testing requirements and acceptance criteria

AI Assistance:

• Code generation for the schema generator tool
• Fixing linting errors related to jsonschema API changes
• Writing documentation and PR description
• Ensuring compliance with repository conventions
• Validation testing execution

All code has been reviewed, tested against production configs, and verified manually.

[joshuamkite-nfb]

Can even see schema test failing my PR because my branch was out of date LOL