commiter-cli 0.3.0__py3-none-any.whl

commiter/middleware_index.py

@@ -0,0 +1,350 @@
+"""Cross-file middleware index: maps middleware to the routes they cover.
+
+Detects middleware registrations across files and resolves which routes
+are covered by which middleware based on scope, path prefix, and line ordering.
+
+Patterns detected:
+  Express:  app.use(authMiddleware)
+            app.use("/api", authMiddleware)
+            router.use(authMiddleware)
+  Flask:    @app.before_request / @bp.before_request
+            app.before_request(func)
+  FastAPI:  app.add_middleware(AuthMiddleware)
+            @app.middleware("http")
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tree_sitter import Tree
+
+
+# Patterns that indicate a variable is a router, not middleware
+_ROUTER_PATTERNS = re.compile(
+    r'.*[Rr]outer$|.*[Rr]outes$|.*_bp$|.*_blueprint$|.*[Hh]andler$|.*[Cc]ontroller$'
+)
+
+
+def _is_router_name(name: str) -> bool:
+    """Check if a variable name looks like a router rather than middleware."""
+    return bool(_ROUTER_PATTERNS.match(name))
+
+
+@dataclass
+class MiddlewareBinding:
+    """A middleware registration found in source code."""
+    name: str              # middleware function/class name
+    scope: str             # "global", "path", "router"
+    path_prefix: str       # "/api" for path-scoped, "" for global/router
+    router_var: str        # "app", "router", "bp" — which object it's mounted on
+    file_path: str
+    line: int
+
+
+class MiddlewareIndex:
+    """Index of middleware registrations across all files.
+
+    Built during Pass 1, queried during Pass 2 to attach middleware to routes.
+    """
+
+    def __init__(self) -> None:
+        # file_path -> list of bindings found in that file
+        self._bindings_by_file: dict[str, list[MiddlewareBinding]] = {}
+        # router_var -> list of bindings (for cross-file: find middleware on a router)
+        self._bindings_by_router: dict[str, list[MiddlewareBinding]] = {}
+        # For cross-file: imported router name -> source file
+        self._router_imports: dict[str, dict[str, str]] = {}
+        # Track where routers are mounted: file -> {router_var: mount_line}
+        self._router_mount_lines: dict[str, dict[str, int]] = {}
+
+    def index_file(self, file_path: str, tree: "Tree", source: bytes, language: str) -> None:
+        """Scan a file for middleware registrations."""
+        abs_path = os.path.abspath(file_path)
+        text = source.decode("utf-8", errors="replace")
+
+        bindings: list[MiddlewareBinding] = []
+
+        if language == "python":
+            bindings.extend(self._find_python_middleware(abs_path, text))
+        elif language in ("javascript", "typescript", "tsx"):
+            bindings.extend(self._find_js_middleware(abs_path, text))
+
+        if bindings:
+            self._bindings_by_file[abs_path] = bindings
+            for b in bindings:
+                self._bindings_by_router.setdefault(b.router_var, []).append(b)
+
+        # Track imports for cross-file resolution
+        self._track_imports(abs_path, text, language)
+
+    def get_middleware_for_route(
+        self,
+        file_path: str,
+        route_pattern: str,
+        router_var: str,
+        route_line: int,
+    ) -> list[str]:
+        """Get middleware names that cover a specific route.
+
+        Args:
+            file_path: File containing the route.
+            route_pattern: The route's URL pattern (e.g. "/api/users").
+            router_var: The variable the route is defined on (e.g. "router", "bp").
+            route_line: Line number of the route definition.
+
+        Returns:
+            List of middleware names covering this route.
+        """
+        abs_path = os.path.abspath(file_path)
+        middleware: list[str] = []
+        seen: set[str] = set()
+
+        def _add(name: str) -> None:
+            if name not in seen:
+                seen.add(name)
+                middleware.append(name)
+
+        # 1. Same-file middleware on the same router, registered before this line
+        for binding in self._bindings_by_file.get(abs_path, []):
+            if binding.router_var == router_var and binding.line < route_line:
+                if binding.scope == "router":
+                    _add(binding.name)
+                elif binding.scope == "path" and route_pattern.startswith(binding.path_prefix):
+                    _add(binding.name)
+                elif binding.scope == "global":
+                    _add(binding.name)
+
+        # 2. Same-file app-level middleware (covers all routes regardless of router_var)
+        for binding in self._bindings_by_file.get(abs_path, []):
+            if binding.scope == "global" and binding.router_var != router_var:
+                if binding.line < route_line:
+                    _add(binding.name)
+
+        # 3. Cross-file: find middleware registered on 'app' in other files
+        # Use router mount lines to check ordering (middleware must be before the router mount)
+        for other_file, bindings in self._bindings_by_file.items():
+            if other_file == abs_path:
+                continue
+
+            # Find the mount line for the router that serves our routes
+            mount_lines = self._router_mount_lines.get(other_file, {})
+            # The router from our file could be imported under various names
+            router_mount_line = None
+            for var_name, mount_line in mount_lines.items():
+                # Check if this import points to our file
+                imports = self._router_imports.get(other_file, {})
+                source = imports.get(var_name, "")
+                file_stem = Path(abs_path).stem
+                if file_stem in source or router_var in source:
+                    router_mount_line = mount_line
+                    break
+
+            for binding in bindings:
+                # Global app-level middleware — must be before router mount (if we know the mount line)
+                if binding.scope == "global" and binding.router_var in ("app", "server"):
+                    if router_mount_line is None or binding.line < router_mount_line:
+                        _add(binding.name)
+                # Path-scoped middleware — must match path AND be before router mount
+                elif binding.scope == "path" and route_pattern.startswith(binding.path_prefix):
+                    if router_mount_line is None or binding.line < router_mount_line:
+                        _add(binding.name)
+
+        # 4. Cross-file: middleware on the router variable that imports this file's router
+        self._resolve_cross_file_router_middleware(abs_path, router_var, middleware, seen)
+
+        return middleware
+
+    def _find_python_middleware(self, abs_path: str, text: str) -> list[MiddlewareBinding]:
+        """Find Flask/FastAPI middleware patterns in Python code."""
+        bindings = []
+
+        # @app.before_request or @bp.before_request
+        for match in re.finditer(r'@(\w+)\.before_request\b', text):
+            var_name = match.group(1)
+            line = text[:match.start()].count("\n") + 1
+            # Find the function name on the next line
+            func_match = re.search(r'def\s+(\w+)', text[match.end():match.end() + 200])
+            func_name = func_match.group(1) if func_match else "before_request"
+            bindings.append(MiddlewareBinding(
+                name=func_name, scope="router", path_prefix="",
+                router_var=var_name, file_path=abs_path, line=line,
+            ))
+
+        # app.before_request(func) — non-decorator form
+        for match in re.finditer(r'(\w+)\.before_request\s*\(\s*(\w+)\s*\)', text):
+            var_name = match.group(1)
+            func_name = match.group(2)
+            line = text[:match.start()].count("\n") + 1
+            bindings.append(MiddlewareBinding(
+                name=func_name, scope="router", path_prefix="",
+                router_var=var_name, file_path=abs_path, line=line,
+            ))
+
+        # app.add_middleware(AuthMiddleware) — FastAPI
+        for match in re.finditer(r'(\w+)\.add_middleware\s*\(\s*(\w+)', text):
+            var_name = match.group(1)
+            class_name = match.group(2)
+            line = text[:match.start()].count("\n") + 1
+            bindings.append(MiddlewareBinding(
+                name=class_name, scope="global", path_prefix="",
+                router_var=var_name, file_path=abs_path, line=line,
+            ))
+
+        # @app.middleware("http") — FastAPI decorator
+        for match in re.finditer(r'@(\w+)\.middleware\s*\(\s*["\']http["\']\s*\)', text):
+            var_name = match.group(1)
+            line = text[:match.start()].count("\n") + 1
+            func_match = re.search(r'(?:async\s+)?def\s+(\w+)', text[match.end():match.end() + 200])
+            func_name = func_match.group(1) if func_match else "http_middleware"
+            bindings.append(MiddlewareBinding(
+                name=func_name, scope="global", path_prefix="",
+                router_var=var_name, file_path=abs_path, line=line,
+            ))
+
+        return bindings
+
+    def _find_js_middleware(self, abs_path: str, text: str) -> list[MiddlewareBinding]:
+        """Find Express middleware patterns in JS/TS code."""
+        bindings = []
+
+        # app.use(middleware), app.use("/path", middleware), router.use(middleware)
+        # Also: app.all("*", middleware) — another pattern for global middleware
+        # Need to distinguish from app.use("/path", router) which is a route mount
+        for match in re.finditer(
+            r'(\w+)\.(?:use|all)\s*\(([^)]+)\)',
+            text,
+        ):
+            obj_name = match.group(1)
+            args_text = match.group(2).strip()
+            line = text[:match.start()].count("\n") + 1
+
+            # Parse arguments
+            parts = [p.strip() for p in self._split_args(args_text)]
+            if not parts:
+                continue
+
+            path_prefix = ""
+            middleware_names = []
+
+            for part in parts:
+                # String argument = path prefix
+                if (part.startswith('"') or part.startswith("'") or part.startswith("`")):
+                    path_prefix = part.strip("\"'`")
+                # Identifier = middleware or router
+                elif re.match(r'^[a-zA-Z_]\w*$', part):
+                    middleware_names.append(part)
+                # Function call like cors() or helmet()
+                elif re.match(r'^[a-zA-Z_]\w*\s*\(', part):
+                    func_name = re.match(r'^(\w+)', part).group(1)
+                    middleware_names.append(f"{func_name}()")
+
+            # Heuristic: if there's only one identifier and it looks like a router
+            # (ends with Router, _router, etc.), record mount line and skip middleware
+            if len(middleware_names) == 1 and path_prefix:
+                name = middleware_names[0]
+                if _is_router_name(name):
+                    self._router_mount_lines.setdefault(abs_path, {})[name] = line
+                    continue  # This is a route mount, handled by PrefixIndex
+
+            # If there are multiple identifiers with a path, the last might be a router
+            # and the others are middleware. Record mount line for router-like ones.
+            if path_prefix and len(middleware_names) > 1:
+                last = middleware_names[-1]
+                if _is_router_name(last):
+                    self._router_mount_lines.setdefault(abs_path, {})[last] = line
+                    middleware_names = middleware_names[:-1]  # remove router, keep middleware
+
+            for mw_name in middleware_names:
+                scope = "path" if path_prefix else "router"
+                # app.use with no path = global; app.all("*", ...) is also global
+                if obj_name in ("app", "server") and (not path_prefix or path_prefix == "*"):
+                    scope = "global"
+                    path_prefix = ""
+                bindings.append(MiddlewareBinding(
+                    name=mw_name, scope=scope, path_prefix=path_prefix,
+                    router_var=obj_name, file_path=abs_path, line=line,
+                ))
+
+        return bindings
+
+    def _split_args(self, args_text: str) -> list[str]:
+        """Split function arguments, respecting nested parens and quotes."""
+        parts = []
+        depth = 0
+        current = ""
+        in_string = None
+
+        for ch in args_text:
+            if in_string:
+                current += ch
+                if ch == in_string:
+                    in_string = None
+                continue
+
+            if ch in ("'", '"', '`'):
+                in_string = ch
+                current += ch
+            elif ch == '(' :
+                depth += 1
+                current += ch
+            elif ch == ')':
+                depth -= 1
+                current += ch
+            elif ch == ',' and depth == 0:
+                if current.strip():
+                    parts.append(current.strip())
+                current = ""
+            else:
+                current += ch
+
+        if current.strip():
+            parts.append(current.strip())
+        return parts
+
+    def _track_imports(self, abs_path: str, text: str, language: str) -> None:
+        """Track router imports for cross-file middleware resolution."""
+        if language in ("javascript", "typescript", "tsx"):
+            for match in re.finditer(r'import\s+(\w+)\s+from\s+["\']([^"\']+)["\']', text):
+                self._router_imports.setdefault(abs_path, {})[match.group(1)] = match.group(2)
+            for match in re.finditer(r'(?:const|let|var)\s+(\w+)\s*=\s*require\s*\(\s*["\']([^"\']+)["\']\s*\)', text):
+                self._router_imports.setdefault(abs_path, {})[match.group(1)] = match.group(2)
+        elif language == "python":
+            for match in re.finditer(r'from\s+(\S+)\s+import\s+(.+)', text):
+                module = 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
+
+    def _resolve_cross_file_router_middleware(
+        self, route_file: str, router_var: str, middleware: list[str], seen: set[str]
+    ) -> None:
+        """Check if other files mount this router with middleware."""
+        route_file_stem = Path(route_file).stem
+
+        for other_file, imports in self._router_imports.items():
+            if other_file == route_file:
+                continue
+            for imported_name, source_path in imports.items():
+                if route_file_stem in source_path or router_var in source_path:
+                    # Find where this router is mounted
+                    mount_line = self._router_mount_lines.get(other_file, {}).get(imported_name)
+
+                    for binding in self._bindings_by_file.get(other_file, []):
+                        if binding.router_var == imported_name or binding.scope == "global":
+                            # Respect line ordering: middleware must be before router mount
+                            if mount_line is not None and binding.line >= mount_line:
+                                continue
+                            if binding.name not in seen:
+                                seen.add(binding.name)
+                                middleware.append(binding.name)
+
+    @property
+    def binding_count(self) -> int:
+        return sum(len(b) for b in self._bindings_by_file.values())

commiter/models.py

@@ -0,0 +1,117 @@
+"""Data models for all extracted documentation artifacts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class FileRole(Enum):
+    BACKEND = "backend"
+    FRONTEND = "frontend"
+    CONFIG = "config"
+    TEST = "test"
+    MIGRATION = "migration"
+    SHARED = "shared"
+    UNKNOWN = "unknown"
+
+
+class ParamSource(Enum):
+    PATH = "path"
+    QUERY = "query"
+    HEADER = "header"
+    BODY = "body"
+
+
+@dataclass
+class Param:
+    name: str
+    source: ParamSource
+    type_hint: str | None = None
+    required: bool = True
+
+
+@dataclass
+class APIEndpoint:
+    repo: str
+    file_path: str
+    line: int
+    http_method: str
+    route_pattern: str
+    handler_name: str
+    framework: str
+    parameters: list[Param] = field(default_factory=list)
+    request_body_fields: list[str] = field(default_factory=list)
+    response_fields: list[str] = field(default_factory=list)
+    auth_decorators: list[str] = field(default_factory=list)
+    db_tables: list[str] = field(default_factory=list)
+    request_body_type: str | None = None
+    response_type: str | None = None
+    middleware: list[str] = field(default_factory=list)
+
+
+@dataclass
+class APICall:
+    repo: str
+    file_path: str
+    line: int
+    component_or_page: str
+    http_method: str
+    url_pattern: str
+    client_library: str
+    body_fields: list[str] = field(default_factory=list)
+    traced_from: str | None = None
+    response_type: str | None = None
+    body_type: str | None = None
+
+
+@dataclass
+class Dependency:
+    repo: str
+    name: str
+    version_constraint: str
+    source_file: str
+    dev_only: bool = False
+
+
+@dataclass
+class FileClassification:
+    file_path: str
+    role: FileRole
+    language: str
+    framework_hints: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DBOperation:
+    repo: str
+    file_path: str
+    line: int
+    operation_type: str  # select, insert, update, delete
+    table_name: str
+    orm_library: str
+    filters: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ServiceRelationship:
+    source_repo: str
+    target_repo: str
+    connection_type: str  # api_call, shared_db, shared_package
+    source_file: str
+    target_endpoint: str
+    confidence: float = 0.0
+
+
+@dataclass
+class RepoDocumentation:
+    repo_name: str
+    repo_path: str
+    languages: list[str] = field(default_factory=list)
+    frameworks: list[str] = field(default_factory=list)
+    endpoints: list[APIEndpoint] = field(default_factory=list)
+    api_calls: list[APICall] = field(default_factory=list)
+    dependencies: list[Dependency] = field(default_factory=list)
+    file_classifications: list[FileClassification] = field(default_factory=list)
+    db_operations: list[DBOperation] = field(default_factory=list)
+    service_relationships: list[ServiceRelationship] = field(default_factory=list)