agentforge-graph 0.3.2__py3-none-any.whl

agentforge_graph/frameworks/packs/spring/__init__.py

@@ -0,0 +1,267 @@
+"""Spring framework pack (feat-011) — MVC controller routes (Java).
+
+Extracts Spring web endpoints into ``Route`` nodes + ``HANDLED_BY`` edges to the
+handler method. A class is a route source only when it is a controller
+(``@RestController`` / ``@Controller``, or carries a class-level
+``@RequestMapping``) — so a plain Java class never mints routes (ADR-0004). Each
+method annotated with ``@GetMapping`` / ``@PostMapping`` / … (or
+``@RequestMapping(method=RequestMethod.X)``) becomes a ``Route`` whose path is
+the class-level base path joined with the method path, and whose handler is the
+``Class#method`` symbol. Intra-file (annotation + method share a file).
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+from tree_sitter import Language, Parser, Query, QueryCursor
+from tree_sitter import Node as TSNode
+from tree_sitter_language_pack import get_language
+
+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
+
+_HERE = Path(__file__).parent
+# mapping annotation -> HTTP method
+_MAPPING = {
+    "GetMapping": "GET",
+    "PostMapping": "POST",
+    "PutMapping": "PUT",
+    "DeleteMapping": "DELETE",
+    "PatchMapping": "PATCH",
+}
+_CONTROLLER = {"RestController", "Controller"}
+
+
+@cache
+def _language() -> Language:
+    return get_language("java")
+
+
+@cache
+def _query_text() -> str:
+    return (_HERE / "routes.scm").read_text(encoding="utf-8")
+
+
+def _text(node: TSNode, src: bytes) -> str:
+    return src[node.start_byte : node.end_byte].decode("utf-8", errors="replace")
+
+
+def _string(node: TSNode, src: bytes) -> str:
+    s = _text(node, src)
+    if len(s) >= 2 and s[0] in "\"'" and s[-1] == s[0]:
+        return s[1:-1]
+    return s
+
+
+def _annotations(node: TSNode) -> list[TSNode]:
+    """The annotation/marker_annotation nodes on a class or method — directly or
+    inside its ``modifiers`` child."""
+    out: list[TSNode] = []
+    for c in node.named_children:
+        if c.type in ("annotation", "marker_annotation"):
+            out.append(c)
+        elif c.type == "modifiers":
+            out.extend(m for m in c.named_children if m.type in ("annotation", "marker_annotation"))
+    return out
+
+
+def _anno_name(anno: TSNode, src: bytes) -> str:
+    name = anno.child_by_field_name("name")
+    return _text(name, src) if name is not None else ""
+
+
+def _anno_path(anno: TSNode, src: bytes) -> str:
+    """The path string of a mapping annotation: a positional
+    ``@GetMapping("/x")`` or a ``value=``/``path=`` element; "" when absent."""
+    args = anno.child_by_field_name("arguments")
+    if args is None:
+        return ""
+    for arg in args.named_children:
+        if arg.type == "string_literal":
+            return _string(arg, src)
+        if arg.type == "element_value_pair":
+            key = arg.child_by_field_name("key")
+            value = arg.child_by_field_name("value")
+            if (
+                key is not None
+                and _text(key, src) in ("value", "path")
+                and value is not None
+                and value.type == "string_literal"
+            ):
+                return _string(value, src)
+    return ""
+
+
+def _request_method(anno: TSNode, src: bytes) -> str:
+    """The HTTP verb from ``@RequestMapping(method=RequestMethod.X)`` (the tail of
+    the field access), or "ALL" when unspecified (Spring matches any method)."""
+    args = anno.child_by_field_name("arguments")
+    if args is None:
+        return "ALL"
+    for arg in args.named_children:
+        if arg.type != "element_value_pair":
+            continue
+        key = arg.child_by_field_name("key")
+        value = arg.child_by_field_name("value")
+        if key is None or _text(key, src) != "method" or value is None:
+            continue
+        # RequestMethod.PUT -> PUT (the field_access tail)
+        if value.type == "field_access":
+            field = value.child_by_field_name("field")
+            return _text(field, src).upper() if field is not None else "ALL"
+        return _text(value, src).rsplit(".", 1)[-1].upper()
+    return "ALL"
+
+
+def _join(base: str, path: str) -> str:
+    """Join a class base path with a method path into a single ``/``-separated
+    pattern (``/api`` + ``/users`` -> ``/api/users``)."""
+    b = base.rstrip("/")
+    p = path
+    if p and not p.startswith("/"):
+        p = "/" + p
+    return (b + p) or "/"
+
+
+class SpringPack(FrameworkPack):
+    name = "spring"
+    language = "java"
+    language_slug = "java"  # SymbolID slug — must match the Java language pack
+    version = "1"
+    dep_names = ("spring-web", "spring-boot-starter-web", "spring-webmvc")
+    import_markers = ("org.springframework.web", "import org.springframework")
+
+    def extract(self, file: SourceFile, repo: str, commit: str) -> FrameworkFacts:
+        src = file.text.encode("utf-8")
+        lang = _language()
+        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_annos = _annotations(class_node)
+        names = {_anno_name(a, src) for a in class_annos}
+        base_path = ""
+        for a in class_annos:
+            if _anno_name(a, src) == "RequestMapping":
+                base_path = _anno_path(a, src)
+        is_controller = bool(names & _CONTROLLER) or "RequestMapping" in names
+        if not is_controller:
+            return  # not a controller -> not a route source (ADR-0004)
+
+        body = class_node.child_by_field_name("body")
+        if body is None:
+            return
+        for member in body.named_children:
+            if member.type != "method_declaration":
+                continue
+            name_node = member.child_by_field_name("name")
+            if name_node is None:
+                continue
+            for anno in _annotations(member):
+                verb_path = self._mapping_for(anno, src)
+                if verb_path is None:
+                    continue
+                method, method_path = verb_path
+                self._emit_route(
+                    method,
+                    _join(base_path, method_path),
+                    class_name,
+                    _text(name_node, src),
+                    member,
+                    repo,
+                    file,
+                    prov,
+                    facts,
+                    seen,
+                )
+
+    def _mapping_for(self, anno: TSNode, src: bytes) -> tuple[str, str] | None:
+        """``(http_method, path)`` for a mapping annotation, or None when the
+        annotation is not a Spring request mapping."""
+        anno_name = _anno_name(anno, src)
+        if anno_name in _MAPPING:
+            return _MAPPING[anno_name], _anno_path(anno, src)
+        if anno_name == "RequestMapping":
+            return _request_method(anno, src), _anno_path(anno, src)
+        return None
+
+    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(
+            self.language_slug,
+            repo,
+            file.path,
+            Descriptor.type(class_name) + Descriptor.method(method_name),
+        )
+        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=(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)
+        )
+
+
+SPRING_PACK = SpringPack()

agentforge_graph/frameworks/packs/spring/routes.scm

@@ -0,0 +1,6 @@
+; Spring MVC controllers (feat-011). Capture every class; the pack inspects each
+; class's annotations (is it a @RestController/@Controller, what is its base
+; @RequestMapping path?) and its methods' mapping annotations in code, so the
+; path/method derivation and the controller guard stay precise.
+(class_declaration
+  name: (identifier) @class) @decl

agentforge_graph/frameworks/packs/sqlalchemy/__init__.py

@@ -0,0 +1,250 @@
+"""SQLAlchemy framework pack (feat-011) — declarative ORM models.
+
+Extracts declarative model classes into ``DataModel`` nodes + ``HAS_FIELD``
+edges to each mapped column (a ``Variable`` field node carrying its column
+type). A class is treated as a model only when its body carries the static
+evidence SQLAlchemy declarative mapping requires — a ``__tablename__`` string
+or at least one ``Column(...)`` / ``mapped_column(...)`` field — so plain
+classes in a SQLAlchemy app never mint false models (ADR-0004).
+
+Both the classic (``name = Column(Integer)``) and 2.0-style
+(``name: Mapped[int] = mapped_column()``) field forms are recognised. Intra-
+file: model, fields, and `HAS_FIELD` edges all live in the file's
+``FileSubgraph`` and ride feat-004 incrementality. ``relationship("X")`` /
+``ForeignKey("t.c")`` string targets are recorded on the model node in pass-1
+and stitched into cross-file ``RELATES_TO`` edges in pass-2 (``resolve``) — a
+unique-match-only resolution against the whole-repo model set (ADR-0004).
+"""
+
+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,
+    GraphStore,
+    NodeKind,
+    Provenance,
+    SourceFile,
+    SymbolID,
+)
+from agentforge_graph.core import Node as GraphNode
+from agentforge_graph.frameworks.base import FrameworkFacts, FrameworkPack
+from agentforge_graph.frameworks.orm import (
+    ModelIndex,
+    framework_models,
+    relations_to_edges,
+)
+from agentforge_graph.frameworks.packs._python_ast import (
+    callee_name,
+    class_body,
+    first_string_arg,
+    iter_class_assignments,
+    python_language,
+    strip_quotes,
+    text,
+)
+
+_HERE = Path(__file__).parent
+_COLUMN_CALLS = {"Column", "mapped_column"}
+
+
+@cache
+def _query_text() -> str:
+    return (_HERE / "models.scm").read_text(encoding="utf-8")
+
+
+def _positional_type(call: TSNode, src: bytes) -> str:
+    """The column's SQL type from the first positional arg: ``Integer`` for
+    ``Column(Integer)`` / ``Column(String(50))``. Keyword args are skipped."""
+    args = call.child_by_field_name("arguments")
+    if args is None:
+        return ""
+    for arg in args.named_children:
+        if arg.type == "keyword_argument":
+            continue
+        if arg.type == "call":  # String(50) -> String
+            return callee_name(arg, src)
+        if arg.type in ("identifier", "attribute"):
+            return callee_name(arg, src) if arg.type == "attribute" else text(arg, src)
+        return ""
+    return ""
+
+
+def _foreign_key_target(call: TSNode, src: bytes) -> str:
+    """A ``ForeignKey("table.col")`` target nested in a ``Column(...)`` arg list
+    (``author_id = Column(Integer, ForeignKey("users.id"))``), or ""."""
+    args = call.child_by_field_name("arguments")
+    if args is None:
+        return ""
+    for arg in args.named_children:
+        if arg.type == "call" and callee_name(arg, src) == "ForeignKey":
+            return first_string_arg(arg, src)
+    return ""
+
+
+def _mapped_type(assignment: TSNode, src: bytes) -> str:
+    """The inner type of a ``Mapped[X]`` annotation (``int`` for
+    ``id: Mapped[int]``), or "" when there is no such annotation."""
+    type_node = assignment.child_by_field_name("type")
+    if type_node is None:
+        return ""
+    generic = type_node.named_children[0] if type_node.named_children else None
+    if generic is None or generic.type != "generic_type":
+        return ""
+    base = generic.named_children[0] if generic.named_children else None
+    if base is None or text(base, src) != "Mapped":
+        return ""
+    # `Mapped[int]` -> generic_type with a `type_parameter` holding `(type (identifier))`
+    targs = next((c for c in generic.named_children if c.type == "type_parameter"), None)
+    if targs is None or not targs.named_children:
+        return ""
+    inner = targs.named_children[0]
+    leaf = inner.named_children[0] if inner.type == "type" and inner.named_children else inner
+    return text(leaf, src)
+
+
+class SQLAlchemyPack(FrameworkPack):
+    name = "sqlalchemy"
+    language = "python"
+    language_slug = "py"  # SymbolID slug — must match the Python language pack
+    version = "1"
+    dep_names = ("sqlalchemy",)
+    import_markers = ("import sqlalchemy", "from sqlalchemy")
+
+    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()
+
+        for _pattern, caps in QueryCursor(query).matches(root):
+            class_caps = caps.get("model")
+            name_caps = caps.get("name")
+            if not (class_caps and name_caps):
+                continue
+            self._extract_model(
+                class_caps[0], text(name_caps[0], src), src, repo, file, prov, facts
+            )
+        return facts
+
+    def _extract_model(
+        self,
+        class_node: TSNode,
+        class_name: str,
+        src: bytes,
+        repo: str,
+        file: SourceFile,
+        prov: Provenance,
+        facts: FrameworkFacts,
+    ) -> None:
+        body = class_body(class_node)
+        if body is None:
+            return
+
+        table: str | None = None
+        fields: list[tuple[str, str, TSNode]] = []  # (name, column_type, assignment node)
+        # pending RELATES_TO targets resolved cross-file in pass-2 (resolve()):
+        # relationship("Post") -> class name; ForeignKey("users.id") -> table.col
+        relations: list[dict[str, str]] = []
+        for field_name, assign, right in iter_class_assignments(body, src):
+            if field_name == "__tablename__" and right.type == "string":
+                table = strip_quotes(text(right, src))
+                continue
+            if right.type != "call":
+                continue
+            callee = callee_name(right, src)
+            if callee in _COLUMN_CALLS:
+                col_type = _positional_type(right, src) or _mapped_type(assign, src)
+                fields.append((field_name, col_type, assign))
+                fk = _foreign_key_target(right, src)  # Column(.., ForeignKey("t.c"))
+                if fk:
+                    relations.append({"field": field_name, "target": fk, "kind": "fk"})
+            elif callee == "relationship":
+                target = first_string_arg(right, src)
+                if target:
+                    relations.append(
+                        {"field": field_name, "target": target, "kind": "relationship"}
+                    )
+
+        # Conservative: a class is a model only with declarative evidence.
+        if table is None and not fields:
+            return
+
+        model_id = SymbolID.for_symbol(self.language_slug, repo, file.path, f"model({class_name}).")
+        class_id = SymbolID.for_symbol(
+            self.language_slug, repo, file.path, Descriptor.type(class_name)
+        )
+        attrs: dict[str, object] = {
+            "framework": self.name,
+            "class": class_id,
+            "model_class": class_name,  # cross-file RELATES_TO target lookup (pass-2)
+        }
+        if table is not None:
+            attrs["table"] = table
+        if relations:
+            attrs["relations"] = relations
+        facts.nodes.append(
+            GraphNode(
+                id=model_id,
+                kind=NodeKind.DATA_MODEL,
+                name=table or class_name,
+                span=(class_node.start_point[0] + 1, class_node.end_point[0] + 1),
+                attrs=attrs,
+                provenance=prov,
+            )
+        )
+        for field_name, col_type, assign in fields:
+            field_id = SymbolID.for_symbol(
+                self.language_slug,
+                repo,
+                file.path,
+                Descriptor.type(class_name) + Descriptor.term(field_name),
+            )
+            facts.nodes.append(
+                GraphNode(
+                    id=field_id,
+                    kind=NodeKind.VARIABLE,
+                    name=field_name,
+                    span=(assign.start_point[0] + 1, assign.end_point[0] + 1),
+                    attrs={"column_type": col_type, "framework": self.name},
+                    provenance=prov,
+                )
+            )
+            facts.edges.append(
+                Edge(src=model_id, dst=field_id, kind=EdgeKind.HAS_FIELD, provenance=prov)
+            )
+
+    async def resolve(self, store: GraphStore, commit: str = "") -> list[Edge]:
+        """Pass-2: stitch the ``relationship``/``ForeignKey`` string targets
+        recorded in pass-1 into ``RELATES_TO`` edges. A ``relationship("Post")``
+        resolves to the model whose class is ``Post``; a ``ForeignKey("users.id")``
+        to the model whose table is ``users``. Ambiguous class names (same name
+        in two files) are left unresolved (ADR-0004 — never guess)."""
+        models = await framework_models(store, self.name)
+        index = ModelIndex(models)
+        prov = Provenance.resolved(f"pack:{self.name}@{self.version}", commit)
+        return relations_to_edges(models, index, _resolve_target, prov)
+
+
+def _resolve_target(rel: dict[str, str], index: ModelIndex) -> str | None:
+    """Resolve one SQLAlchemy relation to a target model id (unique match only)."""
+    target = str(rel.get("target", ""))
+    if not target:
+        return None
+    if rel.get("kind") == "fk":
+        # "users.id" / "schema.users.id" -> the table segment (second-to-last)
+        parts = target.split(".")
+        return index.unique_table(parts[-2] if len(parts) >= 2 else parts[0])
+    # relationship("Post") / "module.Post" -> bare class name
+    return index.unique_class(target.rsplit(".", 1)[-1])
+
+
+SQLALCHEMY_PACK = SQLAlchemyPack()

agentforge_graph/frameworks/packs/sqlalchemy/models.scm

@@ -0,0 +1,7 @@
+; SQLAlchemy declarative models (feat-011). Capture every class; the pack then
+; inspects each class body in code to decide whether it is a DataModel (has a
+; ``__tablename__`` or ``Column(...)``/``mapped_column(...)`` fields). Body
+; analysis is done in Python rather than the query so direct-child scoping
+; (class-level fields only, never nested locals) stays precise.
+(class_definition
+  name: (identifier) @name) @model

agentforge_graph/frameworks/registry.py

@@ -0,0 +1,44 @@
+"""Framework-pack registry (feat-011). Mirrors the language ``PackRegistry``:
+a flat list of built-in packs, resolvable by name or by the language they ride.
+Third-party packs register out-of-tree via an entry point later."""
+
+from __future__ import annotations
+
+from .base import FrameworkPack
+from .packs.django import DJANGO_PACK
+from .packs.express import EXPRESS_PACK
+from .packs.fastapi import FASTAPI_PACK
+from .packs.flask import FLASK_PACK
+from .packs.nestjs import NESTJS_PACK
+from .packs.spring import SPRING_PACK
+from .packs.sqlalchemy import SQLALCHEMY_PACK
+
+BUILTIN_FRAMEWORK_PACKS: list[FrameworkPack] = [
+    FASTAPI_PACK,
+    SQLALCHEMY_PACK,
+    DJANGO_PACK,
+    FLASK_PACK,
+    EXPRESS_PACK,
+    SPRING_PACK,
+    NESTJS_PACK,
+]
+
+
+class FrameworkRegistry:
+    def __init__(self, packs: list[FrameworkPack]) -> None:
+        self._packs = list(packs)
+        self._by_name = {p.name: p for p in packs}
+
+    @property
+    def packs(self) -> list[FrameworkPack]:
+        return list(self._packs)
+
+    def by_name(self, name: str) -> FrameworkPack | None:
+        return self._by_name.get(name)
+
+    def for_language(self, language: str) -> list[FrameworkPack]:
+        return [p for p in self._packs if p.language == language]
+
+
+def builtin_framework_registry() -> FrameworkRegistry:
+    return FrameworkRegistry(BUILTIN_FRAMEWORK_PACKS)

agentforge_graph/ingest/__init__.py

@@ -0,0 +1,30 @@
+"""agentforge_graph.ingest — the tree-sitter ingestion pipeline (feat-002).
+
+Parses a repo with tree-sitter (no build config — ADR-0002) into the
+feat-001 graph and writes it through the feat-003 store. Two passes:
+file-isolated *extract* then graph-only *resolve*. Imports nothing from
+``agentforge`` (ADR-0001).
+"""
+
+from __future__ import annotations
+
+from .codegraph import CodeGraph
+from .extractor import TreeSitterExtractor
+from .pack import DescriptorRules, LanguagePack, PackRegistry
+from .pipeline import IngestPipeline
+from .report import IndexReport, ResolveStats
+from .resolver import ImportResolver
+from .source import RepoSource
+
+__all__ = [
+    "CodeGraph",
+    "RepoSource",
+    "LanguagePack",
+    "DescriptorRules",
+    "PackRegistry",
+    "TreeSitterExtractor",
+    "ImportResolver",
+    "IngestPipeline",
+    "IndexReport",
+    "ResolveStats",
+]