Search documentation of Ragex

# Ragex.Editor.ValidationAI (Ragex v0.4.0)

View Source

AI-enhanced validation error explanation and fix suggestions.

Wraps the standard Validator with optional AI explanations that provide:

- Human-readable error explanations
- Specific fix suggestions
- Similar patterns from the codebase
- Learning from past fixes

## Usage

    alias Ragex.Editor.ValidationAI

    # Validate with AI explanations
    case ValidationAI.validate_with_explanation(content, path: "lib/file.ex") do
      {:ok, :valid} ->
        :ok

      {:error, errors} ->
        # Errors enriched with ai_explanation and ai_suggestion fields
        Enum.each(errors, fn error ->
          IO.puts("Error: #{error.message}")
          if error[:ai_explanation] do
            IO.puts("Why: #{error.ai_explanation}")
            IO.puts("Fix: #{error.ai_suggestion}")
          end
        end)
    end

    # Or enrich existing validation errors
    {:error, errors} = Validator.validate(content, opts)
    enriched = ValidationAI.explain_errors(errors, content, opts)

## Configuration

    # config/runtime.exs
    config :ragex, :ai_features,
      validation_error_explanation: true

    # Disable for specific call
    ValidationAI.validate_with_explanation(content,
      path: "test.ex",
      ai_explain: false
    )

## Summary

### Types

enriched_error()
validation_result()

### Functions

clear_cache()

Clear the explanation cache.

enabled?(opts \\ [])

Check if AI explanations are currently enabled.

explain_errors(errors, content, opts \\ [])

Enrich existing validation errors with AI explanations.

explain_single_error(error, content, file_path, surrounding_lines \\ 3, opts \\ [])

Explain a single validation error.

validate_with_explanation(content, opts \\ [])

Validate code with AI-enhanced error explanations.

## Types

# enriched_error()

    @type enriched_error() :: Ragex.Editor.Types.validation_error()

# validation_result()

    @type validation_result() ::
      {:ok, :valid | :no_validator}
      | {:error, [Ragex.Editor.Types.validation_error()]}

## Functions

# clear_cache()

    @spec clear_cache() :: :ok

Clear the explanation cache.

Useful for testing or when you want fresh explanations.

# enabled?(opts \\ [])

    @spec enabled?(keyword()) :: boolean()

Check if AI explanations are currently enabled.

Takes into account config and optional overrides.

# explain_errors(errors, content, opts \\ [])

    @spec explain_errors([Ragex.Editor.Types.validation_error()], String.t(), keyword()) ::
      [
        enriched_error()
      ]

Enrich existing validation errors with AI explanations.

Takes errors from standard validation and adds AI-generated explanations and fix suggestions.

## Parameters

- `errors` - List of validation errors from Validator
- `content` - Original code content
- `opts` - Options (same as validate_with_explanation/2)

## Returns

- List of enriched errors with `:ai_explanation` and `:ai_suggestion` fields

## Examples

    {:error, errors} = Validator.validate(content, path: "lib/file.ex")
    enriched = ValidationAI.explain_errors(errors, content,
      path: "lib/file.ex"
    )

# explain_single_error(error, content, file_path, surrounding_lines \\ 3, opts \\ [])

    @spec explain_single_error(
      Ragex.Editor.Types.validation_error(),
      String.t(),
      String.t(),
      non_neg_integer(),
      keyword()
    ) :: enriched_error()

Explain a single validation error.

Lower-level function for explaining one error at a time.

## Parameters

- `error` - Single validation error
- `content` - Code content
- `file_path` - Path to file
- `surrounding_lines` - Lines of context (default: 3)
- `opts` - Additional options

## Returns

- Enriched error with AI fields

# validate_with_explanation(content, opts \\ [])

    @spec validate_with_explanation(
      String.t(),
      keyword()
    ) :: validation_result()

Validate code with AI-enhanced error explanations.

This is the main entry point for AI-enhanced validation. It performs standard validation and optionally enriches errors with AI explanations.

## Parameters

- `content` - Code content to validate
- `opts` - Options:
  - `:path` - File path (for language detection)
  - `:language` - Explicit language override
  - `:ai_explain` - Enable/disable AI (default: from config)
  - `:surrounding_lines` - Lines of context around error (default: 3)
  - `:timeout` - AI timeout in ms (default: from feature config)

## Returns

- `{:ok, :valid}` if validation passes
- `{:ok, :no_validator}` if no validator available
- `{:error, [enriched_error]}` if validation fails (with AI explanations)

## Examples

    # Basic usage
    ValidationAI.validate_with_explanation(code, path: "lib/module.ex")

    # Disable AI for this call
    ValidationAI.validate_with_explanation(code,
      path: "lib/module.ex",
      ai_explain: false
    )

    # Custom timeout
    ValidationAI.validate_with_explanation(code,
      path: "lib/module.ex",
      timeout: 10_000
    )