Search documentation of Ragex

# Ragex.Analysis.Suggestions (Ragex v0.4.0)

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