agentforge-graph 0.3.2__py3-none-any.whl

agentforge_graph/frameworks/packs/_js_ast.py

@@ -0,0 +1,56 @@
+"""Shared tree-sitter helpers for JS/TS framework packs (feat-011).
+
+Framework-agnostic primitives over the JavaScript and TypeScript grammars (which
+share the node types these touch). Used by the Express pack and any future JS/TS
+pack (NestJS). Zero ``agentforge`` imports beyond tree-sitter.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+
+from tree_sitter import Language
+from tree_sitter import Node as TSNode
+from tree_sitter_language_pack import get_language
+
+# SymbolID slug -> tree-sitter grammar name.
+_GRAMMAR = {"js": "javascript", "ts": "typescript"}
+
+
+@cache
+def js_language(slug: str) -> Language:
+    """The tree-sitter ``Language`` for a JS/TS SymbolID slug (``js``/``ts``)."""
+    return get_language(_GRAMMAR[slug])
+
+
+def text(node: TSNode, src: bytes) -> str:
+    return src[node.start_byte : node.end_byte].decode("utf-8", errors="replace")
+
+
+def strip_quotes(s: str) -> str:
+    if len(s) >= 2 and s[0] in "\"'`" and s[-1] == s[0]:
+        return s[1:-1]
+    return s
+
+
+def string_value(node: TSNode, src: bytes) -> str | None:
+    """The literal value of a ``string`` node (quotes stripped), or None when the
+    node is not a plain string literal."""
+    if node.type != "string":
+        return None
+    return strip_quotes(text(node, src))
+
+
+def first_arg_string(args: TSNode, src: bytes) -> str | None:
+    """The first argument's string-literal value, or None when it is missing or
+    non-literal (a computed/templated path)."""
+    if not args.named_children:
+        return None
+    return string_value(args.named_children[0], src)
+
+
+def last_named_arg(args: TSNode) -> TSNode | None:
+    """The last argument node — Express's route handler (a function reference or
+    an inline function), after any middleware arguments."""
+    kids = args.named_children
+    return kids[-1] if kids else None

agentforge_graph/frameworks/packs/_python_ast.py

@@ -0,0 +1,157 @@
+"""Shared tree-sitter helpers for Python framework packs (feat-011).
+
+Framework-agnostic primitives over the Python grammar — used by the SQLAlchemy
+and Django ORM packs (and any future Python pack: Flask, FastAPI class views).
+Zero ``agentforge`` imports beyond tree-sitter; no framework semantics here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from functools import cache
+
+from tree_sitter import Language
+from tree_sitter import Node as TSNode
+from tree_sitter_language_pack import get_language
+
+from agentforge_graph.core import Descriptor
+
+
+@cache
+def python_language() -> Language:
+    return get_language("python")
+
+
+def text(node: TSNode, src: bytes) -> str:
+    return src[node.start_byte : node.end_byte].decode("utf-8", errors="replace")
+
+
+def strip_quotes(s: str) -> str:
+    if len(s) >= 2 and s[0] in "\"'" and s[-1] == s[0]:
+        return s[1:-1]
+    return s
+
+
+def callee_name(call: TSNode, src: bytes) -> str:
+    """Last segment of a call's function name: ``Column`` for both ``Column(...)``
+    and ``sa.Column(...)`` / ``models.ForeignKey(...)``."""
+    fn = call.child_by_field_name("function")
+    if fn is None:
+        return ""
+    if fn.type == "attribute":
+        attr = fn.child_by_field_name("attribute")
+        return text(attr, src) if attr is not None else ""
+    return text(fn, src)
+
+
+def class_body(class_node: TSNode) -> TSNode | None:
+    return class_node.child_by_field_name("body")
+
+
+def dotted_tail(node: TSNode, src: bytes) -> str:
+    """Last segment of an identifier or attribute node — ``Model`` for both
+    ``Model`` and ``models.Model`` / ``db.models.Model``; ``User`` for
+    ``myapp.User``. "" for anything else."""
+    if node.type == "attribute":
+        attr = node.child_by_field_name("attribute")
+        return text(attr, src) if attr is not None else ""
+    if node.type == "identifier":
+        return text(node, src)
+    return ""
+
+
+def base_classes(class_node: TSNode, src: bytes) -> list[str]:
+    """The dotted-tail names of a class's base classes: ``["Model"]`` for
+    ``class User(models.Model)``, ``["TimestampedModel"]`` for a subclass."""
+    supers = class_node.child_by_field_name("superclasses")
+    if supers is None:
+        return []
+    return [t for c in supers.named_children if (t := dotted_tail(c, src))]
+
+
+def iter_class_assignments(body: TSNode, src: bytes) -> Iterator[tuple[str, TSNode, TSNode]]:
+    """Yield ``(lhs_name, assignment_node, rhs_node)`` for each class-level
+    ``name = <expr>``. The block may hold the assignment directly or wrapped in
+    an ``expression_statement``; non-identifier LHS is skipped."""
+    for stmt in body.named_children:
+        if stmt.type == "assignment":
+            assign = stmt
+        elif stmt.type == "expression_statement" and stmt.named_children:
+            assign = stmt.named_children[0]
+            if assign.type != "assignment":
+                continue
+        else:
+            continue
+        left = assign.child_by_field_name("left")
+        right = assign.child_by_field_name("right")
+        if left is None or left.type != "identifier" or right is None:
+            continue
+        yield text(left, src), assign, right
+
+
+def first_string_arg(call: TSNode, src: bytes) -> str:
+    """The first string-literal positional arg, stripped (``"Post"`` in
+    ``relationship("Post")``); "" when there is no string positional."""
+    args = call.child_by_field_name("arguments")
+    if args is None:
+        return ""
+    for arg in args.named_children:
+        if arg.type == "string":
+            return strip_quotes(text(arg, src))
+    return ""
+
+
+def enclosing_class(node: TSNode, src: bytes) -> str | None:
+    """The name of the nearest enclosing ``class_definition``, or None for a
+    module-level definition — lets a class-based handler/consumer resolve to its
+    ``Class#method`` symbol."""
+    anc = node.parent
+    while anc is not None:
+        if anc.type == "class_definition":
+            name = anc.child_by_field_name("name")
+            return text(name, src) if name is not None else None
+        anc = anc.parent
+    return None
+
+
+def member_descriptor(name: str, enclosing: str | None) -> str:
+    """``Class#method().`` for a method, ``method().`` for a free function."""
+    if enclosing is not None:
+        return Descriptor.type(enclosing) + Descriptor.method(name)
+    return Descriptor.method(name)
+
+
+def first_string_in(args: TSNode, src: bytes) -> str | None:
+    """The first string-literal positional arg (a route path), or None when the
+    arg is dynamic/non-literal."""
+    for child in args.named_children:
+        if child.type == "string":
+            return strip_quotes(text(child, src))
+    return None
+
+
+def string_list_kwarg(args: TSNode, name: str, src: bytes) -> list[str]:
+    """The string elements of a ``name=[...]`` keyword argument (e.g. Flask's
+    ``methods=["GET", "POST"]``), in order; [] when absent or non-literal."""
+    for arg in args.named_children:
+        if arg.type != "keyword_argument":
+            continue
+        key = arg.child_by_field_name("name")
+        value = arg.child_by_field_name("value")
+        if key is None or text(key, src) != name or value is None or value.type != "list":
+            continue
+        return [strip_quotes(text(e, src)) for e in value.named_children if e.type == "string"]
+    return []
+
+
+def first_positional_arg(call: TSNode, src: bytes) -> TSNode | None:
+    """The first non-keyword argument node, or None — the target in
+    ``ForeignKey(User)`` / ``ForeignKey("app.User")`` / ``CharField(...)``."""
+    args = call.child_by_field_name("arguments")
+    if args is None:
+        return None
+    for arg in args.named_children:
+        if arg.type == "keyword_argument":
+            continue
+        return arg
+    return None

agentforge_graph/frameworks/packs/django/__init__.py

@@ -0,0 +1,240 @@
+"""Django framework pack (feat-011) — ORM models.
+
+Extracts Django model classes into ``DataModel`` nodes + ``HAS_FIELD`` edges to
+each mapped field (a ``Variable`` carrying its field type, e.g. ``CharField``).
+A class is treated as a model only with declarative evidence — a base whose
+tail is ``Model`` (``class X(models.Model)``) or at least one ``models.*Field``
+assignment (which also catches abstract-base subclasses) — so plain classes in
+a Django app never mint false models (ADR-0004).
+
+``ForeignKey`` / ``OneToOneField`` / ``ManyToManyField`` targets (a model class,
+a ``"app.Model"`` string, or ``"self"``) are recorded in pass-1 and stitched
+into cross-file ``RELATES_TO`` edges in pass-2 against the whole-repo model set
+(unique-match-only). FK/O2O are also a ``HAS_FIELD`` column; M2M is relation-
+only. The table name comes from ``class Meta: db_table`` when set (Django's
+``app_label``-derived default is not known statically).
+"""
+
+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 (
+    base_classes,
+    callee_name,
+    class_body,
+    dotted_tail,
+    first_positional_arg,
+    iter_class_assignments,
+    python_language,
+    strip_quotes,
+    text,
+)
+
+_HERE = Path(__file__).parent
+# relation field types -> RELATES_TO kind; FK/O2O also produce a column. Note
+# `ForeignKey` does NOT end in `Field`, so relation calls are matched by name.
+_RELATION_FIELDS = {"ForeignKey": "fk", "OneToOneField": "o2o", "ManyToManyField": "m2m"}
+
+
+@cache
+def _query_text() -> str:
+    return (_HERE / "models.scm").read_text(encoding="utf-8")
+
+
+def _is_field_call(callee: str) -> bool:
+    """A Django model field: any ``*Field`` class plus the relation classes
+    (``ForeignKey`` ends in ``Key``, not ``Field``)."""
+    return callee.endswith("Field") or callee in _RELATION_FIELDS
+
+
+def _is_models_namespaced_field(call: TSNode, src: bytes) -> bool:
+    """True for ``models.CharField(...)`` / ``models.ForeignKey(...)`` — a field
+    call whose receiver tail is ``models``. The namespace check keeps a non-Django
+    ``SomeField()`` from looking like model evidence."""
+    if not _is_field_call(callee_name(call, src)):
+        return False
+    fn = call.child_by_field_name("function")
+    if fn is None or fn.type != "attribute":
+        return False
+    obj = fn.child_by_field_name("object")
+    return obj is not None and dotted_tail(obj, src) == "models"
+
+
+def _relation_target(call: TSNode, src: bytes, self_name: str) -> str:
+    """The related model name from a relation field's first positional arg:
+    ``User`` for ``ForeignKey(User)`` / ``ForeignKey("app.User")``; the class's
+    own name for ``"self"``; "" when non-literal/absent."""
+    arg = first_positional_arg(call, src)
+    if arg is None:
+        return ""
+    if arg.type == "string":
+        target = strip_quotes(text(arg, src)).rsplit(".", 1)[-1]
+        return self_name if target == "self" else target
+    return dotted_tail(arg, src)
+
+
+def _meta_db_table(body: TSNode, src: bytes) -> str | None:
+    """``db_table`` from an inner ``class Meta``, or None."""
+    for stmt in body.named_children:
+        if stmt.type != "class_definition":
+            continue
+        name = stmt.child_by_field_name("name")
+        if name is None or text(name, src) != "Meta":
+            continue
+        meta_body = class_body(stmt)
+        if meta_body is None:
+            continue
+        for fname, _assign, right in iter_class_assignments(meta_body, src):
+            if fname == "db_table" and right.type == "string":
+                return strip_quotes(text(right, src))
+    return None
+
+
+class DjangoPack(FrameworkPack):
+    name = "django"
+    language = "python"
+    language_slug = "py"  # SymbolID slug — must match the Python language pack
+    version = "1"
+    dep_names = ("django",)
+    import_markers = ("import django", "from django")
+
+    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
+
+        has_model_base = any(b == "Model" for b in base_classes(class_node, src))
+        fields: list[tuple[str, str, TSNode]] = []  # (name, field_type, assignment node)
+        relations: list[dict[str, str]] = []
+        has_models_field = False
+        for field_name, assign, right in iter_class_assignments(body, src):
+            if right.type != "call":
+                continue
+            callee = callee_name(right, src)
+            if not _is_field_call(callee):
+                continue
+            if _is_models_namespaced_field(right, src):
+                has_models_field = True
+            kind = _RELATION_FIELDS.get(callee)
+            if kind is not None:
+                target = _relation_target(right, src, class_name)
+                if target:
+                    relations.append({"field": field_name, "target": target, "kind": kind})
+                if kind != "m2m":  # FK/O2O carry a real column; M2M does not
+                    fields.append((field_name, callee, assign))
+            else:
+                fields.append((field_name, callee, assign))
+
+        # Conservative: a class is a model only with declarative evidence.
+        if not (has_model_base or has_models_field):
+            return
+
+        table = _meta_db_table(body, src)
+        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, field_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": field_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 ``ForeignKey``/``OneToOneField``/``ManyToManyField``
+        targets into ``RELATES_TO`` edges. Django targets are model class names,
+        so every relation resolves via the class index (unique match only)."""
+        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 Django relation to a target model id (unique class match)."""
+    return index.unique_class(str(rel.get("target", "")).rsplit(".", 1)[-1])
+
+
+DJANGO_PACK = DjangoPack()

agentforge_graph/frameworks/packs/django/models.scm

@@ -0,0 +1,7 @@
+; Django models (feat-011). Capture every class; the pack inspects each class
+; in code to decide whether it is a Django model — a base whose tail is `Model`
+; (``class X(models.Model)``) or a ``models.*Field`` body assignment — so a
+; plain class in a Django app never mints a false model. Body analysis is done
+; in Python so direct-child scoping (class-level fields only) stays precise.
+(class_definition
+  name: (identifier) @name) @model

agentforge_graph/frameworks/packs/express/__init__.py

@@ -0,0 +1,133 @@
+"""Express framework pack (feat-011) — routes (JavaScript + TypeScript).
+
+Extracts `app.get('/x', handler)` / `router.post('/x', mw, handler)` calls into
+``Route`` nodes. The handler is the call's last argument: a **named** function
+reference resolves to its symbol → a ``HANDLED_BY`` edge; an **anonymous** inline
+handler (`(req, res) => {}`) still yields the ``Route`` (the API surface) but no
+edge (recorded in ``attrs.handler = ""``). A non-route call (`app.use`,
+`app.listen`) or a dynamic (non-literal) path is skipped/counted, never dropped.
+
+The pack spans both sibling languages: it extracts over ``.js`` and ``.ts`` and
+builds handler symbol ids with the *file's* slug (so a `.ts` handler resolves to
+its TS symbol). Intra-file (the route call and a named handler defined in the
+same file); cross-file handler imports and `app.use('/p', router)` prefix
+mounting are follow-ups.
+"""
+
+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 (
+    first_arg_string,
+    js_language,
+    last_named_arg,
+    text,
+)
+
+_HERE = Path(__file__).parent
+_HTTP_METHODS = {"get", "post", "put", "delete", "patch", "head", "options", "all"}
+
+
+@cache
+def _query_text() -> str:
+    return (_HERE / "routes.scm").read_text(encoding="utf-8")
+
+
+class ExpressPack(FrameworkPack):
+    name = "express"
+    language = "javascript/typescript"
+    language_slug = "js"  # primary; `slugs` spans js+ts and extract uses file.language
+    version = "1"
+    dep_names = ("express",)
+    import_markers = (
+        "require('express')",
+        'require("express")',
+        "from 'express'",
+        'from "express"',
+    )
+
+    @property
+    def slugs(self) -> tuple[str, ...]:
+        return ("js", "ts")
+
+    def extract(self, file: SourceFile, repo: str, commit: str) -> FrameworkFacts:
+        slug = file.language  # "js" or "ts" — the file's own slug
+        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):
+            method_caps = caps.get("method")
+            args_caps = caps.get("args")
+            route_caps = caps.get("call")
+            if not (method_caps and args_caps and route_caps):
+                continue
+            method = text(method_caps[0], src).lower()
+            if method not in _HTTP_METHODS:
+                continue  # app.use / app.listen / a non-router method call
+
+            path = first_arg_string(args_caps[0], src)
+            if path is None:
+                facts.unresolved += 1  # dynamic / non-literal path
+                continue
+
+            handler_id = self._handler_id(args_caps[0], slug, repo, file, src)
+            method_u = "ALL" if method == "all" else method.upper()
+            route_id = SymbolID.for_symbol(slug, repo, file.path, f"route({method_u} {path}).")
+            if route_id in seen:
+                continue
+            seen.add(route_id)
+            route_node = route_caps[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 or "",
+                    },
+                    provenance=prov,
+                )
+            )
+            if handler_id is not None:
+                facts.edges.append(
+                    Edge(src=route_id, dst=handler_id, kind=EdgeKind.HANDLED_BY, provenance=prov)
+                )
+        return facts
+
+    def _handler_id(
+        self, args: TSNode, slug: str, repo: str, file: SourceFile, src: bytes
+    ) -> str | None:
+        """The symbol id of a named handler reference (the last argument), or None
+        for an anonymous inline handler (no symbol to point at)."""
+        handler = last_named_arg(args)
+        if handler is None or handler.type != "identifier":
+            return None
+        return SymbolID.for_symbol(slug, repo, file.path, Descriptor.method(text(handler, src)))
+
+
+EXPRESS_PACK = ExpressPack()

agentforge_graph/frameworks/packs/express/routes.scm

@@ -0,0 +1,8 @@
+; Express route registrations (feat-011): `app.get('/x', handler)` /
+; `router.post('/x', mw, handler)`. The method (get/post/…) and a string path
+; are validated in code so non-route calls (`app.use`, `app.listen`) and dynamic
+; paths are handled, not silently missed. Shared verbatim by the JS and TS
+; grammars (same node types).
+(call_expression
+  function: (member_expression object: (_) @obj property: (property_identifier) @method)
+  arguments: (arguments) @args) @call