bug-age 2.0.0__py3-none-any.whl

bug_age/cli.py

@@ -0,0 +1,265 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+"""bug-age command-line interface.
+
+One command, one subcommand per pipeline stage. Each subcommand reads files, writes one JSON output
+(stdout or `--out`), and logs a one-line summary to stderr. Exit status is 0 on success, 1 on a
+runtime error and 2 on a usage error.
+"""
+import hashlib
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__, bundle, catalog, explorer, mcp, szz
+from ._compat import dumps, get, lines, loads
+
+USAGE = """usage: bug-age [--version | --help]
+       bug-age catalog --repo DIR --path CRATE [--head REV] [--out FILE]
+       bug-age szz --repo DIR --catalog FILE [--window-start YYYY-MM-DD] [--release-tags GLOB] [--out FILE]
+       bug-age sweep --repo DIR --path CRATE --fix SHA --overlay DIR --test CMD
+             [--build CMD] [--start SHA] [--runner docker|local] [--repeats N] [--image IMG]
+             [--time-travel-script FILE|none] [--scratch DIR] [--logs DIR] [--out FILE]
+             [--namespace NAME] [--bucket N (toolchain minor rounding, default 4; 0 = exact)]
+       bug-age probe --repo DIR --path CRATE --commits SHA,SHA,... --overlay DIR --test CMD [same options]
+       bug-age bundle --repo DIR --results DIR --repo-url URL --out DIR [--spike DIR] [--out-of-scope 'STAGE|EVIDENCE|DOES_NOT_PROVE']
+       bug-age explorer [--page FILE] --targets NAME=DIR,NAME=DIR --out DIR   (DIR = a bundle output dir)
+       bug-age mcp --bundles NAME=FILE,NAME=FILE   (read-only MCP server on stdio over bundle.json files)
+       bug-age pipeline TARGET.toml [--fresh] [--skip-feasibility]   (every stage for one target)
+       bug-age dockerfile   (print the Method B image's Dockerfile: bug-age dockerfile | docker build -t bug-age-spike:4 -)"""
+
+WARN_BYTES = 8 * 1024 * 1024
+MAX_BYTES = 16 * 1024 * 1024
+
+
+class Failure(Exception):
+    """A runtime error: printed as `bug-age: <message>`, exit status 1."""
+
+
+def flags(args):
+    """`--key value` pairs as a dict; anything else is an error."""
+    out, it = {}, iter(args)
+    for k in it:
+        if not k.startswith("--"):
+            raise Failure(f"unexpected argument '{k}'")
+        try:
+            out[k[2:]] = next(it)
+        except StopIteration:
+            raise Failure(f"missing value for '{k}'") from None
+    return out
+
+
+def need(f, key):
+    """A required flag's value."""
+    if key not in f:
+        raise Failure(f"missing --{key}")
+    return f[key]
+
+
+def write(path, text):
+    """Write UTF-8 text with LF line ends."""
+    try:
+        with open(path, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(text)
+    except OSError as exc:
+        raise Failure(f"cannot write {path}: {exc}") from exc
+
+
+def emit(value, out):
+    """Pretty JSON to `out`, or to stdout when no file is given."""
+    text = dumps(value, pretty=True) + "\n"
+    if out is None:
+        sys.stdout.write(text)
+    else:
+        write(out, text)
+
+
+def sha256(text):
+    """Hex SHA-256 of a text's UTF-8 bytes."""
+    return hashlib.sha256(text.encode()).hexdigest()
+
+
+def tool_version(cmd, args):
+    """First line a tool prints for its version, or "unavailable"."""
+    try:
+        out = subprocess.run([cmd, *args], capture_output=True).stdout.decode("utf-8", "replace")
+    except OSError:
+        return "unavailable"
+    first = lines(out)
+    return first[0] if first else ""
+
+
+def command_line():
+    """This run's command line as it may be published (see bundle.public_command)."""
+    return bundle.public_command(sys.argv, os.getcwd(), os.environ.get("HOME", ""))
+
+
+def read_json(path):
+    """A JSON file as a value, with the path in any error."""
+    try:
+        return loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise Failure(f"{path}: {exc}") from exc
+
+
+def cmd_catalog(f):
+    """`catalog`: rule-based list of fix commits."""
+    cat = catalog.build(Path(need(f, "repo")), f.get("head", "HEAD"), need(f, "path"))
+    print(f"catalog: {len(cat['fixes'])} fixes, {len(cat['excluded'])} excluded, {cat['scanned']} commits scanned",
+          file=sys.stderr)
+    emit(cat, f.get("out"))
+
+
+def cmd_szz(f):
+    """`szz`: Method A for every catalogued fix."""
+    repo = Path(need(f, "repo"))
+    cat = read_json(need(f, "catalog"))
+    path = get(cat, "path")
+    if not isinstance(path, str):
+        raise Failure("catalog has no path")
+    window = f.get("window-start")
+    release_tags = f.get("release-tags", "v[0-9]*")
+    fixes = get(cat, "fixes")
+    if not isinstance(fixes, list):
+        raise Failure("catalog has no fixes")
+    bugs = []
+    for e in fixes:
+        def text(k):
+            v = get(e, k)
+            return v if isinstance(v, str) else ""
+        parents = get(e, "parents")
+        entry = {"sha": text("sha"), "date": text("date"), "subject": text("subject"), "rule": text("rule"),
+                 "parents": [p for p in parents if isinstance(p, str)] if isinstance(parents, list) else []}
+        bugs.append(szz.analyze(repo, entry, path, window, release_tags))
+    with_intro = sum(1 for b in bugs if b["lifetime"] is not None)
+    in_window = sum(1 for b in bugs if b["in_window"] is True)
+    print(f"szz: {len(bugs)} fixes, {with_intro} with a nominated introducer, {in_window} in window", file=sys.stderr)
+    summary = {"fixes": len(bugs), "with_introducer": with_intro, "in_window": in_window if window is not None else None,
+               "window_start": window, "release_tags": release_tags}
+    emit({"head": get(cat, "head"), "path": path, "method": "A (SZZ-style, git blame -w on first parent)",
+          "summary": summary, "bugs": bugs}, f.get("out"))
+
+
+def cmd_bundle(f):
+    """`bundle`: the canonical data bundle, its JS wrapper and a receipt."""
+    repo, out = Path(need(f, "repo")), Path(need(f, "out"))
+    spike = Path(f.get("spike", "spike"))
+    oos = None
+    if "out-of-scope" in f:
+        parts = f["out-of-scope"].split("|", 2)
+        if len(parts) != 3:
+            raise Failure("--out-of-scope must be 'STAGE|EVIDENCE|DOES_NOT_PROVE'")
+        oos = tuple(parts)
+    try:
+        built = bundle.build(repo, Path(need(f, "results")), spike, need(f, "repo-url"), oos)
+    except bundle.BundleError as exc:
+        raise Failure(str(exc)) from exc
+    text = dumps(built)
+    js = f"window.BUG_AGE_BUNDLE = {text};\n"
+    if len(js.encode()) > MAX_BYTES:
+        raise Failure(f"size gate failed: bundle.js is {len(js.encode())} bytes (> {MAX_BYTES})")
+    out.mkdir(parents=True, exist_ok=True)
+    write(out / "bundle.json", text)
+    write(out / "bundle.js", js)
+    receipt = {
+        "command": command_line(),
+        "schema_version": bundle.SCHEMA_VERSION,
+        "blameless_gate": "PASS",
+        "size": {"bundle_json_bytes": len(text.encode()), "bundle_js_bytes": len(js.encode()),
+                 "warn_over_8mb": len(js.encode()) > WARN_BYTES},
+        "outputs": {"bundle.json": sha256(text), "bundle.js": sha256(js)},
+        "versions": {"bug-age": __version__, "git": tool_version("git", ["--version"])},
+        "warnings": [],
+    }
+    print(f"bundle: {len(text.encode())} bytes, sha256 {sha256(text)}, blameless gate PASS", file=sys.stderr)
+    emit(receipt, out / "receipt.json")
+
+
+def cmd_explorer(f):
+    """`explorer`: the static explorer page with one data file per target."""
+    # The page shipped with the package unless another is given.
+    page_path = f.get("page", str(Path(__file__).parent / "data" / "explorer.html"))
+    try:
+        page = Path(page_path).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise Failure(f"{page_path}: {exc}") from exc
+    out = Path(need(f, "out"))
+    targets = []
+    for spec in need(f, "targets").split(","):
+        name, eq, d = spec.partition("=")
+        if not eq:
+            raise Failure(f"--targets entry '{spec}' must be NAME=DIR")
+        targets.append((name, read_json(Path(d) / "bundle.json"), read_json(Path(d) / "receipt.json")))
+    try:
+        page, files, total = explorer.assemble(page, targets)
+    except explorer.ExplorerError as exc:
+        raise Failure(str(exc)) from exc
+    (out / "data").mkdir(parents=True, exist_ok=True)
+    write(out / "index.html", page)
+    outputs = {"index.html": sha256(page)}
+    for path, content in files:
+        write(out / path, content)
+        outputs[path] = sha256(content)
+    print(f"explorer: {len(targets)} targets, {total} bytes (gate {explorer.GATE_BYTES}), size gate PASS", file=sys.stderr)
+    emit({"total_bytes": total, "gate_bytes": explorer.GATE_BYTES, "size_gate": "PASS", "outputs": outputs,
+          "bug-age": __version__}, out / "receipt.json")
+
+
+def cmd_mcp(f):
+    """`mcp`: read-only MCP server on stdio."""
+    targets = []
+    for spec in need(f, "bundles").split(","):
+        name, eq, file = spec.partition("=")
+        if not eq:
+            raise Failure(f"--bundles entry '{spec}' must be NAME=FILE")
+        try:
+            targets.append(mcp.Target(name, file))
+        except RuntimeError as exc:
+            raise Failure(str(exc)) from exc
+    print(f"bug-age mcp: serving {len(targets)} target(s) on stdio", file=sys.stderr)
+    stdin = open(sys.stdin.fileno(), encoding="utf-8", closefd=False)
+    stdout = open(sys.stdout.fileno(), "w", encoding="utf-8", newline="\n", closefd=False)
+    mcp.serve(targets, stdin, stdout)
+
+
+def cmd_sweep(f):
+    """`sweep`: Method B for one fix (see bug_age.sweep)."""
+    from .sweep import cmd_sweep as run
+    run(f)
+
+
+def cmd_probe(f):
+    """`probe`: test given commits with a regression overlay (see bug_age.sweep)."""
+    from .sweep import cmd_probe as run
+    run(f)
+
+
+COMMANDS = {"catalog": cmd_catalog, "szz": cmd_szz, "sweep": cmd_sweep, "probe": cmd_probe,
+            "bundle": cmd_bundle, "explorer": cmd_explorer, "mcp": cmd_mcp}
+
+
+def main(argv=None):
+    """Run one subcommand; return the exit status."""
+    args = sys.argv[1:] if argv is None else argv
+    first = args[0] if args else None
+    if first in ("--version", "-V"):
+        print(f"bug-age {__version__}")
+        return 0
+    if first in (None, "--help", "-h"):
+        print(USAGE)
+        return 0
+    if first == "pipeline":
+        from .pipeline import main as pipeline
+        return pipeline(args[1:])
+    if first == "dockerfile":
+        sys.stdout.write((Path(__file__).parent / "data" / "Dockerfile").read_text(encoding="utf-8"))
+        return 0
+    if first not in COMMANDS:
+        print(f"bug-age: unknown argument '{first}'\n{USAGE}", file=sys.stderr)
+        return 2
+    try:
+        COMMANDS[first](flags(args[1:]))
+    except (Failure, RuntimeError) as exc:
+        print(f"bug-age: {exc}", file=sys.stderr)
+        return 1
+    return 0

bug_age/data/Dockerfile

@@ -0,0 +1,14 @@
+# Per-commit build environment for bug-age (spike and `bug-age sweep --runner docker`).
+# rustup and its cargo/rustc proxies live in the image; toolchains (RUSTUP_HOME=/rustup) and the
+# cargo registry (CARGO_HOME=/cargo) live in named volumes so they persist across commits. Before
+# v4, rustup itself lived in the /cargo volume, so deleting that volume broke the image.
+# safe.directory: index repos are staged from the host; ownership must not block cargo's libgit2.
+FROM debian:bookworm-slim
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates curl gcc g++ libc6-dev make cmake pkg-config git clang libclang-dev libssl-dev \
+ && rm -rf /var/lib/apt/lists/*
+RUN curl -sSf https://sh.rustup.rs | CARGO_HOME=/opt/rustup-bin RUSTUP_HOME=/tmp/rustup-init \
+      sh -s -- -y --profile minimal --default-toolchain none --no-modify-path \
+ && rm -rf /tmp/rustup-init
+RUN git config --system --add safe.directory "*"
+ENV RUSTUP_HOME=/rustup CARGO_HOME=/cargo PATH=/opt/rustup-bin/bin:$PATH

bug_age/data/bundle.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bug-age.invalid/schema/bundle-1.0.0.json",
+  "title": "bug-age bundle",
+  "description": "Canonical data for one target repository. Every number is produced by bug-age scripts; nothing is hand-entered. Blameless: no names or emails (enforced by the build gate).",
+  "type": "object",
+  "required": ["schema_version", "generator", "subject", "summary", "catalog", "method_a", "method_b", "feasibility", "coverage", "commits"],
+  "additionalProperties": false,
+  "$defs": {
+    "sha": {"type": "string", "pattern": "^[0-9a-f]{40}$"},
+    "sha_or_null": {"anyOf": [{"$ref": "#/$defs/sha"}, {"type": "null"}]},
+    "stat": {
+      "description": "Distribution over bugs: median, 90th percentile, maximum, sample size.",
+      "anyOf": [{"type": "null"}, {"type": "object", "required": ["median", "p90", "max", "n"],
+        "properties": {"median": {"type": "number"}, "p90": {"type": "number"}, "max": {"type": "number"}, "n": {"type": "integer", "minimum": 0}}}]
+    },
+    "outcome": {"enum": ["PASS", "FAIL", "UNTESTABLE", "FLAKY"]},
+    "feasibility_run": {
+      "type": "object",
+      "required": ["verdict", "built_and_tested_share", "counts", "method", "samples"],
+      "properties": {
+        "verdict": {"enum": ["GO", "NO-GO"]},
+        "built_and_tested_share": {"type": "number", "minimum": 0, "maximum": 1},
+        "counts": {"type": "object", "additionalProperties": {"type": "integer"}},
+        "method": {"type": "object"},
+        "samples": {"type": "array", "items": {"type": "object", "required": ["sha", "date", "toolchain", "status", "reason", "lockfile_committed"],
+          "properties": {"sha": {"$ref": "#/$defs/sha"}, "status": {"enum": ["BUILT_AND_TESTED", "BUILD_FAILED", "TESTS_FAILED", "NOT_TESTED", "FLAKY"]}}}}
+      }
+    }
+  },
+  "properties": {
+    "schema_version": {"const": "1.1.0"},
+    "generator": {"type": "string", "description": "bug-age version that built the bundle"},
+    "subject": {"type": "object", "required": ["repo_url", "crate_path", "head"],
+      "properties": {"repo_url": {"type": "string"}, "crate_path": {"type": "string"}, "head": {"$ref": "#/$defs/sha"}}},
+    "summary": {
+      "description": "Headline metrics. The explorer page recomputes them from the rows below as a self-check.",
+      "type": "object", "required": ["method_a", "method_b", "feasibility"],
+      "properties": {
+        "method_a": {"type": "object", "required": ["fixes", "with_introducer", "calendar_days", "commits_elapsed", "releases_shipped_bug"],
+          "properties": {"fixes": {"type": "integer"}, "with_introducer": {"type": "integer"},
+            "calendar_days": {"$ref": "#/$defs/stat"}, "commits_elapsed": {"$ref": "#/$defs/stat"}, "releases_shipped_bug": {"$ref": "#/$defs/stat"}}},
+        "method_b": {"type": "object", "required": ["swept", "located", "a_refuted", "verdicts"]},
+        "feasibility": {"type": "object", "required": ["baseline_share", "time_travel_share"]}
+      }
+    },
+    "catalog": {"type": "object", "required": ["include_rule", "scanned", "excluded"],
+      "properties": {"excluded": {"type": "array", "items": {"type": "object", "required": ["sha", "rule"],
+        "properties": {"sha": {"$ref": "#/$defs/sha"}, "rule": {"type": "string", "pattern": "^exclude:"}}}}}},
+    "method_a": {
+      "description": "One entry per catalogued fix (SZZ-style). days = committer days, or author days when the flag committer-dates-compressed is set.",
+      "type": "array",
+      "items": {"type": "object", "required": ["fix", "fix_date", "nominees", "flags", "days"],
+        "not": {"required": ["subject"]},
+        "properties": {"fix": {"$ref": "#/$defs/sha"}, "days": {"type": ["number", "null"]},
+          "nominees": {"type": "array", "items": {"type": "object", "required": ["sha", "date", "blamed_lines"], "properties": {"sha": {"$ref": "#/$defs/sha"}}}},
+          "flags": {"type": "array", "items": {"type": "string"}}}}
+    },
+    "method_b": {
+      "description": "One entry per behavioural sweep. days is exact only when verdict is located; otherwise a lower bound (days_is_lower_bound).",
+      "type": "array",
+      "items": {"type": "object",
+        "required": ["id", "fix", "verdict", "first_failing", "last_passing", "days", "days_is_lower_bound", "method_a_nominee", "a_check", "results", "repro_test"],
+        "properties": {
+          "fix": {"$ref": "#/$defs/sha"},
+          "verdict": {"enum": ["located", "interval", "censored-by-testability", "left-censored", "repro-invalid"]},
+          "first_failing": {"$ref": "#/$defs/sha_or_null"},
+          "last_passing": {"$ref": "#/$defs/sha_or_null"},
+          "days_is_lower_bound": {"type": "boolean"},
+          "a_check": {"type": "object", "required": ["label", "outcomes"],
+            "properties": {"label": {"enum": ["confirmed", "too-late", "refuted", "plausible", "untested", "inconclusive", "not-run"]}}},
+          "results": {"type": "array", "items": {"type": "object", "required": ["sha", "outcome", "steps"],
+            "properties": {"sha": {"$ref": "#/$defs/sha"}, "outcome": {"$ref": "#/$defs/outcome"}}}}
+        }}
+    },
+    "feasibility": {"type": "object", "required": ["baseline", "time_travel"],
+      "description": "null = that feasibility run did not happen for this target",
+      "properties": {"baseline": {"anyOf": [{"type": "null"}, {"$ref": "#/$defs/feasibility_run"}]}, "time_travel": {"anyOf": [{"type": "null"}, {"$ref": "#/$defs/feasibility_run"}]}}},
+    "coverage": {"type": "array", "items": {"type": "object", "required": ["stage", "status", "evidence", "proves", "does_not_prove"],
+      "properties": {"status": {"enum": ["COVERED", "PARTIAL", "NOT TESTED"]}}}},
+    "commits": {
+      "description": "Every SHA referenced anywhere in the bundle: committer date and a short, redacted subject. No author or committer identity.",
+      "type": "object",
+      "propertyNames": {"pattern": "^[0-9a-f]{40}$"},
+      "additionalProperties": {"type": "object", "required": ["date", "subject"], "additionalProperties": false,
+        "properties": {"date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, "subject": {"type": "string", "maxLength": 100}}}
+    }
+  }
+}