Search documentation of Ragex

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

View Source

Priority ranking system for refactoring suggestions.

Scores suggestions based on multiple factors:

- Benefit (40%): Expected improvement from refactoring
- Impact (20%): Scope of change (number of affected files/modules)
- Risk (20%): Likelihood of introducing bugs (subtracted)
- Effort (10%): Time/complexity to implement (subtracted)
- Confidence (10%): Confidence in the detection

## Priority Levels

- critical (score > 0.8): Must address soon, high impact issues
- high (score > 0.6): Important improvements with good ROI
- medium (score > 0.4): Beneficial but not urgent
- low (score > 0.2): Optional improvements
- info (score <= 0.2): For awareness only

## Examples

    alias Ragex.Analysis.Suggestions.Ranker

    suggestion = %{
      pattern: :extract_function,
      confidence: 0.85,
      benefit_score: 0.8,
      effort_score: 0.5,
      impact: %{affected_files: 3, risk: :medium}
    }

    scored = Ranker.score_suggestion(suggestion)
    # => %{...suggestion, priority: :high, priority_score: 0.72}

## Summary

### Functions

adjust_for_pattern(suggestion)

Adjusts priority score based on pattern-specific factors.

calculate_roi(suggestion)

Calculates ROI (Return on Investment) for a suggestion.

calculate_statistics(suggestions)

Calculates statistics for a list of suggestions.

classify_priority(score)

Classifies a numeric priority score into a priority level.

compare_priority(sugg1, sugg2)

Compares two suggestions for sorting.

explain_score(suggestion)

Generates a human-readable explanation of the scoring.

filter_by_priority(suggestions, min_priority)

Filters suggestions by minimum priority level.

group_by_priority(suggestions)

Groups suggestions by priority level.

score_suggestion(suggestion)

Scores a suggestion and assigns a priority level.

## Functions

# adjust_for_pattern(suggestion)

Adjusts priority score based on pattern-specific factors.

Some patterns are inherently more important:

- Dead code removal: Low risk, easy win
- Complexity reduction: High benefit
- Coupling reduction: Medium-high effort, high benefit

# calculate_roi(suggestion)

Calculates ROI (Return on Investment) for a suggestion.

ROI = Benefit / Effort

Higher ROI means better return for the effort invested.

# calculate_statistics(suggestions)

Calculates statistics for a list of suggestions.

Returns map with:

- `:total` - Total number of suggestions
- `:by_priority` - Count by priority level
- `:average_score` - Average priority score
- `:average_roi` - Average ROI
- `:high_priority_count` - Count of high + critical

# classify_priority(score)

Classifies a numeric priority score into a priority level.

## Examples

    iex> Ranker.classify_priority(0.85)
    :critical

    iex> Ranker.classify_priority(0.65)
    :high

    iex> Ranker.classify_priority(0.15)
    :info

# compare_priority(sugg1, sugg2)

Compares two suggestions for sorting.

Returns:

- `:gt` if first has higher priority
- `:lt` if second has higher priority
- `:eq` if equal priority

# explain_score(suggestion)

Generates a human-readable explanation of the scoring.

## Examples

    explanation = Ranker.explain_score(suggestion)
    IO.puts(explanation)

# filter_by_priority(suggestions, min_priority)

Filters suggestions by minimum priority level.

## Examples

    suggestions
    |> Ranker.filter_by_priority(:high)
    # Returns only :critical and :high priority suggestions

# group_by_priority(suggestions)

Groups suggestions by priority level.

## Returns

Map with priority levels as keys and lists of suggestions as values.

# score_suggestion(suggestion)

Scores a suggestion and assigns a priority level.

## Parameters

- `suggestion` - Raw suggestion map from pattern detector

## Returns

- Suggestion with added `:priority` and `:priority_score` fields