codegraph-nav 0.1.0__py3-none-any.whl

codegraph_nav/domain/__init__.py

@@ -0,0 +1,20 @@
+"""Domain intelligence — routes, schemas, and domain tags.
+
+Detects HTTP routes (15+ frameworks), ORM schemas (8+ ORMs), and infers
+domain tags from imports and symbol names.
+"""
+
+from .routes import detect_routes, format_routes_minimal, group_crud_routes
+from .schemas import detect_schemas, format_schemas_minimal
+from .tags import TAG_PATTERNS, infer_file_tags, infer_project_tags
+
+__all__ = [
+    "detect_routes",
+    "format_routes_minimal",
+    "group_crud_routes",
+    "detect_schemas",
+    "format_schemas_minimal",
+    "TAG_PATTERNS",
+    "infer_file_tags",
+    "infer_project_tags",
+]

codegraph_nav/domain/routes.py

@@ -0,0 +1,337 @@
+"""Framework route detection — 15+ frameworks via regex patterns.
+
+Detects HTTP routes from source code using cheap content detection
+followed by regex extraction. Supports Python, JS/TS, Go, Ruby, Java,
+Rust, and PHP frameworks.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections import defaultdict
+from typing import Any
+
+from .tags import infer_file_tags
+
+# ==============================================================================
+# Framework Detectors
+# ==============================================================================
+
+FRAMEWORK_DETECTORS: dict[str, dict[str, Any]] = {
+    # Python
+    "fastapi": {
+        "detect": ["from fastapi", "FastAPI", "APIRouter"],
+        "patterns": [
+            re.compile(r'@(?:app|router)\.(get|post|put|delete|patch)\(\s*["\']([^"\']+)["\']'),
+        ],
+    },
+    "flask": {
+        "detect": ["from flask", "Flask("],
+        "patterns": [
+            re.compile(
+                r'@(?:app|bp|blueprint)\.(route|get|post|put|delete)\(\s*["\']([^"\']+)["\']'
+            ),
+        ],
+    },
+    "django": {
+        "detect": ["from django", "urlpatterns"],
+        "patterns": [
+            re.compile(r"path\(\s*['\"]([^'\"]+)['\"].*?,\s*(\w+)"),
+        ],
+    },
+    # JavaScript/TypeScript
+    "express": {
+        "detect": [
+            "express()",
+            "require('express')",
+            'require("express")',
+            "from 'express'",
+            'from "express"',
+        ],
+        "patterns": [
+            re.compile(r'(?:app|router)\.(get|post|put|delete|patch|all)\(\s*["\']([^"\']+)["\']'),
+        ],
+    },
+    "nextjs": {
+        "detect": [],
+        "file_patterns": [
+            re.compile(r"app/.*/route\.[jt]sx?$"),
+            re.compile(r"pages/api/.*\.[jt]sx?$"),
+        ],
+    },
+    "nestjs": {
+        "detect": ["@nestjs", "@Controller"],
+        "patterns": [
+            re.compile(r"@(Get|Post|Put|Delete|Patch)\(\s*['\"]([^'\"]*)['\"]"),
+        ],
+    },
+    "hono": {
+        "detect": ["from 'hono'", 'from "hono"', "new Hono"],
+        "patterns": [
+            re.compile(r'(?:app|router)\.(get|post|put|delete|patch|all)\(\s*["\']([^"\']+)["\']'),
+        ],
+    },
+    # Go
+    "gin": {
+        "detect": ["gin.Default", "gin.New", '"github.com/gin-gonic'],
+        "patterns": [
+            re.compile(r'(?:r|router|group)\.(GET|POST|PUT|DELETE|PATCH)\(\s*["\']([^"\']+)["\']'),
+        ],
+    },
+    "echo": {
+        "detect": ["echo.New", '"github.com/labstack/echo'],
+        "patterns": [
+            re.compile(r'e\.(GET|POST|PUT|DELETE|PATCH)\(\s*["\']([^"\']+)["\']'),
+        ],
+    },
+    # Ruby
+    "rails": {
+        "detect": ["Rails.application", "ActionController"],
+        "patterns": [
+            re.compile(r"(get|post|put|patch|delete)\s+['\"]([^'\"]+)['\"]"),
+        ],
+    },
+    # Java
+    "spring": {
+        "detect": ["@RestController", "@RequestMapping", "springframework"],
+        "patterns": [
+            re.compile(
+                r'@(GetMapping|PostMapping|PutMapping|DeleteMapping|RequestMapping)\(\s*["\']([^"\']+)["\']'
+            ),
+        ],
+    },
+    # Rust
+    "actix": {
+        "detect": ["actix_web", "HttpServer"],
+        "patterns": [
+            re.compile(r'#\[(get|post|put|delete)\(\s*["\']([^"\']+)["\']'),
+        ],
+    },
+    "axum": {
+        "detect": ["axum::Router", "axum::routing"],
+        "patterns": [
+            re.compile(r"\.(get|post|put|delete)\((\w+)"),
+        ],
+    },
+    # PHP
+    "laravel": {
+        "detect": ["Route::get", "Route::post", "Illuminate"],
+        "patterns": [
+            re.compile(r"Route::(get|post|put|patch|delete)\(\s*['\"]([^'\"]+)['\"]"),
+        ],
+    },
+}
+
+
+# ==============================================================================
+# Route Detection
+# ==============================================================================
+
+
+def detect_routes(code_map: dict, root_path: str = "") -> list[dict]:
+    """Detect HTTP routes from code_map files.
+
+    Returns list of {method, path, file_path, handler_name, framework, tags, confidence}.
+    """
+    routes = []
+    files = code_map.get("files", {})
+
+    for file_path, file_info in files.items():
+        # Read file content
+        abs_path = os.path.join(root_path, file_path) if root_path else file_path
+        try:
+            with open(abs_path, encoding="utf-8", errors="replace") as f:
+                content = f.read()
+        except OSError:
+            continue
+
+        # Try each framework
+        for fw_name, fw_config in FRAMEWORK_DETECTORS.items():
+            # File-pattern-based detection (e.g., Next.js)
+            file_patterns = fw_config.get("file_patterns", [])
+            for fp in file_patterns:
+                if fp.search(file_path):
+                    # Infer method from export names or default to GET
+                    method = _infer_nextjs_method(content) if fw_name == "nextjs" else "GET"
+                    route_path = _file_to_route_path(file_path, fw_name)
+                    tags = infer_file_tags(
+                        file_path, file_info.get("imports", []), file_info.get("symbols", [])
+                    )
+                    routes.append(
+                        {
+                            "method": method,
+                            "path": route_path,
+                            "file_path": file_path,
+                            "handler_name": None,
+                            "framework": fw_name,
+                            "tags": tags,
+                            "confidence": "high",
+                        }
+                    )
+                    break
+
+            # Content-based detection
+            detect_strings = fw_config.get("detect", [])
+            if not detect_strings or not any(d in content for d in detect_strings):
+                continue
+
+            patterns = fw_config.get("patterns", [])
+            for pattern in patterns:
+                for match in pattern.finditer(content):
+                    groups = match.groups()
+                    if len(groups) >= 2:
+                        method = groups[0].upper()
+                        path = groups[1]
+                        # Try to find handler name
+                        handler = _find_handler_near_match(content, match, file_info)
+                        tags = infer_file_tags(
+                            file_path, file_info.get("imports", []), file_info.get("symbols", [])
+                        )
+                        routes.append(
+                            {
+                                "method": method,
+                                "path": path,
+                                "file_path": file_path,
+                                "handler_name": handler,
+                                "framework": fw_name,
+                                "tags": tags,
+                                "confidence": "high",
+                            }
+                        )
+                    elif len(groups) == 1 and fw_name == "django":
+                        # Django path() has different capture groups
+                        path = groups[0]
+                        routes.append(
+                            {
+                                "method": "*",
+                                "path": path,
+                                "file_path": file_path,
+                                "handler_name": None,
+                                "framework": fw_name,
+                                "tags": [],
+                                "confidence": "medium",
+                            }
+                        )
+
+    return routes
+
+
+def _infer_nextjs_method(content: str) -> str:
+    """Infer HTTP method from Next.js route handler exports."""
+    methods = []
+    for method in ("GET", "POST", "PUT", "DELETE", "PATCH"):
+        if re.search(rf"export\s+(?:async\s+)?function\s+{method}\b", content):
+            methods.append(method)
+    return ",".join(methods) if methods else "GET"
+
+
+def _file_to_route_path(file_path: str, framework: str) -> str:
+    """Convert file path to route path for file-based routing."""
+    path = file_path
+    # Next.js: app/api/users/[id]/route.ts → /api/users/:id
+    path = re.sub(r"^app/", "/", path)
+    path = re.sub(r"^pages/", "/", path)
+    path = re.sub(r"/route\.[jt]sx?$", "", path)
+    path = re.sub(r"/index\.[jt]sx?$", "", path)
+    path = re.sub(r"\.[jt]sx?$", "", path)
+    path = re.sub(r"\[([^\]]+)\]", r":\1", path)  # [id] → :id
+    return path or "/"
+
+
+def _find_handler_near_match(content: str, match: re.Match, file_info: dict) -> str | None:
+    """Try to find the handler function name near a route match."""
+    # Look for the function defined right after/around the match
+    pos = match.end()
+    # Check for def/function within 200 chars after match
+    snippet = content[pos : pos + 200]
+    fn_match = re.search(r"(?:def|function|async function)\s+(\w+)", snippet)
+    if fn_match:
+        return fn_match.group(1)
+
+    # Check for preceding function (decorator pattern)
+    pre_snippet = content[max(0, match.start() - 100) : match.start()]
+    fn_match = re.search(r"(?:def|function|async function)\s+(\w+)", pre_snippet)
+    if fn_match:
+        return fn_match.group(1)
+
+    # Check symbols at matching line
+    line_num = content[: match.start()].count("\n") + 1
+    for sym in file_info.get("symbols", []):
+        lines = sym.get("lines", [0, 0])
+        if lines and abs(lines[0] - line_num) <= 3:
+            return str(sym["name"])
+
+    return None
+
+
+# ==============================================================================
+# CRUD Grouping
+# ==============================================================================
+
+
+def group_crud_routes(routes: list[dict]) -> list[dict]:
+    """Group routes by base path, collapsing CRUD endpoints.
+
+    /users GET, POST + /users/:id GET, PUT, DELETE → /users CRUD[5]
+    """
+    by_base: dict[str, list[dict]] = defaultdict(list)
+
+    for route in routes:
+        # Strip dynamic segments for grouping
+        base = re.sub(r"/:[^/]+", "", route["path"])
+        base = re.sub(r"/\{[^}]+\}", "", base)
+        base = base.rstrip("/") or "/"
+        by_base[base].append(route)
+
+    grouped = []
+    for base, group in by_base.items():
+        methods = sorted({r["method"] for r in group})
+        crud_methods = {"GET", "POST", "PUT", "DELETE", "PATCH"}
+        is_crud = len(set(methods) & crud_methods) >= 3
+
+        if is_crud and len(group) >= 3:
+            tags = sorted({t for r in group for t in r.get("tags", [])})
+            grouped.append(
+                {
+                    "method": "CRUD",
+                    "path": base,
+                    "file_path": group[0]["file_path"],
+                    "handler_name": None,
+                    "framework": group[0]["framework"],
+                    "tags": tags,
+                    "confidence": "high",
+                    "count": len(group),
+                    "methods": methods,
+                }
+            )
+        else:
+            grouped.extend(group)
+
+    return grouped
+
+
+# ==============================================================================
+# Formatters
+# ==============================================================================
+
+
+def format_routes_minimal(routes: list[dict], group_crud: bool = True, limit: int = 20) -> str:
+    """Format routes as compact string."""
+    if not routes:
+        return "No routes detected."
+
+    display = group_crud_routes(routes) if group_crud else routes
+
+    lines = [f"{len(routes)} routes detected:"]
+    for r in display[:limit]:
+        tags_str = f" [{','.join(r['tags'])}]" if r.get("tags") else ""
+        handler = f" → {r['handler_name']}" if r.get("handler_name") else ""
+        if r["method"] == "CRUD":
+            lines.append(f"  {r['path']} CRUD[{r.get('count', '?')}]{tags_str} ({r['framework']})")
+        else:
+            lines.append(f"  {r['method']} {r['path']}{handler}{tags_str} ({r['framework']})")
+    if len(display) > limit:
+        lines.append(f"  ... +{len(display) - limit} more")
+
+    return "\n".join(lines)

codegraph_nav/domain/schemas.py

@@ -0,0 +1,229 @@
+"""ORM schema detection — 8+ ORMs via regex patterns.
+
+Detects model definitions from source code by matching ORM-specific patterns
+in class signatures, decorators, and field definitions.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+# ==============================================================================
+# ORM Detectors
+# ==============================================================================
+
+ORM_DETECTORS: dict[str, dict[str, Any]] = {
+    "sqlalchemy": {
+        "detect": ["from sqlalchemy", "Column(", "relationship(", "mapped_column("],
+        "class_pattern": re.compile(r"class\s+(\w+)\(.*?(?:Base|Model|db\.Model|DeclarativeBase)"),
+        "field_pattern": re.compile(r"(\w+)\s*[:=]\s*(?:Column|db\.Column|mapped_column)\((\w+)"),
+    },
+    "django": {
+        "detect": ["from django.db", "models.Model"],
+        "class_pattern": re.compile(r"class\s+(\w+)\((?:models\.Model|.*Model)\)"),
+        "field_pattern": re.compile(r"(\w+)\s*=\s*models\.(\w+Field)"),
+    },
+    "prisma": {
+        "detect": [],
+        "file_patterns": ["schema.prisma", "prisma/schema.prisma"],
+        "model_pattern": re.compile(r"model\s+(\w+)\s*\{([^}]+)\}"),
+        "field_pattern": re.compile(r"(\w+)\s+(\w+)"),
+    },
+    "sequelize": {
+        "detect": ["sequelize", "DataTypes", "Model.init", "define("],
+        "class_pattern": re.compile(r"class\s+(\w+)\s+extends\s+Model"),
+        "field_pattern": re.compile(r"(\w+):\s*\{[^}]*type:\s*DataTypes\.(\w+)"),
+    },
+    "typeorm": {
+        "detect": ["@Entity", "typeorm", "@Column"],
+        "class_pattern": re.compile(r"@Entity\(\)?\s*(?:export\s+)?class\s+(\w+)"),
+        "field_pattern": re.compile(r"@Column\([^)]*\)\s*(\w+)\s*[!?]?:\s*(\w+)"),
+    },
+    "gorm": {
+        "detect": ["gorm.Model", "gorm.io"],
+        "class_pattern": re.compile(r"type\s+(\w+)\s+struct\s*\{"),
+        "field_pattern": re.compile(r"(\w+)\s+(\w+)\s+`gorm:"),
+    },
+    "drizzle": {
+        "detect": ["drizzle-orm", "pgTable", "mysqlTable", "sqliteTable"],
+        "class_pattern": re.compile(
+            r"(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(?:pg|mysql|sqlite)Table"
+        ),
+        "field_pattern": re.compile(r"(\w+):\s*(\w+)\("),
+    },
+    "mongoose": {
+        "detect": ["mongoose", "Schema(", "model("],
+        "class_pattern": re.compile(
+            r"(?:const|let|var)\s+(\w+)Schema\s*=\s*new\s+(?:mongoose\.)?Schema"
+        ),
+        "field_pattern": re.compile(r"(\w+):\s*\{[^}]*type:\s*(\w+)"),
+    },
+}
+
+
+# ==============================================================================
+# Schema Detection
+# ==============================================================================
+
+
+def detect_schemas(code_map: dict, root_path: str = "") -> list[dict]:
+    """Detect ORM models/schemas from code_map files.
+
+    Returns list of {name, file_path, orm, fields: [{name, type}], relations: []}.
+    """
+    schemas = []
+    files = code_map.get("files", {})
+
+    for file_path, file_info in files.items():
+        abs_path = os.path.join(root_path, file_path) if root_path else file_path
+
+        # Special case: Prisma schema files
+        for orm_name, orm_config in ORM_DETECTORS.items():
+            for fp in orm_config.get("file_patterns", []):
+                if file_path.endswith(fp) or fp in file_path:
+                    try:
+                        with open(abs_path, encoding="utf-8", errors="replace") as f:
+                            content = f.read()
+                        schemas.extend(_extract_prisma_schemas(content, file_path))
+                    except OSError:
+                        pass
+
+        # Content-based detection
+        try:
+            with open(abs_path, encoding="utf-8", errors="replace") as f:
+                content = f.read()
+        except OSError:
+            continue
+
+        for orm_name, orm_config in ORM_DETECTORS.items():
+            detect_strings = orm_config.get("detect", [])
+            if not detect_strings or not any(d in content for d in detect_strings):
+                continue
+
+            class_pattern = orm_config.get("class_pattern")
+            field_pattern = orm_config.get("field_pattern")
+
+            if not class_pattern:
+                continue
+
+            for class_match in class_pattern.finditer(content):
+                model_name = class_match.group(1)
+
+                # Extract fields within class body
+                fields = []
+                if field_pattern:
+                    # Search within ~2000 chars after class declaration
+                    body_start = class_match.end()
+                    body = content[body_start : body_start + 2000]
+                    for field_match in field_pattern.finditer(body):
+                        fields.append(
+                            {
+                                "name": field_match.group(1),
+                                "type": field_match.group(2),
+                            }
+                        )
+
+                schemas.append(
+                    {
+                        "name": model_name,
+                        "file_path": file_path,
+                        "orm": orm_name,
+                        "fields": fields,
+                        "relations": [],
+                    }
+                )
+
+    # Also detect from symbols (class signatures)
+    schemas.extend(_detect_from_symbols(files))
+
+    # Deduplicate by (name, file_path)
+    seen = set()
+    unique = []
+    for s in schemas:
+        key = (s["name"], s["file_path"])
+        if key not in seen:
+            seen.add(key)
+            unique.append(s)
+
+    return unique
+
+
+def _extract_prisma_schemas(content: str, file_path: str) -> list[dict]:
+    """Extract models from Prisma schema file."""
+    schemas = []
+    model_pattern = re.compile(r"model\s+(\w+)\s*\{([^}]+)\}")
+    field_pattern = re.compile(r"^\s*(\w+)\s+(\w+)", re.MULTILINE)
+
+    for model_match in model_pattern.finditer(content):
+        name = model_match.group(1)
+        body = model_match.group(2)
+        fields = []
+        for field_match in field_pattern.finditer(body):
+            fname = field_match.group(1)
+            ftype = field_match.group(2)
+            if fname not in ("@@", "//"):
+                fields.append({"name": fname, "type": ftype})
+        schemas.append(
+            {
+                "name": name,
+                "file_path": file_path,
+                "orm": "prisma",
+                "fields": fields,
+                "relations": [],
+            }
+        )
+    return schemas
+
+
+def _detect_from_symbols(files: dict) -> list[dict]:
+    """Detect ORM models from symbol signatures in code_map."""
+    schemas = []
+    orm_base_patterns = [
+        (re.compile(r"class\s+\w+\(.*(?:Base|Model|db\.Model)"), "sqlalchemy"),
+        (re.compile(r"class\s+\w+\(models\.Model\)"), "django"),
+    ]
+
+    for file_path, file_info in files.items():
+        for sym in file_info.get("symbols", []):
+            if sym.get("type") != "class":
+                continue
+            sig = sym.get("signature", "")
+            if not sig:
+                continue
+            for pattern, orm in orm_base_patterns:
+                if pattern.search(sig):
+                    schemas.append(
+                        {
+                            "name": sym["name"],
+                            "file_path": file_path,
+                            "orm": orm,
+                            "fields": [],
+                            "relations": [],
+                        }
+                    )
+                    break
+    return schemas
+
+
+# ==============================================================================
+# Formatters
+# ==============================================================================
+
+
+def format_schemas_minimal(schemas: list[dict], limit: int = 20) -> str:
+    """Format schemas as compact string."""
+    if not schemas:
+        return "No schemas detected."
+
+    lines = [f"{len(schemas)} schemas detected:"]
+    for s in schemas[:limit]:
+        field_count = len(s.get("fields", []))
+        orm_str = f" [{s['orm']}]" if s.get("orm") else ""
+        lines.append(f"  {s['name']}{orm_str} {field_count} fields ({Path(s['file_path']).name})")
+    if len(schemas) > limit:
+        lines.append(f"  ... +{len(schemas) - limit} more")
+
+    return "\n".join(lines)

codegraph_nav/domain/tags.py

@@ -0,0 +1,87 @@
+"""Domain tag inference from imports, symbol names, and file paths.
+
+Tags represent high-level domain concerns: auth, db, cache, api, etc.
+Used to enrich search results, flow descriptions, and route metadata.
+"""
+
+from __future__ import annotations
+
+TAG_PATTERNS: dict[str, list[str]] = {
+    "auth": [
+        "auth",
+        "jwt",
+        "token",
+        "session",
+        "login",
+        "password",
+        "oauth",
+        "credential",
+        "permission",
+    ],
+    "db": [
+        "sql",
+        "query",
+        "model",
+        "orm",
+        "database",
+        "migrate",
+        "schema",
+        "prisma",
+        "drizzle",
+        "sequelize",
+    ],
+    "cache": ["redis", "cache", "memcache", "ttl", "lru"],
+    "queue": ["bull", "celery", "rabbitmq", "kafka", "sqs", "queue", "worker", "job"],
+    "email": ["email", "smtp", "sendgrid", "resend", "mailgun", "ses"],
+    "payment": ["stripe", "payment", "billing", "invoice", "checkout", "charge"],
+    "upload": ["upload", "multer", "s3", "storage", "bucket", "blob"],
+    "ai": ["openai", "anthropic", "claude", "llm", "embedding", "gpt", "gemini"],
+    "api": ["api", "endpoint", "route", "rest", "graphql", "grpc", "websocket"],
+    "test": ["test", "spec", "mock", "fixture", "assert", "pytest"],
+}
+
+
+def infer_file_tags(
+    file_path: str,
+    imports: list[str],
+    symbols: list[dict],
+) -> list[str]:
+    """Infer domain tags for a file from its imports, symbol names, and path.
+
+    Returns sorted list of unique tags.
+    """
+    tags: set[str] = set()
+
+    # Combine all text signals
+    signals = []
+    signals.append(file_path.lower())
+    signals.extend(imp.lower() for imp in imports)
+    signals.extend(sym.get("name", "").lower() for sym in symbols)
+    signals.extend(sym.get("signature", "").lower() for sym in symbols if sym.get("signature"))
+
+    combined = " ".join(signals)
+
+    for tag, keywords in TAG_PATTERNS.items():
+        for keyword in keywords:
+            if keyword in combined:
+                tags.add(tag)
+                break
+
+    return sorted(tags)
+
+
+def infer_project_tags(code_map: dict) -> dict[str, list[str]]:
+    """Infer domain tags for all files in a code_map.
+
+    Returns {file_path: [tags]}.
+    """
+    result = {}
+    for file_path, file_info in code_map.get("files", {}).items():
+        tags = infer_file_tags(
+            file_path,
+            file_info.get("imports", []),
+            file_info.get("symbols", []),
+        )
+        if tags:
+            result[file_path] = tags
+    return result