devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/implementation/test_runtime.py

@@ -0,0 +1,623 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import tomllib
+
+from ..llm.execution_context import get_execution_context
+
+
+REPO_TEST_RUNTIME_DEFAULTS = Path(".devflow") / "test_runtime.json"
+REPO_RED_CONFIG = Path(".redconfig.jsonc")
+_STORY_TEST_SUFFIXES = {".py", ".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"}
+
+
+def _pytest_marker_examples() -> list[str]:
+    return [
+        "pytestmark = [",
+        '    pytest.mark.story_id("<story_id>"),',
+        '    pytest.mark.story_uuid("<story_uuid>"),',
+        '    pytest.mark.plane("<plane>"),',
+        "]",
+    ]
+
+
+def _pytest_runtime_notes() -> list[str]:
+    return [
+        "For Python pytest files, use a valid module-level `pytestmark = [...]` assignment or function/class decorators for story markers.",
+        "Do not place bare `@pytest.mark.*` decorators at Python module top level before the module docstring or imports; that shape is invalid syntax.",
+    ]
+
+
+def _is_legacy_pytest_marker_examples(marker_examples: list[str]) -> bool:
+    return any(example.strip().startswith("@pytest.mark.") for example in marker_examples)
+
+
+def repo_test_runtime_defaults_path(repo_root: Path) -> Path:
+    return repo_root / REPO_TEST_RUNTIME_DEFAULTS
+
+
+def repo_red_config_path(repo_root: Path) -> Path:
+    return repo_root / REPO_RED_CONFIG
+
+
+def _parse_jsonc(text: str) -> Any:
+    """Strip ``//`` line comments and ``/* */`` block comments then JSON-parse.
+
+    Comments inside JSON string literals are preserved.
+    """
+    result: list[str] = []
+    i = 0
+    length = len(text)
+    while i < length:
+        # String literal – copy verbatim (including any // or /* inside)
+        if text[i] == '"':
+            j = i + 1
+            while j < length:
+                if text[j] == '\\':
+                    j += 2
+                    continue
+                if text[j] == '"':
+                    j += 1
+                    break
+                j += 1
+            result.append(text[i:j])
+            i = j
+        # Line comment
+        elif text[i:i + 2] == '//':
+            j = text.find('\n', i)
+            if j == -1:
+                break
+            i = j  # keep the newline itself
+        # Block comment
+        elif text[i:i + 2] == '/*':
+            j = text.find('*/', i + 2)
+            if j == -1:
+                break
+            i = j + 2
+        else:
+            result.append(text[i])
+            i += 1
+    return json.loads("".join(result))
+
+
+def story_test_runtime_contract_path(*, repo_root: Path, story_id: str) -> Path:
+    safe_story_id = re.sub(r"[^A-Za-z0-9_.-]+", "_", story_id) or "unknown_story"
+    return _story_state_root(repo_root=repo_root) / safe_story_id / "test_runtime.json"
+
+
+def _story_state_root(*, repo_root: Path) -> Path:
+    ctx = get_execution_context() or {}
+    override = str(ctx.get("devflow_story_state_root") or "").strip()
+    if override:
+        return Path(override)
+    return repo_root / ".devflow" / "stories"
+
+
+def _load_json_if_exists(path: Path) -> dict[str, Any] | None:
+    if not path.exists() or not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _load_jsonc_if_exists(path: Path) -> dict[str, Any] | None:
+    if not path.exists() or not path.is_file():
+        return None
+    try:
+        payload = _parse_jsonc(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _string_map(raw: Any) -> dict[str, str]:
+    if not isinstance(raw, dict):
+        return {}
+    normalized: dict[str, str] = {}
+    for key, value in raw.items():
+        key_text = str(key or "").strip()
+        if not key_text:
+            continue
+        normalized[key_text] = str(value)
+    return normalized
+
+
+def _string_list(raw: Any) -> list[str]:
+    if isinstance(raw, (list, tuple)):
+        return [str(item) for item in raw if str(item).strip()]
+    return []
+
+
+def _bool_value(raw: Any) -> bool | None:
+    if isinstance(raw, bool):
+        return raw
+    return None
+
+
+def infer_test_runtime_contract(repo_root: Path) -> dict[str, Any]:
+    package_json = repo_root / "package.json"
+    pyproject_toml = repo_root / "pyproject.toml"
+    pytest_examples: list[Path] = []
+    for pattern in ("tests/**/*.py", "fastapi_backend/tests/**/*.py", "backend/tests/**/*.py"):
+        pytest_examples.extend(
+            [
+                p for p in sorted(repo_root.glob(pattern))
+                if p.is_file() and "__pycache__" not in p.parts
+            ]
+        )
+    vitest_examples: list[Path] = []
+    for pattern in (
+        "tests/**/*.test.ts",
+        "tests/**/*.spec.ts",
+        "tests/**/*.test.js",
+        "tests/**/*.spec.js",
+        "tests/**/*.test.mjs",
+        "tests/**/*.spec.mjs",
+    ):
+        vitest_examples.extend([p for p in sorted(repo_root.glob(pattern)) if p.is_file()])
+    if package_json.exists():
+        try:
+            pkg = json.loads(package_json.read_text(encoding="utf-8"))
+        except Exception:
+            pkg = {}
+        deps = {
+            **dict(pkg.get("dependencies") or {}),
+            **dict(pkg.get("devDependencies") or {}),
+        }
+        scripts = dict(pkg.get("scripts") or {})
+        if "vitest" in deps or any("vitest" in str(value) for value in scripts.values()):
+            example_paths = [str(p.relative_to(repo_root)) for p in vitest_examples[:3]]
+            return {
+                "framework": "vitest",
+                "cwd": ".",
+                "env": {},
+                "test_paths": [],
+                "run_cmd": ["npx", "vitest", "run"],
+                "file_globs": [
+                    "tests/**/*.test.ts",
+                    "tests/**/*.spec.ts",
+                    "tests/**/*.test.js",
+                    "tests/**/*.spec.js",
+                ],
+                "marker_format": "comment",
+                "marker_examples": [
+                    "// @story_id: <story_id>",
+                    "// @story_uuid: <story_uuid>",
+                    "// @plane: <plane>",
+                ],
+                "example_paths": example_paths,
+                "source": "inferred",
+            }
+    if pyproject_toml.exists():
+        try:
+            cfg = tomllib.loads(pyproject_toml.read_text(encoding="utf-8"))
+        except Exception:
+            cfg = {}
+        project = dict(cfg.get("project") or {})
+        deps = [str(item) for item in project.get("dependencies") or []]
+        tool = cfg.get("tool", {}) if isinstance(cfg.get("tool"), dict) else {}
+        if "pytest" in " ".join(deps).lower() or "pytest" in json.dumps(tool).lower() or pytest_examples:
+            example_paths = [str(p.relative_to(repo_root)) for p in pytest_examples[:3]]
+            return {
+                "framework": "pytest",
+                "cwd": ".",
+                "env": {},
+                "test_paths": [],
+                "run_cmd": [sys.executable or "python3", "-m", "pytest"],
+                "file_globs": ["tests/**/*.py"],
+                "marker_format": "pytest_decorator",
+                "marker_examples": _pytest_marker_examples(),
+                "notes": _pytest_runtime_notes(),
+                "example_paths": example_paths,
+                "source": "inferred",
+            }
+    example_paths = [str(p.relative_to(repo_root)) for p in pytest_examples[:3]]
+    return {
+        "framework": "pytest",
+        "cwd": ".",
+        "env": {},
+        "test_paths": [],
+        "run_cmd": [sys.executable or "python3", "-m", "pytest"],
+        "file_globs": ["tests/**/*.py"],
+        "marker_format": "pytest_decorator",
+        "marker_examples": _pytest_marker_examples(),
+        "notes": _pytest_runtime_notes(),
+        "example_paths": example_paths,
+        "source": "inferred",
+    }
+
+
+def _normalize_loaded_runtime_contract(
+    *,
+    repo_root: Path,
+    contract: dict[str, Any],
+    story_id: str,
+    story_uuid: str | None = None,
+    source: str,
+    fallback: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return normalize_story_runtime_contract(
+        repo_root=repo_root,
+        contract=contract,
+        story_id=story_id,
+        story_uuid=story_uuid,
+        source=source,
+        fallback=fallback,
+    )
+
+
+def load_repo_test_runtime_defaults(repo_root: Path) -> dict[str, Any] | None:
+    payload = _load_json_if_exists(repo_test_runtime_defaults_path(repo_root)) or {}
+    redconfig_payload = _load_jsonc_if_exists(repo_red_config_path(repo_root)) or {}
+    if not payload and not redconfig_payload:
+        return None
+    payload = _merge_contract(payload, redconfig_payload)
+    normalized: dict[str, Any] = {}
+    framework = str(payload.get("framework") or "").strip()
+    if framework:
+        normalized["framework"] = framework
+    run_cmd = _string_list(payload.get("run_cmd") or payload.get("runner"))
+    if run_cmd:
+        normalized["run_cmd"] = run_cmd
+    cwd = str(payload.get("cwd") or "").strip()
+    if cwd:
+        normalized["cwd"] = cwd
+    env = _string_map(payload.get("env"))
+    if env:
+        normalized["env"] = env
+    setup_cmd = _string_list(payload.get("setup_cmd"))
+    if setup_cmd:
+        normalized["setup_cmd"] = setup_cmd
+    test_path_strip_prefix = str(payload.get("test_path_strip_prefix") or "").strip()
+    if test_path_strip_prefix:
+        normalized["test_path_strip_prefix"] = test_path_strip_prefix
+    file_globs = _string_list(payload.get("file_globs"))
+    if file_globs:
+        normalized["file_globs"] = file_globs
+    marker_format = str(payload.get("marker_format") or "").strip()
+    if marker_format:
+        normalized["marker_format"] = marker_format
+    marker_examples = _string_list(payload.get("marker_examples"))
+    if marker_examples:
+        normalized["marker_examples"] = marker_examples
+    example_paths = _string_list(payload.get("example_paths"))
+    if example_paths:
+        normalized["example_paths"] = example_paths
+    test_paths = _string_list(payload.get("test_paths"))
+    if test_paths:
+        normalized["test_paths"] = test_paths
+    notes = _string_list(payload.get("notes"))
+    if notes:
+        normalized["notes"] = notes
+    command_verified = _bool_value(payload.get("command_verified"))
+    if command_verified is not None:
+        normalized["command_verified"] = command_verified
+    command_verification_mode = str(payload.get("command_verification_mode") or "").strip()
+    if command_verification_mode:
+        normalized["command_verification_mode"] = command_verification_mode
+    verified_run_cmd = _string_list(payload.get("verified_run_cmd"))
+    if verified_run_cmd:
+        normalized["verified_run_cmd"] = verified_run_cmd
+    canonical_test_cmd = _string_list(payload.get("canonical_test_cmd"))
+    if canonical_test_cmd:
+        normalized["canonical_test_cmd"] = canonical_test_cmd
+    canonical_test_cwd = str(payload.get("canonical_test_cwd") or "").strip()
+    if canonical_test_cwd:
+        normalized["canonical_test_cwd"] = canonical_test_cwd
+    normalized["source"] = "repo_defaults"
+    normalized = _normalize_loaded_runtime_contract(
+        repo_root=repo_root,
+        contract=normalized,
+        story_id=str(normalized.get("story_id") or "repo_defaults"),
+        story_uuid=str(normalized.get("story_uuid") or "").strip() or None,
+        source="repo_defaults",
+    )
+    normalized.pop("story_id", None)
+    normalized.pop("story_uuid", None)
+    if not normalized.get("test_paths"):
+        normalized.pop("test_paths", None)
+    if not normalized.get("example_paths"):
+        normalized.pop("example_paths", None)
+    return normalized
+
+
+def load_story_test_runtime_contract(*, repo_root: Path, story_id: str) -> dict[str, Any] | None:
+    path = story_test_runtime_contract_path(repo_root=repo_root, story_id=story_id)
+    payload = _load_json_if_exists(path)
+    if payload is None:
+        return None
+    normalized = _normalize_loaded_runtime_contract(
+        repo_root=repo_root,
+        contract=payload,
+        story_id=story_id,
+        story_uuid=str(payload.get("story_uuid") or "").strip() or None,
+        source=str(payload.get("source") or "story_runtime_contract"),
+        fallback=load_repo_test_runtime_defaults(repo_root),
+    )
+    if normalized != payload:
+        persist_story_runtime_contract(repo_root=repo_root, contract=normalized)
+    return normalized
+
+
+def discover_story_scoped_test_paths(*, repo_root: Path, story_id: str | None = None, story_uuid: str | None = None) -> list[str]:
+    needles = [str(story_id or "").strip(), str(story_uuid or "").strip()]
+    needles = [needle for needle in needles if needle]
+    if not needles:
+        return []
+    roots = [
+        repo_root / "tests",
+        repo_root / "fastapi_backend" / "tests",
+        repo_root / "frontend" / "tests",
+        repo_root / "backend" / "tests",
+    ]
+    discovered: list[str] = []
+    seen: set[str] = set()
+    for tests_dir in roots:
+        if not tests_dir.exists():
+            continue
+        for path in sorted(tests_dir.rglob("*")):
+            if not path.is_file() or path.name.startswith(".") or path.suffix not in _STORY_TEST_SUFFIXES:
+                continue
+            try:
+                content = path.read_text(encoding="utf-8")
+            except Exception:
+                continue
+            if not any(needle in content for needle in needles):
+                continue
+            rel = str(path.relative_to(repo_root))
+            if rel in seen:
+                continue
+            seen.add(rel)
+            discovered.append(rel)
+    return discovered
+
+
+def _merge_contract(base: dict[str, Any], overlay: dict[str, Any] | None) -> dict[str, Any]:
+    if not overlay:
+        return dict(base)
+    merged = dict(base)
+    for key, value in overlay.items():
+        if key == "env":
+            merged["env"] = {**_string_map(base.get("env")), **_string_map(value)}
+            continue
+        if key == "test_path_strip_prefix":
+            prefix = str(value or "").strip()
+            if prefix:
+                merged[key] = prefix
+            else:
+                merged.pop(key, None)
+            continue
+        if key in {"notes", "test_paths", "example_paths", "marker_examples", "file_globs", "verified_run_cmd", "canonical_test_cmd"}:
+            merged[key] = _string_list(value)
+            continue
+        if key in {"run_cmd", "setup_cmd", "runner"}:
+            argv = _string_list(value)
+            if argv:
+                merged["run_cmd" if key in {"run_cmd", "runner"} else key] = argv
+            continue
+        if key == "command_verified":
+            verified = _bool_value(value)
+            if verified is not None:
+                merged[key] = verified
+            continue
+        if key == "command_verification_mode":
+            mode = str(value or "").strip()
+            if mode:
+                merged[key] = mode
+            else:
+                merged.pop(key, None)
+            continue
+        if key == "canonical_test_cwd":
+            cwd = str(value or "").strip()
+            if cwd:
+                merged[key] = cwd
+            else:
+                merged.pop(key, None)
+            continue
+        merged[key] = value
+    return merged
+
+
+def normalize_story_runtime_contract(
+    *,
+    repo_root: Path,
+    contract: dict[str, Any],
+    story_id: str,
+    story_uuid: str | None = None,
+    source: str,
+    fallback: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    base = infer_test_runtime_contract(repo_root)
+    if fallback:
+        base = _merge_contract(base, fallback)
+    merged = _merge_contract(base, contract)
+    normalized = dict(merged)
+    normalized["framework"] = str(normalized.get("framework") or base.get("framework") or "pytest").strip() or "pytest"
+    normalized["cwd"] = str(normalized.get("cwd") or ".").strip() or "."
+    normalized["run_cmd"] = _string_list(normalized.get("run_cmd")) or _string_list(base.get("run_cmd")) or [sys.executable or "python3", "-m", "pytest"]
+    normalized["env"] = _string_map(normalized.get("env"))
+    normalized["test_paths"] = _string_list(normalized.get("test_paths"))
+    test_path_strip_prefix = str(normalized.get("test_path_strip_prefix") or "").strip()
+    if test_path_strip_prefix:
+        normalized["test_path_strip_prefix"] = test_path_strip_prefix
+    else:
+        normalized.pop("test_path_strip_prefix", None)
+    normalized["story_id"] = story_id
+    if story_uuid:
+        normalized["story_uuid"] = story_uuid
+    if normalized.get("setup_cmd"):
+        normalized["setup_cmd"] = _string_list(normalized.get("setup_cmd"))
+    else:
+        normalized.pop("setup_cmd", None)
+    command_verified = _bool_value(normalized.get("command_verified"))
+    if command_verified is not None:
+        normalized["command_verified"] = command_verified
+    else:
+        normalized.pop("command_verified", None)
+    command_verification_mode = str(normalized.get("command_verification_mode") or "").strip()
+    if command_verification_mode:
+        normalized["command_verification_mode"] = command_verification_mode
+    else:
+        normalized.pop("command_verification_mode", None)
+    verified_run_cmd = _string_list(normalized.get("verified_run_cmd"))
+    if verified_run_cmd:
+        normalized["verified_run_cmd"] = verified_run_cmd
+    else:
+        normalized.pop("verified_run_cmd", None)
+    canonical_test_cmd = _string_list(normalized.get("canonical_test_cmd"))
+    if canonical_test_cmd:
+        normalized["canonical_test_cmd"] = canonical_test_cmd
+    else:
+        normalized.pop("canonical_test_cmd", None)
+    canonical_test_cwd = str(normalized.get("canonical_test_cwd") or "").strip()
+    if canonical_test_cwd:
+        normalized["canonical_test_cwd"] = canonical_test_cwd
+    else:
+        normalized.pop("canonical_test_cwd", None)
+    notes = _string_list(normalized.get("notes"))
+    if str(normalized.get("framework") or "").strip().lower() == "pytest":
+        marker_examples = _string_list(normalized.get("marker_examples"))
+        if not marker_examples or _is_legacy_pytest_marker_examples(marker_examples):
+            normalized["marker_examples"] = _pytest_marker_examples()
+        notes = list(dict.fromkeys([*notes, *_pytest_runtime_notes()]))
+    if notes:
+        normalized["notes"] = notes
+    else:
+        normalized.pop("notes", None)
+    normalized["source"] = source
+    return normalized
+
+
+def resolve_story_runtime_contract(
+    *,
+    repo_root: Path,
+    story_id: str,
+    story_uuid: str | None = None,
+    test_paths: list[str] | None = None,
+    prefer_story_contract: bool = True,
+) -> dict[str, Any]:
+    repo_defaults = load_repo_test_runtime_defaults(repo_root)
+    story_contract = load_story_test_runtime_contract(repo_root=repo_root, story_id=story_id) if prefer_story_contract else None
+    fallback = repo_defaults or {}
+    if story_contract is not None:
+        resolved = normalize_story_runtime_contract(
+            repo_root=repo_root,
+            contract=story_contract,
+            story_id=story_id,
+            story_uuid=story_uuid,
+            source=str(story_contract.get("source") or "story_runtime_contract"),
+            fallback=fallback,
+        )
+    elif repo_defaults is not None:
+        resolved = normalize_story_runtime_contract(
+            repo_root=repo_root,
+            contract=repo_defaults,
+            story_id=story_id,
+            story_uuid=story_uuid,
+            source="repo_defaults",
+        )
+    else:
+        resolved = normalize_story_runtime_contract(
+            repo_root=repo_root,
+            contract={},
+            story_id=story_id,
+            story_uuid=story_uuid,
+            source="inferred",
+        )
+    if test_paths is not None:
+        resolved["test_paths"] = _string_list(test_paths)
+    return resolved
+
+
+def normalize_recovery_story_runtime_contract(*, repo_root: Path, contract: dict[str, Any]) -> dict[str, Any]:
+    normalized = dict(contract)
+    run_cmd = _string_list(normalized.get("run_cmd"))
+    backend_cwd = _infer_backend_runtime_cwd(repo_root=repo_root, contract=normalized)
+    canonical_run_cmd = _unwrap_host_backend_pytest_wrapper(run_cmd)
+    if str(normalized.get("framework") or "").strip().lower() != "pytest":
+        return normalized
+    if backend_cwd is None or canonical_run_cmd is None:
+        return normalized
+    normalized["cwd"] = backend_cwd
+    normalized["run_cmd"] = canonical_run_cmd
+    return normalized
+
+
+def persist_story_runtime_contract(*, repo_root: Path, contract: dict[str, Any]) -> Path:
+    story_id = str(contract.get("story_id") or "").strip()
+    if not story_id:
+        raise ValueError("story runtime contract requires story_id")
+    path = story_test_runtime_contract_path(repo_root=repo_root, story_id=story_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(contract, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def runtime_contract_cwd(*, repo_root: Path, runtime_contract: dict[str, Any]) -> Path:
+    cwd = str(runtime_contract.get("cwd") or ".").strip() or "."
+    target = Path(cwd)
+    if not target.is_absolute():
+        target = repo_root / target
+    return target
+
+
+def runtime_contract_env(runtime_contract: dict[str, Any]) -> dict[str, str]:
+    return {**os.environ, **_string_map(runtime_contract.get("env"))}
+
+
+def runtime_contract_test_args(*, runtime_contract: dict[str, Any], test_paths: list[str]) -> list[str]:
+    cwd = str(runtime_contract.get("cwd") or ".").strip() or "."
+    prefix = f"{cwd.rstrip('/')}/"
+    adjusted: list[str] = []
+    for path in test_paths:
+        value = str(path).strip()
+        if cwd not in {"", "."} and value.startswith(prefix):
+            value = value[len(prefix):]
+        adjusted.append(value)
+    return adjusted
+
+
+def _infer_backend_runtime_cwd(*, repo_root: Path, contract: dict[str, Any]) -> str | None:
+    candidates: list[Any] = [
+        contract.get("test_paths"),
+        contract.get("file_globs"),
+        contract.get("example_paths"),
+    ]
+    for values in candidates:
+        for raw in _string_list(values):
+            if raw.startswith("fastapi_backend/"):
+                return "fastapi_backend"
+            if raw.startswith("backend/"):
+                return "backend"
+    for name in ("fastapi_backend", "backend"):
+        if (repo_root / name).exists():
+            return name
+    return None
+
+
+def _unwrap_host_backend_pytest_wrapper(run_cmd: list[str]) -> list[str] | None:
+    if len(run_cmd) < 4:
+        return None
+    if run_cmd[:3] == ["docker", "compose", "run"]:
+        search_start = 3
+    elif run_cmd[:2] == ["docker-compose", "run"]:
+        search_start = 2
+    else:
+        return None
+    try:
+        service_index = next(index for index in range(search_start, len(run_cmd)) if run_cmd[index] == "backend")
+    except StopIteration:
+        return None
+    nested = run_cmd[service_index + 1 :]
+    if nested[:3] == ["uv", "run", "pytest"]:
+        return nested
+    return None

devflow_engine/integration/__init__.py

@@ -0,0 +1,19 @@
+from .dag import (
+    CANONICAL_ACTOR_ALLOWED_COMBINATIONS,
+    IntegrationDagResult,
+    _sync_integration_to_supabase,
+    default_integration_stages,
+    prepare_integration_payload,
+    render_stage_plan,
+    run_integration_dag,
+)
+
+__all__ = [
+    "CANONICAL_ACTOR_ALLOWED_COMBINATIONS",
+    "IntegrationDagResult",
+    "_sync_integration_to_supabase",
+    "default_integration_stages",
+    "prepare_integration_payload",
+    "render_stage_plan",
+    "run_integration_dag",
+]