Search documentation of Ragex

# Ragex.Analysis.LocationEnricher (Ragex v0.4.0)

View Source

Enriches analysis results with accurate location information from the knowledge graph.

## Purpose

Metastatic's MetaAST abstraction intentionally strips language-specific details like line numbers to enable language-agnostic analysis. However, Ragex's knowledge graph contains accurate location information extracted during initial code analysis.

This module bridges the gap by enriching Metastatic analysis results with location data from the knowledge graph.

## Usage

    alias Ragex.Analysis.LocationEnricher

    # Enrich a single issue/smell
    enriched = LocationEnricher.enrich_issue(issue, file_path)

    # Enrich list of issues
    enriched_list = LocationEnricher.enrich_issues(issues, file_path)

    # Find function containing a location
    {:ok, func} = LocationEnricher.find_function_at_location(file_path, line: 42)

## Enrichment Strategy

1. Direct match: If issue has function/module context, match against graph
2. Line-based match: Find function containing the reported line number
3. File-based fallback: Return file-level location if no function match
4. Preserve original: Keep Metastatic data if graph unavailable

## Summary

### Types

issue()
location()

### Functions

enrich_issue(issue, file_path \\ nil)

Enriches a single issue with location data from the knowledge graph.

enrich_issues(issues, file_path \\ nil)

Enriches a list of issues with location data.

extract_snippet(file_path, start_line, end_line)

Extracts code snippet from a file given line range.

find_function_at_location(file_path, opts)

Finds the function at a specific location in a file.

## Types

# issue()

    @type issue() :: %{
      optional(:location) => location() | nil,
      optional(:line) => non_neg_integer() | nil,
      optional(:column) => non_neg_integer() | nil,
      optional(:file) => String.t() | nil,
      optional(:context) => map()
    }

# location()

    @type location() :: %{
      optional(:file) => String.t(),
      optional(:line) => non_neg_integer() | nil,
      optional(:column) => non_neg_integer() | nil,
      optional(:module) => atom() | nil,
      optional(:function) => atom() | nil,
      optional(:arity) => non_neg_integer() | nil,
      optional(:formatted) => String.t()
    }

## Functions

# enrich_issue(issue, file_path \\ nil)

    @spec enrich_issue(issue(), String.t() | nil) :: issue()

Enriches a single issue with location data from the knowledge graph.

## Parameters

- `issue` - Issue map from analysis (must have file or location)
- `file_path` - Optional file path override

## Returns

Enriched issue with updated location fields

# enrich_issues(issues, file_path \\ nil)

    @spec enrich_issues([issue()], String.t() | nil) :: [issue()]

Enriches a list of issues with location data.

# extract_snippet(file_path, start_line, end_line)

    @spec extract_snippet(String.t(), non_neg_integer(), non_neg_integer()) ::
      {:ok, String.t()} | {:error, term()}

Extracts code snippet from a file given line range.

## Parameters

- `file_path` - Path to source file
- `start_line` - Starting line number (1-indexed)
- `end_line` - Ending line number (1-indexed)

## Returns

- `{:ok, snippet}` - Code snippet as string
- `{:error, reason}` - Failed to read file

# find_function_at_location(file_path, opts)

    @spec find_function_at_location(
      String.t(),
      keyword()
    ) :: {:ok, map()} | {:error, :not_found}

Finds the function at a specific location in a file.

## Parameters

- `file_path` - Path to source file
- `opts` - Keyword list with `:line` or `:module` and `:function`

## Returns

- `{:ok, function_info}` - Function metadata from graph
- `{:error, :not_found}` - No matching function found