@spec examples_hash() :: {:ok, String.t()} | {:error, String.t()}

Get a hash of all examples in the specification.

Used to detect changes to the specification over time.

@spec extract_examples() :: {:ok, map()} | {:error, String.t()}

Extract all examples from the specification.

Returns a map with categorized examples:

• examples - Testable examples as {code, expected, section} tuples
• todos - TODO markers as {code, description, section} tuples
• bugs - BUG markers as {code, description, section} tuples
• skipped - Count of illustrative examples (using ...)

Returns

{:ok, %{
  examples: [{"(+ 1 2)", 3, "## Section"}, ...],
  todos: [{"(code)", "description", "## Section"}, ...],
  bugs: [],
  skipped: 2
}}

@spec extract_examples(String.t()) :: map()

Extract examples from specification content string.

Parses the markdown content and extracts code examples with expected values, TODO markers, BUG markers, and counts skipped illustrative examples.

Parameters

• content - The specification markdown content as a string

Returns

%{
  examples: [{"(+ 1 2)", 3, "## Section"}, ...],
  todos: [{"(code)", "description", "## Section"}, ...],
  bugs: [],
  skipped: 2
}

@spec negative_tests() :: [tuple()]

Get negative test cases for Section 13 (unsupported features).

Returns a list of tuples: {feature_name, code, expected_error_type}. These programs should all fail with specific error types.

Returns

[
  {"def", "(def x 10)", :validation_error},
  {"defn", "(defn foo [x] x)", :validation_error},
  ...
]

@spec section_hashes() :: {:ok, map()} | {:error, String.t()}

Get hashes for each section of the specification.

Returns a map of section headers to their content hashes. Used to detect drift in specific sections of the spec.

Returns

{:ok, %{
  "## 1. Overview" => "hash1",
  "## 2. Lexical Structure" => "hash2",
  ...
}}

@spec validate_example(String.t(), any()) :: :ok | {:error, String.t()}

Validate a single example: code should produce expected result.

Returns :ok if validation passes, {:error, reason} otherwise.

Examples

iex> PtcRunner.Lisp.SpecValidator.validate_example("(+ 1 2)", 3)
:ok

iex> PtcRunner.Lisp.SpecValidator.validate_example("(+ 1 2)", 4)
{:error, "Expected 4 but got 3"}

@spec validate_negative_test(String.t(), atom()) :: :ok | {:error, String.t()}

Validate a negative test case (should fail with specific error).

Returns :ok if the code fails with the expected error type, {:error, reason} otherwise.

@spec validate_spec() :: {:ok, map()} | {:error, String.t()}

Validate all examples in the PTC-Lisp specification.

Returns a summary of results with counts of passed, failed, skipped examples, as well as TODO and BUG markers found in the spec.

Returns

{:ok, %{
  passed: 95,
  failed: 0,
  skipped: 2,
  todos: [{"(code)", "description", "## Section"}, ...],
  bugs: [],
  failures: [...]
}}