feat: regex introspection API — explain, verbose export, ASCII + SVG visualize + annotated errors (#272)

Ships the regex introspection API on the `Regex` wrapper — three new
methods that turn a compiled pattern into something a human can read,
plus a full retrofit of every error message to a shape that shows the
caller *where* the failure happened and *how* to fix it.

## `Regex.explain()`

Plain-English bullet list of what the pattern accepts, followed by a
small set of concrete accepted strings.

```
- The text must start with either "http" or "https".
- Then the text must have "://".
- Then the text must have one or more letters, digits, or underscores.

Text this pattern accepts:
    http://ab1
    https://b1_c
    http://1_c2d
```

## `Regex.to_verbose_string()`

An `re.VERBOSE`-compatible export where every fragment is annotated
inline. Copy-pasting the output into `re.compile(..., re.VERBOSE)`
compiles to the same pattern.

```
(?P<year>               # begin group named "year"
  \d{4}                 # exactly 4
)                       # end group named "year"
```

## `Regex.visualize(format='ascii')`

ASCII railroad diagram — `START` and `END` boxes flanking the pattern,
arrows between elements, fork/merge junctions for alternation,
dashed-caption blocks for captures and lookarounds.

```
                        +--------+
                   +--->| "cat"  |----+
                   |    +--------+    |
                   |                  |
   +-------+       |    +--------+    |   +-----+
   | START |------>+--->| "dog"  |----+-->| END |
   +-------+       |    +--------+    |   +-----+
                   |                  |
                   |    +--------+    |
                   +--->| "fish" |----+
                        +--------+
```

## `Regex.visualize(format='svg', engine='graphviz')`

SVG rendered by Graphviz. Junction-point fork/merge for alternation,
dashed rounded clusters for captures/lookarounds, folded two-line node
labels for quantifiers (e.g. `digit\n(one or more)`). Requires the
optional `graphviz` extra; the missing-dependency error names the
install command.

## Annotated error messages

Every exception across `edify.errors` — anchors, captures, input,
internal, naming, quantifier, structure — now emits a message that names
the offending call in the caller's source, explains the invariant that
was violated, and prescribes the fix:

```
error: start_of_input has already been added to this pattern

  --> user_code.py:14:26
   |
14 |     pattern = RegexBuilder().start_of_input().digit().start_of_input()
   |                                                       ^^^^^^^^^^^^^^^^ second start_of_input added here
   |
   = note: a pattern can carry at most one start_of_input anchor; the earlier .start_of_input() call already set it.

help: remove the duplicate .start_of_input() call from the chain.
```

Caller source location is captured via `sys._getframe()` walking to the
first non-edify frame and `co_positions()` for precise column spans.

## Other landings

- `Regex` retains the AST elements the builder produced; every
introspection method operates on the AST directly rather than parsing
the emitted regex string.
- Lazy compile cache on `BuilderCore` — a builder's `to_regex()` result
is memoised so `.match()` / `.search()` / `.explain()` share one
compiled pattern.
- `Regex.__getattr__` delegates any attribute not on the wrapper to the
underlying `re.Pattern`, so `.pattern`, `.flags`, `.groups`,
`.groupindex` continue to work.
- `Regex.__eq__` / `Regex.__hash__` raise when called on an unfinished
builder, pointing at both the compare/hash call site and the still-open
frame or dangling quantifier.
- Property test extended: every recursively-built composition of
quantifiers, groups, captures, named captures, and subexpressions emits
its expected regex exactly, no fragment dropped or duplicated.

1 files changed, 92 insertions, 0 deletions

diff --git a/tests/introspect/visualize.test.py b/tests/introspect/visualize.test.py
new file mode 100644
index 0000000..a1e2ef5
--- /dev/null
+++ b/tests/introspect/visualize.test.py
@@ -0,0 +1,92 @@
+"""Tests for the visualize dispatcher in :mod:`edify.introspect.visualize`."""
+
+import pytest
+
+from edify import RegexBuilder
+from edify.elements.types.leaves import DigitElement
+from edify.errors.introspect import (
+    UnsupportedVisualizationEngineError,
+    UnsupportedVisualizationFormatError,
+)
+from edify.introspect.visualize import visualize_elements
+
+
+def _digit_regex():
+    return RegexBuilder().digit().to_regex()
+
+
+def test_default_format_and_engine_produce_ascii_railroad_output():
+    output = visualize_elements((DigitElement(),))
+    assert "| START |" in output
+    assert "| digit |" in output
+    assert "| END |" in output
+
+
+def test_explicit_ascii_format_and_engine_produce_ascii_railroad_output():
+    output = visualize_elements((DigitElement(),), format="ascii", engine="ascii")
+    assert "| digit |" in output
+
+
+def test_ascii_format_with_wrong_engine_raises_engine_error():
+    with pytest.raises(UnsupportedVisualizationEngineError):
+        visualize_elements((DigitElement(),), format="ascii", engine="graphviz")
+
+
+def test_svg_format_with_graphviz_engine_produces_svg_output():
+    regex = _digit_regex()
+    output = visualize_elements(regex.elements, format="svg", engine="graphviz")
+    assert "</svg>" in output
+
+
+def test_svg_format_with_wrong_engine_raises_engine_error():
+    with pytest.raises(UnsupportedVisualizationEngineError):
+        visualize_elements((DigitElement(),), format="svg", engine="ascii")
+
+
+def test_unknown_format_raises_format_error():
+    with pytest.raises(UnsupportedVisualizationFormatError):
+        visualize_elements((DigitElement(),), format="pdf")
+
+
+def test_unknown_format_error_names_the_received_format_in_message():
+    with pytest.raises(UnsupportedVisualizationFormatError) as excinfo:
+        visualize_elements((DigitElement(),), format="mermaid")
+    assert "'mermaid'" in str(excinfo.value)
+
+
+def test_engine_error_names_both_format_and_engine_in_message():
+    with pytest.raises(UnsupportedVisualizationEngineError) as excinfo:
+        visualize_elements((DigitElement(),), format="ascii", engine="mermaid")
+    message = str(excinfo.value)
+    assert "'ascii'" in message
+    assert "'mermaid'" in message
+
+
+def test_regex_visualize_end_to_end_defaults_to_ascii():
+    regex = _digit_regex()
+    output = regex.visualize()
+    assert "| digit |" in output
+
+
+def test_regex_visualize_svg_end_to_end():
+    regex = _digit_regex()
+    output = regex.visualize(format="svg", engine="graphviz")
+    assert "</svg>" in output
+
+
+def test_regex_visualize_rejects_unknown_format_end_to_end():
+    regex = _digit_regex()
+    with pytest.raises(UnsupportedVisualizationFormatError):
+        regex.visualize(format="dot")
+
+
+def test_regex_visualize_rejects_engine_mismatch_end_to_end():
+    regex = _digit_regex()
+    with pytest.raises(UnsupportedVisualizationEngineError):
+        regex.visualize(format="svg", engine="ascii")
+
+
+def test_empty_elements_still_render_start_and_end():
+    output = visualize_elements(())
+    assert "START" in output
+    assert "END" in output