Search documentation of Ragex

# Ragex.Editor.Refactor.AIPreview (Ragex v0.4.0)

View Source

AI-enhanced refactoring preview commentary.

Provides natural language summaries, risk assessments, and recommendations for refactoring operations before they are executed.

## Features

- Natural language summary of what will change
- Risk assessment based on impact analysis
- Actionable recommendations
- Learning from similar refactorings in the codebase

## Usage

    alias Ragex.Editor.Refactor.AIPreview

    # Generate commentary for a refactoring operation
    preview_data = %{
      operation: :rename_function,
      params: %{module: :MyModule, old_name: :old_func, new_name: :new_func},
      affected_files: ["lib/my_module.ex", "test/my_module_test.exs"],
      diff: "..."
    }

    case AIPreview.generate_commentary(preview_data) do
      {:ok, commentary} ->
        IO.puts("Summary: #{commentary.summary}")
        IO.puts("Risk Level: #{commentary.risk_level}")
        Enum.each(commentary.recommendations, &IO.puts("- #{&1}"))

      {:error, reason} ->
        Logger.warning("Failed to generate AI commentary: #{reason}")
    end

## Configuration

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

    # Disable for specific call
    AIPreview.generate_commentary(preview_data, ai_preview: false)

## Summary

### Types

commentary()
preview_data()

### Functions

clear_cache()

Clear the preview commentary cache.

enabled?(opts \\ [])

Check if AI preview commentary is currently enabled.

generate_commentary(preview_data, opts \\ [])

Generate AI commentary for a refactoring preview.

## Types

# commentary()

    @type commentary() :: %{
      summary: String.t(),
      risk_level: :low | :medium | :high | :critical,
      risks: [String.t()],
      recommendations: [String.t()],
      estimated_impact: String.t(),
      confidence: float()
    }

# preview_data()

    @type preview_data() :: %{
      :operation => atom(),
      :params => map(),
      :affected_files => [String.t()],
      optional(:diff) => String.t(),
      optional(:stats) => map()
    }

## Functions

# clear_cache()

    @spec clear_cache() :: :ok

Clear the preview commentary cache.

Useful for testing or when you want fresh commentaries.

# enabled?(opts \\ [])

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

Check if AI preview commentary is currently enabled.

Takes into account config and optional overrides.

# generate_commentary(preview_data, opts \\ [])

    @spec generate_commentary(
      preview_data(),
      keyword()
    ) :: {:ok, commentary()} | {:error, term()}

Generate AI commentary for a refactoring preview.

Analyzes the refactoring operation and generates natural language explanations, risk assessments, and recommendations.

## Parameters

- `preview_data` - Map containing operation details
- `opts` - Options:
  - `:ai_preview` - Enable/disable AI (default: from config)
  - `:provider` - AI provider override
  - `:timeout` - AI timeout in ms (default: from feature config)
  - `:include_recommendations` - Include recommendations (default: true)

## Returns

- `{:ok, commentary}` - Generated commentary
- `{:error, reason}` - Error if generation fails

## Examples

    preview = %{
      operation: :rename_function,
      params: %{module: :MyModule, old_name: :old, new_name: :new, arity: 2},
      affected_files: ["lib/my_module.ex"],
      stats: %{lines_changed: 5, files_affected: 1}
    }

    {:ok, commentary} = AIPreview.generate_commentary(preview)