graphcheck 0.1.0__py3-none-any.whl

graphcheck/connection_profiles.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import yaml
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from graphcheck.errors import (
+    profile_invalid,
+    profile_missing,
+    profile_not_found,
+    profile_password_missing,
+    profile_uri_invalid,
+)
+from graphcheck.project import PROFILES_FILE
+
+
+class ConnectionProfile(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    user: str
+    password: str | None = None
+    password_env: str | None = None
+    database: str
+
+    def resolved(self, name: str) -> ConnectionProfile:
+        if self.password_env:
+            env_password = os.environ.get(self.password_env)
+            if env_password:
+                return self.model_copy(update={"password": env_password, "password_env": None})
+            if not self.password:
+                raise profile_password_missing(name, self.password_env)
+        if not self.password:
+            raise profile_password_missing(name)
+        return self.model_copy(update={"password_env": None})
+
+
+class ProfilesFile(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    default: str
+    profiles: dict[str, ConnectionProfile]
+
+
+def default_profiles() -> ProfilesFile:
+    return ProfilesFile(
+        default="local",
+        profiles={
+            "local": ConnectionProfile(
+                uri="bolt://localhost:7687",
+                user="neo4j",
+                password="graphora",
+                database="neo4j",
+            )
+        },
+    )
+
+
+def write_default_profiles(root: Path) -> None:
+    (root / PROFILES_FILE).write_text(
+        """# Edit the inline password below for the fastest local setup.
+# For CI/production, remove `password` and use `password_env: NEO4J_PASSWORD` instead.
+# Enterprise: assign only the built-in reader role. Community: EXPLAIN guards each query.
+# Use bolt:// for direct local Bolt, or neo4j+s:// for a CA-signed TLS/routing endpoint.
+default: local
+profiles:
+  local:
+    uri: bolt://localhost:7687
+    user: neo4j
+    password: graphora
+    database: neo4j
+""",
+        encoding="utf-8",
+    )
+
+
+def load_profiles(root: Path) -> ProfilesFile:
+    path = root / PROFILES_FILE
+    if not path.exists():
+        raise profile_missing()
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        return ProfilesFile.model_validate(raw)
+    except (OSError, yaml.YAMLError, ValidationError) as exc:
+        raise profile_invalid(f"Invalid profiles.yml: {exc}") from exc
+
+
+def select_profile(
+    profiles: ProfilesFile, name: str | None = None
+) -> tuple[str, ConnectionProfile]:
+    selected = name or profiles.default
+    try:
+        profile = profiles.profiles[selected]
+    except KeyError as exc:
+        raise profile_not_found(selected) from exc
+    validate_profile_uri(profile.uri)
+    return selected, profile.resolved(selected)
+
+
+def validate_profile_uri(uri: str) -> None:
+    try:
+        parsed = urlsplit(uri)
+        valid = parsed.scheme in {
+            "bolt",
+            "bolt+s",
+            "bolt+ssc",
+            "neo4j",
+            "neo4j+s",
+            "neo4j+ssc",
+        } and bool(parsed.hostname)
+        if parsed.port is not None and not 1 <= parsed.port <= 65535:
+            valid = False
+    except ValueError:
+        valid = False
+    if not valid:
+        raise profile_uri_invalid(uri)

graphcheck/contracts/check.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, model_validator
+
+from graphcheck.contracts.results import Pattern, Severity
+from graphcheck.contracts.scalars import JsonSchemaInteger
+from graphcheck.packs import REGISTRY
+from graphcheck.yaml_loader import DuplicateKeyError as DuplicateKeyError
+from graphcheck.yaml_loader import load_yaml_mapping
+
+
+class UnknownCheckError(ValueError):
+    """A conformance check references a `check` name not in the pack registry."""
+
+
+class SuiteValidationError(ValueError):
+    """A suite file is syntactically valid YAML but invalid as a GraphCheck suite."""
+
+
+def load_suite_yaml(text: str) -> dict:
+    try:
+        return load_yaml_mapping(text, description="a suite file")
+    except DuplicateKeyError:
+        raise
+    except ValueError as exc:
+        raise SuiteValidationError(str(exc)) from exc
+
+
+def _parse_severity(value: object) -> object:
+    if type(value) is str:
+        return Severity(value)
+    return value
+
+
+type SuiteSeverity = Annotated[Severity | None, BeforeValidator(_parse_severity)]
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+
+class Defaults(_Strict):
+    severity: SuiteSeverity = None
+    tags: list[str] = []
+
+
+class _Envelope(_Strict):
+    id: str
+    severity: SuiteSeverity = None
+    tags: list[str] = []
+    provenance: str | None = None
+    generated: bool = False
+
+
+class ConformanceCheck(_Envelope):
+    # No populate_by_name: the external key is the frozen `with` alias only, never `with_`.
+    check: str
+    with_: dict = Field(alias="with")  # required — SPEC-02 freezes `check` + `with` for conformance
+
+
+class RowBounds(_Strict):
+    min: JsonSchemaInteger | None = None
+    max: JsonSchemaInteger | None = None
+    exactly: JsonSchemaInteger | None = None
+
+    @model_validator(mode="after")
+    def _bounds_are_meaningful_and_consistent(self) -> RowBounds:
+        values = {"min": self.min, "max": self.max, "exactly": self.exactly}
+        if all(value is None for value in values.values()):
+            raise ValueError("rows must declare at least one of min, max, or exactly")
+        for name, value in values.items():
+            if value is not None and value < 0:
+                raise ValueError(f"rows.{name} must be non-negative")
+        if self.min is not None and self.max is not None and self.min > self.max:
+            raise ValueError("rows.min must not exceed rows.max")
+        if self.exactly is not None:
+            if self.min is not None and self.exactly < self.min:
+                raise ValueError("rows.exactly must not be less than rows.min")
+            if self.max is not None and self.exactly > self.max:
+                raise ValueError("rows.exactly must not exceed rows.max")
+        return self
+
+    def permits(self, count: int) -> bool:
+        if self.exactly is not None and count != self.exactly:
+            return False
+        if self.min is not None and count < self.min:
+            return False
+        return self.max is None or count <= self.max
+
+    def permits_nonempty(self) -> bool:
+        if self.exactly is not None:
+            return self.exactly > 0
+        return self.max is None or self.max > 0
+
+
+class Expect(_Strict):
+    rows: RowBounds | None = None
+    columns: list[str] | None = None
+    unique: bool | None = None
+    contains: list | None = None
+    equals: list | None = None
+    empty: bool | None = None
+
+    @model_validator(mode="after")
+    def _assertions_are_meaningful_and_consistent(self) -> Expect:
+        assertions = (
+            self.rows,
+            self.columns,
+            self.unique,
+            self.contains,
+            self.equals,
+            self.empty,
+        )
+        if all(assertion is None for assertion in assertions):
+            raise ValueError("expect must declare at least one assertion")
+        if self.contains == []:
+            raise ValueError("expect.contains must not be empty")
+
+        if self.rows is not None:
+            if self.empty is True and not self.rows.permits(0):
+                raise ValueError("expect.empty=true conflicts with expect.rows")
+            if self.empty is False and not self.rows.permits_nonempty():
+                raise ValueError("expect.empty=false conflicts with expect.rows")
+            if self.equals is not None and not self.rows.permits(len(self.equals)):
+                raise ValueError("expect.equals length conflicts with expect.rows")
+            if self.contains and not self.rows.permits_nonempty():
+                raise ValueError("expect.contains conflicts with expect.rows")
+
+        if self.empty is True:
+            if self.contains:
+                raise ValueError("expect.empty=true conflicts with expect.contains")
+            if self.equals is not None and self.equals:
+                raise ValueError("expect.empty=true conflicts with expect.equals")
+        elif self.empty is False and self.equals == []:
+            raise ValueError("expect.empty=false conflicts with empty expect.equals")
+
+        if (
+            self.contains is not None
+            and self.equals is not None
+            and any(value not in self.equals for value in self.contains)
+        ):
+            raise ValueError("expect.contains must be a subset of expect.equals")
+        return self
+
+
+class CompetencyCheck(_Envelope):
+    question: str
+    query: str
+    params: dict = {}
+    expect: Expect
+
+    @model_validator(mode="after")
+    def _content_is_valid(self) -> CompetencyCheck:
+        if not self.question.strip():
+            raise ValueError("competency question must not be blank")
+        if not self.query.strip():
+            raise ValueError("competency query must not be blank")
+        if any(not isinstance(key, str) for key in self.params):
+            raise ValueError("competency params keys must be strings")
+        return self
+
+
+class DriftCheck(_Envelope):
+    metric: str
+    target: dict
+    baseline: str = "latest"
+    tolerance: dict
+
+    @model_validator(mode="after")
+    def _content_is_valid(self) -> DriftCheck:
+        if not self.metric.strip():
+            raise ValueError("drift metric must not be blank")
+        if not self.baseline.strip():
+            raise ValueError("drift baseline must not be blank")
+        if not self.tolerance:
+            raise ValueError("drift tolerance must not be empty")
+        if any(not isinstance(key, str) for key in self.target):
+            raise ValueError("drift target keys must be strings")
+        if any(not isinstance(key, str) for key in self.tolerance):
+            raise ValueError("drift tolerance keys must be strings")
+        return self
+
+
+class LoadedCheck(_Strict):
+    id: str
+    pattern: Pattern
+    severity: Severity  # resolved (check -> defaults -> error)
+    tags: list[str]  # resolved (defaults + check)
+    provenance: str | None = None
+    generated: bool  # effective (file OR check)
+    spec: ConformanceCheck | CompetencyCheck | DriftCheck  # validated payload the engine executes
+
+
+class Suite(_Strict):
+    suite: str
+    checks: list[LoadedCheck]
+
+
+class _SuiteFile(_Strict):
+    suite: str | None = None  # optional in the file; falls back to the source filename stem
+    generated: bool = False
+    defaults: Defaults = Defaults()
+    conformance: list[ConformanceCheck] = []
+    competency: list[CompetencyCheck] = []
+    drift: list[DriftCheck] = []
+
+
+def _competency_pattern(expect: Expect) -> Pattern:
+    if expect.contains is not None or expect.equals is not None:
+        return Pattern.COMPETENCY_REGRESSION
+    return Pattern.COMPETENCY_SHAPE
+
+
+def load_suite(text: str, *, source: str | None = None) -> Suite:
+    raw = load_suite_yaml(text)
+    parsed = _SuiteFile.model_validate(raw)
+    suite_id = parsed.suite or (Path(source).stem if source else None)
+    if not suite_id:
+        raise SuiteValidationError("suite name required: no `suite:` key and no source filename")
+    defaults = parsed.defaults
+    checks: list[LoadedCheck] = []
+
+    def resolve(env: _Envelope, pattern: Pattern) -> LoadedCheck:
+        severity = env.severity or defaults.severity or Severity.ERROR
+        tags = list(dict.fromkeys([*defaults.tags, *env.tags]))
+        generated = parsed.generated or env.generated
+        return LoadedCheck(
+            id=env.id,
+            pattern=pattern,
+            severity=severity,
+            tags=tags,
+            provenance=env.provenance,
+            generated=generated,
+            spec=env,
+        )
+
+    for c in parsed.conformance:
+        if c.check not in REGISTRY:
+            raise UnknownCheckError(f"unknown check type: {c.check!r}")
+        # Validate `with` against the pack model AND keep the normalized result, so pack
+        # defaults (e.g. completeness threshold=1.0) survive onto spec.with_ for the engine.
+        c.with_ = REGISTRY[c.check].model_validate(c.with_).model_dump()
+        checks.append(resolve(c, Pattern.CONFORMANCE))
+    for c in parsed.competency:
+        checks.append(resolve(c, _competency_pattern(c.expect)))
+    for c in parsed.drift:
+        checks.append(resolve(c, Pattern.DRIFT))
+
+    seen: set[str] = set()
+    for lc in checks:
+        if lc.id in seen:
+            raise SuiteValidationError(f"duplicate check id {lc.id!r} in suite {suite_id!r}")
+        seen.add(lc.id)
+
+    return Suite(suite=suite_id, checks=checks)

graphcheck/contracts/profile.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Hashable
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from graphcheck.contracts.results import RunTarget
+
+SCHEMA_VERSION = "1.0"
+FINGERPRINT_ALGORITHM = "sha256"
+
+
+class ProfileStatus(StrEnum):
+    COMPLETE = "complete"
+    PARTIAL = "partial"
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        strict=True,
+    )
+
+
+class ProfileMetadata(_Strict):
+    generated_at: str
+    graphcheck_version: str
+
+
+class ProfileProperty(_Strict):
+    name: str
+    type: str
+
+
+class LabelProfile(_Strict):
+    name: str
+    count: int = Field(ge=0)
+    properties: list[ProfileProperty]
+    degree_distribution: DegreeDistribution | None
+
+
+class RelationshipTypeProfile(_Strict):
+    name: str
+    count: int = Field(ge=0)
+
+
+class ConstraintProfile(_Strict):
+    name: str
+    type: str
+    labels_or_types: list[str]
+    properties: list[str]
+
+
+class IndexProfile(_Strict):
+    name: str
+    type: str
+    labels_or_types: list[str]
+    properties: list[str]
+
+
+class GraphSchema(_Strict):
+    labels: list[LabelProfile]
+    relationship_types: list[RelationshipTypeProfile]
+    constraints: list[ConstraintProfile]
+    indexes: list[IndexProfile]
+
+
+class DegreeDistribution(_Strict):
+    median: float = Field(ge=0)
+    p95: float = Field(ge=0)
+    p99: float = Field(ge=0)
+    maximum: int = Field(ge=0)
+
+    @model_validator(mode="after")
+    def _percentiles_are_ordered(self) -> DegreeDistribution:
+        if not self.median <= self.p95 <= self.p99 <= self.maximum:
+            raise ValueError("degree distribution must satisfy median <= p95 <= p99 <= maximum")
+        return self
+
+
+class PropertyCoverage(_Strict):
+    owner: Literal["node", "relationship"]
+    owner_name: str
+    property: str
+    coverage: float = Field(ge=0, le=100)
+
+
+class ProfileStatistics(_Strict):
+    node_count: int = Field(ge=0)
+    relationship_count: int = Field(ge=0)
+    property_coverage: list[PropertyCoverage]
+
+
+class BaselineProfile(_Strict):
+    schema_version: Literal["1.0"]
+    status: ProfileStatus
+    partial_reason: str | None
+    target: RunTarget
+    metadata: ProfileMetadata
+    graph_schema: GraphSchema = Field(alias="schema")
+    statistics: ProfileStatistics
+    fingerprint: str
+
+    @model_validator(mode="after")
+    def _semantic_invariants(self) -> BaselineProfile:
+        if self.status is ProfileStatus.COMPLETE:
+            if self.partial_reason is not None:
+                raise ValueError("complete baseline must have partial_reason=null")
+
+            for label_profile in self.graph_schema.labels:
+                if label_profile.degree_distribution is None:
+                    raise ValueError(
+                        f"label {label_profile.name!r} must carry "
+                        "degree_distribution in a complete profile"
+                    )
+
+            for relationship_type in self.graph_schema.relationship_types:
+                if relationship_type.count > self.statistics.relationship_count:
+                    raise ValueError(
+                        f"schema.relationship_types[{relationship_type.name!r}].count "
+                        f"({relationship_type.count}) exceeds "
+                        f"statistics.relationship_count "
+                        f"({self.statistics.relationship_count})"
+                    )
+
+        elif not self.partial_reason:
+            raise ValueError("partial baseline must carry a non-empty partial_reason")
+
+        for label_profile in self.graph_schema.labels:
+            if label_profile.count > self.statistics.node_count:
+                raise ValueError(
+                    f"schema.labels[{label_profile.name!r}].count "
+                    f"({label_profile.count}) exceeds "
+                    f"statistics.node_count "
+                    f"({self.statistics.node_count})"
+                )
+
+        expected_fingerprint = profile_fingerprint(self.graph_schema, self.statistics)
+        if self.fingerprint != expected_fingerprint:
+            raise ValueError(
+                f"fingerprint must be {expected_fingerprint!r} for the v0 profile fingerprint input"
+            )
+
+        label_names = [label_profile.name for label_profile in self.graph_schema.labels]
+
+        _require_sorted("schema.labels", label_names)
+        _require_unique("schema.labels", label_names)
+
+        for label_profile in self.graph_schema.labels:
+            property_names = [prop.name for prop in label_profile.properties]
+
+            _require_sorted(
+                f"schema.labels[{label_profile.name!r}].properties",
+                property_names,
+            )
+            _require_unique(
+                f"schema.labels[{label_profile.name!r}].properties",
+                property_names,
+            )
+
+        relationship_names = [rel.name for rel in self.graph_schema.relationship_types]
+
+        _require_sorted(
+            "schema.relationship_types",
+            relationship_names,
+        )
+        _require_unique(
+            "schema.relationship_types",
+            relationship_names,
+        )
+
+        constraint_names = [constraint.name for constraint in self.graph_schema.constraints]
+
+        _require_sorted(
+            "schema.constraints",
+            constraint_names,
+        )
+        _require_unique(
+            "schema.constraints",
+            constraint_names,
+        )
+
+        for constraint in self.graph_schema.constraints:
+            _require_sorted(
+                f"schema.constraints[{constraint.name!r}].labels_or_types",
+                constraint.labels_or_types,
+            )
+
+            _require_unique(
+                f"schema.constraints[{constraint.name!r}].labels_or_types",
+                constraint.labels_or_types,
+            )
+            _require_sorted(
+                f"schema.constraints[{constraint.name!r}].properties",
+                constraint.properties,
+            )
+
+            _require_unique(
+                f"schema.constraints[{constraint.name!r}].properties",
+                constraint.properties,
+            )
+
+        index_names = [index.name for index in self.graph_schema.indexes]
+
+        _require_sorted(
+            "schema.indexes",
+            index_names,
+        )
+        _require_unique(
+            "schema.indexes",
+            index_names,
+        )
+
+        for index in self.graph_schema.indexes:
+            _require_sorted(
+                f"schema.indexes[{index.name!r}].labels_or_types",
+                index.labels_or_types,
+            )
+
+            _require_unique(
+                f"schema.indexes[{index.name!r}].labels_or_types",
+                index.labels_or_types,
+            )
+            _require_sorted(
+                f"schema.indexes[{index.name!r}].properties",
+                index.properties,
+            )
+            _require_unique(
+                f"schema.indexes[{index.name!r}].properties",
+                index.properties,
+            )
+
+        coverage_identities = [
+            (
+                coverage.owner,
+                coverage.owner_name,
+                coverage.property,
+            )
+            for coverage in self.statistics.property_coverage
+        ]
+
+        _require_sorted(
+            "statistics.property_coverage",
+            coverage_identities,
+        )
+
+        _require_unique(
+            "statistics.property_coverage",
+            coverage_identities,
+        )
+
+        return self
+
+
+def _require_sorted(field: str, values: list[object]) -> None:
+    """Ensure collections are canonically ordered."""
+    if values != sorted(values):
+        raise ValueError(f"{field} must be canonically sorted")
+
+
+def _require_unique(field: str, values: list[Hashable]) -> None:
+    """Ensure collections do not contain duplicate identities."""
+    if len(values) != len(set(values)):
+        raise ValueError(f"{field} must contain unique values")
+
+
+def fingerprint_input(
+    graph_schema: GraphSchema, statistics: ProfileStatistics
+) -> dict[str, object]:
+    return {
+        "labels": [label.model_dump() for label in graph_schema.labels],
+        "relationship_types": [
+            relationship_type.model_dump() for relationship_type in graph_schema.relationship_types
+        ],
+        "node_count": statistics.node_count,
+        "relationship_count": statistics.relationship_count,
+    }
+
+
+def profile_fingerprint(graph_schema: GraphSchema, statistics: ProfileStatistics) -> str:
+    raw = json.dumps(
+        fingerprint_input(graph_schema, statistics),
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode()
+    return f"{FINGERPRINT_ALGORITHM}:{hashlib.sha256(raw).hexdigest()}"