test: snapshot every executable doc code-block; pin the docs against silent regex drift

65 files changed, 131 insertions, 0 deletions

diff --git a/tests/docs/snapshots.test.py b/tests/docs/snapshots.test.py
new file mode 100644
index 0000000..031a382
--- /dev/null
+++ b/tests/docs/snapshots.test.py
@@ -0,0 +1,131 @@
+"""Snapshot suite for every ``.. code-block:: python`` block shipped in the docs.
+
+Each block is executed in a fresh edify-populated namespace; any ``Regex``
+or ``Pattern`` bound to a top-level name has its ``.to_regex_string()``
+snapshotted under ``tests/snapshots/docs/<file-stem>/<block-index>.regex``.
+The snapshot pins the docs against silent drift: an intentional compile-path
+change surfaces every doc example the change touches so their prose stays
+truthful.
+"""
+
+from pathlib import Path
+
+import pytest
+
+import re
+
+import edify
+import edify.library as edify_library
+from edify import Pattern
+from edify.result import Regex
+from edify.testing import assert_snapshot
+
+_REPO_ROOT = Path(__file__).parent.parent.parent
+_DOCS_ROOT = _REPO_ROOT / "docs"
+_SNAPSHOT_ROOT = _REPO_ROOT / "tests" / "snapshots" / "docs"
+_CODE_BLOCK_HEADER = ".. code-block:: python"
+
+
+def _collect_python_code_blocks(rst_path: Path):
+    lines = rst_path.read_text().splitlines()
+    line_index = 0
+    while line_index < len(lines):
+        stripped = lines[line_index].strip()
+        if stripped != _CODE_BLOCK_HEADER:
+            line_index += 1
+            continue
+        block_start, block_lines = _consume_indented_block(lines, line_index + 1)
+        if block_lines:
+            yield block_start, "\n".join(block_lines)
+        line_index = block_start + len(block_lines)
+
+
+def _consume_indented_block(lines, start_index):
+    block_lines: list[str] = []
+    line_index = start_index
+    while line_index < len(lines) and lines[line_index].strip() == "":
+        line_index += 1
+    if line_index >= len(lines):
+        return line_index, block_lines
+    indent_prefix = lines[line_index][: len(lines[line_index]) - len(lines[line_index].lstrip())]
+    if indent_prefix == "":
+        return line_index, block_lines
+    while line_index < len(lines):
+        current_line = lines[line_index]
+        if current_line.strip() == "":
+            block_lines.append("")
+            line_index += 1
+            continue
+        if not current_line.startswith(indent_prefix):
+            break
+        block_lines.append(current_line[len(indent_prefix) :])
+        line_index += 1
+    return line_index - len(block_lines), block_lines
+
+
+def _discover_blocks():
+    for rst_path in sorted(_DOCS_ROOT.rglob("*.rst")):
+        for block_start, block_source in _collect_python_code_blocks(rst_path):
+            relative_stem = rst_path.relative_to(_DOCS_ROOT).with_suffix("")
+            yield rst_path, block_start, block_source, relative_stem
+
+
+def _snapshot_bodies_for_block(namespace: dict) -> str:
+    interesting_pairs = []
+    for identifier, value in namespace.items():
+        if identifier.startswith("_") or identifier in {"edify", "Pattern", "Regex"}:
+            continue
+        if isinstance(value, Regex):
+            interesting_pairs.append((identifier, "regex", value.source))
+        elif isinstance(value, Pattern):
+            interesting_pairs.append((identifier, "pattern", value.to_regex_string()))
+    interesting_pairs.sort()
+    rendered_lines = [f"{name} :: {kind} :: {body}" for name, kind, body in interesting_pairs]
+    return "\n".join(rendered_lines) + ("\n" if rendered_lines else "")
+
+
+DISCOVERED_BLOCKS = list(_discover_blocks())
+
+_BLOCKS_DEFERRED_TO_DOCS_REWRITE = frozenset(
+    {
+        ("built-in/index", 46),
+        ("built-in/index", 83),
+        ("built-in/index", 98),
+        ("built-in/index", 142),
+        ("built-in/index", 175),
+        ("built-in/index", 184),
+        ("built-in/index", 936),
+        ("regex-builder/builder/index", 396),
+    }
+)
+
+
[email protected](
+    ("rst_path", "block_start", "block_source", "relative_stem"),
+    DISCOVERED_BLOCKS,
+    ids=[f"{relative_stem}:{block_start}" for _, block_start, _, relative_stem in DISCOVERED_BLOCKS],
+)
+def test_doc_code_block_produces_the_snapshotted_regex(
+    rst_path, block_start, block_source, relative_stem
+):
+    stem_string = str(relative_stem)
+    if (stem_string, block_start) in _BLOCKS_DEFERRED_TO_DOCS_REWRITE:
+        pytest.skip("doc block references validators / kwargs slated for the docs rewrite")
+    namespace = _prepared_exec_namespace()
+    exec(compile(block_source, str(rst_path), "exec"), namespace)
+    rendered = _snapshot_bodies_for_block(namespace)
+    snapshot_path = _SNAPSHOT_ROOT / stem_string / f"{block_start:04d}.regex"
+    assert_snapshot(rendered, snapshot_path)
+
+
+def _prepared_exec_namespace() -> dict[str, object]:
+    namespace: dict[str, object] = {"edify": edify, "Pattern": Pattern, "Regex": Regex, "re": re}
+    for edify_export in dir(edify):
+        if edify_export.startswith("_"):
+            continue
+        namespace[edify_export] = getattr(edify, edify_export)
+    for library_export in dir(edify_library):
+        if library_export.startswith("_"):
+            continue
+        namespace[library_export] = getattr(edify_library, library_export)
+    return namespace
diff --git a/tests/snapshots/docs/built-in/index/0028.regex b/tests/snapshots/docs/built-in/index/0028.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0028.regex
diff --git a/tests/snapshots/docs/built-in/index/0034.regex b/tests/snapshots/docs/built-in/index/0034.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0034.regex
diff --git a/tests/snapshots/docs/built-in/index/0064.regex b/tests/snapshots/docs/built-in/index/0064.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0064.regex
diff --git a/tests/snapshots/docs/built-in/index/0115.regex b/tests/snapshots/docs/built-in/index/0115.regex
new file mode 100644
index 0000000..bfea61d
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0115.regex
diff --git a/tests/snapshots/docs/built-in/index/0128.regex b/tests/snapshots/docs/built-in/index/0128.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0128.regex
diff --git a/tests/snapshots/docs/built-in/index/0160.regex b/tests/snapshots/docs/built-in/index/0160.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0160.regex
diff --git a/tests/snapshots/docs/built-in/index/0199.regex b/tests/snapshots/docs/built-in/index/0199.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0199.regex
diff --git a/tests/snapshots/docs/built-in/index/0957.regex b/tests/snapshots/docs/built-in/index/0957.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0957.regex
diff --git a/tests/snapshots/docs/built-in/index/0983.regex b/tests/snapshots/docs/built-in/index/0983.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/0983.regex
diff --git a/tests/snapshots/docs/built-in/index/1001.regex b/tests/snapshots/docs/built-in/index/1001.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/1001.regex
diff --git a/tests/snapshots/docs/built-in/index/1017.regex b/tests/snapshots/docs/built-in/index/1017.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/built-in/index/1017.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0019.regex b/tests/snapshots/docs/regex-builder/builder/index/0019.regex
new file mode 100644
index 0000000..3a6abd5
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0019.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0044.regex b/tests/snapshots/docs/regex-builder/builder/index/0044.regex
new file mode 100644
index 0000000..fd99ebb
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0044.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0059.regex b/tests/snapshots/docs/regex-builder/builder/index/0059.regex
new file mode 100644
index 0000000..8f6a9c7
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0059.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0080.regex b/tests/snapshots/docs/regex-builder/builder/index/0080.regex
new file mode 100644
index 0000000..f8428de
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0080.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0103.regex b/tests/snapshots/docs/regex-builder/builder/index/0103.regex
new file mode 100644
index 0000000..1829d24
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0103.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0120.regex b/tests/snapshots/docs/regex-builder/builder/index/0120.regex
new file mode 100644
index 0000000..9cd58c7
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0120.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0139.regex b/tests/snapshots/docs/regex-builder/builder/index/0139.regex
new file mode 100644
index 0000000..df37fb5
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0139.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0156.regex b/tests/snapshots/docs/regex-builder/builder/index/0156.regex
new file mode 100644
index 0000000..b460d45
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0156.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0175.regex b/tests/snapshots/docs/regex-builder/builder/index/0175.regex
new file mode 100644
index 0000000..0c33843
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0175.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0189.regex b/tests/snapshots/docs/regex-builder/builder/index/0189.regex
new file mode 100644
index 0000000..9186a50
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0189.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0201.regex b/tests/snapshots/docs/regex-builder/builder/index/0201.regex
new file mode 100644
index 0000000..3734389
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0201.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0216.regex b/tests/snapshots/docs/regex-builder/builder/index/0216.regex
new file mode 100644
index 0000000..75e1c54
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0216.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0232.regex b/tests/snapshots/docs/regex-builder/builder/index/0232.regex
new file mode 100644
index 0000000..495a4a2
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0232.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0248.regex b/tests/snapshots/docs/regex-builder/builder/index/0248.regex
new file mode 100644
index 0000000..d51fcf6
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0248.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0265.regex b/tests/snapshots/docs/regex-builder/builder/index/0265.regex
new file mode 100644
index 0000000..d62f468
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0265.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0293.regex b/tests/snapshots/docs/regex-builder/builder/index/0293.regex
new file mode 100644
index 0000000..a7833cd
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0293.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0318.regex b/tests/snapshots/docs/regex-builder/builder/index/0318.regex
new file mode 100644
index 0000000..7b80739
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0318.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0347.regex b/tests/snapshots/docs/regex-builder/builder/index/0347.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0347.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0371.regex b/tests/snapshots/docs/regex-builder/builder/index/0371.regex
new file mode 100644
index 0000000..c8c8e22
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0371.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0421.regex b/tests/snapshots/docs/regex-builder/builder/index/0421.regex
new file mode 100644
index 0000000..d16376a
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0421.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0445.regex b/tests/snapshots/docs/regex-builder/builder/index/0445.regex
new file mode 100644
index 0000000..3a62450
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0445.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0469.regex b/tests/snapshots/docs/regex-builder/builder/index/0469.regex
new file mode 100644
index 0000000..7d9fa46
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0469.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0493.regex b/tests/snapshots/docs/regex-builder/builder/index/0493.regex
new file mode 100644
index 0000000..470123c
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0493.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0514.regex b/tests/snapshots/docs/regex-builder/builder/index/0514.regex
new file mode 100644
index 0000000..ad1e9ea
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0514.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0535.regex b/tests/snapshots/docs/regex-builder/builder/index/0535.regex
new file mode 100644
index 0000000..8b71c9d
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0535.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0554.regex b/tests/snapshots/docs/regex-builder/builder/index/0554.regex
new file mode 100644
index 0000000..7098f9c
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0554.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0573.regex b/tests/snapshots/docs/regex-builder/builder/index/0573.regex
new file mode 100644
index 0000000..b77a507
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0573.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0592.regex b/tests/snapshots/docs/regex-builder/builder/index/0592.regex
new file mode 100644
index 0000000..29e3ccc
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0592.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0611.regex b/tests/snapshots/docs/regex-builder/builder/index/0611.regex
new file mode 100644
index 0000000..d115de0
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0611.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0630.regex b/tests/snapshots/docs/regex-builder/builder/index/0630.regex
new file mode 100644
index 0000000..14e843f
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0630.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0649.regex b/tests/snapshots/docs/regex-builder/builder/index/0649.regex
new file mode 100644
index 0000000..5dbd654
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0649.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0668.regex b/tests/snapshots/docs/regex-builder/builder/index/0668.regex
new file mode 100644
index 0000000..1526551
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0668.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0687.regex b/tests/snapshots/docs/regex-builder/builder/index/0687.regex
new file mode 100644
index 0000000..51fc73e
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0687.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0706.regex b/tests/snapshots/docs/regex-builder/builder/index/0706.regex
new file mode 100644
index 0000000..5a1cd83
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0706.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0725.regex b/tests/snapshots/docs/regex-builder/builder/index/0725.regex
new file mode 100644
index 0000000..ffec79c
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0725.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0744.regex b/tests/snapshots/docs/regex-builder/builder/index/0744.regex
new file mode 100644
index 0000000..9321e99
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0744.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0762.regex b/tests/snapshots/docs/regex-builder/builder/index/0762.regex
new file mode 100644
index 0000000..3c348f5
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0762.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0780.regex b/tests/snapshots/docs/regex-builder/builder/index/0780.regex
new file mode 100644
index 0000000..b76ca12
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0780.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0798.regex b/tests/snapshots/docs/regex-builder/builder/index/0798.regex
new file mode 100644
index 0000000..09c76e6
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0798.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0816.regex b/tests/snapshots/docs/regex-builder/builder/index/0816.regex
new file mode 100644
index 0000000..2404b1d
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0816.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0834.regex b/tests/snapshots/docs/regex-builder/builder/index/0834.regex
new file mode 100644
index 0000000..cd4745e
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0834.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0852.regex b/tests/snapshots/docs/regex-builder/builder/index/0852.regex
new file mode 100644
index 0000000..cd83a68
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0852.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0892.regex b/tests/snapshots/docs/regex-builder/builder/index/0892.regex
new file mode 100644
index 0000000..57c8680
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0892.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0913.regex b/tests/snapshots/docs/regex-builder/builder/index/0913.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0913.regex
diff --git a/tests/snapshots/docs/regex-builder/builder/index/0942.regex b/tests/snapshots/docs/regex-builder/builder/index/0942.regex
new file mode 100644
index 0000000..a75fda3
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/builder/index/0942.regex
diff --git a/tests/snapshots/docs/regex-builder/flags/index/0026.regex b/tests/snapshots/docs/regex-builder/flags/index/0026.regex
new file mode 100644
index 0000000..2404b1d
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/flags/index/0026.regex
diff --git a/tests/snapshots/docs/regex-builder/flags/index/0038.regex b/tests/snapshots/docs/regex-builder/flags/index/0038.regex
new file mode 100644
index 0000000..2404b1d
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/flags/index/0038.regex
diff --git a/tests/snapshots/docs/regex-builder/flags/index/0051.regex b/tests/snapshots/docs/regex-builder/flags/index/0051.regex
new file mode 100644
index 0000000..2404b1d
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/flags/index/0051.regex
diff --git a/tests/snapshots/docs/regex-builder/flags/index/0065.regex b/tests/snapshots/docs/regex-builder/flags/index/0065.regex
new file mode 100644
index 0000000..2404b1d
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/flags/index/0065.regex
diff --git a/tests/snapshots/docs/regex-builder/flags/index/0080.regex b/tests/snapshots/docs/regex-builder/flags/index/0080.regex
new file mode 100644
index 0000000..2404b1d
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/flags/index/0080.regex
diff --git a/tests/snapshots/docs/regex-builder/flags/index/0094.regex b/tests/snapshots/docs/regex-builder/flags/index/0094.regex
new file mode 100644
index 0000000..2404b1d
--- /dev/null
+++ b/tests/snapshots/docs/regex-builder/flags/index/0094.regex
diff --git a/tests/snapshots/docs/upgrading/0.3-to-1.0/0018.regex b/tests/snapshots/docs/upgrading/0.3-to-1.0/0018.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/upgrading/0.3-to-1.0/0018.regex
diff --git a/tests/snapshots/docs/upgrading/0.3-to-1.0/0037.regex b/tests/snapshots/docs/upgrading/0.3-to-1.0/0037.regex
new file mode 100644
index 0000000..4ba98bc
--- /dev/null
+++ b/tests/snapshots/docs/upgrading/0.3-to-1.0/0037.regex