Add inline examples to schema validation errors

[Copilot]

Schema validation errors now include field-specific inline examples following the error message pattern: [what's wrong] + [what's expected] + [example].

Changes

Enhanced error messages (pkg/workflow/schema_validation.go):

• Added enhanceSchemaValidationError() to wrap ValidationError with field-specific examples
• Added extractFieldPath() to extract field name from InstanceLocation
• Added getFieldExample() with 22 common workflow field examples + generic type fallbacks

Test coverage (2 new test files):

• Unit tests for field extraction, example generation, and error enhancement
• Integration tests for workflow compilation and example quality

Example

Before:

GitHub Actions schema validation failed: type mismatch at /timeout-minutes

After:

GitHub Actions schema validation failed: type mismatch at /timeout-minutes. Example: timeout-minutes: 10

For enum fields:

GitHub Actions schema validation failed: invalid enum value. Valid engines are: copilot, claude, codex, custom. Example: engine: copilot

For complex fields:

GitHub Actions schema validation failed: type error. Example: permissions:
  contents: read
  issues: write

Generic type-based examples (string, boolean, object, array, integer) are provided for fields not in the predefined map.

Fixes #4071

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Add inline examples to schema validation errors</issue_title>
<issue_description>## Objective
Enhance schema validation error messages to provide inline examples rather than just referencing the schema. When validation fails, show the user exactly what correct YAML should look like.

Context

Part of discussion #4071 - Repository Quality Improvement. Schema validation errors currently return generic messages that reference the schema but don't provide actionable examples. This forces users to search documentation.

Approach

1. Enhance pkg/workflow/schema_validation.go to parse schema validation errors and identify which field failed
2. Create a helper function extractFieldFromSchemaError() to parse JSON schema validation errors
3. Build a map of common field examples for quick lookup
4. Provide field-specific examples based on the failed field

Files to Modify

• Update: pkg/workflow/schema_validation.go
• Update: pkg/workflow/schema_validation_test.go
• Create: Helper function for field extraction and example mapping

Example Improvements

Current behavior:

return fmt.Errorf("GitHub Actions schema validation failed: %w", err)

Improved behavior for timeout-minutes:

GitHub Actions schema validation failed for 'timeout-minutes': must be an integer. Example: timeout-minutes: 10

Improved behavior for engine:

GitHub Actions schema validation failed for 'engine': invalid value. Valid engines are: copilot, claude, codex, custom. Example: engine: copilot

Improved behavior for permissions:

GitHub Actions schema validation failed for 'permissions': must be an object with permission levels. Example: permissions:\\n  contents: read\\n  issues: write

Implementation Steps

1. Add helper function to extract field name from schema validation error message
2. Create map of field-specific examples for common fields:
   • timeout-minutes, engine, permissions, on, tools, etc.
3. Enhance validateGitHubActionsSchema() to parse the error and provide targeted examples
4. Add comprehensive tests for different schema validation failure scenarios

Acceptance Criteria

• Schema validation errors extract field name from validation error
• Field-specific examples are provided based on the failed field
• Common schema violations (type mismatches, missing fields) have tailored examples
• Error messages reference both the schema issue and provide inline examples
• Tests verify example inclusion in schema validation errors
• Handle cases where field name cannot be extracted (fallback to generic message)
• Run make test-unit to verify all tests pass

AI generated by Plan Command for discussion #4071</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [task] Add inline examples to schema validation errors #4074

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull Request Overview

This PR enhances schema validation error messages to provide inline, field-specific examples rather than requiring users to reference external documentation. When a GitHub Actions schema validation fails, users now receive helpful examples showing correct YAML syntax for the field in question.

Key changes:

• Added intelligent error enhancement to provide context-aware examples based on the failing field
• Implemented a comprehensive field example map covering 22 common workflow fields with fallback to generic type-based examples
• Added thorough test coverage including unit tests and integration tests for example quality

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
pkg/workflow/schema_validation.go	Enhanced with enhanceSchemaValidationError(), extractFieldPath(), and getFieldExample() functions to wrap validation errors with examples
pkg/workflow/schema_validation_test.go	Added comprehensive unit tests for field extraction, example generation, and error enhancement logic
pkg/workflow/schema_validation_integration_test.go	Added integration tests to verify workflow compilation and validate example quality for common fields

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The newlines in the example strings are double-escaped (\\\\n), which will render as literal \\n in error messages instead of actual line breaks. They should use single backslash (\\n) or use raw string literals with actual newlines.

[Copilot]

The newline is double-escaped (\\\\n), which will render as literal \\n in the error message instead of an actual line break. It should use single backslash (\\n).

Suggested change

	return fmt.Sprintf("Example: %s:\\n key: value", fieldPath)
	return fmt.Sprintf("Example: %s:\n key: value", fieldPath)