@callback analyze(node :: Metastatic.AST.meta_ast(), context :: context()) :: [issue()]

Analyzes a single AST node in context.

Called once per node during AST traversal. Returns a list of issues found at this node. Return empty list if no issues.

The context includes:

• Current document
• Analyzer configuration
• Parent node stack
• Current depth
• Custom scope data

Examples

@impl true
# New 3-tuple format: {:literal, [subtype: :integer, ...], value}
def analyze({:literal, meta, value} = node, _context) do
  subtype = Keyword.get(meta, :subtype)
  if subtype == :integer and value > 1000 do
    [
      %{
        analyzer: __MODULE__,
        category: :style,
        severity: :warning,
        message: "Large literal value #{value}",
        node: node,
        location: %{line: nil, column: nil, path: nil},
        suggestion: nil,
        metadata: %{value: value}
      }
    ]
  else
    []
  end
end

def analyze(_node, _context), do: []

@callback info() :: info()

Returns metadata about this analyzer.

Must include:

• :name - Unique identifier (atom)
• :category - Analysis category
• :description - Brief one-line description
• :severity - Default severity level
• :explanation - Detailed explanation (can be multi-line)
• :configurable - Whether analyzer accepts configuration

Examples

@impl true
def info do
  %{
    name: :unused_variables,
    category: :correctness,
    description: "Detects variables that are assigned but never used",
    severity: :warning,
    explanation: """
    Variables that are assigned but never referenced add noise and
    may indicate bugs or incomplete code.
    """,
    configurable: true
  }
end

@callback run_after(context :: context(), issues :: [issue()]) :: [issue()]

Optional: Called once after AST traversal completes.

Use this for:

• Final analysis requiring full AST knowledge
• Cross-node validation
• Generating summary issues

Receives all issues collected so far. Can return modified or additional issues.

Examples

@impl true
def run_after(context, issues) do
  # Generate issues from collected state
  assigned = Map.keys(context.assigned)
  used = context.used

  unused = Enum.filter(assigned, fn var ->
    not MapSet.member?(used, var)
  end)

  new_issues = Enum.map(unused, fn var ->
    %{
      analyzer: __MODULE__,
      category: :correctness,
      severity: :warning,
      message: "Variable '#{var}' is assigned but never used",
      node: {:variable, [], var},  # New 3-tuple format
      location: %{line: nil, column: nil, path: nil},
      suggestion: nil,
      metadata: %{variable: var}
    }
  end)

  issues ++ new_issues
end

@callback run_before(context :: context()) :: {:ok, context()} | {:skip, reason :: term()}

Optional: Called once before AST traversal starts.

Use this for:

• Initializing analyzer state
• Pre-processing the document
• Checking if analysis should proceed

Return {:ok, context} to continue with (possibly modified) context. Return {:skip, reason} to skip this analyzer entirely.

Examples

@impl true
def run_before(context) do
  # Initialize state in context
  context = Map.put(context, :assigned, %{})
  context = Map.put(context, :used, MapSet.new())
  {:ok, context}
end

# Or skip if conditions not met
def run_before(context) do
  if context.document.language == :unsupported do
    {:skip, :unsupported_language}
  else
    {:ok, context}
  end
end