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

- Fixed schema-gen tool for jsonschema v0.13.0 API changes
- Added comprehensive developer documentation in schema-gen/
- Integrated schema validation into CI/CD pipeline
- Updated user documentation with IDE support guidance
- Validated schema against 3 production digger.yml configs
- Created Makefile with schema-generate, schema-validate, and schema-check targets

New dependencies (scoped to schema-gen tool):
- github.com/invopop/jsonschema v0.13.0
- github.com/wk8/go-ordered-map/v2 v2.1.8

AI Assistance: This PR was developed with AI assistance (Claude via Roo Code)
under human direction. The human directed the overall approach, validation
strategy, and ensured adherence to repository conventions. The AI helped
with code fixes, documentation, and validation testing.

Author: joshuamkite-nfb

.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
@@ -202,7 +210,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