Search documentation of Ragex

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

View Source

Preserves location metadata from native AST through Metastatic analysis.

## Purpose

Phase 2 of comprehensive location solution: After extracting location info from native AST (Phase 1), this module attaches that information to Metastatic analysis results.

Since Metastatic's MetaAST abstraction strips location metadata, we maintain a separate location map and merge it back into analysis results.

## Strategy

1. Extract: Use ASTLocationExtractor to get native AST locations
2. Correlate: Match analysis results to location map by identifier
3. Merge: Attach location metadata to issues/smells/vulnerabilities
4. Fallback: Use LocationEnricher when native locations unavailable

## 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` - Map from ASTLocationExtractor
- `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)