gwc-pybundle 2.1.2__py3-none-any.whl

pybundle/steps/ai_context.py

@@ -0,0 +1,791 @@
+from __future__ import annotations
+
+import json
+import subprocess  # nosec B404 - Required for tool execution, paths validated
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .base import StepResult
+from ..context import BundleContext
+from ..filters import should_exclude_from_analysis
+
+
+@dataclass
+class AIContextStep:
+    """Generate AI_CONTEXT.md file with auto-detected project information."""
+
+    name: str = "AI context"
+    outfile: str = "AI_CONTEXT.md"
+
+    def run(self, ctx: BundleContext) -> StepResult:
+        start = time.time()
+        out = ctx.workdir / self.outfile
+        out.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            content = self._generate_ai_context(ctx)
+            out.write_text(content, encoding="utf-8")
+            
+            elapsed = int((time.time() - start) * 1000)
+            return StepResult(self.name, "OK", elapsed, "")
+        except Exception as e:
+            out.write_text(f"Error generating AI_CONTEXT.md: {e}\n", encoding="utf-8")
+            return StepResult(
+                self.name, "FAIL", int((time.time() - start) * 1000), str(e)
+            )
+
+    def _generate_ai_context(self, ctx: BundleContext) -> str:
+        """Generate the AI_CONTEXT.md content with auto-detected information."""
+        sections = []
+
+        # Header
+        sections.append(self._generate_header(ctx))
+
+        # 0) What this project is
+        sections.append(self._generate_project_overview(ctx))
+
+        # 1) How to run it
+        sections.append(self._generate_how_to_run(ctx))
+
+        # 2) Repository map
+        sections.append(self._generate_repo_map(ctx))
+
+        # 3) Architecture & patterns
+        sections.append(self._generate_architecture(ctx))
+
+        # 4) Configuration
+        sections.append(self._generate_configuration(ctx))
+
+        # 5) Data model & storage
+        sections.append(self._generate_data_model(ctx))
+
+        # 6) API surface
+        sections.append(self._generate_api_surface(ctx))
+
+        # 7) Tests & quality gates
+        sections.append(self._generate_tests_quality(ctx))
+
+        # 8) Sharp edges
+        sections.append(self._generate_sharp_edges(ctx))
+
+        # 9) Change guide
+        sections.append(self._generate_change_guide(ctx))
+
+        # 10) AI rules
+        sections.append(self._generate_ai_rules(ctx))
+
+        return "\n\n".join(sections)
+
+    def _generate_header(self, ctx: BundleContext) -> str:
+        """Generate the header section."""
+        project_name = ctx.root.name
+        return f"""# AI_CONTEXT.md
+
+> **Auto-generated by pybundle** — {time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime())}
+>
+> **Purpose**: Give an AI assistant (or a new dev) just enough truth to make safe, consistent changes without guessing.
+>
+> **Rules**: Prefer facts over vibes. Link to files. Keep it updated.
+
+**Project**: `{project_name}`
+
+---
+
+**How to interpret this document:**
+
+* **Known Facts** — Extracted directly from code/configs with file:line refs (high confidence)
+* **Inferred** — Pattern matching auto-detection (verify before trusting)
+
+When you see file paths or specific references, treat as known fact. When you see "(detected)" without refs, verify first."""
+
+    def _generate_project_overview(self, ctx: BundleContext) -> str:
+        """Generate section 0: What this project is."""
+        # Try to extract from README
+        readme_path = ctx.root / "README.md"
+        description = "Python project"
+        
+        if readme_path.exists():
+            try:
+                content = readme_path.read_text(encoding="utf-8", errors="ignore")
+                lines = content.splitlines()
+                # Look for first non-empty, non-heading line as description
+                for line in lines[1:10]:  # Check first 10 lines
+                    line = line.strip()
+                    if line and not line.startswith("#") and not line.startswith("!"):
+                        description = line
+                        break
+            except Exception:
+                pass
+
+        # Detect framework
+        framework = self._detect_framework(ctx.root)
+        framework_note = f" (using {framework})" if framework else ""
+
+        return f"""---
+
+## 0) What this project is
+
+**One-liner:** {description}
+
+**Type:** {framework_note if framework_note else "Python application"}
+
+**Core functionality:**
+{self._detect_core_functionality(ctx.root)}
+
+**Entry points:**
+{self._list_entrypoints(ctx.root)}"""
+
+    def _generate_how_to_run(self, ctx: BundleContext) -> str:
+        """Generate section 1: How to run it."""
+        python_version = "3.9+"
+        if ctx.tools.python:
+            try:
+                result = subprocess.run(  # nosec B603
+                    [ctx.tools.python, "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                if result.returncode == 0:
+                    python_version = result.stdout.strip().replace("Python ", "")
+            except Exception:
+                pass
+
+        # Detect requirements file
+        req_file = "requirements.txt"
+        if (ctx.root / "pyproject.toml").exists():
+            req_file = "pyproject.toml (using pip install .)"
+
+        # Detect how to run
+        run_command = self._detect_run_command(ctx.root)
+
+        return f"""---
+
+## 1) How to run it (local)
+
+**Prerequisites:**
+
+* Python: `{python_version}`
+* Dependencies: See `{req_file}`
+
+**Install:**
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
+pip install -r requirements.txt
+```
+
+**Run:**
+
+```bash
+{run_command}
+```
+
+**Development tasks:**
+
+```bash
+# Format code
+ruff format .
+
+# Lint
+ruff check .
+
+# Type check
+mypy .
+
+# Run tests
+pytest
+```"""
+
+    def _generate_repo_map(self, ctx: BundleContext) -> str:
+        """Generate section 2: Repository map."""
+        # Find key directories
+        key_dirs = []
+        for dir_name in ["app", "src", "lib", "core", "api", "routers", "models"]:
+            dir_path = ctx.root / dir_name
+            if dir_path.is_dir():
+                key_dirs.append(f"* `{dir_name}/` — {self._describe_directory(dir_path)}")
+
+        # Find key files
+        key_files = []
+        for file_name in ["main.py", "app.py", "__main__.py", "server.py", "cli.py"]:
+            file_path = ctx.root / file_name
+            if file_path.exists():
+                key_files.append(f"* `{file_name}` — Main entry point")
+
+        dirs_section = "\n".join(key_dirs) if key_dirs else "* (Auto-detection found no standard structure)"
+        files_section = "\n".join(key_files) if key_files else "* (No main entry files detected)"
+
+        return f"""---
+
+## 2) Repository map (what to read first)
+
+### Primary entry points
+
+{files_section}
+
+### Key directories
+
+{dirs_section}
+
+### Tests
+
+* `tests/` — Test suite (if present)"""
+
+    def _generate_architecture(self, ctx: BundleContext) -> str:
+        """Generate section 3: Architecture & patterns."""
+        framework = self._detect_framework(ctx.root)
+        
+        patterns = []
+        if self._file_exists_in_tree(ctx.root, "*router*.py"):
+            patterns.append("* Routing-based architecture (routers define endpoints)")
+        if self._file_exists_in_tree(ctx.root, "*service*.py"):
+            patterns.append("* Service layer pattern (business logic in services)")
+        if self._file_exists_in_tree(ctx.root, "*repository*.py") or self._file_exists_in_tree(ctx.root, "*repo.py"):
+            patterns.append("* Repository pattern (data access abstraction)")
+        if self._file_exists_in_tree(ctx.root, "middleware*.py"):
+            patterns.append("* Middleware for cross-cutting concerns")
+
+        patterns_section = "\n".join(patterns) if patterns else "* (No clear architectural patterns auto-detected)"
+
+        return f"""---
+
+## 3) Architecture & patterns
+
+**Framework:** {framework or "Not detected"}
+
+**Key patterns:**
+
+{patterns_section}
+
+**Error handling:**
+
+{self._detect_error_handling(ctx.root)}
+
+**Logging:**
+
+{self._detect_logging(ctx.root)}"""
+
+    def _generate_configuration(self, ctx: BundleContext) -> str:
+        """Generate section 4: Configuration."""
+        env_vars = self._extract_env_vars(ctx.root)
+        
+        required = []
+        optional = []
+        
+        for var in sorted(env_vars.keys()):
+            refs = env_vars[var]
+            # Show first 3 file:line references
+            ref_str = ", ".join(f"{path}:{line}" for path, line in refs[:3])
+            if len(refs) > 3:
+                ref_str += f" (+{len(refs) - 3} more)"
+            
+            # Heuristic: vars with "SECRET", "KEY", "TOKEN" are likely required
+            if any(x in var.upper() for x in ["SECRET", "KEY", "TOKEN", "PASSWORD"]):
+                required.append(f"* `{var}` — used in [{ref_str}]")
+            else:
+                optional.append(f"* `{var}` — used in [{ref_str}]")
+        
+        required_section = "\n".join(required) if required else "* (None detected)"
+        optional_section = "\n".join(optional) if optional else "* (None detected)"
+
+        config_files = []
+        for cf in ["pyproject.toml", "setup.cfg", "mypy.ini", ".env.example"]:
+            if (ctx.root / cf).exists():
+                config_files.append(f"* `{cf}`")
+        
+        config_section = "\n".join(config_files) if config_files else "* (None detected)"
+
+        return f"""---
+
+## 4) Configuration (env vars + config files)
+
+**Required environment variables:**
+
+{required_section}
+
+**Optional environment variables:**
+
+{optional_section}
+
+**Config files:**
+
+{config_section}"""
+
+    def _generate_data_model(self, ctx: BundleContext) -> str:
+        """Generate section 5: Data model & storage."""
+        # Detect database usage
+        db_type = self._detect_database(ctx.root)
+        orm = self._detect_orm(ctx.root)
+        
+        # Find model files
+        model_files = []
+        for pattern in ["*model*.py", "*schema*.py"]:
+            for p in ctx.root.rglob(pattern):
+                if not any(x in p.parts for x in [".venv", "venv", "__pycache__", "artifacts"]):
+                    rel_path = p.relative_to(ctx.root)
+                    model_files.append(f"* `{rel_path}` — Data models/schemas")
+                    if len(model_files) >= 3:  # Limit to 3 files
+                        break
+        
+        models_section = "\n".join(model_files) if model_files else "* (No model files detected)"
+
+        return f"""---
+
+## 5) Data model & storage
+
+**Database:** {db_type or "Not detected"}
+
+**ORM/Data layer:** {orm or "Not detected"}
+
+**Model files:**
+
+{models_section}
+
+**Migrations:**
+
+{self._detect_migrations(ctx.root)}"""
+
+    def _generate_api_surface(self, ctx: BundleContext) -> str:
+        """Generate section 6: API surface."""
+        # Detect API routes
+        routes = self._extract_routes(ctx.root)
+        
+        if routes:
+            routes_section = "\n".join(f"* `{r}`" for r in routes[:10])  # Limit to 10
+        else:
+            routes_section = "* (No API routes auto-detected)"
+
+        return f"""---
+
+## 6) API surface (what's stable)
+
+**Detected endpoints:**
+
+{routes_section}
+
+**Note:** This is auto-detected. Verify actual endpoints in your router files."""
+
+    def _generate_tests_quality(self, ctx: BundleContext) -> str:
+        """Generate section 7: Tests & quality gates."""
+        test_framework = "pytest" if self._file_exists_in_tree(ctx.root, "test_*.py") else "Not detected"
+        test_dir = "tests/" if (ctx.root / "tests").is_dir() else "Not detected"
+
+        return f"""---
+
+## 7) Tests & quality gates
+
+**Test framework:** {test_framework}
+
+**Test location:** `{test_dir}`
+
+**Run tests:**
+
+```bash
+pytest
+```
+
+**Quality checks:**
+
+```bash
+# Linting
+ruff check .
+
+# Type checking
+mypy .
+
+# Code coverage
+pytest --cov
+```"""
+
+    def _generate_sharp_edges(self, ctx: BundleContext) -> str:
+        """Generate section 8: Sharp edges."""
+        return """---
+
+## 8) Sharp edges (gotchas)
+
+**Known issues:**
+
+* (Add known issues manually)
+
+**Common mistakes:**
+
+* (Add common mistakes manually)
+
+**Performance notes:**
+
+* (Add performance considerations manually)"""
+
+    def _generate_change_guide(self, ctx: BundleContext) -> str:
+        """Generate section 9: Change guide."""
+        return """---
+
+## 9) Change guide (common tasks)
+
+**Add a new API endpoint:**
+
+1. Create route handler in appropriate router file
+2. Add validation schemas if needed
+3. Update tests
+4. Document in OpenAPI/docstring
+
+**Add a new database model:**
+
+1. Define model in models file
+2. Create migration (if using migrations)
+3. Update related services/repositories
+4. Add tests
+
+**Add a new dependency:**
+
+```bash
+pip install <package>
+pip freeze > requirements.txt
+```"""
+
+    def _generate_ai_rules(self, ctx: BundleContext) -> str:
+        """Generate section 10: AI rules."""
+        return """---
+
+## 10) AI rules (when changing code)
+
+**ALWAYS:**
+
+* Preserve existing error handling patterns
+* Maintain type hints on all function signatures
+* Update tests when changing behavior
+* Keep existing logging format
+* Follow the patterns in existing code
+
+**NEVER:**
+
+* Remove type hints
+* Skip error handling
+* Change API contracts without discussion
+* Remove existing tests
+* Modify configuration defaults without noting it
+
+**WHEN IN DOUBT:**
+
+* Ask before changing database schemas
+* Ask before adding new dependencies
+* Ask before changing API response shapes
+* Check existing code for similar patterns"""
+
+    # Helper methods for detection
+
+    def _detect_framework(self, root: Path) -> str | None:
+        """Detect web framework used."""
+        for p in root.rglob("*.py"):
+            if any(x in p.parts for x in [".venv", "venv", "__pycache__"]):
+                continue
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                if "from fastapi" in content or "import fastapi" in content:
+                    return "FastAPI"
+                if "from flask" in content or "import flask" in content:
+                    return "Flask"
+                if "from django" in content or "import django" in content:
+                    return "Django"
+            except Exception:
+                continue
+        return None
+
+    def _detect_core_functionality(self, root: Path) -> str:
+        """Detect core functionality from code structure."""
+        features = []
+        
+        if self._file_exists_in_tree(root, "*api*.py") or self._file_exists_in_tree(root, "*router*.py"):
+            features.append("* REST API endpoints")
+        if self._file_exists_in_tree(root, "*template*.html") or (root / "templates").is_dir():
+            features.append("* Server-side HTML rendering")
+        if self._file_exists_in_tree(root, "*websocket*.py"):
+            features.append("* WebSocket support")
+        if self._file_exists_in_tree(root, "*celery*.py") or self._file_exists_in_tree(root, "*task*.py"):
+            features.append("* Background task processing")
+        if self._file_exists_in_tree(root, "*auth*.py"):
+            features.append("* Authentication/authorization")
+        
+        return "\n".join(features) if features else "* (Auto-detection could not determine core features)"
+
+    def _list_entrypoints(self, root: Path) -> str:
+        """List detected entry points."""
+        entrypoints = []
+        
+        # Check for __main__.py
+        if (root / "__main__.py").exists():
+            entrypoints.append("* `python -m <package>` (via __main__.py)")
+        
+        # Check for main app blocks in common locations
+        for pattern in ["main.py", "app.py", "server.py", "*/main.py", "*/app.py"]:
+            for p in root.glob(pattern):
+                if should_exclude_from_analysis(p):
+                    continue
+                try:
+                    content = p.read_text(encoding="utf-8", errors="ignore")
+                    if 'if __name__ == "__main__"' in content:
+                        rel_path = p.relative_to(root)
+                        entrypoints.append(f"* `python {rel_path}` (__main__ block)")
+                except Exception:
+                    pass
+        
+        # Detect FastAPI/uvicorn apps
+        for p in root.rglob("*.py"):
+            if should_exclude_from_analysis(p):
+                continue
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                if "FastAPI(" in content:
+                    # Extract variable name
+                    import re
+                    match = re.search(r'(\w+)\s*=\s*FastAPI\(', content)
+                    if match:
+                        app_var = match.group(1)
+                        rel_path = str(p.relative_to(root)).replace("/", ".").replace("\\", ".").replace(".py", "")
+                        entrypoints.append(f"* `uvicorn {rel_path}:{app_var}` (FastAPI)")
+            except Exception:
+                pass
+        
+        # Check for console_scripts in pyproject.toml
+        pyproject = root / "pyproject.toml"
+        if pyproject.exists():
+            try:
+                import tomllib
+                with open(pyproject, "rb") as f:
+                    data = tomllib.load(f)
+                
+                scripts = data.get("project", {}).get("scripts", {})
+                for name, target in scripts.items():
+                    entrypoints.append(f"* `{name}` → `{target}` (console script)")
+                    
+                poetry_scripts = data.get("tool", {}).get("poetry", {}).get("scripts", {})
+                for name, target in poetry_scripts.items():
+                    entrypoints.append(f"* `{name}` → `{target}` (Poetry script)")
+            except Exception:
+                # Fallback to text search
+                try:
+                    content = pyproject.read_text(encoding="utf-8")
+                    if "[project.scripts]" in content or "[tool.poetry.scripts]" in content:
+                        entrypoints.append("* Console scripts (see pyproject.toml)")
+                except Exception:
+                    pass
+        
+        return "\n".join(entrypoints) if entrypoints else "* (No entry points detected)"
+
+    def _detect_run_command(self, root: Path) -> str:
+        """Detect how to run the application."""
+        # Check for FastAPI apps first (most specific)
+        for p in root.rglob("*.py"):
+            if should_exclude_from_analysis(p):
+                continue
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                if "FastAPI(" in content:
+                    import re
+                    match = re.search(r'(\w+)\s*=\s*FastAPI\(', content)
+                    if match:
+                        app_var = match.group(1)
+                        rel_path = str(p.relative_to(root)).replace("/", ".").replace("\\", ".").replace(".py", "")
+                        return f"uvicorn {rel_path}:{app_var} --reload"
+            except Exception:
+                pass
+        
+        # Check for common patterns
+        if (root / "main.py").exists():
+            return "python main.py"
+        if (root / "app.py").exists():
+            return "python app.py"
+        if (root / "__main__.py").exists():
+            return f"python -m {root.name}"
+        
+        return "# Run command not auto-detected, see README.md"
+
+    def _describe_directory(self, dir_path: Path) -> str:
+        """Provide a brief description of a directory's purpose."""
+        dir_name = dir_path.name
+        
+        descriptions = {
+            "app": "Application code",
+            "src": "Source code",
+            "api": "API layer",
+            "routers": "Route handlers",
+            "models": "Data models",
+            "services": "Business logic",
+            "core": "Core functionality",
+            "lib": "Library code",
+            "utils": "Utility functions",
+            "templates": "HTML templates",
+            "static": "Static assets",
+            "tests": "Test suite",
+        }
+        
+        return descriptions.get(dir_name, "Code directory")
+
+    def _file_exists_in_tree(self, root: Path, pattern: str) -> bool:
+        """Check if any file matching pattern exists in tree."""
+        try:
+            for _ in root.rglob(pattern):
+                return True
+        except Exception:
+            pass
+        return False
+
+    def _detect_error_handling(self, root: Path) -> str:
+        """Detect error handling patterns."""
+        has_middleware = self._file_exists_in_tree(root, "*middleware*.py")
+        has_exception_handlers = False
+        
+        for p in root.rglob("*.py"):
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                if "@app.exception_handler" in content or "HTTPException" in content:
+                    has_exception_handlers = True
+                    break
+            except Exception:
+                continue
+        
+        if has_middleware or has_exception_handlers:
+            return "* Centralized exception handling detected"
+        return "* (Error handling pattern not auto-detected)"
+
+    def _detect_logging(self, root: Path) -> str:
+        """Detect logging configuration."""
+        for p in root.rglob("*.py"):
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                if "import logging" in content or "from logging" in content:
+                    return "* Python logging module in use"
+            except Exception:
+                continue
+        return "* (Logging not detected)"
+
+    def _extract_env_vars(self, root: Path) -> dict[str, list[tuple[str, int]]]:
+        """
+        Extract environment variables used in the project with file+line references.
+        Returns dict mapping var name to list of (relative_path, line_number) tuples.
+        Filters out OS/toolchain noise.
+        """
+        # OS/toolchain vars to filter out - these pollute AI context
+        OS_NOISE = {
+            # CI/CD platforms
+            "GITHUB_ACTIONS", "GITHUB_TOKEN", "GITHUB_WORKSPACE", "GITHUB_SHA",
+            "CI", "CONTINUOUS_INTEGRATION", "GITLAB_CI", "CIRCLECI", "TRAVIS",
+            # Testing frameworks
+            "PYTEST_CURRENT_TEST", "PYTEST_VERSION", "PYTEST_TIMEOUT",
+            # Python tooling
+            "PYTHONPATH", "PYTHONHOME", "PYTHONDONTWRITEBYTECODE", "PYTHONUNBUFFERED",
+            "VIRTUAL_ENV", "CONDA_DEFAULT_ENV", "CONDA_PREFIX",
+            # Build/compile
+            "CC", "CXX", "CFLAGS", "CXXFLAGS", "LDFLAGS", "AR", "NM", "RANLIB",
+            # Android SDK (common on dev machines)
+            "ANDROID_HOME", "ANDROID_SDK_ROOT", "ANDROID_NDK_HOME",
+            # System/OS
+            "PATH", "HOME", "USER", "SHELL", "LANG", "LC_ALL", "TZ", "TERM",
+            "PWD", "OLDPWD", "SHLVL", "EDITOR", "PAGER",
+            # SSL/Security debugging
+            "SSLKEYLOGFILE", "SSL_CERT_FILE", "SSL_CERT_DIR",
+            # Package managers
+            "PIP_INDEX_URL", "PIP_EXTRA_INDEX_URL", "NPM_TOKEN",
+            # Display/X11
+            "DISPLAY", "XAUTHORITY", "WAYLAND_DISPLAY",
+        }
+        
+        env_vars: dict[str, list[tuple[str, int]]] = {}
+        
+        # Patterns to detect env var usage
+        import re
+        patterns = [
+            re.compile(r'os\.getenv\(["\']([A-Z_]+)["\']\)'),
+            re.compile(r'os\.environ\[["\']([A-Z_]+)["\']\]'),
+            re.compile(r'os\.environ\.get\(["\']([A-Z_]+)["\']\)'),
+        ]
+        
+        for p in root.rglob("*.py"):
+            if should_exclude_from_analysis(p):
+                continue
+            try:
+                with open(p, "r", encoding="utf-8", errors="ignore") as f:
+                    for line_num, line in enumerate(f, start=1):
+                        for pattern in patterns:
+                            for match in pattern.finditer(line):
+                                var_name = match.group(1)
+                                # Filter OS/toolchain noise
+                                if var_name not in OS_NOISE:
+                                    rel_path = str(p.relative_to(root))
+                                    if var_name not in env_vars:
+                                        env_vars[var_name] = []
+                                    env_vars[var_name].append((rel_path, line_num))
+            except Exception:
+                continue
+        
+        return env_vars
+
+    def _detect_database(self, root: Path) -> str | None:
+        """Detect database type."""
+        for p in root.rglob("*.py"):
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                if "postgresql" in content.lower() or "psycopg" in content:
+                    return "PostgreSQL"
+                if "mysql" in content.lower() or "pymysql" in content:
+                    return "MySQL"
+                if "sqlite" in content.lower():
+                    return "SQLite"
+                if "mongodb" in content.lower() or "pymongo" in content:
+                    return "MongoDB"
+            except Exception:
+                continue
+        return None
+
+    def _detect_orm(self, root: Path) -> str | None:
+        """Detect ORM/data layer."""
+        for p in root.rglob("*.py"):
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                if "from sqlalchemy" in content or "import sqlalchemy" in content:
+                    return "SQLAlchemy"
+                if "from django.db" in content:
+                    return "Django ORM"
+                if "from tortoise" in content:
+                    return "Tortoise ORM"
+            except Exception:
+                continue
+        return None
+
+    def _detect_migrations(self, root: Path) -> str:
+        """Detect migration system."""
+        if (root / "migrations").is_dir() or (root / "alembic").is_dir():
+            return "* Migration system detected (likely Alembic)"
+        return "* (No migrations detected)"
+
+    def _extract_routes(self, root: Path) -> list[str]:
+        """Extract API routes from code."""
+        routes = []
+        
+        for p in root.rglob("*.py"):
+            if any(x in p.parts for x in [".venv", "venv", "__pycache__", "artifacts"]):
+                continue
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                import re
+                # FastAPI patterns
+                patterns = [
+                    r'@\w+\.(get|post|put|delete|patch)\(["\']([^"\']+)["\']\)',
+                    r'@app\.route\(["\']([^"\']+)["\']\)',
+                ]
+                for pattern in patterns:
+                    matches = re.findall(pattern, content)
+                    for match in matches:
+                        if isinstance(match, tuple):
+                            if len(match) == 2:
+                                routes.append(f"{match[0].upper()} {match[1]}")
+                            else:
+                                routes.append(f"GET {match[0]}")
+                        else:
+                            routes.append(f"GET {match}")
+            except Exception:
+                continue
+        
+        return sorted(set(routes))