graphcheck 0.2.0__tar.gz → 0.3.0__tar.gz

graphcheck-0.3.0/.gitattributes

@@ -0,0 +1,2 @@
+*.sh text eol=lf
+docs/samples/reports/*.html text eol=lf

graphcheck-0.3.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+*                                  @ezhilvendhan @kev-graphora
+/tests/fixtures/                   @jayachandra-bit

{graphcheck-0.2.0 → graphcheck-0.3.0}/.github/pull_request_template.md

@@ -10,7 +10,7 @@
 - [ ] No `print` / `console.log`; structured logger only
 - [ ] No swallowed exceptions (`except: pass`)
 - [ ] No un-issued TODOs
-- [ ] Design detailed in `docs/specs/<name>.md` (where applicable)
+- [ ] Design detailed in `docs/specifications/<name>.md` (where applicable)
 - [ ] CHANGELOG.md entry
 - [ ] No new third-party dependency without team review
 - [ ] No agent meta-commentary or AI attribution anywhere

graphcheck-0.3.0/.github/scripts/first-run.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${GRAPHCHECK_BOOTSTRAP_PYTHON:?Set GRAPHCHECK_BOOTSTRAP_PYTHON to the clean runner Python}"
+: "${GRAPHCHECK_WHEEL_DIR:?Set GRAPHCHECK_WHEEL_DIR to the directory containing one wheel}"
+: "${FIRST_RUN_PLATFORM:?Set FIRST_RUN_PLATFORM to the evidence platform name}"
+: "${FIRST_RUN_TRIAL:?Set FIRST_RUN_TRIAL to the one-based trial number}"
+: "${FIRST_RUN_TESTED_GITHUB_SHA:?Set FIRST_RUN_TESTED_GITHUB_SHA to github.sha}"
+: "${FIRST_RUN_GITHUB_EVENT_NAME:?Set FIRST_RUN_GITHUB_EVENT_NAME to github.event_name}"
+
+FIRST_RUN_DIR="${FIRST_RUN_DIR:-${RUNNER_TEMP:-/tmp}/graphcheck-first-run}"
+FIRST_RUN_PR_HEAD_SHA="${FIRST_RUN_PR_HEAD_SHA:-}"
+FIRST_RUN_RUNNER_OS="${FIRST_RUN_RUNNER_OS:-unknown}"
+FIRST_RUN_RUNNER_IMAGE="${FIRST_RUN_RUNNER_IMAGE:-unknown}"
+FIRST_RUN_VENV="${FIRST_RUN_VENV:-${RUNNER_TEMP:-/tmp}/graphcheck-first-run-venv-${FIRST_RUN_PLATFORM}-${FIRST_RUN_TRIAL}}"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+evidence_script="$script_dir/first_run_evidence.py"
+mkdir -p "$FIRST_RUN_DIR"
+
+fail_stage() {
+  local stage="$1" fix="$2"
+  printf 'First-run failed during %s.\nFix: %s\n' "$stage" "$fix" | tee "$FIRST_RUN_DIR/failure.txt" >&2
+  exit 1
+}
+
+run_stage() {
+  local stage="$1" log="$2" fix="$3"
+  shift 3
+  set +e
+  "$@" 2>&1 | tee -a "$log"
+  local status=${PIPESTATUS[0]}
+  set -e
+  test "$status" -eq 0 || fail_stage "$stage" "$fix See $log for details."
+}
+
+shopt -s nullglob
+wheels=("$GRAPHCHECK_WHEEL_DIR"/*.whl)
+test "${#wheels[@]}" -eq 1 || fail_stage "wheel discovery" "Place exactly one built GraphCheck wheel in $GRAPHCHECK_WHEEL_DIR."
+wheel="${wheels[0]}"
+
+read -r started_at_ns started_monotonic_ns < <("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "import time; print(time.time_ns(), time.monotonic_ns())")
+install_log="$FIRST_RUN_DIR/install.log"
+run_stage "virtual environment creation" "$install_log" "Verify that Python includes venv support and the runner temp directory is writable." "$GRAPHCHECK_BOOTSTRAP_PYTHON" -m venv "$FIRST_RUN_VENV"
+graphcheck_python="$FIRST_RUN_VENV/bin/python"
+graphcheck_bin="$FIRST_RUN_VENV/bin/graphcheck"
+run_stage "GraphCheck installation" "$install_log" "Verify package-index connectivity and that the wheel supports this Python version." "$graphcheck_python" -m pip install --disable-pip-version-check --no-cache-dir "$wheel"
+install_finished_ns=$("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "import time; print(time.monotonic_ns())")
+
+fixture_log="$FIRST_RUN_DIR/fixture.log"
+run_stage "Neo4j fixture preparation" "$fixture_log" "Start the pinned Neo4j service and verify Bolt credentials." "$graphcheck_python" "$evidence_script" prepare-fixture
+fixture_finished_ns=$("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "import time; print(time.monotonic_ns())")
+
+project="$FIRST_RUN_DIR/project"
+mkdir -p "$project"
+cd "$project"
+init_started_ns=$("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "import time; print(time.monotonic_ns())")
+run_stage "graphcheck init" "$FIRST_RUN_DIR/init.log" "Run graphcheck debug --json and correct the reported connection or project configuration problem." "$graphcheck_bin" init
+init_finished_ns=$("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "import time; print(time.monotonic_ns())")
+grep -q "Detected Neo4j" "$FIRST_RUN_DIR/init.log" || fail_stage "graphcheck init connectivity" "Run graphcheck debug --json and correct the reported Neo4j connection problem."
+grep -q "Traceback (most recent call last)" "$FIRST_RUN_DIR/init.log" && fail_stage "graphcheck init diagnostics" "Use the stable diagnostic instead of exposing a Python traceback."
+for required in graphcheck.yml profiles.yml checks/example.yml; do
+  test -f "$required" || fail_stage "graphcheck init artifact validation" "Confirm the project directory is writable and retry graphcheck init."
+done
+
+run_started_ns=$("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "import time; print(time.monotonic_ns())")
+set +e
+"$graphcheck_bin" run 2>&1 | tee "$FIRST_RUN_DIR/run.log"
+run_exit_code=${PIPESTATUS[0]}
+set -e
+run_finished_ns=$("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "import time; print(time.monotonic_ns())")
+finished_at_ns=$("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "import time; print(time.time_ns())")
+grep -q "Traceback (most recent call last)" "$FIRST_RUN_DIR/run.log" && fail_stage "graphcheck run diagnostics" "Use the stable diagnostic instead of exposing a Python traceback."
+
+python_version=$("$graphcheck_python" -c "import platform; print(platform.python_version())")
+run_stage "first-result validation" "$FIRST_RUN_DIR/validation.log" "Inspect results.json, report.html, and run.log; a valid result must be complete, scored, and execute at least one check." \
+  "$GRAPHCHECK_BOOTSTRAP_PYTHON" "$evidence_script" record \
+  --results .graphcheck/runs/latest/results.json \
+  --report .graphcheck/runs/latest/report.html \
+  --output "$FIRST_RUN_DIR/timing.json" \
+  --platform "$FIRST_RUN_PLATFORM" \
+  --trial "$FIRST_RUN_TRIAL" \
+  --run-exit-code "$run_exit_code" \
+  --started-at-ns "$started_at_ns" \
+  --finished-at-ns "$finished_at_ns" \
+  --install-ns "$((install_finished_ns - started_monotonic_ns))" \
+  --fixture-ns "$((fixture_finished_ns - install_finished_ns))" \
+  --init-ns "$((init_finished_ns - init_started_ns))" \
+  --run-ns "$((run_finished_ns - run_started_ns))" \
+  --total-ns "$((run_finished_ns - started_monotonic_ns))" \
+  --python-version "$python_version" \
+  --runner-os "$FIRST_RUN_RUNNER_OS" \
+  --runner-image "$FIRST_RUN_RUNNER_IMAGE" \
+  --tested-github-sha "$FIRST_RUN_TESTED_GITHUB_SHA" \
+  --pull-request-head-sha "$FIRST_RUN_PR_HEAD_SHA" \
+  --github-event-name "$FIRST_RUN_GITHUB_EVENT_NAME"
+
+total_seconds=$("$GRAPHCHECK_BOOTSTRAP_PYTHON" -c "print(round(($run_finished_ns - $started_monotonic_ns) / 1_000_000_000, 3))")
+printf 'Install -> init -> first valid run completed in %.3f seconds; median budget: <900 seconds.\n' "$total_seconds" | tee "$FIRST_RUN_DIR/timing.txt" | tee -a "$FIRST_RUN_DIR/run.log"
+
+profile_log="$FIRST_RUN_DIR/profile.log"
+run_stage "graphcheck profile smoke check" "$profile_log" "Run graphcheck debug --json and correct the reported profiling problem." "$graphcheck_bin" profile
+grep -q "Traceback (most recent call last)" "$profile_log" && fail_stage "graphcheck profile diagnostics" "Use the stable diagnostic instead of exposing a Python traceback."
+baseline_found=0
+for baseline in .graphcheck/baselines/*.json; do
+  test -f "$baseline" && baseline_found=1 && break
+done
+test "$baseline_found" -eq 1 || fail_stage "graphcheck profile artifact validation" "Confirm the artifact directory is writable and retry graphcheck profile."

graphcheck-0.3.0/.github/scripts/first_run_evidence.py

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""Record and aggregate clean-environment first-run evidence using only the stdlib."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import statistics
+import sys
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+SCHEMA_VERSION = "1"
+DEFAULT_PLATFORMS = ("linux-container", "macos", "wsl")
+
+
+def _seconds(nanoseconds: int) -> float:
+    return round(nanoseconds / 1_000_000_000, 3)
+
+
+def _timestamp(nanoseconds: int) -> str:
+    return datetime.fromtimestamp(nanoseconds / 1_000_000_000, UTC).isoformat()
+
+
+def _read_results(path: Path, errors: list[str]) -> dict[str, object] | None:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        errors.append(f"results.json could not be read: {type(exc).__name__}: {exc}")
+        return None
+    if not isinstance(payload, dict):
+        errors.append("results.json must contain a JSON object")
+        return None
+    return payload
+
+
+def _result_facts(
+    payload: dict[str, object] | None, run_exit_code: int, errors: list[str]
+) -> tuple[int | None, int | float | None, str | None, str | None]:
+    if payload is None:
+        return None, None, None, None
+    run = payload.get("run")
+    totals = payload.get("totals")
+    score = payload.get("score")
+    if not isinstance(run, dict):
+        errors.append("results.json is missing the run object")
+        run = {}
+    if not isinstance(totals, dict):
+        errors.append("results.json is missing the totals object")
+        totals = {}
+    selected, skipped = totals.get("checks"), totals.get("skipped")
+    executed = (
+        selected - skipped
+        if isinstance(selected, int)
+        and not isinstance(selected, bool)
+        and isinstance(skipped, int)
+        and not isinstance(skipped, bool)
+        else None
+    )
+    if executed is None or executed < 1:
+        errors.append("results.json must contain at least one executed check")
+    run_status = run.get("run_status", run.get("status"))
+    if run_status != "complete":
+        errors.append("results.json run.run_status must be complete")
+    if run_exit_code not in {0, 1, 2}:
+        errors.append("a complete scored run must exit with code 0, 1, or 2")
+    if run.get("exit_code") != run_exit_code:
+        errors.append("the command exit code does not match results.json")
+    score_value = score.get("value") if isinstance(score, dict) else None
+    if (
+        isinstance(score_value, bool)
+        or not isinstance(score_value, (int, float))
+        or not math.isfinite(score_value)
+    ):
+        errors.append("results.json must contain a finite numeric score")
+        score_value = None
+    elif not 0 <= score_value <= 100:
+        errors.append("results.json score must be between 0 and 100")
+    target = run.get("target")
+    return (
+        executed,
+        score_value,
+        run.get("graphcheck_version") if isinstance(run.get("graphcheck_version"), str) else None,
+        (
+            target.get("server_version")
+            if isinstance(target, dict) and isinstance(target.get("server_version"), str)
+            else None
+        ),
+    )
+
+
+def record(args: argparse.Namespace) -> int:
+    errors: list[str] = []
+    if args.trial < 1:
+        errors.append("trial must be a positive integer")
+    if args.budget_seconds < 1:
+        errors.append("budget_seconds must be a positive integer")
+    if args.finished_at_ns < args.started_at_ns:
+        errors.append("finished_at must not precede started_at")
+    if not args.tested_github_sha:
+        errors.append("tested_github_sha must identify the checkout tested by this trial")
+    if args.github_event_name == "pull_request" and not args.pull_request_head_sha:
+        errors.append("pull_request_head_sha is required for pull_request evidence")
+    for name in ("install", "fixture", "init", "run", "total"):
+        if getattr(args, f"{name}_ns") < 0:
+            errors.append(f"{name} timing must be non-negative")
+    results_path, report_path, output_path = map(Path, (args.results, args.report, args.output))
+    payload = _read_results(results_path, errors)
+    if not report_path.is_file() or report_path.stat().st_size < 1:
+        errors.append("report.html is missing or empty")
+    executed, score, graphcheck_version, neo4j_version = _result_facts(
+        payload, args.run_exit_code, errors
+    )
+    timings = {
+        name: _seconds(getattr(args, f"{name}_ns"))
+        for name in ("install", "fixture", "init", "run", "total")
+    }
+    evidence = {
+        "schema_version": SCHEMA_VERSION,
+        "platform": args.platform,
+        "trial": args.trial,
+        "github_event_name": args.github_event_name,
+        "tested_github_sha": args.tested_github_sha,
+        "pull_request_head_sha": args.pull_request_head_sha or None,
+        "provenance_note": (
+            "tested_github_sha is github.sha: the synthetic merge commit for pull_request events "
+            "and the pushed commit for push events"
+        ),
+        "runner_os": args.runner_os,
+        "runner_image": args.runner_image,
+        "python_version": args.python_version,
+        "graphcheck_version": graphcheck_version,
+        "neo4j_version": neo4j_version,
+        "timing_boundary": "clean-wheel-install-start_to_valid-init-run-result",
+        "database_ready_before_install": False,
+        "profile_smoke_after_timing": True,
+        "started_at": _timestamp(args.started_at_ns),
+        "finished_at": _timestamp(args.finished_at_ns),
+        "timings_seconds": timings,
+        "budget_seconds": args.budget_seconds,
+        "within_individual_budget": timings["total"] < args.budget_seconds,
+        "run_exit_code": args.run_exit_code,
+        "executed_checks": executed,
+        "score": score,
+        "valid": not errors,
+        "validation_errors": errors,
+        "artifacts": {"results": str(results_path), "report": str(report_path)},
+    }
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(evidence, indent=2) + "\n", encoding="utf-8")
+    if errors:
+        for error in errors:
+            print(f"First-run evidence invalid: {error}", file=sys.stderr)
+        print(
+            f"Fix: inspect the command logs and {output_path}, correct the failure, and retry.",
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        f"Valid first result: {executed} executed check(s), score {score}, "
+        f"install-to-result {timings['total']:.3f}s."
+    )
+    return 0
+
+
+def prepare_fixture(args: argparse.Namespace) -> int:
+    from neo4j import GraphDatabase
+
+    deadline, last_error = time.monotonic() + args.timeout_seconds, None
+    while time.monotonic() < deadline:
+        try:
+            with GraphDatabase.driver(
+                args.uri,
+                auth=(args.user, args.password),
+                connection_timeout=1,
+            ) as driver:
+                driver.verify_connectivity()
+                driver.execute_query(
+                    "MERGE (:Customer {name: 'Ada'})",
+                    database_=args.database,
+                )
+            print(f"Prepared first-run fixture at {args.uri}/{args.database}.")
+            return 0
+        except Exception as exc:
+            last_error = exc
+            time.sleep(2)
+    print(
+        "First-run fixture setup failed: Neo4j did not become ready "
+        f"within {args.timeout_seconds} seconds ({type(last_error).__name__}: {last_error}).\n"
+        "Fix: verify that Neo4j is running, Bolt is reachable, and the configured credentials "
+        "are correct.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+def _load_samples(root: Path) -> tuple[dict[tuple[str, int], dict[str, object]], list[str]]:
+    samples: dict[tuple[str, int], dict[str, object]] = {}
+    errors: list[str] = []
+    for path in sorted(root.rglob("timing.json")):
+        try:
+            sample = json.loads(path.read_text(encoding="utf-8"))
+            key = (str(sample["platform"]), int(sample["trial"]))
+        except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+            errors.append(f"{path}: unreadable timing evidence ({type(exc).__name__}: {exc})")
+            continue
+        if key in samples:
+            errors.append(f"duplicate timing evidence for {key[0]} trial {key[1]}")
+        else:
+            samples[key] = sample
+    return samples, errors
+
+
+def summarize(args: argparse.Namespace) -> int:
+    root, output_dir = Path(args.input), Path(args.output)
+    samples, errors = _load_samples(root)
+    tested_github_shas = sorted(
+        {
+            value
+            for sample in samples.values()
+            if isinstance((value := sample.get("tested_github_sha")), str) and value
+        }
+    )
+    pull_request_head_shas = sorted(
+        {
+            value
+            for sample in samples.values()
+            if isinstance((value := sample.get("pull_request_head_sha")), str) and value
+        }
+    )
+    github_event_names = sorted(
+        {
+            value
+            for sample in samples.values()
+            if isinstance((value := sample.get("github_event_name")), str) and value
+        }
+    )
+    for (platform_name, trial), sample in samples.items():
+        if not isinstance(sample.get("tested_github_sha"), str) or not sample["tested_github_sha"]:
+            errors.append(f"{platform_name} trial {trial} is missing tested_github_sha")
+        if sample.get("github_event_name") == "pull_request" and not sample.get(
+            "pull_request_head_sha"
+        ):
+            errors.append(f"{platform_name} trial {trial} is missing pull_request_head_sha")
+    if len(tested_github_shas) != 1:
+        errors.append("timing evidence must contain exactly one tested GitHub SHA")
+    if len(pull_request_head_shas) > 1:
+        errors.append("timing evidence contains more than one pull-request head SHA")
+    if len(github_event_names) != 1:
+        errors.append("timing evidence must contain exactly one GitHub event name")
+    platforms: dict[str, dict[str, object]] = {}
+    for platform_name in args.platforms:
+        observations: list[dict[str, object]] = []
+        for trial in range(1, args.trials + 1):
+            sample = samples.get((platform_name, trial))
+            if sample is None:
+                errors.append(f"missing timing evidence for {platform_name} trial {trial}")
+                continue
+            timings = sample.get("timings_seconds")
+            total = timings.get("total") if isinstance(timings, dict) else None
+            if sample.get("valid") is not True:
+                errors.append(f"{platform_name} trial {trial} did not produce a valid result")
+            if (
+                isinstance(total, bool)
+                or not isinstance(total, (int, float))
+                or not math.isfinite(total)
+                or total < 0
+            ):
+                errors.append(f"{platform_name} trial {trial} has invalid total timing")
+                continue
+            observations.append({"trial": trial, "total_seconds": total})
+        median_seconds = (
+            round(statistics.median(item["total_seconds"] for item in observations), 3)
+            if len(observations) == args.trials
+            else None
+        )
+        under_budget = median_seconds is not None and median_seconds < args.budget_seconds
+        if median_seconds is not None and not under_budget:
+            errors.append(
+                f"{platform_name} median {median_seconds:.3f}s is not under {args.budget_seconds}s"
+            )
+        platforms[platform_name] = {
+            "samples": observations,
+            "median_seconds": median_seconds,
+            "under_budget": under_budget,
+        }
+    passed = not errors
+    summary = {
+        "schema_version": SCHEMA_VERSION,
+        "metric": "clean-wheel-install-start_to_valid-init-run-result",
+        "tested_github_sha": tested_github_shas[0] if len(tested_github_shas) == 1 else None,
+        "pull_request_head_sha": (
+            pull_request_head_shas[0] if len(pull_request_head_shas) == 1 else None
+        ),
+        "github_event_name": github_event_names[0] if len(github_event_names) == 1 else None,
+        "budget_seconds": args.budget_seconds,
+        "trials_per_platform": args.trials,
+        "platforms": platforms,
+        "passed": passed,
+        "errors": errors,
+    }
+    lines = ["# GraphCheck first-run evidence", ""]
+    if len(tested_github_shas) == 1:
+        lines.extend((f"Tested GitHub SHA: `{tested_github_shas[0]}`", ""))
+    if len(pull_request_head_shas) == 1:
+        lines.extend((f"Pull-request head SHA: `{pull_request_head_shas[0]}`", ""))
+    lines.extend(
+        (
+            "Budget: median install-to-first-valid-result "
+            f"**under {args.budget_seconds // 60} minutes**.",
+            "",
+            "| Platform | Samples (seconds) | Median (seconds) | Result |",
+            "| --- | ---: | ---: | --- |",
+        )
+    )
+    for name, result in platforms.items():
+        sample_text = (
+            ", ".join(str(item["total_seconds"]) for item in result["samples"]) or "missing"
+        )
+        median_text = (
+            str(result["median_seconds"]) if result["median_seconds"] is not None else "n/a"
+        )
+        lines.append(
+            f"| {name} | {sample_text} | {median_text} | "
+            f"{'PASS' if result['under_budget'] else 'FAIL'} |"
+        )
+    if errors:
+        lines.extend(("", "## Errors", "", *(f"- {error}" for error in errors)))
+    lines.extend(("", f"Overall: **{'PASS' if passed else 'FAIL'}**", ""))
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "first-run-summary.json").write_text(
+        json.dumps(summary, indent=2) + "\n", encoding="utf-8"
+    )
+    (output_dir / "first-run-summary.md").write_text("\n".join(lines), encoding="utf-8")
+    print("\n".join(lines))
+    return 0 if passed else 1
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser()
+    commands = root.add_subparsers(dest="command", required=True)
+    record_parser = commands.add_parser("record")
+    for name in (
+        "results",
+        "report",
+        "output",
+        "platform",
+        "python-version",
+        "runner-os",
+        "runner-image",
+        "tested-github-sha",
+        "github-event-name",
+    ):
+        record_parser.add_argument(f"--{name}", required=True)
+    for name in (
+        "started-at-ns",
+        "finished-at-ns",
+        "install-ns",
+        "fixture-ns",
+        "init-ns",
+        "run-ns",
+        "total-ns",
+    ):
+        record_parser.add_argument(f"--{name}", type=int, required=True)
+    record_parser.add_argument("--trial", type=int, required=True)
+    record_parser.add_argument("--run-exit-code", type=int, required=True)
+    record_parser.add_argument("--pull-request-head-sha", default="")
+    record_parser.add_argument("--budget-seconds", type=int, default=900)
+    record_parser.set_defaults(handler=record)
+    fixture_parser = commands.add_parser("prepare-fixture")
+    fixture_parser.add_argument("--uri", default="bolt://localhost:7687")
+    fixture_parser.add_argument("--user", default="neo4j")
+    fixture_parser.add_argument("--password", default="graphora")
+    fixture_parser.add_argument("--database", default="neo4j")
+    fixture_parser.add_argument("--timeout-seconds", type=int, default=120)
+    fixture_parser.set_defaults(handler=prepare_fixture)
+    summary_parser = commands.add_parser("summarize")
+    summary_parser.add_argument("--input", required=True)
+    summary_parser.add_argument("--output", required=True)
+    summary_parser.add_argument("--platforms", nargs="+", default=list(DEFAULT_PLATFORMS))
+    summary_parser.add_argument("--trials", type=int, default=3)
+    summary_parser.add_argument("--budget-seconds", type=int, default=900)
+    summary_parser.set_defaults(handler=summarize)
+    return root
+
+
+def main() -> int:
+    try:
+        args = parser().parse_args()
+        return args.handler(args)
+    except Exception as exc:
+        print(
+            f"First-run evidence tooling failed: {type(exc).__name__}: {exc}\n"
+            "Fix: verify the evidence arguments and files, then retry.",
+            file=sys.stderr,
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

graphcheck-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,144 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [development, main]
+
+jobs:
+  secret-scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install checksum-verified gitleaks
+        env:
+          GITLEAKS_VERSION: 8.29.1
+          GITLEAKS_SHA256: e4eb209d04e20339d77122a3bdf9cd41351255cfb27ebcb75e85325e04f88924
+        run: >-
+          archive="$RUNNER_TEMP/gitleaks.tar.gz"; curl --fail --silent --show-error --location
+          "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          --output "$archive"; echo "$GITLEAKS_SHA256  $archive" | sha256sum --check -;
+          tar -xzf "$archive" -C "$RUNNER_TEMP" gitleaks; echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
+      - name: Scan pull-request commits
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: gitleaks git --redact --log-opts="${BASE_SHA}..${HEAD_SHA}" .
+      - name: Scan protected-branch history
+        if: github.event_name == 'push'
+        run: gitleaks git --redact .
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  # Repo-wide suite on the locked driver. The `test (3.12)` / `test (3.13)` contexts are
+  # required by the branch ruleset, so this job's name and matrix must stay stable.
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run pytest --cov=graphcheck --cov-report=term-missing --cov-fail-under=80
+
+  # Neo4j Python driver compatibility across the supported range, on a separate job name so
+  # it does not collide with the required `test` contexts above.
+  driver-compat:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.12"
+            driver-line: min
+          - python-version: "3.14"
+            driver-line: latest-6
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install uv and select the matrix Python
+        uses: astral-sh/setup-uv@v5
+        with:
+          # Sets UV_PYTHON, which overrides the committed .python-version so uv
+          # runs on the matrix interpreter (not the pinned 3.12).
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - name: Select tested Neo4j Python driver line
+        env:
+          DRIVER_LINE: ${{ matrix.driver-line }}
+        run: |
+          if [ "$DRIVER_LINE" = "min" ]; then
+            uv pip install "neo4j==5.20.0"
+          else
+            uv pip install --upgrade "neo4j>=6,<7"
+          fi
+      - name: Assert the interpreter matches the matrix (guards against a single pinned run)
+        env:
+          WANT: ${{ matrix.python-version }}
+        run: uv run --no-sync python -c "import os, sys; want=tuple(int(p) for p in os.environ['WANT'].split('.')); assert sys.version_info[:2]==want, sys.version"
+      - name: Test installed driver line
+        env:
+          PYTHONDEVMODE: ${{ matrix.driver-line == 'min' && '1' || '0' }}
+          PYTHONWARNINGS: ${{ matrix.driver-line == 'min' && 'error::ResourceWarning' || 'default' }}
+        run: >
+          uv run --no-sync pytest
+          tests/unit/connectors/test_neo4j_adapter.py
+          tests/unit/engine/test_executor.py
+          tests/unit/application/test_profiler.py
+          tests/unit/application/test_debug_diagnostics.py
+
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        neo4j-target: [lts-cypher-5, current-cypher-5, current-cypher-25]
+    env:
+      GRAPHCHECK_NEO4J_INTEGRATION: "1"
+      GRAPHCHECK_NEO4J_TARGET: ${{ matrix.neo4j-target }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: >
+          uv run pytest
+          tests/integration/test_integration_neo4j_adapter.py
+          tests/integration/test_integration_engine.py
+          tests/integration/test_hostile_graphs.py
+          tests/integration/test_mcp_neo4j_workflow.py
+          tests/integration/test_performance_plans.py
+          -v
+
+  installed-wheel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv venv .wheel-venv
+      - run: uv pip install --python .wheel-venv/bin/python dist/*.whl
+      - run: .wheel-venv/bin/graphcheck --version
+      - run: .wheel-venv/bin/graphcheck --help
+      - name: Verify installed package resources
+        run: .wheel-venv/bin/python -c "from importlib.resources import files; assert files('graphcheck').joinpath('packs/core.yml').is_file(); assert files('graphcheck').joinpath('packs/pii.yml').is_file()"