Improve error messages for Rego compilation failures caused by version incompatibilities

[st3penta]

When a user's policy rules use Rego syntax or OPA built-in features not supported by the OPA version bundled with ec-cli, the resulting error messages are raw compiler errors from OPA/conftest (e.g. rego_type_error, rego_parse_error) that are difficult to interpret and troubleshoot.

Currently, errors from runner.TestRunner.Run() and conftest.LoadWithData() in internal/evaluator/conftest_evaluator.go propagate directly to the user without any interception or enhancement. For example, a user might see:

Error: error validating image ... : load: loading policies: get compiler: 3 errors occurred:
/tmp/.../main.rego:14: rego_type_error: undefined function opa.runtime

This provides no indication that the issue is a version mismatch between the bundled OPA and the policy's Rego syntax.

Proposed improvements:

1. Intercept rego_type_error and rego_parse_error from OPA/conftest compilation and wrap them with a user-friendly message explaining the likely cause (OPA/Rego version incompatibility).
2. Include the bundled OPA version in the error output so users can cross-reference supported features.
3. Suggest potential solutions (e.g. upgrading ec-cli, or adjusting the policy to use compatible syntax).
4. Preserve the original low-level error as additional detail for debugging.

Acceptance Criteria:

• ec-cli produces a helpful, actionable error message when it encounters Rego syntax or features not supported by the bundled OPA version
• The error message includes the bundled OPA version number
• The error message suggests potential solutions (upgrade ec-cli or adjust policy syntax)
• The original compiler error is still available for debugging purposes

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 10:19 AM UTC · Completed 10:21 AM UTC
Commit: 47d3320 · View workflow run →

[fullsend-ai-triage]

Triage Summary

This is a well-defined feature request to improve error handling for OPA/Rego version mismatch compilation failures.

Problem: Raw rego_type_error and rego_parse_error from OPA/conftest propagate to users without version context or remediation guidance.

Where to look: internal/evaluator/conftest_evaluator.go — error paths from runner.TestRunner.Run() and conftest.LoadWithData().

Recommended approach:

1. Add error detection for rego_type_error and rego_parse_error patterns in the error returns from conftest
2. Wrap matched errors with a user-friendly message including the bundled OPA version and remediation suggestions
3. Preserve the original error for --debug output

Related issue: #1150 covers the narrower case of custom rego functions that aren't supported. These two issues overlap — resolving #3345 could subsume #1150 if the error wrapping covers both OPA built-in and custom function compilation errors.

Proposed test:

Unit test: simulate OPA compilation error with 'rego_type_error: undefined function'
- Assert wrapped error contains bundled OPA version string
- Assert wrapped error contains remediation guidance
- Assert original error is preserved
- Assert non-rego errors pass through unwrapped

Acceptance test: policy with unsupported Rego built-in
- Run ec validate, assert output includes version info and suggestions

---

Labels: This UX improvement targets the CLI evaluator's error handling for Rego compilation failures.