commiter-cli 0.3.0__py3-none-any.whl

commiter/prefix_index.py

@@ -0,0 +1,211 @@
+"""Cross-file router/blueprint prefix index.
+
+Detects prefix declarations across files and resolves them to prepend
+to route patterns found on routers/blueprints.
+
+Patterns detected:
+  Flask:   Blueprint("name", __name__, url_prefix="/api/users")
+           app.register_blueprint(bp, url_prefix="/api/users")
+  FastAPI: app.include_router(users_router, prefix="/api/users")
+  Express: app.use("/api/users", usersRouter)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from commiter.parser import node_text, find_nodes_by_type
+
+if TYPE_CHECKING:
+    from tree_sitter import Tree, Node
+
+
+@dataclass
+class PrefixBinding:
+    """A binding between a router/blueprint variable name and its URL prefix."""
+    variable_name: str
+    prefix: str
+    file_path: str
+    line: int
+
+
+class PrefixIndex:
+    """Index of router/blueprint prefix bindings across all files.
+
+    Usage:
+        idx = PrefixIndex()
+        # Pass 1: index all files
+        for path in files:
+            idx.index_file(path, tree, source, language)
+        # Pass 2: look up prefix for a route
+        prefix = idx.get_prefix_for_file(file_path, router_var_name)
+    """
+
+    def __init__(self) -> None:
+        # variable_name -> list of PrefixBinding
+        self._bindings: dict[str, list[PrefixBinding]] = {}
+        # file_path -> list of PrefixBinding (all bindings found in a file)
+        self._by_file: dict[str, list[PrefixBinding]] = {}
+        # For cross-file: imported router name -> (source_file, original_name)
+        self._router_imports: dict[str, dict[str, str]] = {}  # file -> {local_name: source_file}
+
+    def index_file(self, file_path: str, tree: "Tree", source: bytes, language: str) -> None:
+        """Scan a file for prefix declarations."""
+        abs_path = os.path.abspath(file_path)
+        text = source.decode("utf-8", errors="replace")
+
+        if language == "python":
+            self._index_python_prefixes(abs_path, tree, source, text)
+        elif language in ("javascript", "typescript", "tsx"):
+            self._index_js_prefixes(abs_path, tree, source, text)
+
+    def get_prefix_for_file(self, file_path: str, router_var: str | None = None) -> str:
+        """Get the accumulated URL prefix for routes in a file.
+
+        Checks if any other file mounts a router from this file with a prefix.
+
+        Args:
+            file_path: The file containing the routes.
+            router_var: Optional variable name of the router (e.g. "bp", "router").
+
+        Returns:
+            The prefix string (e.g. "/api/v1") or empty string if none found.
+        """
+        abs_path = os.path.abspath(file_path)
+        file_name = Path(abs_path).stem
+
+        # Strategy 1: Check if a specific router variable has a known prefix
+        if router_var and router_var in self._bindings:
+            for binding in self._bindings[router_var]:
+                return binding.prefix
+
+        # Strategy 2: Check if any binding references this file (cross-file)
+        # Look through all bindings for ones that import from this file
+        for importing_file, imports in self._router_imports.items():
+            for local_name, source_file in imports.items():
+                # Check if source_file matches our file
+                if self._files_match(source_file, abs_path, importing_file):
+                    if local_name in self._bindings:
+                        for binding in self._bindings[local_name]:
+                            if binding.file_path == importing_file:
+                                return binding.prefix
+
+        # Strategy 3: Check same-file Blueprint/Router definitions with inline prefix
+        for binding in self._by_file.get(abs_path, []):
+            return binding.prefix
+
+        return ""
+
+    def _index_python_prefixes(self, abs_path: str, tree: "Tree", source: bytes, text: str) -> None:
+        """Index Flask Blueprint and FastAPI include_router prefixes."""
+
+        # Pattern 1: Blueprint("name", __name__, url_prefix="/api/users")
+        for match in re.finditer(
+            r'(\w+)\s*=\s*Blueprint\s*\([^)]*url_prefix\s*=\s*["\']([^"\']+)["\']',
+            text,
+        ):
+            var_name = match.group(1)
+            prefix = match.group(2)
+            line = text[:match.start()].count("\n") + 1
+            binding = PrefixBinding(variable_name=var_name, prefix=prefix, file_path=abs_path, line=line)
+            self._bindings.setdefault(var_name, []).append(binding)
+            self._by_file.setdefault(abs_path, []).append(binding)
+
+        # Pattern 2: app.register_blueprint(bp, url_prefix="/api/users")
+        for match in re.finditer(
+            r'\.register_blueprint\s*\(\s*(\w+)(?:\s*,\s*url_prefix\s*=\s*["\']([^"\']+)["\'])?',
+            text,
+        ):
+            var_name = match.group(1)
+            prefix = match.group(2)
+            if prefix:
+                line = text[:match.start()].count("\n") + 1
+                binding = PrefixBinding(variable_name=var_name, prefix=prefix, file_path=abs_path, line=line)
+                self._bindings.setdefault(var_name, []).append(binding)
+                self._by_file.setdefault(abs_path, []).append(binding)
+
+        # Pattern 3: app.include_router(users_router, prefix="/api/users")
+        for match in re.finditer(
+            r'\.include_router\s*\(\s*(\w+)(?:\s*,\s*prefix\s*=\s*["\']([^"\']+)["\'])?',
+            text,
+        ):
+            var_name = match.group(1)
+            prefix = match.group(2)
+            if prefix:
+                line = text[:match.start()].count("\n") + 1
+                binding = PrefixBinding(variable_name=var_name, prefix=prefix, file_path=abs_path, line=line)
+                self._bindings.setdefault(var_name, []).append(binding)
+                self._by_file.setdefault(abs_path, []).append(binding)
+
+        # Track imports: from .routes import router, from routes.users import users_router
+        for match in re.finditer(r'from\s+(\S+)\s+import\s+(.+)', text):
+            module_path = match.group(1)
+            names = [n.strip().split(" as ")[-1].strip() for n in match.group(2).split(",")]
+            for name in names:
+                if name:
+                    self._router_imports.setdefault(abs_path, {})[name] = module_path
+
+    def _index_js_prefixes(self, abs_path: str, tree: "Tree", source: bytes, text: str) -> None:
+        """Index Express app.use("/prefix", router) patterns."""
+
+        # Pattern: app.use("/api/users", usersRouter)
+        for match in re.finditer(
+            r'(\w+)\.use\s*\(\s*["\']([^"\']+)["\']\s*,\s*(\w+)\s*\)',
+            text,
+        ):
+            mount_obj = match.group(1)  # app, server, etc.
+            prefix = match.group(2)
+            router_var = match.group(3)
+            line = text[:match.start()].count("\n") + 1
+            binding = PrefixBinding(variable_name=router_var, prefix=prefix, file_path=abs_path, line=line)
+            self._bindings.setdefault(router_var, []).append(binding)
+            self._by_file.setdefault(abs_path, []).append(binding)
+
+        # Track imports: import usersRouter from "./routes/users"
+        # const usersRouter = require("./routes/users")
+        for match in re.finditer(r'import\s+(\w+)\s+from\s+["\']([^"\']+)["\']', text):
+            name = match.group(1)
+            source_path = match.group(2)
+            self._router_imports.setdefault(abs_path, {})[name] = source_path
+
+        for match in re.finditer(r'(?:const|let|var)\s+(\w+)\s*=\s*require\s*\(\s*["\']([^"\']+)["\']\s*\)', text):
+            name = match.group(1)
+            source_path = match.group(2)
+            self._router_imports.setdefault(abs_path, {})[name] = source_path
+
+    def _files_match(self, import_path: str, target_abs_path: str, importer_abs_path: str) -> bool:
+        """Check if an import path could resolve to the target file."""
+        target_stem = Path(target_abs_path).stem
+        target_name = Path(target_abs_path).name
+
+        # Direct name match
+        if import_path.endswith(target_stem) or import_path.endswith(target_name):
+            return True
+
+        # Relative path resolution
+        if import_path.startswith("."):
+            importer_dir = str(Path(importer_abs_path).parent)
+            resolved = os.path.normpath(os.path.join(importer_dir, import_path))
+            # Try with common extensions
+            for ext in ("", ".py", ".js", ".ts", ".tsx", "/index.ts", "/index.js"):
+                if os.path.normpath(resolved + ext) == os.path.normpath(target_abs_path):
+                    return True
+                # Also compare stems
+                if Path(resolved + ext).stem == target_stem:
+                    return True
+
+        # Python dotted imports: .routes -> routes.py in same dir
+        if import_path.startswith("."):
+            module = import_path.lstrip(".").replace(".", "/")
+            if module == target_stem or module.endswith("/" + target_stem):
+                return True
+
+        return False
+
+    @property
+    def binding_count(self) -> int:
+        return sum(len(b) for b in self._bindings.values())

commiter/report/ai.py

@@ -0,0 +1,120 @@
+"""Compact plain-text output optimized for LLM context windows.
+
+Minimal tokens, no decorative formatting, all essential data with file:line references.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from commiter.models import RepoDocumentation
+
+
+def generate_ai(docs: list[RepoDocumentation],
+                sections: dict[str, str | None] | None = None) -> str:
+    """Generate compact AI-friendly plain text output."""
+    lines: list[str] = []
+
+    for doc in docs:
+        lines.extend(_repo_section(doc, sections))
+
+    return "\n".join(lines)
+
+
+def _show(sections: dict | None, key: str) -> bool:
+    if sections is None:
+        return True
+    return sections.get(key) is not None
+
+
+def _rel(file_path: str, repo_name: str) -> str:
+    """Make file path relative to repo."""
+    if repo_name + "/" in file_path:
+        return file_path.split(repo_name + "/", 1)[-1]
+    return Path(file_path).name
+
+
+def _repo_section(doc: RepoDocumentation,
+                  sections: dict[str, str | None] | None = None) -> list[str]:
+    lines: list[str] = []
+
+    # Header
+    lines.append(f"REPO: {doc.repo_name}")
+    if doc.frameworks:
+        lines.append(f"FRAMEWORKS: {', '.join(doc.frameworks)}")
+    if doc.languages:
+        lines.append(f"LANGUAGES: {', '.join(doc.languages)}")
+    lines.append("")
+
+    # Endpoints
+    if doc.endpoints and _show(sections, "endpoints"):
+        lines.append("ENDPOINTS:")
+        for ep in doc.endpoints:
+            rel = _rel(ep.file_path, doc.repo_name)
+            lines.append(f"  {ep.http_method} {ep.route_pattern} → {ep.handler_name} [{rel}:{ep.line}]")
+
+            if ep.parameters:
+                params = ", ".join(f"{p.name} ({p.source.value})" for p in ep.parameters)
+                lines.append(f"    params: {params}")
+
+            if ep.request_body_type and ep.request_body_fields:
+                fields = ", ".join(ep.request_body_fields)
+                lines.append(f"    body: {ep.request_body_type} {{{fields}}}")
+            elif ep.request_body_type:
+                lines.append(f"    body: {ep.request_body_type}")
+            elif ep.request_body_fields:
+                fields = ", ".join(ep.request_body_fields)
+                lines.append(f"    body: {{{fields}}}")
+
+            if ep.response_fields:
+                lines.append(f"    response: {{{', '.join(ep.response_fields)}}}")
+
+            if ep.auth_decorators:
+                lines.append(f"    auth: {', '.join(ep.auth_decorators)}")
+
+            if ep.middleware:
+                lines.append(f"    middleware: {', '.join(ep.middleware)}")
+
+            if ep.db_tables:
+                lines.append(f"    db: {', '.join(ep.db_tables)}")
+
+        lines.append("")
+
+    # Frontend API Calls
+    if doc.api_calls and _show(sections, "calls"):
+        lines.append("API CALLS:")
+        for call in doc.api_calls:
+            rel = _rel(call.file_path, doc.repo_name)
+            traced = f" via {call.traced_from}" if call.traced_from else ""
+            lines.append(f"  {call.http_method} {call.url_pattern} ← {call.component_or_page} [{rel}:{call.line}]{traced}")
+        lines.append("")
+
+    # DB Operations
+    if doc.db_operations and _show(sections, "db"):
+        lines.append("DB OPERATIONS:")
+        for op in doc.db_operations:
+            rel = _rel(op.file_path, doc.repo_name)
+            filters = f" WHERE {', '.join(op.filters)}" if op.filters else ""
+            lines.append(f"  {op.operation_type.upper()} {op.table_name}{filters} ({op.orm_library}) [{rel}:{op.line}]")
+        lines.append("")
+
+    # Dependencies
+    if doc.dependencies and _show(sections, "deps"):
+        runtime = [d for d in doc.dependencies if not d.dev_only]
+        dev = [d for d in doc.dependencies if d.dev_only]
+        if runtime:
+            deps_str = ", ".join(f"{d.name} {d.version_constraint}" for d in sorted(runtime, key=lambda x: x.name))
+            lines.append(f"DEPS: {deps_str}")
+        if dev:
+            dev_str = ", ".join(f"{d.name} {d.version_constraint}" for d in sorted(dev, key=lambda x: x.name))
+            lines.append(f"DEV DEPS: {dev_str}")
+        lines.append("")
+
+    # Cross-repo relationships
+    shared_db = [r for r in doc.service_relationships if r.connection_type == "shared_db"]
+    if shared_db:
+        tables = set(r.target_endpoint.replace("table:", "") for r in shared_db)
+        lines.append(f"SHARED DB TABLES: {', '.join(sorted(tables))}")
+        lines.append("")
+
+    return lines

commiter/report/api_guide.py

@@ -0,0 +1,217 @@
+"""Generate curl command guides for API endpoints.
+
+Produces ready-to-paste curl commands with all known data pre-filled:
+method, route, body template, auth headers, path params, query params.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from commiter.models import RepoDocumentation, APIEndpoint, ParamSource
+
+
+# Common auth-related middleware/decorator names
+_AUTH_INDICATORS = {
+    "auth", "authenticate", "authMiddleware", "requireAuth", "isAuthenticated",
+    "verifyToken", "requireLogin", "protect", "jwt_required", "login_required",
+    "require_auth", "token_required", "Depends(get_current_user",
+}
+
+# Env var names that might contain the API base URL
+_BASE_URL_ENV_KEYS = [
+    "API_URL", "BASE_URL", "SERVER_URL",
+    "NEXT_PUBLIC_API_URL", "VITE_API_URL", "REACT_APP_API_URL",
+    "NUXT_PUBLIC_API_BASE",
+]
+
+# Env var names for port
+_PORT_ENV_KEYS = ["PORT", "SERVER_PORT", "APP_PORT"]
+
+
+def generate_api_guide(
+    docs: list[RepoDocumentation],
+    env_vars: dict[str, str] | None = None,
+) -> str:
+    """Generate curl command guides for all endpoints across repos."""
+    lines: list[str] = []
+    base_url = _detect_base_url(env_vars or {})
+
+    for doc in docs:
+        if not doc.endpoints:
+            continue
+
+        lines.append(f"API Guide: {doc.repo_name}")
+        lines.append(f"Base URL: {base_url}")
+        lines.append("")
+
+        for ep in doc.endpoints:
+            lines.extend(_endpoint_guide(ep, doc.repo_name, base_url))
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def _detect_base_url(env_vars: dict[str, str]) -> str:
+    """Detect the API base URL from environment variables."""
+    # Check explicit URL vars
+    for key in _BASE_URL_ENV_KEYS:
+        if key in env_vars:
+            return env_vars[key].rstrip("/")
+
+    # Check for PORT
+    for key in _PORT_ENV_KEYS:
+        if key in env_vars:
+            return f"http://localhost:{env_vars[key]}"
+
+    return "http://localhost:3000"
+
+
+def _endpoint_guide(ep: APIEndpoint, repo_name: str, base_url: str) -> list[str]:
+    """Generate a guide + curl command for a single endpoint."""
+    lines: list[str] = []
+    rel = _rel_path(ep.file_path, repo_name)
+
+    # Header
+    lines.append(f"{ep.http_method} {ep.route_pattern} → {ep.handler_name} [{rel}:{ep.line}]")
+
+    # Auth info
+    has_auth = _detect_auth(ep)
+    if has_auth:
+        lines.append(f"  Auth: {', '.join(has_auth)}")
+
+    # Path parameters
+    path_params = [p for p in ep.parameters if p.source == ParamSource.PATH]
+    if path_params:
+        params_str = ", ".join(f"{p.name}: {p.type_hint or 'string'}" for p in path_params)
+        lines.append(f"  Path params: {params_str}")
+
+    # Body fields
+    if ep.request_body_fields:
+        body_type = ep.request_body_type or "object"
+        lines.append(f"  Body: {body_type}")
+        for field_str in ep.request_body_fields:
+            # Parse "name: type" or "name: type?" format
+            optional = "?" in field_str
+            clean = field_str.rstrip("?").strip()
+            req_label = "(optional)" if optional else "(required)"
+            lines.append(f"    - {clean} {req_label}")
+
+    # Curl command
+    lines.append("")
+    lines.extend(_build_curl(ep, base_url, has_auth))
+
+    return lines
+
+
+def _build_curl(ep: APIEndpoint, base_url: str, auth: list[str]) -> list[str]:
+    """Build the curl command for an endpoint."""
+    # Build URL with path param placeholders
+    url = _build_url(ep, base_url)
+
+    parts: list[str] = [f"  curl -X {ep.http_method} '{url}'"]
+
+    # Content-Type header for methods with body
+    if ep.http_method in ("POST", "PUT", "PATCH"):
+        parts.append('    -H "Content-Type: application/json"')
+
+    # Auth header if needed
+    if auth:
+        parts.append('    -H "Authorization: Bearer <YOUR_TOKEN>"')
+
+    # Request body
+    if ep.request_body_fields and ep.http_method in ("POST", "PUT", "PATCH"):
+        body = _build_body_template(ep)
+        body_json = json.dumps(body, indent=6)
+        # Indent the JSON to align with the -d flag
+        body_lines = body_json.split("\n")
+        parts.append(f"    -d '{body_lines[0]}")
+        for bl in body_lines[1:]:
+            parts[-1] += f"\n    {bl}"
+        parts[-1] += "'"
+
+    # Join with line continuation
+    return [" \\\n".join(parts)]
+
+
+def _build_url(ep: APIEndpoint, base_url: str) -> str:
+    """Build the full URL with path param placeholders."""
+    route = ep.route_pattern
+
+    # Replace framework-specific param syntax with readable placeholders
+    # Express :id → <id>
+    import re
+    route = re.sub(r":(\w+)", r"<\1>", route)
+    # Flask <param> already in the right format
+    # FastAPI {param} → <param>
+    route = re.sub(r"\{(\w+)\}", r"<\1>", route)
+
+    # Add query params if any
+    query_params = [p for p in ep.parameters if p.source == ParamSource.QUERY]
+    if query_params:
+        query_str = "&".join(f"{p.name}=<{p.type_hint or 'value'}>" for p in query_params)
+        route += f"?{query_str}"
+
+    return f"{base_url}{route}"
+
+
+def _build_body_template(ep: APIEndpoint) -> dict:
+    """Build a JSON body template from request body fields."""
+    body = {}
+    for field_str in ep.request_body_fields:
+        # Parse "name: type" format
+        if ":" in field_str:
+            name, type_info = field_str.split(":", 1)
+            name = name.strip()
+            type_info = type_info.strip().rstrip("?").strip()
+            body[name] = _type_placeholder(type_info)
+        else:
+            body[field_str.strip()] = "<value>"
+    return body
+
+
+def _type_placeholder(type_str: str) -> str | int | bool | list:
+    """Generate a placeholder value based on the type string."""
+    t = type_str.lower().strip()
+
+    if t == "string" or t == "str":
+        return "<string>"
+    elif t in ("number", "int", "float", "integer"):
+        return 0
+    elif t in ("boolean", "bool"):
+        return False
+    elif t.endswith("[]") or t.startswith("array"):
+        return []
+    elif "|" in type_str:
+        # Enum-like: "admin" | "editor" | "viewer"
+        options = [o.strip().strip("'\"") for o in type_str.split("|")]
+        return f"<{'|'.join(options)}>"
+    elif type_str[0].isupper():
+        # CamelCase type name — likely an enum or custom type
+        return f"<{type_str}>"
+    else:
+        return f"<{type_str}>"
+
+
+def _detect_auth(ep: APIEndpoint) -> list[str]:
+    """Detect auth requirements from decorators and middleware."""
+    auth_items = []
+
+    for dec in ep.auth_decorators:
+        auth_items.append(dec)
+
+    for mw in ep.middleware:
+        # Check if this middleware name suggests authentication
+        mw_clean = mw.rstrip("()")
+        if any(indicator.lower() in mw_clean.lower() for indicator in _AUTH_INDICATORS):
+            if mw not in auth_items:
+                auth_items.append(mw)
+
+    return auth_items
+
+
+def _rel_path(file_path: str, repo_name: str) -> str:
+    if repo_name + "/" in file_path:
+        return file_path.split(repo_name + "/", 1)[-1]
+    return Path(file_path).name