Ragex.Analysis.MetastaticBridge (Ragex v0.12.0)

View Source

Bridge to Metastatic analysis capabilities.

Delegates all AST-level analysis to Metastatic's analysis modules, providing a unified interface for Ragex to access:

  • Complexity metrics (cyclomatic, cognitive, nesting, Halstead, LoC, function metrics)
  • Purity analysis (side effect detection)

Usage

alias Ragex.Analysis.MetastaticBridge

# Analyze single file
{:ok, result} = MetastaticBridge.analyze_file("lib/my_module.ex")

# Analyze with specific metrics
{:ok, result} = MetastaticBridge.analyze_file("lib/my_module.ex",
  metrics: [:cyclomatic, :cognitive, :purity])

# Analyze directory
{:ok, results} = MetastaticBridge.analyze_directory("lib/")

Result Format

Analysis results include:

  • :path - File path
  • :language - Detected language
  • :complexity - Complexity metrics map
  • :purity - Purity analysis map
  • :warnings - List of warning strings
  • :timestamp - Analysis timestamp

Summary

Types

analysis_error()
analysis_result()

Functions

analyze_directory(path, opts \\ [])

Analyzes all files in a directory.

analyze_file(path, opts \\ [])

Analyzes a single file for code quality metrics.

domains()

Returns the list of supported semantic domains.

extract_operations(document, opts \\ [])

Extracts semantic operations from a document.

parse_file(path, opts \\ [])

Parses a file and returns a Metastatic Document.

supported_metrics()

Returns the list of supported metrics.

Types

analysis_error()

@type analysis_error() :: %{path: String.t(), error: term(), timestamp: DateTime.t()}

analysis_result()

@type analysis_result() :: %{
  path: String.t(),
  language: atom(),
  complexity: map(),
  purity: map(),
  warnings: [String.t()],
  timestamp: DateTime.t()
}

Functions

analyze_directory(path, opts \\ [])

@spec analyze_directory(path :: String.t(), opts :: keyword()) ::
  {:ok, [analysis_result()]} | {:error, term()}

Analyzes all files in a directory.

Options

  • :recursive - Recursively analyze subdirectories (default: true)
  • :metrics - List of metrics to calculate (default: all)
  • :thresholds - Custom threshold map
  • :parallel - Use parallel processing (default: true)
  • :max_concurrency - Maximum concurrent analyses (default: System.schedulers_online())

Examples

{:ok, results} = MetastaticBridge.analyze_directory("lib/")
Enum.each(results, fn result ->
  IO.puts("#{result.path}: cyclomatic=#{result.complexity.cyclomatic}")
end)

analyze_file(path, opts \\ [])

@spec analyze_file(path :: String.t(), opts :: keyword()) ::
  {:ok, analysis_result()} | {:error, term()}

Analyzes a single file for code quality metrics.

Delegates to Metastatic for all analysis operations.

Options

  • :metrics - List of metrics to calculate (default: all)
  • :thresholds - Custom threshold map for complexity warnings
  • :language - Explicit language (default: auto-detect)

Examples

{:ok, result} = MetastaticBridge.analyze_file("lib/my_module.ex")
result.complexity.cyclomatic  # => 5
result.purity.pure?           # => false

domains()

@spec domains() :: [atom()]

Returns the list of supported semantic domains.

Examples

iex> MetastaticBridge.domains()
[:db, :http, :auth, :cache, :queue, :file, :external_api]

extract_operations(document, opts \\ [])

@spec extract_operations(
  Metastatic.Document.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Extracts semantic operations from a document.

Returns a list of operations found in the AST, each tagged with:

  • :domain - The operation domain (:db, :http, :auth, etc.)
  • :operation - The specific operation (:retrieve, :create, etc.)
  • :target - The target entity (e.g., "User" for Repo.get(User, id))
  • :framework - The detected framework (:ecto, :django, etc.)

The document should be parsed with enrich: true for best results.

Options

  • :domain - Filter by specific domain (default: all)

Examples

{:ok, doc} = MetastaticBridge.parse_file("lib/my_module.ex", enrich: true)
{:ok, ops} = MetastaticBridge.extract_operations(doc)
{:ok, db_ops} = MetastaticBridge.extract_operations(doc, domain: :db)

parse_file(path, opts \\ [])

@spec parse_file(path :: String.t(), opts :: keyword()) ::
  {:ok, Metastatic.Document.t()} | {:error, term()}

Parses a file and returns a Metastatic Document.

This function is useful for accessing Metastatic's low-level analysis capabilities directly, such as dead code detection.

Options

  • :language - Explicit language (default: auto-detect)
  • :enrich - Apply semantic enrichment with OpKind metadata (default: false)

Semantic Enrichment

When enrich: true is passed, the AST is enriched with OpKind semantic metadata that tags function calls with their semantic meaning:

  • Domain: :db, :http, :auth, :cache, :queue, :file, :external_api
  • Operation: :retrieve, :create, :update, :delete, :query, etc.
  • Framework: :ecto, :django, :requests, etc.

Examples

# Basic parsing
{:ok, doc} = MetastaticBridge.parse_file("lib/my_module.ex")

# With semantic enrichment
{:ok, doc} = MetastaticBridge.parse_file("lib/my_module.ex", enrich: true)
Metastatic.Analysis.DeadCode.analyze(doc)

supported_metrics()

@spec supported_metrics() :: [atom()]

Returns the list of supported metrics.

Examples

iex> Ragex.Analysis.MetastaticBridge.supported_metrics()
[:cyclomatic, :cognitive, :nesting, :halstead, :loc, :function_metrics, :purity]