gisel-ab 0.9.0__py3-none-any.whl

gisel_ab/__init__.py

@@ -0,0 +1,120 @@
+"""gisel-ab: an A/B workbench around LLVM GlobalISel legalizer rules.
+
+The package has one job: answer "does the legalizer this repository replaced
+behave like the one it came from?"  Everything a caller needs to locate lives
+here, so no module has to guess its depth in the tree.
+
+    PKG       this package (code, data, cpp)
+    AB_ROOT   the checkout that contains ``src/`` and ``scripts/``
+    DATA      target registry, contracts, suite, domain  (package data)
+    CPP       query-runner C++ sources                    (package data)
+    SCRIPTS   the shell entry points                      (checkout only)
+    EVIDENCE  the frozen evidence tree                    (checkout only)
+
+``DATA`` and ``CPP`` travel with an installed wheel; ``SCRIPTS`` and
+``EVIDENCE`` do not, and the commands that need them say so instead of
+raising a FileNotFoundError three levels down.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+PKG = Path(__file__).resolve().parent
+SRC = PKG.parent
+AB_ROOT = SRC.parent
+DATA = PKG / "data"
+CPP = PKG / "cpp"
+SCRIPTS = AB_ROOT / "scripts"
+EVIDENCE = AB_ROOT / "evidence"
+
+
+def _gisel_package_dir() -> Path | None:
+    """The installed ``gisel`` package directory, when it is importable."""
+    try:
+        spec = importlib.util.find_spec("gisel")
+    except (ImportError, ValueError):
+        return None
+    if spec is None or not spec.submodule_search_locations:
+        return None
+    return Path(next(iter(spec.submodule_search_locations))).resolve()
+
+
+def gisel_src(explicit=None) -> Path:
+    """A directory that makes ``import gisel`` work.
+
+    ``GISEL_SRC`` wins; then a sibling checkout; then the installed package,
+    whose parent is the directory that belongs on ``sys.path``.  A path is
+    returned even when nothing is found, so the caller's error names the
+    place it looked.
+    """
+    value = explicit or os.environ.get("GISEL_SRC")
+    if value:
+        return Path(value).expanduser().resolve()
+    sibling = (AB_ROOT.parent / "gisel").resolve()
+    if (sibling / "gisel" / "__init__.py").is_file():
+        return sibling
+    package = _gisel_package_dir()
+    if package is not None:
+        return package.parent
+    return sibling
+
+
+def gisel_package() -> Path | None:
+    """The ``gisel`` package directory, from a checkout or an install."""
+    root = gisel_src()
+    for candidate in (root / "gisel", root):
+        if (candidate / "__init__.py").is_file():
+            return candidate
+    return _gisel_package_dir()
+
+
+def gisel_data(name: str) -> Path | None:
+    """The ``corpus``/``cases`` directory, checkout first, wheel second.
+
+    The wheel ships byte-identical copies under ``gisel/data``; the checkout
+    keeps the canonical copies under ``tests/``.
+    """
+    package = gisel_package()
+    roots = [package.parent, package] if package is not None else [gisel_src()]
+    for root in roots:
+        for candidate in (root / "tests" / name,
+                          root / "gisel" / "data" / name,
+                          root / "data" / name):
+            if candidate.is_dir():
+                return candidate.resolve()
+    return None
+
+
+def gisel_path_entry() -> str:
+    """The ``sys.path`` entry that makes ``import gisel`` work."""
+    return str(gisel_src())
+
+
+def ensure_gisel_on_path() -> Path:
+    path = gisel_src()
+    entry = str(path)
+    if entry not in sys.path:
+        sys.path.insert(0, entry)
+    return path
+
+
+def child_env(env=None) -> dict:
+    """A copy of ``env`` (default: os.environ) that children can import from.
+
+    Subprocesses are started as ``python3 -m gisel_ab.<verb>``; they need
+    ``SRC`` on ``PYTHONPATH`` and gisel on it too unless it is installed.
+    """
+    out = dict(os.environ if env is None else env)
+    parts = [str(SRC)]
+    gisel = gisel_path_entry()
+    if Path(gisel).is_dir():
+        parts.append(gisel)
+    current = out.get("PYTHONPATH")
+    if current:
+        parts.extend(part for part in current.split(os.pathsep) if part)
+    out["PYTHONPATH"] = os.pathsep.join(dict.fromkeys(parts))
+    return out

gisel_ab/__main__.py

@@ -0,0 +1,8 @@
+"""``python3 -m gisel_ab`` is the installed entry point (needs ``src`` on PYTHONPATH)."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

gisel_ab/baseline.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Record the facts a remediation run is measured against.
+
+    baseline.py [--out data/baseline-YYYY-MM-DD.json]
+
+The file is deliberately boring: repository heads, corpus/artifact/feature
+hashes, the target registry, and the numbers already pinned by EVIDENCE.json.
+It does not run a build and it does not change behavior.  Later waves compare
+their output with this snapshot instead of trusting a document's memory.
+
+Exit codes: 0 = written; 2 = a required input is missing or unreadable.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+
+from gisel_ab import paths
+from gisel_ab import targets as target_specs
+
+PKG = Path(__file__).resolve().parent
+AB = PKG.parents[1]
+DATA = PKG / "data"
+GISEL = Path(__import__("os").environ.get("GISEL_SRC", AB.parent / "gisel"))
+UPSTREAM = paths.sibling(AB.parent, "UPSTREAM_SOURCE",
+                         "gisel-anchor", "upstream-source")
+
+
+def sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def repo_state(path: Path) -> dict:
+    def git(*args: str) -> str:
+        proc = subprocess.run(
+            ["git", "-C", str(path), *args],
+            capture_output=True, text=True)
+        if proc.returncode != 0:
+            raise SystemExit("git %s failed in %s: %s"
+                             % (" ".join(args), path, proc.stderr.strip()))
+        return proc.stdout.strip()
+
+    return {
+        "head": git("rev-parse", "HEAD"),
+        "branch": git("rev-parse", "--abbrev-ref", "HEAD"),
+        "dirty": bool(git("status", "--porcelain", "--untracked-files=no")),
+    }
+
+
+def hashes(root: Path, pattern: str) -> dict:
+    return {path.relative_to(root).as_posix(): sha256(path)
+            for path in sorted(root.glob(pattern)) if path.is_file()}
+
+
+def evidence_summary(path: Path) -> dict:
+    manifest = json.loads(path.read_text())
+    entries = {}
+    for entry in manifest.get("entries", []):
+        expect = entry.get("expect", {})
+        entries[entry["id"]] = {
+            "direction": entry.get("direction"),
+            "target": entry.get("target"),
+            "expect": {key: expect[key] for key in sorted(expect)},
+            "snapshot": entry.get("snapshot"),
+        }
+    return {
+        "sha256": sha256(path),
+        "schema": manifest.get("schema"),
+        "generated": manifest.get("generated"),
+        "entries": entries,
+    }
+
+
+def target_registry(root: Path) -> dict:
+    out = {}
+    for path in sorted(target_specs.TARGET_DIR.glob("*.json")):
+        data = json.loads(path.read_text())
+        out[path.stem] = {
+            "sha256": sha256(path),
+            "strategy": data.get("strategy"),
+            "query_count": data.get("query_count"),
+        }
+    return out
+
+
+def build() -> dict:
+    for path in (GISEL, UPSTREAM, AB):
+        if not path.is_dir():
+            raise SystemExit("missing checkout: %s" % path)
+    return {
+        "snapshot": "pre-remediation",
+        "repos": {
+            "gisel": repo_state(GISEL),
+            "ab": repo_state(AB),
+            "upstream-source": repo_state(UPSTREAM),
+        },
+        "gisel": {
+            "corpora": hashes(GISEL, "tests/corpus/*.gisel"),
+            "artifacts": hashes(GISEL, "tests/artifacts/*.inc"),
+            "features": hashes(GISEL, "tests/cases/*features*.json"),
+            "domain_queries": hashes(GISEL, "tests/cases/*domain*.jsonl"),
+        },
+        "ab": {
+            "evidence": evidence_summary(AB / "EVIDENCE.json"),
+            "targets": target_registry(AB),
+            "contracts": hashes(DATA, "*-contract.json"),
+            "gate_scripts": {
+                name: sha256(AB / name)
+                for name in (
+                    "src/gisel_ab/l0/diff.py",
+                    "src/gisel_ab/l0/queries.py",
+                    "scripts/verify-evidence.sh",
+                    "scripts/e2e/run-u-end-to-end.sh",
+                    "scripts/negative/run-g-negative.sh",
+                    "scripts/negative/run-predicate-negative.sh",
+                )
+            },
+        },
+        "upstream_source": {
+            "pin_manifest": hashes(UPSTREAM, "pin/*.json"),
+            "oracle_queries": hashes(UPSTREAM, "oracle/*/*/queries.jsonl*"),
+        },
+    }
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="baseline")
+    parser.add_argument("--out", type=Path, default=None)
+    args = parser.parse_args(argv)
+    out = args.out or (DATA / ("baseline-%s.json" % date.today()))
+    data = build()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(data, indent=1, sort_keys=True) + "\n")
+    print(str(out))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gisel_ab/bugreport.py

@@ -0,0 +1,113 @@
+"""`gisel-ab bug-report`: one JSON file with the facts a reader would ask for.
+
+    gisel-ab bug-report                 # stdout
+    gisel-ab bug-report --out bug.json  # write a file
+
+It collects versions, the cohort record, the doctor verdict and the last
+run's ledger line.  It deliberately does not collect the evidence tree: a bug
+report is small enough to paste into an issue, and the evidence is fetchable
+from the cohort release.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from gisel_ab import doctor
+
+SCHEMA = 1
+
+
+def _installed(name: str):
+    try:
+        import importlib.metadata as metadata
+        return metadata.version(name)
+    except Exception:
+        return None
+
+
+def _module_version(name: str):
+    try:
+        module = __import__(name)
+    except Exception:
+        return None
+    return getattr(module, "__version__", None)
+
+
+def _release() -> dict:
+    path = doctor.AB_ROOT / "RELEASE.json"
+    try:
+        doc = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {}
+    keep = ("cohort", "version", "repos", "generated_at")
+    return {key: doc[key] for key in keep if key in doc}
+
+
+def _last_run() -> dict | None:
+    ledgers = sorted((doctor.AB_ROOT / ".ab").glob("*/ledger.jsonl"))
+    if not ledgers:
+        return None
+    path = ledgers[-1]
+    lines = path.read_text().strip().splitlines()
+    if not lines:
+        return None
+    try:
+        record = json.loads(lines[-1])
+    except ValueError:
+        return {"target": path.parent.name, "ledger": str(path),
+                "error": "the last line is not JSON"}
+    return {"target": path.parent.name, "ledger": str(path), "record": record}
+
+
+def report(tree=None, build=None) -> dict:
+    from gisel_ab.cli import _version
+    checks = doctor.checks(tree, build)
+    return {
+        "schema": SCHEMA,
+        "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "python": sys.version.split()[0],
+        "platform": platform.platform(),
+        "versions": {
+            "gisel-ab": _version(),
+            "gisel-anchor": _module_version("gisel_anchor"),
+            "gisel": _module_version("gisel"),
+            "installed.gisel-ab": _installed("gisel-ab"),
+            "installed.gisel-anchor": _installed("gisel-anchor"),
+            "installed.gisel": _installed("gisel"),
+        },
+        "cohort": _release(),
+        "doctor": {"ok": not any(c.status == doctor.FAIL for c in checks),
+                   "checks": [c.as_dict() for c in checks]},
+        "last_run": _last_run(),
+    }
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="gisel-ab bug-report",
+        description="collect versions, the cohort record and the doctor verdict "
+                    "into one JSON file (no evidence tree)")
+    ap.add_argument("--out", help="write here instead of stdout")
+    ap.add_argument("--tree", help="LLVM checkout (default: configured)")
+    ap.add_argument("--build", help="ninja build (default: configured)")
+    args = ap.parse_args(argv)
+    text = json.dumps(report(args.tree, args.build), indent=2,
+                      sort_keys=True) + "\n"
+    if args.out:
+        path = Path(args.out).expanduser()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text)
+        print("wrote %s" % path)
+        return 0
+    print(text, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gisel_ab/cli.py

@@ -0,0 +1,150 @@
+"""One verb table for the workbench: ``ab.py <verb> ...``.
+
+Before this module each tool was its own script with its own parser, and the
+documentation had to name six different entry points.  There is still one
+implementation per verb; this module only routes.  Imports are lazy so
+``--help`` works in an environment without LLVM, gisel, or the evidence tree.
+
+Verbs that need a checkout rather than an install say so in their own error
+message; nothing here reads the tree.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+import sys
+from pathlib import Path
+
+# verb -> (module, callable, prepend the verb to argv)
+#
+# ``run``/``mir``/``verify`` share one parser in ``l0/run.py``: the harness
+# builds, answers and diffs in one process, so they must stay in one module.
+VERBS = {
+    "doctor": (("gisel_ab.doctor", "main", False),
+               "check tree/build/gisel/state before a run (read-only)"),
+    "bug-report": (("gisel_ab.bugreport", "main", False),
+                   "collect versions, cohort and doctor into one JSON"),
+    "setup": (("gisel_ab.setup", "main", False),
+              "record the LLVM tree/build/evidence paths (no export)"),
+    "run": (("gisel_ab.l0.run", "main", True),
+            "build both sides, answer, diff, restore"),
+    "mir": (("gisel_ab.l0.run", "main", True),
+            "L2: answerless queries -> MIR -> replay both libraries"),
+    "verify": (("gisel_ab.l0.run", "main", True),
+               "check the build is back on the baseline library"),
+    "diff": (("gisel_ab.l0.diff", "main", False),
+             "compare two answer files (action or full)"),
+    "l3": (("gisel_ab.l3", "main", False),
+           "run check-llvm twice and compare it test by test"),
+    "suite": (("gisel_ab.suite", "main", False),
+              "check/refresh the per-target answer snapshots"),
+    "vertical": (("gisel_ab.vertical", "main", False),
+                 "run or verify one target's whole slice"),
+    "cohort": (("gisel_ab.cohort", "main", False),
+               "plan, check, tag and verify a frozen cohort"),
+    "evidence": (("gisel_ab.evidence", "main", False),
+                 "verify EVIDENCE.json against live or frozen artifacts"),
+    "plan": (("gisel_ab.domain_plan", "main", True),
+             "print one target's domain plan (no build)"),
+}
+
+# Not in the front page but still reachable: they are the internals the ten
+# verbs call, and keeping them addressable is how a failure gets reproduced.
+INTERNALS = {
+    "attribute": ("gisel_ab.l0.attribute", "main"),
+    "closure": ("gisel_ab.l0.closure", "main"),
+    "queries": ("gisel_ab.l0.queries", "main"),
+    "swap": ("gisel_ab.l0.swap", "main"),
+    "inject": ("gisel_ab.l0.inject_predicate", "main"),
+    "baseline": ("gisel_ab.baseline", "main"),
+    "replay-frozen": ("gisel_ab.replay_frozen", "main"),
+    "refresh-counts": ("gisel_ab.refresh_counts", "main"),
+    "mir-from-query": ("gisel_ab.mir.from_query", "main"),
+    "mir-replay": ("gisel_ab.mir.replay", "main"),
+    "mir-config-check": ("gisel_ab.mir.config_check", "main"),
+}
+
+
+def _version() -> str:
+    """The checkout's version when there is one, else the installed metadata.
+
+    The source wins so `python3 ab.py --version` reflects the tree being
+    edited, even when a stale editable install is still on the path.
+    """
+    pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    try:
+        text = pyproject.read_text()
+    except OSError:
+        text = ""
+    match = re.search(r'^version\s*=\s*"([^"]+)"', text, re.M)
+    if match:
+        return match.group(1)
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version("gisel-ab")
+        except PackageNotFoundError:
+            pass
+    except ImportError:
+        pass
+    return "unknown"
+
+
+# What a verb needs before it can run; the help groups by this so a reader
+# can start with the offline half.
+NEEDS_BUILD = {"run", "mir", "verify", "l3", "vertical"}
+NEEDS_TREE = {"cohort"}
+
+
+def _usage() -> str:
+    width = max(len(name) for name in VERBS)
+    groups = (
+        ("without LLVM", [name for name in VERBS
+                          if name not in NEEDS_BUILD | NEEDS_TREE]),
+        ("with an LLVM tree and build", [name for name in VERBS
+                                         if name in NEEDS_BUILD]),
+        ("with a git tree (no build)", [name for name in VERBS
+                                        if name in NEEDS_TREE]),
+    )
+    chunks = []
+    for title, names in groups:
+        chunks.append("  %s:" % title)
+        for name in names:
+            chunks.append("    %-*s  %s" % (width, name, VERBS[name][1]))
+    return (
+        "usage: gisel-ab <verb> [options]\n"
+        "       (checkout: python3 ab.py <verb>)\n"
+        "\n"
+        "verbs (each takes --help; gisel-ab --version):\n"
+        + "\n".join(chunks)
+        + "\n\n"
+        "Internals stay callable for reproduction: %s\n"
+        % ", ".join(sorted(INTERNALS))
+    )
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] in ("-V", "--version"):
+        print("gisel-ab %s" % _version())
+        return 0
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(_usage(), end="")
+        return 0 if argv else 2
+    verb, rest = argv[0], argv[1:]
+    if verb in INTERNALS:
+        module, name = INTERNALS[verb]
+        return getattr(importlib.import_module(module), name)(rest) or 0
+    entry = VERBS.get(verb)
+    if entry is None:
+        print("ab: unknown verb %r\n\n%s" % (verb, _usage()), file=sys.stderr,
+              end="")
+        return 2
+    (module, name, prepend), _ = entry
+    args = [verb, *rest] if prepend else rest
+    return getattr(importlib.import_module(module), name)(args) or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())