project-brain-cli 1.0.0__py3-none-any.whl

project_brain/core/doctor_checks/environment.py

@@ -0,0 +1,92 @@
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+from project_brain.core.doctor_checks.models import DoctorCheck
+
+
+def run_environment_checks(root: Path):
+    checks = []
+
+    # Python version
+    version = sys.version_info
+
+    if version.major >= 3 and version.minor >= 10:
+        checks.append(
+            DoctorCheck(
+                "Environment",
+                "Python",
+                "pass",
+                f"Python {version.major}.{version.minor}",
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                "Environment",
+                "Python",
+                "fail",
+                "Python 3.10+ required",
+                "Upgrade Python to >=3.10",
+            )
+        )
+
+    # OS
+    checks.append(
+        DoctorCheck(
+            "Environment",
+            "OS",
+            "info",
+            platform.platform(),
+        )
+    )
+
+    # Virtual env
+    venv_active = (
+        hasattr(sys, "real_prefix")
+        or (hasattr(sys, "base_prefix") and sys.base_prefix != sys.prefix)
+    )
+
+    if venv_active:
+        checks.append(
+            DoctorCheck(
+                "Environment",
+                "Virtual Environment",
+                "pass",
+                "Virtual environment active",
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                "Environment",
+                "Virtual Environment",
+                "warn",
+                "No virtual environment detected",
+                "Create one:\npython -m venv env",
+            )
+        )
+
+    # Git installed
+    if shutil.which("git"):
+        checks.append(
+            DoctorCheck(
+                "Environment",
+                "Git",
+                "pass",
+                "Git installed",
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                "Environment",
+                "Git",
+                "fail",
+                "Git not installed",
+                "Install Git from https://git-scm.com/",
+            )
+        )
+
+    return checks

project_brain/core/doctor_checks/exports.py

@@ -0,0 +1,70 @@
+from pathlib import Path
+
+from project_brain.core.doctor_checks.models import DoctorCheck
+
+
+def check_export(path: Path, name: str):
+    if not path.exists():
+        return DoctorCheck(
+            "Exports",
+            name,
+            "warn",
+            "Export missing",
+        )
+
+    if path.stat().st_size == 0:
+        return DoctorCheck(
+            "Exports",
+            name,
+            "warn",
+            "Export empty",
+        )
+
+    return DoctorCheck(
+        "Exports",
+        name,
+        "pass",
+        "Export available",
+    )
+
+
+def run_export_checks(root: Path):
+    checks = []
+
+    export_dir = root / ".brain" / "exports"
+
+    if not export_dir.exists():
+        checks.append(
+            DoctorCheck(
+                "Exports",
+                "Exports Directory",
+                "warn",
+                "Exports directory missing",
+            )
+        )
+        return checks
+
+    checks.append(
+        DoctorCheck(
+            "Exports",
+            "Exports Directory",
+            "pass",
+            "Exports directory exists",
+        )
+    )
+
+    checks.append(
+        check_export(
+            export_dir / "full_code.txt",
+            "Full Code Export",
+        )
+    )
+
+    checks.append(
+        check_export(
+            export_dir / "code_changes.txt",
+            "Code Changes Export",
+        )
+    )
+
+    return checks

project_brain/core/doctor_checks/llm.py

@@ -0,0 +1,107 @@
+import os
+import subprocess
+from pathlib import Path
+
+from project_brain.core.config_loader import load_config
+from project_brain.core.doctor_checks.models import DoctorCheck
+
+
+def run_llm_checks(root: Path):
+    checks = []
+
+    config = load_config(root)
+
+    llm = config.get("llm", {})
+
+    provider = llm.get("provider", "none")
+    model = llm.get("model", "")
+
+    checks.append(
+        DoctorCheck(
+            "LLM",
+            "Provider",
+            "info",
+            provider,
+        )
+    )
+
+    if provider == "none":
+        checks.append(
+            DoctorCheck(
+                "LLM",
+                "Status",
+                "info",
+                "LLM disabled",
+            )
+        )
+        return checks
+
+    if not model:
+        checks.append(
+            DoctorCheck(
+                "LLM",
+                "Model",
+                "fail",
+                "No model configured",
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                "LLM",
+                "Model",
+                "pass",
+                model,
+            )
+        )
+
+    if provider == "ollama":
+        try:
+            subprocess.run(
+                ["ollama", "list"],
+                capture_output=True,
+                check=True,
+            )
+
+            checks.append(
+                DoctorCheck(
+                    "LLM",
+                    "Ollama",
+                    "pass",
+                    "Ollama available",
+                )
+            )
+
+        except Exception:
+            checks.append(
+                DoctorCheck(
+                    "LLM",
+                    "Ollama",
+                    "fail",
+                    "Ollama unavailable",
+                    "Install Ollama",
+                )
+            )
+
+    elif provider == "openai":
+        if os.getenv("OPENAI_API_KEY"):
+            checks.append(
+                DoctorCheck(
+                    "LLM",
+                    "OPENAI_API_KEY",
+                    "pass",
+                    "API key configured",
+                )
+            )
+        else:
+            checks.append(
+                DoctorCheck(
+                    "LLM",
+                    "OPENAI_API_KEY",
+                    "fail",
+                    "Missing API key",
+                    "Set OPENAI_API_KEY",
+                )
+            )
+
+    return checks

project_brain/core/doctor_checks/models.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class DoctorCheck:
+    category: str
+    name: str
+    status: str
+    message: str
+    fix: str = ""

project_brain/core/doctor_checks/repository.py

@@ -0,0 +1,102 @@
+from pathlib import Path
+
+from project_brain.core.differ import is_git_repo, run_git_command
+from project_brain.core.doctor_checks.models import DoctorCheck
+
+
+def get_repo_size(root: Path):
+    total = 0
+
+    try:
+        for path in root.rglob("*"):
+            if path.is_file():
+                total += path.stat().st_size
+    except Exception:
+        return "Unknown"
+
+    return f"{round(total / (1024 * 1024), 2)} MB"
+
+
+def run_repository_checks(root: Path):
+    checks = []
+
+    if not is_git_repo(root):
+        checks.append(
+            DoctorCheck(
+                "Repository",
+                "Git Repository",
+                "warn",
+                "Not a git repository",
+                "Run:\ngit init",
+            )
+        )
+        return checks
+
+    checks.append(
+        DoctorCheck(
+            "Repository",
+            "Git Repository",
+            "pass",
+            "Git repository detected",
+        )
+    )
+
+    branch = run_git_command(
+        ["branch", "--show-current"],
+        root,
+    )
+
+    if branch:
+        checks.append(
+            DoctorCheck(
+                "Repository",
+                "Branch",
+                "pass",
+                branch,
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                "Repository",
+                "Branch",
+                "warn",
+                "Detached HEAD state",
+            )
+        )
+
+    commit = run_git_command(
+        ["rev-parse", "--short", "HEAD"],
+        root,
+    )
+
+    if commit:
+        checks.append(
+            DoctorCheck(
+                "Repository",
+                "Latest Commit",
+                "pass",
+                commit,
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                "Repository",
+                "Latest Commit",
+                "warn",
+                "No commits found",
+                "Create initial commit",
+            )
+        )
+
+    checks.append(
+        DoctorCheck(
+            "Repository",
+            "Repository Size",
+            "info",
+            get_repo_size(root),
+        )
+    )
+
+    return checks

project_brain/core/explainer.py

@@ -0,0 +1,334 @@
+import hashlib
+import json
+import re
+from pathlib import Path
+import os
+
+from project_brain.core.config_loader import load_config
+from project_brain.core.differ import (compute_diff, extract_functions,
+                                       get_file_from_ref)
+from project_brain.core.logger import log_error, log_warning
+from project_brain.llm.provider import call_llm
+
+
+def hash_pair(old: str, new: str, fn: str) -> str:
+    return hashlib.sha256((old + new + fn).encode()).hexdigest()
+
+
+def load_cache(cache_dir: Path, key: str):
+    path = cache_dir / f"{key}.json"
+    if path.exists():
+        try:
+            return json.loads(path.read_text())
+        except Exception as e:
+            log_warning(f"⚠️ Corrupted cache ignored: {path}")
+            return None
+    return None
+
+
+def cleanup_cache(cache_dir: Path, max_files=1000):
+    files = sorted(cache_dir.glob("*.json"), key=lambda f: f.stat().st_mtime)
+
+    if len(files) > max_files:
+        for f in files[: len(files) - max_files]:
+            f.unlink()
+
+
+def is_valid_cache(data: dict) -> bool:
+    if not isinstance(data, dict):
+        return False
+
+    if "fast" not in data or "detailed" not in data:
+        return False
+
+    for section in ["fast", "detailed"]:
+        part = data.get(section)
+        if not isinstance(part, dict):
+            return False
+        if not all(k in part for k in ["change", "impact", "risk"]):
+            return False
+        if part["risk"] not in ["low", "medium", "high"]:
+            return False
+
+    return True
+
+
+def save_cache(cache_dir: Path, key: str, data: dict):
+    if not is_valid_cache(data):
+        log_warning(f"Invalid cache skipped: {key}")
+        return
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    path = cache_dir / f"{key}.json"
+    path.write_text(json.dumps(data, indent=2))
+    cleanup_cache(cache_dir)
+
+
+def build_prompt(old_code: str, new_code: str, fn: str) -> str:
+    return f"""
+        You are a senior software engineer performing a code review.
+
+        Analyze the function change and return STRICT JSON ONLY.
+
+        DO NOT use markdown.
+        DO NOT add text outside JSON.
+
+        Return EXACTLY:
+
+        {{
+          "fast": {{
+            "change": "(1-2 lines) short line summary",
+            "impact": "(1-2 lines) short line impact",
+            "risk": "low | medium | high"
+          }},
+          "detailed": {{
+            "change": "Explain what changed at logic level (4-6 lines)",
+            "impact": "Explain system-level impact and behavior changes (4-6 lines)",
+            "risk": "Explain actual risk reasoning + severity (2-3 lines, end with low|medium|high)"
+          }}
+        }}
+
+        Rules:
+        - fast = minimal summary only
+        - detailed MUST include reasoning, not just description
+        - DO NOT repeat fast output in detailed
+        - risk must still end with one of: low, medium, high
+
+        Function: {fn}
+
+        Old Code:
+        {old_code}
+
+        New Code:
+        {new_code}
+        """.strip()
+
+
+def safe_extract(source: str):
+    try:
+        return extract_functions(source)
+    except Exception as e:
+        log_error(f"Function failed: {str(e)}")
+        return {}
+
+
+def explain_diff(from_ref: str, to_ref: str, root: Path) -> list[dict] | None:
+    config = load_config(root)
+    llm_cfg = config.get("llm", {})
+
+    provider = llm_cfg.get("provider", "none")
+    model = llm_cfg.get("model", "")
+    api_key = ""
+
+    diff = compute_diff(from_ref, to_ref, root)
+    if not diff:
+        return None
+
+    results = []
+    cache_dir = root / ".brain" / "cache"
+
+    for fd in diff["function_diffs"]:
+        file = fd["file"]
+
+        old_src = get_file_from_ref(from_ref, file, root) or ""
+        new_src = get_file_from_ref(to_ref, file, root) or ""
+
+        old_funcs = safe_extract(old_src)
+        new_funcs = safe_extract(new_src)
+
+        changed_funcs = list(
+            set(fd["added"]) | set(fd["removed"]) | set(fd["modified"])
+        )
+
+        if not changed_funcs:
+            continue
+
+        for fn in changed_funcs:
+            old_code = old_funcs.get(fn, "")
+            new_code = new_funcs.get(fn, "")
+
+            key = hash_pair(old_code, new_code, fn)
+            cached = load_cache(cache_dir, key)
+
+            if cached and is_valid_cache(cached):
+                data = select_output(cached, config)
+                results.append({"file": file, "function": fn, **data})
+                continue
+
+            # No LLM configured
+            if provider == "none":
+                data = {
+                    "change": f"Function '{fn}' has code-level changes",
+                    "impact": "Behavior may differ depending on logic changes",
+                    "risk": "medium",
+                }
+                results.append({"file": file, "function": fn, **data})
+                continue
+
+            prompt = build_prompt(old_code, new_code, fn)
+            response = call_llm(provider, model, prompt, api_key)
+
+            if response["error"]:
+                log_error(f"LLM error: {response['error']}")
+                parsed = None
+            else:
+                parsed = normalize_response(response["output"], provider, model, api_key)
+            
+            # retry if parsing failed
+            if not parsed:
+                fix_prompt = f"""
+                Convert this into the required JSON structure:
+            
+                {response["output"]}
+            
+                Return ONLY:
+                {{
+                "fast": {{ "change": "...", "impact": "...", "risk": "low|medium|high" }},
+                "detailed": {{ "change": "...", "impact": "...", "risk": "low|medium|high" }}
+                }}
+                """
+                response = call_llm(provider, model, fix_prompt, api_key)
+                if response["error"]:
+                    parsed = None
+                else:
+                    parsed = parse_llm_json(response["output"])
+            
+            if parsed:
+                save_cache(cache_dir, key, parsed)
+                data = select_output(parsed, config)
+            else:
+                data = {
+                    "change": "Failed to generate structured output",
+                    "impact": "Unknown",
+                    "risk": "high"
+                }
+            results.append({"file": file, "function": fn, **data})
+    explain_cfg = config.get("explain", {})
+    include_risks = explain_cfg.get("include_risks", True)
+
+    if not include_risks:
+        for result in results:
+            result["risk"] = ""
+    return results
+
+
+def parse_llm_json(response: str):
+    try:
+        data = json.loads(response)
+
+        if not all(k in data for k in ["fast", "detailed"]):
+            raise ValueError("Missing structure")
+
+        return data
+
+    except Exception as e:
+        log_error(f"Function failed: {str(e)}")
+        return None
+
+
+def normalize_response(response_text: str, provider, model, api_key):
+    # Step 1: direct parse
+    parsed = parse_llm_json(response_text)
+    if parsed and is_valid_cache(parsed):
+        return parsed
+
+    # Step 2: try extracting legacy text
+    extracted = extract_from_old_text(response_text)
+    if extracted.get("change"):
+        structured = {
+            "fast": extracted,
+            "detailed": extracted
+        }
+        if is_valid_cache(structured):
+            return structured
+
+    # Step 3: LLM fix (last resort)
+    fix_prompt = f"""
+Convert into STRICT JSON:
+
+{response_text}
+
+Return ONLY:
+{{
+  "fast": {{ "change": "...", "impact": "...", "risk": "low|medium|high" }},
+  "detailed": {{ "change": "...", "impact": "...", "risk": "low|medium|high" }}
+}}
+"""
+
+    response = call_llm(provider, model, fix_prompt, api_key)
+
+    if response["error"]:
+        return None
+
+    parsed = parse_llm_json(response["output"])
+    if parsed and is_valid_cache(parsed):
+        return parsed
+
+    return None
+
+
+def extract_from_old_text(text: str):
+    sections = {"change": "", "impact": "", "risk": ""}
+
+    # Normalize
+    text = text.replace("\r", "").strip()
+
+    # Patterns
+    change_match = re.search(
+        r"(?:What changed|### 1\..*?changed)(.*?)(?:###|$)", text, re.S | re.I
+    )
+    impact_match = re.search(
+        r"(?:Why it matters|Impact|### 2\..*?|### 3\..*?)(.*?)(?:###|$)",
+        text,
+        re.S | re.I,
+    )
+    risk_match = re.search(r"(?:Risk|### 4\..*?risk)(.*?)(?:###|$)", text, re.S | re.I)
+
+    if change_match:
+        sections["change"] = change_match.group(1).strip()
+
+    if impact_match:
+        sections["impact"] = impact_match.group(1).strip()
+
+    if risk_match:
+        sections["risk"] = risk_match.group(1).strip()
+
+    # Normalize risk
+    r = sections["risk"].lower()
+    if "high" in r:
+        sections["risk"] = "high"
+    elif "medium" in r:
+        sections["risk"] = "medium"
+    else:
+        sections["risk"] = "low"
+
+    return sections
+
+def select_output(parsed: dict, config: dict):
+    explain_cfg = config.get("explain", {})
+
+    level = explain_cfg.get("level", "detailed")
+    include_risks = explain_cfg.get("include_risks", True)
+
+    selected = parsed.get(level, {})
+
+    # ensure fields exist
+    change = selected.get("change", "")
+    impact = selected.get("impact", "")
+    risk = selected.get("risk", "medium")
+
+    if risk not in ["low", "medium", "high"]:
+        risk = "medium"
+
+    if not include_risks:
+        return {
+            "change": change,
+            "impact": impact,
+            "risk": ""
+        }
+
+    return {
+        "change": change,
+        "impact": impact,
+        "risk": risk
+    }