commiter-cli 0.3.0__py3-none-any.whl

commiter/__init__.py

@@ -0,0 +1,3 @@
+"""Repo Documenter - Generate documentation from repository code analysis."""
+
+__version__ = "0.1.0"

commiter/adapters/base.py

@@ -0,0 +1,96 @@
+"""Base adapter interface — teaches extractors what framework patterns look like."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tree_sitter import Node, Tree
+
+
+@dataclass
+class RouteMatch:
+    """A matched route definition in source code."""
+    http_method: str
+    route_pattern: str
+    handler_name: str
+    handler_node: "Node"
+    decorator_nodes: list["Node"] = field(default_factory=list)
+    line: int = 0
+    param_types: dict[str, str] = field(default_factory=dict)
+    router_var: str = ""  # variable name the route is defined on (e.g. "bp", "router", "app")
+
+
+@dataclass
+class APICallMatch:
+    """A matched outbound API call in frontend code."""
+    http_method: str
+    url_pattern: str
+    call_node: "Node"
+    line: int = 0
+    response_type: str | None = None
+    body_type: str | None = None
+
+
+@dataclass
+class DBOpMatch:
+    """A matched database operation."""
+    operation_type: str  # select, insert, update, delete
+    table_name: str
+    call_node: "Node"
+    line: int = 0
+    filters: list[str] = field(default_factory=list)
+
+
+class BaseAdapter(ABC):
+    """Abstract adapter that framework-specific adapters inherit from."""
+
+    framework_name: str = "base"
+    language: str = "unknown"
+
+    @abstractmethod
+    def find_route_definitions(self, tree: "Tree", source: bytes) -> list[RouteMatch]:
+        """Find all route/endpoint definitions in a parsed file."""
+        ...
+
+    def extract_auth_info(self, route: RouteMatch, source: bytes) -> list[str]:
+        """Find auth decorators/middleware on a handler. Override per framework."""
+        return []
+
+    def extract_request_body_fields(self, route: RouteMatch, source: bytes) -> list[str]:
+        """Infer request body field names from handler. Override per framework."""
+        return []
+
+    def extract_response_fields(self, route: RouteMatch, source: bytes) -> list[str]:
+        """Infer response field names from return statements. Override per framework."""
+        return []
+
+    def extract_path_params(self, route_pattern: str) -> list[str]:
+        """Extract path parameter names from a route pattern. Override per framework."""
+        return []
+
+
+class FrontendAdapter(ABC):
+    """Adapter for detecting outbound API calls in frontend code."""
+
+    framework_name: str = "base-frontend"
+    language: str = "unknown"
+
+    @abstractmethod
+    def find_api_calls(self, tree: "Tree", source: bytes) -> list[APICallMatch]:
+        """Find outbound HTTP/API calls in frontend code."""
+        ...
+
+
+class DBAdapter(ABC):
+    """Adapter for detecting database operations."""
+
+    orm_name: str = "base-db"
+    language: str = "unknown"
+
+    @abstractmethod
+    def find_db_operations(self, tree: "Tree", source: bytes) -> list[DBOpMatch]:
+        """Find database operations."""
+        ...

commiter/adapters/django_rest.py

@@ -0,0 +1,247 @@
+"""Django REST Framework adapter — recognizes DRF ViewSet and APIView patterns."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from commiter.adapters.base import BaseAdapter, RouteMatch
+from commiter.parser import node_text, find_nodes_by_type
+
+if TYPE_CHECKING:
+    from tree_sitter import Node, Tree
+
+# DRF ViewSet action methods
+VIEWSET_ACTIONS = {
+    "list": "GET",
+    "create": "POST",
+    "retrieve": "GET",
+    "update": "PUT",
+    "partial_update": "PATCH",
+    "destroy": "DELETE",
+}
+
+# DRF APIView method mapping
+APIVIEW_METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}
+
+# Common DRF auth/permission classes
+AUTH_CLASSES = {
+    "IsAuthenticated", "IsAdminUser", "IsAuthenticatedOrReadOnly",
+    "AllowAny", "DjangoModelPermissions", "TokenAuthentication",
+    "SessionAuthentication", "JWTAuthentication",
+}
+
+
+class DjangoRESTAdapter(BaseAdapter):
+    framework_name = "django-rest"
+    language = "python"
+
+    def find_route_definitions(self, tree: Tree, source: bytes) -> list[RouteMatch]:
+        routes = []
+        text = source.decode("utf-8", errors="replace")
+
+        # Strategy 1: Find ViewSet classes and their action methods
+        routes.extend(self._find_viewset_routes(tree, source, text))
+
+        # Strategy 2: Find APIView classes with get/post/put/delete methods
+        routes.extend(self._find_apiview_routes(tree, source, text))
+
+        # Strategy 3: Find @api_view decorated functions
+        routes.extend(self._find_api_view_functions(tree, source))
+
+        return routes
+
+    def _find_viewset_routes(self, tree: Tree, source: bytes, text: str) -> list[RouteMatch]:
+        routes = []
+        root = tree.root_node
+
+        for child in root.children:
+            if child.type != "class_definition":
+                continue
+
+            class_text = node_text(child, source)
+            class_name = ""
+            name_node = child.child_by_field_name("name")
+            if name_node:
+                class_name = node_text(name_node, source)
+
+            # Check if it inherits from a ViewSet
+            superclasses = node_text(child.child_by_field_name("superclasses"), source) if child.child_by_field_name("superclasses") else ""
+            if not any(vs in superclasses for vs in ("ViewSet", "ModelViewSet", "GenericViewSet", "ReadOnlyModelViewSet")):
+                continue
+
+            # Find action methods in the class body
+            body = child.child_by_field_name("body")
+            if not body:
+                continue
+
+            for member in body.children:
+                if member.type == "function_definition":
+                    method_name_node = member.child_by_field_name("name")
+                    if not method_name_node:
+                        continue
+                    method_name = node_text(method_name_node, source)
+
+                    if method_name in VIEWSET_ACTIONS:
+                        http_method = VIEWSET_ACTIONS[method_name]
+                        route = self._infer_viewset_route(class_name, method_name)
+                        routes.append(RouteMatch(
+                            http_method=http_method,
+                            route_pattern=route,
+                            handler_name=f"{class_name}.{method_name}",
+                            handler_node=member,
+                            line=member.start_point[0] + 1,
+                        ))
+
+                # Also check for decorated definitions (custom actions)
+                elif member.type == "decorated_definition":
+                    decorators = []
+                    func_node = None
+                    for sub in member.children:
+                        if sub.type == "decorator":
+                            decorators.append(node_text(sub, source))
+                        elif sub.type == "function_definition":
+                            func_node = sub
+
+                    if func_node:
+                        func_name_node = func_node.child_by_field_name("name")
+                        if func_name_node:
+                            func_name = node_text(func_name_node, source)
+                            for dec in decorators:
+                                if "@action" in dec:
+                                    methods_match = re.search(r'methods\s*=\s*\[([^\]]+)\]', dec)
+                                    methods = ["POST"]
+                                    if methods_match:
+                                        methods = [m.strip().strip("\"'").upper() for m in methods_match.group(1).split(",")]
+                                    for m in methods:
+                                        route = self._infer_viewset_route(class_name, func_name)
+                                        routes.append(RouteMatch(
+                                            http_method=m,
+                                            route_pattern=f"{route}{func_name}/",
+                                            handler_name=f"{class_name}.{func_name}",
+                                            handler_node=func_node,
+                                            line=func_node.start_point[0] + 1,
+                                        ))
+
+        return routes
+
+    def _find_apiview_routes(self, tree: Tree, source: bytes, text: str) -> list[RouteMatch]:
+        routes = []
+        root = tree.root_node
+
+        for child in root.children:
+            if child.type != "class_definition":
+                continue
+
+            name_node = child.child_by_field_name("name")
+            if not name_node:
+                continue
+            class_name = node_text(name_node, source)
+
+            superclasses = child.child_by_field_name("superclasses")
+            if not superclasses:
+                continue
+            super_text = node_text(superclasses, source)
+            if "APIView" not in super_text:
+                continue
+
+            body = child.child_by_field_name("body")
+            if not body:
+                continue
+
+            for member in body.children:
+                if member.type == "function_definition":
+                    method_name_node = member.child_by_field_name("name")
+                    if not method_name_node:
+                        continue
+                    method_name = node_text(method_name_node, source)
+
+                    if method_name in APIVIEW_METHODS:
+                        route = self._infer_class_route(class_name)
+                        routes.append(RouteMatch(
+                            http_method=method_name.upper(),
+                            route_pattern=route,
+                            handler_name=f"{class_name}.{method_name}",
+                            handler_node=member,
+                            line=member.start_point[0] + 1,
+                        ))
+
+        return routes
+
+    def _find_api_view_functions(self, tree: Tree, source: bytes) -> list[RouteMatch]:
+        """Find @api_view(['GET', 'POST']) decorated functions."""
+        routes = []
+        root = tree.root_node
+
+        for child in root.children:
+            if child.type != "decorated_definition":
+                continue
+
+            decorators = []
+            func_node = None
+            for sub in child.children:
+                if sub.type == "decorator":
+                    decorators.append(sub)
+                elif sub.type == "function_definition":
+                    func_node = sub
+
+            if not func_node:
+                continue
+
+            for dec in decorators:
+                dec_text = node_text(dec, source)
+                if "api_view" not in dec_text:
+                    continue
+
+                methods_match = re.search(r'\[([^\]]+)\]', dec_text)
+                methods = ["GET"]
+                if methods_match:
+                    methods = [m.strip().strip("\"'").upper() for m in methods_match.group(1).split(",")]
+
+                func_name_node = func_node.child_by_field_name("name")
+                handler_name = node_text(func_name_node, source) if func_name_node else "<anonymous>"
+
+                for method in methods:
+                    routes.append(RouteMatch(
+                        http_method=method,
+                        route_pattern=f"/{handler_name.replace('_', '-')}/",
+                        handler_name=handler_name,
+                        handler_node=func_node,
+                        decorator_nodes=decorators,
+                        line=func_node.start_point[0] + 1,
+                    ))
+
+        return routes
+
+    def extract_auth_info(self, route: RouteMatch, source: bytes) -> list[str]:
+        """Detect permission_classes and authentication_classes."""
+        auth = []
+        # Check if parent class has permission_classes
+        handler_text = node_text(route.handler_node, source) if route.handler_node else ""
+
+        # Check class-level attributes (look in parent)
+        parent = route.handler_node.parent if route.handler_node else None
+        if parent:
+            parent_text = node_text(parent, source)
+            for cls in AUTH_CLASSES:
+                if cls in parent_text:
+                    auth.append(cls)
+
+        return auth
+
+    def extract_path_params(self, route_pattern: str) -> list[str]:
+        return re.findall(r"<(?:\w+:)?(\w+)>", route_pattern)
+
+    def _infer_viewset_route(self, class_name: str, action: str) -> str:
+        """Infer route from ViewSet class name: UserViewSet -> /users/"""
+        name = class_name.replace("ViewSet", "").replace("View", "")
+        name = re.sub(r"(?<!^)(?=[A-Z])", "-", name).lower()
+        if action in ("retrieve", "update", "partial_update", "destroy"):
+            return f"/{name}s/<pk>/"
+        return f"/{name}s/"
+
+    def _infer_class_route(self, class_name: str) -> str:
+        """Infer route from APIView class name."""
+        name = class_name.replace("APIView", "").replace("View", "")
+        name = re.sub(r"(?<!^)(?=[A-Z])", "-", name).lower()
+        return f"/{name}/"

commiter/adapters/express.py

@@ -0,0 +1,204 @@
+"""Express.js adapter — recognizes Express route patterns."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from commiter.adapters.base import BaseAdapter, RouteMatch
+from commiter.parser import node_text, find_nodes_by_type
+
+if TYPE_CHECKING:
+    from tree_sitter import Node, Tree
+
+# Matches: app.get("/path", ...), router.post("/path", ...)
+ROUTE_CALL_RE = re.compile(
+    r"^(\w+)\.(get|post|put|delete|patch|all)\s*$"
+)
+
+# Express path params: /users/:id
+PATH_PARAM_RE = re.compile(r":(\w+)")
+
+# Common auth middleware names
+AUTH_MIDDLEWARE = {
+    "authenticate", "auth", "requireAuth", "isAuthenticated",
+    "verifyToken", "requireLogin", "passport.authenticate",
+    "authMiddleware", "protect",
+}
+
+
+class ExpressAdapter(BaseAdapter):
+    framework_name = "express"
+    language = "javascript"  # also works for TS via the extractor's language matching
+
+    def find_route_definitions(self, tree: Tree, source: bytes) -> list[RouteMatch]:
+        routes = []
+        call_nodes = find_nodes_by_type(tree.root_node, "call_expression")
+
+        for call in call_nodes:
+            func_node = call.child_by_field_name("function")
+            if not func_node or func_node.type != "member_expression":
+                continue
+
+            func_text = node_text(func_node, source)
+            match = ROUTE_CALL_RE.match(func_text)
+            if not match:
+                continue
+
+            router_var_name = match.group(1)
+            method = match.group(2).upper()
+            if method == "ALL":
+                method = "ALL"
+
+            args = call.child_by_field_name("arguments")
+            if not args:
+                continue
+
+            # Skip app.all("*", ...) — that's middleware, not a route
+            if method == "ALL":
+                first_arg_text = ""
+                for a in args.children:
+                    if a.type in ("string", "template_string"):
+                        first_arg_text = node_text(a, source).strip("'\"`")
+                        break
+                if first_arg_text == "*":
+                    continue
+
+            # First argument should be the route string
+            route_pattern = None
+            handler_node = None
+            middleware_names: list[str] = []
+
+            for i, arg in enumerate(args.children):
+                if arg.type in ("string", "template_string"):
+                    text = node_text(arg, source)
+                    if text.startswith(("'", '"', "`")):
+                        route_pattern = text[1:-1]
+                elif arg.type in ("arrow_function", "function_expression", "function"):
+                    handler_node = arg
+                elif arg.type == "member_expression":
+                    # Class-based handler: userController.getAll
+                    handler_node = arg
+                elif arg.type == "identifier":
+                    name = node_text(arg, source)
+                    if route_pattern is not None and handler_node is None:
+                        # Could be middleware or the handler
+                        middleware_names.append(name)
+
+            if not route_pattern:
+                continue
+
+            # The handler name: try to find from handler node or infer from route
+            handler_name = self._infer_handler_name(call, source, route_pattern, method, handler_node)
+
+            routes.append(RouteMatch(
+                http_method=method,
+                route_pattern=route_pattern,
+                handler_name=handler_name,
+                handler_node=handler_node or call,
+                decorator_nodes=[],
+                line=call.start_point[0] + 1,
+                router_var=router_var_name,
+            ))
+
+        return routes
+
+    def extract_auth_info(self, route: RouteMatch, source: bytes) -> list[str]:
+        """Check if any middleware arguments match known auth patterns."""
+        auth = []
+        # Re-examine the call node's arguments for middleware identifiers
+        if route.handler_node and route.handler_node.parent:
+            parent = route.handler_node.parent
+            for child in parent.children:
+                if child.type == "identifier":
+                    name = node_text(child, source)
+                    if name in AUTH_MIDDLEWARE:
+                        auth.append(name)
+        return auth
+
+    def extract_request_body_fields(self, route: RouteMatch, source: bytes,
+                                     type_definitions: dict | None = None) -> list[str]:
+        """Find req.body fields from runtime accesses and TS type annotations."""
+        fields = []
+        if route.handler_node is None:
+            return fields
+        body_text = node_text(route.handler_node, source)
+
+        # Try TS type annotation first: (req: Request<{}, {}, CreateUserBody>)
+        body_type = self._extract_request_body_type(route.handler_node, source)
+        if body_type:
+            route.param_types["_request_body_type"] = body_type
+            # Resolve from same-file type definitions if available
+            if type_definitions and body_type in type_definitions:
+                for tf in type_definitions[body_type]:
+                    opt = "?" if tf.optional else ""
+                    fields.append(f"{tf.name}: {tf.type_str}{opt}")
+                return fields
+
+        # Fallback: runtime field accesses
+        # req.body.fieldName
+        for match in re.finditer(r'req\.body\.(\w+)', body_text):
+            field = match.group(1)
+            if field not in fields:
+                fields.append(field)
+
+        # req.body["fieldName"] or req.body['fieldName']
+        for match in re.finditer(r'req\.body\[(["\'])(\w+)\1\]', body_text):
+            field = match.group(2)
+            if field not in fields:
+                fields.append(field)
+
+        # Destructuring: const { name, email } = req.body
+        for match in re.finditer(r'\{([^}]+)\}\s*=\s*req\.body', body_text):
+            for name in match.group(1).split(","):
+                field = name.strip().split(":")[0].strip()
+                if field and field not in fields:
+                    fields.append(field)
+
+        return fields
+
+    def _extract_request_body_type(self, handler_node: Node, source: bytes) -> str | None:
+        """Extract the body type from Request<Params, ResBody, ReqBody> annotation."""
+        handler_text = node_text(handler_node, source)
+        # Match: req: Request<any, any, CreateUserBody> or req: Request<{}, {}, CreateUserBody>
+        match = re.search(r':\s*Request\s*<[^,]*,[^,]*,\s*(\w+)\s*>', handler_text)
+        if match:
+            return match.group(1)
+        return None
+
+    def extract_response_fields(self, route: RouteMatch, source: bytes) -> list[str]:
+        """Find fields in res.json({...}) calls."""
+        fields = []
+        if route.handler_node is None:
+            return fields
+        body_text = node_text(route.handler_node, source)
+
+        for match in re.finditer(r'(\w+)\s*:', body_text):
+            key = match.group(1)
+            # Filter out common non-response keys
+            if key not in ("const", "let", "var", "if", "else", "return", "function", "async", "await"):
+                if key not in fields:
+                    fields.append(key)
+
+        return fields
+
+    def extract_path_params(self, route_pattern: str) -> list[str]:
+        return PATH_PARAM_RE.findall(route_pattern)
+
+    def _infer_handler_name(self, call: Node, source: bytes, route: str, method: str,
+                            handler_node: "Node | None" = None) -> str:
+        """Try to get a handler name from the handler node, assignment, or route."""
+        # Class-based handler: userController.getAll -> "UserController.getAll"
+        if handler_node and handler_node.type == "member_expression":
+            return node_text(handler_node, source)
+
+        # Check if this call is part of an assignment
+        parent = call.parent
+        if parent and parent.type in ("variable_declarator", "assignment_expression"):
+            name_node = parent.child_by_field_name("name") or parent.child_by_field_name("left")
+            if name_node:
+                return node_text(name_node, source)
+
+        # Fallback: method + route
+        clean_route = route.replace("/", "_").strip("_")
+        return f"{method.lower()}_{clean_route}" if clean_route else method.lower()