superseed 0.2.0__py3-none-any.whl

superseed/__init__.py

@@ -0,0 +1,21 @@
+"""SuperSeed — declarative Neo4j fixtures for pytest."""
+
+from superseed.compiler import CypherSeedPlan, compile_scenario
+from superseed.decorator import get_superseed_marker, super_seed
+from superseed.registry import Registry, load_registry
+from superseed.schema import Schema, load_schema
+from superseed.seeder import Neo4jSeeder
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "CypherSeedPlan",
+    "Neo4jSeeder",
+    "Registry",
+    "Schema",
+    "compile_scenario",
+    "get_superseed_marker",
+    "load_registry",
+    "load_schema",
+    "super_seed",
+]

superseed/cli.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from superseed.errors import SuperSeedError
+from superseed.registry import load_registry
+from superseed.scan.runner import default_schema_path, run_scan, validate_registry
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="SuperSeed — declarative Neo4j fixtures for pytest.",
+)
+
+
+def _resolve_config(config: Path | None) -> Path:
+    if config is not None:
+        if not config.is_file():
+            raise typer.BadParameter(f"Config file not found: {config}")
+        return config
+
+    discovered = Path("superseed.yaml")
+    if discovered.is_file():
+        return discovered
+
+    raise typer.BadParameter("Pass --config/-c or run from a directory with superseed.yaml")
+
+
+@app.command("validate")
+def validate_cmd(
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to superseed.yaml",
+    ),
+    schema: Path | None = typer.Option(
+        None,
+        "--schema",
+        help="Optional schema YAML (defaults to movies.schema.yaml beside config)",
+    ),
+) -> None:
+    """Parse superseed.yaml and optional schema; exit 1 on error."""
+    config_path = _resolve_config(config)
+    schema_path = schema or default_schema_path(config_path)
+    try:
+        registry = validate_registry(config_path, schema_path)
+    except SuperSeedError as exc:
+        typer.secho(f"Validation failed: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo(f"Valid: {config_path} ({len(registry.scenarios)} scenarios)")
+
+
+@app.command("list")
+def list_cmd(
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to superseed.yaml",
+    ),
+) -> None:
+    """Print scenario names and descriptions."""
+    config_path = _resolve_config(config)
+    registry = load_registry(config_path)
+    for name in sorted(registry.scenarios):
+        scenario = registry.scenarios[name]
+        description = scenario.description or "(no description)"
+        typer.echo(f"{name}\t{description}")
+
+
+@app.command("scan")
+def scan_cmd(
+    path: Path = typer.Argument(..., help="Repository file or directory to scan"),
+    output: Path = typer.Option(
+        Path(".superseed"),
+        "--output",
+        "-o",
+        help="Directory for suggested YAML and repo_index.json",
+    ),
+) -> None:
+    """Extract Cypher from repository modules and write suggested scenario stubs."""
+    if not path.exists():
+        raise typer.BadParameter(f"Scan path not found: {path}")
+
+    try:
+        queries, suggested_dir, index_path = run_scan(path, output)
+    except SuperSeedError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo(f"Scanned {len(queries)} repository method(s)")
+    typer.echo(f"Suggested stubs: {suggested_dir}")
+    typer.echo(f"Repo index: {index_path}")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

superseed/compiler.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from superseed.errors import SuperSeedError
+from superseed.registry import Scenario, ScenarioNode, ScenarioRelationship
+from superseed.schema import Schema, validate_scenario_nodes
+
+PARAM_PATTERN = re.compile(r"\$\{([a-z][a-z0-9_]*)\}")
+
+
+@dataclass(frozen=True)
+class CypherStatement:
+    query: str
+    parameters: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class CypherSeedPlan:
+    run_id: str
+    statements: list[CypherStatement] = field(default_factory=list)
+
+
+def _interpolate_params(value: Any, params: dict[str, Any]) -> Any:
+    if isinstance(value, str):
+
+        def repl(match: re.Match[str]) -> str:
+            name = match.group(1)
+            if name not in params:
+                msg = f"Unknown scenario parameter: {name}"
+                raise SuperSeedError(msg)
+            return str(params[name])
+
+        return PARAM_PATTERN.sub(repl, value)
+    if isinstance(value, dict):
+        return {key: _interpolate_params(item, params) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_interpolate_params(item, params) for item in value]
+    return value
+
+
+def _resolved_node_props(
+    node: ScenarioNode,
+    params: dict[str, Any],
+    defaults: dict[str, dict[str, Any]],
+    schema: Schema | None,
+    *,
+    run_id: str,
+    index: int,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    key = _interpolate_params(node.key, params)
+    props: dict[str, Any] = {}
+    if schema is not None:
+        label_schema = schema.labels.get(node.label)
+        if label_schema is not None:
+            props.update(label_schema.defaults)
+    props.update(defaults.get(node.label, {}))
+    props.update(_interpolate_params(node.props, params))
+
+    merged = {**props, **key}
+    if "id" not in merged:
+        merged["id"] = f"{run_id}-{node.label.lower()}-{index}"
+
+    non_key_props = {name: value for name, value in merged.items() if name not in key}
+    return key, non_key_props
+
+
+def _compile_node(
+    node: ScenarioNode,
+    *,
+    params: dict[str, Any],
+    defaults: dict[str, dict[str, Any]],
+    schema: Schema | None,
+    run_id: str,
+    index: int,
+) -> CypherStatement:
+    key, props = _resolved_node_props(
+        node,
+        params,
+        defaults,
+        schema,
+        run_id=run_id,
+        index=index,
+    )
+    key_match = ", ".join(f"{prop}: ${prop}" for prop in key)
+    set_clauses = [f"n.{prop} = ${prop}" for prop in props]
+    set_clauses.append("n.testRunId = $run_id")
+    query = f"MERGE (n:{node.label} {{{key_match}}})\nSET {', '.join(set_clauses)}"
+    parameters = {**key, **props, "run_id": run_id}
+    return CypherStatement(query=query, parameters=parameters)
+
+
+def _compile_relationship(
+    relationship: ScenarioRelationship,
+    *,
+    params: dict[str, Any],
+    run_id: str,
+    index: int,
+) -> CypherStatement:
+    from_key = _interpolate_params(relationship.from_.key, params)
+    to_key = _interpolate_params(relationship.to.key, params)
+    rel_props = _interpolate_params(relationship.props, params)
+
+    from_match = ", ".join(f"{prop}: $from_{prop}" for prop in from_key)
+    to_match = ", ".join(f"{prop}: $to_{prop}" for prop in to_key)
+    from_params = {f"from_{prop}": value for prop, value in from_key.items()}
+    to_params = {f"to_{prop}": value for prop, value in to_key.items()}
+
+    set_clauses = [f"r.{prop} = $rel_{prop}" for prop in rel_props]
+    rel_params = {f"rel_{prop}": value for prop, value in rel_props.items()}
+    set_statement = f"SET {', '.join(set_clauses)}" if set_clauses else ""
+
+    query = f"""
+MATCH (a:{relationship.from_.label} {{{from_match}}})
+MATCH (b:{relationship.to.label} {{{to_match}}})
+MERGE (a)-[r:{relationship.type}]->(b)
+{set_statement}
+""".strip()
+
+    return CypherStatement(
+        query=query,
+        parameters={**from_params, **to_params, **rel_params},
+    )
+
+
+def compile_scenario(
+    scenario: Scenario,
+    *,
+    defaults: dict[str, dict[str, Any]] | None = None,
+    overrides: dict[str, Any] | None = None,
+    run_id: str,
+    schema: Schema | None = None,
+) -> CypherSeedPlan:
+    registry_defaults = defaults or {}
+    params = {**scenario.parameters, **(overrides or {})}
+    validate_scenario_nodes(scenario, registry_defaults=registry_defaults, schema=schema)
+
+    statements: list[CypherStatement] = []
+    for index, node in enumerate(scenario.nodes):
+        statements.append(
+            _compile_node(
+                node,
+                params=params,
+                defaults=registry_defaults,
+                schema=schema,
+                run_id=run_id,
+                index=index,
+            )
+        )
+
+    for index, relationship in enumerate(scenario.relationships):
+        statements.append(
+            _compile_relationship(
+                relationship,
+                params=params,
+                run_id=run_id,
+                index=index,
+            )
+        )
+
+    return CypherSeedPlan(run_id=run_id, statements=statements)

superseed/decorator.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import pytest
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def super_seed(scenario: str, /, **overrides: Any) -> Callable[[F], F]:
+    def wrap(fn: F) -> F:
+        setattr(
+            fn,
+            "__superseed__",
+            {
+                "mode": "explicit",
+                "scenario": scenario,
+                "overrides": overrides,
+            },
+        )
+        return fn
+
+    return wrap
+
+
+def get_superseed_marker(item: pytest.Item) -> dict[str, Any] | None:
+    if not hasattr(item, "obj") or item.obj is None:
+        return None
+
+    meta = getattr(item.obj, "__superseed__", None)
+    if meta is None:
+        return None
+
+    return {
+        "mode": meta.get("mode", "explicit"),
+        "scenario": meta["scenario"],
+        "overrides": meta.get("overrides", {}),
+    }

superseed/errors.py

@@ -0,0 +1,10 @@
+class SuperSeedError(Exception):
+    """Base error for SuperSeed."""
+
+
+class ScenarioNotFoundError(SuperSeedError):
+    """Raised when a named scenario is missing from the registry."""
+
+
+class SchemaValidationError(SuperSeedError):
+    """Raised when scenario data violates the label schema."""

superseed/plugin.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+import pytest
+
+from superseed.compiler import compile_scenario
+from superseed.decorator import get_superseed_marker
+from superseed.errors import ScenarioNotFoundError
+from superseed.registry import get_scenario, load_registry
+from superseed.schema import Schema, load_schema
+from superseed.seeder import Neo4jSeeder
+
+RUN_ID_ATTR = "_superseed_run_id"
+REGISTRY_ATTR = "_superseed_registry"
+
+
+def find_upward(start: Path, filename: str) -> Path | None:
+    for directory in (start, *start.parents):
+        candidate = directory / filename
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def resolve_config_path(item: pytest.Item, config: pytest.Config) -> Path:
+    option = config.getoption("--superseed-config")
+    configured = Path(option)
+    if configured.is_file():
+        return configured
+
+    start = Path(str(item.fspath)).parent
+    discovered = find_upward(start, option)
+    if discovered is not None:
+        return discovered
+
+    msg = f"SuperSeed config not found: {option} (searched upward from {start})"
+    raise pytest.UsageError(msg)
+
+
+def resolve_schema_path(config_path: Path, pytest_config: pytest.Config) -> Path | None:
+    option = pytest_config.getoption("--superseed-schema")
+    if option:
+        schema_path = Path(option)
+        if schema_path.is_file():
+            return schema_path
+        msg = f"SuperSeed schema file not found: {schema_path}"
+        raise pytest.UsageError(msg)
+
+    for name in ("movies.schema.yaml", "superseed.schema.yaml"):
+        candidate = config_path.parent / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_schema_for_config(config_path: Path, pytest_config: pytest.Config) -> Schema | None:
+    schema_path = resolve_schema_path(config_path, pytest_config)
+    if schema_path is None:
+        return None
+    return load_schema(schema_path)
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    parser.addoption(
+        "--superseed-config",
+        action="store",
+        default="superseed.yaml",
+        help="Path to superseed.yaml or filename to search upward from the test module",
+    )
+    parser.addoption(
+        "--superseed-schema",
+        action="store",
+        default=None,
+        help="Optional schema YAML path (defaults to movies.schema.yaml beside the config)",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line(
+        "markers",
+        "superseed: marks a test that seeds Neo4j data via @super_seed (dynamically applied)",
+    )
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_runtest_setup(item: pytest.Item) -> None:
+    marker = get_superseed_marker(item)
+    if marker is None:
+        return
+
+    config_path = resolve_config_path(item, item.config)
+    registry = load_registry(config_path)
+    scenario_name = marker["scenario"]
+
+    try:
+        scenario = get_scenario(registry, scenario_name)
+    except ScenarioNotFoundError as exc:
+        raise exc
+
+    schema = load_schema_for_config(config_path, item.config)
+    run_id = str(uuid.uuid4())
+    plan = compile_scenario(
+        scenario,
+        defaults=registry.defaults,
+        overrides=marker["overrides"],
+        run_id=run_id,
+        schema=schema,
+    )
+
+    setattr(item, RUN_ID_ATTR, run_id)
+    setattr(item, REGISTRY_ATTR, registry)
+    Neo4jSeeder(registry.neo4j).seed(plan)
+
+
+@pytest.hookimpl(trylast=True)
+def pytest_runtest_teardown(item: pytest.Item) -> None:
+    run_id = getattr(item, RUN_ID_ATTR, None)
+    registry = getattr(item, REGISTRY_ATTR, None)
+    if run_id is None or registry is None:
+        return
+    Neo4jSeeder(registry.neo4j).cleanup(run_id)

superseed/registry.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from superseed.errors import ScenarioNotFoundError, SuperSeedError
+
+ENV_PATTERN = re.compile(r"\$\{([A-Z][A-Z0-9_]*)(?::-([^}]*))?\}")
+
+
+@dataclass(frozen=True)
+class Neo4jConfig:
+    uri: str
+    user: str
+    password: str
+
+
+@dataclass(frozen=True)
+class NodeEndpoint:
+    label: str
+    key: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ScenarioNode:
+    label: str
+    key: dict[str, Any]
+    props: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ScenarioRelationship:
+    type: str
+    from_: NodeEndpoint
+    to: NodeEndpoint
+    props: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Scenario:
+    name: str
+    parameters: dict[str, Any] = field(default_factory=dict)
+    nodes: list[ScenarioNode] = field(default_factory=list)
+    relationships: list[ScenarioRelationship] = field(default_factory=list)
+    description: str | None = None
+    linked_repository: str | None = None
+    required_labels: list[str] = field(default_factory=list)
+    required_relationships: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Registry:
+    neo4j: Neo4jConfig
+    defaults: dict[str, dict[str, Any]]
+    scenarios: dict[str, Scenario]
+    path: Path
+
+
+def resolve_env_vars(value: Any) -> Any:
+    if isinstance(value, str):
+        def repl(match: re.Match[str]) -> str:
+            name = match.group(1)
+            default = match.group(2)
+            if name in os.environ:
+                return os.environ[name]
+            if default is not None:
+                return default
+            msg = f"Missing environment variable: {name}"
+            raise SuperSeedError(msg)
+
+        return ENV_PATTERN.sub(repl, value)
+    if isinstance(value, dict):
+        return {key: resolve_env_vars(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [resolve_env_vars(item) for item in value]
+    return value
+
+
+def _parse_endpoint(raw: dict[str, Any]) -> NodeEndpoint:
+    label = raw.get("label")
+    key = raw.get("key")
+    if not isinstance(label, str) or not isinstance(key, dict):
+        msg = "Relationship endpoint requires string label and dict key"
+        raise SuperSeedError(msg)
+    return NodeEndpoint(label=label, key=key)
+
+
+def _parse_scenario(name: str, raw: dict[str, Any]) -> Scenario:
+    nodes: list[ScenarioNode] = []
+    for node in raw.get("nodes", []):
+        if not isinstance(node, dict):
+            msg = f"Scenario {name!r} has invalid node entry"
+            raise SuperSeedError(msg)
+        label = node.get("label")
+        key = node.get("key")
+        if not isinstance(label, str) or not isinstance(key, dict):
+            msg = f"Scenario {name!r} node requires label and key"
+            raise SuperSeedError(msg)
+        props = node.get("props", {})
+        if not isinstance(props, dict):
+            msg = f"Scenario {name!r} node props must be a mapping"
+            raise SuperSeedError(msg)
+        nodes.append(ScenarioNode(label=label, key=key, props=props))
+
+    relationships: list[ScenarioRelationship] = []
+    for rel in raw.get("relationships", []):
+        if not isinstance(rel, dict):
+            msg = f"Scenario {name!r} has invalid relationship entry"
+            raise SuperSeedError(msg)
+        rel_type = rel.get("type")
+        from_raw = rel.get("from")
+        to_raw = rel.get("to")
+        if (
+            not isinstance(rel_type, str)
+            or not isinstance(from_raw, dict)
+            or not isinstance(to_raw, dict)
+        ):
+            msg = f"Scenario {name!r} relationship requires type, from, and to"
+            raise SuperSeedError(msg)
+        props = rel.get("props", {})
+        if not isinstance(props, dict):
+            msg = f"Scenario {name!r} relationship props must be a mapping"
+            raise SuperSeedError(msg)
+        relationships.append(
+            ScenarioRelationship(
+                type=rel_type,
+                from_=_parse_endpoint(from_raw),
+                to=_parse_endpoint(to_raw),
+                props=props,
+            )
+        )
+
+    parameters = raw.get("parameters", {})
+    if not isinstance(parameters, dict):
+        msg = f"Scenario {name!r} parameters must be a mapping"
+        raise SuperSeedError(msg)
+
+    description = raw.get("description")
+    if description is not None and not isinstance(description, str):
+        msg = f"Scenario {name!r} description must be a string"
+        raise SuperSeedError(msg)
+
+    linked_repository = raw.get("linked_repository")
+    if linked_repository is not None and not isinstance(linked_repository, str):
+        msg = f"Scenario {name!r} linked_repository must be a string"
+        raise SuperSeedError(msg)
+
+    required_labels = raw.get("required_labels", [])
+    if not isinstance(required_labels, list) or not all(
+        isinstance(item, str) for item in required_labels
+    ):
+        msg = f"Scenario {name!r} required_labels must be a list of strings"
+        raise SuperSeedError(msg)
+
+    required_relationships = raw.get("required_relationships", [])
+    if not isinstance(required_relationships, list) or not all(
+        isinstance(item, str) for item in required_relationships
+    ):
+        msg = f"Scenario {name!r} required_relationships must be a list of strings"
+        raise SuperSeedError(msg)
+
+    return Scenario(
+        name=name,
+        parameters=parameters,
+        nodes=nodes,
+        relationships=relationships,
+        description=description,
+        linked_repository=linked_repository,
+        required_labels=required_labels,
+        required_relationships=required_relationships,
+    )
+
+
+def load_registry(path: str | Path) -> Registry:
+    config_path = Path(path)
+    raw_text = config_path.read_text(encoding="utf-8")
+    raw = yaml.safe_load(raw_text)
+    if not isinstance(raw, dict):
+        msg = f"Invalid registry file: {config_path}"
+        raise SuperSeedError(msg)
+
+    resolved = resolve_env_vars(raw)
+
+    neo4j_raw = resolved.get("neo4j", {})
+    if not isinstance(neo4j_raw, dict):
+        msg = "Registry requires a neo4j mapping"
+        raise SuperSeedError(msg)
+
+    uri = neo4j_raw.get("uri")
+    user = neo4j_raw.get("user")
+    password = neo4j_raw.get("password")
+    if not isinstance(uri, str) or not isinstance(user, str) or not isinstance(password, str):
+        msg = "neo4j.uri, neo4j.user, and neo4j.password must be strings"
+        raise SuperSeedError(msg)
+
+    defaults = resolved.get("defaults", {})
+    if not isinstance(defaults, dict):
+        msg = "Registry defaults must be a mapping"
+        raise SuperSeedError(msg)
+
+    scenarios_raw = resolved.get("scenarios", {})
+    if not isinstance(scenarios_raw, dict):
+        msg = "Registry scenarios must be a mapping"
+        raise SuperSeedError(msg)
+
+    scenarios = {
+        name: _parse_scenario(name, scenario_raw)
+        for name, scenario_raw in scenarios_raw.items()
+        if isinstance(scenario_raw, dict)
+    }
+
+    return Registry(
+        neo4j=Neo4jConfig(uri=uri, user=user, password=password),
+        defaults=defaults,
+        scenarios=scenarios,
+        path=config_path,
+    )
+
+
+def get_scenario(registry: Registry, name: str) -> Scenario:
+    try:
+        return registry.scenarios[name]
+    except KeyError as exc:
+        raise ScenarioNotFoundError(f"Scenario not found: {name}") from exc