graphcheck 0.1.0__py3-none-any.whl

graphcheck/__init__.py

@@ -0,0 +1,9 @@
+"""GraphCheck — semantic observability for property graphs."""
+
+# Single source of truth for the version. `pyproject.toml` declares the version as dynamic and
+# reads it from here at build time (see `[tool.hatch.version]`), so the built distribution and
+# `--version` always agree without a second literal or a runtime metadata lookup (the latter is
+# slow enough on Windows to breach the cold-start budget for the `--version` fast path).
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

graphcheck/application/artifacts.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import shutil
+import threading
+import time
+import uuid
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from filelock import FileLock
+
+from graphcheck.contracts.results import Results
+
+RenderObserver = Callable[[int, bool], None]
+RenderedArtifacts = tuple[bytes, bytes, bytes]
+
+# The `latest` alias is the only artifact target multiple runs contend for (historical run
+# directories are unique per run id). MCP 2.0 dispatches synchronous tools through worker
+# threads, so two run_suite calls can publish concurrently within one process; separate CLI
+# processes can also publish at once. This in-process thread lock is shared by every code
+# path that publishes `latest`.
+_LATEST_PUBLISH_LOCK = threading.Lock()
+
+
+@contextmanager
+def latest_publication_lock(runs_dir: Path) -> Iterator[None]:
+    """Serialize publication of the shared `latest` alias across threads and processes.
+
+    Every writer that swaps `<runs_dir>/latest` must hold this lock so the exists/move/swap
+    sequence in publish_run_directory can never interleave with another publisher.
+    """
+    file_lock = FileLock(str(runs_dir / ".latest.lock"))
+    with _LATEST_PUBLISH_LOCK, file_lock:
+        yield
+
+
+def render_run_artifacts(
+    results: Results,
+    *,
+    render_observer: RenderObserver | None = None,
+) -> RenderedArtifacts:
+    """Render the results.json, report.html, and summary.json bytes exactly once.
+
+    Rendering once and publishing the bytes to both the history directory and `latest`
+    keeps the two directories byte-identical and avoids re-rendering the HTML report twice.
+    """
+    from graphcheck.reporting.history import report_summary_json
+    from graphcheck.reporting.html import render_validated_html_report
+    from graphcheck.reporting.writer import validated_results_json
+
+    model, rendered_json = validated_results_json(results)
+
+    render_started = time.monotonic()
+    try:
+        rendered_html = render_validated_html_report(model)
+    except Exception:
+        if render_observer is not None:
+            render_observer(max(0, round((time.monotonic() - render_started) * 1000)), False)
+        raise
+    if render_observer is not None:
+        render_observer(max(0, round((time.monotonic() - render_started) * 1000)), True)
+
+    rendered_summary = report_summary_json(model)
+    return (
+        rendered_json.encode("utf-8"),
+        rendered_html.encode("utf-8"),
+        rendered_summary.encode("utf-8"),
+    )
+
+
+def write_run_artifacts(
+    results: Results,
+    runs_dir: Path,
+    *,
+    render_observer: RenderObserver | None = None,
+) -> tuple[Path, Path]:
+    """Publish a run's history directory and refresh the shared `latest` alias.
+
+    This is the single artifact writer used by both `graphcheck run` and the MCP server
+    (through execute_run), so every surface produces identical artifacts: a report_name-based
+    history id, an atomically swapped results/report/summary triple, and a serialized `latest`
+    refresh.
+    """
+    from graphcheck.reporting.history import report_name
+
+    runs_dir.mkdir(parents=True, exist_ok=True)
+    resolved_runs = runs_dir.resolve()
+    results.run.id = report_name(results)
+    historical_dir = runs_dir / results.run.id
+    if (
+        historical_dir.name.casefold() == "latest"
+        or historical_dir.resolve().parent != resolved_runs
+    ):
+        raise ValueError(f"run id cannot be used as an artifact directory: {results.run.id!r}")
+
+    artifacts = render_run_artifacts(results, render_observer=render_observer)
+    publish_run_directory(artifacts, historical_dir)
+
+    latest_dir = runs_dir / "latest"
+    with latest_publication_lock(runs_dir):
+        publish_run_directory(artifacts, latest_dir)
+    return latest_dir / "results.json", latest_dir / "report.html"
+
+
+def publish_run_directory(artifacts: RenderedArtifacts, directory: Path) -> None:
+    """Stage and swap a complete results/report/summary triple without exposing a mixed set."""
+
+    parent = directory.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    token = uuid.uuid4().hex
+    staging = parent / f".{directory.name}.staging-{token}"
+    backup = parent / f".{directory.name}.backup-{token}"
+    staging.mkdir()
+    previous_moved = False
+
+    try:
+        for name, content in zip(
+            ("results.json", "report.html", "summary.json"), artifacts, strict=True
+        ):
+            (staging / name).write_bytes(content)
+
+        if directory.exists():
+            is_junction = getattr(directory, "is_junction", lambda: False)
+            if not directory.is_dir() or directory.is_symlink() or is_junction():
+                raise OSError(f"refusing to replace linked or non-directory artifact: {directory}")
+            directory.replace(backup)
+            previous_moved = True
+
+        staging.replace(directory)
+
+    except Exception:
+        if previous_moved and backup.exists():
+            if directory.exists():
+                shutil.rmtree(directory)
+            backup.replace(directory)
+        raise
+
+    else:
+        if backup.exists():
+            shutil.rmtree(backup)
+
+    finally:
+        if staging.exists():
+            shutil.rmtree(staging)

graphcheck/application/paths.py

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+
+def project_path(root: Path, configured: str) -> Path:
+    path = Path(configured)
+    return path if path.is_absolute() else root / path

graphcheck/application/run.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import inspect
+import time
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+
+from graphcheck.application.artifacts import (
+    RenderObserver,
+    write_run_artifacts,
+)
+from graphcheck.application.paths import project_path
+from graphcheck.application.suites import load_suite_inputs
+from graphcheck.connection_profiles import (
+    load_profiles,
+    select_profile,
+)
+from graphcheck.contracts.results import CheckError, Results
+from graphcheck.engine import (
+    DirectoryBaselineProvider,
+    Engine,
+    EngineConfig,
+    failed_results,
+)
+from graphcheck.errors import GraphCheckError
+from graphcheck.neo4j_adapter import Neo4jClient
+from graphcheck.project import (
+    find_project_root,
+    load_project_config,
+)
+from graphcheck.telemetry.events import EngineEventSink
+
+
+@dataclass(slots=True)
+class RunRequest:
+    profile: str | None
+    suite_ids: list[str]
+    tags: list[str]
+    fail_fast: bool
+    concurrency: int | None = None
+    verify_read_only_credential: bool = False
+
+
+@dataclass(slots=True)
+class RunOutcome:
+    results: Results
+    results_path: Path | None
+    report_path: Path | None
+    artifact_error: Exception | None = None
+    # `time.monotonic()` boundaries so a caller can attribute setup versus
+    # artifact-write time correctly. `setup_done_perf` is stamped once profile,
+    # client, credential, and suite setup finish (before the engine runs);
+    # `artifact_started_perf` is stamped immediately before artifacts are written.
+    setup_done_perf: float | None = None
+    artifact_started_perf: float | None = None
+
+
+def execute_run(
+    request: RunRequest,
+    *,
+    progress_callback: Callable[[int, int, str], None] | None = None,
+    event_sink: EngineEventSink | None = None,
+    render_observer: RenderObserver | None = None,
+    client_factory: Callable[[object, int], Neo4jClient] | None = None,
+    artifact_writer: Callable[..., tuple[Path, Path]] = write_run_artifacts,
+    target_observer: Callable[[object], None] | None = None,
+) -> RunOutcome:
+    """
+    Execute a GraphCheck run independently of the CLI or MCP.
+    """
+    root = find_project_root()
+    config = load_project_config(root)
+    artifacts = project_path(root, config.artifacts)
+    runs_dir = artifacts / "runs"
+
+    checks_dir = project_path(root, config.checks)
+    profiles = load_profiles(root)
+    _, selected_profile = select_profile(
+        profiles,
+        request.profile,
+    )
+
+    client: Neo4jClient | None = None
+    setup_done_perf: float | None = None
+    engine_started = False
+
+    try:
+        max_concurrency = request.concurrency or int(config.concurrency)
+
+        factory = client_factory or _new_neo4j_client
+        client = factory(
+            selected_profile,
+            max_concurrency,
+        )
+
+        if request.verify_read_only_credential:
+            target = _verify_cli_audit_credential(client)
+            if target_observer is not None:
+                target_observer(target)
+
+        suite_inputs = load_suite_inputs(
+            checks_dir,
+            request.suite_ids,
+        )
+        setup_done_perf = time.monotonic()
+        engine = Engine(
+            client,
+            baselines=DirectoryBaselineProvider(
+                artifacts / "baselines",
+            ),
+            config=EngineConfig(max_concurrency=max_concurrency),
+            progress_callback=progress_callback,
+            event_sink=event_sink,
+        )
+        engine_started = True
+        results = engine.run(
+            suite_inputs,
+            tags=request.tags,
+            fail_fast=request.fail_fast,
+            selection_suites=request.suite_ids or None,
+        )
+
+    except GraphCheckError as exc:
+        if setup_done_perf is None:
+            setup_done_perf = time.monotonic()
+        results = failed_results(
+            exc.error,
+            suite_ids=request.suite_ids,
+            tags=request.tags,
+            fail_fast=request.fail_fast,
+        )
+
+    except Exception as exc:
+        if setup_done_perf is None:
+            setup_done_perf = time.monotonic()
+        if engine_started:
+            # An unexpected fault raised by Engine.run() is an engine error, not a
+            # configuration problem. Preserve `engine.unexpected` so the CLI reports it as
+            # ENGINE / ENGINE_ERROR rather than a user configuration failure.
+            error = CheckError(
+                code="engine.unexpected",
+                message=f"The GraphCheck engine failed unexpectedly: {type(exc).__name__}: {exc}",
+                fix="Re-run the check suite; if it recurs, file a bug with the run details.",
+            )
+        else:
+            error = CheckError(
+                code="run.configuration",
+                message=f"GraphCheck could not prepare the run: {type(exc).__name__}: {exc}",
+                fix="Fix the project configuration, then run `graphcheck debug` and try again.",
+            )
+        results = failed_results(
+            error,
+            suite_ids=request.suite_ids,
+            tags=request.tags,
+            fail_fast=request.fail_fast,
+        )
+
+    finally:
+        if client is not None:
+            with suppress(Exception):
+                client.close()
+
+    # Publish exactly once, outside the setup/engine exception translation above. A write
+    # failure must preserve the completed (or already-failed) result and surface as
+    # artifact_error with the real artifact-write timing boundary — never a retried write
+    # nor a re-labelled run.configuration result.
+    artifact_started_perf = time.monotonic()
+    try:
+        results_path, report_path = artifact_writer(
+            results,
+            runs_dir,
+            render_observer=render_observer,
+        )
+    except Exception as artifact_exc:
+        return RunOutcome(
+            results=results,
+            results_path=None,
+            report_path=None,
+            artifact_error=artifact_exc,
+            setup_done_perf=setup_done_perf,
+            artifact_started_perf=artifact_started_perf,
+        )
+
+    return RunOutcome(
+        results=results,
+        results_path=results_path,
+        report_path=report_path,
+        setup_done_perf=setup_done_perf,
+        artifact_started_perf=artifact_started_perf,
+    )
+
+
+def _new_neo4j_client(profile, max_concurrency: int):
+    """Construct the workload-aware Neo4j client while retaining simple test doubles."""
+    parameters = inspect.signature(Neo4jClient).parameters.values()
+    accepts_setting = any(
+        parameter.name == "max_concurrency" or parameter.kind is inspect.Parameter.VAR_KEYWORD
+        for parameter in parameters
+    )
+    return (
+        Neo4jClient(profile, max_concurrency=max_concurrency)
+        if accepts_setting
+        else Neo4jClient(profile)
+    )
+
+
+def _verify_cli_audit_credential(client: object) -> object | None:
+    """Probe the target, verify the read-only credential, and return the probed target.
+
+    The returned target carries the live node/relationship counts so a caller can render a
+    run header without probing the database a second time.
+    """
+    verify = getattr(client, "verify_read_only_credential", None)
+    probe = getattr(client, "probe", None)
+    result = probe() if callable(probe) else None
+    if callable(verify):
+        verify()
+    target = result[0] if isinstance(result, tuple) else result
+    if isinstance(result, tuple) and len(result) > 2 and target is not None:
+        counts = result[2]
+        copy = getattr(target, "model_copy", None)
+        if callable(copy):
+            target = copy(
+                update={
+                    "nodes": getattr(counts, "nodes", getattr(target, "nodes", None)),
+                    "relationships": getattr(
+                        counts, "relationships", getattr(target, "relationships", None)
+                    ),
+                }
+            )
+    return target

graphcheck/application/suites.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from graphcheck.engine.runner import SuiteInput
+from graphcheck.errors import GraphCheckError
+
+
+def load_suite_inputs(checks_dir: Path, requested_suites: list[str]) -> list[SuiteInput]:
+    if not checks_dir.is_dir():
+        raise GraphCheckError(
+            "run.checks_missing",
+            f"Configured checks directory was not found: {checks_dir}",
+            "Create the directory or fix `checks` in graphcheck.yml.",
+        )
+    try:
+        paths = sorted(
+            path
+            for path in checks_dir.rglob("*")
+            if path.is_file() and path.suffix.lower() in {".yml", ".yaml"}
+        )
+    except OSError as exc:
+        raise GraphCheckError(
+            "run.checks_unreadable",
+            f"Could not enumerate check suites in {checks_dir}: {exc}",
+            "Check the configured checks path and its filesystem permissions.",
+        ) from exc
+
+    loaded: list[SuiteInput] = []
+    for path in paths:
+        try:
+            text = path.read_text(encoding="utf-8")
+            loaded.append(SuiteInput.from_yaml(text, source=str(path)))
+        except Exception as exc:
+            raise GraphCheckError(
+                "run.suite_invalid",
+                f"Suite {path} is invalid: {type(exc).__name__}: {exc}",
+                "Fix the suite YAML and remove unknown keys, then run it again.",
+            ) from exc
+
+    if not requested_suites:
+        return loaded
+    requested = set(requested_suites)
+    return [item for item in loaded if item.suite.suite in requested]

graphcheck/baselines.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from graphcheck.contracts.profile import BaselineProfile
+from graphcheck.errors import GraphCheckError
+from graphcheck.project import find_project_root
+
+_BASELINE_NAME = re.compile(r"\d{8}T\d{6}(?:\.\d{6})?\.json")
+
+
+def baseline_directory(
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> Path:
+    """Return the configured timestamped-baseline directory."""
+
+    root = find_project_root() if project_root is None else project_root
+    if project_root is None and Path(artifacts) == Path(".graphcheck"):
+        artifacts = _discovered_artifacts(root)
+    configured = Path(artifacts)
+    artifacts_dir = configured if configured.is_absolute() else root / configured
+    return artifacts_dir / "baselines"
+
+
+def current_baseline_file(
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> Path:
+    root = find_project_root() if project_root is None else project_root
+    if project_root is None and Path(artifacts) == Path(".graphcheck"):
+        artifacts = _discovered_artifacts(root)
+    configured = Path(artifacts)
+    artifacts_dir = configured if configured.is_absolute() else root / configured
+    return artifacts_dir / "current-baseline.json"
+
+
+def _discovered_artifacts(root: Path) -> str | Path:
+    """Use configured artifacts when a real project file exists; aid legacy callers/tests."""
+
+    from graphcheck.project import PROJECT_FILE, load_project_config
+
+    if not (root / PROJECT_FILE).is_file():
+        return ".graphcheck"
+    return load_project_config(root).artifacts
+
+
+def write_baseline(
+    profile: BaselineProfile,
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> Path:
+    baselines_dir = baseline_directory(project_root, artifacts)
+    baselines_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now(UTC)
+    content = profile.model_dump_json(
+        by_alias=True,
+        indent=2,
+    )
+    while True:
+        path = baselines_dir / f"{timestamp:%Y%m%dT%H%M%S.%f}.json"
+        try:
+            with path.open("x", encoding="utf-8") as snapshot:
+                snapshot.write(content)
+            return path
+        except FileExistsError:
+            timestamp += timedelta(microseconds=1)
+
+
+def list_baselines(
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> list[Path]:
+    baselines_dir = baseline_directory(project_root, artifacts)
+    if not baselines_dir.is_dir():
+        return []
+    return sorted(
+        path
+        for path in baselines_dir.iterdir()
+        if path.is_file() and _BASELINE_NAME.fullmatch(path.name)
+    )
+
+
+def latest_baseline(
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> Path | None:
+    baselines = list_baselines(project_root, artifacts)
+    return baselines[-1] if baselines else None
+
+
+def set_current_baseline(
+    filename: str | None = None,
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> Path:
+    baselines_dir = baseline_directory(project_root, artifacts)
+    baselines = list_baselines(project_root, artifacts)
+
+    if filename is None:
+        if not baselines:
+            raise GraphCheckError(
+                "baseline.missing",
+                "No timestamped baseline snapshots were found.",
+                "Run `graphcheck profile` to create a baseline snapshot first.",
+            )
+
+        # Default to the previous run.
+        # If only one baseline exists, use that.
+        selected = baselines[0] if len(baselines) == 1 else baselines[-2]
+
+    else:
+        selected = {path.name: path for path in baselines}.get(filename)
+        if selected is None:
+            raise GraphCheckError(
+                "baseline.not_found",
+                f"Baseline snapshot {filename!r} was not found in {baselines_dir}.",
+                "Choose an existing timestamped snapshot, or run `graphcheck profile`.",
+            )
+
+    selected_file = current_baseline_file(project_root, artifacts)
+    selected_file.parent.mkdir(parents=True, exist_ok=True)
+    selected_file.write_text(
+        json.dumps({"baseline": selected.name}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+    return selected
+
+
+def get_current_baseline(
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> Path | None:
+    selected_file = current_baseline_file(project_root, artifacts)
+    if not selected_file.exists():
+        return None
+    try:
+        payload = json.loads(selected_file.read_text(encoding="utf-8"))
+        filename = payload["baseline"]
+    except (OSError, json.JSONDecodeError, KeyError, TypeError) as exc:
+        raise GraphCheckError(
+            "baseline.current_invalid",
+            f"{selected_file} is not valid baseline metadata.",
+            "Run `graphcheck baseline set` to select an active baseline again.",
+        ) from exc
+    if not isinstance(filename, str):
+        raise GraphCheckError(
+            "baseline.current_invalid",
+            f"{selected_file} is not valid baseline metadata.",
+            "Run `graphcheck baseline set` to select an active baseline again.",
+        )
+    baselines = list_baselines(project_root, artifacts)
+    selected = {path.name: path for path in baselines}.get(filename)
+    if selected is None:
+        raise GraphCheckError(
+            "baseline.current_missing",
+            f"The active baseline snapshot {filename!r} does not exist.",
+            "Run `graphcheck baseline set` to select an existing baseline.",
+        )
+    return selected
+
+
+def resolve_diff_baselines(
+    current_baseline_name: str | None = None,
+    latest_baseline_name: str | None = None,
+    *,
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> tuple[Path, Path]:
+    """Resolve the Current and Latest Baseline snapshots for a diff."""
+    if (current_baseline_name is None) != (latest_baseline_name is None):
+        raise GraphCheckError(
+            "baseline.not_found",
+            "Both Current Baseline and Latest Baseline must be specified together.",
+            "Provide two baseline snapshots, or omit both to use the defaults.",
+        )
+
+    if current_baseline_name is not None and latest_baseline_name is not None:
+        return (
+            _resolve_baseline_path(
+                current_baseline_name,
+                project_root=project_root,
+                artifacts=artifacts,
+            ),
+            _resolve_baseline_path(
+                latest_baseline_name,
+                project_root=project_root,
+                artifacts=artifacts,
+            ),
+        )
+
+    baselines = list_baselines(project_root, artifacts)
+    if len(baselines) < 2:
+        raise GraphCheckError(
+            "baseline.missing",
+            "At least two timestamped baseline snapshots are required for a diff.",
+            "Run `graphcheck profile` at least twice to create baseline snapshots.",
+        )
+
+    current_baseline = get_current_baseline(project_root, artifacts)
+    if current_baseline is None:
+        current_baseline = baselines[-2]
+    return current_baseline, baselines[-1]
+
+
+def _resolve_baseline_path(
+    name: str,
+    *,
+    project_root: Path | None = None,
+    artifacts: str | Path = ".graphcheck",
+) -> Path:
+    requested = Path(name)
+    if requested.is_file():
+        return requested
+
+    selected = {path.name: path for path in list_baselines(project_root, artifacts)}.get(name)
+    if selected is not None:
+        return selected
+
+    raise GraphCheckError(
+        "baseline.not_found",
+        f"Baseline snapshot {name!r} was not found.",
+        "Choose an existing timestamped snapshot or valid baseline file path.",
+    )

graphcheck/bootstrap.py

@@ -0,0 +1,19 @@
+"""Lightweight console entry point with a standard-library-only version fast path."""
+
+from __future__ import annotations
+
+import sys
+
+from graphcheck import __version__
+
+
+def cli() -> None:
+    if sys.argv[1:] == ["--version"]:
+        print(f"graphcheck {__version__}")
+        return
+    from graphcheck.telemetry.consent import resolve_consent
+
+    consent = resolve_consent()
+    from graphcheck.cli import cli as typer_cli
+
+    typer_cli(consent=consent)