Search documentation of Ragex

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

View Source

Semantic code analysis using Metastatic's OpKind metadata system.

This module provides access to semantic operation analysis, allowing extraction and analysis of code operations by domain (database, HTTP, authentication, caching, file I/O, etc.).

## OpKind Domains

The following semantic domains are supported:

- `:db` - Database operations (Ecto, Django ORM, ActiveRecord, Sequelize, etc.)
- `:http` - HTTP client operations (HTTPoison, Req, requests, axios, etc.)
- `:auth` - Authentication/authorization (Guardian, Pow, Devise, Passport, etc.)
- `:cache` - Cache operations (Cachex, Redis, Memcached, etc.)
- `:queue` - Message queue operations (Oban, Broadway, Celery, Sidekiq, etc.)
- `:file` - File I/O operations (File, fs, shutil, etc.)
- `:external_api` - External service calls (AWS, Stripe, Twilio, etc.)

## Usage

    alias Ragex.Analysis.Semantic

    # Parse file with semantic enrichment
    {:ok, doc} = Semantic.parse_file("lib/my_module.ex")

    # Extract all semantic operations
    {:ok, ops} = Semantic.extract_operations(doc)

    # Extract operations by domain
    {:ok, db_ops} = Semantic.extract_operations(doc, domain: :db)
    {:ok, http_ops} = Semantic.extract_operations(doc, domain: :http)

    # Analyze file for semantic context
    {:ok, context} = Semantic.analyze_file("lib/my_module.ex")

    # Get security-relevant operations
    {:ok, security_ops} = Semantic.security_operations(doc)

## Semantic Context

The semantic context provides AI-friendly summaries of code operations:

    %{
      file: "lib/user_controller.ex",
      domains: %{
        db: [%{operation: :retrieve, target: "User", framework: :ecto, count: 3}],
        http: [],
        auth: [%{operation: :authenticate, framework: :guardian, count: 1}]
      },
      summary: "Controller with 3 DB reads, 1 auth check",
      security_relevant: true
    }

## Summary

### Types

directory_result()
domain()
operation()
semantic_context()

### Functions

analyze_directory(path, opts \\ [])

Analyzes multiple files in a directory for semantic context.

analyze_file(path, opts \\ [])

Analyzes a file and returns semantic context.

describe_operations(operations)

Generates a human-readable description of semantic operations.

domains()

Returns the list of supported semantic domains.

extract_operations(document, opts \\ [])

Extracts semantic operations from a document.

operations_summary(operations)

Returns a summary of operations by domain.

parse_file(path, opts \\ [])

Parses a file with semantic enrichment.

security_operations(doc)

Extracts or filters security-relevant operations.

## Types

# directory_result()

    @type directory_result() :: %{
      path: String.t(),
      files: [String.t()],
      operations: [operation()],
      total_operations: non_neg_integer(),
      by_domain: %{required(domain()) => non_neg_integer()},
      security_relevant: boolean()
    }

# domain()

    @type domain() :: :db | :http | :auth | :cache | :queue | :file | :external_api

# operation()

    @type operation() :: %{
      domain: domain(),
      operation: atom(),
      target: String.t() | nil,
      framework: atom() | nil,
      async: boolean(),
      line: non_neg_integer() | nil
    }

# semantic_context()

    @type semantic_context() :: %{
      file: String.t(),
      language: atom(),
      domains: %{required(domain()) => [operation()]},
      summary: String.t(),
      security_relevant: boolean(),
      operation_count: non_neg_integer(),
      timestamp: DateTime.t()
    }

## Functions

# analyze_directory(path, opts \\ [])

    @spec analyze_directory(
      String.t(),
      keyword()
    ) :: {:ok, directory_result()} | {:error, term()}

Analyzes multiple files in a directory for semantic context.

## Options

- `:recursive` - Recursively analyze subdirectories (default: true)
- `:parallel` - Use parallel processing (default: true)
- `:max_concurrency` - Maximum concurrent analyses (default: System.schedulers_online())

## Examples

    {:ok, contexts} = Semantic.analyze_directory("lib/")

# analyze_file(path, opts \\ [])

    @spec analyze_file(
      String.t(),
      keyword()
    ) :: {:ok, semantic_context()} | {:error, term()}

Analyzes a file and returns semantic context.

Provides a structured summary of all semantic operations in the file, grouped by domain, with security relevance flagging.

## Examples

    {:ok, context} = Semantic.analyze_file("lib/user_controller.ex")
    context.security_relevant  # => true (has auth/db operations)

# describe_operations(operations)

    @spec describe_operations([operation()]) :: String.t()

Generates a human-readable description of semantic operations.

Useful for providing context to AI assistants.

## Examples

    {:ok, ops} = Semantic.extract_operations(doc)
    description = Semantic.describe_operations(ops)
    # => "5 database operations (3 retrieve, 2 create), 2 HTTP requests (get)"

# domains()

    @spec domains() :: [domain()]

Returns the list of supported semantic domains.

## Examples

    iex> Ragex.Analysis.Semantic.domains()
    [:db, :http, :auth, :cache, :queue, :file, :external_api]

# extract_operations(document, opts \\ [])

    @spec extract_operations(
      Metastatic.Document.t(),
      keyword()
    ) :: {:ok, [operation()]} | {:error, term()}

Extracts semantic operations from a document.

## Options

- `:domain` - Filter by specific domain (default: all)

## Examples

    {:ok, all_ops} = Semantic.extract_operations(doc)
    {:ok, db_ops} = Semantic.extract_operations(doc, domain: :db)

# operations_summary(operations)

    @spec operations_summary([operation()]) :: %{required(domain()) => non_neg_integer()}

Returns a summary of operations by domain.

## Examples

    summary = Semantic.operations_summary(operations)
    # => %{db: 5, http: 2, auth: 1, cache: 0, queue: 0, file: 3, external_api: 0}

# parse_file(path, opts \\ [])

    @spec parse_file(
      String.t(),
      keyword()
    ) :: {:ok, Metastatic.Document.t()} | {:error, term()}

Parses a file with semantic enrichment.

This parses the source code to MetaAST and enriches function calls with OpKind semantic metadata.

## Options

- `:language` - Explicit language (default: auto-detect)
- `:enrich` - Whether to apply semantic enrichment (default: true)

## Examples

    {:ok, doc} = Semantic.parse_file("lib/my_module.ex")

# security_operations(doc)

    @spec security_operations(Metastatic.Document.t() | [operation()]) ::
      {:ok, [operation()]} | {:error, term()} | [operation()]

Extracts or filters security-relevant operations.

When given a `Document`, extracts security-relevant operations from it. When given a list of operations, filters to security-relevant ones.

Returns operations from domains that are security-sensitive:

- `:db` - Database operations (SQL injection, data access)
- `:auth` - Authentication/authorization
- `:file` - File operations (path traversal)
- `:http` - HTTP operations (SSRF)
- `:external_api` - External APIs

Also includes operations with write/delete/modify actions.

## Examples

    # From document
    {:ok, security_ops} = Semantic.security_operations(doc)

    # From list
    security_ops = Semantic.security_operations(operations)