Ragex.Analysis.DependencyGraph.AIInsights (Ragex v0.8.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"]
# }