devlensio 0.6.2 → 1.0.1

package/extractors/python/devlens_extractors_python/edges/calls.py

@@ -0,0 +1,112 @@
+"""CALLS edge resolution — resolves metadata.calls names to node ids.
+
+Consumes the shared LookupMaps (lookup.py). Resolution ladder:
+  self./cls.        → same-class method (exact dotted name)
+  ClassName.method  → same-file dotted lookup
+  alias.member      → lazy [pip]/pkg::member node
+  module-alias.walk → submodule walk via module_map
+  plain name        → global nodes_by_name → import alias refinement
+Unknown/builtin names resolve to nothing (no edge) — metadata.calls keeps
+them for LLM context.
+"""
+from __future__ import annotations
+
+from ..lookup import LookupMaps, closest_by_path, module_name
+from ..third_party import ThirdPartyRegistry
+
+
+def _find_in_file(lookup: LookupMaps, rel: str, name: str) -> str | None:
+    return lookup.nodes_by_file.get(rel, {}).get(name)
+
+
+def _walk_module(lookup: LookupMaps, alias_target: str, rest: str) -> str | None:
+    """'user.User' with alias → file::models/__init__.py: consume submodule
+    segments via module_map, then look up the symbol in the final file."""
+    current_rel = alias_target[len("file::"):]
+    current_module = module_name(current_rel)
+    segments = rest.split(".")
+    consumed = 0
+
+    while consumed < len(segments):
+        candidate = f"{current_module}.{segments[consumed]}"
+        nxt = lookup.module_map.get(candidate)
+        if not nxt:
+            break
+        current_rel, current_module = nxt, candidate
+        consumed += 1
+
+    return _find_in_file(lookup, current_rel, ".".join(segments[consumed:]))
+
+
+def _resolve(called: str, node: dict, lookup: LookupMaps,
+             registry: ThirdPartyRegistry) -> str | None:
+    rel = node["filePath"]
+    symbols = lookup.symbol_maps.get(rel, {})
+
+    # ── 1. self.x() / cls.x() → method of the enclosing class ──
+    if called.startswith(("self.", "cls.")):
+        parent_class = node["metadata"].get("parentClass")
+        if parent_class:
+            return _find_in_file(lookup, rel,
+                                 f"{parent_class}.{called.split('.', 1)[1]}")
+        return None
+
+    # ── 2. dotted name ──
+    if "." in called:
+        root, rest = called.split(".", 1)
+
+        # 2a. ClassName.method defined in the same file
+        if root in lookup.nodes_by_file.get(rel, {}):
+            return _find_in_file(lookup, rel, called)
+
+        # 2b. member access through an import alias
+        alias_target = symbols.get(root)
+        if not alias_target:
+            return None
+        if alias_target.startswith("[pip]/"):
+            # third-party chain: requests.get → lazily create [pip]/requests::get
+            pkg = alias_target.split("/", 1)[1]
+            if "::" in pkg:
+                # chain root is already a named import — current_app.logger.info
+                # → [pip]/flask::current_app (the meaningful hop)
+                return alias_target
+            member = registry.method_node(pkg, rest.split(".")[0])
+            return member["id"] if member else None
+        if alias_target.startswith("file::"):
+            return _walk_module(lookup, alias_target, rest)
+        return None
+
+    # ── 3. plain name — global lookup, closest-by-path on collision ──
+    candidates = lookup.nodes_by_name.get(called)
+    if candidates:
+        if len(candidates) == 1:
+            return candidates[0][0]
+        return closest_by_path(candidates, rel)
+
+    # ── 4. import alias — refine file targets to the actual symbol ──
+    alias_target = symbols.get(called)
+    if alias_target:
+        if alias_target.startswith("file::"):
+            return _find_in_file(lookup, alias_target[len("file::"):], called)
+        return alias_target   # "[pip]/..." or "path.py::Symbol"
+    return None
+
+
+def resolve_calls(lookup: LookupMaps, registry: ThirdPartyRegistry) -> list[dict]:
+    """Resolve every FUNCTION/METHOD node's calls → CALLS edges.
+    Also writes metadata.resolvedCalls back onto nodes (JS callEdges.ts mirror)."""
+    edges: list[dict] = []
+
+    for node in lookup.node_by_id.values():
+        if node["type"] not in ("FUNCTION", "METHOD"):
+            continue
+        resolved: list[dict] = []
+        for called in node["metadata"].get("calls", []):
+            target = _resolve(called, node, lookup, registry)
+            if target and target != node["id"]:
+                edges.append({"from": node["id"], "to": target, "type": "CALLS",
+                              "metadata": {"calledName": called}})
+                resolved.append({"name": called, "nodeId": target})
+        node["metadata"]["resolvedCalls"] = resolved
+
+    return edges

package/extractors/python/devlens_extractors_python/edges/enrich.py

@@ -0,0 +1,44 @@
+"""Metadata enrichment — pydantic isSchema + celery isTask (Step 9).
+
+Resolves parse-time facts (metadata.bases, metadata.decorators) via symbol
+maps. No AST re-walks. IMPORTANT: each marker set needs its OWN memo dict —
+a cached 'miss' from the model scan must not short-circuit the schema scan.
+"""
+from __future__ import annotations
+
+from ..lookup import LookupMaps
+from .orm_edges import _base_chain_hit
+
+
+def _is_celery_task(decorators: list[str], lookup: LookupMaps, rel: str) -> bool:
+    """@shared_task (celery's own name) · @app.task / @celery_app.task
+    (Celery instance pattern) · bare @task (requires celery import proof)."""
+    symbols = lookup.symbol_maps.get(rel, {})
+    for dec in decorators:
+        root = dec.split("(")[0].strip()   # strip args: "app.task()" → "app.task"
+        parts = root.split(".")
+        if not parts:
+            continue
+        if parts[-1] == "shared_task":
+            return True                    # celery-specific decorator name
+        if parts[-1] == "task" and len(parts) >= 2:
+            return True                    # @app.task — Celery instance pattern
+        if parts[-1] == "task" and "celery" in symbols.get("task", ""):
+            return True                    # bare @task, imported from celery
+    return False
+
+
+def enrich_metadata(lookup: LookupMaps) -> None:
+    """Mark pydantic schemas (CLASS nodes) and celery tasks (FUNCTION/METHOD).
+
+    Pure metadata mutation — no new nodes or edges."""
+    memo: dict[str, str | None] = {}       # own memo — marker-set isolation
+
+    for node in lookup.node_by_id.values():
+        if node["type"] == "CLASS":
+            if _base_chain_hit(node, lookup, memo, ("pydantic", "sqlmodel")):
+                node["metadata"]["isSchema"] = True
+        if node["type"] in ("FUNCTION", "METHOD") \
+                and _is_celery_task(node["metadata"].get("decorators", []),
+                                    lookup, node["filePath"]):
+            node["metadata"]["isTask"] = True

package/extractors/python/devlens_extractors_python/edges/imports.py

@@ -0,0 +1,155 @@
+"""Import resolution — the sys.path simulation.
+
+Resolves every import to a local file (IMPORTS edge) or a third-party
+package node ([pip]/...). Also writes the per-file symbol map
+(local name → target node id) into lookup.symbol_maps, which CALLS
+resolution and route detection consume.
+"""
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+from ..lookup import LookupMaps
+from ..parser import ParsedFile
+from ..third_party import STDLIB_MODULES, ThirdPartyRegistry
+
+
+@dataclass
+class ImportItem:
+    module: str | None     # dotted module as written ("models.user", None for bare relative)
+    name: str | None       # imported name for from-imports (None for `import x`)
+    alias: str             # local binding ("User", "as_name", or top package for `import a.b`)
+    level: int             # 0 = absolute, 1 = ".", 2 = ".."
+    is_star: bool
+
+
+def extract_imports(tree: ast.Module) -> list[ImportItem]:
+    items: list[ImportItem] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                items.append(ImportItem(
+                    module=alias.name, name=None,
+                    alias=alias.asname or alias.name.split(".")[0],
+                    level=0, is_star=False))
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                items.append(ImportItem(
+                    module=node.module, name=None if alias.name == "*" else alias.name,
+                    alias=alias.asname or alias.name,
+                    level=node.level, is_star=alias.name == "*"))
+    return items
+
+
+def build_module_map(rel_paths: list[str]) -> dict[str, str]:
+    """dotted module name → relative file path.
+
+    'models/user.py' → 'models.user' · 'models/__init__.py' → 'models'
+    src/ layout: 'src/models/user.py' also registers as 'models.user'.
+    First registration wins (deterministic)."""
+    module_map: dict[str, str] = {}
+
+    def register(rel: str) -> None:
+        parts = rel.split("/")
+        if parts[-1] == "__init__.py":
+            module = ".".join(parts[:-1])
+        else:
+            module = ".".join(parts[:-1] + [parts[-1][:-3]])
+        module_map.setdefault(module, rel)
+
+    for rel in rel_paths:
+        register(rel)
+        if rel.startswith("src/"):
+            register(rel[4:])
+
+    return module_map
+
+
+def _current_package(rel_path: str) -> str:
+    """Dotted package of a file: 'models/sub/views.py' → 'models.sub'."""
+    return ".".join(rel_path.split("/")[:-1])
+
+
+def resolve_file_imports(parsed: ParsedFile, lookup: LookupMaps,
+                         registry: ThirdPartyRegistry) -> tuple[list[dict], list[str]]:
+    """Resolve one file's imports.
+
+    Returns (edges, imported_local_paths). Writes into lookup.symbol_maps
+    (local alias → target node id), used by CALLS + route resolution.
+    """
+    rel = parsed.rel_path
+    file_id = parsed.file_node["id"]
+    file_symbols: dict[str, str] = {}
+    edges: list[dict] = []
+    imported_paths: list[str] = []
+    module_map = lookup.module_map
+    symbol_map = lookup.symbol_maps
+
+    for item in extract_imports(parsed.tree):
+        # ── 1. Expand relative imports to an absolute module name ──
+        if item.level == 0:
+            module = item.module or ""
+        else:
+            base_parts = _current_package(rel).split(".")
+            base_parts = base_parts[: max(0, len(base_parts) - (item.level - 1))]
+            base = ".".join(base_parts)
+            module = f"{base}.{item.module}" if item.module else base
+
+        # `from . import x` — x may be a submodule (base.x) or a symbol in base
+        if item.name and item.module is None:
+            sub = module_map.get(f"{module}.{item.name}")
+            if sub:
+                file_symbols[item.alias] = f"file::{sub}"
+                imported_paths.append(sub)
+                edges.append({"from": file_id, "to": f"file::{sub}", "type": "IMPORTS",
+                              "metadata": {"importPath": module, "importedName": item.name}})
+                continue
+
+        # ── 2. Try to resolve inside the repo ──
+        target_rel = module_map.get(module)
+        if target_rel:
+            target_file_id = f"file::{target_rel}"
+            imported_paths.append(target_rel)
+
+            if item.is_star:
+                # Can't know which names — edge to the module file, tag ambiguous
+                edges.append({"from": file_id, "to": target_file_id, "type": "IMPORTS",
+                              "metadata": {"importPath": module, "isStarImport": True}})
+                continue
+
+            if item.name:
+                # from X import Y — Y may be a submodule (X/Y.py) or a symbol in X
+                sub = module_map.get(f"{module}.{item.name}")
+                if sub:
+                    target_file_id = f"file::{sub}"
+                    imported_paths.append(sub)
+
+            file_symbols[item.alias] = target_file_id
+            edges.append({"from": file_id, "to": target_file_id, "type": "IMPORTS",
+                          "metadata": {"importPath": module,
+                                       "importedName": item.name}})
+            continue
+
+        # ── 3. Not local → stdlib (skip) or third-party (node) ──
+        if item.level > 0:
+            continue  # relative import that failed locally — skip silently
+
+        pkg = module.split(".")[0]
+        if not module or pkg in STDLIB_MODULES:
+            continue  # stdlib / builtin — noise, no edge, no node
+
+        if item.name and not item.is_star:
+            target = registry.method_node(pkg, item.name)
+        else:
+            target = registry.package_node(pkg)
+        if target is None:
+            continue  # third-party not permitted (options.includedThirdPartyLibs)
+
+        file_symbols[item.alias] = target["id"]
+        edges.append({"from": file_id, "to": target["id"], "type": "IMPORTS",
+                      "metadata": {"importPath": pkg, "isThirdParty": True,
+                                   "importedName": item.name}})
+
+    symbol_map[rel] = file_symbols
+    return edges, sorted(set(imported_paths))

package/extractors/python/devlens_extractors_python/edges/inheritance.py

@@ -0,0 +1,97 @@
+"""Inheritance edges — EXTENDS / IMPLEMENTS (class → base).
+
+Python's interface mechanism is ABC/Protocol inheritance, so:
+  - base resolves to a CONCRETE class (or permitted [pip] node) → EXTENDS
+  - base resolves to an ABSTRACT class (chain hits ABC/Protocol/ABCMeta)
+    → IMPLEMENTS
+Bases that resolve to nothing (stdlib, unresolved imports) get no edge —
+an edge must always point at a real node (never dangling).
+
+Engine note: CodeEdgeType already defines EXTENDS + IMPLEMENTS ("NEW
+LANGUAGES") — Python is the first extractor to emit them.
+"""
+from __future__ import annotations
+
+from ..lookup import LookupMaps
+
+ABSTRACT_MARKERS = {"ABC", "ABCMeta", "Protocol", "RuntimeProtocol"}
+
+
+def _is_abstract(node: dict, lookup: LookupMaps, memo: dict,
+                 depth: int = 0) -> bool:
+    """Class inherits (transitively) from ABC/Protocol/ABCMeta."""
+    if depth > 4:
+        return False
+    node_id = node["id"]
+    if node_id in memo:
+        return memo[node_id]
+
+    rel = node["filePath"]
+    symbols = lookup.symbol_maps.get(rel, {})
+    abstract = False
+
+    for base in node["metadata"].get("bases", []):
+        parts = base.split(".")
+        root = parts[-1]
+        if root in ABSTRACT_MARKERS:
+            abstract = True
+            break
+        alias = symbols.get(parts[0], "")
+        target = None
+        if alias.startswith("file::"):
+            target = lookup.nodes_by_file.get(alias[len("file::"):], {}).get(root)
+        if not target:
+            target = lookup.nodes_by_file.get(rel, {}).get(root)
+        if target:
+            child = lookup.node_by_id.get(target)
+            if child and child["type"] == "CLASS" \
+                    and _is_abstract(child, lookup, memo, depth + 1):
+                abstract = True
+                break
+
+    memo[node_id] = abstract
+    return abstract
+
+
+def resolve_inheritance(lookup: LookupMaps, registry) -> list[dict]:
+    """EXTENDS / IMPLEMENTS edges for every CLASS node's bases."""
+    edges: list[dict] = []
+    abstract_memo: dict[str, bool] = {}
+
+    for node in lookup.node_by_id.values():
+        if node["type"] != "CLASS":
+            continue
+        rel = node["filePath"]
+        symbols = lookup.symbol_maps.get(rel, {})
+
+        for base in node["metadata"].get("bases", []):
+            parts = base.split(".")
+            root = parts[-1]
+            alias = symbols.get(parts[0], "")
+
+            # third-party base → [pip] node (only when permitted)
+            if alias.startswith("[pip]/"):
+                target_id = alias
+            # imported module base → local class in that file
+            elif alias.startswith("file::"):
+                target_id = lookup.nodes_by_file.get(
+                    alias[len("file::"):], {}).get(root)
+            # same-file base
+            else:
+                target_id = lookup.nodes_by_file.get(rel, {}).get(root)
+
+            if not target_id or target_id == node["id"]:
+                continue
+
+            abstract = False
+            target = lookup.node_by_id.get(target_id)
+            if target and target["type"] == "CLASS":
+                abstract = _is_abstract(target, lookup, abstract_memo)
+
+            edges.append({
+                "from": node["id"], "to": target_id,
+                "type": "IMPLEMENTS" if abstract else "EXTENDS",
+                "metadata": {"baseName": root},
+            })
+
+    return edges

package/extractors/python/devlens_extractors_python/edges/orm_edges.py

@@ -0,0 +1,225 @@
+"""ORM data-layer edges — model detection + READS_FROM/WRITES_TO.
+
+Optimized:
+  - ORM call patterns were collected at PARSE time (metadata.ormOps) —
+    this module only RESOLVES names via lookup maps. No AST re-walks.
+  - Model detection: ONE memoized pass over lookup.node_by_id; base
+    chains resolved through symbol maps + local class links (depth-capped).
+  - All resolutions are dict lookups (symbol maps, nodes_by_name).
+
+Direction: consumer → store (mirrors stateEdges.ts) — the function/class
+that reads or writes points AT the model CLASS node.
+"""
+from __future__ import annotations
+
+import ast
+
+from ..lookup import LookupMaps, closest_by_path
+
+MAX_BASE_DEPTH = 4
+
+
+def _flask_sqlalchemy_instances(parsed_files: list, lookup: LookupMaps) -> set:
+    """{(rel_path, var)} for `db = SQLAlchemy()` (Flask-SQLAlchemy) — enables
+    `class User(db.Model)` base resolution through a local instance."""
+    instances: set = set()
+    for pf in parsed_files:
+        symbols = lookup.symbol_maps.get(pf.rel_path, {})
+        if not any("flask_sqlalchemy" in v for v in symbols.values()):
+            continue
+        for stmt in pf.tree.body:
+            if isinstance(stmt, ast.Assign) and isinstance(stmt.value, ast.Call) \
+                    and isinstance(stmt.value.func, ast.Name) \
+                    and stmt.value.func.id == "SQLAlchemy":
+                for t in stmt.targets:
+                    if isinstance(t, ast.Name):
+                        instances.add((pf.rel_path, t.id))
+    return instances
+
+
+def _marker_hit(alias: str, markers: tuple[str, ...]) -> str | None:
+    """Marker match against a resolved [pip]/ target.
+
+    'django' uses a PREDICATE (not substring) to avoid false positives like
+    django_filters::FilterSet: the target must actually be a django model-ish
+    thing (django.db.models, a *.models module, or ::Model/::models member).
+    Other markers stay substring-based (single-package ecosystems).
+    """
+    for marker in markers:
+        if marker == "django":
+            if any(p in alias for p in
+                   ("django.db.models", "::Model", ".models", "::models")):
+                return "django"
+        elif marker in alias:
+            return marker
+    return None
+
+
+def _base_chain_hit(node: dict, lookup: LookupMaps, memo: dict,
+                    markers: tuple[str, ...], depth: int = 0,
+                    flask_db: frozenset = frozenset()) -> str | None:
+    """Walk the base chain; return the first marker matched in [pip]/ aliases.
+
+    markers are substrings tested against resolved third-party targets,
+    e.g. ('django', 'sqlalchemy', 'sqlmodel') for models or ('pydantic',) for
+    schemas. Handles local chains: class Base(DeclarativeBase) → class User(Base),
+    and Flask-SQLAlchemy: class User(db.Model) with db = SQLAlchemy().
+    NOTE: each marker set needs its OWN memo dict — a cached miss from one
+    scan must not short-circuit a different scan (memo-isolation).
+    """
+    if depth > MAX_BASE_DEPTH:
+        return None
+    node_id = node["id"]
+    if node_id in memo:
+        return memo[node_id]
+
+    rel = node["filePath"]
+    symbols = lookup.symbol_maps.get(rel, {})
+    result = None
+
+    for base in node["metadata"].get("bases", []):
+        parts = base.split(".")
+        first, last = parts[0], parts[-1]
+
+        # Flask-SQLAlchemy: db.Model where db = SQLAlchemy() in this file
+        if last == "Model" and (rel, first) in flask_db:
+            result = "sqlalchemy"
+            break
+
+        alias = symbols.get(first, "")
+
+        if alias.startswith("[pip]/"):
+            result = _marker_hit(alias, markers)
+            if result:
+                break
+            continue
+        # local class (same file or imported file) → recurse the chain
+        target = None
+        if alias.startswith("file::"):
+            target_rel = alias[len("file::"):]
+            # db.Model with db = SQLAlchemy() in the imported file
+            if last == "Model" and (target_rel, first) in flask_db:
+                result = "sqlalchemy"
+                break
+            target = lookup.nodes_by_file.get(target_rel, {}).get(last)
+        if not target:
+            target = lookup.nodes_by_file.get(rel, {}).get(last)
+        if target:
+            child = lookup.node_by_id.get(target)
+            if child and child["type"] == "CLASS":
+                result = _base_chain_hit(child, lookup, memo, markers,
+                                         depth + 1, flask_db)
+                if result:
+                    break
+
+    memo[node_id] = result
+    return result
+
+
+def detect_models(lookup: LookupMaps,
+                  parsed_files: list | None = None) -> dict[str, str]:
+    """Mark model CLASS nodes (metadata.isModel/modelType); return name → id map."""
+    models: dict[str, str] = {}
+    memo: dict[str, str | None] = {}
+    flask_db = frozenset(_flask_sqlalchemy_instances(parsed_files or [], lookup))
+
+    for node in lookup.node_by_id.values():
+        if node["type"] != "CLASS":
+            continue
+        kind = _base_chain_hit(node, lookup, memo,
+                               ("django", "sqlalchemy", "sqlmodel"),
+                               flask_db=flask_db)
+        if kind:
+            node["metadata"]["isModel"] = True
+            node["metadata"]["modelType"] = kind
+            models.setdefault(node["name"], node["id"])
+
+    return models
+
+
+def _resolve_name(lookup: LookupMaps, rel: str, name: str) -> str | None:
+    """Name → node id via symbol map (refined), then global closest-by-path."""
+    alias = lookup.symbol_maps.get(rel, {}).get(name)
+    if alias:
+        if alias.startswith("file::"):
+            return lookup.nodes_by_file.get(alias[len("file::"):], {}).get(name)
+        return alias
+    candidates = lookup.nodes_by_name.get(name)
+    if candidates:
+        return candidates[0][0] if len(candidates) == 1 else closest_by_path(candidates, rel)
+    return None
+
+
+def _match_instance_var(var: str, models: dict[str, str]) -> str | None:
+    """user.save() / session.add(user) — var name ↔ model name heuristic.
+    Exact → singularized → case-insensitive (user ↔ User, users ↔ User)."""
+    for key in (var, var.rstrip("s")):
+        if key in models:
+            return models[key]
+    lower = var.lower()
+    for name, node_id in models.items():
+        if name.lower() == lower or name.lower() == lower.rstrip("s"):
+            return node_id
+    return None
+
+
+def _resolve_orm_target(op: dict, node: dict, lookup: LookupMaps,
+                        models: dict[str, str]) -> str | None:
+    rel = node["filePath"]
+
+    # bare sqlalchemy statements (select/insert/update/delete) — verify the
+    # function name is actually sqlalchemy's, else skip (avoid false positives
+    # on generic update()/delete() helpers)
+    if op.get("root"):
+        alias = lookup.symbol_maps.get(rel, {}).get(op["root"], "")
+        if "sqlalchemy" not in alias:
+            return None
+
+    if op.get("target"):
+        target = models.get(op["target"])            # fast path: name IS a model
+        if not target:
+            target = _resolve_name(lookup, rel, op["target"])
+        if target:
+            tnode = lookup.node_by_id.get(target)
+            if tnode and tnode["metadata"].get("isModel"):
+                return target
+        return None
+
+    if op.get("arg"):                                # instance heuristic
+        return _match_instance_var(op["arg"], models)
+
+    return None
+
+
+def resolve_orm_edges(lookup: LookupMaps, models: dict[str, str]) -> list[dict]:
+    """metadata.ormOps → READS_FROM/WRITES_TO edges; serializer Meta.model links."""
+    edges: list[dict] = []
+
+    for node in lookup.node_by_id.values():
+        if node["type"] not in ("FUNCTION", "METHOD", "CLASS"):
+            continue
+        for op in node["metadata"].get("ormOps", []):
+            target = _resolve_orm_target(op, node, lookup, models)
+            if not target or target == node["id"]:
+                continue
+            edges.append({
+                "from": node["id"],
+                "to": target,
+                "type": "READS_FROM" if op["kind"] == "read" else "WRITES_TO",
+                "metadata": {"ormType": op["pattern"],
+                             "heuristic": bool(op.get("arg"))},
+            })
+
+    # DRF serializer: class Meta: model = User → serializer READS_FROM model
+    for node in lookup.node_by_id.values():
+        if node["type"] != "CLASS":
+            continue
+        linked = node["metadata"].get("linkedModel")
+        if linked and linked in models and models[linked] != node["id"]:
+            edges.append({
+                "from": node["id"], "to": models[linked],
+                "type": "READS_FROM",
+                "metadata": {"ormType": "serializer", "callPattern": "meta_model"},
+            })
+
+    return edges

package/extractors/python/devlens_extractors_python/edges/routes/__init__.py

@@ -0,0 +1,28 @@
+"""Route detection — split by framework style:
+
+  decorators.py   FastAPI/Flask decorator routes (+ include_router prefixes)
+  django_urls.py  Django urlpatterns (path/re_path/url + include recursion)
+  drf.py          DRF routers (DefaultRouter().register → CRUD expansion)
+  common.py       shared builders (RouteResult, ROUTE node, HANDLES edge)
+"""
+from __future__ import annotations
+
+from ...lookup import LookupMaps
+from .common import RouteResult
+from .decorators import detect_decorator_routes
+from .django_urls import detect_django_urlpatterns
+from .drf import detect_drf_routers
+
+
+def detect_routes(parsed_files: list, lookup: LookupMaps, fingerprint) -> RouteResult:
+    """Detect FastAPI/Flask decorator routes + Django urlpatterns + DRF routers.
+    Self-describing: runs whichever patterns the code actually uses;
+    a repo with neither produces an empty RouteResult (never crashes)."""
+    result = RouteResult()
+    detect_decorator_routes(parsed_files, lookup, fingerprint, result)
+    detect_django_urlpatterns(parsed_files, lookup, result)
+    detect_drf_routers(parsed_files, lookup, result)
+    return result
+
+
+__all__ = ["detect_routes", "RouteResult"]