Ragex.Analysis.LocationPreservation (Ragex v0.13.0)

View Source

Preserves location metadata through Metastatic analysis.

Purpose

Merges location information into Metastatic analysis results. When the analysis result does not already carry precise line/column data, falls back to LocationEnricher which uses the knowledge graph.

Strategy

  1. Check: If a pre-populated location_map is provided, try to match by identifier
  2. Fallback: Use LocationEnricher for knowledge-graph-based location enrichment
  3. Preserve: Keep any existing location data on issues

Usage

alias Ragex.Analysis.LocationPreservation

# Wrap Metastatic analysis with location preservation
{:ok, result} = LocationPreservation.with_locations(path, fn ->
  # Your Metastatic analysis here
  Metastatic.Analysis.Security.analyze(doc)
end)

# Result now includes native AST locations merged with analysis data

Summary

Functions

merge_location_into_issue(issue, location_map, file_path, use_enricher \\ true)

Merges native AST location into a single issue.

merge_locations(issues, location_map, file_path, opts \\ [])

Merges native AST locations into analysis issues/results.

with_locations(path, analysis_fn, opts \\ [])

Executes analysis function with location preservation.

Functions

merge_location_into_issue(issue, location_map, file_path, use_enricher \\ true)

@spec merge_location_into_issue(map(), map(), String.t(), boolean()) :: map()

Merges native AST location into a single issue.

Strategy

  1. Try to match issue to location map by:
    • Module.function/arity key
    • Module name key
    • Function name from context
  2. If no match, use LocationEnricher (if enabled)
  3. Preserve any existing location data

Parameters

  • issue - Single issue map
  • location_map - Native AST locations
  • file_path - Source file path
  • use_enricher - Whether to use LocationEnricher fallback

Returns

  • Issue map with merged location

merge_locations(issues, location_map, file_path, opts \\ [])

@spec merge_locations([map()], map(), String.t(), keyword()) :: [map()]

Merges native AST locations into analysis issues/results.

Takes a list of issues (from Security, BusinessLogic, Smells, etc.) and enriches them with location data from the native AST location map.

Parameters

  • issues - List of issue maps from analysis
  • location_map - Optional pre-computed location map (pass %{} if unavailable)
  • file_path - Source file path (for fallback enrichment)
  • opts - Keyword options
    • :fallback_enricher - Use LocationEnricher when AST locations missing (default: true)

Returns

  • List of issues with merged location data

Examples

issues = [%{category: :injection, severity: :high, context: %{function: "process"}}]
location_map = %{"MyModule.process/2" => %{line: 42, column: 5}}
enriched = LocationPreservation.merge_locations(issues, location_map, "lib/file.ex")

with_locations(path, analysis_fn, opts \\ [])

@spec with_locations(String.t(), (Metastatic.Document.t() -> any()), keyword()) ::
  {:ok, any()} | {:error, term()}

Executes analysis function with location preservation.

Extracts native AST locations, runs analysis, then merges locations into results.

Parameters

  • path - Source file path
  • analysis_fn - Function that performs analysis (receives Document)
  • opts - Keyword options
    • :language - Override language detection
    • :fallback_enricher - Use LocationEnricher as fallback (default: true)

Returns

  • {:ok, result_with_locations} - Analysis result with merged locations
  • {:error, reason} - Analysis or extraction failed

Examples

{:ok, result} = LocationPreservation.with_locations("lib/my_module.ex", fn doc ->
  Metastatic.Analysis.Security.analyze(doc)
end)