Search documentation of Ragex

# Ragex.Analysis.MetastaticBridge (Ragex v0.4.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]