Phase 0.3: test suite for config, nonce, run context, report, CLI, and the em dash rule

64 tests. Config coverage includes every fail closed path: missing surfaces,
empty surfaces, duplicate names, unknown keys at both levels with the key named
in the message, declared entries that are not surface:carrier, and unknown
surface types.

The run context tests set a canary variable in the parent environment and assert
it is absent from both scrubbed run environments, so an inherited variable
cannot quietly become an undeclared channel.

The em dash meta test scans through git ls-files, including untracked files that
are not ignored, so a new file is checked before it is committed. It was
verified against a deliberate canary file that it actually fails.

Claude-Session: https://claude.ai/code/session_01FchscQuS6Ar9k5Y6VdJ7MY

Author: webpro255

tests/test_cli.py

@@ -0,0 +1,54 @@
+"""CLI tests. Phase 0 has no adapters, so probe never exits 0."""
+
+import json
+
+import pytest
+
+from runprobe import __version__
+from runprobe.cli import EXIT_CANNOT_RUN, main
+
+
+def test_version_flag_prints_the_version(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert __version__ in capsys.readouterr().out
+
+
+def test_no_command_prints_help_and_exits_two(capsys):
+    assert main([]) == EXIT_CANNOT_RUN
+    assert "usage: runprobe" in capsys.readouterr().err
+
+
+def test_probe_with_a_missing_config_exits_two(capsys, tmp_path):
+    assert main(["probe", "--config", str(tmp_path / "nope.json")]) == EXIT_CANNOT_RUN
+    assert "config file not found" in capsys.readouterr().err
+
+
+def test_probe_with_an_unknown_surface_type_exits_two(capsys, tmp_path):
+    path = tmp_path / "surfaces.json"
+    path.write_text(json.dumps({"surfaces": [{"name": "a", "type": "filesystem"}]}))
+    assert main(["probe", "--config", str(path)]) == EXIT_CANNOT_RUN
+    assert "unknown surface type: filesystem" in capsys.readouterr().err
+
+
+def test_probe_reports_no_adapters_once_a_type_resolves(capsys, tmp_path, monkeypatch):
+    """With a type registered, config validation passes and the probe stops here."""
+    from runprobe.config import SURFACE_TYPES
+
+    monkeypatch.setitem(SURFACE_TYPES, "fake", "tests.fake")
+    path = tmp_path / "surfaces.json"
+    path.write_text(json.dumps({"surfaces": [{"name": "a", "type": "fake"}]}))
+    assert main(["probe", "--config", str(path)]) == EXIT_CANNOT_RUN
+    assert "no adapters registered" in capsys.readouterr().err
+
+
+def test_report_path_defaults(tmp_path):
+    from runprobe.cli import build_parser
+
+    args = build_parser().parse_args(["probe", "--config", "surfaces.json"])
+    assert args.report == "runprobe-report.json"
+    args = build_parser().parse_args(
+        ["probe", "--config", "surfaces.json", "--report", "out.json"]
+    )
+    assert args.report == "out.json"

tests/test_config.py

@@ -0,0 +1,183 @@
+"""Config loader tests. Every case here is a fail closed case except the first."""
+
+import json
+
+import pytest
+
+from runprobe.config import SURFACE_TYPES, Config, ConfigError, load, parse
+
+
+def write_config(tmp_path, data):
+    path = tmp_path / "surfaces.json"
+    path.write_text(json.dumps(data), encoding="utf-8")
+    return path
+
+
+@pytest.fixture
+def registered_type(monkeypatch):
+    """Register a fake surface type so structural tests can reach a valid config.
+
+    The real registry is empty in Phase 0, so without this every config would
+    fail on type resolution and the valid case could not be tested at all.
+    """
+    monkeypatch.setitem(SURFACE_TYPES, "fake", "tests.fake")
+    return "fake"
+
+
+def test_valid_minimal_config_loads(tmp_path, registered_type):
+    path = write_config(tmp_path, {"surfaces": [{"name": "shared_tmp", "type": "fake"}]})
+    config = load(path)
+    assert isinstance(config, Config)
+    assert len(config.surfaces) == 1
+    assert config.surfaces[0].name == "shared_tmp"
+    assert config.surfaces[0].type == "fake"
+    assert config.surfaces[0].params == {}
+    assert config.declared == []
+    assert config.source == path
+
+
+def test_valid_config_with_params_and_declared(tmp_path, registered_type):
+    path = write_config(
+        tmp_path,
+        {
+            "surfaces": [{"name": "shared_tmp", "type": "fake", "params": {"path": "/tmp"}}],
+            "declared": ["shared_tmp:file_content"],
+        },
+    )
+    config = load(path)
+    assert config.surfaces[0].params == {"path": "/tmp"}
+    assert config.is_declared("shared_tmp", "file_content")
+    assert not config.is_declared("shared_tmp", "directory_name")
+
+
+def test_missing_surfaces_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse({})
+    assert "surfaces" in str(exc.value)
+
+
+def test_empty_surfaces_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": []})
+    assert "must not be empty" in str(exc.value)
+
+
+def test_surfaces_not_a_list_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": {"name": "shared_tmp"}})
+    assert "surfaces must be a list" in str(exc.value)
+
+
+def test_duplicate_surface_name_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse(
+            {
+                "surfaces": [
+                    {"name": "shared_tmp", "type": "fake"},
+                    {"name": "shared_tmp", "type": "fake"},
+                ]
+            }
+        )
+    message = str(exc.value)
+    assert "duplicate surface name" in message
+    assert "shared_tmp" in message
+
+
+def test_unknown_top_level_key_errors_and_names_the_key():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a", "type": "fake"}], "surfacez": []})
+    message = str(exc.value)
+    assert "unknown key" in message
+    assert "surfacez" in message
+
+
+def test_unknown_key_inside_a_surface_errors_and_names_the_path():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a", "type": "fake", "parms": {}}]})
+    message = str(exc.value)
+    assert "unknown key" in message
+    assert "parms" in message
+    assert "surfaces[0].parms" in message
+
+
+def test_declared_entry_without_a_colon_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a", "type": "fake"}], "declared": ["a_file_content"]})
+    message = str(exc.value)
+    assert "declared[0]" in message
+    assert "surface_name:carrier_name" in message
+
+
+def test_declared_entry_with_two_colons_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a", "type": "fake"}], "declared": ["a:b:c"]})
+    assert "surface_name:carrier_name" in str(exc.value)
+
+
+def test_declared_entry_naming_an_undefined_surface_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a", "type": "fake"}], "declared": ["b:file_content"]})
+    assert "undefined surface" in str(exc.value)
+
+
+def test_unknown_surface_type_errors_with_the_type_name():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a", "type": "s3_bucket"}]})
+    message = str(exc.value)
+    assert "unknown surface type" in message
+    assert "s3_bucket" in message
+
+
+def test_surface_type_registry_is_empty_in_this_phase():
+    assert SURFACE_TYPES == {}
+
+
+def test_missing_surface_name_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"type": "fake"}]})
+    assert "'name'" in str(exc.value)
+
+
+def test_missing_surface_type_errors():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a"}]})
+    assert "'type'" in str(exc.value)
+
+
+def test_surface_name_must_be_a_string():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": 7, "type": "fake"}]})
+    assert "surfaces[0].name must be a string" in str(exc.value)
+
+
+def test_params_must_be_an_object():
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a", "type": "fake", "params": []}]})
+    assert "surfaces[0].params must be an object" in str(exc.value)
+
+
+def test_root_must_be_an_object():
+    with pytest.raises(ConfigError) as exc:
+        parse([{"name": "a", "type": "fake"}])
+    assert "config root must be an object" in str(exc.value)
+
+
+def test_structural_errors_are_reported_before_unknown_type():
+    """A config with both a typo and an unbuilt adapter reports the typo."""
+    with pytest.raises(ConfigError) as exc:
+        parse({"surfaces": [{"name": "a", "type": "not_built_yet", "parms": {}}]})
+    assert "unknown key" in str(exc.value)
+
+
+def test_missing_file_errors(tmp_path):
+    with pytest.raises(ConfigError) as exc:
+        load(tmp_path / "does_not_exist.json")
+    assert "config file not found" in str(exc.value)
+
+
+def test_malformed_json_errors(tmp_path):
+    path = tmp_path / "surfaces.json"
+    path.write_text("{not json", encoding="utf-8")
+    with pytest.raises(ConfigError) as exc:
+        load(path)
+    assert "not valid JSON" in str(exc.value)

tests/test_no_em_dashes.py

@@ -0,0 +1,66 @@
+"""Meta test: no em dashes anywhere in the tracked source or docs.
+
+House rule from PLAN.md section 12. Scoped through git ls-files, which honours .gitignore,
+so gitignored files (PLAN.md, .prompts/) are never read by the test suite.
+Untracked but not ignored files are included too, so a new file is checked
+before it is committed rather than after.
+"""
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+# Written as an escape so that this file does not itself contain the character.
+EM_DASH = "\u2014"
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+SCANNED_PREFIXES = ("src/", "tests/")
+
+
+def tracked_files():
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+            cwd=REPO_ROOT,
+            capture_output=True,
+            check=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        pytest.skip(f"git ls-files unavailable: {exc}")
+
+    return [name for name in result.stdout.split("\0") if name]
+
+
+def scanned_files():
+    """Every tracked file under src/ or tests/, plus every tracked Markdown file."""
+    selected = []
+    for name in tracked_files():
+        if name.startswith(SCANNED_PREFIXES) or name.endswith(".md"):
+            path = REPO_ROOT / name
+            if path.is_file():
+                selected.append(name)
+    return selected
+
+
+def test_scan_covers_the_expected_files():
+    """Guard against the scan silently matching nothing and passing for free."""
+    names = scanned_files()
+    assert "README.md" in names
+    assert any(name.startswith("src/runprobe/") for name in names)
+    assert any(name.startswith("tests/") for name in names)
+
+
+def test_no_em_dashes_in_tracked_source_and_docs():
+    offenders = []
+    for name in scanned_files():
+        text = (REPO_ROOT / name).read_text(encoding="utf-8", errors="replace")
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            if EM_DASH in line:
+                offenders.append(f"{name}:{lineno}: {line.strip()}")
+
+    assert not offenders, "em dash found (house rule, use commas or colons):\n" + "\n".join(
+        offenders
+    )

tests/test_nonce.py

@@ -0,0 +1,26 @@
+"""Nonce tests."""
+
+import string
+
+from runprobe.nonce import NONCE_HEX_CHARS, generate
+
+
+def test_nonce_is_sixteen_characters():
+    assert len(generate()) == 16
+    assert NONCE_HEX_CHARS == 16
+
+
+def test_nonce_is_lowercase_hex_only():
+    nonce = generate()
+    allowed = set(string.hexdigits.lower())
+    assert set(nonce) <= allowed
+    assert nonce == nonce.lower()
+
+
+def test_two_calls_differ():
+    assert generate() != generate()
+
+
+def test_many_calls_are_unique():
+    """A repeat inside a small sample would mean the generator is not random."""
+    assert len({generate() for _ in range(500)}) == 500