graphcheck 0.1.0__py3-none-any.whl

graphcheck/debug_diagnostics.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from graphcheck.contracts.check import (
+    DuplicateKeyError,
+    SuiteValidationError,
+    UnknownCheckError,
+    load_suite,
+)
+from graphcheck.contracts.results import Capabilities
+from graphcheck.errors import GraphCheckError
+from graphcheck.neo4j_adapter import BlockedCheck, Visibility
+from graphcheck.packs import CapabilityRequirement
+from graphcheck.packs.catalog import PackCatalogError, load_pack_requirements
+from graphcheck.project import load_project_config
+
+APOC_INSTALL_FIX = (
+    "Install APOC for this Neo4j DBMS, restart Neo4j, then run `graphcheck debug` again."
+)
+
+SUPPORTED_REQUIREMENTS: tuple[CapabilityRequirement, ...] = (
+    "read",
+    "show_procedures",
+    "apoc",
+    "count_store",
+    "store_consistency",
+)
+
+
+@dataclass(frozen=True)
+class CapabilityContext:
+    read: bool
+    show_procedures: bool
+    apoc: bool
+    count_store: bool
+    store_consistency: bool = False
+
+    @classmethod
+    def from_probe(cls, capabilities: Capabilities, visibility: Visibility) -> CapabilityContext:
+        return cls(
+            read=visibility.can_read,
+            show_procedures=visibility.can_show_procedures,
+            apoc=capabilities.apoc,
+            count_store=capabilities.count_store,
+            # Cypher cannot observe corrupt relationship endpoint records. A future C2 store
+            # consistency adapter can set this explicitly without changing SPEC-01 capabilities.
+            store_consistency=False,
+        )
+
+
+def blocked_checks_for_project(
+    root: Path,
+    context: CapabilityContext,
+    *,
+    pack_paths: Iterable[Path] | None = None,
+) -> list[BlockedCheck]:
+    """Report checks that cannot run because a probed database capability is missing."""
+    config = load_project_config(root)
+    checks_dir = root / config.checks
+    if not checks_dir.exists():
+        return []
+
+    try:
+        pack_requirements = load_pack_requirements(pack_paths)
+    except PackCatalogError as exc:
+        raise GraphCheckError(
+            "packs.invalid",
+            f"Could not load check pack capability metadata: {exc}",
+            "Fix the check pack YAML, then run `graphcheck debug` again.",
+        ) from exc
+
+    blocked: list[BlockedCheck] = []
+    for path in _suite_paths(checks_dir):
+        try:
+            suite = load_suite(path.read_text(encoding="utf-8"), source=str(path))
+        except (
+            OSError,
+            yaml.YAMLError,
+            ValidationError,
+            DuplicateKeyError,
+            UnknownCheckError,
+            SuiteValidationError,
+        ) as exc:
+            raise GraphCheckError(
+                "checks.invalid",
+                f"Could not load check suite {path}: {exc}",
+                "Fix the check YAML, then run `graphcheck debug` again.",
+            ) from exc
+        for check in suite.checks:
+            if check.generated:
+                continue
+            if check.pattern.value != "conformance":
+                continue
+            requirements = pack_requirements.get(check.spec.check)
+            if requirements is None:
+                raise GraphCheckError(
+                    "packs.requirements_missing",
+                    f"Check {check.spec.check!r} has no capability declaration in pack metadata.",
+                    "Add the check to its pack YAML with a non-empty `requires` list.",
+                )
+            for capability in requirements:
+                if _capability_present(context, capability):
+                    continue
+                blocked.append(
+                    BlockedCheck(
+                        suite=suite.suite,
+                        check_id=check.id,
+                        check=check.spec.check,
+                        missing_capability=capability,
+                        fix=_capability_fix(context, capability),
+                    )
+                )
+    return blocked
+
+
+def _suite_paths(checks_dir: Path) -> list[Path]:
+    return sorted({*checks_dir.glob("*.yml"), *checks_dir.glob("*.yaml")})
+
+
+def _capability_present(context: CapabilityContext, capability: CapabilityRequirement) -> bool:
+    if capability not in SUPPORTED_REQUIREMENTS:
+        raise RuntimeError(f"unsupported pack capability requirement: {capability!r}")
+    return bool(getattr(context, capability))
+
+
+def _capability_fix(context: CapabilityContext, capability: CapabilityRequirement) -> str:
+    if capability == "apoc":
+        if not context.show_procedures:
+            return (
+                "Grant procedure visibility and execution to the configured Neo4j user; "
+                "if APOC is not installed, install it and restart Neo4j, then run "
+                "`graphcheck debug` again."
+            )
+        return APOC_INSTALL_FIX
+    if capability == "read":
+        return "Grant read access to the configured Neo4j user, then run `graphcheck debug` again."
+    if capability == "show_procedures":
+        return (
+            "Grant procedure visibility to the configured Neo4j user, "
+            "then run `graphcheck debug` again."
+        )
+    if capability == "count_store":
+        return "Enable count-store support for this check, then run `graphcheck debug` again."
+    if capability == "store_consistency":
+        return (
+            "Run Neo4j's offline consistency checker or install a connector that exposes a "
+            "read-only relationship-store consistency probe."
+        )
+    return f"Enable the `{capability}` capability, then run `graphcheck debug` again."

graphcheck/diff.py

@@ -0,0 +1,420 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from graphcheck.contracts.profile import BaselineProfile, ProfileStatus
+from graphcheck.errors import GraphCheckError
+
+
+class SchemaVersionMismatch(ValueError):
+    """Raised when snapshots use incompatible contracts."""
+
+
+@dataclass(frozen=True)
+class DiffReport:
+    schema_version: str
+    baseline_a: str
+    baseline_b: str
+    a_status: str
+    b_status: str
+    fingerprint_changed: bool
+    drift_detected: bool
+    labels: dict[str, Any]
+    relationship_types: dict[str, Any]
+    constraints: dict[str, Any]
+    indexes: dict[str, Any]
+    statistics: dict[str, Any]
+    summary: dict[str, Any]
+    a_partial_reason: str | None = None
+    b_partial_reason: str | None = None
+
+
+def _change(name: str, before: int | float, after: int | float) -> dict[str, Any]:
+    delta = after - before
+    return {
+        "name": name,
+        "from": before,
+        "to": after,
+        "delta": delta,
+        "pct": None if before == 0 else round(delta / before * 100, 1),
+    }
+
+
+def _count_collection(
+    a_items: list[Any], b_items: list[Any], suppress_removed: bool
+) -> dict[str, Any]:
+    a = {item.name: item for item in a_items}
+    b = {item.name: item for item in b_items}
+    shared = sorted(a.keys() & b.keys())
+    return {
+        "changed": [
+            _change(name, a[name].count, b[name].count)
+            for name in shared
+            if a[name].count != b[name].count
+        ],
+        "added": [{"name": name, "to": b[name].count} for name in sorted(b.keys() - a.keys())],
+        "removed": []
+        if suppress_removed
+        else [{"name": name, "from": a[name].count} for name in sorted(a.keys() - b.keys())],
+        "unchanged": sum(a[name].count == b[name].count for name in shared),
+    }
+
+
+def _definition(item: Any) -> dict[str, Any]:
+    return {
+        "name": item.name,
+        "labels_or_types": list(item.labels_or_types),
+        "properties": list(item.properties),
+        "type": item.type,
+    }
+
+
+def _definition_collection(
+    a_items: list[Any], b_items: list[Any], suppress_removed: bool
+) -> dict[str, Any]:
+    a = {item.name: item for item in a_items}
+    b = {item.name: item for item in b_items}
+    added, removed, unchanged = set(b) - set(a), set(a) - set(b), 0
+    for name in set(a) & set(b):
+        if a[name] == b[name]:
+            unchanged += 1
+        else:
+            added.add(name)
+            removed.add(name)
+    return {
+        "added": [_definition(b[name]) for name in sorted(added)],
+        "removed": [] if suppress_removed else [_definition(a[name]) for name in sorted(removed)],
+        "unchanged": unchanged,
+    }
+
+
+def compare(
+    baseline_a: BaselineProfile,
+    baseline_b: BaselineProfile,
+    baseline_a_name: str = "baseline_a",
+    baseline_b_name: str = "baseline_b",
+) -> DiffReport:
+    """Compare profiles without formatting or recomputing their fingerprints."""
+    if baseline_a.status is ProfileStatus.PARTIAL or baseline_b.status is ProfileStatus.PARTIAL:
+        raise GraphCheckError(
+            "diff.partial_baseline",
+            "Comparison is inconclusive because one or more baselines are partial.",
+            "Generate complete baseline profiles before running `graphcheck diff`.",
+        )
+    if baseline_a.schema_version != baseline_b.schema_version:
+        raise SchemaVersionMismatch(
+            "cannot diff baselines with different schema_version "
+            f"(a={baseline_a.schema_version}, b={baseline_b.schema_version})"
+        )
+    b_partial = baseline_b.status is ProfileStatus.PARTIAL
+    labels = _count_collection(
+        baseline_a.graph_schema.labels,
+        baseline_b.graph_schema.labels,
+        b_partial and not baseline_b.graph_schema.labels,
+    )
+    relationships = _count_collection(
+        baseline_a.graph_schema.relationship_types,
+        baseline_b.graph_schema.relationship_types,
+        b_partial and not baseline_b.graph_schema.relationship_types,
+    )
+    constraints = _definition_collection(
+        baseline_a.graph_schema.constraints,
+        baseline_b.graph_schema.constraints,
+        b_partial and not baseline_b.graph_schema.constraints,
+    )
+    indexes = _definition_collection(
+        baseline_a.graph_schema.indexes,
+        baseline_b.graph_schema.indexes,
+        b_partial and not baseline_b.graph_schema.indexes,
+    )
+    a_cov = {
+        (x.owner, x.owner_name, x.property): x for x in baseline_a.statistics.property_coverage
+    }
+    b_cov = {
+        (x.owner, x.owner_name, x.property): x for x in baseline_b.statistics.property_coverage
+    }
+    cov_changed = []
+
+    def order(key: tuple[str, str, str]) -> tuple[str, str, str]:
+        return (key[1], key[2], key[0])
+
+    for key in sorted(a_cov.keys() & b_cov.keys(), key=order):
+        old, new = a_cov[key], b_cov[key]
+        if old.coverage != new.coverage:
+            cov_changed.append(
+                {
+                    "owner": old.owner,
+                    "owner_name": old.owner_name,
+                    "property": old.property,
+                    "from": old.coverage,
+                    "to": new.coverage,
+                    "delta_pp": round(new.coverage - old.coverage, 1),
+                }
+            )
+    coverage = {
+        "changed": cov_changed,
+        "added": [b_cov[k].model_dump() for k in sorted(b_cov.keys() - a_cov.keys(), key=order)],
+        "removed": []
+        if b_partial and not b_cov
+        else [a_cov[k].model_dump() for k in sorted(a_cov.keys() - b_cov.keys(), key=order)],
+        "unchanged": len(a_cov.keys() & b_cov.keys()) - len(cov_changed),
+    }
+    a_labels = {x.name: x for x in baseline_a.graph_schema.labels}
+    b_labels = {x.name: x for x in baseline_b.graph_schema.labels}
+    degree: dict[str, Any] = {}
+    for name in sorted(a_labels.keys() & b_labels.keys()):
+        old, new = a_labels[name].degree_distribution, b_labels[name].degree_distribution
+        if old is None or new is None:
+            degree[name] = None
+        elif old != new:
+            degree[name] = {"from": old.model_dump(), "to": new.model_dump()}
+    statistics = {
+        "node_count": None
+        if baseline_a.statistics.node_count == baseline_b.statistics.node_count
+        else _change(
+            "node_count", baseline_a.statistics.node_count, baseline_b.statistics.node_count
+        ),
+        "relationship_count": None
+        if baseline_a.statistics.relationship_count == baseline_b.statistics.relationship_count
+        else _change(
+            "relationship_count",
+            baseline_a.statistics.relationship_count,
+            baseline_b.statistics.relationship_count,
+        ),
+        "property_coverage": coverage,
+        "degree_distribution": degree,
+    }
+    summary = {
+        "labels": {
+            "changed": len(labels["changed"]),
+            "added": len(labels["added"]),
+            "removed": len(labels["removed"]),
+        },
+        "relationship_types": {
+            "changed": len(relationships["changed"]),
+            "added": len(relationships["added"]),
+            "removed": len(relationships["removed"]),
+        },
+        "constraints": {"added": len(constraints["added"]), "removed": len(constraints["removed"])},
+        "indexes": {"added": len(indexes["added"]), "removed": len(indexes["removed"])},
+        "statistics": {
+            "changed": sum(
+                (
+                    statistics["node_count"] is not None,
+                    statistics["relationship_count"] is not None,
+                    bool(cov_changed or coverage["added"] or coverage["removed"]),
+                    any(item is not None for item in degree.values()),
+                )
+            )
+        },
+    }
+    fingerprint_changed = baseline_a.fingerprint != baseline_b.fingerprint
+    drift_detected = any(
+        (
+            fingerprint_changed,
+            bool(labels["changed"] or labels["added"] or labels["removed"]),
+            bool(relationships["changed"] or relationships["added"] or relationships["removed"]),
+            bool(constraints["added"] or constraints["removed"]),
+            bool(indexes["added"] or indexes["removed"]),
+            statistics["node_count"] is not None,
+            statistics["relationship_count"] is not None,
+            bool(coverage["changed"] or coverage["added"] or coverage["removed"]),
+            any(item is not None for item in degree.values()),
+        )
+    )
+    return DiffReport(
+        baseline_a.schema_version,
+        Path(baseline_a_name).name,
+        Path(baseline_b_name).name,
+        str(baseline_a.status),
+        str(baseline_b.status),
+        fingerprint_changed,
+        drift_detected,
+        labels,
+        relationships,
+        constraints,
+        indexes,
+        statistics,
+        summary,
+        baseline_a.partial_reason,
+        baseline_b.partial_reason,
+    )
+
+
+def _number(value: int | float) -> str:
+    return f"{value:,.0f}" if float(value).is_integer() else f"{value:,}"
+
+
+def _count_line(item: dict[str, Any], prefix: str = "") -> str:
+    before, after, delta = item.get("from", 0), item.get("to", 0), item.get("delta")
+    if "from" not in item:
+        note = "new"
+    elif "to" not in item:
+        after, note = 0, "removed"
+    else:
+        pct = item["pct"]
+        note = f"{delta:+,}, n/a" if pct is None else f"{delta:+,}, {pct:+.1f}%"
+    return f"{prefix}{item['name']} {_number(before)} → {_number(after)} ({note})"
+
+
+def _render_counts(title: str, section: dict[str, Any]) -> list[str]:
+    body: list[str] = []
+    for item in section["changed"]:
+        body.append(_count_line(item))
+    for item in section["added"]:
+        body.append(_count_line(item, "+ "))
+    for item in section["removed"]:
+        body.append(_count_line(item, "- "))
+    if body and section["unchanged"]:
+        body.append(f"({section['unchanged']} unchanged)")
+    return [title, *body] if body else []
+
+
+def render_human(report: DiffReport) -> str:
+    lines = [
+        f"diff  {report.baseline_a} → {report.baseline_b}",
+        f"fingerprint: {'CHANGED' if report.fingerprint_changed else 'MATCH'}",
+    ]
+    partial = False
+    if report.a_status == str(ProfileStatus.PARTIAL):
+        lines.extend(("", f"warning: baseline_a is PARTIAL — {report.a_partial_reason}"))
+        partial = True
+    if report.b_status == str(ProfileStatus.PARTIAL):
+        lines.extend(("", f"warning: baseline_b is PARTIAL — {report.b_partial_reason}"))
+        partial = True
+    if partial:
+        lines.append("Collections missing due to partial status are not reported as removed.")
+    if not report.drift_detected:
+        return "\n".join((*lines, "", "No drift detected."))
+    sections = [
+        _render_counts("Labels", report.labels),
+        _render_counts("Relationships", report.relationship_types),
+    ]
+    for title, collection in (("Constraints", report.constraints), ("Indexes", report.indexes)):
+        body = []
+        for sign, key in (("+", "added"), ("-", "removed")):
+            for item in collection[key]:
+                target, props = ", ".join(item["labels_or_types"]), ", ".join(item["properties"])
+                body.append(f"{sign} {item['name']} [{target}({props}), {item['type']}] ({key})")
+        sections.append([title, *body] if body else [])
+    stats: list[str] = []
+    for label, key in (("Nodes", "node_count"), ("Relationships", "relationship_count")):
+        if report.statistics[key]:
+            stats.append(_count_line({**report.statistics[key], "name": label}))
+    for item in report.statistics["property_coverage"]["changed"]:
+        stats.append(
+            f"{item['owner_name']}.{item['property']} cover    "
+            f"{item['from']:.1f}% → {item['to']:.1f}% ({item['delta_pp']:+.1f} pp)"
+        )
+
+    for item in report.statistics["property_coverage"]["added"]:
+        stats.append(
+            f"+ {item['owner_name']}.{item['property']} cover    {item['coverage']:.1f}% (new)"
+        )
+
+    for item in report.statistics["property_coverage"]["removed"]:
+        stats.append(
+            f"- {item['owner_name']}.{item['property']} cover    {item['coverage']:.1f}% (removed)"
+        )
+    for name, item in report.statistics["degree_distribution"].items():
+        if item is not None:
+            stats.append(f"{name} degree distribution")
+            for field, before in item["from"].items():
+                after = item["to"][field]
+                delta = round(after - before, 1)
+                stats.append(f"{field}: {_number(before)} → {_number(after)} ({delta:+g})")
+    sections.append(["Statistics", *stats] if stats else [])
+    for section in sections:
+        if section:
+            lines.extend(("", *section))
+    summary = report.summary
+    parts: list[str] = []
+    labels = summary["labels"]
+    if any(labels.values()):
+        noun = "label" if labels["changed"] == 1 else "labels"
+        parts.append(
+            f"{labels['changed']} {noun} changed, {labels['added']} added, "
+            f"{labels['removed']} removed"
+        )
+    relationships = summary["relationship_types"]
+    if any(relationships.values()):
+        noun = "relationship" if relationships["changed"] == 1 else "relationships"
+        parts.append(
+            f"{relationships['changed']} {noun} changed, {relationships['added']} added, "
+            f"{relationships['removed']} removed"
+        )
+    for key, singular in (("constraints", "constraint"), ("indexes", "index")):
+        values = summary[key]
+        details = []
+        for action in ("added", "removed"):
+            count = values[action]
+            if count:
+                if singular == "index":
+                    noun = "index" if count == 1 else "indexes"
+                else:
+                    noun = singular if count == 1 else f"{singular}s"
+                details.append(f"{count} {noun} {action}")
+        if details:
+            parts.append(", ".join(details))
+    changed = summary["statistics"]["changed"]
+    if changed:
+        noun = "statistic" if changed == 1 else "statistics"
+        parts.append(f"{changed} {noun} changed")
+    if parts:
+        lines.extend(("", f"Summary: {' · '.join(parts)}"))
+    return "\n".join(lines)
+
+
+def render_json(report: DiffReport) -> str:
+    statistics = {
+        **report.statistics,
+        "node_count": (
+            None
+            if report.statistics["node_count"] is None
+            else {
+                key: value
+                for key, value in report.statistics["node_count"].items()
+                if key != "name"
+            }
+        ),
+        "relationship_count": (
+            None
+            if report.statistics["relationship_count"] is None
+            else {
+                key: value
+                for key, value in report.statistics["relationship_count"].items()
+                if key != "name"
+            }
+        ),
+    }
+    payload = {
+        "schema_version": report.schema_version,
+        "baseline_a": report.baseline_a,
+        "baseline_b": report.baseline_b,
+        "a_status": report.a_status,
+        "b_status": report.b_status,
+        "fingerprint_changed": report.fingerprint_changed,
+        "drift_detected": report.drift_detected,
+        "labels": report.labels,
+        "relationship_types": report.relationship_types,
+        "constraints": {
+            "added": report.constraints["added"],
+            "removed": report.constraints["removed"],
+        },
+        "indexes": {
+            "added": report.indexes["added"],
+            "removed": report.indexes["removed"],
+        },
+        "statistics": statistics,
+        "summary": report.summary,
+    }
+    return json.dumps(payload, indent=2)
+
+
+def diff(current_baseline: BaselineProfile, latest_baseline: BaselineProfile) -> list[str]:
+    """Compatibility wrapper for the original line-oriented API."""
+    report = compare(current_baseline, latest_baseline)
+    return [] if not report.drift_detected else render_human(report).splitlines()[3:]

graphcheck/engine/__init__.py

@@ -0,0 +1,64 @@
+from graphcheck.engine.baseline import (
+    BaselineProvider,
+    BaselineValue,
+    DirectoryBaselineProvider,
+    MappingBaselineProvider,
+)
+from graphcheck.engine.compiler import (
+    CompiledCheck,
+    ConformancePlan,
+    CypherCompiler,
+    EvidenceCondition,
+    compile_check,
+    register_conformance_compiler,
+)
+from graphcheck.engine.evaluator import Evaluation, VerdictEvaluator, evaluate_check
+from graphcheck.engine.executor import ExecutionResult, Executor, ReadOnlyExecutor, execute_query
+from graphcheck.engine.runner import (
+    Engine,
+    EngineConfig,
+    SuiteInput,
+    YamlSuiteInput,
+    failed_results,
+    run_suite,
+    run_suite_yaml,
+)
+from graphcheck.engine.sampling import (
+    SamplingDecision,
+    SamplingPolicy,
+    derive_check_seed,
+    deterministic_sample_indices,
+    wilson_estimate,
+)
+
+__all__ = [
+    "BaselineProvider",
+    "BaselineValue",
+    "CompiledCheck",
+    "ConformancePlan",
+    "CypherCompiler",
+    "DirectoryBaselineProvider",
+    "Engine",
+    "EngineConfig",
+    "EvidenceCondition",
+    "Evaluation",
+    "ExecutionResult",
+    "Executor",
+    "MappingBaselineProvider",
+    "ReadOnlyExecutor",
+    "SamplingDecision",
+    "SamplingPolicy",
+    "SuiteInput",
+    "YamlSuiteInput",
+    "VerdictEvaluator",
+    "compile_check",
+    "derive_check_seed",
+    "deterministic_sample_indices",
+    "evaluate_check",
+    "execute_query",
+    "failed_results",
+    "register_conformance_compiler",
+    "run_suite",
+    "run_suite_yaml",
+    "wilson_estimate",
+]