cg-code-graph 0.23.4__tar.gz → 0.23.5__tar.gz

{cg_code_graph-0.23.4/cg_code_graph.egg-info → cg_code_graph-0.23.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cg-code-graph
-Version: 0.23.4
+Version: 0.23.5
 Summary: cg: a code graph of routes, calls, data access and platform boundaries for agents and humans (CLI + MCP server)
 Author: cyberchronos00
 License-Expression: MIT

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/__init__.py

@@ -1,2 +1,2 @@
 """code-graph: deterministic code knowledge graph (beta)."""
-__version__ = "0.23.4"
+__version__ = "0.23.5"

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/blindspots.py

@@ -222,11 +222,23 @@ def express_loop_routes(root: Path, files: list[str]) -> dict | None:
 _PHP_LOOPS = re.compile(r"\b(?:foreach|for|while)\s*\(|->\s*(?:each|map|flatMap|eachSpread)\s*\(|\barray_(?:map|walk)\s*\(")
 
 
-def laravel_loop_routes(root: Path, files: list[str]) -> dict | None:
-    """Route::get(...) inside foreach / for / ->each(...) / array_map(...): the URIs come from data, so the Laravel
-    plugin cannot list them."""
+def laravel_loop_routes(root: Path, files: list[str], builder=None) -> dict | None:
+    """Route::get(...) inside foreach / for / ->each(...) / array_map(...) that the Laravel plugin did not unroll.
+
+    Loops over literal data in route files are unrolled (#184); the plugin records every loop it saw in
+    `builder.route_loops` ({file: [{line, end, unrolled, reason}]}). The ones it could not unroll are reported with
+    their reason (`iterable not literal`); the regex below still finds loops outside route files."""
     hits = []
+    reasons: dict[str, str] = {}
+    known = getattr(builder, "route_loops", None) or {}
+    for rel, loops in known.items():
+        for lp in loops:
+            if not lp.get("unrolled"):
+                hits.append((rel, lp["line"]))
+                if lp.get("reason"):
+                    reasons[f"{rel}:{lp['line']}"] = lp["reason"]
     for rel in files:
+        spans = [(lp["line"], lp.get("end") or lp["line"]) for lp in known.get(rel, [])]
         src = _read(root, rel)
         if not src or "Route::" not in src:
             continue
@@ -237,9 +249,17 @@ def laravel_loop_routes(root: Path, files: list[str]) -> dict | None:
                 continue
             if re.search(r"\bRoute::\s*(?:get|post|put|patch|delete|any|match|resource|apiResource|resources|apiResources|view|redirect)\s*\(",
                          src[b0:b1]):
-                hits.append((rel, _line(src, start)))
+                ln = _line(src, start)
+                if not any(lo <= ln <= hi for lo, hi in spans):
+                    hits.append((rel, ln))
                 done_until = b1
-    return _finding("laravel_loop_routes", hits)
+    out = _finding("laravel_loop_routes", hits)
+    if out and reasons:
+        out["reasons"] = {k: reasons[k] for k in out["samples"] if k in reasons}
+        why = sorted(set(out["reasons"].values()))
+        if why:
+            out["what"] = f"{out['what']} ({'; '.join(why)})"
+    return out
 
 
 # ------------------------------------------------------------------------------------------- Django (AST)
@@ -549,7 +569,7 @@ def detect(root: str | Path, files_by_ext: dict[str, list[str]], builder=None, p
     run(nuxt_unevaluable_import_dirs, root)
     run(vue_unresolved_navigation, builder)
     run(ts_unrecognised_http_client, root, js, builder)
-    run(laravel_loop_routes, root, php)
+    run(laravel_loop_routes, root, php, builder)
     py = programs.get("python")
     if py is not None:
         run(django_dynamic_urlpatterns, [(m.file, m.tree) for m in py.modules.values()])

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/cli.py

@@ -826,6 +826,9 @@ def main(argv=None):
 def _unknown_route(st, spec: str, as_json: bool) -> bool:
     miss = Q.route_failure(st, spec)
     if not miss:
+        note = Q.route_declared_note(st, spec)
+        if note:
+            print(note, file=sys.stderr)
         return False
     if as_json:
         print(json.dumps({"error": miss["error"], "spec": miss["spec"], "suggestions": miss["suggestions"]}))

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/core/plugin.py

@@ -59,6 +59,9 @@ class GraphBuilder:
         # Pigeon API definitions found by the Dart plugin ({Api: {kind: host | flutter, methods, file}}): bridges.py
         # links their native implementations / native callers
         self.pigeon_apis: dict = {}
+        # loops around route registrations in Laravel route files ({file: [{line, end, unrolled, reason}]}, #184):
+        # the blind-spot detector reports the ones that were not unrolled
+        self.route_loops: dict = {}
         # keyed-hash salt for the markers that stand in for secret values (cg_code_graph/core/redact.py); the indexer
         # sets it from the graph DB before any plugin runs
         self.redact_salt: str | None = None

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/link.py

@@ -11,8 +11,11 @@ graphs (role backend, frontend or both):
 Matching is deterministic (no guessing):
   - the client path is the extractor's URL template with the origin (scheme://host or the
     unknown server-URL placeholder) and query string removed;
-  - backend URIs are tried as declared and, for routes from routes/api.php, with the `/api`
-    prefix Laravel adds;
+  - backend URIs are tried at the path the server serves them under: a Laravel route of routes/api.php is
+    stored with its API prefix (`apiPrefix` in bootstrap/app.php, a RouteServiceProvider group, `api` by
+    default) and keeps its declared path in attrs.declared_uri. When no prefix configuration was found
+    (the `api` default) the declared path is tried as well, and a route from an older graph without
+    declared_uri gets the `/api` + uri variant (see route_uri_variants);
   - segments match when literal == literal, client placeholder <-> route {param},
     client literal -> route {param} (resolved), or a client segment with an embedded
     placeholder fully matches a route literal (heuristic, e.g. export.{format} ~ export.csv);
@@ -39,6 +42,28 @@ from types import SimpleNamespace
 from .core.model import CONFIDENCE_RANK
 from .core.store import GraphStore
 
+
+_API_ROUTE_FILE = re.compile(r"(^|/)routes/api(\.php$|/)")
+
+
+def route_uri_variants(file: str | None, attrs: dict) -> list[tuple[str, str]]:
+    """(variant, uri) pairs a route answers to. `file` is the route node's file (with or without a repo prefix).
+
+    A Laravel route stores the served path (#191): attrs.uri carries the API prefix and attrs.declared_uri the
+    path as written. The declared path is also tried when the prefix is Laravel's default rather than read from
+    configuration. A route without declared_uri from routes/api.php (an older graph) gets the `/api` variant."""
+    uri = attrs.get("uri")
+    out = [("as-declared", uri)]
+    declared = attrs.get("declared_uri")
+    if declared:
+        out = [("served", uri)]
+        if attrs.get("prefix_from") == "laravel-default" and declared != uri:
+            out.append(("declared, without the default /api prefix", declared))
+        return out
+    if _API_ROUTE_FILE.search(file or "") and uri and not uri.startswith("/api/"):
+        out.append(("api-prefixed", "/api" + uri))
+    return out
+
 PARAM = re.compile(r"^\{(\w+)(\?)?\}$")
 CATCH_ALL = re.compile(r"^\{(\w+)\*(\?)?\}$")   # {rest*} one or more segments, {rest*?} zero or more (TS routers, Next.js)
 PH = re.compile(r"\{[^{}]*\}")
@@ -401,9 +426,7 @@ def link_many(repos: list[tuple[str, str, str]], out_db: str, *, allow: dict | N
                     uri, method = a.get("uri"), a.get("method")
                     if not uri or not method:
                         continue
-                    uris = [("as-declared", uri)]
-                    if (r[1] or "").startswith("routes/api.php") or (r[1] or "").startswith("routes/api/"):
-                        uris.append(("api-prefixed", "/api" + uri))
+                    uris = route_uri_variants(r[1], a)
                     routes.append({"id": mid(name, r[0]), "uri": uri, "method": method, "uris": uris, "server": name,
                                    "file": f"{name}/{r[1]}" if r[1] else None, "line": r[3],
                                    "attrs": dict(a, _file=r[1], _line=r[3])})

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/plans.py

@@ -21,6 +21,7 @@ from . import presets
 from . import query as Q
 from .core.model import PROPAGATING
 from .core.store import GraphStore
+from .link import route_uri_variants
 
 PLAN_VERSION = 1
 STATUSES = ("draft", "agreed", "in_progress", "implemented", "abandoned")
@@ -419,10 +420,8 @@ class Ctx:
             a = json.loads(r["attrs"] or "{}")
             if not a.get("uri") or not a.get("method"):
                 continue
-            uris = [("as-declared", a["uri"])]
             f = (r["file"] or "").split("/", 1)[-1] if self.combined else (r["file"] or "")
-            if f.startswith("routes/api"):
-                uris.append(("api-prefixed", "/api" + a["uri"]))
+            uris = route_uri_variants(f, a)
             out.append({"id": r["id"], "uri": a["uri"], "method": a["method"], "uris": uris, "file": r["file"], "line": r["line"]})
         return out
 
@@ -796,10 +795,8 @@ def snapshot_clients(st, route_ids, root: str | Path | None = None) -> list[dict
                     a = json.loads(r["attrs"] or "{}")
                     if not a.get("uri") or not a.get("method"):
                         continue
-                    uris = [("as-declared", a["uri"])]
                     rf = (r["file"] or "").split("/", 1)[-1] if combined else (r["file"] or "")
-                    if rf.startswith("routes/api"):
-                        uris.append(("api-prefixed", "/api" + a["uri"]))
+                    uris = route_uri_variants(rf, a)
                     routes.append({"id": r["id"], "uri": a["uri"], "method": a["method"], "uris": uris,
                                    "file": r["file"], "line": r["line"]})
             hit = [m["route"] for m in match_endpoint(c.get("method") or "GET", base + c["path"], routes)["matched"]

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/plugins/laravel/plugin.py

@@ -180,6 +180,7 @@ class LaravelPlugin(FrameworkPlugin):
         self.observers, self.listeners, self.schedules, self.bindings = [], [], [], []
         self.seen_cols = set()
         self.records = {r["file"]: r for r in prog.records}
+        self._apply_route_mounts()
         self._parse_config()
         self._parse_migrations()
         self._parse_models()
@@ -196,6 +197,40 @@ class LaravelPlugin(FrameworkPlugin):
         self.tests = LaravelTests(self, prog)
         prog.test_fact_handlers.append(self.tests.handle_fact)
 
+    # ---- route files: served path (#191)
+    def _route_mounts(self) -> dict[str, tuple[str, str]]:
+        """routes file -> (prefix, where it comes from): `withRouting(api:, apiPrefix:)` / `then:` groups in
+        bootstrap/app.php, `Route::prefix(..)->group(base_path(..))` in a (Laravel <= 10) RouteServiceProvider."""
+        out: dict[str, tuple[str, str]] = {}
+        order = sorted(self.records, key=lambda f: (not f.startswith("bootstrap/"), f))
+        for f in order:
+            for m in self.records[f].get("route_mounts") or []:
+                rf = m.get("file")
+                if isinstance(rf, str) and rf not in out and isinstance(m.get("prefix"), str):
+                    out[rf] = (m["prefix"].strip("/"), f)
+        return out
+
+    def _apply_route_mounts(self):
+        """Every route of routes/api.php (and routes/api/) is stored at the path Laravel serves it under: the configured
+        API prefix, `api` when nothing configures it. The declared path stays in `declared_uri`."""
+        mounts = self._route_mounts()
+        for f, r in self.records.items():
+            if not f.startswith("routes/") or not r.get("routes"):
+                continue
+            hit = mounts.get(f)
+            if hit is None and f.startswith("routes/api/"):
+                hit = mounts.get("routes/api.php")
+            if hit is None and (f == "routes/api.php" or f.startswith("routes/api/")):
+                hit = ("api", "laravel-default")
+            if hit is None or not hit[0]:
+                continue
+            prefix, src = hit
+            for rt in r["routes"]:
+                declared = rt.get("full_uri") or "/"
+                rt["declared_uri"] = declared
+                rt["full_uri"] = "/" + "/".join(p for p in (prefix.strip("/"), declared.strip("/")) if p)
+                rt["prefix_from"] = src
+
     # ---- config/*.php
     def _parse_config(self):
         b = self.b
@@ -916,13 +951,20 @@ class LaravelPlugin(FrameworkPlugin):
         cid = self.b.add_node("config", key, lang="php")
         self.b.add_edge(fn.id, cid, "READS_CONFIG", fn.file, line, conf)
 
+    def _recv_of(self, c, h) -> dict:
+        """attrs.recv for an edge into a job's handle() inherited from a base class: the job class, so the base
+        handle()'s `$this->execute()` reaches only this job's override (#148)."""
+        if c.methods.get("handle") is h or c.methods.get("__invoke") is h:
+            return {}
+        return {"recv": [f"{c.kind}:{c.fqcn}"]}
+
     def _dispatch(self, fn, cls, line, conf):
         c = self.prog.cls(cls)
         if not c:
             return
         h = self.prog.find_method(c.fqcn, "handle") or self.prog.find_method(c.fqcn, "__invoke")
         if self._is_job(c.fqcn) and h:
-            self.b.add_edge(fn.id, h.id, "DISPATCHES", fn.file, line, conf, via="job")
+            self.b.add_edge(fn.id, h.id, "DISPATCHES", fn.file, line, conf, via="job", **self._recv_of(c, h))
         else:
             eid = self.b.add_node("event", c.fqcn, name=c.fqcn.split("\\")[-1], fqn=c.fqcn, file=c.file, line=c.line,
                                   module=module_of(c.file), lang="php")
@@ -1011,6 +1053,8 @@ class LaravelPlugin(FrameworkPlugin):
         from ..php.inline_guards import for_action
         n = 0
         for f, r in self.records.items():
+            if r.get("route_loops"):
+                b.route_loops[f] = r["route_loops"]
             for rt in r.get("routes") or []:
                 for verb in rt["methods"]:
                     key = f"{verb.upper()} {rt['full_uri']}"
@@ -1021,6 +1065,15 @@ class LaravelPlugin(FrameworkPlugin):
                         self.stats["route_middleware_unresolved"] = self.stats.get("route_middleware_unresolved", 0) + 1
                     attrs = {"name": rt.get("name") or None, "middleware": mws if rt.get("middleware") is not None else None,
                              "uri": rt["full_uri"], "method": verb.upper()}
+                    if rt.get("declared_uri"):
+                        attrs["declared_uri"] = rt["declared_uri"]
+                        attrs["prefix_from"] = rt.get("prefix_from")
+                    for k, ak in (("defaults", "defaults"), ("wheres", "where")):
+                        if rt.get(k):
+                            attrs[ak] = rt[k]
+                    if rt.get("unrolled_from"):
+                        u = rt["unrolled_from"]
+                        attrs["unrolled_from"] = {"file": f, "line": u.get("line"), "binding": u.get("binding") or {}}
                     if rt.get("webhook_client"):
                         attrs["webhook_client"] = rt["webhook_client"]
                         attrs["webhook_framework"] = "laravel-webhook-client"
@@ -1197,7 +1250,7 @@ class LaravelPlugin(FrameworkPlugin):
                 if h:
                     jid = b.add_node("job", c.fqcn, name=c.fqcn.split("\\")[-1], fqn=c.fqcn, file=c.file, line=c.line,
                                      module=module_of(c.file), lang="php", entry_kind="queue_job")
-                    b.add_edge(jid, h.id, "HANDLED_BY", c.file, h.line, EXACT)
+                    b.add_edge(jid, h.id, "HANDLED_BY", c.file, h.line, EXACT, **self._recv_of(c, h))
                     self.stats["jobs"] += 1
             if c.fqcn.startswith("App\\Listeners\\"):
                 h = prog.find_method(c.fqcn, "handle")

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/plugins/laravel/tests.py

@@ -7,8 +7,8 @@
   TEST_CALLS -> the file (beforeEach, uses(...) and other file-level setup);
 * HTTP test calls (`$this->getJson('/api/x')`, `->actingAs($u)->post(route('x.store'))`, Pest `get('/x')`,
   `$this->json('PATCH', '/x')`, and the same calls through project helpers such as `$this->getAs('/x')` whose URL /
-  verb are parameters) -> TEST_HTTP -> the matching route (URIs matched like cross-repo links, with the
-  `/api` prefix Laravel adds to routes/api.php; `route('name')` by route name).
+  verb are parameters) -> TEST_HTTP -> the matching route (URIs matched like cross-repo links, on the served path: routes/api.php routes
+  carry the API prefix Laravel adds; `route('name')` by route name).
 
 Edges made by test code are retyped to non-propagating TEST_* kinds afterwards (cg_code_graph/tests_index.py), so
 tests never change blast radius, caller counts or entry tagging. `cg tests <symbol|route>` walks them on purpose.
@@ -154,7 +154,7 @@ class LaravelTests:
 
     # ---- after reference emission
     def contribute(self) -> dict:
-        from ...link import match_endpoint
+        from ...link import match_endpoint, route_uri_variants
         b, prog = self.lp.b, self.prog
         st = defaultdict(int)
         self._expand_helpers(st)
@@ -162,9 +162,7 @@ class LaravelTests:
         for nid, n in b.nodes.items():
             if n.kind != "route" or not n.attrs.get("uri") or not n.attrs.get("method"):
                 continue
-            uris = [("as-declared", n.attrs["uri"])]
-            if (n.file or "").startswith(("routes/api.php", "routes/api/")):
-                uris.append(("api-prefixed", "/api" + n.attrs["uri"]))
+            uris = route_uri_variants(n.file, n.attrs)
             routes.append({"id": nid, "uri": n.attrs["uri"], "method": n.attrs["method"], "uris": uris})
             if n.attrs.get("name"):
                 by_name[n.attrs["name"]].append(n)

{cg_code_graph-0.23.4 → cg_code_graph-0.23.5}/cg_code_graph/plugins/nuxt/plugin.py

@@ -18,6 +18,7 @@ contribute: file-based routing (route path per page), entry points (pages = ui_p
 from __future__ import annotations
 
 import atexit
+from collections import defaultdict
 import json
 import re
 import shutil
@@ -98,10 +99,30 @@ _SIDE_SKIP = re.compile(r"\.(test|spec)\.[cm]?[jt]sx?$|\.d\.ts$")
 
 def side_dirs(root: Path, src_dir: str) -> list[str]:
     """Root-level server/ and shared/ of a Nuxt project whose srcDir is not the root (with a root srcDir they are
-    already inside it; Nuxt 3's src/server sits inside a src/ srcDir)."""
+    already inside it; Nuxt 3's src/server sits inside a src/ srcDir), and the server/ dirs of local layers."""
     if src_dir in ("", "."):
         return []
-    return [d for d in SIDE_DIRS if (root / d).is_dir()]
+    return [d for d in SIDE_DIRS if (root / d).is_dir()] + layer_server_dirs(root, src_dir)
+
+
+def layer_server_dirs(root: Path, src_dir: str | None = None) -> list[str]:
+    """server/ dirs of local layers (#217): `extends: ['./layers/admin']` and the auto-registered layers/*/."""
+    out: list[str] = []
+    try:
+        plan_layers = nuxt_import_plan(root, src_dir)["layers"][1:]
+    except Exception:   # noqa: BLE001  (a config the scanner cannot read: no extends)
+        plan_layers = []
+    cands = [ly["dir"] for ly in plan_layers]
+    if (root / "layers").is_dir():
+        cands += sorted(d for d in (root / "layers").iterdir() if d.is_dir())
+    for d in cands:
+        try:
+            rel = d.resolve().relative_to(root.resolve()).as_posix()
+        except ValueError:
+            continue
+        if rel and rel != "." and (root / rel / "server").is_dir() and f"{rel}/server" not in out:
+            out.append(f"{rel}/server")
+    return out
 
 
 def side_files(root: Path, dirs: list[str]) -> list[str]:
@@ -895,6 +916,83 @@ def nitro_route(rel: str, prefix: str = "") -> tuple[str, str] | None:
     return method, "/" + "/".join(s.strip("/") for s in [prefix.strip("/")] + segs if s.strip("/"))
 
 
+_OBJ_HOOK = re.compile(r"\b(onRequest|onBeforeResponse)\s*:\s*(\[[^\]]*\]|[A-Za-z_$][\w$]*|\(|async\b|function\b)")
+_OBJ_HANDLER_REF = re.compile(r"\bhandler\s*:\s*([A-Za-z_$][\w$]*)\s*[,}\n]")
+_PATH_GUARD = re.compile(r"if\s*\(\s*!\s*(?:event\.path|event\.node\.req\.url|getRequestURL\(\s*event\s*\)\.pathname)"
+                         r"(?:\?)?\.startsWith\(\s*['\"`]([^'\"`]+)['\"`]\s*\)\s*\)\s*\{?\s*return\b")
+
+
+def object_hooks(src: str) -> tuple[list[tuple[str, str]], str | None]:
+    """`defineEventHandler({ onRequest: [auth], onBeforeResponse: fn, handler })` (#217): [(hook, name)] where name is
+    an identifier or `<inline>`, and the identifier given as `handler` (None when it is an inline function)."""
+    i = src.find("defineEventHandler(")
+    if i < 0:
+        return [], None
+    j = i + len("defineEventHandler(")
+    while j < len(src) and src[j] in " \t\r\n":
+        j += 1
+    if j >= len(src) or src[j] != "{":
+        return [], None
+    body = src[j:]
+    hooks = []
+    for m in _OBJ_HOOK.finditer(body):
+        hook, val = m.group(1), m.group(2)
+        if val.startswith("["):
+            for name in re.findall(r"[A-Za-z_$][\w$]*", val[1:-1]):
+                hooks.append((hook, name))
+        elif val in ("(", "async", "function"):
+            hooks.append((hook, "<inline>"))
+        else:
+            hooks.append((hook, val))
+    ref = _OBJ_HANDLER_REF.search(body)
+    return hooks, ref.group(1) if ref and ref.group(1) not in ("async", "function") else None
+
+
+def path_guard(src: str) -> str | None:
+    """Prefix of `if (!event.path.startsWith('/api/admin')) return` at the top of a Nitro middleware (#217)."""
+    m = _PATH_GUARD.search(src)
+    return m.group(1) if m else None
+
+
+def rule_covers(pattern: str, uri: str) -> bool:
+    """Nitro routeRules pattern (`/api/legacy/**`, `/blog/*`, exact) against a route uri with {param} segments."""
+    pat = pattern.rstrip("/") or "/"
+    if pat.endswith("/**"):
+        base = pat[:-3]
+        return uri == base or uri.startswith(base + "/")
+    ps, us = pat.strip("/").split("/"), uri.strip("/").split("/")
+    if len(ps) != len(us):
+        return False
+    return all(p == "*" or p == u or (u.startswith("{") and p.startswith(":")) for p, u in zip(ps, us))
+
+
+def config_handlers(cfg: dict) -> list[dict]:
+    """`serverHandlers` and `nitro.handlers` entries of a parsed nuxt.config: [{route, method, handler, middleware}]."""
+    out = []
+    nitro = cfg.get("nitro") if isinstance(cfg.get("nitro"), dict) else {}
+    for where, items in (("serverHandlers", cfg.get("serverHandlers")), ("nitro.handlers", nitro.get("handlers"))):
+        for it in items if isinstance(items, list) else []:
+            if not isinstance(it, dict) or not isinstance(it.get("handler"), str):
+                continue
+            out.append({"route": it.get("route") if isinstance(it.get("route"), str) else None,
+                        "method": it.get("method") if isinstance(it.get("method"), str) else None,
+                        "handler": it["handler"], "middleware": it.get("middleware") is True, "from": where})
+    return out
+
+
+def proxy_rules(cfg: dict) -> dict[str, str]:
+    """routeRules / nitro.routeRules patterns with a `proxy` -> proxy target (or '?' when not a literal)."""
+    out = {}
+    nitro = cfg.get("nitro") if isinstance(cfg.get("nitro"), dict) else {}
+    for rules in (cfg.get("routeRules"), nitro.get("routeRules")):
+        for pat, rule in (rules.items() if isinstance(rules, dict) else ()):
+            if isinstance(rule, dict) and "proxy" in rule:
+                p = rule["proxy"]
+                target = p if isinstance(p, str) else (p.get("to") if isinstance(p, dict) and isinstance(p.get("to"), str) else "?")
+                out[pat] = target
+    return out
+
+
 def server_dirs(root: Path, src_dir: str) -> list[str]:
     """Nitro server dirs of a Nuxt project: the root server/ (Nuxt 4 serverDir) and <srcDir>/server (Nuxt 3)."""
     cands = ["server"] + ([] if src_dir in ("", ".") else [f"{src_dir.strip('/')}/server"])
@@ -1185,11 +1283,29 @@ class NuxtPlugin(FrameworkPlugin):
     def _nitro(self, project: Project, b: GraphBuilder) -> dict:
         from ..tsweb.common import add_route
         st = {"routes": 0, "middleware": 0, "plugins": 0, "proxy_routes": 0, "linked_calls": 0}
-        dirs = server_dirs(project.root, self.src_dir)
-        if not dirs:
+        self._mod_refs = None
+        root = project.root
+        dirs = server_dirs(root, self.src_dir)
+        layer_dirs = [d for d in layer_server_dirs(root, self.src_dir) if d not in dirs]
+        cfg_path = _config_path(root)
+        cfg = {}
+        if cfg_path:
+            try:
+                cfg = _find_config_object(cfg_path.read_text(errors="replace"))
+            except Exception:   # noqa: BLE001
+                cfg = {}
+        cfg_handlers = config_handlers(cfg)
+        if not dirs and not layer_dirs and not cfg_handlers:
             return st
+        dirs = dirs + layer_dirs
         files = sorted({n.file for n in b.nodes.values() if n.lang == "ts" and n.kind == "module" and n.file})
 
+        def read(f: str) -> str:
+            try:
+                return (root / f).read_text(errors="replace")
+            except OSError:
+                return ""
+
         def handler(f: str) -> tuple[str | None, str]:
             for nid in (f"function:{f}#default", f"function:{f}#handler"):
                 if b.has(nid):
@@ -1212,7 +1328,7 @@ class NuxtPlugin(FrameworkPlugin):
                     h, _c = handler(f)
                     if h:
                         label(f, "middleware")
-                        middleware.append((h, f"nitro:{_NITRO_EXT.sub('', inner)}", "resolved"))
+                        middleware.append((h, f"nitro:{_NITRO_EXT.sub('', inner)}", "resolved", path_guard(read(f))))
                         st["middleware"] += 1
                 elif top == "plugins" and inner and nitro_route(inner) is not None:
                     h, _c = handler(f)
@@ -1224,25 +1340,105 @@ class NuxtPlugin(FrameworkPlugin):
                     r = nitro_route(inner, "/api" if top == "api" else "")
                     if r:
                         routes.append((f, top, r))
+        # nuxt.config serverHandlers / nitro.handlers: { route, method, handler: '~~/server/handlers/x.ts' }
+        for ch in cfg_handlers:
+            hf = self._config_handler_file(root, ch["handler"], set(files))
+            if not hf:
+                st["config_handlers_unresolved"] = st.get("config_handlers_unresolved", 0) + 1
+                continue
+            if ch["middleware"] or not ch["route"]:
+                h, _c = handler(hf)
+                if h:
+                    label(hf, "middleware")
+                    middleware.append((h, f"nitro:{ch['handler']}", "resolved", path_guard(read(hf))))
+                    st["middleware"] += 1
+                continue
+            method = (ch["method"] or "ANY").upper()
+            uri = re.sub(r":(\w+)", r"{\1}", "/" + ch["route"].strip("/"))
+            routes.append((hf, ch["from"], (method, uri)))
+        rules = proxy_rules(cfg)
+
+        def scoped(uri: str) -> list[tuple]:
+            out = []
+            for m in middleware:
+                prefix = m[3] if len(m) > 3 else None
+                if prefix is None:
+                    out.append(m[:3])
+                elif uri == prefix.rstrip("/") or uri.startswith(prefix.rstrip("/") + "/"):
+                    out.append((m[0], m[1], "heuristic"))     # early return outside the prefix (#217)
+            return out
+
         for f, top, (method, uri) in routes:
             h, conf = handler(f)
+            src = read(f)
+            hooks, ref = object_hooks(src)
+            if ref and b.has(f"function:{f}#{ref}"):
+                h, conf = f"function:{f}#{ref}", "exact"
             line = (b.nodes[h].line or 1) if h else 1
-            attrs = {"file_route": True, "nitro_dir": top, "method_from": "file suffix" if method != "ANY" else "any"}
-            try:
-                src = (project.root / f).read_text(errors="replace")
-            except OSError:
-                src = ""
+            attrs = {"file_route": top in ("api", "routes"), "nitro_dir": top,
+                     "method_from": ("file suffix" if top in ("api", "routes") else "config") if method != "ANY" else "any"}
+            if top not in ("api", "routes"):
+                attrs["registered_in"] = top
             if _PROXY_CALL.search(src):
                 attrs["proxy"] = True
+            for pat, target in rules.items():
+                if rule_covers(pat, uri):
+                    attrs["proxy"] = True
+                    attrs["proxy_rule"] = pat
+                    if target != "?":
+                        attrs["proxy_target"] = target
+                    break
+            if attrs.get("proxy"):
                 st["proxy_routes"] += 1
             if not h or h.startswith("module:"):
                 attrs["handler_unresolved"] = True
-            add_route(b, method, uri, [h] if h else [], f, line, "nuxt", conf, attrs, middleware)
+            mws = scoped(uri)
+            for hook, name in hooks:
+                nid = self._hook_node(b, f, hook, name)
+                if nid:
+                    mws.append((nid, f"{hook}:{name if name != '<inline>' else 'inline'}", "exact"))
+            add_route(b, method, uri, [h] if h else [], f, line, "nuxt", conf, attrs, mws)
             label(f, "route")
             st["routes"] += 1
         st["linked_calls"] = self._link_nitro(b)
         return st
 
+    def _config_handler_file(self, root: Path, spec: str, files: set[str]) -> str | None:
+        """A nuxt.config handler path (`~~/server/x.ts`, `~/server/x`, `./server/x.ts`) -> indexed file."""
+        s = spec.strip()
+        src = self.src_dir.strip("/") if self.src_dir not in ("", ".") else ""
+        bases = []
+        for alias, base in (("~~/", ""), ("@@/", ""), ("~/", src), ("@/", src), ("./", ""), ("/", "")):
+            if s.startswith(alias):
+                bases = [base, ""] if base else [""]
+                s = s[len(alias):]
+                break
+        else:
+            bases = [""]
+        for base in bases:
+            stem = f"{base}/{s}" if base else s
+            for cand in [stem] + [stem + ext for ext in (".ts", ".js", ".mjs", ".mts")] + [f"{stem}/index.ts"]:
+                if cand in files:
+                    return cand
+        return None
+
+    def _hook_node(self, b: GraphBuilder, f: str, hook: str, name: str) -> str | None:
+        """onRequest / onBeforeResponse function of an object-form handler: inline, local, or an imported function."""
+        local = f"function:{f}#{hook if name == '<inline>' else name}"
+        if b.has(local):
+            return local
+        if name == "<inline>":
+            return None
+        if getattr(self, "_mod_refs", None) is None:
+            self._mod_refs = defaultdict(list)
+            for e in b.edges.values():
+                if e.kind in ("CALLS", "REFERENCES") and e.src.startswith("module:"):
+                    self._mod_refs[e.src].append(e.dst)
+        for dst in self._mod_refs.get(f"module:{f}", ()):
+            if dst.endswith(f"#{name}") and b.has(dst):
+                return dst
+        return None
+
     def _link_nitro(self, b: GraphBuilder) -> int:
         """Same-origin client calls of this app (relative URLs: `$fetch('/api/x')`, `useFetch`) -> its Nitro routes.
         Proxy routes (proxyRequest / sendProxy) forward elsewhere and are not link targets."""