Ragex.Analysis.Suggestions (Ragex v0.3.1)

View Source

Automated refactoring suggestion engine.

Analyzes code to identify refactoring opportunities by combining:

  • Code duplication detection (Type I-IV clones)
  • Dead code detection (interprocedural + intraprocedural)
  • Quality metrics (complexity, coupling, instability)
  • Impact analysis (risk scoring, effort estimation)
  • Dependency analysis (circular dependencies, god modules)

Each suggestion includes:

  • Pattern type (extract_function, split_module, etc.)
  • Priority level (critical, high, medium, low, info)
  • Actionable plan with step-by-step instructions
  • RAG-powered context-aware advice (optional)

Usage

alias Ragex.Analysis.Suggestions

# Analyze a module for refactoring opportunities
{:ok, suggestions} = Suggestions.analyze_target({:module, MyModule})

# Analyze a file
{:ok, suggestions} = Suggestions.analyze_target("lib/my_module.ex")

# Analyze a directory
{:ok, suggestions} = Suggestions.analyze_target("lib/", recursive: true)

# Filter by priority
{:ok, high_priority} = Suggestions.analyze_target(target, min_priority: :high)

# Get specific patterns only
{:ok, complexity} = Suggestions.analyze_target(target, patterns: [:simplify_complexity])

Summary

Types

analysis_result()
pattern()
priority()
suggestion()
target()

Functions

analyze_target(target, opts \\ [])

Analyzes a target (module, function, file, or directory) for refactoring opportunities.

suggest_for_pattern(target, pattern, opts \\ [])

Generates suggestions for a specific pattern type.

Types

analysis_result()

@type analysis_result() :: %{
  suggestions: [suggestion()],
  summary: map(),
  target: target(),
  analyzed_at: DateTime.t()
}

pattern()

@type pattern() ::
  :extract_function
  | :inline_function
  | :split_module
  | :merge_modules
  | :remove_dead_code
  | :reduce_coupling
  | :simplify_complexity
  | :extract_module

priority()

@type priority() :: :critical | :high | :medium | :low | :info

suggestion()

@type suggestion() :: %{
  id: String.t(),
  pattern: pattern(),
  priority: priority(),
  priority_score: float(),
  target: map(),
  reason: String.t(),
  metrics: map(),
  impact: map(),
  effort: map(),
  benefit: String.t(),
  confidence: float(),
  rag_advice: String.t() | nil,
  action_plan: map() | nil,
  examples: [String.t()]
}

target()

@type target() ::
  {:module, module()}
  | {:function, module(), atom(), non_neg_integer()}
  | String.t()

Functions

analyze_target(target, opts \\ [])

@spec analyze_target(
  target(),
  keyword()
) :: {:ok, analysis_result()} | {:error, term()}

Analyzes a target (module, function, file, or directory) for refactoring opportunities.

Parameters

  • target - Target to analyze:
    • {:module, module()} - Analyze a specific module
    • {:function, module, name, arity} - Analyze a specific function
    • string - File or directory path
  • opts - Keyword list of options:
    • :patterns - Filter by pattern types (default: all)
    • :min_priority - Minimum priority level (default: :low)
    • :include_actions - Include action plans (default: true)
    • :use_rag - Use RAG for enhanced advice (default: false)
    • :recursive - For directories, scan recursively (default: true)

Returns

  • {:ok, analysis_result} - Analysis with suggestions
  • {:error, reason} - Error if analysis fails

Examples

iex> {:ok, analysis} = Suggestions.analyze_target({:module, MyModule})
iex> length(analysis.suggestions)
5

suggest_for_pattern(target, pattern, opts \\ [])

@spec suggest_for_pattern(target(), pattern(), keyword()) ::
  {:ok, [suggestion()]} | {:error, term()}

Generates suggestions for a specific pattern type.

Parameters

  • target - Target to analyze
  • pattern - Pattern type to detect
  • opts - Options (same as analyze_target/2)

Returns

  • {:ok, [suggestion]} - List of suggestions for the pattern
  • {:error, reason} - Error if analysis fails