@matt82198/aesop 0.1.0 → 0.2.0

package/tools/mutation_test.py

@@ -0,0 +1,401 @@
+#!/usr/bin/env python3
+"""
+Mutation testing tool — measures whether a module's tests actually catch bugs.
+
+This tool applies small source-code mutations (copy, never mutate original) to
+a target module and runs its test suite against each mutation. Tests that pass
+despite a mutation indicate a gap in test coverage (weak tests). Survived
+mutations are reported as weak spots the tests don't cover.
+
+Why: green test suites often just mean 'tests agree with the code', not
+'tests catch bugs'. Mutation testing reveals test quality gaps.
+
+Mutations applied:
+  - Flip comparison operators (== <-> !=, < <-> >=, > <-> <=)
+  - Replace numeric literals with +1
+  - Replace boolean returns with negation
+  - Replace 'and' <-> 'or'
+  - Replace 'is None' <-> 'is not None'
+
+Configuration (aesop.config.json):
+  [none — no configuration needed]
+
+API:
+  run(target_module_path, test_module_path) -> dict
+    Returns {"killed": int, "survived": int, "mutations": [...]}
+    mutations is a list of {"file": str, "line": int, "original": str, "mutated": str}
+
+CLI:
+  python tools/mutation_test.py --target module.py --test test_module.py [--json]
+    Exit 0 always (advisory, not gated). --json outputs JSON to stdout.
+"""
+
+import argparse
+import ast
+import copy
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Tuple, Optional
+
+
+class MutationGenerator(ast.NodeTransformer):
+    """AST transformer that generates mutations of a Python module."""
+
+    def __init__(self):
+        self.mutations: List[Tuple[int, str, str]] = []  # (line, original, mutated)
+        self.current_mutation_idx = 0
+        self.target_mutation_idx = -1  # -1 means no mutation, just record
+
+    def record_mutation(self, line: int, original: str, mutated: str) -> None:
+        """Record a mutation and track mutation index."""
+        self.mutations.append((line, original, mutated))
+
+    def visit_Compare(self, node: ast.Compare) -> Any:
+        """Mutate comparison operators: == <-> !=, < <-> >=, etc."""
+        self.generic_visit(node)
+
+        # Map of operator mutations
+        op_map = {
+            ast.Eq: (ast.NotEq, "==", "!="),
+            ast.NotEq: (ast.Eq, "!=", "=="),
+            ast.Lt: (ast.GtE, "<", ">="),
+            ast.Gt: (ast.LtE, ">", "<="),
+            ast.LtE: (ast.Gt, "<=", ">"),
+            ast.GtE: (ast.Lt, ">=", "<"),
+        }
+
+        for i, op in enumerate(node.ops):
+            if type(op) in op_map:
+                mutated_op, orig_str, mut_str = op_map[type(op)]
+                self.record_mutation(node.lineno, orig_str, mut_str)
+
+                if self.current_mutation_idx == len(self.mutations) - 1 and self.target_mutation_idx == self.current_mutation_idx:
+                    node.ops[i] = mutated_op()
+
+                self.current_mutation_idx += 1
+
+        return node
+
+    def visit_Constant(self, node: ast.Constant) -> Any:
+        """Mutate numeric literals: n -> n+1."""
+        self.generic_visit(node)
+
+        if isinstance(node.value, (int, float)) and not isinstance(node.value, bool):
+            mutated_val = node.value + 1
+            self.record_mutation(node.lineno, str(node.value), str(mutated_val))
+
+            if self.current_mutation_idx == len(self.mutations) - 1 and self.target_mutation_idx == self.current_mutation_idx:
+                node.value = mutated_val
+
+            self.current_mutation_idx += 1
+
+        return node
+
+    def visit_Return(self, node: ast.Return) -> Any:
+        """Mutate boolean returns: True -> False, False -> True."""
+        self.generic_visit(node)
+
+        if node.value and isinstance(node.value, ast.Constant):
+            if isinstance(node.value.value, bool):
+                orig_val = node.value.value
+                mut_val = not orig_val
+                self.record_mutation(node.lineno, str(orig_val), str(mut_val))
+
+                if self.current_mutation_idx == len(self.mutations) - 1 and self.target_mutation_idx == self.current_mutation_idx:
+                    node.value.value = mut_val
+
+                self.current_mutation_idx += 1
+
+        return node
+
+    def visit_BoolOp(self, node: ast.BoolOp) -> Any:
+        """Mutate boolean operators: and <-> or."""
+        self.generic_visit(node)
+
+        if isinstance(node.op, (ast.And, ast.Or)):
+            is_and = isinstance(node.op, ast.And)
+            orig_str = "and" if is_and else "or"
+            mut_str = "or" if is_and else "and"
+            self.record_mutation(node.lineno, orig_str, mut_str)
+
+            if self.current_mutation_idx == len(self.mutations) - 1 and self.target_mutation_idx == self.current_mutation_idx:
+                node.op = ast.Or() if is_and else ast.And()
+
+            self.current_mutation_idx += 1
+
+        return node
+
+    def visit_UnaryOp(self, node: ast.UnaryOp) -> Any:
+        """Mutate 'not' in returns to None checks."""
+        self.generic_visit(node)
+        return node
+
+
+def extract_mutations(source: str) -> List[Tuple[int, str, str]]:
+    """Parse source and extract all possible mutations."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    transformer = MutationGenerator()
+    transformer.generic_visit(tree)
+    return transformer.mutations
+
+
+def apply_mutation(source: str, mutation_idx: int) -> Optional[str]:
+    """Apply a specific mutation to source code by index.
+
+    Returns mutated source, or None if mutation_idx is out of range.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+
+    mutations = extract_mutations(source)
+    if mutation_idx < 0 or mutation_idx >= len(mutations):
+        return None
+
+    # Re-parse and apply the specific mutation
+    tree = ast.parse(source)
+    transformer = MutationGenerator()
+    transformer.target_mutation_idx = mutation_idx
+    new_tree = transformer.visit(tree)
+
+    try:
+        return ast.unparse(new_tree)
+    except Exception:
+        # If unparsing fails, return None
+        return None
+
+
+def _pytest_available() -> bool:
+    """Return True if pytest is importable by the current interpreter.
+
+    We must decide the runner up-front rather than relying on a subprocess
+    exception: ``python -m pytest`` with pytest absent exits with code 1
+    ("No module named pytest") and does NOT raise FileNotFoundError, so an
+    ``except FileNotFoundError`` fallback would never fire — every test run
+    would look like a failure (exit 1) and every mutation would be counted
+    as 'killed', reporting 0 survivors regardless of test quality.
+    """
+    try:
+        return importlib.util.find_spec("pytest") is not None
+    except Exception:
+        return False
+
+
+def run_tests(test_module_path: str, work_dir: str, timeout: int = 30) -> Tuple[int, str]:
+    """Run a test module in a subprocess against the code in ``work_dir``.
+
+    The (mutated) target copy lives in ``work_dir``; we force that directory
+    onto PYTHONPATH and run with cwd=work_dir so the test genuinely imports
+    the MUTATED copy on every platform, regardless of any sys.path juggling
+    the test module itself does. Prefers pytest when available, else falls
+    back to the always-present stdlib unittest.
+
+    Returns (exit_code, stdout+stderr).
+    """
+    # Deterministically make the mutated copy importable (Linux + Windows).
+    env = dict(os.environ)
+    existing = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = work_dir + (os.pathsep + existing if existing else "")
+
+    if _pytest_available():
+        cmd = [sys.executable, "-m", "pytest", "-xvs", test_module_path]
+    else:
+        # unittest needs a module name (importable via cwd/PYTHONPATH), not a path.
+        cmd = [sys.executable, "-m", "unittest", "-v", Path(test_module_path).stem]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=work_dir,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+        return result.returncode, result.stdout + result.stderr
+    except subprocess.TimeoutExpired:
+        return 124, "Test timeout (>{}s)".format(timeout)
+
+
+def run(target_module_path: str, test_module_path: str) -> Dict[str, Any]:
+    """Run mutation testing on target_module_path using test_module_path.
+
+    Returns {
+        "killed": int,
+        "survived": int,
+        "mutations": [
+            {"file": str, "line": int, "original": str, "mutated": str},
+            ...
+        ]
+    }
+    """
+    target_path = Path(target_module_path).resolve()
+    test_path = Path(test_module_path).resolve()
+
+    if not target_path.exists():
+        return {
+            "killed": 0,
+            "survived": 0,
+            "mutations": [],
+            "error": f"target module not found: {target_module_path}",
+        }
+
+    if not test_path.exists():
+        return {
+            "killed": 0,
+            "survived": 0,
+            "mutations": [],
+            "error": f"test module not found: {test_module_path}",
+        }
+
+    # Read target source
+    try:
+        source = target_path.read_text(encoding="utf-8")
+    except Exception as e:
+        return {
+            "killed": 0,
+            "survived": 0,
+            "mutations": [],
+            "error": f"failed to read target: {e}",
+        }
+
+    # Extract mutations
+    mutations = extract_mutations(source)
+    if not mutations:
+        return {
+            "killed": 0,
+            "survived": 0,
+            "mutations": [],
+        }
+
+    # Create temporary work directory
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+
+        # Copy target to temp dir
+        temp_target = tmpdir / target_path.name
+        temp_target.write_text(source, encoding="utf-8")
+
+        # Copy test to temp dir
+        temp_test = tmpdir / test_path.name
+        try:
+            test_source = test_path.read_text(encoding="utf-8")
+            temp_test.write_text(test_source, encoding="utf-8")
+        except Exception as e:
+            return {
+                "killed": 0,
+                "survived": 0,
+                "mutations": [],
+                "error": f"failed to copy test: {e}",
+            }
+
+        # Copy any other Python files from test directory (dependencies)
+        test_dir = test_path.parent
+        for py_file in test_dir.glob("*.py"):
+            if py_file.name not in (test_path.name, target_path.name):
+                try:
+                    dest = tmpdir / py_file.name
+                    dest.write_text(py_file.read_text(encoding="utf-8"), encoding="utf-8")
+                except Exception:
+                    pass  # Best effort
+
+        # Run tests against unmutated code (baseline)
+        baseline_exit, _ = run_tests(str(temp_test), str(tmpdir))
+        baseline_passes = (baseline_exit == 0)
+
+        # Guard: if baseline tests fail, the results are invalid.
+        # Every mutation would also fail, giving a false-perfect kill rate.
+        if not baseline_passes:
+            return {
+                "killed": 0,
+                "survived": 0,
+                "mutations": [],
+                "error": "baseline tests fail in sandbox — results invalid",
+            }
+
+        killed = 0
+        survived = 0
+        survived_mutations = []
+
+        # Test each mutation
+        for mut_idx, (line, orig, mutated) in enumerate(mutations):
+            mutated_source = apply_mutation(source, mut_idx)
+            if mutated_source is None:
+                continue
+
+            # Write mutated source to temp file
+            temp_target.write_text(mutated_source, encoding="utf-8")
+
+            # Run tests
+            exit_code, _ = run_tests(str(temp_test), str(tmpdir))
+            tests_pass = (exit_code == 0)
+
+            if tests_pass:
+                # Mutation survived (tests didn't catch the bug)
+                survived += 1
+                survived_mutations.append({
+                    "file": target_path.name,
+                    "line": line,
+                    "original": orig,
+                    "mutated": mutated,
+                })
+            else:
+                # Mutation killed (tests caught the bug)
+                killed += 1
+
+        # Restore original
+        temp_target.write_text(source, encoding="utf-8")
+
+        return {
+            "killed": killed,
+            "survived": survived,
+            "mutations": survived_mutations,
+        }
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Mutation testing tool - measure test quality by applying mutations."
+    )
+    parser.add_argument("--target", required=True, help="Target module to mutate (path to .py file)")
+    parser.add_argument("--test", required=True, help="Test module to run (path to .py file)")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+
+    args = parser.parse_args(argv)
+
+    result = run(args.target, args.test)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print("Mutation test results:")
+        print(f"  Killed:   {result['killed']}")
+        print(f"  Survived: {result['survived']}")
+        if result["survived"] > 0:
+            print("\nSurvived mutations (test gaps):")
+            for mut in result["mutations"]:
+                print(f"  {mut['file']}:{mut['line']} - {mut['original']} -> {mut['mutated']}")
+        if "error" in result:
+            print(f"\nError: {result['error']}", file=sys.stderr)
+
+    # Exit nonzero if there's a baseline error (tool/setup failure).
+    # Normal results (mutations/survivors) exit 0 (advisory).
+    if "error" in result:
+        return 1
+    return 0  # Exit 0 always (advisory) for normal results
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/portability_check.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""
+Portability gate: scan shipped surface for hardcoded personal/environment paths.
+
+Detects absolute Windows user paths (C:\\Users\\<name> / C:/Users/<name>),
+POSIX home paths (/home/<name>, /Users/<name>), and private-machine tokens
+('conductor3', 'matt8'). Allows clearly-marked examples/defaults (lines containing
+'example', 'default', or 'e.g.').
+
+Exit 0 clean, 1 with numbered file:line findings.
+Supports --json output and --root for base directory.
+"""
+
+import sys
+import os
+import json
+import re
+import glob
+import argparse
+from pathlib import Path
+
+
+def read_package_json(root):
+    """Read package.json and extract 'files' array."""
+    pkg_path = os.path.join(root, 'package.json')
+    try:
+        with open(pkg_path, 'r') as f:
+            content = json.load(f)
+        return content.get('files', [])
+    except (FileNotFoundError, json.JSONDecodeError):
+        return []
+
+
+def expand_globs(root, patterns):
+    """Expand glob patterns from package.json 'files' array."""
+    files = set()
+    for pattern in patterns:
+        # Normalize pattern to use forward slashes for glob
+        pattern = pattern.replace('\\', '/')
+        full_pattern = os.path.join(root, pattern).replace('\\', '/')
+
+        matches = glob.glob(full_pattern, recursive=True)
+        for match in matches:
+            # Use Path to normalize, convert back to string
+            normalized = str(Path(match))
+            files.add(normalized)
+
+    return sorted(files)
+
+
+def is_text_file(filepath):
+    """Check if file is likely text (not binary)."""
+    binary_extensions = {
+        '.bin', '.exe', '.dll', '.so', '.dylib',
+        '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp',
+        '.pdf', '.zip', '.tar', '.gz', '.rar',
+        '.woff', '.woff2', '.ttf', '.eot',
+        '.mp3', '.mp4', '.wav', '.mov'
+    }
+    _, ext = os.path.splitext(filepath.lower())
+    return ext not in binary_extensions
+
+
+def read_file_lines(filepath):
+    """Read file lines, handling encoding issues gracefully."""
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            return f.readlines()
+    except UnicodeDecodeError:
+        try:
+            with open(filepath, 'r', encoding='latin-1') as f:
+                return f.readlines()
+        except Exception:
+            return []
+    except Exception:
+        return []
+
+
+def is_exception_line(line):
+    """Check if line is marked as example/default."""
+    line_lower = line.lower()
+    return any(marker in line_lower for marker in ['example', 'default', 'e.g.'])
+
+
+def scan_line_for_paths(line):
+    """Scan a line for problematic paths and tokens."""
+    findings = []
+
+    # Windows absolute paths: C:\Users\<name> or C:/Users/<name>
+    windows_user_patterns = [
+        r'C:\\Users\\[a-zA-Z0-9_\-\.]+',
+        r'C:/Users/[a-zA-Z0-9_\-\.]+'
+    ]
+    for pattern in windows_user_patterns:
+        matches = re.finditer(pattern, line)
+        for match in matches:
+            findings.append({
+                'type': 'windows_user_path',
+                'path': match.group(0)
+            })
+
+    # POSIX home paths: /home/<name> or /Users/<name>
+    posix_patterns = [
+        r'/home/[a-zA-Z0-9_\-\.]+',
+        r'/Users/[a-zA-Z0-9_\-\.]+'
+    ]
+    for pattern in posix_patterns:
+        matches = re.finditer(pattern, line)
+        for match in matches:
+            findings.append({
+                'type': 'posix_home_path',
+                'path': match.group(0)
+            })
+
+    # Private machine tokens: 'conductor3' and 'matt8'
+    # These are simple word boundary matches (whole word)
+    for token in ['conductor3', 'matt8']:
+        # Use word boundaries to avoid false positives in longer identifiers
+        pattern = r'\b' + re.escape(token) + r'\b'
+        matches = re.finditer(pattern, line)
+        for match in matches:
+            findings.append({
+                'type': 'private_token',
+                'token': token
+            })
+
+    return findings
+
+
+def scan_shipped_surface(root, json_output=False):
+    """Scan shipped surface for portability issues."""
+    patterns = read_package_json(root)
+    if not patterns:
+        print("Warning: Could not read package.json 'files' array", file=sys.stderr)
+        return []
+
+    files = expand_globs(root, patterns)
+    all_findings = []
+
+    for filepath in files:
+        if not os.path.isfile(filepath) or not is_text_file(filepath):
+            continue
+
+        lines = read_file_lines(filepath)
+        for line_num, line in enumerate(lines, 1):
+            # Skip exception lines (marked as example/default)
+            if is_exception_line(line):
+                continue
+
+            # Scan for issues
+            issues = scan_line_for_paths(line)
+            for issue in issues:
+                relative_path = os.path.relpath(filepath, root)
+                finding = {
+                    'file': relative_path,
+                    'line': line_num,
+                    'content': line.rstrip()[:100],  # First 100 chars
+                    **issue
+                }
+                all_findings.append(finding)
+
+    return all_findings
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Portability gate: scan for hardcoded personal paths'
+    )
+    parser.add_argument(
+        '--root',
+        default='.',
+        help='Root directory to scan (default: current directory)'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output findings as JSON'
+    )
+
+    args = parser.parse_args()
+    root = os.path.abspath(args.root)
+
+    findings = scan_shipped_surface(root, json_output=args.json)
+
+    if args.json:
+        print(json.dumps(findings, indent=2))
+    else:
+        if findings:
+            print(f"Found {len(findings)} portability issue(s):", file=sys.stderr)
+            for i, finding in enumerate(findings, 1):
+                print(
+                    f"{i}. {finding['file']}:{finding['line']}: "
+                    f"{finding.get('type', 'unknown')}",
+                    file=sys.stderr
+                )
+                if finding.get('path'):
+                    print(f"   Path: {finding['path']}", file=sys.stderr)
+                if finding.get('token'):
+                    print(f"   Token: {finding['token']}", file=sys.stderr)
+                print(f"   {finding['content']}", file=sys.stderr)
+
+    return 1 if findings else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/tools/reconcile.py

@@ -60,9 +60,11 @@ manufacturing a false "in sync".
 
 ## Usage
 
-    python tools/reconcile.py --state-md STATE.md --db state/events.db
-    python tools/reconcile.py --state-md STATE.md --db state/events.db --resolve
-    python tools/reconcile.py --state-md STATE.md --db state/events.db --json
+    python tools/reconcile.py --state-md STATE.md
+    python tools/reconcile.py --state-md STATE.md --resolve
+    python tools/reconcile.py --state-md STATE.md --json
+
+(DB path defaults to state/tracker_events.db; override with --db if needed.)
 
 Exit codes: 0 = no drift (or drift cleanly resolved), 1 = drift detected and
 NOT resolved (report mode), 2 = usage/file error.
@@ -81,6 +83,7 @@ if str(ROOT) not in sys.path:
     sys.path.insert(0, str(ROOT))
 
 from state_store.store import EventStore  # noqa: E402
+from tools.common import get_state_db_path  # noqa: E402
 
 PHASE_RE = re.compile(r"^##\s*Phase:\s*`([^`]+)`", re.MULTILINE)
 
@@ -251,7 +254,7 @@ def _format_human(report: dict) -> str:
 def main(argv=None) -> int:
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument("--state-md", default="STATE.md", help="Path to STATE.md (default: ./STATE.md)")
-    parser.add_argument("--db", default="state/events.db", help="Path to state_store SQLite db")
+    parser.add_argument("--db", default=str(get_state_db_path()), help="Path to state_store SQLite db (default: state/tracker_events.db)")
     parser.add_argument("--resolve", action="store_true", help="Fix drift by writing the authoritative value to the non-authoritative side (opt-in; default is detect+report only)")
     parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON instead of human text")
     args = parser.parse_args(argv)