feat!: Regex result wrapper on .to_regex(), plus flag kwargs at the terminal (#270)

Reshapes what `.to_regex()` returns and takes, so pattern compilation
becomes a first-class edify value.

## `Regex` result wrapper class
`edify.Regex` is a composition wrapper over `re.Pattern` (which is a
CPython C type and cannot be subclassed). It exposes:
- `.source` — the emitted regex string.
- `.compiled` — the underlying `re.Pattern` for callers that need
identity checks, `isinstance` checks, or direct interop with libraries
typed on `re.Pattern`.
- Eight direct delegates — `.match()`, `.search()`, `.fullmatch()`,
`.findall()`, `.finditer()`, `.sub()`, `.subn()`, `.split()` — mirroring
the `re.Pattern` query surface.
- Value equality on `(source, flags)` plus `__hash__`.

## `to_regex()` now returns `Regex`
The terminal returns `edify.Regex` instead of raw `re.Pattern`. The
existing eight query methods continue to work via delegation. `.match()`
/ `.search()` / … on builders (via `MatcherMixin`) still work because
they go through the same delegation.

**Breaking:** `isinstance(x, re.Pattern)` and `re.Pattern`-typed
annotations on values returned from `.to_regex()` break. Callers that
need the raw pattern read `.compiled`.

## Flag kwargs on `.to_regex(...)`
`.to_regex()` now accepts six keyword-only flag arguments —
`ascii_only`, `debug`, `ignore_case`, `multiline`, `dotall`, `verbose` —
that OR-merge into the flag snapshot the builder already carries.
Passing `ignore_case=True` at the terminal is equivalent to calling
`.ignore_case()` mid-chain. Kwargs never turn a chain-set flag off; the
terminal is the natural home for pattern-global settings.

## Example
```python
from edify import RegexBuilder

email = RegexBuilder().start_of_input().one_or_more().letter().end_of_input()
regex = email.to_regex(ignore_case=True)

regex.source                  # ^[a-zA-Z]+$
regex.match("Hello")          # <re.Match ...>
regex.compiled                # <re.Pattern object; flags=re.IGNORECASE>
```

Closes #133
Closes #134
Closes #128

5 files changed, 172 insertions, 3 deletions

diff --git a/tests/builder/builder.test.py b/tests/builder/builder.test.py
index ddd1997..82aa1cf 100644
--- a/tests/builder/builder.test.py
+++ b/tests/builder/builder.test.py
@@ -47,7 +47,7 @@ def regex_equality(regex, rb_expression):
 
 def regex_compilation(regex, rb_expression, f=0):
     rb_expression_c = rb_expression.to_regex()
-    assert re.compile(regex, flags=f) == rb_expression_c
+    assert re.compile(regex, flags=f) == rb_expression_c.compiled
 
 
 def test_empty_regex():
diff --git a/tests/builder/flags.test.py b/tests/builder/flags.test.py
new file mode 100644
index 0000000..d35d2ff
--- /dev/null
+++ b/tests/builder/flags.test.py
@@ -0,0 +1,72 @@
+"""Tests for the flag keyword arguments on :meth:`TerminalsMixin.to_regex`."""
+
+import re
+import sys
+
+import pytest
+
+from edify import Pattern, RegexBuilder
+
+_ON_PYPY = hasattr(sys, "pypy_version_info")
+
+
+def test_no_kwargs_uses_only_the_chain_flag_snapshot():
+    compiled = RegexBuilder().string("hi").to_regex()
+    assert compiled.compiled.flags & re.I == 0
+
+
+def test_ignore_case_kwarg_enables_the_ignore_case_flag():
+    compiled = RegexBuilder().string("hi").to_regex(ignore_case=True)
+    assert compiled.compiled.flags & re.I == re.I
+
+
+def test_multiline_kwarg_enables_the_multiline_flag():
+    compiled = RegexBuilder().string("hi").to_regex(multiline=True)
+    assert compiled.compiled.flags & re.M == re.M
+
+
+def test_dotall_kwarg_enables_the_dotall_flag():
+    compiled = RegexBuilder().string("hi").to_regex(dotall=True)
+    assert compiled.compiled.flags & re.S == re.S
+
+
+def test_ascii_only_kwarg_enables_the_ascii_flag():
+    compiled = RegexBuilder().string("hi").to_regex(ascii_only=True)
+    assert compiled.compiled.flags & re.A == re.A
+
+
+def test_verbose_kwarg_enables_the_verbose_flag():
+    compiled = RegexBuilder().string("hi").to_regex(verbose=True)
+    assert compiled.compiled.flags & re.X == re.X
+
+
[email protected](
+    _ON_PYPY,
+    reason="PyPy's re.DEBUG opcode disassembler has an upstream IndexError bug",
+)
+def test_debug_kwarg_compiles_without_error():
+    compiled = RegexBuilder().string("hi").to_regex(debug=True)
+    assert compiled.source == "hi"
+
+
+def test_kwargs_or_merge_with_chain_flags():
+    compiled = RegexBuilder().ignore_case().string("hi").to_regex(multiline=True)
+    assert compiled.compiled.flags & re.I == re.I
+    assert compiled.compiled.flags & re.M == re.M
+
+
+def test_kwargs_never_turn_off_a_chain_flag():
+    compiled = RegexBuilder().ignore_case().string("hi").to_regex(ignore_case=False)
+    assert compiled.compiled.flags & re.I == re.I
+
+
+def test_kwargs_work_on_pattern_too():
+    compiled = Pattern().string("hi").to_regex(ignore_case=True)
+    assert compiled.compiled.flags & re.I == re.I
+
+
+def test_multiple_kwargs_combine():
+    compiled = RegexBuilder().string("hi").to_regex(ignore_case=True, multiline=True, dotall=True)
+    assert compiled.compiled.flags & re.I == re.I
+    assert compiled.compiled.flags & re.M == re.M
+    assert compiled.compiled.flags & re.S == re.S
diff --git a/tests/builder/use.test.py b/tests/builder/use.test.py
index 10d7855..0253786 100644
--- a/tests/builder/use.test.py
+++ b/tests/builder/use.test.py
@@ -21,7 +21,7 @@ def test_use_drops_the_pattern_flag_snapshot_by_default():
     case_insensitive_pattern = Pattern().ignore_case().string("hello")
     expression = RegexBuilder().use(case_insensitive_pattern)
     compiled = expression.to_regex()
-    assert compiled.flags & 2 == 0
+    assert compiled.compiled.flags & 2 == 0
 
 
 def test_use_accepts_another_regex_builder_as_the_source():
diff --git a/tests/pattern/composition.test.py b/tests/pattern/composition.test.py
index f58df57..18a6bc2 100644
--- a/tests/pattern/composition.test.py
+++ b/tests/pattern/composition.test.py
@@ -20,7 +20,7 @@ def test_pattern_exposes_to_regex_string_terminal():
 def test_pattern_exposes_to_regex_terminal():
     pattern = Pattern().digit()
     compiled = pattern.to_regex()
-    assert compiled.pattern == "\\d"
+    assert compiled.source == "\\d"
 
 
 def test_pattern_supports_nested_use_composition():
diff --git a/tests/result/regex.test.py b/tests/result/regex.test.py
new file mode 100644
index 0000000..d6f2a64
--- /dev/null
+++ b/tests/result/regex.test.py
@@ -0,0 +1,97 @@
+"""Tests for the :class:`edify.result.Regex` wrapper class."""
+
+import re
+
+import pytest
+
+from edify.result import Regex
+
+
[email protected]
+def digit_regex() -> Regex:
+    return Regex("\\d+", re.compile("\\d+"))
+
+
+def test_source_returns_the_pattern_string(digit_regex):
+    assert digit_regex.source == "\\d+"
+
+
+def test_compiled_returns_the_underlying_re_pattern(digit_regex):
+    assert isinstance(digit_regex.compiled, re.Pattern)
+
+
+def test_compiled_pattern_matches_the_source(digit_regex):
+    assert digit_regex.compiled.pattern == "\\d+"
+
+
+def test_match_delegates_to_the_compiled_pattern(digit_regex):
+    hit = digit_regex.match("123")
+    assert hit is not None
+    assert hit.group() == "123"
+
+
+def test_search_delegates_to_the_compiled_pattern(digit_regex):
+    hit = digit_regex.search("abc 456 def")
+    assert hit is not None
+    assert hit.group() == "456"
+
+
+def test_fullmatch_delegates_to_the_compiled_pattern(digit_regex):
+    assert digit_regex.fullmatch("789") is not None
+    assert digit_regex.fullmatch("7x9") is None
+
+
+def test_findall_delegates_to_the_compiled_pattern(digit_regex):
+    assert digit_regex.findall("1 2 3") == ["1", "2", "3"]
+
+
+def test_finditer_delegates_to_the_compiled_pattern(digit_regex):
+    hits = list(digit_regex.finditer("42 99"))
+    assert [match.group() for match in hits] == ["42", "99"]
+
+
+def test_sub_delegates_to_the_compiled_pattern(digit_regex):
+    assert digit_regex.sub("[X]", "hi 12 there 34") == "hi [X] there [X]"
+
+
+def test_subn_delegates_to_the_compiled_pattern(digit_regex):
+    result, count = digit_regex.subn("[X]", "1 2 3")
+    assert result == "[X] [X] [X]"
+    assert count == 3
+
+
+def test_split_delegates_to_the_compiled_pattern(digit_regex):
+    assert digit_regex.split("hi1there2end") == ["hi", "there", "end"]
+
+
+def test_repr_shows_the_source(digit_regex):
+    assert repr(digit_regex) == "<Regex '\\\\d+'>"
+
+
+def test_equal_when_source_and_flags_match():
+    a = Regex("\\d+", re.compile("\\d+"))
+    b = Regex("\\d+", re.compile("\\d+"))
+    assert a == b
+
+
+def test_not_equal_when_source_differs():
+    a = Regex("\\d+", re.compile("\\d+"))
+    b = Regex("\\w+", re.compile("\\w+"))
+    assert a != b
+
+
+def test_not_equal_when_flags_differ():
+    a = Regex("\\d+", re.compile("\\d+"))
+    b = Regex("\\d+", re.compile("\\d+", flags=re.IGNORECASE))
+    assert a != b
+
+
+def test_hash_matches_when_equal():
+    a = Regex("\\d+", re.compile("\\d+"))
+    b = Regex("\\d+", re.compile("\\d+"))
+    assert hash(a) == hash(b)
+
+
+def test_equality_with_non_regex_returns_not_implemented():
+    a = Regex("\\d+", re.compile("\\d+"))
+    assert a.__eq__("foo") is NotImplemented