@matt82198/aesop 0.2.0 → 0.3.1

package/tools/stateapi_lint.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""
+tools.stateapi_lint — Scanner for direct state file opens outside the API.
+
+Detects violations of the "reads go through state_store.read_api" rule by scanning
+ui/ and tools/ for direct opens of state files (tracker.json, orchestrator-status.json,
+heartbeat files, OUTCOMES-LEDGER.md) outside the read_api module.
+
+Writers (state_store/export.py, state_store/ingest.py, etc.) are allowlisted.
+
+RATCHET MODE (hardening):
+  Baseline is keyed by file + pattern-id (NOT line numbers).
+  Without --update-baseline flag:
+    - FAILS if baseline contains entries absent from current scan (stale baseline)
+    - FAILS if current violations missing from baseline (new violations)
+    - PASS only if: current violations exactly match baseline entries
+  With --update-baseline flag:
+    - Allows regenerating the baseline (sets current as new baseline)
+
+  CI MUST NEVER pass --update-baseline (hand-edits of baseline detected & fail).
+
+Exit codes:
+  0 = all checks pass
+  1 = violations detected or baseline mismatch
+  2 = error
+
+Usage:
+  python tools/stateapi_lint.py [--root REPO_ROOT] [--json] [--update-baseline]
+
+Options:
+  --root REPO_ROOT: Repository root (default: cwd)
+  --json: Output JSON instead of text
+  --update-baseline: Regenerate baseline from current violations (CI must never use)
+"""
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# State files that should only be read via the API
+STATE_FILES_TO_PROTECT = [
+    "tracker.json",
+    "orchestrator-status.json",
+    "OUTCOMES-LEDGER.md",
+    ".watchdog-heartbeat",
+    ".monitor-heartbeat",
+    ".orchestrator-heartbeat",
+]
+
+# File patterns that are WRITERS and allowed to access state files directly
+WRITER_ALLOWLIST = [
+    "state_store/export.py",
+    "state_store/ingest.py",
+    "state_store/read_api.py",  # The read API facade itself (reads the state files)
+    "state_store/write_api.py",  # The write API facade (reads/writes the projection atomically)
+    "ui/collectors.py",  # Some readers also export/flush
+    "tools/cost.py",  # Parses ledger
+]
+
+# Directories to scan for violations
+SCAN_DIRS = ["ui", "tools", "state_store"]  # Include state_store to catch internal issues
+
+
+def find_direct_opens(repo_root):
+    """Scan repo for direct opens of protected state files outside the API.
+
+    Returns violations keyed by file + pattern-id (not line numbers).
+    Pattern-id is the matched pattern index, making the key stable across line edits.
+
+    Args:
+        repo_root: Path to repository root
+
+    Returns:
+        list: List of violation keys (file@pattern-id format)
+    """
+    repo_root = Path(repo_root)
+    violations = []
+
+    # Pattern to detect file opens: Path(...).read_text(), open(...), json.load(open(...)), etc.
+    # Each pattern gets an ID for stable keying across line number changes
+    read_patterns = [
+        (r'["\']tracker\.json["\']', "tracker-json"),
+        (r'["\']orchestrator-status\.json["\']', "status-json"),
+        (r'["\']OUTCOMES-LEDGER\.md["\']', "ledger-md"),
+        (r'["\']\.watchdog-heartbeat["\']', "watchdog-hb"),
+        (r'["\']\.monitor-heartbeat["\']', "monitor-hb"),
+        (r'["\']\.orchestrator-heartbeat["\']', "orchestrator-hb"),
+        (r'state\s*/\s*tracker\.json', "state-tracker-json"),
+        (r'state\s*/\s*orchestrator-status', "state-status-json"),
+        (r'state\s*/\s*.*heartbeat', "state-heartbeat"),
+    ]
+
+    for scan_dir in SCAN_DIRS:
+        scan_path = repo_root / scan_dir
+        if not scan_path.exists():
+            continue
+
+        for py_file in scan_path.rglob("*.py"):
+            # Check if this file is in the allowlist
+            relative_path = py_file.relative_to(repo_root)
+            is_allowed = any(
+                str(relative_path).replace("\\", "/") == allow.replace("\\", "/")
+                for allow in WRITER_ALLOWLIST
+            )
+
+            if is_allowed:
+                continue
+
+            try:
+                content = py_file.read_text(encoding="utf-8", errors="replace")
+            except Exception:
+                continue
+
+            # Skip if file imports read_api (it's using the facade correctly)
+            if "from state_store.read_api import" in content or "import state_store.read_api" in content:
+                continue
+
+            # Scan for violations
+            for line_num, line in enumerate(content.split("\n"), 1):
+                for pattern, pattern_id in read_patterns:
+                    if re.search(pattern, line):
+                        # Additional filter: skip comment lines and string literals in docstrings
+                        if line.strip().startswith("#"):
+                            continue
+                        if '"""' in line or "'''" in line:
+                            continue
+
+                        # Key is file@pattern-id (stable across line edits)
+                        # Use posix separators for cross-platform consistency
+                        violation_key = f"{relative_path.as_posix()}@{pattern_id}"
+                        if violation_key not in violations:
+                            violations.append(violation_key)
+                        break  # Only report once per line per file
+
+    return sorted(violations)
+
+
+def save_baseline(baseline_file, data):
+    """Save violations baseline to JSON file.
+
+    Args:
+        baseline_file: Path to baseline file
+        data: dict with "violations" list
+    """
+    baseline_file = Path(baseline_file)
+    baseline_file.parent.mkdir(parents=True, exist_ok=True)
+    baseline_file.write_text(json.dumps(data, indent=2))
+
+
+def load_baseline(baseline_file):
+    """Load violations baseline from JSON file.
+
+    Returns:
+        dict with "violations" list, or empty dict if file missing.
+    """
+    baseline_file = Path(baseline_file)
+    if not baseline_file.exists():
+        return {"violations": []}
+
+    try:
+        return json.loads(baseline_file.read_text())
+    except Exception:
+        return {"violations": []}
+
+
+def normalize_key(key):
+    """Normalize violation keys to forward-slash separators for cross-platform consistency.
+
+    Converts backslash separators (legacy Windows baseline entries) to forward slashes.
+
+    Args:
+        key: Violation key string
+
+    Returns:
+        str: Key with forward-slash separators
+    """
+    return key.replace("\\", "/")
+
+
+def check_ratchet(baseline_violations, current_violations):
+    """Check ratchet: baseline and current must match exactly.
+
+    Fails if:
+      1. Baseline contains entries absent from current (stale baseline)
+      2. Current violations missing from baseline (new violations)
+
+    Only passes if current violations exactly match baseline (bidirectional check).
+    Normalizes both sets to forward-slash separators for cross-platform consistency.
+
+    Args:
+        baseline_violations: list of violation keys from baseline
+        current_violations: list of violation keys from current scan
+
+    Returns:
+        tuple: (is_ok, stale_entries, new_violations)
+          is_ok (bool): True only if baseline == current
+          stale_entries (list): Entries in baseline not in current
+          new_violations (list): Entries in current not in baseline
+    """
+    # Normalize both to forward slashes for comparison
+    baseline_set = set(normalize_key(v) for v in baseline_violations)
+    current_set = set(normalize_key(v) for v in current_violations)
+
+    stale = list(baseline_set - current_set)
+    new = list(current_set - baseline_set)
+
+    is_ok = (len(stale) == 0 and len(new) == 0)
+    return is_ok, sorted(stale), sorted(new)
+
+
+def main(argv=None):
+    """CLI entry point."""
+    argv = sys.argv[1:] if argv is None else argv
+
+    repo_root = None
+    output_format = "text"
+    baseline_file = None
+    update_baseline = False
+
+    # Parse arguments
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--root":
+            i += 1
+            if i < len(argv):
+                repo_root = argv[i]
+            i += 1
+        elif arg.startswith("--root="):
+            repo_root = arg[len("--root="):]
+            i += 1
+        elif arg == "--json":
+            output_format = "json"
+            i += 1
+        elif arg == "--baseline":
+            i += 1
+            if i < len(argv):
+                baseline_file = argv[i]
+            i += 1
+        elif arg == "--update-baseline":
+            update_baseline = True
+            i += 1
+        else:
+            print(f"Unknown argument: {arg}", file=sys.stderr)
+            return 2
+
+    if repo_root is None:
+        repo_root = Path.cwd()
+    else:
+        repo_root = Path(repo_root)
+
+    if baseline_file is None:
+        baseline_file = repo_root / ".stateapi-baseline.json"
+
+    # Scan for violations
+    violations = find_direct_opens(str(repo_root))
+
+    # Load baseline
+    baseline_data = load_baseline(str(baseline_file))
+    baseline_violations = baseline_data.get("violations", [])
+
+    # If --update-baseline, save current as baseline and exit
+    if update_baseline:
+        save_baseline(baseline_file, {"violations": violations})
+        if output_format == "json":
+            print(json.dumps({"ok": True, "message": "Baseline updated", "count": len(violations)}, indent=2))
+        else:
+            print(f"Baseline updated: {len(violations)} violation(s) recorded")
+        return 0
+
+    # Check ratchet: baseline must match current exactly
+    is_ok, stale_entries, new_violations = check_ratchet(baseline_violations, violations)
+
+    if output_format == "json":
+        result = {
+            "ok": is_ok,
+            "violations": violations,
+            "baseline_count": len(baseline_violations),
+            "current_count": len(violations),
+            "stale_entries": stale_entries,
+            "new_violations": new_violations,
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        # Text format
+        print(f"State API lint: {len(violations)} violation(s) found")
+        if baseline_violations:
+            print(f"  (baseline: {len(baseline_violations)})")
+
+        if violations:
+            for v in sorted(violations):
+                print(f"  {v}")
+
+        # Report stale entries (in baseline but not current)
+        if stale_entries:
+            print(f"\nSTALE baseline entries ({len(stale_entries)}) — hand-edited or fixed?:")
+            for v in stale_entries:
+                print(f"  {v}")
+
+        # Report new violations (in current but not baseline)
+        if new_violations:
+            print(f"\nNEW violations ({len(new_violations)}):")
+            for v in new_violations:
+                print(f"  {v}")
+
+        # Final verdict
+        if is_ok:
+            if violations:
+                print(f"\nPASS: All {len(violations)} violations match baseline")
+            else:
+                print("\nPASS: No violations")
+            return 0
+        else:
+            if stale_entries and new_violations:
+                print(f"\nFAIL: {len(stale_entries)} stale + {len(new_violations)} new violation(s)")
+            elif stale_entries:
+                print(f"\nFAIL: {len(stale_entries)} stale baseline entries (hand-edited?)")
+            else:
+                print(f"\nFAIL: {len(new_violations)} new violation(s) detected")
+            return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/test_battery.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""test_battery.py -- run the local union test battery, parallel by default.
+
+Runs the four harnesses (python unittest discover, node --test, shell suites,
+ui vitest+tsc) as concurrent subprocesses with per-harness rc capture, stdin
+closed (the hook suite hangs on never-EOF stdin), and an explicit summary
+table. Exit 0 only when every harness exits 0.
+
+Per-harness timeout (AESOP_BATTERY_HARNESS_TIMEOUT_S, default 1800s = 30min):
+on expiry, the process tree is killed and rc=124 is recorded with a TIMEOUT
+note. Applies in both serial and parallel modes.
+
+Usage:
+  python tools/test_battery.py [--serial] [--skip ui|sh|node|py ...] [--json]
+
+--serial runs harnesses one at a time (the pre-wave-29 behavior; fallback if
+parallel runs prove load-fragile on a box). Logs land in the state scratch dir
+(AESOP_BATTERY_LOGDIR or the system temp dir) as battery-<harness>.log.
+"""
+import argparse
+import json
+import os
+import platform
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+
+HARNESSES = {
+    "py": [sys.executable, "-m", "unittest", "discover", "-s", "tests"],
+    "node": ["npm", "run", "test:node"],
+    "sh": ["npm", "run", "test:sh"],
+    "ui": None,  # composite: tsc + vitest, run via _ui_command
+}
+
+
+def _get_harness_timeout():
+    """Get per-harness timeout in seconds (env AESOP_BATTERY_HARNESS_TIMEOUT_S, default 1800)."""
+    timeout_s = os.environ.get("AESOP_BATTERY_HARNESS_TIMEOUT_S", "1800")
+    try:
+        return int(timeout_s)
+    except ValueError:
+        return 1800
+
+
+def _kill_process_tree(proc):
+    """Kill process and all children (Windows: taskkill /T /F, others: SIGKILL)."""
+    try:
+        if platform.system() == "Windows":
+            subprocess.run(
+                ["taskkill", "/PID", str(proc.pid), "/T", "/F"],
+                capture_output=True,
+                timeout=5,
+            )
+        else:
+            # Unix: SIGKILL via os.killpg (process group)
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except (ProcessLookupError, OSError):
+                # Process already gone or not in a group; try direct kill
+                try:
+                    os.kill(proc.pid, signal.SIGKILL)
+                except (ProcessLookupError, OSError):
+                    pass
+    except Exception:
+        # Ignore kill errors; process may already be dead
+        pass
+
+
+def _wait_with_timeout(proc, timeout_s):
+    """Wait for process with timeout; return (rc, timed_out).
+
+    On timeout, kills the process tree and returns (124, True).
+    Otherwise returns (proc.returncode, False).
+    """
+    try:
+        proc.wait(timeout=timeout_s)
+        return proc.returncode, False
+    except subprocess.TimeoutExpired:
+        _kill_process_tree(proc)
+        # Wait a moment for kill to take effect, then force reap
+        try:
+            proc.wait(timeout=1)
+        except subprocess.TimeoutExpired:
+            pass
+        return 124, True
+
+
+def _ui_command():
+    # ui/web needs node_modules; npx resolves local binaries.
+    return "npx tsc --noEmit && npx vitest run --silent"
+
+
+def run_harness(name, logdir, parallel=True):
+    """Spawn one harness with stdin closed; return (name, Popen, logfile)."""
+    log = Path(logdir) / f"battery-{name}.log"
+    f = open(log, "w", encoding="utf-8", errors="replace")
+    env = os.environ.copy()
+    if parallel and name == "node" and "AESOP_TEST_CHILD_TIMEOUT_MS" not in env:
+        # Under 4-harness parallel load, scaffold child processes legitimately
+        # exceed the 30s solo ceiling; the tests honor this knob (wave-29).
+        env["AESOP_TEST_CHILD_TIMEOUT_MS"] = "90000"
+    if name == "ui":
+        proc = subprocess.Popen(
+            _ui_command(), shell=True, cwd=str(REPO / "ui" / "web"),
+            stdin=subprocess.DEVNULL, stdout=f, stderr=subprocess.STDOUT, env=env,
+        )
+    else:
+        # npm needs shell resolution on Windows.
+        use_shell = os.name == "nt" and HARNESSES[name][0] == "npm"
+        cmd = " ".join(HARNESSES[name]) if use_shell else HARNESSES[name]
+        proc = subprocess.Popen(
+            cmd, shell=use_shell, cwd=str(REPO),
+            stdin=subprocess.DEVNULL, stdout=f, stderr=subprocess.STDOUT, env=env,
+        )
+    return name, proc, f, log
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Run the local union test battery")
+    ap.add_argument("--serial", action="store_true", help="run harnesses sequentially")
+    ap.add_argument("--skip", action="append", default=[], choices=list(HARNESSES),
+                    help="skip a harness (repeatable)")
+    ap.add_argument("--json", action="store_true", help="machine-readable summary")
+    args = ap.parse_args()
+
+    logdir = os.environ.get("AESOP_BATTERY_LOGDIR") or tempfile.mkdtemp(prefix="aesop-battery-")
+    os.makedirs(logdir, exist_ok=True)
+    names = [n for n in HARNESSES if n not in args.skip]
+    started = time.time()
+    results = {}
+    timeout_s = _get_harness_timeout()
+
+    if args.serial:
+        for n in names:
+            name, proc, f, log = run_harness(n, logdir, parallel=False)
+            rc, timed_out = _wait_with_timeout(proc, timeout_s)
+            f.close()
+            result = {"rc": rc, "log": str(log)}
+            if timed_out:
+                result["note"] = "TIMEOUT"
+            results[name] = result
+    else:
+        procs = [run_harness(n, logdir) for n in names]
+        for name, proc, f, log in procs:
+            rc, timed_out = _wait_with_timeout(proc, timeout_s)
+            f.close()
+            result = {"rc": rc, "log": str(log)}
+            if timed_out:
+                result["note"] = "TIMEOUT"
+            results[name] = result
+
+    wall = round(time.time() - started, 1)
+    ok = all(r["rc"] == 0 for r in results.values())
+    if args.json:
+        print(json.dumps({"ok": ok, "wall_s": wall, "mode": "serial" if args.serial else "parallel",
+                          "results": results}))
+    else:
+        print(f"battery mode={'serial' if args.serial else 'parallel'} wall={wall}s")
+        for n, r in results.items():
+            verdict = "PASS" if r["rc"] == 0 else "FAIL"
+            note_str = f" {r['note']}" if "note" in r else ""
+            print(f"  {n:5s} rc={r['rc']}  {verdict}{note_str}  log={r['log']}")
+        print("BATTERY:", "GREEN" if ok else "RED")
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()