Ragex.Analysis.LocationEnricher (Ragex v0.14.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