igel-qe-core 1.0.3 → 1.0.7

package/src/project/ai_folder.py

@@ -0,0 +1,602 @@
+"""ai_folder.py — .ai/ folder scaffolding and system state cache management.
+
+Ownership rules:
+  Human-editable (committed to Git):
+    .ai/project.yaml          — repo metadata, test/page dir layout, framework type
+    .ai/context.md            — free-text project description used in prompts
+    .ai/framework_rules.md    — coding conventions and style hints
+
+  System cache (gitignored, rebuilt from DB on init/status):
+    .ai/system/project_state.json   — asset counts, requirement counts, last sync
+    .ai/system/sync_state.json      — last indexed commit and file list
+    .ai/system/generation_history.json — last 50 generation records
+    .ai/system/model_preferences.json  — task→model routing snapshot from DB
+
+  Key invariant: .ai/system/*.json files are ONLY written by rebuild_system_state_from_db().
+  They are never written during generation. The model router reads model_preferences.json
+  as a local read-through cache; the DB (igel_generation_history) is always authoritative.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+# Markers used when walking up the directory tree to find the repo root
+_ROOT_MARKERS = ["pyproject.toml", "setup.py", "setup.cfg", "conftest.py", ".git"]
+
+_AI_SYSTEM_DIR_NAME = ".ai/system"
+_GITIGNORE_ENTRIES = [
+    ".ai/system/",
+    ".ai/system/*",
+]
+
+# ── repo root detection ────────────────────────────────────────────────────────
+
+def detect_repo_root(start: Path | None = None) -> Path:
+    """Walk up from start (default: cwd) until a repo-root marker is found.
+
+    Returns the directory containing the marker, or the original start directory
+    if no marker is found (graceful degradation).
+    """
+    current = (start or Path.cwd()).resolve()
+    for candidate in [current, *current.parents]:
+        if any((candidate / m).exists() for m in _ROOT_MARKERS):
+            return candidate
+    logger.warning("Could not detect repo root from %s; using cwd", current)
+    return current
+
+
+def detect_framework_layout(repo_root: Path) -> dict:
+    """Auto-detect common automation framework directories.
+
+    Returns a dict of role → relative-path for directories that actually exist.
+    """
+    candidates = {
+        "tests_dir":    ["tests", "test", "specs"],
+        "pages_dir":    ["pages", "page_objects", "pom"],
+        "fixtures_dir": ["fixtures", "conftest", "test_fixtures"],
+        "utils_dir":    ["utils", "helpers", "utilities"],
+        "api_dir":      ["api_clients", "api", "services"],
+        "data_dir":     ["testdata", "test_data", "data"],
+    }
+    layout: dict[str, str] = {}
+    for role, names in candidates.items():
+        for name in names:
+            candidate = repo_root / name
+            if candidate.is_dir():
+                layout[role] = name
+                break
+    return layout
+
+
+# ── scaffold ───────────────────────────────────────────────────────────────────
+
+def scaffold_ai_folder(repo_root: Path) -> None:
+    """Create the .ai/ folder tree with stub files (idempotent).
+
+    Human-editable files are created with helpful placeholder content if they
+    don't already exist. System files are created as empty JSON objects.
+    Adds .ai/system/ to .gitignore.
+    """
+    ai_dir = repo_root / ".ai"
+    system_dir = ai_dir / "system"
+    context_dir = ai_dir / "context"
+    framework_dir = ai_dir / "framework"
+    policy_dir = ai_dir / "policy"
+    governance_dir = ai_dir / "governance"
+    feedback_dir = ai_dir / "feedback"
+    artifacts_dir = ai_dir / "artifacts"
+    system_dir.mkdir(parents=True, exist_ok=True)
+    context_dir.mkdir(parents=True, exist_ok=True)
+    framework_dir.mkdir(parents=True, exist_ok=True)
+    policy_dir.mkdir(parents=True, exist_ok=True)
+    governance_dir.mkdir(parents=True, exist_ok=True)
+    feedback_dir.mkdir(parents=True, exist_ok=True)
+    (artifacts_dir / "requirements").mkdir(parents=True, exist_ok=True)
+    (artifacts_dir / "automation-plans").mkdir(parents=True, exist_ok=True)
+    (artifacts_dir / "index").mkdir(parents=True, exist_ok=True)
+
+    layout = detect_framework_layout(repo_root)
+
+    # Human-editable stubs (only created if absent; never overwritten)
+    _write_if_absent(
+        ai_dir / "project.yaml",
+        yaml.dump(
+            {
+                "repo_name": repo_root.name,
+                "framework_type": "pytest",
+                "tests_dir": layout.get("tests_dir", "tests"),
+                "pages_dir": layout.get("pages_dir", "pages"),
+                "fixtures_dir": layout.get("fixtures_dir", "fixtures"),
+                "utils_dir": layout.get("utils_dir", "utils"),
+                "api_dir": layout.get("api_dir", "api_clients"),
+            },
+            default_flow_style=False,
+        ),
+    )
+    _write_if_absent(
+        ai_dir / "context.md",
+        f"# {repo_root.name} — IGEL QE Project Context\n\n"
+        "Describe the product under test, key features, and any domain knowledge\n"
+        "the AI should use when generating test cases and automation scripts.\n",
+    )
+    _write_if_absent(
+        ai_dir / "framework_rules.md",
+        "# Automation Framework Rules\n\n"
+        "Add coding conventions, naming patterns, fixture usage rules,\n"
+        "and any constraints the script generator must respect.\n\n"
+        "Examples:\n"
+        "- Page objects must inherit from `BasePage`\n"
+        "- All tests must use the `browser` fixture from `conftest.py`\n"
+        "- Use `assert_that()` not bare `assert` for readability\n",
+    )
+
+    # Structured context and framework metadata
+    _write_if_absent(
+        context_dir / "project.md",
+        f"# {repo_root.name} Project Context\n\n"
+        "Document business domain context and terminology here.\n",
+    )
+    _write_if_absent(
+        context_dir / "domain.md",
+        "# Domain Notes\n\n"
+        "Capture product domain behaviors, assumptions, and edge cases.\n",
+    )
+    _write_if_absent(
+        context_dir / "constraints.yaml",
+        yaml.dump(
+            {
+                "missing_asset_policy": {
+                    "create": False,
+                    "propose": True,
+                    "require_review": True,
+                }
+            },
+            default_flow_style=False,
+        ),
+    )
+    _write_if_absent(
+        framework_dir / "manifest.yaml",
+        yaml.dump(
+            {
+                "framework": "pytest",
+                "paths": {
+                    "tests": layout.get("tests_dir", "tests"),
+                    "pages": layout.get("pages_dir", "pages"),
+                    "fixtures": layout.get("fixtures_dir", "fixtures"),
+                    "utils": layout.get("utils_dir", "utils"),
+                },
+            },
+            default_flow_style=False,
+        ),
+    )
+    _write_if_absent(policy_dir / "profiles.yaml", "default_profile: safe-default\n")
+    _write_if_absent(
+        governance_dir / "approval_rules.yaml",
+        "require_human_approval: true\n"
+        "min_confidence_for_auto_publish: 0.8\n",
+    )
+    _write_if_absent(
+        governance_dir / "generation_rules.yaml",
+        "enforce_policy_engine: true\n"
+        "enforce_agent_guardrails: true\n",
+    )
+    _write_if_absent(feedback_dir / "README.md", "Store feedback exports and reconciliation notes.\n")
+
+    # Artifact index stubs
+    _write_if_absent(artifacts_dir / "index" / "by_jira.json", "{}\n")
+    _write_if_absent(artifacts_dir / "index" / "by_test_reqid.json", "{}\n")
+
+    # System state stubs (empty objects — rebuilt from DB by rebuild_system_state_from_db)
+    for name in ("project_state", "sync_state", "generation_history", "model_preferences"):
+        _write_if_absent(system_dir / f"{name}.json", "{}\n")
+
+    # Gitignore
+    _update_gitignore(repo_root)
+
+    logger.info("Scaffolded .ai/ folder at %s", ai_dir)
+
+
+def _write_if_absent(path: Path, content: str) -> None:
+    if not path.exists():
+        path.write_text(content, encoding="utf-8")
+        logger.debug("Created %s", path)
+
+
+def _update_gitignore(repo_root: Path) -> None:
+    gitignore = repo_root / ".gitignore"
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    additions = [e for e in _GITIGNORE_ENTRIES if e not in existing]
+    if additions:
+        with gitignore.open("a", encoding="utf-8") as f:
+            f.write("\n# IGEL QE Agent — auto-managed system state\n")
+            for entry in additions:
+                f.write(f"{entry}\n")
+        logger.info("Updated .gitignore with .ai/system/ entries")
+
+
+# ── project.yaml read/write ────────────────────────────────────────────────────
+
+def read_project_yaml(repo_root: Path) -> dict:
+    path = repo_root / ".ai" / "project.yaml"
+    if not path.exists():
+        return {}
+    try:
+        with path.open(encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except Exception as e:
+        logger.warning("Failed to read project.yaml: %s", e)
+        return {}
+
+
+def write_project_yaml(repo_root: Path, data: dict) -> None:
+    path = repo_root / ".ai" / "project.yaml"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        yaml.dump(data, f, default_flow_style=False)
+
+
+def artifact_requirement_dir(repo_root: Path, jira_key: str, test_reqid: str | None = None) -> Path:
+    """Return .ai artifact path for a requirement/test_reqid."""
+    reqid = (test_reqid or jira_key).strip()
+    return repo_root / ".ai" / "artifacts" / "requirements" / jira_key / reqid
+
+
+def write_testcase_artifacts(
+    repo_root: Path,
+    jira_key: str,
+    generated_cases: list,
+    approved_cases: list,
+    *,
+    test_reqid: str | None = None,
+    requirement_hash: str | None = None,
+    framework_hash: str | None = None,
+) -> dict:
+    """Write generated and approved testcase artifacts for deterministic script input reuse."""
+    req_dir = artifact_requirement_dir(repo_root, jira_key, test_reqid)
+    req_dir.mkdir(parents=True, exist_ok=True)
+
+    gen_payload = {
+        "jira_key": jira_key,
+        "test_reqid": test_reqid or jira_key,
+        "count": len(generated_cases),
+        "cases": [_to_dict(tc) for tc in generated_cases],
+    }
+    approved_payload = {
+        "jira_key": jira_key,
+        "test_reqid": test_reqid or jira_key,
+        "count": len(approved_cases),
+        "cases": [_to_dict(tc) for tc in approved_cases],
+        "staleness": {
+            "requirement_hash": requirement_hash,
+            "framework_hash": framework_hash,
+            "approved_content_hash": compute_cases_content_hash(approved_cases),
+        },
+    }
+
+    _write_system_json(req_dir / "testcases.generated.json", gen_payload)
+    _write_system_json(req_dir / "testcases.approved.json", approved_payload)
+
+    # Keep index files for fast lookup
+    idx_jira = repo_root / ".ai" / "artifacts" / "index" / "by_jira.json"
+    idx_reqid = repo_root / ".ai" / "artifacts" / "index" / "by_test_reqid.json"
+    _merge_index(idx_jira, jira_key, str(req_dir))
+    _merge_index(idx_reqid, test_reqid or jira_key, str(req_dir))
+
+    return {
+        "artifact_dir": str(req_dir),
+        "generated_count": len(generated_cases),
+        "approved_count": len(approved_cases),
+    }
+
+
+def read_approved_testcase_artifact(repo_root: Path, jira_key: str, test_reqid: str | None = None) -> dict:
+    req_dir = artifact_requirement_dir(repo_root, jira_key, test_reqid)
+    path = req_dir / "testcases.approved.json"
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as e:
+        logger.warning("Failed to read approved testcase artifact %s: %s", path, e)
+        return {}
+
+
+def write_requirement_plan_artifact(
+    repo_root: Path,
+    jira_key: str,
+    scenarios_with_rules: list,
+    resolved_context: Any,
+    source_report: Any,
+    *,
+    test_reqid: str | None = None,
+    requirement_hash: str | None = None,
+) -> dict:
+    """Persist requirement-planning output (scenarios/business rules + resolved
+    context + source report) so generate_test_cases can reuse it without re-planning."""
+    req_dir = artifact_requirement_dir(repo_root, jira_key, test_reqid)
+    req_dir.mkdir(parents=True, exist_ok=True)
+
+    scenarios_payload = [_to_dict(sr) for sr in scenarios_with_rules]
+    payload = {
+        "jira_key": jira_key,
+        "test_reqid": test_reqid or jira_key,
+        "scenario_count": len(scenarios_with_rules),
+        "scenarios": scenarios_payload,
+        "resolved_context": _to_dict(resolved_context),
+        "source_report": _to_dict(source_report),
+        "staleness": {
+            "requirement_hash": requirement_hash,
+            "plan_content_hash": _json_hash(scenarios_payload),
+        },
+    }
+    _write_system_json(req_dir / "plan.json", payload)
+
+    idx_jira = repo_root / ".ai" / "artifacts" / "index" / "by_jira.json"
+    idx_reqid = repo_root / ".ai" / "artifacts" / "index" / "by_test_reqid.json"
+    _merge_index(idx_jira, jira_key, str(req_dir))
+    _merge_index(idx_reqid, test_reqid or jira_key, str(req_dir))
+
+    return {"artifact_dir": str(req_dir), "scenario_count": len(scenarios_with_rules)}
+
+
+def read_plan_artifact(repo_root: Path, jira_key: str, test_reqid: str | None = None) -> dict:
+    req_dir = artifact_requirement_dir(repo_root, jira_key, test_reqid)
+    path = req_dir / "plan.json"
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as e:
+        logger.warning("Failed to read plan artifact %s: %s", path, e)
+        return {}
+
+
+def write_approval_artifact(
+    repo_root: Path,
+    jira_key: str,
+    stage: str,
+    payload: dict,
+    *,
+    test_reqid: str | None = None,
+) -> dict:
+    """Persist approval status for a workflow stage.
+
+    Example stages: testcase_plan, automation_plan.
+    """
+    req_dir = artifact_requirement_dir(repo_root, jira_key, test_reqid)
+    req_dir.mkdir(parents=True, exist_ok=True)
+    safe_stage = stage.strip().replace(" ", "_").lower()
+    path = req_dir / f"approval.{safe_stage}.json"
+    _write_system_json(path, payload)
+    return {"artifact_path": str(path), "stage": safe_stage}
+
+
+def read_approval_artifact(
+    repo_root: Path,
+    jira_key: str,
+    stage: str,
+    *,
+    test_reqid: str | None = None,
+) -> dict:
+    req_dir = artifact_requirement_dir(repo_root, jira_key, test_reqid)
+    safe_stage = stage.strip().replace(" ", "_").lower()
+    path = req_dir / f"approval.{safe_stage}.json"
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as e:
+        logger.warning("Failed to read approval artifact %s: %s", path, e)
+        return {}
+
+
+def artifact_automation_plan_dir(repo_root: Path, jira_key: str, test_reqid: str | None = None) -> Path:
+    """Return .ai artifact path for an automation plan."""
+    reqid = (test_reqid or jira_key).strip()
+    return repo_root / ".ai" / "artifacts" / "automation-plans" / jira_key / reqid
+
+
+def write_automation_plan_artifact(
+    repo_root: Path,
+    jira_key: str,
+    plan: Any,
+    *,
+    test_reqid: str | None = None,
+    approved_content_hash: str | None = None,
+) -> dict:
+    """Persist a designed AutomationPlan so generate_automation can reuse it without redesigning."""
+    plan_dir = artifact_automation_plan_dir(repo_root, jira_key, test_reqid)
+    plan_dir.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "jira_key": jira_key,
+        "test_reqid": test_reqid or jira_key,
+        "plan": _to_dict(plan),
+        "staleness": {"approved_content_hash": approved_content_hash},
+    }
+    _write_system_json(plan_dir / "plan.json", payload)
+    return {"artifact_dir": str(plan_dir)}
+
+
+def read_automation_plan_artifact(repo_root: Path, jira_key: str, test_reqid: str | None = None) -> dict:
+    path = artifact_automation_plan_dir(repo_root, jira_key, test_reqid) / "plan.json"
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as e:
+        logger.warning("Failed to read automation plan artifact %s: %s", path, e)
+        return {}
+
+
+def _to_dict(obj: Any) -> dict:
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump()
+    if is_dataclass(obj) and not isinstance(obj, type):
+        return asdict(obj)
+    if isinstance(obj, dict):
+        return obj
+    return {"value": str(obj)}
+
+
+def _json_hash(data: Any) -> str:
+    import hashlib
+
+    raw = json.dumps(data, sort_keys=True, default=str).encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()
+
+
+def compute_cases_content_hash(cases: list) -> str:
+    """Deterministic content hash of a list of test-case-like objects, for staleness comparisons."""
+    return _json_hash([_to_dict(c) for c in cases])
+
+
+def _merge_index(path: Path, key: str, value: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existing = {}
+    if path.exists():
+        try:
+            existing = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            existing = {}
+    existing[key] = value
+    path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
+
+
+# ── system state (DB read-through cache) ──────────────────────────────────────
+
+def rebuild_system_state_from_db(repo_root: Path) -> dict:
+    """Query the DB and write all .ai/system/*.json cache files.
+
+    This is the ONLY function that writes to .ai/system/.
+    It must be called explicitly (from igel-qe init or igel-qe status).
+    It is never called during test generation.
+    Returns a summary dict for display.
+    """
+    system_dir = repo_root / ".ai" / "system"
+    system_dir.mkdir(parents=True, exist_ok=True)
+
+    summary: dict[str, Any] = {}
+
+    try:
+        from src.db.client import get_conn
+
+        with get_conn() as conn:
+            with conn.cursor() as cur:
+                # Project state
+                project_state = _query_project_state(cur)
+                summary["project_state"] = project_state
+                _write_system_json(system_dir / "project_state.json", project_state)
+
+                # Sync state
+                sync_state = _query_sync_state(cur)
+                summary["sync_state"] = sync_state
+                _write_system_json(system_dir / "sync_state.json", sync_state)
+
+                # Generation history (last 50 rows)
+                gen_history = _query_generation_history(cur)
+                summary["generation_history_count"] = len(gen_history)
+                _write_system_json(system_dir / "generation_history.json", {"records": gen_history})
+
+                # Model preferences (task→best model from history)
+                model_prefs = _build_model_preferences(cur)
+                summary["model_preferences"] = model_prefs
+                _write_system_json(system_dir / "model_preferences.json", model_prefs)
+
+        logger.info("Rebuilt .ai/system/ state from DB")
+    except Exception as e:
+        logger.error("Failed to rebuild system state: %s", e)
+        summary["error"] = str(e)
+
+    return summary
+
+
+def _query_project_state(cur) -> dict:
+    state: dict[str, Any] = {}
+    for table, key in [
+        ("igel_asset_registry", "asset_count"),
+        ("igel_requirements", "requirement_count"),
+        ("igel_generated_testcases", "testcase_count"),
+        ("igel_automation_scripts", "script_count"),
+    ]:
+        try:
+            cur.execute(f"SELECT COUNT(*) FROM {table}")
+            row = cur.fetchone()
+            state[key] = row[0] if row else 0
+        except Exception:
+            state[key] = 0
+    return state
+
+
+def _query_sync_state(cur) -> dict:
+    try:
+        cur.execute("""
+            SELECT source, last_synced_at, status
+            FROM connector_sync_state
+            ORDER BY last_synced_at DESC NULLS LAST
+        """)
+        rows = cur.fetchall()
+        return {
+            "connectors": [
+                {"source": r[0], "last_synced_at": str(r[1]) if r[1] else None, "status": r[2]}
+                for r in rows
+            ]
+        }
+    except Exception:
+        return {}
+
+
+def _query_generation_history(cur) -> list:
+    try:
+        cur.execute("""
+            SELECT jira_key, action, model_used, task_type, tokens_in, tokens_out,
+                   duration_ms, quality_score, routed_by, created_at
+            FROM igel_generation_history
+            ORDER BY created_at DESC
+            LIMIT 50
+        """)
+        cols = ["jira_key", "action", "model_used", "task_type", "tokens_in",
+                "tokens_out", "duration_ms", "quality_score", "routed_by", "created_at"]
+        return [dict(zip(cols, [str(v) if v is not None else None for v in row])) for row in cur.fetchall()]
+    except Exception:
+        return []
+
+
+def _build_model_preferences(cur) -> dict:
+    """Aggregate igel_generation_history to get the best-performing model per task_type."""
+    try:
+        cur.execute("""
+            SELECT task_type, model_used,
+                   AVG(quality_score) AS avg_quality,
+                   COUNT(*) AS call_count
+            FROM igel_generation_history
+            WHERE task_type IS NOT NULL AND quality_score IS NOT NULL
+            GROUP BY task_type, model_used
+            ORDER BY task_type, avg_quality DESC NULLS LAST
+        """)
+        prefs: dict[str, dict] = {}
+        for task_type, model_used, avg_quality, call_count in cur.fetchall():
+            # First row per task_type is the best (ORDER BY avg_quality DESC)
+            if task_type not in prefs:
+                prefs[task_type] = {
+                    "recommended_model": model_used,
+                    "avg_quality": round(float(avg_quality), 4) if avg_quality else None,
+                    "call_count": call_count,
+                }
+        return prefs
+    except Exception:
+        return {}
+
+
+def _write_system_json(path: Path, data: Any) -> None:
+    try:
+        path.write_text(json.dumps(data, indent=2, default=str) + "\n", encoding="utf-8")
+    except Exception as e:
+        logger.warning("Failed to write %s: %s", path, e)