Search documentation of Metastatic

# Metastatic.Validator (Metastatic v0.13.2)

View Source

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:

1. Structural conformance - AST structure matches M2 type definitions
2. Type safety - All type tags are valid M2 types
3. Semantic preservation - Required semantic information is present
4. 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"}}}