agentforge-graph 0.3.2__py3-none-any.whl

agentforge_graph/frameworks/packs/fastapi/__init__.py

@@ -0,0 +1,210 @@
+"""FastAPI framework pack (feat-011) — routes + dependency injection.
+
+Routes: ``@app.get("/x")`` / ``@router.post(...)`` decorators become ``Route``
+nodes + ``HANDLED_BY`` edges to the handler ``Function``. DI: a parameter
+defaulting to ``Depends(provider)`` / ``Security(provider)`` becomes a
+``Service`` node (the provider) + an ``INJECTED_INTO`` edge to the consuming
+function. Both are intra-file (decorator/param and the function share a file, so
+the edge endpoints are in the file's ``FileSubgraph``). Class-based handlers /
+consumers resolve to their ``Class#method`` symbol. Cross-file ``include_router``
+prefix composition and grounding the provider name to its definition are
+follow-ups; a dynamic (non-literal) route path is counted as unresolved.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+from tree_sitter import Node as TSNode
+from tree_sitter import Parser, Query, QueryCursor
+
+from agentforge_graph.core import (
+    Edge,
+    EdgeKind,
+    NodeKind,
+    Provenance,
+    SourceFile,
+    SymbolID,
+)
+from agentforge_graph.core import Node as GraphNode
+from agentforge_graph.frameworks.base import FrameworkFacts, FrameworkPack
+from agentforge_graph.frameworks.packs._python_ast import (
+    callee_name,
+    dotted_tail,
+    enclosing_class,
+    first_positional_arg,
+    first_string_in,
+    member_descriptor,
+    python_language,
+    text,
+)
+
+_HERE = Path(__file__).parent
+_HTTP_METHODS = {"get", "post", "put", "delete", "patch", "options", "head"}
+_DI_CALLS = {"Depends", "Security"}  # FastAPI dependency markers
+
+
+@cache
+def _routes_query() -> str:
+    return (_HERE / "routes.scm").read_text(encoding="utf-8")
+
+
+@cache
+def _depends_query() -> str:
+    return (_HERE / "depends.scm").read_text(encoding="utf-8")
+
+
+class FastAPIPack(FrameworkPack):
+    name = "fastapi"
+    language = "python"
+    language_slug = "py"  # SymbolID slug — must match the Python language pack
+    version = "1"
+    dep_names = ("fastapi",)
+    import_markers = ("import fastapi", "from fastapi")
+
+    def extract(self, file: SourceFile, repo: str, commit: str) -> FrameworkFacts:
+        src = file.text.encode("utf-8")
+        root = Parser(python_language()).parse(src).root_node
+        prov = Provenance.parsed(f"pack:{self.name}@{self.version}", commit)
+        facts = FrameworkFacts()
+        self._extract_routes(root, src, repo, file, prov, facts)
+        self._extract_depends(root, src, repo, file, prov, facts)
+        return facts
+
+    def _extract_routes(
+        self,
+        root: TSNode,
+        src: bytes,
+        repo: str,
+        file: SourceFile,
+        prov: Provenance,
+        facts: FrameworkFacts,
+    ) -> None:
+        query = Query(python_language(), _routes_query())
+        seen: set[str] = set()
+        for _pattern, caps in QueryCursor(query).matches(root):
+            method_caps = caps.get("method")
+            handler_caps = caps.get("handler")
+            args_caps = caps.get("args")
+            if not (method_caps and handler_caps and args_caps):
+                continue
+            method = text(method_caps[0], src).lower()
+            if method not in _HTTP_METHODS:
+                continue  # @app.middleware / @app.on_event / etc. — not a route
+
+            # A route we recognise but can't pin down statically is counted,
+            # not dropped: a dynamic (non-literal) path.
+            path = first_string_in(args_caps[0], src)
+            if path is None:
+                facts.unresolved += 1
+                continue
+
+            handler = text(handler_caps[0], src)
+            handler_desc = member_descriptor(handler, enclosing_class(handler_caps[0], src))
+            handler_id = SymbolID.for_symbol(self.language_slug, repo, file.path, handler_desc)
+            method_u = method.upper()
+            route_id = SymbolID.for_symbol(
+                self.language_slug, repo, file.path, f"route({method_u} {path})."
+            )
+            if route_id in seen:
+                continue
+            seen.add(route_id)
+            route_node = caps["route"][0]
+            facts.nodes.append(
+                GraphNode(
+                    id=route_id,
+                    kind=NodeKind.ROUTE,
+                    name=f"{method_u} {path}",
+                    span=(route_node.start_point[0] + 1, route_node.end_point[0] + 1),
+                    attrs={
+                        "method": method_u,
+                        "path": path,
+                        "framework": self.name,
+                        "handler": handler_id,
+                    },
+                    provenance=prov,
+                )
+            )
+            facts.edges.append(
+                Edge(src=route_id, dst=handler_id, kind=EdgeKind.HANDLED_BY, provenance=prov)
+            )
+
+    def _extract_depends(
+        self,
+        root: TSNode,
+        src: bytes,
+        repo: str,
+        file: SourceFile,
+        prov: Provenance,
+        facts: FrameworkFacts,
+    ) -> None:
+        query = Query(python_language(), _depends_query())
+        seen_service: set[str] = set()
+        seen_edge: set[tuple[str, str]] = set()
+        for _pattern, caps in QueryCursor(query).matches(root):
+            fn_caps = caps.get("fn")
+            name_caps = caps.get("func")
+            if not (fn_caps and name_caps):
+                continue
+            fn_node = fn_caps[0]
+            # MVP: only module-level functions (class-based consumers, like
+            # class-based route handlers, are a follow-up) — counted, not dropped.
+            params = fn_node.child_by_field_name("parameters")
+            if params is None:
+                continue
+            providers = self._depends_providers(params, src)
+            if not providers:
+                continue
+            consumer_desc = member_descriptor(
+                text(name_caps[0], src), enclosing_class(name_caps[0], src)
+            )
+            consumer_id = SymbolID.for_symbol(self.language_slug, repo, file.path, consumer_desc)
+            for provider in providers:
+                service_id = SymbolID.for_symbol(
+                    self.language_slug, repo, file.path, f"service({provider})."
+                )
+                if service_id not in seen_service:
+                    seen_service.add(service_id)
+                    facts.nodes.append(
+                        GraphNode(
+                            id=service_id,
+                            kind=NodeKind.SERVICE,
+                            name=provider,
+                            span=(fn_node.start_point[0] + 1, fn_node.start_point[0] + 1),
+                            attrs={"framework": self.name, "provider": provider},
+                            provenance=prov,
+                        )
+                    )
+                edge_key = (service_id, consumer_id)
+                if edge_key not in seen_edge:
+                    seen_edge.add(edge_key)
+                    facts.edges.append(
+                        Edge(
+                            src=service_id,
+                            dst=consumer_id,
+                            kind=EdgeKind.INJECTED_INTO,
+                            provenance=prov,
+                        )
+                    )
+
+    def _depends_providers(self, params: TSNode, src: bytes) -> list[str]:
+        """Provider names from ``= Depends(provider)`` / ``= Security(provider)``
+        parameter defaults, in source order (deduped)."""
+        providers: list[str] = []
+        for param in params.named_children:
+            if param.type not in ("default_parameter", "typed_default_parameter"):
+                continue
+            value = param.child_by_field_name("value")
+            if value is None or value.type != "call":
+                continue
+            if callee_name(value, src) not in _DI_CALLS:
+                continue
+            arg = first_positional_arg(value, src)
+            provider = dotted_tail(arg, src) if arg is not None else ""
+            if provider and provider not in providers:
+                providers.append(provider)
+        return providers
+
+
+FASTAPI_PACK = FastAPIPack()

agentforge_graph/frameworks/packs/fastapi/depends.scm

@@ -0,0 +1,6 @@
+; FastAPI dependency injection (feat-011). Capture every function so the pack
+; can inspect its parameters for `= Depends(provider)` / `= Security(provider)`
+; defaults in code (both `default_parameter` and `typed_default_parameter`
+; carry the call in their `value` field).
+(function_definition
+  name: (identifier) @func) @fn

agentforge_graph/frameworks/packs/fastapi/routes.scm

@@ -0,0 +1,10 @@
+; FastAPI route decorators (feat-011). Matches `@app.get("/x")` /
+; `@router.post(...)` on a function. The method/path are validated in code
+; (HTTP verb + a string-literal path) so non-route or dynamic-path decorators
+; can be counted as unresolved rather than silently missed.
+(decorated_definition
+  (decorator
+    (call
+      function: (attribute object: (identifier) @app attribute: (identifier) @method)
+      arguments: (argument_list) @args))
+  definition: (function_definition name: (identifier) @handler)) @route

agentforge_graph/frameworks/packs/flask/__init__.py

@@ -0,0 +1,143 @@
+"""Flask framework pack (feat-011) — routes.
+
+Extracts ``@app.route("/x", methods=[...])`` / blueprint ``@bp.route(...)`` and
+the Flask 2.0 shortcuts (``@app.get("/x")`` …) into ``Route`` nodes + ``HANDLED_BY``
+edges to the handler ``Function``/method. A ``route`` decorator defaults to
+``GET`` and may list several ``methods`` → one ``Route`` per method. Class-based
+handlers resolve to their ``Class#method`` symbol; a dynamic (non-literal) path
+is counted unresolved, never dropped. Intra-file (decorator and handler share a
+file), so it rides the file's ``FileSubgraph`` + feat-004 incrementality.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+from tree_sitter import Node as TSNode
+from tree_sitter import Parser, Query, QueryCursor
+
+from agentforge_graph.core import (
+    Edge,
+    EdgeKind,
+    NodeKind,
+    Provenance,
+    SourceFile,
+    SymbolID,
+)
+from agentforge_graph.core import Node as GraphNode
+from agentforge_graph.frameworks.base import FrameworkFacts, FrameworkPack
+from agentforge_graph.frameworks.packs._python_ast import (
+    enclosing_class,
+    first_string_in,
+    member_descriptor,
+    python_language,
+    string_list_kwarg,
+    text,
+)
+
+_HERE = Path(__file__).parent
+_HTTP_METHODS = {"get", "post", "put", "delete", "patch", "options", "head"}
+
+
+@cache
+def _query_text() -> str:
+    return (_HERE / "routes.scm").read_text(encoding="utf-8")
+
+
+class FlaskPack(FrameworkPack):
+    name = "flask"
+    language = "python"
+    language_slug = "py"  # SymbolID slug — must match the Python language pack
+    version = "1"
+    dep_names = ("flask",)
+    import_markers = ("import flask", "from flask")
+
+    def extract(self, file: SourceFile, repo: str, commit: str) -> FrameworkFacts:
+        src = file.text.encode("utf-8")
+        root = Parser(python_language()).parse(src).root_node
+        query = Query(python_language(), _query_text())
+        prov = Provenance.parsed(f"pack:{self.name}@{self.version}", commit)
+        facts = FrameworkFacts()
+        seen: set[str] = set()
+
+        for _pattern, caps in QueryCursor(query).matches(root):
+            method_caps = caps.get("method")
+            handler_caps = caps.get("handler")
+            args_caps = caps.get("args")
+            if not (method_caps and handler_caps and args_caps):
+                continue
+            decorator = text(method_caps[0], src).lower()
+            methods = self._methods_for(decorator, args_caps[0], src)
+            if methods is None:
+                continue  # not a route decorator (e.g. @app.before_request)
+
+            path = first_string_in(args_caps[0], src)
+            if path is None:
+                facts.unresolved += 1  # dynamic / non-literal path
+                continue
+
+            handler = text(handler_caps[0], src)
+            handler_id = SymbolID.for_symbol(
+                self.language_slug,
+                repo,
+                file.path,
+                member_descriptor(handler, enclosing_class(handler_caps[0], src)),
+            )
+            route_node = caps["route"][0]
+            for method in methods:
+                self._emit_route(
+                    method, path, handler_id, route_node, repo, file, prov, facts, seen
+                )
+        return facts
+
+    def _methods_for(self, decorator: str, args: TSNode, src: bytes) -> list[str] | None:
+        """The HTTP methods a decorator declares: the ``methods=[...]`` kwarg for
+        ``@app.route`` (default ``GET``), the verb itself for ``@app.get`` …, or
+        None when the decorator is not a route."""
+        if decorator == "route":
+            listed = [m.upper() for m in string_list_kwarg(args, "methods", src)]
+            return listed or ["GET"]
+        if decorator in _HTTP_METHODS:
+            return [decorator.upper()]
+        return None
+
+    def _emit_route(
+        self,
+        method: str,
+        path: str,
+        handler_id: str,
+        route_node: TSNode,
+        repo: str,
+        file: SourceFile,
+        prov: Provenance,
+        facts: FrameworkFacts,
+        seen: set[str],
+    ) -> None:
+        route_id = SymbolID.for_symbol(
+            self.language_slug, repo, file.path, f"route({method} {path})."
+        )
+        if route_id in seen:
+            return
+        seen.add(route_id)
+        facts.nodes.append(
+            GraphNode(
+                id=route_id,
+                kind=NodeKind.ROUTE,
+                name=f"{method} {path}",
+                span=(route_node.start_point[0] + 1, route_node.end_point[0] + 1),
+                attrs={
+                    "method": method,
+                    "path": path,
+                    "framework": self.name,
+                    "handler": handler_id,
+                },
+                provenance=prov,
+            )
+        )
+        facts.edges.append(
+            Edge(src=route_id, dst=handler_id, kind=EdgeKind.HANDLED_BY, provenance=prov)
+        )
+
+
+FLASK_PACK = FlaskPack()

agentforge_graph/frameworks/packs/flask/routes.scm

@@ -0,0 +1,11 @@
+; Flask route decorators (feat-011). Matches `@app.route("/x", methods=[...])`,
+; blueprint `@bp.route(...)`, and the Flask 2.0 shortcuts `@app.get("/x")` etc.
+; on a function. The decorator attribute (route/get/post/…) and the path/methods
+; are validated in code so non-route decorators (`@app.before_request`) and
+; dynamic paths are handled, not silently missed.
+(decorated_definition
+  (decorator
+    (call
+      function: (attribute object: (_) @app attribute: (identifier) @method)
+      arguments: (argument_list) @args))
+  definition: (function_definition name: (identifier) @handler)) @route

agentforge_graph/frameworks/packs/nestjs/__init__.py

@@ -0,0 +1,205 @@
+"""NestJS framework pack (feat-011) — controller routes (TypeScript).
+
+Extracts NestJS endpoints into ``Route`` nodes + ``HANDLED_BY`` edges. A class is
+a route source only when it carries an ``@Controller`` decorator (ADR-0004); its
+optional ``@Controller('base')`` argument is the base path. Each method decorated
+with ``@Get`` / ``@Post`` / ``@Put`` / ``@Delete`` / ``@Patch`` / ``@All``
+becomes a ``Route`` whose path is the base joined with the decorator's path
+argument, handled by the ``Class#method`` symbol. TypeScript decorators are
+preceding siblings of the node they annotate, so the pack reads the class's
+preceding decorators and walks the class body in order.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+from tree_sitter import Node as TSNode
+from tree_sitter import Parser, Query, QueryCursor
+
+from agentforge_graph.core import (
+    Descriptor,
+    Edge,
+    EdgeKind,
+    NodeKind,
+    Provenance,
+    SourceFile,
+    SymbolID,
+)
+from agentforge_graph.core import Node as GraphNode
+from agentforge_graph.frameworks.base import FrameworkFacts, FrameworkPack
+from agentforge_graph.frameworks.packs._js_ast import js_language, string_value, text
+
+_HERE = Path(__file__).parent
+_SLUG = "ts"
+_MAPPING = {
+    "Get": "GET",
+    "Post": "POST",
+    "Put": "PUT",
+    "Delete": "DELETE",
+    "Patch": "PATCH",
+    "All": "ALL",
+}
+
+
+@cache
+def _query_text() -> str:
+    return (_HERE / "routes.scm").read_text(encoding="utf-8")
+
+
+def _decorator_name_and_path(dec: TSNode, src: bytes) -> tuple[str, str]:
+    """``(name, path)`` for a decorator: ``@Get(':id')`` -> ``("Get", ":id")``,
+    ``@Get()`` / ``@Get`` -> ``("Get", "")``."""
+    child = dec.named_children[0] if dec.named_children else None
+    if child is None:
+        return "", ""
+    if child.type == "call_expression":
+        fn = child.child_by_field_name("function")
+        name = text(fn, src) if fn is not None else ""
+        args = child.child_by_field_name("arguments")
+        path = ""
+        if args is not None and args.named_children:
+            path = string_value(args.named_children[0], src) or ""
+        return name, path
+    if child.type == "identifier":
+        return text(child, src), ""
+    return "", ""
+
+
+def _preceding_decorators(node: TSNode, src: bytes) -> list[tuple[str, str]]:
+    """The ``(name, path)`` of each decorator immediately preceding ``node``
+    (TS attaches decorators as previous siblings; an ``export`` keyword may sit
+    between)."""
+    out: list[tuple[str, str]] = []
+    sib = node.prev_sibling
+    while sib is not None:
+        if sib.type == "decorator":
+            out.append(_decorator_name_and_path(sib, src))
+        elif sib.is_named:
+            break  # a real preceding statement ends the decorator run
+        sib = sib.prev_sibling
+    return out
+
+
+def _join(base: str, path: str) -> str:
+    """Join NestJS path segments (which omit leading slashes) into one absolute
+    pattern: ``users`` + ``:id`` -> ``/users/:id``."""
+    segments = [s.strip("/") for s in (base, path) if s.strip("/")]
+    return "/" + "/".join(segments) if segments else "/"
+
+
+class NestJSPack(FrameworkPack):
+    name = "nestjs"
+    language = "typescript"
+    language_slug = _SLUG  # SymbolID slug — must match the TypeScript language pack
+    version = "1"
+    dep_names = ("@nestjs/common", "@nestjs/core")
+    import_markers = ("@nestjs/common", "from '@nestjs", 'from "@nestjs')
+
+    def extract(self, file: SourceFile, repo: str, commit: str) -> FrameworkFacts:
+        src = file.text.encode("utf-8")
+        lang = js_language(_SLUG)
+        root = Parser(lang).parse(src).root_node
+        query = Query(lang, _query_text())
+        prov = Provenance.parsed(f"pack:{self.name}@{self.version}", commit)
+        facts = FrameworkFacts()
+        seen: set[str] = set()
+
+        for _pattern, caps in QueryCursor(query).matches(root):
+            class_caps = caps.get("decl")
+            name_caps = caps.get("class")
+            if not (class_caps and name_caps):
+                continue
+            self._extract_controller(
+                class_caps[0], text(name_caps[0], src), src, repo, file, prov, facts, seen
+            )
+        return facts
+
+    def _extract_controller(
+        self,
+        class_node: TSNode,
+        class_name: str,
+        src: bytes,
+        repo: str,
+        file: SourceFile,
+        prov: Provenance,
+        facts: FrameworkFacts,
+        seen: set[str],
+    ) -> None:
+        class_decos = _preceding_decorators(class_node, src)
+        controller = next((d for d in class_decos if d[0] == "Controller"), None)
+        if controller is None:
+            return  # not a controller -> not a route source (ADR-0004)
+        base_path = controller[1]
+
+        body = class_node.child_by_field_name("body")
+        if body is None:
+            return
+        pending: list[tuple[str, str]] = []
+        for member in body.named_children:
+            if member.type == "decorator":
+                pending.append(_decorator_name_and_path(member, src))
+                continue
+            if member.type == "method_definition":
+                name_node = member.child_by_field_name("name")
+                if name_node is not None:
+                    for deco_name, deco_path in pending:
+                        verb = _MAPPING.get(deco_name)
+                        if verb is None:
+                            continue
+                        self._emit_route(
+                            verb,
+                            _join(base_path, deco_path),
+                            class_name,
+                            text(name_node, src),
+                            member,
+                            repo,
+                            file,
+                            prov,
+                            facts,
+                            seen,
+                        )
+            pending = []
+
+    def _emit_route(
+        self,
+        method: str,
+        path: str,
+        class_name: str,
+        method_name: str,
+        member: TSNode,
+        repo: str,
+        file: SourceFile,
+        prov: Provenance,
+        facts: FrameworkFacts,
+        seen: set[str],
+    ) -> None:
+        handler_id = SymbolID.for_symbol(
+            _SLUG, repo, file.path, Descriptor.type(class_name) + Descriptor.method(method_name)
+        )
+        route_id = SymbolID.for_symbol(_SLUG, repo, file.path, f"route({method} {path}).")
+        if route_id in seen:
+            return
+        seen.add(route_id)
+        facts.nodes.append(
+            GraphNode(
+                id=route_id,
+                kind=NodeKind.ROUTE,
+                name=f"{method} {path}",
+                span=(member.start_point[0] + 1, member.end_point[0] + 1),
+                attrs={
+                    "method": method,
+                    "path": path,
+                    "framework": self.name,
+                    "handler": handler_id,
+                },
+                provenance=prov,
+            )
+        )
+        facts.edges.append(
+            Edge(src=route_id, dst=handler_id, kind=EdgeKind.HANDLED_BY, provenance=prov)
+        )
+
+
+NESTJS_PACK = NestJSPack()

agentforge_graph/frameworks/packs/nestjs/routes.scm

@@ -0,0 +1,6 @@
+; NestJS controllers (feat-011). Capture every class; the pack inspects each
+; class's decorators (`@Controller('base')`) and its methods' decorators
+; (`@Get(':id')` …) in code, since TypeScript decorators are preceding siblings
+; of the node they annotate (not children) — so ordered traversal stays precise.
+(class_declaration
+  name: (type_identifier) @class) @decl