#!/usr/bin/env python3

"""External cross-check against git's own ``t/perf`` suite.

License boundary (GPLv2): git's ``t/perf`` scripts are GPLv2 and are NEVER

vendored, copied, or translated into this repository. This module drives the

upstream suite at arm's length only — a subprocess invocation of

``<git-src>/t/perf/run`` inside the user's own git source tree — and then

aggregates the raw numeric output files (``t/test-results/*.result``) that the

suite leaves behind. Reading numbers out of result files is data aggregation,

not derivation of GPL code; no shell logic crosses the boundary.

What this gives the harness: git's own perf numbers for the same corpus

fixture (``GIT_PERF_REPO``), labeled ``measurement_source:

"git_tperf_external"``. t/perf reports min-of-N while our lanes report

medians, so the comparison is a sanity band (see ``sanity_band``), never an

equality check.

Result-file format (observed, liberal): each ``<script>.<n>.result`` file

holds one line per repetition of whitespace-separated floats — GNU-time-style

``real user sys`` seconds. We take the first float as real seconds and any

second/third as user/sys; malformed lines are skipped, never fatal.

``<script>.<n>.descr`` (when present) holds the human description;

``<script>.subtests`` lists test numbers and is not needed for parsing.

Modes:

- run mode (default): requires ``--git-src`` pointing at a git source tree

  containing ``t/perf/run``. Missing or not such a tree -> exit 3 with skip

  JSON ``{"status": "skipped", "reason": "git_src_missing:<path>"}`` on

  stdout (skip honesty: no git source tree is a coverage gap, not an error).

  A nonzero exit from ``./run`` is recorded in a run-record row, never a hard

  failure — partial result files are still parsed.

- ``--parse-only DIR``: skip running; parse an existing ``t/test-results``

  directory. This is the testable path (unittest runs without a git tree).

Output: JSONL under ``--results`` (a directory): one row per repetition plus

one ``min_of_n`` summary row per test, all stamped with runner identity

(ADR-0007) via ``oakbench.runner``.

Exit codes: 0 on parsed rows; 3 skip (git source tree or results missing);

2 usage errors.

"""

from __future__ import annotations

import argparse

import json

import os

import subprocess

import sys

from pathlib import Path

from typing import Any, Optional

sys.path.insert(0, str(Path(__file__).resolve().parent))

from oakbench.runner import runner_fields, stamp_row

SCHEMA_VERSION = 1

MEASUREMENT_SOURCE = "git_tperf_external"

RESULTS_FILENAME = "tperf_external.jsonl"

DEFAULT_REPEAT_COUNT = 10

EXIT_OK = 0

EXIT_USAGE = 2

EXIT_SKIP = 3

def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:

    parser = argparse.ArgumentParser(

        description="Run git's t/perf suite at arm's length and aggregate its raw .result files."

    )

    parser.add_argument(

        "--git-src",

        type=Path,

        default=None,

        help="Git source tree containing t/perf (missing/not-a-git-tree -> exit 3 skip JSON)",

    )

    parser.add_argument(

        "--perf-repo",

        type=Path,

        default=None,

        help="Corpus fixture repository exported as GIT_PERF_REPO",

    )

    parser.add_argument(

        "--repeat-count",

        type=int,

        default=DEFAULT_REPEAT_COUNT,

        help=f"Exported as GIT_PERF_REPEAT_COUNT (default {DEFAULT_REPEAT_COUNT})",

    )

    parser.add_argument(

        "--tests",

        type=str,

        default=None,

        help="Optional CSV subset of perf scripts, e.g. p0001-rev-list.sh",

    )

    parser.add_argument(

        "--results",

        type=Path,

        required=True,

        help=f"Directory for the output JSONL ({RESULTS_FILENAME})",

    )

    parser.add_argument(

        "--parse-only",

        type=Path,

        default=None,

        metavar="DIR",

        help="Skip running; parse an existing t/test-results directory",

    )

    return parser.parse_args(argv)

def _floats(tokens: list[str]) -> Optional[list[float]]:

    try:

        return [float(token) for token in tokens]

    except ValueError:

        return None

def _split_result_stem(stem: str) -> tuple[str, Optional[str]]:

    """``p0001-rev-list.1`` -> (``p0001-rev-list``, ``1``)."""

    if "." in stem:

        script, number = stem.rsplit(".", 1)

        return script, number

    return stem, None

def _description_for(results_dir: Path, script: str, number: Optional[str]) -> Optional[str]:

    if number is None:

        return None

    descr_path = results_dir / f"{script}.{number}.descr"

    try:

        text = descr_path.read_text(errors="replace").strip()

    except OSError:

        return None

    return text or None

def _ms(seconds: Optional[float]) -> Optional[float]:

    if seconds is None:

        return None

    return round(seconds * 1000.0, 6)

def parse_tperf_results(results_dir: Path) -> list[dict[str, Any]]:

    """Parse every ``*.result`` file in a t/test-results directory into rows.

    One row per repetition line plus one min-of-N summary row per test.

    Liberal: each line is N whitespace-separated floats; the first is real

    seconds, optional second/third are user/sys. Malformed lines are skipped.

    """

    rows: list[dict[str, Any]] = []

    for result_path in sorted(results_dir.glob("*.result")):

        script, number = _split_result_stem(result_path.stem)

        tperf_test = f"{script}.{number}" if number is not None else script

        description = _description_for(results_dir, script, number)

        try:

            text = result_path.read_text(errors="replace")

        except OSError:

            continue

        reals_ms: list[float] = []

        repetition = 0

        for line in text.splitlines():

            tokens = line.split()

            if not tokens:

                continue

            values = _floats(tokens)

            if not values:

                continue  # malformed line: skipped, never fatal

            repetition += 1

            real_ms = _ms(values[0])

            reals_ms.append(real_ms)

            rows.append(

                {

                    "schema_version": SCHEMA_VERSION,

                    "measurement_source": MEASUREMENT_SOURCE,

                    "tperf_script": script,

                    "tperf_test": tperf_test,

                    "tperf_description": description,

                    "repetition": repetition,

                    "elapsed_ms": real_ms,

                    "user_ms": _ms(values[1]) if len(values) > 1 else None,

                    "sys_ms": _ms(values[2]) if len(values) > 2 else None,

                    "subject": "git",

                    "subject_kind": "git",

                }

            )

        if reals_ms:

            rows.append(

                {

                    "schema_version": SCHEMA_VERSION,

                    "measurement_source": MEASUREMENT_SOURCE,

                    "tperf_script": script,

                    "tperf_test": tperf_test,

                    "tperf_description": description,

                    "tperf_statistic": "min_of_n",

                    "elapsed_ms": min(reals_ms),

                    "n": len(reals_ms),

                    "subject": "git",

                    "subject_kind": "git",

                }

            )

    return rows

def sanity_band(

    tperf_min_ms: Optional[float],

    our_median_ms: Optional[float],

    *,

    tolerance_pct: float = 50,

) -> dict[str, Any]:

    """Sanity band between t/perf's min-of-N and our median for one operation.

    ``ratio`` is ``our_median_ms / tperf_min_ms``; ``within_band`` is true when

    the ratio sits inside ``1 +/- tolerance_pct/100``. Guards (documented):

    when either input is None or ``tperf_min_ms <= 0`` (zero-division guard),

    ``ratio`` is None and ``within_band`` is False — unmeasured never passes.

    """

    result: dict[str, Any] = {

        "tperf_min_ms": tperf_min_ms,

        "our_median_ms": our_median_ms,

        "tolerance_pct": tolerance_pct,

        "ratio": None,

        "within_band": False,

    }

    if tperf_min_ms is None or our_median_ms is None:

        return result

    if tperf_min_ms <= 0:

        return result

    ratio = float(our_median_ms) / float(tperf_min_ms)

    result["ratio"] = ratio

    result["within_band"] = abs(ratio - 1.0) * 100.0 <= tolerance_pct

    return result

def _skip(reason: str) -> int:

    print(json.dumps({"status": "skipped", "reason": reason}))

    return EXIT_SKIP

def run_tperf(git_src: Path, args: argparse.Namespace) -> dict[str, Any]:

    """Invoke ``./run`` inside <git-src>/t/perf at arm's length; record only."""

    perf_dir = git_src / "t" / "perf"

    command = ["./run"]

    if args.tests:

        command.extend(name.strip() for name in args.tests.split(",") if name.strip())

    env = dict(os.environ)

    if args.perf_repo is not None:

        env["GIT_PERF_REPO"] = str(args.perf_repo.resolve())

    env["GIT_PERF_REPEAT_COUNT"] = str(args.repeat_count)

    try:

        proc = subprocess.run(

            command,

            cwd=str(perf_dir),

            env=env,

            capture_output=True,

            text=True,

        )

        returncode: Optional[int] = proc.returncode

        error: Optional[str] = None

    except OSError as exc:

        returncode = None

        error = str(exc)

    # Nonzero/failed runs are recorded, never fatal: partial .result files

    # are still worth aggregating.

    return {

        "schema_version": SCHEMA_VERSION,

        "measurement_source": MEASUREMENT_SOURCE,

        "record_kind": "tperf_run",

        "command": command,

        "cwd": str(perf_dir),

        "git_perf_repo": str(args.perf_repo) if args.perf_repo is not None else None,

        "git_perf_repeat_count": args.repeat_count,

        "returncode": returncode,

        "error": error,

        "subject": "git",

        "subject_kind": "git",

    }

def main(argv: Optional[list[str]] = None) -> int:

    args = parse_args(argv)

    rows: list[dict[str, Any]] = []

    if args.parse_only is not None:

        results_dir = args.parse_only

        if not results_dir.is_dir():

            return _skip(f"results_dir_missing:{results_dir}")

    else:

        git_src = args.git_src

        if git_src is None:

            return _skip("git_src_missing:")

        run_script = git_src / "t" / "perf" / "run"

        if not git_src.is_dir() or not run_script.is_file():

            return _skip(f"git_src_missing:{git_src}")

        rows.append(run_tperf(git_src, args))

        results_dir = git_src / "t" / "test-results"

        if not results_dir.is_dir():

            return _skip(f"results_dir_missing:{results_dir}")

    rows.extend(parse_tperf_results(results_dir))

    fields = runner_fields()

    stamped = [stamp_row(row, fields) for row in rows]

    args.results.mkdir(parents=True, exist_ok=True)

    out_path = args.results / RESULTS_FILENAME

    with out_path.open("w", encoding="utf-8") as fh:

        for row in stamped:

            fh.write(json.dumps(row, sort_keys=True) + "\n")

    print(f"[result] {out_path} ({len(stamped)} rows)", file=sys.stderr)

    measured = [row for row in stamped if "elapsed_ms" in row]

    return EXIT_OK if measured else EXIT_SKIP

if __name__ == "__main__":

    raise SystemExit(main())