Ragex.Analysis.Semantic
(Ragex v0.12.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
Functions
Analyzes multiple files in a directory for semantic context.
Analyzes a file and returns semantic context.
Generates a human-readable description of semantic operations.
Returns the list of supported semantic domains.
Extracts semantic operations from a document.
Returns a summary of operations by domain.
Parses a file with semantic enrichment.
Extracts or filters security-relevant operations.
Types
@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() }
@type domain() :: :db | :http | :auth | :cache | :queue | :file | :external_api
@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
@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/")@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)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)"@spec domains() :: [domain()]
Returns the list of supported semantic domains.
Examples
iex> Ragex.Analysis.Semantic.domains()
[:db, :http, :auth, :cache, :queue, :file, :external_api]@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)@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}@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")@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)