Code To Prd

{
  "project": {
    "root": "/path/to/my-app",
    "name": "my-app",
    "framework": "next",
    "detected_frameworks": ["next", "react"],
    "key_dependencies": {
      "next": "14.1.0",
      "react": "18.2.0",
      "tailwindcss": "3.4.1",
      "axios": "1.6.5",
      "@tanstack/react-query": "5.17.0"
    },
    "stack_type": "fullstack"
  },
  "structure": {
    "total_files": 87,
    "components": {
      "components": 42,
      "modules": 35
    },
    "route_dirs": ["/path/to/my-app/app"],
    "api_dirs": ["/path/to/my-app/app/api"],
    "state_dirs": ["/path/to/my-app/src/store"],
    "i18n_dirs": [],
    "controller_dirs": [],
    "model_dirs": [],
    "dto_dirs": []
  },
  "routes": {
    "count": 8,
    "frontend_pages": [
      {"path": "/", "source": "app/page.tsx", "filesystem": true},
      {"path": "/dashboard", "source": "app/dashboard/page.tsx", "filesystem": true},
      {"path": "/users", "source": "app/users/page.tsx", "filesystem": true},
      {"path": "/users/:id", "source": "app/users/[id]/page.tsx", "filesystem": true},
      {"path": "/settings", "source": "app/settings/page.tsx", "filesystem": true}
    ],
    "backend_endpoints": [
      {"path": "/api/users", "method": "GET", "source": "app/api/users/route.ts", "type": "backend"},
      {"path": "/api/users", "method": "POST", "source": "app/api/users/route.ts", "type": "backend"},
      {"path": "/api/users/:id", "method": "GET", "source": "app/api/users/[id]/route.ts", "type": "backend"}
    ],
    "pages": []
  },
  "apis": {
    "total": 5,
    "integrated": 4,
    "mock": 1,
    "endpoints": [
      {"path": "/api/users", "method": "GET", "source": "services/user.ts", "integrated": true, "mock_detected": false},
      {"path": "/api/users", "method": "POST", "source": "services/user.ts", "integrated": true, "mock_detected": false},
      {"path": "/api/users/:id", "method": "GET", "source": "services/user.ts", "integrated": true, "mock_detected": false},
      {"path": "/api/users/:id", "method": "PUT", "source": "services/user.ts", "integrated": true, "mock_detected": false},
      {"path": "/api/dashboard/stats", "method": "GET", "source": "services/dashboard.ts", "integrated": false, "mock_detected": true}
    ]
  },
  "enums": {
    "count": 2,
    "definitions": [
      {"name": "UserRole", "type": "enum", "values": {"ADMIN": "admin", "USER": "user", "MANAGER": "manager"}, "source": "types/user.ts"},
      {"name": "STATUS_MAP", "type": "constant_map", "values": {"active": "Active", "inactive": "Inactive", "suspended": "Suspended"}, "source": "constants/status.ts"}
    ]
  },
  "models": {
    "count": 0,
    "definitions": []
  },
  "summary": {
    "pages": 5,
    "backend_endpoints": 3,
    "api_endpoints": 5,
    "api_integrated": 4,
    "api_mock": 1,
    "enums": 2,
    "models": 0,
    "has_i18n": false,
    "has_state_management": true,
    "stack_type": "fullstack"
  }
}

prd/

#!/usr/bin/env python3
"""Analyze any codebase (frontend, backend, or fullstack) and extract routes, APIs, models, and structure.

Supports: React, Vue, Angular, Svelte, Next.js, Nuxt, NestJS, Express, Django, FastAPI, Flask.
Stdlib only — no third-party dependencies. Outputs JSON for downstream PRD generation.

Usage:
    python3 codebase_analyzer.py /path/to/project
    python3 codebase_analyzer.py /path/to/project --output prd-analysis.json
    python3 codebase_analyzer.py /path/to/project --format markdown
"""

import argparse
import json
import os
import re
from collections import defaultdict
from pathlib import Path
from typing import Any, Dict, List, Optional, Set, Tuple

IGNORED_DIRS = {
    ".git", "node_modules", ".next", "dist", "build", "coverage",
    "venv", ".venv", "__pycache__", ".nuxt", ".output", ".cache",
    ".turbo", ".vercel", "out", "storybook-static",
    ".tox", ".mypy_cache", ".pytest_cache", "htmlcov", "staticfiles",
    "media", "migrations", "egg-info",
}

FRAMEWORK_SIGNALS = {
    "react": ["react", "react-dom"],
    "next": ["next"],
    "vue": ["vue"],
    "nuxt": ["nuxt"],
    "angular": ["@angular/core"],
    "svelte": ["svelte"],
    "sveltekit": ["@sveltejs/kit"],
    "solid": ["solid-js"],
    "astro": ["astro"],
    "remix": ["@remix-run/react"],
    "nestjs": ["@nestjs/core"],
    "express": ["express"],
    "fastify": ["fastify"],
}

# Python backend frameworks detected via project files (no package.json)
PYTHON_FRAMEWORK_FILES = {
    "django": ["manage.py", "settings.py"],
    "fastapi": ["main.py"],  # confirmed via imports
    "flask": ["app.py"],      # confirmed via imports
}

ROUTE_FILE_PATTERNS = [
    "**/router.{ts,tsx,js,jsx}",
    "**/routes.{ts,tsx,js,jsx}",
    "**/routing.{ts,tsx,js,jsx}",
    "**/app-routing*.{ts,tsx,js,jsx}",
]

ROUTE_DIR_PATTERNS = [
    "pages", "views", "routes", "app",
    "src/pages", "src/views", "src/routes", "src/app",
]

API_DIR_PATTERNS = [
    "api", "services", "requests", "endpoints", "client",
    "src/api", "src/services", "src/requests",
]

STATE_DIR_PATTERNS = [
    "store", "stores", "models", "context", "state",
    "src/store", "src/stores", "src/models", "src/context",
]

I18N_DIR_PATTERNS = [
    "locales", "i18n", "lang", "translations", "messages",
    "src/locales", "src/i18n", "src/lang",
]

# Backend-specific directory patterns
CONTROLLER_DIR_PATTERNS = [
    "controllers", "src/controllers", "src/modules",
]

MODEL_DIR_PATTERNS = [
    "models", "entities", "src/entities", "src/models",
]

DTO_DIR_PATTERNS = [
    "dto", "dtos", "src/dto", "serializers",
]

MOCK_SIGNALS = [
    r"setTimeout\s*\(.*\breturn\b",
    r"Promise\.resolve\s*\(",
    r"\.mock\.",
    r"__mocks__",
    r"mockData",
    r"mock[A-Z]",
    r"faker\.",
    r"fixtures?/",
]

REAL_API_SIGNALS = [
    r"\baxios\b",
    r"\bfetch\s*\(",
    r"httpGet|httpPost|httpPut|httpDelete|httpPatch",
    r"\.get\s*\(\s*['\"`/]",
    r"\.post\s*\(\s*['\"`/]",
    r"\.put\s*\(\s*['\"`/]",
    r"\.delete\s*\(\s*['\"`/]",
    r"\.patch\s*\(\s*['\"`/]",
    r"useSWR|useQuery|useMutation",
    r"\$http\.",
    r"this\.http\.",
]

ROUTE_PATTERNS = [
    # React Router
    r'<Route\s+[^>]*path\s*=\s*["\']([^"\']+)["\']',
    r'path\s*:\s*["\']([^"\']+)["\']',
    # Vue Router
    r'path\s*:\s*["\']([^"\']+)["\']',
    # Angular
    r'path\s*:\s*["\']([^"\']+)["\']',
]

API_PATH_PATTERNS = [
    r'["\'](?:GET|POST|PUT|DELETE|PATCH)["\'].*?["\'](/[a-zA-Z0-9/_\-:{}]+)["\']',
    r'(?:get|post|put|delete|patch)\s*\(\s*["\'](/[a-zA-Z0-9/_\-:{}]+)["\']',
    r'(?:url|path|endpoint|baseURL)\s*[:=]\s*["\'](/[a-zA-Z0-9/_\-:{}]+)["\']',
    r'fetch\s*\(\s*[`"\'](?:https?://[^/]+)?(/[a-zA-Z0-9/_\-:{}]+)',
]

COMPONENT_EXTENSIONS = {".tsx", ".jsx", ".vue", ".svelte", ".astro"}
CODE_EXTENSIONS = {".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte", ".astro", ".py"}

# NestJS decorator patterns
NEST_ROUTE_PATTERNS = [
    r"@(?:Get|Post|Put|Delete|Patch|Head|Options|All)\s*\(\s*['\"]([^'\"]*)['\"]",
    r"@Controller\s*\(\s*['\"]([^'\"]*)['\"]",
]

# Django URL patterns
DJANGO_ROUTE_PATTERNS = [
    r"path\s*\(\s*['\"]([^'\"]+)['\"]",
    r"url\s*\(\s*r?['\"]([^'\"]+)['\"]",
    r"register\s*\(\s*r?['\"]([^'\"]+)['\"]",
]

# Django/Python model patterns
PYTHON_MODEL_PATTERNS = [
    r"class\s+(\w+)\s*\(.*?models\.Model\)",
    r"class\s+(\w+)\s*\(.*?BaseModel\)",  # Pydantic
]

# NestJS entity/DTO patterns
NEST_MODEL_PATTERNS = [
    r"@Entity\s*\(.*?\)\s*(?:export\s+)?class\s+(\w+)",
    r"class\s+(\w+(?:Dto|DTO|Entity|Schema))\b",
]


def detect_framework(project_root: Path) -> Dict[str, Any]:
    """Detect framework from package.json (Node.js) or project files (Python)."""
    detected = []
    all_deps = {}
    pkg_name = ""
    pkg_version = ""

    # Node.js detection via package.json
    pkg_path = project_root / "package.json"
    if pkg_path.exists():
        try:
            with open(pkg_path) as f:
                pkg = json.load(f)
            pkg_name = pkg.get("name", "")
            pkg_version = pkg.get("version", "")
            for key in ("dependencies", "devDependencies", "peerDependencies"):
                all_deps.update(pkg.get(key, {}))
            for framework, signals in FRAMEWORK_SIGNALS.items():
                if any(s in all_deps for s in signals):
                    detected.append(framework)
        except (json.JSONDecodeError, IOError):
            pass

    # Python backend detection via project files and imports
    if (project_root / "manage.py").exists():
        detected.append("django")
    if (project_root / "requirements.txt").exists() or (project_root / "pyproject.toml").exists():
        for req_file in ["requirements.txt", "pyproject.toml", "setup.py", "Pipfile"]:
            req_path = project_root / req_file
            if req_path.exists():
                try:
                    content = req_path.read_text(errors="replace").lower()
                    if "django" in content and "django" not in detected:
                        detected.append("django")
                    if "fastapi" in content:
                        detected.append("fastapi")
                    if "flask" in content and "flask" not in detected:
                        detected.append("flask")
                except IOError:
                    pass

    # Prefer specific over generic
    priority = [
        "sveltekit", "next", "nuxt", "remix", "astro",  # fullstack JS
        "nestjs", "express", "fastify",                   # backend JS
        "django", "fastapi", "flask",                     # backend Python
        "angular", "svelte", "vue", "react", "solid",     # frontend JS
    ]
    framework = "unknown"
    for fw in priority:
        if fw in detected:
            framework = fw
            break

    return {
        "framework": framework,
        "name": pkg_name or project_root.name,
        "version": pkg_version,
        "detected_frameworks": detected,
        "dependency_count": len(all_deps),
        "key_deps": {k: v for k, v in all_deps.items()
                     if any(s in k for s in ["router", "redux", "vuex", "pinia", "zustand",
                                              "mobx", "recoil", "jotai", "tanstack", "swr",
                                              "axios", "tailwind", "material", "ant",
                                              "chakra", "shadcn", "i18n", "intl",
                                              "typeorm", "prisma", "sequelize", "mongoose",
                                              "passport", "jwt", "class-validator"])},
    }


def find_dirs(root: Path, patterns: List[str]) -> List[Path]:
    """Find directories matching common patterns."""
    found = []
    for pattern in patterns:
        candidate = root / pattern
        if candidate.is_dir():
            found.append(candidate)
    return found


def walk_files(root: Path, extensions: Set[str] = CODE_EXTENSIONS) -> List[Path]:
    """Walk project tree, skip ignored dirs, return files matching extensions."""
    results = []
    for dirpath, dirnames, filenames in os.walk(root):
        dirnames[:] = [d for d in dirnames if d not in IGNORED_DIRS]
        for fname in filenames:
            if Path(fname).suffix in extensions:
                results.append(Path(dirpath) / fname)
    return results


def extract_routes_from_file(filepath: Path) -> List[Dict[str, str]]:
    """Extract route definitions from a file."""
    routes = []
    try:
        content = filepath.read_text(errors="replace")
    except IOError:
        return routes

    for pattern in ROUTE_PATTERNS:
        for match in re.finditer(pattern, content):
            path = match.group(1)
            if path and not path.startswith("http") and len(path) < 200:
                routes.append({
                    "path": path,
                    "source": str(filepath),
                    "line": content[:match.start()].count("\n") + 1,
                })
    return routes


def extract_routes_from_filesystem(pages_dir: Path, root: Path) -> List[Dict[str, str]]:
    """Infer routes from file-system routing (Next.js, Nuxt, SvelteKit)."""
    routes = []
    for filepath in sorted(pages_dir.rglob("*")):
        if filepath.is_file() and filepath.suffix in CODE_EXTENSIONS:
            rel = filepath.relative_to(pages_dir)
            route = "/" + str(rel.with_suffix("")).replace("\\", "/")
            # Normalize index routes
            route = re.sub(r"/index$", "", route) or "/"
            # Convert [param] to :param
            route = re.sub(r"\[\.\.\.(\w+)\]", r"*\1", route)
            route = re.sub(r"\[(\w+)\]", r":\1", route)
            routes.append({
                "path": route,
                "source": str(filepath),
                "filesystem": True,
            })
    return routes


def extract_apis_from_file(filepath: Path) -> List[Dict[str, Any]]:
    """Extract API calls from a file."""
    apis = []
    try:
        content = filepath.read_text(errors="replace")
    except IOError:
        return apis

    is_mock = any(re.search(p, content) for p in MOCK_SIGNALS)
    is_real = any(re.search(p, content) for p in REAL_API_SIGNALS)

    for pattern in API_PATH_PATTERNS:
        for match in re.finditer(pattern, content):
            path = match.group(1) if match.lastindex else match.group(0)
            if path and len(path) < 200:
                # Try to detect HTTP method
                context = content[max(0, match.start() - 100):match.end()]
                method = "UNKNOWN"
                for m in ["GET", "POST", "PUT", "DELETE", "PATCH"]:
                    if m.lower() in context.lower():
                        method = m
                        break

                apis.append({
                    "path": path,
                    "method": method,
                    "source": str(filepath),
                    "line": content[:match.start()].count("\n") + 1,
                    "integrated": is_real and not is_mock,
                    "mock_detected": is_mock,
                })
    return apis


def extract_enums(filepath: Path) -> List[Dict[str, Any]]:
    """Extract enum/constant definitions."""
    enums = []
    try:
        content = filepath.read_text(errors="replace")
    except IOError:
        return enums

    # TypeScript enums
    for match in re.finditer(r"enum\s+(\w+)\s*\{([^}]+)\}", content):
        name = match.group(1)
        body = match.group(2)
        values = re.findall(r"(\w+)\s*=\s*['\"]?([^,'\"\n]+)", body)
        enums.append({
            "name": name,
            "type": "enum",
            "values": {k.strip(): v.strip().rstrip(",") for k, v in values},
            "source": str(filepath),
        })

    # Object constant maps (const STATUS_MAP = { ... })
    for match in re.finditer(
        r"(?:const|export\s+const)\s+(\w*(?:MAP|STATUS|TYPE|ENUM|OPTION|ROLE|STATE)\w*)\s*[:=]\s*\{([^}]+)\}",
        content, re.IGNORECASE
    ):
        name = match.group(1)
        body = match.group(2)
        values = re.findall(r"['\"]?(\w+)['\"]?\s*:\s*['\"]([^'\"]+)['\"]", body)
        if values:
            enums.append({
                "name": name,
                "type": "constant_map",
                "values": dict(values),
                "source": str(filepath),
            })

    return enums


def extract_backend_routes(filepath: Path, framework: str) -> List[Dict[str, str]]:
    """Extract route definitions from NestJS controllers or Django url configs."""
    routes = []
    try:
        content = filepath.read_text(errors="replace")
    except IOError:
        return routes

    patterns = []
    if framework in ("nestjs", "express", "fastify"):
        patterns = NEST_ROUTE_PATTERNS
    elif framework == "django":
        patterns = DJANGO_ROUTE_PATTERNS

    # For NestJS, also grab the controller prefix
    controller_prefix = ""
    if framework == "nestjs":
        m = re.search(r"@Controller\s*\(\s*['\"]([^'\"]*)['\"]", content)
        if m:
            controller_prefix = "/" + m.group(1).strip("/")

    for pattern in patterns:
        for match in re.finditer(pattern, content):
            path = match.group(1)
            if not path or path.startswith("http") or len(path) > 200:
                continue
            # For NestJS method decorators, prepend controller prefix
            if framework == "nestjs" and not path.startswith("/"):
                full_path = f"{controller_prefix}/{path}".replace("//", "/")
            else:
                full_path = path if path.startswith("/") else f"/{path}"

            # Detect HTTP method from decorator name
            method = "UNKNOWN"
            ctx = content[max(0, match.start() - 30):match.start()]
            for m_name in ["Get", "Post", "Put", "Delete", "Patch"]:
                if f"@{m_name}" in ctx or f"@{m_name.lower()}" in ctx:
                    method = m_name.upper()
                    break

            routes.append({
                "path": full_path,
                "method": method,
                "source": str(filepath),
                "line": content[:match.start()].count("\n") + 1,
                "type": "backend",
            })
    return routes


def extract_models(filepath: Path, framework: str) -> List[Dict[str, Any]]:
    """Extract model/entity definitions from backend code."""
    models = []
    try:
        content = filepath.read_text(errors="replace")
    except IOError:
        return models

    patterns = PYTHON_MODEL_PATTERNS if framework in ("django", "fastapi", "flask") else NEST_MODEL_PATTERNS
    for pattern in patterns:
        for match in re.finditer(pattern, content):
            name = match.group(1)
            # Try to extract fields
            fields = []
            # For Django models: field_name = models.FieldType(...)
            if framework == "django":
                block_start = match.end()
                block = content[block_start:block_start + 2000]
                for fm in re.finditer(
                    r"(\w+)\s*=\s*models\.(\w+)\s*\(([^)]*)\)", block
                ):
                    fields.append({
                        "name": fm.group(1),
                        "type": fm.group(2),
                        "args": fm.group(3).strip()[:100],
                    })
            models.append({
                "name": name,
                "source": str(filepath),
                "framework": framework,
                "fields": fields,
            })
    return models


def count_components(files: List[Path]) -> Dict[str, int]:
    """Count components by type."""
    counts: Dict[str, int] = defaultdict(int)
    for f in files:
        if f.suffix in COMPONENT_EXTENSIONS:
            counts["components"] += 1
        elif f.suffix in {".ts", ".js"}:
            counts["modules"] += 1
    return dict(counts)


def analyze_project(project_root: Path) -> Dict[str, Any]:
    """Run full analysis on a frontend project."""
    root = Path(project_root).resolve()
    if not root.is_dir():
        return {"error": f"Not a directory: {root}"}

    # 1. Framework detection
    framework_info = detect_framework(root)

    # 2. File inventory
    all_files = walk_files(root)
    component_counts = count_components(all_files)

    # 3. Directory structure
    route_dirs = find_dirs(root, ROUTE_DIR_PATTERNS)
    api_dirs = find_dirs(root, API_DIR_PATTERNS)
    state_dirs = find_dirs(root, STATE_DIR_PATTERNS)
    i18n_dirs = find_dirs(root, I18N_DIR_PATTERNS)

    # 4. Routes (frontend + backend)
    routes = []
    fw = framework_info["framework"]

    # Frontend: config-based routes
    for f in all_files:
        if any(p in f.name.lower() for p in ["router", "routes", "routing"]):
            routes.extend(extract_routes_from_file(f))

    # Frontend: file-system routes (Next.js, Nuxt, SvelteKit)
    if fw in ("next", "nuxt", "sveltekit", "remix", "astro"):
        for d in route_dirs:
            routes.extend(extract_routes_from_filesystem(d, root))

    # Backend: NestJS controllers, Django urls
    if fw in ("nestjs", "express", "fastify", "django"):
        for f in all_files:
            if fw == "django" and "urls.py" in f.name:
                routes.extend(extract_backend_routes(f, fw))
            elif fw in ("nestjs", "express", "fastify") and ".controller." in f.name:
                routes.extend(extract_backend_routes(f, fw))

    # Deduplicate routes by path (+ method for backend)
    seen_paths: Set[str] = set()
    unique_routes = []
    for r in routes:
        key = r["path"] if r.get("type") != "backend" else f"{r.get('method', '')}:{r['path']}"
        if key not in seen_paths:
            seen_paths.add(key)
            unique_routes.append(r)
    routes = sorted(unique_routes, key=lambda r: r["path"])

    # 5. API calls
    apis = []
    for f in all_files:
        apis.extend(extract_apis_from_file(f))

    # Deduplicate APIs by path+method
    seen_apis: Set[Tuple[str, str]] = set()
    unique_apis = []
    for a in apis:
        key = (a["path"], a["method"])
        if key not in seen_apis:
            seen_apis.add(key)
            unique_apis.append(a)
    apis = sorted(unique_apis, key=lambda a: a["path"])

    # 6. Enums
    enums = []
    for f in all_files:
        enums.extend(extract_enums(f))

    # 7. Models/entities (backend)
    models = []
    if fw in ("django", "fastapi", "flask", "nestjs"):
        for f in all_files:
            if fw == "django" and "models.py" in f.name:
                models.extend(extract_models(f, fw))
            elif fw == "nestjs" and (".entity." in f.name or ".dto." in f.name):
                models.extend(extract_models(f, fw))

    # Deduplicate models by name
    seen_models: Set[str] = set()
    unique_models = []
    for m in models:
        if m["name"] not in seen_models:
            seen_models.add(m["name"])
            unique_models.append(m)
    models = sorted(unique_models, key=lambda m: m["name"])

    # Backend-specific directories
    controller_dirs = find_dirs(root, CONTROLLER_DIR_PATTERNS)
    model_dirs = find_dirs(root, MODEL_DIR_PATTERNS)
    dto_dirs = find_dirs(root, DTO_DIR_PATTERNS)

    # 8. Summary
    mock_count = sum(1 for a in apis if a.get("mock_detected"))
    real_count = sum(1 for a in apis if a.get("integrated"))
    backend_routes = [r for r in routes if r.get("type") == "backend"]
    frontend_routes = [r for r in routes if r.get("type") != "backend"]

    analysis = {
        "project": {
            "root": str(root),
            "name": framework_info.get("name", root.name),
            "framework": framework_info["framework"],
            "detected_frameworks": framework_info.get("detected_frameworks", []),
            "key_dependencies": framework_info.get("key_deps", {}),
            "stack_type": "backend" if fw in ("django", "fastapi", "flask", "nestjs", "express", "fastify") and not frontend_routes else
                          "fullstack" if backend_routes and frontend_routes else "frontend",
        },
        "structure": {
            "total_files": len(all_files),
            "components": component_counts,
            "route_dirs": [str(d) for d in route_dirs],
            "api_dirs": [str(d) for d in api_dirs],
            "state_dirs": [str(d) for d in state_dirs],
            "i18n_dirs": [str(d) for d in i18n_dirs],
            "controller_dirs": [str(d) for d in controller_dirs],
            "model_dirs": [str(d) for d in model_dirs],
            "dto_dirs": [str(d) for d in dto_dirs],
        },
        "routes": {
            "count": len(routes),
            "frontend_pages": frontend_routes,
            "backend_endpoints": backend_routes,
            "pages": routes,  # backward compat
        },
        "apis": {
            "total": len(apis),
            "integrated": real_count,
            "mock": mock_count,
            "endpoints": apis,
        },
        "enums": {
            "count": len(enums),
            "definitions": enums,
        },
        "models": {
            "count": len(models),
            "definitions": models,
        },
        "summary": {
            "pages": len(frontend_routes),
            "backend_endpoints": len(backend_routes),
            "api_endpoints": len(apis),
            "api_integrated": real_count,
            "api_mock": mock_count,
            "enums": len(enums),
            "models": len(models),
            "has_i18n": len(i18n_dirs) > 0,
            "has_state_management": len(state_dirs) > 0,
            "stack_type": "backend" if fw in ("django", "fastapi", "flask", "nestjs", "express", "fastify") and not frontend_routes else
                          "fullstack" if backend_routes and frontend_routes else "frontend",
        },
    }

    return analysis


def format_markdown(analysis: Dict[str, Any]) -> str:
    """Format analysis as markdown summary."""
    lines = []
    proj = analysis["project"]
    summary = analysis["summary"]
    stack = summary.get("stack_type", "frontend")

    lines.append(f"# Codebase Analysis: {proj['name'] or 'Project'}")
    lines.append("")
    lines.append(f"**Framework:** {proj['framework']}")
    lines.append(f"**Stack type:** {stack}")
    lines.append(f"**Total files:** {analysis['structure']['total_files']}")
    if summary.get("pages"):
        lines.append(f"**Frontend pages:** {summary['pages']}")
    if summary.get("backend_endpoints"):
        lines.append(f"**Backend endpoints:** {summary['backend_endpoints']}")
    lines.append(f"**API calls detected:** {summary['api_endpoints']} "
                 f"({summary['api_integrated']} integrated, {summary['api_mock']} mock)")
    lines.append(f"**Enums:** {summary['enums']}")
    if summary.get("models"):
        lines.append(f"**Models/entities:** {summary['models']}")
    lines.append(f"**i18n:** {'Yes' if summary['has_i18n'] else 'No'}")
    lines.append(f"**State management:** {'Yes' if summary['has_state_management'] else 'No'}")
    lines.append("")

    if analysis["routes"]["pages"]:
        lines.append("## Pages / Routes")
        lines.append("")
        lines.append("| # | Route | Source |")
        lines.append("|---|-------|--------|")
        for i, r in enumerate(analysis["routes"]["pages"], 1):
            src = r.get("source", "").split("/")[-1]
            fs = " (fs)" if r.get("filesystem") else ""
            lines.append(f"| {i} | `{r['path']}` | {src}{fs} |")
        lines.append("")

    if analysis["apis"]["endpoints"]:
        lines.append("## API Endpoints")
        lines.append("")
        lines.append("| Method | Path | Integrated | Source |")
        lines.append("|--------|------|-----------|--------|")
        for a in analysis["apis"]["endpoints"]:
            src = a.get("source", "").split("/")[-1]
            status = "✅" if a.get("integrated") else "⚠️ Mock"
            lines.append(f"| {a['method']} | `{a['path']}` | {status} | {src} |")
        lines.append("")

    if analysis["enums"]["definitions"]:
        lines.append("## Enums & Constants")
        lines.append("")
        for e in analysis["enums"]["definitions"]:
            lines.append(f"### {e['name']} ({e['type']})")
            if e["values"]:
                lines.append("| Key | Value |")
                lines.append("|-----|-------|")
                for k, v in e["values"].items():
                    lines.append(f"| {k} | {v} |")
            lines.append("")

    if analysis.get("models", {}).get("definitions"):
        lines.append("## Models / Entities")
        lines.append("")
        for m in analysis["models"]["definitions"]:
            lines.append(f"### {m['name']} ({m.get('framework', '')})")
            if m.get("fields"):
                lines.append("| Field | Type | Args |")
                lines.append("|-------|------|------|")
                for fld in m["fields"]:
                    lines.append(f"| {fld['name']} | {fld['type']} | {fld.get('args', '')} |")
            lines.append("")

    if proj.get("key_dependencies"):
        lines.append("## Key Dependencies")
        lines.append("")
        for dep, ver in sorted(proj["key_dependencies"].items()):
            lines.append(f"- `{dep}`: {ver}")
        lines.append("")

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Analyze any codebase (frontend, backend, fullstack) for PRD generation"
    )
    parser.add_argument("project", help="Path to project root")
    parser.add_argument("-o", "--output", help="Output file (default: stdout)")
    parser.add_argument(
        "-f", "--format",
        choices=["json", "markdown"],
        default="json",
        help="Output format (default: json)",
    )
    args = parser.parse_args()

    analysis = analyze_project(Path(args.project))

    if args.format == "markdown":
        output = format_markdown(analysis)
    else:
        output = json.dumps(analysis, indent=2, ensure_ascii=False)

    if args.output:
        Path(args.output).write_text(output)
        print(f"Written to {args.output}")
    else:
        print(output)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Scaffold PRD directory structure from frontend_analyzer.py output.

Reads analysis JSON and creates the prd/ directory with README.md,
per-page stubs, and appendix files pre-populated with extracted data.

Stdlib only — no third-party dependencies.

Usage:
    python3 frontend_analyzer.py /path/to/project -o analysis.json
    python3 prd_scaffolder.py analysis.json
    python3 prd_scaffolder.py analysis.json --output-dir ./prd --project-name "My App"
"""

import argparse
import json
import re
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, Optional
from pathlib import Path
from typing import Any, Dict, List


def slugify(text: str) -> str:
    """Convert text to a filename-safe slug."""
    text = text.strip().lower()
    text = re.sub(r"[/:{}*?\"<>|]", "-", text)
    text = re.sub(r"[^a-z0-9\-]", "-", text)
    text = re.sub(r"-+", "-", text)
    return text.strip("-")


def route_to_page_name(route: str) -> str:
    """Convert a route path to a human-readable page name."""
    if route == "/" or route == "":
        return "Home"
    parts = route.strip("/").split("/")
    # Remove dynamic segments for naming
    clean = [p for p in parts if not p.startswith(":") and not p.startswith("*")]
    if not clean:
        clean = [p.lstrip(":*") for p in parts]
    return " ".join(w.capitalize() for w in "-".join(clean).replace("_", "-").split("-"))


def generate_readme(project_name: str, routes: List[Dict], summary: Dict, date: str) -> str:
    """Generate the PRD README.md."""
    lines = [
        f"# {project_name} — Product Requirements Document",
        "",
        f"> Generated: {date}",
        "",
        "## System Overview",
        "",
        f"<!-- TODO: Describe what {project_name} does, its business context, and primary users -->",
        "",
        "## Summary",
        "",
        f"| Metric | Count |",
        f"|--------|-------|",
        f"| Pages | {summary.get('pages', 0)} |",
        f"| API Endpoints | {summary.get('api_endpoints', 0)} |",
        f"| Integrated APIs | {summary.get('api_integrated', 0)} |",
        f"| Mock APIs | {summary.get('api_mock', 0)} |",
        f"| Enums/Constants | {summary.get('enums', 0)} |",
        f"| i18n | {'Yes' if summary.get('has_i18n') else 'No'} |",
        f"| State Management | {'Yes' if summary.get('has_state_management') else 'No'} |",
        "",
        "## Module Overview",
        "",
        "| Module | Pages | Core Functionality |",
        "|--------|-------|--------------------|",
        "| <!-- TODO: Group pages into modules --> | | |",
        "",
        "## Page Inventory",
        "",
        "| # | Page Name | Route | Module | Doc Link |",
        "|---|-----------|-------|--------|----------|",
    ]

    for i, route in enumerate(routes, 1):
        path = route.get("path", "/")
        name = route_to_page_name(path)
        slug = slugify(name) or f"page-{i}"
        filename = f"{i:02d}-{slug}.md"
        lines.append(f"| {i} | {name} | `{path}` | <!-- TODO --> | [→](./pages/{filename}) |")

    lines.extend([
        "",
        "## Global Notes",
        "",
        "### Permission Model",
        "<!-- TODO: Summarize auth/role system if present -->",
        "",
        "### Common Interaction Patterns",
        "<!-- TODO: Global rules — delete confirmations, default sort, etc. -->",
        "",
    ])

    return "\n".join(lines)


def generate_page_stub(route: Dict, index: int, date: str) -> str:
    """Generate a per-page PRD stub."""
    path = route.get("path", "/")
    name = route_to_page_name(path)
    source = route.get("source", "unknown")

    return f"""# {name}

> **Route:** `{path}`
> **Module:** <!-- TODO -->
> **Source:** `{source}`
> **Generated:** {date}

## Overview
<!-- TODO: 2-3 sentences — core function and use case -->

## Layout
<!-- TODO: Region breakdown — search area, table, detail panel, action bar, etc. -->

## Fields

### Search / Filters
| Field | Type | Required | Options / Enum | Default | Notes |
|-------|------|----------|---------------|---------|-------|
| <!-- TODO --> | | | | | |

### Data Table
| Column | Format | Sortable | Filterable | Notes |
|--------|--------|----------|-----------|-------|
| <!-- TODO --> | | | | |

### Actions
| Button | Visibility Condition | Behavior |
|--------|---------------------|----------|
| <!-- TODO --> | | |

## Interactions

### Page Load
<!-- TODO: What happens on mount — default queries, preloaded data -->

### Search
- **Trigger:** <!-- TODO -->
- **Behavior:** <!-- TODO -->
- **Special rules:** <!-- TODO -->

### Create / Edit
- **Trigger:** <!-- TODO -->
- **Modal/drawer content:** <!-- TODO -->
- **Validation:** <!-- TODO -->
- **On success:** <!-- TODO -->

### Delete
- **Trigger:** <!-- TODO -->
- **Confirmation:** <!-- TODO -->
- **On success:** <!-- TODO -->

## API Dependencies

| API | Method | Path | Trigger | Integrated | Notes |
|-----|--------|------|---------|-----------|-------|
| <!-- TODO --> | | | | | |

## Page Relationships
- **From:** <!-- TODO: Source pages + params -->
- **To:** <!-- TODO: Target pages + params -->
- **Data coupling:** <!-- TODO: Cross-page refresh triggers -->

## Business Rules
<!-- TODO: Anything that doesn't fit above -->
"""


def generate_enum_dictionary(enums: List[Dict]) -> str:
    """Generate the enum dictionary appendix."""
    lines = [
        "# Enum & Constant Dictionary",
        "",
        "All enums, status codes, and type mappings extracted from the codebase.",
        "",
    ]

    if not enums:
        lines.append("*No enums detected. Manual review recommended.*")
        return "\n".join(lines)

    for e in enums:
        lines.append(f"## {e['name']}")
        lines.append(f"**Type:** {e.get('type', 'unknown')} | **Source:** `{e.get('source', 'unknown').split('/')[-1]}`")
        lines.append("")
        if e.get("values"):
            lines.append("| Key | Value |")
            lines.append("|-----|-------|")
            for k, v in e["values"].items():
                lines.append(f"| `{k}` | {v} |")
        lines.append("")

    return "\n".join(lines)


def generate_api_inventory(apis: List[Dict]) -> str:
    """Generate the API inventory appendix."""
    lines = [
        "# API Inventory",
        "",
        "All API endpoints detected in the codebase.",
        "",
    ]

    if not apis:
        lines.append("*No API calls detected. Manual review recommended.*")
        return "\n".join(lines)

    integrated = [a for a in apis if a.get("integrated")]
    mocked = [a for a in apis if a.get("mock_detected") and not a.get("integrated")]
    unknown = [a for a in apis if not a.get("integrated") and not a.get("mock_detected")]

    for label, group in [("Integrated APIs", integrated), ("Mock / Stub APIs", mocked), ("Unknown Status", unknown)]:
        if group:
            lines.append(f"## {label}")
            lines.append("")
            lines.append("| Method | Path | Source | Notes |")
            lines.append("|--------|------|--------|-------|")
            for a in group:
                src = a.get("source", "").split("/")[-1]
                lines.append(f"| {a.get('method', '?')} | `{a.get('path', '?')}` | {src} | |")
            lines.append("")

    return "\n".join(lines)


def generate_page_relationships(routes: List[Dict]) -> str:
    """Generate page relationships appendix stub."""
    lines = [
        "# Page Relationships",
        "",
        "Navigation flow and data coupling between pages.",
        "",
        "## Navigation Map",
        "",
        "<!-- TODO: Fill in after page-by-page analysis -->",
        "",
        "```",
        "Home",
    ]

    for r in routes[:20]:  # Cap at 20 for readability
        name = route_to_page_name(r.get("path", "/"))
        lines.append(f"  ├── {name}")

    if len(routes) > 20:
        lines.append(f"  └── ... ({len(routes) - 20} more)")

    lines.extend([
        "```",
        "",
        "## Cross-Page Data Dependencies",
        "",
        "| Source Page | Target Page | Trigger | Data Passed |",
        "|-----------|------------|---------|------------|",
        "| <!-- TODO --> | | | |",
        "",
    ])

    return "\n".join(lines)


def scaffold(analysis: Dict[str, Any], output_dir: Path, project_name: Optional[str] = None):
    """Create the full PRD directory structure."""
    date = datetime.now().strftime("%Y-%m-%d")
    name = project_name or analysis.get("project", {}).get("name", "Project")
    routes = analysis.get("routes", {}).get("pages", [])
    apis = analysis.get("apis", {}).get("endpoints", [])
    enums = analysis.get("enums", {}).get("definitions", [])
    summary = analysis.get("summary", {})

    # Create directories
    pages_dir = output_dir / "pages"
    appendix_dir = output_dir / "appendix"
    pages_dir.mkdir(parents=True, exist_ok=True)
    appendix_dir.mkdir(parents=True, exist_ok=True)

    # README.md
    readme = generate_readme(name, routes, summary, date)
    (output_dir / "README.md").write_text(readme)
    print(f"  Created: README.md")

    # Per-page stubs
    for i, route in enumerate(routes, 1):
        page_name = route_to_page_name(route.get("path", "/"))
        slug = slugify(page_name) or f"page-{i}"
        filename = f"{i:02d}-{slug}.md"
        content = generate_page_stub(route, i, date)
        (pages_dir / filename).write_text(content)
        print(f"  Created: pages/{filename}")

    # Appendix
    (appendix_dir / "enum-dictionary.md").write_text(generate_enum_dictionary(enums))
    print(f"  Created: appendix/enum-dictionary.md")

    (appendix_dir / "api-inventory.md").write_text(generate_api_inventory(apis))
    print(f"  Created: appendix/api-inventory.md")

    (appendix_dir / "page-relationships.md").write_text(generate_page_relationships(routes))
    print(f"  Created: appendix/page-relationships.md")

    print(f"\n✅ PRD scaffold complete: {output_dir}")
    print(f"   {len(routes)} page stubs, {len(apis)} API endpoints, {len(enums)} enums")
    print(f"\n   Next: Review each page stub and fill in the TODO sections.")


def validate_analysis(analysis: Dict[str, Any]) -> List[str]:
    """Validate analysis JSON has the required structure. Returns list of errors."""
    errors = []

    if not isinstance(analysis, dict):
        return ["Analysis must be a JSON object"]

    if "error" in analysis:
        errors.append(f"Analysis contains error: {analysis['error']}")

    required_keys = ["project", "routes", "apis"]
    for key in required_keys:
        if key not in analysis:
            errors.append(f"Missing required key: '{key}'")

    if "project" in analysis:
        proj = analysis["project"]
        if not isinstance(proj, dict):
            errors.append("'project' must be an object")
        elif "framework" not in proj:
            errors.append("'project.framework' is missing")

    if "routes" in analysis:
        routes = analysis["routes"]
        if not isinstance(routes, dict):
            errors.append("'routes' must be an object")
        elif "pages" not in routes and "frontend_pages" not in routes and "backend_endpoints" not in routes:
            errors.append("'routes' must contain 'pages', 'frontend_pages', or 'backend_endpoints'")

    if "apis" in analysis:
        apis = analysis["apis"]
        if not isinstance(apis, dict):
            errors.append("'apis' must be an object")
        elif "endpoints" not in apis:
            errors.append("'apis.endpoints' is missing")

    return errors


def print_summary(output_dir: Path, analysis: Dict[str, Any]):
    """Print a structured summary of what was generated."""
    routes = analysis.get("routes", {}).get("pages", [])
    apis = analysis.get("apis", {}).get("endpoints", [])
    enums = analysis.get("enums", {}).get("definitions", [])
    models = analysis.get("models", {}).get("definitions", [])
    summary = analysis.get("summary", {})
    stack = summary.get("stack_type", "unknown")

    print(f"\nPRD scaffold complete: {output_dir}/")
    print(f"  Stack type:     {stack}")
    print(f"  Page stubs:     {len(routes)}")
    print(f"  API endpoints:  {len(apis)}")
    print(f"  Enums:          {len(enums)}")
    if models:
        print(f"  Models:         {len(models)}")
    print(f"\n  Next: Review each page stub and fill in the TODO sections.")


def main():
    parser = argparse.ArgumentParser(
        description="Scaffold PRD directory from codebase analysis"
    )
    parser.add_argument("analysis", help="Path to analysis JSON from codebase_analyzer.py")
    parser.add_argument("-o", "--output-dir", default="prd", help="Output directory (default: prd/)")
    parser.add_argument("-n", "--project-name", help="Override project name")
    parser.add_argument("--validate-only", action="store_true",
                        help="Validate analysis JSON without generating files")
    parser.add_argument("--dry-run", action="store_true",
                        help="Show what would be created without writing files")
    args = parser.parse_args()

    analysis_path = Path(args.analysis)
    if not analysis_path.exists():
        print(f"Error: Analysis file not found: {analysis_path}")
        raise SystemExit(2)

    try:
        with open(analysis_path) as f:
            analysis = json.load(f)
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON in {analysis_path}: {e}")
        raise SystemExit(2)

    # Validate
    errors = validate_analysis(analysis)
    if errors:
        print(f"Validation errors in {analysis_path}:")
        for err in errors:
            print(f"  - {err}")
        raise SystemExit(1)

    if args.validate_only:
        print(f"Analysis file is valid: {analysis_path}")
        routes = analysis.get("routes", {}).get("pages", [])
        print(f"  {len(routes)} routes, "
              f"{len(analysis.get('apis', {}).get('endpoints', []))} APIs, "
              f"{len(analysis.get('enums', {}).get('definitions', []))} enums")
        return

    output_dir = Path(args.output_dir)

    if args.dry_run:
        routes = analysis.get("routes", {}).get("pages", [])
        print(f"Dry run — would create in {output_dir}/:\n")
        print(f"  {output_dir}/README.md")
        for i, route in enumerate(routes, 1):
            name = route_to_page_name(route.get("path", "/"))
            slug = slugify(name) or f"page-{i}"
            print(f"  {output_dir}/pages/{i:02d}-{slug}.md")
        print(f"  {output_dir}/appendix/enum-dictionary.md")
        print(f"  {output_dir}/appendix/api-inventory.md")
        print(f"  {output_dir}/appendix/page-relationships.md")
        print(f"\n  Total: {len(routes) + 4} files")
        return

    print(f"Scaffolding PRD in {output_dir}/...\n")
    scaffold(analysis, output_dir, args.project_name)
    print_summary(output_dir, analysis)


if __name__ == "__main__":
    main()