Ragex.Editor.Refactor.AIPreview (Ragex v0.8.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)