wizard-central-toolkit 0.2.0__py3-none-any.whl

wiz_central_toolkit/debugwiz/debug_wizard.py

@@ -0,0 +1,364 @@
+"""debug-wizard brain — the diagnosis oracle. Never mutates; only proposes."""
+
+import ast
+import builtins
+import datetime as dt
+import json
+import re
+from collections import Counter
+from pathlib import Path
+
+HOME = Path.home()
+BANK = HOME / ".debug-wizard"
+IGNORE_LIST = BANK / "ignored.json"
+
+DEBUG_LAW = """DEBUG LAW (Debug Wizard, the diagnosis oracle)
+1. Diagnose freely: autopsy tracebacks, classify errors, count hotspots, report facts.
+2. Never mutate: no writes, no patches, no fixes applied — only proposals staged for the Write Wizard.
+3. Consent wall: any fix suggestion goes through write_wizard propose; Governor consents.
+4. Plain verdicts: [OK]/[FAIL]/out of scope, exit 0/1/2, no tracebacks.
+5. Truth first: run python_wizard check or python -m py_compile before analysis.
+6. Ignore list amends only by Governor decree; protected paths stay ignored.
+"""
+
+def _ensure_bank():
+    BANK.mkdir(parents=True, exist_ok=True)
+    if not IGNORE_LIST.exists():
+        IGNORE_LIST.write_text("[]")
+
+def load_ignored() -> list[str]:
+    _ensure_bank()
+    try:
+        return json.loads(IGNORE_LIST.read_text())
+    except (json.JSONDecodeError, OSError):
+        return []
+
+def add_ignore(path_str: str) -> dict:
+    target = Path(path_str).expanduser().resolve()
+    ign = load_ignored()
+    if str(target) in ign:
+        return {"ok": False, "error": f"already ignored: {target}"}
+    ign.append(str(target))
+    IGNORE_LIST.write_text(json.dumps(ign, indent=2))
+    return {"ok": True, "ignored": str(target)}
+
+def remove_ignore(path_str: str) -> dict:
+    target = Path(path_str).expanduser().resolve()
+    ign = load_ignored()
+    if str(target) not in ign:
+        return {"ok": False, "error": f"not ignored: {target}"}
+    ign.remove(str(target))
+    IGNORE_LIST.write_text(json.dumps(ign, indent=2))
+    return {"ok": True, "unignored": str(target)}
+
+def _walk_py_files(root: Path):
+    root = Path(root)
+    if not root.exists():
+        return
+    if root.is_file() and root.suffix == ".py":
+        yield root
+        return
+
+    ignored = [Path(p) for p in load_ignored()]
+    for p in sorted(root.rglob("*.py")):
+        if any(part in {".venv", ".git", "__pycache__"} for part in p.parts):
+            continue
+        resolved = p.resolve()
+        if any(resolved == item or item in resolved.parents for item in ignored):
+            continue
+        yield p
+
+def _compile_errors(file: Path) -> list[dict]:
+    """Return list of compilation errors without tracebacks."""
+    errors = []
+    try:
+        with file.open("r", encoding="utf-8", errors="replace") as f:
+            source = f.read()
+        ast.parse(source)
+    except SyntaxError as e:
+        errors.append({
+            "line": e.lineno or 1,
+            "type": "SyntaxError",
+            "message": e.msg or "invalid syntax",
+            "col": e.offset or 0,
+            "snippet": e.text.strip() if e.text else ""
+        })
+    except Exception as e:
+        errors.append({"line": 0, "type": type(e).__name__, "message": str(e)})
+    return errors
+
+def _classify(errors: list[dict]) -> dict[str, int]:
+    counts = Counter(e["type"] for e in errors)
+    return dict(counts)
+
+_MODULE_DUNDERS = frozenset(
+    {"__file__", "__name__", "__doc__", "__package__", "__spec__",
+     "__loader__", "__builtins__", "__path__", "__cached__"}
+)
+
+
+def _missing_imports(file: Path) -> list[str]:
+    """Names read but never bound anywhere in the file (likely missing imports)."""
+    try:
+        tree = ast.parse(file.read_text(encoding="utf-8", errors="replace"))
+    except (SyntaxError, ValueError, OSError):
+        return []
+    bound: set[str] = set(dir(builtins)) | _MODULE_DUNDERS
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and any(a.name == "*" for a in node.names):
+            return []  # star import: cannot know what it defines
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                bound.add(alias.asname or alias.name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                bound.add(alias.asname or alias.name)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            bound.add(node.name)
+        elif isinstance(node, ast.arg):
+            bound.add(node.arg)
+        elif isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)):
+            bound.add(node.id)
+        elif isinstance(node, ast.ExceptHandler) and node.name:
+            bound.add(node.name)
+        elif isinstance(node, (ast.Global, ast.Nonlocal)):
+            bound.update(node.names)
+        elif isinstance(node, (ast.MatchAs, ast.MatchStar)) and node.name:
+            bound.add(node.name)
+        elif isinstance(node, ast.MatchMapping) and node.rest:
+            bound.add(node.rest)
+        elif type(node).__name__ in ("TypeVar", "ParamSpec", "TypeVarTuple"):
+            bound.add(str(getattr(node, "name", "")))
+    used = {
+        node.id
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load)
+    }
+    return sorted(used - bound)
+
+
+def _signature_issues(file: Path) -> list[dict]:
+    """Detect call vs definition mismatches."""
+    issues = []
+    try:
+        tree = ast.parse(file.read_text(encoding="utf-8", errors="replace"))
+    except SyntaxError:
+        return [{"line": 0, "type": "SyntaxError", "message": "file unparseable"}]
+    
+    defs = {node.name: {"args": len(node.args.args), "lineno": node.lineno}
+            for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)}
+    calls = [(node.func.id, len(node.args), node.lineno)
+             for node in ast.walk(tree) if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)]
+    
+    for func_name, call_args, lineno in calls:
+        if func_name in defs and defs[func_name]["args"] != call_args:
+            issues.append({"line": lineno, "type": "SignatureMismatch",
+                          "message": f"{func_name} def={defs[func_name]['args']} args, call={call_args}"})
+    return issues
+
+_TB_FRAME = re.compile(
+    r'^\s*File "(?P<file>.+)", line (?P<line>\d+)(?:, in (?P<func>.*))?$')
+_TB_EXC = re.compile(
+    r"^(?P<type>[A-Za-z_][\w.]*)\s*(?::\s*(?P<msg>.*))?$")
+
+
+def _parse_traceback(text: str) -> dict | None:
+    """Parse a real Python traceback pasted/saved in a file, or None.
+
+    A traceback is its header line, at least one File frame, and a
+    final exception line. Anything else is not a traceback and the
+    caller falls back to the compile check.
+    """
+    lines = text.splitlines()
+    if not any(l.strip().startswith("Traceback (most recent call last)")
+               for l in lines):
+        return None
+    frames = []
+    for l in lines:
+        m = _TB_FRAME.match(l)
+        if m:
+            frames.append({"file": m.group("file"),
+                           "line": int(m.group("line")),
+                           "func": (m.group("func") or "").strip()})
+    exc = None
+    for l in reversed(lines):
+        s = l.strip()
+        if not s or s.startswith("File ") or s.startswith("Traceback"):
+            continue
+        m = _TB_EXC.match(s)
+        if m and (m.group("type")[0].isupper() or "." in m.group("type")):
+            exc = {"type": m.group("type"), "message": m.group("msg") or ""}
+        break  # only the last content line can be the exception line
+    if not frames or exc is None:
+        return None
+    return {"frames": frames, "type": exc["type"], "message": exc["message"]}
+
+
+def _read_text(file: Path) -> str:
+    try:
+        return Path(file).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _frame_home(file: str) -> str:
+    """'library' for stdlib / site-packages frames, else 'project'."""
+    import sysconfig
+    f = file.replace("\\", "/")
+    roots = [sysconfig.get_path("stdlib"), sysconfig.get_path("purelib"),
+             sysconfig.get_path("platlib")]
+    if "/site-packages/" in f:
+        return "library"
+    if any(r and f.startswith(r.replace("\\", "/")) for r in roots):
+        return "library"
+    return "project"
+
+
+def stack_digest(text: str) -> dict | None:
+    """Digest a saved traceback: exception, frame chain, deepest frames.
+
+    Returns None when the text is not a traceback. The deepest
+    project frame is the last frame outside the library — where the
+    Governor's own code was standing when it fell. A frame repeated
+    three or more times is flagged as suspected recursion.
+    """
+    tb = _parse_traceback(text)
+    if tb is None:
+        return None
+    frames = [{**fr, "home": _frame_home(fr["file"])} for fr in tb["frames"]]
+    counts = Counter((f["file"], f["line"], f["func"]) for f in frames)
+    repeated = [(k, c) for k, c in counts.most_common() if c >= 3]
+    project = [f for f in frames if f["home"] == "project"]
+    return {"type": tb["type"], "message": tb["message"],
+            "frames": frames,
+            "deepest": frames[-1],
+            "deepest_project": project[-1] if project else None,
+            "repeated": repeated}
+
+
+def trace(file: Path) -> dict:
+    """Autopsy one file: a saved traceback if it is one, else compilation errors."""
+    tb = _parse_traceback(_read_text(file))
+    if tb is not None:
+        last = tb["frames"][-1]
+        return {"file": str(file), "ok": False, "traceback": tb,
+                "errors": [{"line": last["line"], "type": tb["type"],
+                            "message": tb["message"], "col": 0, "snippet": ""}]}
+    errors = _compile_errors(file)
+    return {"file": str(file), "errors": errors, "ok": len(errors) == 0}
+
+def classify_file(file: Path) -> dict:
+    """Error type breakdown."""
+    tb = _parse_traceback(_read_text(file))
+    if tb is not None:
+        return {"file": str(file), "classification": {tb["type"]: 1}, "total": 1}
+    errors = _compile_errors(file)
+    return {"file": str(file), "classification": _classify(errors), "total": len(errors)}
+
+def locate(root: Path, pattern: str) -> list[str]:
+    """Find files whose contents contain the pattern, or whose errors match it."""
+    hits = []
+    for f in _walk_py_files(root):
+        if pattern in _read_text(f):
+            hits.append(str(f))
+            continue
+        err = trace(f)
+        for e in err.get("errors", []):
+            if pattern.lower() in e["message"].lower() or pattern in e["type"]:
+                hits.append(str(f))
+                break
+    return hits
+
+def count_dir(root: Path) -> dict:
+    """Errors by category."""
+    all_errors = []
+    for f in _walk_py_files(root):
+        all_errors.extend(_compile_errors(f))
+    return {"totals": _classify(all_errors), "files_checked": sum(1 for _ in _walk_py_files(root))}
+
+def hotspot(root: Path) -> list[tuple[str, int]]:
+    """Files with most errors, ranked."""
+    scores = []
+    for f in _walk_py_files(root):
+        err_count = len(_compile_errors(f))
+        if err_count > 0:
+            scores.append((str(f), err_count))
+    return sorted(scores, key=lambda x: -x[1])[:10]
+
+def timeline(root: Path) -> list[dict]:
+    """Error frequency by modification time."""
+    data = []
+    for f in _walk_py_files(root):
+        err_count = len(_compile_errors(f))
+        if err_count > 0:
+            data.append({
+                "file": str(f),
+                "errors": err_count,
+                "mtime": f.stat().st_mtime
+            })
+    data.sort(key=lambda x: -x["mtime"])
+    return data
+
+def imports(file: Path) -> dict:
+    """Missing import detection."""
+    missing = _missing_imports(file)
+    return {"file": str(file), "likely_missing": missing}
+
+def names(file: Path) -> list[str]:
+    """Undefined names."""
+    return _missing_imports(file)
+
+def signatures(file: Path) -> list[dict]:
+    """Function signature issues."""
+    return _signature_issues(file)
+
+def suggest_fix(file: Path) -> str:
+    """Human-readable fix suggestion (no AI — heuristic)."""
+    tb = _parse_traceback(_read_text(file))
+    if tb is not None:
+        last = tb["frames"][-1]
+        lines = [f"[TRACEBACK] {file}"]
+        for fr in tb["frames"]:
+            lines.append(f"  File \"{fr['file']}\", line {fr['line']}, in {fr['func']}")
+        lines.append(f"  {tb['type']}: {tb['message']}" if tb["message"]
+                     else f"  {tb['type']}")
+        lines.append(f"raised at {last['file']}:{last['line']} in {last['func']} "
+                     f"(innermost of {len(tb['frames'])} frame(s)) — start there.")
+        return "\n".join(lines)
+    errs = trace(file)
+    if errs["ok"]:
+        return f"[OK] {file}: no compilation errors"
+    lines = [f"[ISSUE] {file}"]
+    for e in errs["errors"][:5]:
+        lines.append(f"  Line {e['line']}: {e['type']} — {e['message']}")
+    if errs["errors"][5:]:
+        lines.append(f"  ... and {len(errs['errors']) - 5} more errors")
+    return "\n".join(lines)
+
+def audit_dir(root: Path) -> dict:
+    """Full error census."""
+    files = list(_walk_py_files(root))
+    healthy = 0
+    unhealthy = 0
+    total_errors = 0
+    for f in files:
+        err = trace(f)
+        if err["ok"]:
+            healthy += 1
+        else:
+            unhealthy += 1
+            total_errors += len(err["errors"])
+    return {"healthy": healthy, "unhealthy": unhealthy, "total_errors": total_errors,
+            "files_checked": len(files), "health_pct": round(healthy / max(len(files), 1) * 100, 1)}
+
+def report_json(root: Path) -> str:
+    """JSON report for CI/CD."""
+    data = {"timestamp": dt.datetime.now().isoformat(timespec="seconds"), "root": str(root),
+            "audit": audit_dir(root),
+            "hotspots": [{"file": f, "errors": e} for f, e in hotspot(root)]}
+    return json.dumps(data, indent=2)
+
+def stats_fleet() -> dict:
+    """Fleet statistics derivable anywhere: the current directory's error census."""
+    root = Path.cwd()
+    return {str(root): audit_dir(root)}

wiz_central_toolkit/diffwiz/__main__.py

@@ -0,0 +1,21 @@
+"""Entry point for wiz dispatch."""
+import sys
+from .lib import cli as internal_cli
+
+# Wrap main() to accept argv (wiz dispatcher calls main(args))
+def main(argv=None):
+    # Save original sys.argv
+    old_argv = sys.argv
+    # Replace with provided argv (or empty list)
+    if argv is not None:
+        sys.argv = [sys.argv[0]] + list(argv)
+    try:
+        return internal_cli.main()
+    finally:
+        sys.argv = old_argv
+
+# Also expose for module-level access
+__all__ = ['main']
+
+if __name__ == "__main__":
+    sys.exit(main())

wiz_central_toolkit/diffwiz/cli.py

@@ -0,0 +1,134 @@
+"""diff-wizard CLI front-end."""
+import sys
+from pathlib import Path
+from .lib.diff_wizard import DiffWizard
+
+def main() -> int:
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help", "help"):
+        print("Diff Wizard — standalone change-truth doctor")
+        print("usage: diffwiz <command> [args]")
+        print("  files <a> <b>             unified diff of two files")
+        print("  dirs <a> <b>              compare directory trees")
+        print("  context <N> <a> <b>       unified diff with N context lines")
+        print("  summary <a> <b>           diff statistics without full output")
+        print("  word <a> <b>              word-level diff")
+        print("  same <a> <b>              exit 0 if identical, 1 if different (silent)")
+        print("  reverse <a> <b>           diff b -> a (swap sides)")
+        return 0
+
+    wiz = DiffWizard()
+
+    # --- existing commands ---
+    if args[0] == "files":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        text = wiz.diff_files(a, b)
+        if not text:
+            print("[OK] files identical")
+            return 0
+        print(text)
+        print("[FAIL] files differ")
+        return 1
+    if args[0] == "dirs":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        da, db = Path(args[1]), Path(args[2])
+        for p in (da, db):
+            if not p.is_dir():
+                print(f"[FAIL] not a directory: {p}")
+                return 1
+        r = wiz.diff_dirs(da, db)
+        count = len(r["only_a"]) + len(r["only_b"]) + len(r["differing"])
+        for rel in r["only_a"]:
+            print(f"only in {args[1]}: {rel}")
+        for rel in r["only_b"]:
+            print(f"only in {args[2]}: {rel}")
+        for rel in r["differing"]:
+            print(f"differing: {rel}")
+        if count == 0:
+            print("[OK] trees identical")
+            return 0
+        print(f"[FAIL] {count} differences")
+        return 1
+
+    # --- new commands ---
+    if args[0] == "context":
+        if len(args) < 4:
+            print("out of scope - context requires N a b")
+            return 2
+        n = int(args[1])
+        a, b = Path(args[2]), Path(args[3])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        text = wiz.diff_files_context(a, b, n)
+        if not text:
+            print("[OK] files identical")
+            return 0
+        print(text)
+        print("[FAIL] files differ")
+        return 1
+    if args[0] == "summary":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        r = wiz.diff_summary(a, b)
+        if r["identical"]:
+            print("[OK] identical")
+            return 0
+        print(f"added={r['added_lines']} removed={r['removed_lines']} hunks={r['hunks']}")
+        return 1
+    if args[0] == "word":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        print(wiz.diff_word_level(a, b))
+        return 0
+    if args[0] == "same":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        return 0 if wiz.files_identical(a, b) else 1
+    if args[0] == "reverse":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        text = wiz.diff_files_reverse(a, b)
+        if not text:
+            print("[OK] files identical")
+            return 0
+        print(text)
+        print("[FAIL] files differ")
+        return 1
+
+    print("out of scope")
+    return 2

wiz_central_toolkit/diffwiz/lib/__init__.py

@@ -0,0 +1 @@
+# wizard package init

wiz_central_toolkit/diffwiz/lib/cli.py

@@ -0,0 +1,144 @@
+"""diff-wizard CLI front-end."""
+import sys
+from pathlib import Path
+from .diff_wizard import DiffWizard
+
+
+def main(argv=None) -> int:
+    args = sys.argv[1:] if argv is None else list(argv)
+    if not args or args[0] in ("-h", "--help", "help"):
+        print("Diff Wizard — standalone change-truth doctor")
+        print("alias: diffwiz")
+        print("usage: diff_wizard <command> [args]")
+        print("  files <a> <b>             unified diff of two files")
+        print("  dirs <a> <b>              compare directory trees")
+        print("  context <N> <a> <b>       unified diff with N context lines")
+        print("  summary <a> <b>           diff statistics without full output")
+        print("  word <a> <b>              word-level diff")
+        print("  same <a> <b>              exit 0 if identical, 1 if different (silent)")
+        print("  reverse <a> <b>           diff b -> a (swap sides)")
+        return 0
+
+    wiz = DiffWizard()
+
+    # --- existing commands ---
+    if args[0] == "files":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        text = wiz.diff_files(a, b)
+        if not text:
+            print("[OK] files identical")
+            return 0
+        print(text)
+        print("[FAIL] files differ")
+        return 1
+
+    if args[0] == "dirs":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        da, db = Path(args[1]), Path(args[2])
+        for p in (da, db):
+            if not p.is_dir():
+                print(f"[FAIL] not a directory: {p}")
+                return 1
+        r = wiz.diff_dirs(da, db)
+        count = len(r["only_a"]) + len(r["only_b"]) + len(r["differing"])
+        for rel in r["only_a"]:
+            print(f"only in {args[1]}: {rel}")
+        for rel in r["only_b"]:
+            print(f"only in {args[2]}: {rel}")
+        for rel in r["differing"]:
+            print(f"differing: {rel}")
+        if count == 0:
+            print("[OK] trees identical")
+            return 0
+        print(f"[FAIL] {count} differences")
+        return 1
+
+    # --- new commands ---
+    if args[0] == "context":
+        if len(args) < 4:
+            print("out of scope - context requires N a b")
+            return 2
+        n = int(args[1])
+        a, b = Path(args[2]), Path(args[3])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        text = wiz.diff_files_context(a, b, n)
+        if not text:
+            print("[OK] files identical")
+            return 0
+        print(text)
+        print("[FAIL] files differ")
+        return 1
+
+    if args[0] == "summary":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+            if not p.is_file():
+                print(f"[FAIL] not a file: {p}")
+                return 1
+        r = wiz.diff_summary(a, b)
+        if r["identical"]:
+            print("[OK] identical")
+            return 0
+        print(f"added={r['added_lines']} removed={r['removed_lines']} hunks={r['hunks']}")
+        return 1
+
+    if args[0] == "word":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        print(wiz.diff_word_level(a, b))
+        return 0
+
+    if args[0] == "same":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        return 0 if wiz.files_identical(a, b) else 1
+
+    if args[0] == "reverse":
+        if len(args) < 3:
+            print("out of scope")
+            return 2
+        a, b = Path(args[1]), Path(args[2])
+        for p in (a, b):
+            if not p.exists():
+                print(f"[FAIL] not found: {p}")
+                return 1
+        text = wiz.diff_files_reverse(a, b)
+        if not text:
+            print("[OK] files identical")
+            return 0
+        print(text)
+        print("[FAIL] files differ")
+        return 1
+
+    print("out of scope")
+    return 2