Build strict NUnit parity harness

tools/generate_surface.py

@@ -13,7 +13,9 @@ import hashlib
 import json
 import keyword
 import re
-from collections import defaultdict
+import subprocess
+import tempfile
+from collections import Counter, defaultdict
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -51,13 +53,33 @@ TYPE_RE = re.compile(
 )
 NAMESPACE_RE = re.compile(r"^\s*namespace\s+([A-Za-z_][A-Za-z0-9_.]*)", re.MULTILINE)
 TEST_ATTR_RE = re.compile(r"\[(Test|TestCase)(?:\((.*?)\))?\]", re.DOTALL)
+CATEGORY_RE = re.compile(r'\[Category\("([^"]+)"\)\]')
 METHOD_RE = re.compile(
     r"\b(?:public|internal)\s+(?:static\s+)?(?:async\s+)?"
     r"(?:void|Task(?:\s*<[^>]+>)?|ValueTask(?:\s*<[^>]+>)?)\s+"
     r"([A-Za-z_][A-Za-z0-9_]*)\s*\(",
     re.DOTALL,
 )
-CLASS_RE = re.compile(r"\b(?:public|internal)\s+(?:sealed\s+|partial\s+)?class\s+([A-Za-z_][A-Za-z0-9_]*)")
+CLASS_RE = re.compile(
+    r"\b(?:(?:public|internal|private|protected|sealed|partial|abstract|static)\s+)*"
+    r"class\s+([A-Za-z_][A-Za-z0-9_]*)"
+)
+PARITY_MARKER_RE = re.compile(
+    r"^// parity-case: (?P<id>\S+) (?P<body_sha256>[0-9a-f]{64}) "
+    r"(?P<status>translated|ignored-live|benchmark)$",
+    re.MULTILINE,
+)
+RUST_TEST_RE = re.compile(r"(?:#\[[^\]]+\]\s*)*fn\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(", re.MULTILINE)
+FORBIDDEN_REVIEW_BODY_RE = re.compile(
+    r"\bpending\s*\(|\bassert_[A-Za-z0-9_]*case\s*\(|"
+    r"\b(?:todo|unimplemented|unimplemented_api)\s*!|\bnot_implemented\s*\("
+)
+EXPECTED_TESTS = 1289
+PARITY_FILES = (
+    Path("tests/compat/tests/generated_parity.rs"),
+    Path("tests/PARITY.md"),
+    Path("tests/upstream-tests.json"),
+)
 
 
 def snake(name: str) -> str:
@@ -88,6 +110,151 @@ def source_files(root: Path) -> list[Path]:
     return sorted(p for p in root.rglob("*.cs") if "obj" not in p.parts and "bin" not in p.parts)
 
 
+def mask_csharp_comments(text: str) -> str:
+    """Blank comments without shifting source offsets or touching string literals."""
+    masked = list(text)
+    index = 0
+    state = "code"
+    while index < len(text):
+        char = text[index]
+        following = text[index + 1] if index + 1 < len(text) else ""
+        if state == "code":
+            if char == '"':
+                state = "string"
+            elif char == "'":
+                state = "char"
+            elif char == "/" and following == "/":
+                masked[index] = masked[index + 1] = " "
+                index += 1
+                state = "line_comment"
+            elif char == "/" and following == "*":
+                masked[index] = masked[index + 1] = " "
+                index += 1
+                state = "block_comment"
+        elif state in {"string", "char"}:
+            if char == "\\":
+                index += 1
+            elif (state == "string" and char == '"') or (state == "char" and char == "'"):
+                state = "code"
+        elif state == "line_comment":
+            if char == "\n":
+                state = "code"
+            else:
+                masked[index] = " "
+        elif state == "block_comment":
+            if char == "*" and following == "/":
+                masked[index] = masked[index + 1] = " "
+                index += 1
+                state = "code"
+            elif char != "\n":
+                masked[index] = " "
+        index += 1
+    return "".join(masked)
+
+
+def mask_rust_noncode(text: str) -> str:
+    """Blank Rust comments and string/character contents without shifting offsets."""
+    masked = list(text)
+    index = 0
+    state = "code"
+    block_depth = 0
+    raw_hashes = 0
+    while index < len(text):
+        char = text[index]
+        following = text[index + 1] if index + 1 < len(text) else ""
+        if state == "code":
+            raw = re.match(r'(?:b|c)?r(#{0,255})"', text[index:])
+            if raw:
+                raw_hashes = len(raw.group(1))
+                for offset in range(len(raw.group(0))):
+                    masked[index + offset] = " "
+                index += len(raw.group(0)) - 1
+                state = "raw_string"
+            elif char == '"':
+                masked[index] = " "
+                state = "string"
+            elif char == "'" and re.match(r"'(?:\\.|[^\\'\n])'", text[index:]):
+                masked[index] = " "
+                state = "char"
+            elif char == "/" and following == "/":
+                masked[index] = masked[index + 1] = " "
+                index += 1
+                state = "line_comment"
+            elif char == "/" and following == "*":
+                masked[index] = masked[index + 1] = " "
+                index += 1
+                block_depth = 1
+                state = "block_comment"
+        elif state in {"string", "char"}:
+            masked[index] = " "
+            if char == "\\" and index + 1 < len(text):
+                masked[index + 1] = " "
+                index += 1
+            elif (state == "string" and char == '"') or (state == "char" and char == "'"):
+                state = "code"
+        elif state == "raw_string":
+            masked[index] = " "
+            ending = '"' + "#" * raw_hashes
+            if text.startswith(ending, index):
+                for offset in range(len(ending)):
+                    masked[index + offset] = " "
+                index += len(ending) - 1
+                state = "code"
+        elif state == "line_comment":
+            if char == "\n":
+                state = "code"
+            else:
+                masked[index] = " "
+        elif state == "block_comment":
+            masked[index] = " "
+            if char == "/" and following == "*":
+                masked[index + 1] = " "
+                index += 1
+                block_depth += 1
+            elif char == "*" and following == "/":
+                masked[index + 1] = " "
+                index += 1
+                block_depth -= 1
+                if block_depth == 0:
+                    state = "code"
+        index += 1
+    return "".join(masked)
+
+
+def rust_test_body(text: str, rust_test: re.Match[str]) -> str:
+    masked = mask_rust_noncode(text)
+    brace = masked.find("{", rust_test.end())
+    if brace < 0:
+        raise RuntimeError(f"Rust test {rust_test.group(1)} has no body")
+    depth = 0
+    for index in range(brace, len(masked)):
+        if masked[index] == "{":
+            depth += 1
+        elif masked[index] == "}":
+            depth -= 1
+            if depth == 0:
+                return text[brace + 1 : index]
+    raise RuntimeError(f"Rust test {rust_test.group(1)} has an unterminated body")
+
+
+def validate_reviewed_body(path: Path, rust_test: re.Match[str], body: str) -> str:
+    code = mask_rust_noncode(body).strip()
+    if not code:
+        raise RuntimeError(f"Reviewed parity test has an empty body: {path}:{rust_test.group(1)}")
+    forbidden = FORBIDDEN_REVIEW_BODY_RE.search(code)
+    if forbidden:
+        raise RuntimeError(
+            f"Reviewed parity test uses forbidden placeholder/dispatcher `{forbidden.group(0)}`: "
+            f"{path}:{rust_test.group(1)}"
+        )
+    if not re.search(r"\bassert(?:_[A-Za-z0-9_]+)?!|\.expect\s*\(|\.unwrap(?:_err)?\s*\(|\?", code):
+        raise RuntimeError(
+            f"Reviewed parity test has no explicit assertion or checked API result: "
+            f"{path}:{rust_test.group(1)}"
+        )
+    return hashlib.sha256(body.encode()).hexdigest()
+
+
 def namespace_at(text: str, position: int) -> str:
     matches = [m for m in NAMESPACE_RE.finditer(text) if m.start() <= position]
     return matches[-1].group(1) if matches else ""
@@ -200,9 +367,28 @@ def generate_apis(upstream: Path, output: Path) -> tuple[int, int]:
     return total_types, total_members
 
 
-def enclosing_class(text: str, position: int) -> str:
-    matches = [m for m in CLASS_RE.finditer(text) if m.start() <= position]
-    return matches[-1].group(1) if matches else "UnknownFixture"
+def enclosing_class_match(text: str, position: int) -> re.Match[str] | None:
+    containing: list[re.Match[str]] = []
+    for match in CLASS_RE.finditer(text, 0, position):
+        brace = text.find("{", match.end())
+        if brace == -1 or brace >= position:
+            continue
+        depth = 0
+        for index in range(brace, len(text)):
+            if text[index] == "{":
+                depth += 1
+            elif text[index] == "}":
+                depth -= 1
+                if depth == 0:
+                    if position < index:
+                        containing.append(match)
+                    break
+    return containing[-1] if containing else None
+
+
+def attributes_before(text: str, position: int) -> str:
+    match = re.search(r"((?:\s*\[[^\]]+\]\s*)+)$", text[:position], re.DOTALL)
+    return match.group(1) if match else ""
 
 
 def method_body_hash(text: str, method_start: int) -> str:
@@ -227,76 +413,299 @@ def method_body_hash(text: str, method_start: int) -> str:
     return hashlib.sha256(body.encode()).hexdigest()
 
 
-def generate_tests(upstream: Path, output: Path) -> int:
+def stable_case_id(source: str, fixture: str, method: str, attribute: str, parameters: str | None) -> str:
+    test_id = f"{source}::{fixture}.{method}"
+    if attribute == "Test":
+        return f"{test_id}::test"
+    normalized = " ".join((parameters or "").split())
+    digest = hashlib.sha256(normalized.encode()).hexdigest()[:16]
+    return f"{test_id}::case:{digest}"
+
+
+def helper_types(roots: tuple[Path, ...], upstream: Path) -> dict[str, str]:
+    helpers: dict[str, str] = {}
+    for root in roots:
+        for path in source_files(root):
+            text = path.read_text(encoding="utf-8-sig")
+            searchable = mask_csharp_comments(text)
+            if TEST_ATTR_RE.search(searchable):
+                continue
+            relative = path.relative_to(upstream).as_posix()
+            for match in CLASS_RE.finditer(searchable):
+                helpers.setdefault(match.group(1), relative)
+    return helpers
+
+
+def extract_tests(upstream: Path) -> list[dict[str, object]]:
     roots = (upstream / "LibreMetaverse.Tests", upstream / "LibreMetaverse.Rendering.Tests")
+    helpers = helper_types(roots, upstream)
     tests: list[dict[str, object]] = []
     for root in roots:
         for path in source_files(root):
             text = path.read_text(encoding="utf-8-sig")
+            searchable = mask_csharp_comments(text)
             relative = path.relative_to(upstream).as_posix()
-            attrs = list(TEST_ATTR_RE.finditer(text))
+            dependencies = sorted(
+                helper_path
+                for helper, helper_path in helpers.items()
+                if helper_path != relative and re.search(rf"\b{re.escape(helper)}\b", text)
+            )
+            attrs = list(TEST_ATTR_RE.finditer(searchable))
             for attr_index, attr in enumerate(attrs):
                 next_attr = attrs[attr_index + 1].start() if attr_index + 1 < len(attrs) else len(text)
-                method = METHOD_RE.search(text, attr.end(), next_attr + 1200)
+                method = METHOD_RE.search(searchable, attr.end(), next_attr + 1200)
                 if method is None:
-                    method = METHOD_RE.search(text, attr.end())
+                    method = METHOD_RE.search(searchable, attr.end())
                 if method is None:
                     raise RuntimeError(f"No test method after {relative}:{text.count(chr(10), 0, attr.start()) + 1}")
+                if attr.group(1) == "Test" and TEST_ATTR_RE.search(searchable, attr.end(), method.start()):
+                    continue
                 name = method.group(1)
-                fixture = enclosing_class(text, method.start())
+                class_match = enclosing_class_match(searchable, method.start())
+                fixture = class_match.group(1) if class_match else "UnknownFixture"
                 attr_text = " ".join(attr.group(0).split())
+                parameters = " ".join((attr.group(2) or "").split()) or None
                 line = text.count("\n", 0, attr.start()) + 1
+                category_text = searchable[attr.start() : method.start()]
+                if class_match:
+                    category_text += attributes_before(searchable, class_match.start())
+                categories = sorted(set(CATEGORY_RE.findall(category_text)))
                 tests.append(
                     {
+                        "id": stable_case_id(relative, fixture, name, attr.group(1), parameters),
+                        "csharp_test_id": f"{relative}::{fixture}.{name}",
+                        "parameter_case": parameters,
                         "source": relative,
                         "line": line,
                         "fixture": fixture,
                         "method": name,
                         "attribute": attr_text,
                         "body_sha256": method_body_hash(text, method.start()),
+                        "categories": categories,
+                        "fixture_dependencies": dependencies,
                     }
                 )
-    seen: defaultdict[str, int] = defaultdict(int)
+    ids = [str(test["id"]) for test in tests]
+    duplicates = sorted(case_id for case_id, count in Counter(ids).items() if count > 1)
+    if duplicates:
+        raise RuntimeError("Duplicate stable NUnit case IDs: " + ", ".join(duplicates))
+    return tests
+
+
+def reviewed_tests(root: Path) -> dict[str, dict[str, object]]:
+    reviews: dict[str, dict[str, object]] = {}
+    review_roots = (root / "tests" / "compat" / "tests", root / "crates")
+    for path in sorted(path for review_root in review_roots for path in review_root.rglob("*.rs")):
+        if path.name == "generated_parity.rs":
+            continue
+        text = path.read_text()
+        for marker in PARITY_MARKER_RE.finditer(text):
+            next_marker = PARITY_MARKER_RE.search(text, marker.end())
+            rust_test = RUST_TEST_RE.search(text, marker.end(), next_marker.start() if next_marker else len(text))
+            if rust_test is None:
+                raise RuntimeError(f"Parity marker has no following Rust test: {path}:{text.count(chr(10), 0, marker.start()) + 1}")
+            body_sha256 = validate_reviewed_body(path, rust_test, rust_test_body(text, rust_test))
+            case_id = marker.group("id")
+            if case_id in reviews:
+                raise RuntimeError(f"Duplicate reviewed parity case: {case_id}")
+            reviews[case_id] = {
+                "body_sha256": marker.group("body_sha256"),
+                "rust_body_sha256": body_sha256,
+                "status": marker.group("status"),
+                "rust_file": path.relative_to(root).as_posix(),
+                "rust_line": text.count("\n", 0, marker.start()) + 1,
+                "rust_test": rust_test.group(1),
+            }
+    return reviews
+
+
+def render_parity_report(tests: list[dict[str, object]]) -> str:
+    status_counts = {status: sum(test["status"] == status for test in tests) for status in ("pending", "translated", "ignored-live", "benchmark", "drifted")}
+    live_candidates = sum("RequiresLiveServer" in test["categories"] for test in tests)
+    benchmark_candidates = sum("Benchmark" in test["categories"] for test in tests)
+    lines = [
+        "# NUnit to Rust parity ledger",
+        "",
+        f"Generated from LibreMetaverse `{UPSTREAM_COMMIT}`. Stable IDs identify one NUnit `[Test]` or `[TestCase]` invocation; the body hash covers the original C# method declaration and body.",
+        "",
+        "## Status",
+        "",
+        f"- Total: **{len(tests):,}**",
+        f"- Pending/unreviewed: **{status_counts['pending']:,}**",
+        f"- Translated/reviewed: **{status_counts['translated']:,}**",
+        f"- Ignored live/reviewed: **{status_counts['ignored-live']:,}** ({live_candidates:,} upstream live candidates)",
+        f"- Benchmarks/reviewed: **{status_counts['benchmark']:,}** ({benchmark_candidates:,} upstream benchmark candidates)",
+        f"- Drifted: **{status_counts['drifted']:,}**",
+        "",
+        "Reviewed Rust tests live outside `generated_parity.rs` and carry a `parity-case` marker. Regeneration preserves those files and fails if their source body hash drifts.",
+        "",
+        "| Stable case ID | C# test | Parameter case | Source | Categories | Fixtures | Rust location | Status | Body SHA-256 |",
+        "|---|---|---|---|---|---|---|---|---|",
+    ]
+    for test in tests:
+        parameter = str(test["parameter_case"] or "").replace("|", "&#124;")
+        categories = ", ".join(test["categories"])
+        fixtures = ", ".join(test["fixture_dependencies"])
+        rust_location = (
+            f"{test['rust_file']}:{test['rust_line']} (`{test['rust_test']}`)"
+            if test["status"] != "pending"
+            else "pending source translation"
+        )
+        lines.append(
+            f"| `{test['id']}` | `{test['fixture']}.{test['method']}` | `{parameter}` | `{test['source']}:{test['line']}` | `{categories}` | `{fixtures}` | `{rust_location}` | `{test['status']}` | `{test['body_sha256']}` |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def generate_tests(upstream: Path, output: Path, review_root: Path | None = None) -> int:
+    tests = extract_tests(upstream)
+    reviews = reviewed_tests(review_root or output)
+    tests_by_id = {str(test["id"]): test for test in tests}
+    stale = sorted(set(reviews) - set(tests_by_id))
+    if stale:
+        raise RuntimeError("Reviewed cases missing from pinned upstream: " + ", ".join(stale))
+    drifted = sorted(
+        case_id
+        for case_id, review in reviews.items()
+        if review["body_sha256"] != tests_by_id[case_id]["body_sha256"]
+    )
+    if drifted:
+        raise RuntimeError("Reviewed cases have drifted C# bodies: " + ", ".join(drifted))
+
     rust_lines = [
         "// @generated by tools/generate_surface.py; do not edit by hand.",
         f"// Source: LibreMetaverse {UPSTREAM_COMMIT}",
-        "use libremetaverse_compat_tests::pending;",
+        "// Pending cases are catalog entries, not fake executable Rust tests.",
         "",
     ]
-    parity_lines = [
-        "# NUnit to Rust parity ledger",
-        "",
-        f"Generated from LibreMetaverse `{UPSTREAM_COMMIT}`. Each row is one NUnit `[Test]` or `[TestCase]` invocation. The body hash covers the original C# method declaration and body.",
-        "",
-        "| Rust test | C# test | Source | Attribute | Body SHA-256 |",
-        "|---|---|---|---|---|",
-    ]
     for test in tests:
-        base = snake(f"{test['fixture']}_{test['method']}")
-        seen[base] += 1
-        rust_name = base if seen[base] == 1 else f"{base}_case_{seen[base]}"
-        test["rust_test"] = rust_name
-        identity = f"{test['fixture']}.{test['method']}"
-        rust_lines.extend(
-            [
-                "#[test]",
-                f"fn {rust_name}() {{",
-                f"    pending({json.dumps(test['source'])}, {test['line']}, {json.dumps(identity)}, {json.dumps(test['attribute'])}, {json.dumps(test['body_sha256'])});",
-                "}",
-                "",
-            ]
-        )
-        parity_lines.append(
-            f"| `{rust_name}` | `{identity}` | `{test['source']}:{test['line']}` | `{str(test['attribute']).replace('|', '&#124;')}` | `{test['body_sha256']}` |"
+        review = reviews.get(str(test["id"]))
+        if review:
+            test.update(review)
+            test["semantic_review"] = "reviewed"
+            continue
+        test.update(
+            {
+                "rust_file": "tests/compat/tests/generated_parity.rs",
+                "rust_line": len(rust_lines) + 1,
+                "rust_test": "",
+                "rust_body_sha256": None,
+                "status": "pending",
+                "semantic_review": "unreviewed",
+            }
         )
+        rust_lines.append(f"// pending-parity-case: {test['id']} {test['body_sha256']}")
     generated_dir = output / "tests" / "compat" / "tests"
     generated_dir.mkdir(parents=True, exist_ok=True)
-    (generated_dir / "generated_parity.rs").write_text("\n".join(rust_lines))
-    (output / "tests" / "PARITY.md").write_text("\n".join(parity_lines) + "\n")
-    (output / "tests" / "upstream-tests.json").write_text(json.dumps({"upstream_commit": UPSTREAM_COMMIT, "tests": tests}, indent=2) + "\n")
+    (generated_dir / "generated_parity.rs").write_text("\n".join(rust_lines) + "\n")
+    (output / "tests" / "PARITY.md").write_text(render_parity_report(tests))
+    report = {
+        "pending": sum(test["status"] == "pending" for test in tests),
+        "translated": sum(test["status"] == "translated" for test in tests),
+        "ignored_live": sum(test["status"] == "ignored-live" for test in tests),
+        "benchmark": sum(test["status"] == "benchmark" for test in tests),
+        "drifted": 0,
+        "unreviewed": sum(test["semantic_review"] == "unreviewed" for test in tests),
+    }
+    catalog = {
+        "schema_version": 2,
+        "upstream_commit": UPSTREAM_COMMIT,
+        "expected_cases": EXPECTED_TESTS,
+        "report": report,
+        "tests": tests,
+    }
+    (output / "tests" / "upstream-tests.json").write_text(json.dumps(catalog, indent=2) + "\n")
     return len(tests)
 
 
+def scan_parity_markers(root: Path) -> dict[str, list[dict[str, object]]]:
+    return {case_id: [review] for case_id, review in reviewed_tests(root).items()}
+
+
+def check_test_parity(root: Path, require_reviewed: bool = False) -> dict[str, int]:
+    catalog_path = root / "tests" / "upstream-tests.json"
+    catalog = json.loads(catalog_path.read_text())
+    if catalog.get("schema_version") != 2:
+        raise RuntimeError("Unsupported test parity catalog schema")
+    tests = catalog.get("tests", [])
+    expected = catalog.get("expected_cases")
+    if expected != EXPECTED_TESTS or len(tests) != EXPECTED_TESTS:
+        raise RuntimeError(f"Expected {EXPECTED_TESTS} cataloged NUnit invocations, found {len(tests)}")
+    if catalog.get("upstream_commit") != UPSTREAM_COMMIT:
+        raise RuntimeError("Test parity catalog targets the wrong upstream commit")
+
+    ids = [test["id"] for test in tests]
+    duplicate_ids = sorted(case_id for case_id, count in Counter(ids).items() if count > 1)
+    if duplicate_ids:
+        raise RuntimeError("Duplicate catalog case IDs: " + ", ".join(duplicate_ids))
+    by_id = {test["id"]: test for test in tests}
+    markers = scan_parity_markers(root)
+    reviewed_ids = {case_id for case_id, test in by_id.items() if test["status"] != "pending"}
+    missing = sorted(reviewed_ids - set(markers))
+    stale = sorted(set(markers) - set(by_id))
+    premature = sorted(set(markers) - reviewed_ids)
+    duplicates = sorted(case_id for case_id, entries in markers.items() if len(entries) != 1)
+    if missing:
+        raise RuntimeError("Missing Rust parity cases: " + ", ".join(missing))
+    if stale:
+        raise RuntimeError("Stale Rust parity cases: " + ", ".join(stale))
+    if premature:
+        raise RuntimeError("Catalog still marks reviewed Rust cases pending: " + ", ".join(premature))
+    if duplicates:
+        raise RuntimeError("Duplicate Rust parity cases: " + ", ".join(duplicates))
+
+    drifted: list[str] = []
+    mismatched: list[str] = []
+    for case_id in reviewed_ids:
+        test = by_id[case_id]
+        marker = markers[case_id][0]
+        if marker["body_sha256"] != test["body_sha256"]:
+            drifted.append(case_id)
+        for key in ("status", "rust_file", "rust_line", "rust_test", "rust_body_sha256"):
+            if marker[key] != test[key]:
+                mismatched.append(f"{case_id}:{key}")
+    if drifted:
+        raise RuntimeError("Drifted reviewed C# test bodies: " + ", ".join(drifted))
+    if mismatched:
+        raise RuntimeError("Stale parity catalog metadata: " + ", ".join(mismatched))
+
+    report = {
+        "pending": sum(test["status"] == "pending" for test in tests),
+        "translated": sum(test["status"] == "translated" for test in tests),
+        "ignored_live": sum(test["status"] == "ignored-live" for test in tests),
+        "benchmark": sum(test["status"] == "benchmark" for test in tests),
+        "drifted": 0,
+        "unreviewed": sum(test["semantic_review"] != "reviewed" for test in tests),
+    }
+    if catalog.get("report") != report:
+        raise RuntimeError("Stale parity summary report")
+    if require_reviewed and report["unreviewed"]:
+        raise RuntimeError(f"{report['unreviewed']} NUnit invocations remain semantically unreviewed")
+    return report
+
+
+def verify_upstream(upstream: Path) -> None:
+    commit = subprocess.run(
+        ["git", "-C", str(upstream), "rev-parse", "HEAD"],
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout.strip()
+    if commit != UPSTREAM_COMMIT:
+        raise RuntimeError(f"Expected LibreMetaverse {UPSTREAM_COMMIT}, found {commit}")
+
+
+def check_test_regeneration(upstream: Path, output: Path) -> None:
+    with tempfile.TemporaryDirectory() as temporary:
+        generated = Path(temporary)
+        count = generate_tests(upstream, generated, review_root=output)
+        if count != EXPECTED_TESTS:
+            raise RuntimeError(f"Expected {EXPECTED_TESTS} NUnit invocations at {UPSTREAM_COMMIT}, found {count}")
+        stale = [str(path) for path in PARITY_FILES if not (output / path).exists() or (output / path).read_bytes() != (generated / path).read_bytes()]
+        if stale:
+            raise RuntimeError("Stale generated test parity files: " + ", ".join(stale))
+
+
 def generate_program_manifest(upstream: Path, output: Path) -> int:
     roots = [
         upstream / "Programs" / "VivoxTest",
@@ -331,14 +740,28 @@ def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument("--upstream", type=Path, default=Path("../libremetaverse"))
     parser.add_argument("--output", type=Path, default=Path("."))
+    parser.add_argument("--tests-only", action="store_true")
+    parser.add_argument("--check", action="store_true")
     args = parser.parse_args()
     upstream = args.upstream.resolve()
     output = args.output.resolve()
+    verify_upstream(upstream)
+    if args.check:
+        check_test_regeneration(upstream, output)
+        report = check_test_parity(output)
+        print(f"test parity is current: {report}")
+        return
+    if args.tests_only:
+        tests = generate_tests(upstream, output)
+        if tests != EXPECTED_TESTS:
+            raise RuntimeError(f"Expected {EXPECTED_TESTS} NUnit invocations at {UPSTREAM_COMMIT}, found {tests}")
+        print(f"generated {tests} test parity cases")
+        return
     types, members = generate_apis(upstream, output)
     tests = generate_tests(upstream, output)
     programs = generate_program_manifest(upstream, output)
-    if tests != 1295:
-        raise RuntimeError(f"Expected 1295 NUnit invocations at {UPSTREAM_COMMIT}, found {tests}")
+    if tests != EXPECTED_TESTS:
+        raise RuntimeError(f"Expected {EXPECTED_TESTS} NUnit invocations at {UPSTREAM_COMMIT}, found {tests}")
     print(f"generated {types} type declarations, {members} public declaration lines, {tests} tests, and {programs} program manifests")