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

.github/workflows/libs_test.yml

@@ -57,11 +57,15 @@ jobs:
         with:
           tofu_version: 1.8.5
 
+      - name: Validate digger.yml Schema
+        run: make schema-check
+        working-directory: libs/digger_config
+
       - name: Test
         run: |
           if [ "${{ steps.pr_check.outputs.is_external }}" = "true" ]; then
             export IS_EXTERNAL_PR="true"
-            go test ./... 
+            go test ./...
           else
             go test ./...
           fi

docs/ce/reference/digger.yml.mdx

@@ -7,6 +7,14 @@ description: "Reference for configuring Digger via the digger.yml configuration
   Fields marked as **Required** must be set. Optional fields have sensible defaults shown below.
 </Note>
 
+<Tip>
+  **IDE Support**: Add this to the top of your `digger.yml` for autocomplete and validation:
+  ```yaml
+  # yaml-language-server: $schema=https://docs.opentaco.dev/schemas/digger.yml.json
+  ```
+  The [JSON Schema](https://docs.opentaco.dev/schemas/digger.yml.json) is automatically generated from the codebase and is the authoritative source for validation.
+</Tip>
+
 You can configure Digger by dropping a `digger.yml` file at the root level of your repo.
 
 ```yml
@@ -208,7 +216,7 @@ workflows:
 </ParamField>
 
 <ParamField path="comment_render_mode" type="string" default="basic">
-  How to render plan output in comments. Options: `basic`, `detailed`.
+  How to render plan output in comments. Options: `basic`, `group_by_module`.
 </ParamField>
 
 <ParamField path="mention_drifted_projects_in_pr" type="boolean" default="false">

libs/digger_config/Makefile

@@ -0,0 +1,23 @@
+.PHONY: schema-generate schema-validate test-schema
+
+# Generate JSON schema from Go structs
+schema-generate:
+	@echo "Generating JSON schema from Go structs..."
+	@cd cmd/schema-gen && GOWORK=off go mod download && GOWORK=off go run main.go -output ../../digger-schema.json
+	@echo "✓ Schema generated successfully"
+
+# Validate existing schema matches Go structs
+schema-validate:
+	@echo "Validating JSON schema against Go structs..."
+	@cd cmd/schema-gen && GOWORK=off go mod download && GOWORK=off go run main.go -validate -output ../../digger-schema.json
+	@echo "✓ Schema validation passed"
+
+# Run schema tests
+test-schema:
+	@echo "Running schema tests..."
+	@go test -v -run "^Test.*" schema_test.go config.go converters.go digger_config.go utils.go validators.go yaml.go
+	@echo "✓ All schema tests passed"
+
+# Run all schema checks (for CI)
+schema-check: schema-validate test-schema
+	@echo "✓ All schema checks passed"

libs/digger_config/README.md

@@ -0,0 +1,71 @@
+# Digger Config Library
+
+Go library for parsing and validating Digger configuration files (`digger.yml`).
+
+## Components
+
+### Configuration Parsing
+- **[`digger_config.go`](digger_config.go)** - Main configuration loading and parsing
+- **[`yaml.go`](yaml.go)** - YAML struct definitions
+- **[`converters.go`](converters.go)** - Convert YAML structs to internal types
+- **[`validators.go`](validators.go)** - Configuration validation logic
+
+### JSON Schema
+- **[`digger-schema.json`](digger-schema.json)** - JSON Schema for `digger.yml`
+- **[`cmd/schema-gen/`](cmd/schema-gen/)** - Schema generation tool
+- **[`schema_test.go`](schema_test.go)** - Schema validation tests
+
+See [`cmd/schema-gen/README.md`](cmd/schema-gen/README.md) for schema generation documentation.
+
+### Terragrunt Support
+- **[`terragrunt/`](terragrunt/)** - Terragrunt configuration parsing
+
+## Usage
+
+```go
+import "github.com/diggerhq/digger/libs/digger_config"
+
+// Load configuration
+config, _, _, _, err := digger_config.LoadDiggerConfig(".", true, nil, nil)
+if err != nil {
+    log.Fatal(err)
+}
+
+// Validate
+if err := digger_config.ValidateDiggerConfig(config); err != nil {
+    log.Fatal(err)
+}
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests
+go test ./...
+
+# Schema tests only
+make test-schema
+```
+
+### Maintaining the Schema
+
+When modifying configuration structs:
+
+```bash
+# Regenerate schema
+make schema-generate
+
+# Validate it matches
+make schema-validate
+
+# Run all checks
+make schema-check
+```
+
+See [`cmd/schema-gen/README.md`](cmd/schema-gen/README.md) for details.
+
+## Configuration Reference
+
+See the [digger.yml reference documentation](../../docs/ce/reference/digger.yml.mdx) for user-facing configuration documentation.

libs/digger_config/cmd/schema-gen/README.md

@@ -0,0 +1,101 @@
+# Schema Generator
+
+Automatically generates and validates the JSON Schema for `digger.yml` configuration files.
+
+## Overview
+
+This tool generates [`digger-schema.json`](../../digger-schema.json) from the Go struct definitions in [`yaml.go`](../../yaml.go), ensuring the schema stays in sync with the actual configuration code.
+
+## Usage
+
+### Generate Schema
+
+```bash
+cd libs/digger_config
+make schema-generate
+```
+
+This creates/updates `digger-schema.json` with:
+- All fields from `DiggerConfigYaml` and nested structs
+- Type information (string, boolean, array, object)
+- Enum constraints from code constants
+- Field descriptions and default values
+- YAML field name mapping (using `yaml:` struct tags)
+
+### Validate Schema
+
+```bash
+make schema-validate
+```
+
+Validates that the existing schema matches the current Go struct definitions. Fails if:
+- Schema is missing properties that exist in Go structs
+- Critical enum values don't match code constants
+
+### Run All Checks
+
+```bash
+make schema-check
+```
+
+Runs both validation and all schema tests. Use this in CI/CD.
+
+## How It Works
+
+1. **Reflection**: Uses [`github.com/invopop/jsonschema`](https://github.com/invopop/jsonschema) to reflect on Go structs
+2. **YAML Tag Mapping**: Configured with `FieldNameTag: "yaml"` to use YAML field names
+3. **Enhancement**: [`enhanceSchema()`](main.go:75) adds:
+   - Enum values from code constants (e.g., `CommentRenderModeBasic`)
+   - Field descriptions
+   - Default values
+4. **Validation**: Compares generated schema against existing file
+
+## Schema ID
+
+The schema is published at:
+```
+https://docs.opentaco.dev/schemas/digger.yml.json
+```
+
+## Development
+
+### Adding New Fields
+
+When you add fields to `DiggerConfigYaml`:
+
+1. Add the field with proper `yaml:` tag:
+   ```go
+   NewField string `yaml:"new_field"`
+   ```
+
+2. Regenerate the schema:
+   ```bash
+   make schema-generate
+   ```
+
+3. If the field has enum values, add them in [`enhanceSchema()`](main.go:75):
+   ```go
+   if prop, ok := props.Get("new_field"); ok && prop != nil {
+       prop.Enum = []interface{}{"value1", "value2"}
+       prop.Description = "Description of new field"
+   }
+   ```
+
+### Testing
+
+Schema tests are in [`schema_test.go`](../../schema_test.go). Add tests for:
+- New enum fields
+- Required field validation
+- Default value behavior
+
+## Dependencies
+
+- `github.com/invopop/jsonschema` v0.13.0 - Schema generation
+- `github.com/wk8/go-ordered-map/v2` v2.1.8 - Ordered property maps (transitive)
+
+## Related Files
+
+- [`../../digger-schema.json`](../../digger-schema.json) - Generated schema
+- [`../../yaml.go`](../../yaml.go) - Source structs
+- [`../../schema_test.go`](../../schema_test.go) - Schema validation tests
+- [`../../Makefile`](../../Makefile) - Build targets