Search documentation of Ragex

# Ragex.Analysis.DependencyGraph.AIInsights (Ragex v0.4.0)

View Source

AI-powered context-aware insights for dependency analysis.

Uses AI to provide architectural recommendations for high-coupling modules, distinguishing between "good" coupling (central services) and "bad" coupling (tangled dependencies), and suggesting specific refactoring strategies.

## Features

- Context-aware coupling evaluation
- Architectural pattern recognition
- Refactoring strategy recommendations
- Technical debt assessment
- Circular dependency resolution strategies

## Usage

    alias Ragex.Analysis.DependencyGraph.AIInsights

    # Get insights for a high-coupling module
    coupling_data = %{
      module: MyApp.UserService,
      coupling_in: 15,
      coupling_out: 12,
      instability: 0.55,
      dependencies: [...]
    }

    {:ok, insights} = AIInsights.analyze_coupling(coupling_data)
    # => %{
    #   coupling_assessment: :concerning,
    #   reasoning: "High coupling due to...",
    #   recommendations: ["Extract user validation...", ...],
    #   refactoring_priority: :high
    # }

    # Analyze circular dependency
    {:ok, resolution} = AIInsights.resolve_circular_dependency(cycle_data)

## Configuration

    config :ragex, :ai_features,
      dependency_insights: true

## Summary

### Types

coupling_data()
coupling_insights()
cycle_data()
cycle_resolution()

### Functions

analyze_batch(coupling_list, opts \\ [])

Analyze multiple modules in batch.

analyze_coupling(coupling_data, opts \\ [])

Analyze coupling metrics for a module and provide AI insights.

clear_cache()

Clear the insights cache.

enabled?(opts \\ [])

Check if AI dependency insights are currently enabled.

resolve_circular_dependency(cycle_data, opts \\ [])

Analyze a circular dependency and suggest resolution strategies.

## Types

# coupling_data()

    @type coupling_data() :: map()

# coupling_insights()

    @type coupling_insights() :: %{
      coupling_assessment: :acceptable | :concerning | :problematic,
      reasoning: String.t(),
      recommendations: [String.t()],
      refactoring_priority: :low | :medium | :high,
      technical_debt_score: float()
    }

# cycle_data()

    @type cycle_data() :: map()

# cycle_resolution()

    @type cycle_resolution() :: %{
      resolution_strategy: String.t(),
      steps: [String.t()],
      estimated_effort: :small | :medium | :large,
      risks: [String.t()]
    }

## Functions

# analyze_batch(coupling_list, opts \\ [])

    @spec analyze_batch(
      [coupling_data()],
      keyword()
    ) :: {:ok, [coupling_insights()]} | {:error, term()}

Analyze multiple modules in batch.

# analyze_coupling(coupling_data, opts \\ [])

    @spec analyze_coupling(
      coupling_data(),
      keyword()
    ) :: {:ok, coupling_insights()} | {:error, term()}

Analyze coupling metrics for a module and provide AI insights.

Uses AI to evaluate whether coupling is appropriate given the module's architectural role, and provides specific recommendations.

## Parameters

- `coupling_data` - Module coupling metrics
- `opts` - Options:
  - `:ai_insights` - Enable/disable AI (default: from config)

## Returns

- `{:ok, coupling_insights}` - Assessment and recommendations
- `{:error, reason}` - Error if analysis fails

## Examples

    coupling_data = %{
      module: MyApp.UserService,
      coupling_in: 15,
      coupling_out: 8,
      instability: 0.35,
      dependencies: [MyApp.Repo, MyApp.Email, MyApp.Cache],
      dependents: [MyApp.Web.UserController, ...]
    }

    {:ok, insights} = AIInsights.analyze_coupling(coupling_data)
    # => %{
    #   coupling_assessment: :acceptable,
    #   reasoning: "UserService is a central service...",
    #   recommendations: ["Consider extracting email logic..."],
    #   refactoring_priority: :medium,
    #   technical_debt_score: 0.4
    # }

# clear_cache()

    @spec clear_cache() :: :ok

Clear the insights cache.

# enabled?(opts \\ [])

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

Check if AI dependency insights are currently enabled.

# resolve_circular_dependency(cycle_data, opts \\ [])

    @spec resolve_circular_dependency(
      cycle_data(),
      keyword()
    ) :: {:ok, cycle_resolution()} | {:error, term()}

Analyze a circular dependency and suggest resolution strategies.

Uses AI to understand the architectural issue and provide step-by-step refactoring guidance.

## Parameters

- `cycle_data` - Circular dependency information
- `opts` - Options (same as analyze_coupling/2)

## Returns

- `{:ok, cycle_resolution}` - Resolution strategy with steps
- `{:error, reason}` - Error if analysis fails

## Examples

    cycle_data = %{
      cycle: [ModuleA, ModuleB, ModuleC, ModuleA],
      dependencies: [
        {ModuleA, ModuleB, [:calls]},
        {ModuleB, ModuleC, [:imports]},
        {ModuleC, ModuleA, [:calls]}
      ]
    }

    {:ok, resolution} = AIInsights.resolve_circular_dependency(cycle_data)
    # => %{
    #   resolution_strategy: "Break cycle by extracting shared interface",
    #   steps: ["Create ModuleD with shared functions", ...],
    #   estimated_effort: :medium,
    #   risks: ["May require updating tests"]
    # }