Metastatic.Validator (Metastatic v0.10.4)

Conformance validation for MetaAST.

This module provides formal M1 → M2 conformance checking and validation of MetaAST structures according to the theoretical foundations.

New 3-Tuple Format

All MetaAST nodes are uniform 3-element tuples:

{type_atom, keyword_meta, children_or_value}

Conformance Rules (Definition 8 from THEORETICAL_FOUNDATIONS.md)

A term t ∈ M1 conforms to M2 if it can be represented by M2 meta-types without loss of essential semantic information. Validation checks:

Structural conformance - AST structure matches M2 type definitions
Type safety - All type tags are valid M2 types
Semantic preservation - Required semantic information is present
Native escape hatches - M2.3 used only when necessary

Validation Levels

Strict - No M2.3 native constructs allowed (M2.1 + M2.2 + M2.2s only)
Standard - M2.3 allowed but discouraged
Permissive - All M2 levels accepted

Note: M2.2s (Structural/Organizational layer) is part of the extended layer and includes container, function_def, attribute_access, augmented_assignment, and property types.

Usage

# Validate a MetaAST document
alias Metastatic.Validator

doc = %Metastatic.Document{
  ast: {:binary_op, [category: :arithmetic, operator: :+],
        [{:variable, [], "x"}, {:literal, [subtype: :integer], 5}]},
  language: :python,
  metadata: %{}
}

Validator.validate(doc)
# => {:ok, %{level: :core, native_constructs: 0, warnings: []}}

# Strict validation (reject native constructs)
Validator.validate(doc, mode: :strict)
# => {:ok, %{...}} or {:error, :native_constructs_not_allowed}

Validation Result

Returns:

{:ok, metadata} - Valid MetaAST with validation metadata
{:error, reason} - Invalid structure

Metadata includes:

:level - Highest M2 level used (:core, :extended, :native)
:native_constructs - Count of M2.3 language_specific nodes
:warnings - List of validation warnings
:variables - Set of all variables referenced
:depth - Maximum AST depth

Summary

Types

validation_mode()

validation_result()

Functions

valid?(document, opts \\ [])

Quick validation check - returns boolean.

validate(document, opts \\ [])

Validate a MetaAST document.

validate_ast(ast, opts \\ [])

Validate just the AST structure (without Document wrapper).

Types

validation_mode()

@type validation_mode() :: :strict | :standard | :permissive

validation_result()

@type validation_result() :: {:ok, map()} | {:error, term()}

Functions

valid?(document, opts \\ [])

@spec valid?(
  Metastatic.Document.t(),
  keyword()
) :: boolean()

Quick validation check - returns boolean.

Examples

iex> doc = %Metastatic.Document{ast: {:literal, [subtype: :integer], 42}, language: :python, metadata: %{}}
iex> Metastatic.Validator.valid?(doc)
true

iex> invalid_doc = %Metastatic.Document{ast: {:bad, [], "ast"}, language: :python, metadata: %{}}
iex> Metastatic.Validator.valid?(invalid_doc)
false

validate(document, opts \\ [])

@spec validate(
  Metastatic.Document.t(),
  keyword()
) :: validation_result()

Validate a MetaAST document.

Options

:mode - Validation mode (:strict, :standard, :permissive)
:max_depth - Maximum allowed AST depth (default: 1000)
:max_variables - Maximum unique variables (default: 10000)

Examples

iex> doc = %Metastatic.Document{ast: {:literal, [subtype: :integer], 42}, language: :python, metadata: %{}}
iex> {:ok, meta} = Metastatic.Validator.validate(doc)
iex> meta.level
:core

iex> invalid_doc = %Metastatic.Document{ast: {:invalid_type, [], "oops"}, language: :python, metadata: %{}}
iex> Metastatic.Validator.validate(invalid_doc)
{:error, {:invalid_structure, {:invalid_type, [], "oops"}}}

validate_ast(ast, opts \\ [])

@spec validate_ast(
  Metastatic.AST.meta_ast(),
  keyword()
) :: validation_result()

Validate just the AST structure (without Document wrapper).

Examples

iex> {:ok, meta} = Metastatic.Validator.validate_ast({:literal, [subtype: :integer], 42})
iex> meta.level
:core

iex> Metastatic.Validator.validate_ast({:invalid, [], "nope"})
{:error, {:invalid_structure, {:invalid, [], "nope"}}}