Search documentation of Metastatic

# Metastatic.Semantic.OpKind (Metastatic v0.13.2)

View Source

Semantic operation kind metadata for MetaAST nodes.

OpKind captures the semantic meaning of function calls and operations, enabling analyzers to reason about code at a higher level than raw syntax.

## Structure

An OpKind is a keyword list with the following fields:

- `:domain` - The operation domain (required)
- `:operation` - The specific operation type (required)
- `:target` - The entity/resource being operated on (optional)
- `:async` - Whether this is an async operation (optional, default: false)
- `:framework` - The framework/library this pattern comes from (optional)

## Domains

Currently supported domains:

- `:db` - Database operations (CRUD, transactions, queries)

Future domains (not yet implemented):

- `:http` - HTTP client operations
- `:auth` - Authentication/authorization
- `:cache` - Cache operations
- `:queue` - Message queue operations
- `:file` - File I/O operations
- `:external_api` - External API calls

## Database Operations (`:db`)

Operation | Description
--- | ---
`:retrieve` | Fetch single record by primary key
`:retrieve_all` | Fetch multiple/all records
`:query` | Complex query with conditions
`:create` | Insert new record
`:update` | Update existing record
`:delete` | Delete record
`:transaction` | Transaction boundary
`:preload` | Eager load associations
`:aggregate` | Aggregation operations (count, sum, etc.)

## Examples

    # Elixir/Ecto: Repo.get(User, 1)
    [domain: :db, operation: :retrieve, target: "User", framework: :ecto]

    # Python/Django: User.objects.filter(active=True)
    [domain: :db, operation: :query, target: "User", framework: :django]

    # JavaScript/Sequelize: User.findAll()
    [domain: :db, operation: :retrieve_all, target: "User", framework: :sequelize]

## Usage in MetaAST

OpKind is stored in the metadata of `:function_call` nodes:

    {:function_call, [
      name: "Repo.get",
      line: 42,
      op_kind: [domain: :db, operation: :retrieve, target: "User"]
    ], [args...]}

Analyzers can check for the presence of `op_kind`:

    def analyze({:function_call, meta, _args} = node, _context) do
      case Keyword.get(meta, :op_kind) do
        nil -> use_heuristics(node)
        op_kind -> analyze_with_semantic(node, op_kind)
      end
    end

## Summary

### Types

auth_operation()

Auth operation types

cache_operation()

Cache operation types

db_operation()

Database operation types

domain()

Supported operation domains

external_api_operation()

External API operation types

file_operation()

File operation types

framework()

Known framework identifiers

http_operation()

HTTP operation types

operation()

All operation types (union of domain-specific operations)

queue_operation()

Queue operation types

t()

OpKind as a keyword list

### Functions

auth?(op_kind)

Checks if this is an auth operation.

auth_operations()

Returns all supported auth operations.

cache?(op_kind)

Checks if this is a cache operation.

cache_operations()

Returns all supported cache operations.

db?(op_kind)

Checks if this is a database operation.

db_operations()

Returns all supported database operations.

domain(op_kind)

Gets the domain from an OpKind.

domains()

Returns all supported domains.

external_api?(op_kind)

Checks if this is an external API operation.

external_api_operations()

Returns all supported external API operations.

file?(op_kind)

Checks if this is a file operation.

file_operations()

Returns all supported file operations.

http?(op_kind)

Checks if this is an HTTP operation.

http_operations()

Returns all supported HTTP operations.

new(domain, operation, opts \\ [])

Creates a new OpKind keyword list.

operation(op_kind)

Gets the operation from an OpKind.

queue?(op_kind)

Checks if this is a queue operation.

queue_operations()

Returns all supported queue operations.

read?(op_kind)

Checks if this is a read operation (retrieve, retrieve_all, query).

target(op_kind)

Gets the target from an OpKind.

valid?(op_kind)

Checks if a value is a valid OpKind.

write?(op_kind)

Checks if this is a write operation (create, update, delete).

## Types

# auth_operation()

    @type auth_operation() ::
      :login
      | :logout
      | :authenticate
      | :register
      | :verify_token
      | :generate_token
      | :refresh_token
      | :hash_password
      | :verify_password
      | :authorize
      | :oauth
      | :session

Auth operation types

# cache_operation()

    @type cache_operation() ::
      :get
      | :set
      | :delete
      | :clear
      | :invalidate
      | :expire
      | :exists
      | :increment
      | :decrement
      | :ttl
      | :fetch

Cache operation types

# db_operation()

    @type db_operation() ::
      :retrieve
      | :retrieve_all
      | :query
      | :create
      | :update
      | :delete
      | :transaction
      | :preload
      | :aggregate

Database operation types

# domain()

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

Supported operation domains

# external_api_operation()

    @type external_api_operation() ::
      :call | :upload | :download | :send | :charge | :webhook | :search | :sync

External API operation types

# file_operation()

    @type file_operation() ::
      :read
      | :write
      | :append
      | :delete
      | :copy
      | :move
      | :exists
      | :stat
      | :mkdir
      | :rmdir
      | :list
      | :open
      | :close

File operation types

# framework()

    @type framework() ::
      :ecto
      | :amnesia
      | :sqlalchemy
      | :django
      | :peewee
      | :sequelize
      | :typeorm
      | :prisma
      | :mongoose
      | :activerecord
      | :httpoison
      | :req
      | :tesla
      | :finch
      | :requests
      | :httpx
      | :aiohttp
      | :nethttp
      | :httparty
      | :faraday
      | :restclient
      | :fetch
      | :axios
      | :got
      | :superagent
      | :guardian
      | :pow
      | :bcrypt_elixir
      | :argon2_elixir
      | :pbkdf2_elixir
      | :comeonin
      | :ueberauth
      | :flask_login
      | :pyjwt
      | :jose
      | :passlib
      | :devise
      | :warden
      | :bcrypt_ruby
      | :passport
      | :jsonwebtoken
      | :bcryptjs
      | :auth0
      | :cachex
      | :concache
      | :nebulex
      | :ets
      | :redis_py
      | :django_cache
      | :flask_cache
      | :rails_cache
      | :dalli
      | :redis_rb
      | :node_cache
      | :ioredis
      | :broadway
      | :oban
      | :genstage
      | :amqp
      | :celery
      | :rq
      | :kombu
      | :sidekiq
      | :activejob
      | :resque
      | :bullmq
      | :amqplib
      | :agenda
      | :elixir_file
      | :elixir_io
      | :python_builtin
      | :python_os
      | :pathlib
      | :shutil
      | :ruby_file
      | :fileutils
      | :nodejs_fs
      | :nodejs_fs_promises
      | :ex_aws
      | :boto3
      | :aws_sdk
      | :aws_sdk_js
      | :stripe
      | :twilio
      | :sendgrid
      | :unknown

Known framework identifiers

# http_operation()

    @type http_operation() ::
      :get | :post | :put | :patch | :delete | :head | :options | :request | :stream

HTTP operation types

# operation()

    @type operation() ::
      db_operation()
      | http_operation()
      | auth_operation()
      | cache_operation()
      | queue_operation()
      | file_operation()
      | external_api_operation()

All operation types (union of domain-specific operations)

# queue_operation()

    @type queue_operation() ::
      :publish
      | :consume
      | :subscribe
      | :acknowledge
      | :reject
      | :enqueue
      | :dequeue
      | :schedule
      | :retry
      | :process

Queue operation types

# t()

    @type t() :: [
      domain: domain(),
      operation: operation(),
      target: String.t() | nil,
      async: boolean(),
      framework: framework() | nil
    ]

OpKind as a keyword list

## Functions

# auth?(op_kind)

    @spec auth?(t()) :: boolean()

Checks if this is an auth operation.

## Examples

    iex> op_kind = [domain: :auth, operation: :login]
    iex> Metastatic.Semantic.OpKind.auth?(op_kind)
    true

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.auth?(op_kind)
    false

# auth_operations()

    @spec auth_operations() :: [auth_operation()]

Returns all supported auth operations.

## Examples

    iex> Metastatic.Semantic.OpKind.auth_operations()
    [:login, :logout, :authenticate, :register, :verify_token, :generate_token, :refresh_token, :hash_password, :verify_password, :authorize, :oauth, :session]

# cache?(op_kind)

    @spec cache?(t()) :: boolean()

Checks if this is a cache operation.

## Examples

    iex> op_kind = [domain: :cache, operation: :get]
    iex> Metastatic.Semantic.OpKind.cache?(op_kind)
    true

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.cache?(op_kind)
    false

# cache_operations()

    @spec cache_operations() :: [cache_operation()]

Returns all supported cache operations.

## Examples

    iex> Metastatic.Semantic.OpKind.cache_operations()
    [:get, :set, :delete, :clear, :invalidate, :expire, :exists, :increment, :decrement, :ttl, :fetch]

# db?(op_kind)

    @spec db?(t()) :: boolean()

Checks if this is a database operation.

## Examples

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.db?(op_kind)
    true

    iex> op_kind = [domain: :http, operation: :get]
    iex> Metastatic.Semantic.OpKind.db?(op_kind)
    false

# db_operations()

    @spec db_operations() :: [db_operation()]

Returns all supported database operations.

## Examples

    iex> Metastatic.Semantic.OpKind.db_operations()
    [:retrieve, :retrieve_all, :query, :create, :update, :delete, :transaction, :preload, :aggregate]

# domain(op_kind)

    @spec domain(t()) :: domain() | nil

Gets the domain from an OpKind.

## Examples

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.domain(op_kind)
    :db

# domains()

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

Returns all supported domains.

## Examples

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

# external_api?(op_kind)

    @spec external_api?(t()) :: boolean()

Checks if this is an external API operation.

## Examples

    iex> op_kind = [domain: :external_api, operation: :call]
    iex> Metastatic.Semantic.OpKind.external_api?(op_kind)
    true

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.external_api?(op_kind)
    false

# external_api_operations()

    @spec external_api_operations() :: [external_api_operation()]

Returns all supported external API operations.

## Examples

    iex> Metastatic.Semantic.OpKind.external_api_operations()
    [:call, :upload, :download, :send, :charge, :webhook, :search, :sync]

# file?(op_kind)

    @spec file?(t()) :: boolean()

Checks if this is a file operation.

## Examples

    iex> op_kind = [domain: :file, operation: :read]
    iex> Metastatic.Semantic.OpKind.file?(op_kind)
    true

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.file?(op_kind)
    false

# file_operations()

    @spec file_operations() :: [file_operation()]

Returns all supported file operations.

## Examples

    iex> Metastatic.Semantic.OpKind.file_operations()
    [:read, :write, :append, :delete, :copy, :move, :exists, :stat, :mkdir, :rmdir, :list, :open, :close]

# http?(op_kind)

    @spec http?(t()) :: boolean()

Checks if this is an HTTP operation.

## Examples

    iex> op_kind = [domain: :http, operation: :get]
    iex> Metastatic.Semantic.OpKind.http?(op_kind)
    true

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.http?(op_kind)
    false

# http_operations()

    @spec http_operations() :: [http_operation()]

Returns all supported HTTP operations.

## Examples

    iex> Metastatic.Semantic.OpKind.http_operations()
    [:get, :post, :put, :patch, :delete, :head, :options, :request, :stream]

# new(domain, operation, opts \\ [])

    @spec new(domain(), operation(), keyword()) :: t()

Creates a new OpKind keyword list.

## Examples

    iex> Metastatic.Semantic.OpKind.new(:db, :retrieve)
    [domain: :db, operation: :retrieve, target: nil, async: false, framework: nil]

    iex> Metastatic.Semantic.OpKind.new(:db, :retrieve, target: "User", framework: :ecto)
    [domain: :db, operation: :retrieve, target: "User", async: false, framework: :ecto]

# operation(op_kind)

    @spec operation(t()) :: operation() | nil

Gets the operation from an OpKind.

## Examples

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.operation(op_kind)
    :retrieve

# queue?(op_kind)

    @spec queue?(t()) :: boolean()

Checks if this is a queue operation.

## Examples

    iex> op_kind = [domain: :queue, operation: :enqueue]
    iex> Metastatic.Semantic.OpKind.queue?(op_kind)
    true

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.queue?(op_kind)
    false

# queue_operations()

    @spec queue_operations() :: [queue_operation()]

Returns all supported queue operations.

## Examples

    iex> Metastatic.Semantic.OpKind.queue_operations()
    [:publish, :consume, :subscribe, :acknowledge, :reject, :enqueue, :dequeue, :schedule, :retry, :process]

# read?(op_kind)

    @spec read?(t()) :: boolean()

Checks if this is a read operation (retrieve, retrieve_all, query).

## Examples

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.read?(op_kind)
    true

    iex> op_kind = [domain: :db, operation: :create]
    iex> Metastatic.Semantic.OpKind.read?(op_kind)
    false

# target(op_kind)

    @spec target(t()) :: String.t() | nil

Gets the target from an OpKind.

## Examples

    iex> op_kind = [domain: :db, operation: :retrieve, target: "User"]
    iex> Metastatic.Semantic.OpKind.target(op_kind)
    "User"

# valid?(op_kind)

    @spec valid?(term()) :: boolean()

Checks if a value is a valid OpKind.

## Examples

    iex> Metastatic.Semantic.OpKind.valid?([domain: :db, operation: :retrieve])
    true

    iex> Metastatic.Semantic.OpKind.valid?([domain: :invalid, operation: :foo])
    false

    iex> Metastatic.Semantic.OpKind.valid?("not a keyword list")
    false

# write?(op_kind)

    @spec write?(t()) :: boolean()

Checks if this is a write operation (create, update, delete).

## Examples

    iex> op_kind = [domain: :db, operation: :create]
    iex> Metastatic.Semantic.OpKind.write?(op_kind)
    true

    iex> op_kind = [domain: :db, operation: :retrieve]
    iex> Metastatic.Semantic.OpKind.write?(op_kind)
    false