@descryy/adapter-python 0.2.0 → 0.3.1

package/dist/extract.js

@@ -30,11 +30,11 @@
  * because `a/__init__.py` importing from `b/__init__.py` importing back is legal
  * Python and must not hang the run.
  */
-import { databaseTableNodesFromModel, edgeId, endpointQsp, isTypeLikeNodeType, nodeId, normaliseEndpointPath, symbolQsp, testCaseQsp, } from "@descryy/ir";
+import { databaseTableNodesFromModel, edgeId, endpointQsp, isCallableNodeType, isTypeLikeNodeType, nodeId, normaliseEndpointPath, symbolQsp, testCaseQsp, } from "@descryy/ir";
 import { importRoots, modulePathOf, moduleNameOf, resolveImport, } from "./module.js";
 import { DECLARATIVE_BASE_FACTORIES, ORM_BASE_MODULES, isFrameworkBaseName, ormShapeOf, } from "./orm.js";
 import { globToRegExp, PYTEST_DEFAULTS } from "./pytest-config.js";
-import { drfShapeOf, dtoShapeOf, isDrfSerializerRoot, isPydanticRoot, isValidatorDecorator, } from "./pydantic.js";
+import { drfShapeOf, dtoShapeOf, isDrfSerializerRoot, isPydanticRoot, isValidatorDecorator, PYDANTIC_MODEL_MEMBERS, } from "./pydantic.js";
 import { DRF_ACTIONS, drfRegisterCallsIn, drfRouterLocalsIn, djangoUrlEntriesIn, HTTP_METHODS, isApplicationRouter, joinPath, mountsIn, odooRouteFromDecorator, routeFromDecorator, routersIn, } from "./routes.js";
 import { GRAPHQL_METHOD, fieldFromMethod, fieldsFromAttributes, operationPath, schemaDeclsIn, } from "./graphql.js";
 import { clientCallsIn, clientLocalsIn } from "./client.js";
@@ -94,6 +94,20 @@ const REASONS = {
     routeIdCollision: "this route's method and path are identical to one already emitted, so it collapsed onto " +
         "the same API_ROUTE node and this declaration's own SERVES_API edge and location were " +
         "dropped. The endpoint is real; this specific declaration is not the one the graph kept.",
+    routeHandlerUnresolved: "this route's handler does not resolve to a callable declaration this run could name. A " +
+        "decorator's handler is read straight off the parse tree, not inferred, so a genuine miss " +
+        "here is a real gap rather than a guess.",
+    routeHandlerCrossFile: "this view does not resolve to a declaration in the same file as its route registration -- " +
+        "imported from elsewhere, a name this file does not declare, or (for a class-based view) a " +
+        "class whose verb methods live in another file or are inherited rather than written here. " +
+        "Naming the exact function that serves this route would need a second import hop, which this " +
+        "pass does not add -- the same decline already made for this file's own HTTP-verb dispatch " +
+        "read (a cross-file class-based view defaults to GET rather than inspecting an imported " +
+        "class's methods). The route is real; which function serves it is unreadable from here.",
+    drfActionNotOverridden: "this DRF action comes from the router's own fixed contract (DefaultRouter/SimpleRouter " +
+        "always generate it), not from the viewset's own body. Its method is inherited from DRF's " +
+        "installed ModelViewSet/mixins -- outside the analysed set entirely -- unless this viewset " +
+        "overrides it in source, where it isn't.",
     djangoPathNotLiteral: "a Django path()/re_path()/url() call whose route is written as anything but a literal — " +
         "or, for re_path()/url(), a regex this reader will not translate because it is not just a " +
         "literal segment with named groups. Emitting a route here would attach a caller to a path " +
@@ -102,6 +116,14 @@ const REASONS = {
         "analysed — an installed app, a module outside the analysed set, or a name this reader does " +
         "not evaluate (a computed string, a (module, namespace) tuple). The routes behind it are real " +
         "and unreadable from here.",
+    djangoMethodNotDeclared: "a urlconf entry names no HTTP verb, and this run could not read one from source either — " +
+        "no @require_http_methods/@require_GET/@require_POST/@api_view decorator on the view, and " +
+        "(for a class-based view) no verb-named method readable on the class, whether declared in " +
+        "this file or one import hop away. Django dispatches by matching the request's own method " +
+        "against the view at runtime; nothing in source states a single verb here. `attrs.method` " +
+        "is recorded as GET and `attrs.methodDeclared` is false so that default is never mistaken " +
+        "for a declaration: a real POST to this path will never match this route, and an unrelated " +
+        "GET caller silently could.",
     odooPathNotLiteral: "an @http.route(...) whose path is written as anything but a literal, so the path it serves " +
         "is not knowable from source.",
     odooMethodsNotLiteral: "an @http.route(...) whose methods= is written but not readable as a list of literals — " +
@@ -728,6 +750,40 @@ export function extract(input) {
             ...(attrs === undefined ? {} : { attrs }),
         });
     };
+    /**
+     * A route's handler, resolved to the callable declaration it names —
+     * always in the SAME file as the lookup key, never across an import.
+     *
+     * Every route-serving pass in this file (FastAPI/Flask decorators, Odoo,
+     * Django's per-verb class-based-view dispatch) already resolves a
+     * decorator's or `urlpatterns` entry's handler this way, restricted to one
+     * file's own `byFullName` map — `djangoRouteMethods`, above, is the
+     * precedent: a class-based view whose verb methods live in another file
+     * stays at the GET default rather than following the import. The
+     * route -> handler `CALLS` edge below stays consistent with that: a name
+     * this run cannot bind to a same-file declaration is disclosed, never
+     * chased across a module boundary it does not already follow.
+     */
+    function resolveSameFileHandler(file, fullName) {
+        const found = byFullName.get(file)?.get(fullName);
+        return found !== undefined && isCallableNodeType(found.type) ? found : undefined;
+    }
+    /**
+     * Route -> handler, golden pattern 19. Unlike Express (`adapter-typescript`),
+     * which needs a recurrence guard because a handler argument can be shared,
+     * route-agnostic terminal middleware, Python's decorator form has no such
+     * ambiguity: the function directly beneath `@router.get(...)` unambiguously
+     * IS that route's handler, however many other routes decorate it too. No
+     * recurrence check is ported here.
+     */
+    const emitHandlerCalls = (routeId, handler, rawTarget, file, line, reason, level) => {
+        if (handler !== undefined) {
+            push({ from: routeId, to: handler.id, type: "CALLS" }, level);
+        }
+        else {
+            disclose({ id: routeId }, "CALLS", rawTarget, file, line, reason);
+        }
+    };
     // --- pass 1: nodes --------------------------------------------------------
     for (const file of files) {
         const parsed = input.parsed.files[file];
@@ -1137,6 +1193,49 @@ export function extract(input) {
             .filter((target) => target !== undefined && isTypeLikeNodeType(target.type));
         return candidates.length === 1 ? candidates[0] : undefined;
     }
+    const localAnnotationIndex = new Map();
+    const localAnnotationsOf = (file, local) => {
+        let index = localAnnotationIndex.get(file);
+        if (index === undefined) {
+            index = new Map();
+            for (const entry of input.parsed.files[file]?.localAnnotations ?? []) {
+                const bucket = index.get(entry.local);
+                if (bucket === undefined)
+                    index.set(entry.local, [entry]);
+                else
+                    bucket.push(entry);
+            }
+            localAnnotationIndex.set(file, index);
+        }
+        return index.get(local) ?? [];
+    };
+    /**
+     * A local variable's *own* type annotation — `org: Organization | None =
+     * await get_org_for_user(...)` inside a function body. Neither
+     * `instantiatedType` (a bare constructor call only) nor
+     * `parameterAnnotatedType` (a function parameter only) can see this shape;
+     * it is the actual root cause of UAT round 4's missed defect
+     * (`sherpa-backend`'s `src/apis/reviews.py`: `org` is a local, not a
+     * parameter, and its annotation was never read at all).
+     *
+     * Same scope discipline as `instantiatedType` — innermost enclosing scope
+     * wins over a module-level annotation of the same name — and the same
+     * "exactly one type-like candidate" discipline `parameterAnnotatedType`
+     * already applies: `Optional[X]`, `X | None` and `Union[X, Y]` all still
+     * resolve to nothing where more than one type-like name survives.
+     */
+    function localAnnotatedType(file, scopePath, local) {
+        const scopeKey = scopePath.join(".");
+        const inScope = localAnnotationsOf(file, local).filter((a) => a.scope.length === 0 || a.scope.join(".") === scopeKey);
+        const chosen = inScope.find((a) => a.scope.length > 0 && a.scope.join(".") === scopeKey) ??
+            inScope.find((a) => a.scope.length === 0);
+        if (chosen === undefined)
+            return undefined;
+        const candidates = typeNamesIn(chosen.annotation)
+            .map((name) => followName(file, name))
+            .filter((target) => target !== undefined && isTypeLikeNodeType(target.type));
+        return candidates.length === 1 ? candidates[0] : undefined;
+    }
     /**
      * Is "this attribute is not declared" a claim this adapter can actually
      * stand behind for this type?
@@ -1180,6 +1279,28 @@ export function extract(input) {
             return baseChainIsFieldFree(receiverType.file, leaf);
         });
     }
+    /**
+     * Is this a read of `BaseModel`'s own surface, reached through a
+     * Pydantic-classified receiver (the same classification
+     * `attributeExistenceIsProvable` uses, not SQLAlchemy's)?
+     *
+     * `baseChainIsFieldFree` treats any unresolvable base as field-free —
+     * correct for SQLAlchemy's `DeclarativeBase` marker, but not for
+     * `BaseModel`, which is equally unresolvable-in-repo yet has a real,
+     * stable member set of its own (`model_dump`, `model_fields_set`, ...).
+     * Rather than changing `baseChainIsFieldFree` itself — which would also
+     * change the SQLAlchemy path, and that path's assumption is correct —
+     * this is checked narrowly at the one call site that turns "not a
+     * declared field" into a reported `unresolvedFields` fact.
+     */
+    function isPydanticModelMember(receiverType, name) {
+        if (!PYDANTIC_MODEL_MEMBERS.has(name))
+            return false;
+        const orm = ormShapes.get(receiverType.id);
+        if (orm !== undefined)
+            return false; // SQLAlchemy (or another ORM) — untouched, not this path
+        return dtoShapes.has(receiverType.id) && isPydanticClass(receiverType.file, receiverType.declaration.path[0] ?? "");
+    }
     /**
      * Walks a class's own base chain, and is safe to "see through" only where
      * every hop is either external (nothing this run declares — the
@@ -1214,6 +1335,30 @@ export function extract(input) {
             return baseChainIsFieldFree(target.file, leaf, seen);
         });
     }
+    /**
+     * True when `declared`'s own base chain reaches `typing.Protocol` — PEP 544's
+     * explicit, syntactic declaration of a structural interface. Walked rather than
+     * checked only on the immediate base list so a Protocol that widens another
+     * Protocol (`class WiderPort(Renderer, Protocol)`) is still recognised as one;
+     * bounded the same way `baseChainIsFieldFree` bounds its own base-chain walk,
+     * since this walks the same graph and needs the same cycle guard.
+     */
+    function isProtocolDeclared(declared, seen = new Set()) {
+        const key = `${declared.file}:${declared.id}`;
+        if (seen.has(key) || seen.size > 32)
+            return false;
+        seen.add(key);
+        const bases = declared.declaration.bases ?? [];
+        return bases.some((base) => {
+            if (base === null)
+                return false;
+            const leaf = base.split("[")[0].split(".").pop();
+            if (leaf === "Protocol")
+                return true;
+            const next = followName(declared.file, leaf);
+            return next !== undefined && isProtocolDeclared(next, seen);
+        });
+    }
     for (const file of files) {
         const parsed = input.parsed.files[file];
         const byFull = byFullName.get(file);
@@ -1237,12 +1382,22 @@ export function extract(input) {
                     continue;
                 const root = base.split("[")[0].split(".").pop();
                 const target = followName(file, root);
+                // B5 (13.2.3's other half): Python has no `implements` keyword, so
+                // `adapter-typescript`'s language-level implements/extends split
+                // (extract.ts:1279) had no analogue here and every base fell to
+                // INHERITS. `typing.Protocol` is Python's own explicit, syntactic
+                // declaration of a structural interface (PEP 544) — a base that is a
+                // Protocol, directly or through another Protocol, is declared as an
+                // interface, not a concrete implementation to inherit. Matched to
+                // what the source declares, never inferred from behaviour (rule 1's
+                // "if the framework will tell you, never infer it").
+                const edgeType = root === "Protocol" || (target !== undefined && isProtocolDeclared(target)) ? "IMPLEMENTS" : "INHERITS";
                 if (target === undefined) {
-                    disclose(self, "INHERITS", root, file, declaration.range.startLine, "outside");
+                    disclose(self, edgeType, root, file, declaration.range.startLine, "outside");
                     continue;
                 }
                 if (target.id !== self.id)
-                    push({ from: self.id, to: target.id, type: "INHERITS" }, 2);
+                    push({ from: self.id, to: target.id, type: edgeType }, 2);
             }
         }
         // --- calls, method calls, and the tests that make them ------------------
@@ -1821,8 +1976,10 @@ export function extract(input) {
                 // exactly this, and two producers of one route must mint the same
                 // endpoint id or the join this whole lane exists for does not happen.
                 const routeId = nodeId(scope, "API_ROUTE", `${method} ${served}`, LANGUAGE);
+                let isNewRoute = false;
                 if (!routeSeen.has(routeId)) {
                     routeSeen.add(routeId);
+                    isNewRoute = true;
                     nodes.push({
                         id: routeId,
                         type: "API_ROUTE",
@@ -1856,6 +2013,18 @@ export function extract(input) {
                     // one declaration exists".
                     disclose(from, "SERVES_API", `${method} ${served}`, route.file, route.line, "routeIdCollision");
                 }
+                // Route -> handler, golden pattern 19. Only for the declaration that
+                // actually won the node above — the second of two declarations
+                // colliding on one method+path already lost its SERVES_API edge and
+                // location just above, and letting its handler through here would
+                // attach an unrelated function to a route it does not own.
+                if (isNewRoute) {
+                    const handler = route.handler === null ? undefined : resolveSameFileHandler(route.file, route.handler.join("."));
+                    emitHandlerCalls(routeId, handler, route.handler === null ? `${method} ${served}` : route.handler.join("."), route.file, route.line, "routeHandlerUnresolved", 0);
+                }
+                else {
+                    disclose({ id: routeId }, "CALLS", `${method} ${served}`, route.file, route.line, "routeIdCollision");
+                }
                 // **Nothing served, nothing to join.** An unmounted router's route has
                 // no real served path — `served` above is only what it *would* be at
                 // the application root, and minting a workspace-scoped `API_ENDPOINT`
@@ -1884,9 +2053,12 @@ export function extract(input) {
                             attrs: { method, pathTemplate: normaliseEndpointPath(served) },
                         });
                     }
-                    // `SERVES_API` and nothing else *to the endpoint*. Golden pattern 04
-                    // asserts this edge alone, and a route-to-handler edge would be a
-                    // second claim with no golden behind it and no draw measuring it.
+                    // `SERVES_API` and nothing else *to the endpoint*, per golden
+                    // pattern 04. The route -> handler half is a separate edge to a
+                    // separate target (the FUNCTION, not the fileless API_ENDPOINT) —
+                    // golden pattern 19's own CALLS assertion, emitted above regardless
+                    // of `mounted`: which function a decorator sits on is a fact about
+                    // the declaration, not about whether anything ends up serving it.
                     push({ from: routeId, to: endpointId, type: "SERVES_API" }, level);
                 }
                 // The route's contract: which validated shapes it names. `USES_TYPE`
@@ -1910,7 +2082,19 @@ export function extract(input) {
                     const { request, response } = routeContractNames(route);
                     for (const name of new Set([...request, ...response])) {
                         const target = followName(route.file, name);
-                        if (target === undefined || !dtoShapes.has(target.id))
+                        // B8: distinguished from the silent case just below. A name this run
+                        // cannot resolve at all (an external library type, or a name outside
+                        // the analysed file set) is a genuine resolution gap and worth
+                        // measuring — this is the "unresolved name" half of the three-way
+                        // breakdown 13.3.18 asked for. A name that DOES resolve but is not a
+                        // validated shape stays silent: that route parameter was never
+                        // expected to be a DTO, and disclosing it would manufacture noise
+                        // about a relationship nothing claimed existed.
+                        if (target === undefined) {
+                            disclose({ id: routeId }, "USES_TYPE", name, route.file, route.line, "outside");
+                            continue;
+                        }
+                        if (!dtoShapes.has(target.id))
                             continue;
                         const roles = [];
                         if (request.has(name))
@@ -1994,35 +2178,140 @@ export function extract(input) {
             djangoPrefixCache.set(startFile, result);
             return result;
         };
+        /**
+         * A method restriction Django's own decorators state outright —
+         * `require_GET`/`require_POST` (bare, no call) and
+         * `require_http_methods([...])`/DRF's `api_view([...])` (a call whose
+         * one positional argument is a list of verbs). A real declaration, read
+         * from the decorator's own arguments — never inferred from the view's
+         * name or body. `null` means no such decorator sits on this declaration,
+         * not "GET" — the two are different facts and the caller must not
+         * collapse them.
+         */
+        function declaredHttpMethods(declaration) {
+            for (const decorator of declaration.decorators ?? []) {
+                const leaf = (decorator ?? "").split(".").pop();
+                if (leaf === "require_GET")
+                    return ["GET"];
+                if (leaf === "require_POST")
+                    return ["POST"];
+            }
+            for (const call of declaration.decoratorCalls ?? []) {
+                const leaf = (call.callee ?? "").split(".").pop();
+                if (leaf !== "require_http_methods" && leaf !== "api_view")
+                    continue;
+                const list = call.argLists?.[0];
+                if (list === undefined || list === null)
+                    continue;
+                const methods = list
+                    .filter((m) => typeof m === "string")
+                    .map((m) => m.toUpperCase());
+                if (methods.length > 0)
+                    return methods;
+            }
+            return null;
+        }
+        /**
+         * The declaration a Django view reference names, following the same
+         * one-hop import chain every cross-file lookup in this pass already
+         * walks (`followName`, used above for a route's own DTO names) — not a
+         * new resolution mechanism. `text` is the view argument's source text:
+         * a bare name (`my_view`) resolves directly; `module.attr` (`views.my_view`)
+         * takes one further hop through the module's own binding, since
+         * `followName`/`bindingsOf` are keyed by the imported local name and a
+         * dotted attribute access never appears as one.
+         */
+        function resolveViewDeclaration(file, text) {
+            const direct = followName(file, text);
+            if (direct !== undefined)
+                return direct;
+            const dot = text.lastIndexOf(".");
+            if (dot === -1)
+                return undefined;
+            const modulePart = text.slice(0, dot);
+            const leaf = text.slice(dot + 1);
+            if (modulePart.includes("."))
+                return undefined; // one hop, matching classFileOf's own precedent
+            const binding = bindingsOf.get(file)?.get(modulePart);
+            if (binding === undefined)
+                return undefined;
+            return declaredIn.get(binding.file)?.get(leaf);
+        }
         /**
          * A urlconf entry names no verb — Django dispatches by looking at the
-         * request, not the registration. Defaulting to GET matches this file's
-         * own precedent for Flask's undecorated `.route()` (`GENERIC_ROUTE_ATTRS`,
-         * above). Upgraded when the view is a same-file class-based view whose
-         * body itself declares HTTP-verb-named methods — Django's actual
-         * dispatch mechanism (`View.dispatch` calls `getattr(self,
-         * request.method.lower())`), read from source rather than guessed.
-         * Cross-file CBVs and function-based views stay at the GET default —
-         * resolving an imported class's own methods is a second import hop this
-         * pass does not add.
+         * request, not the registration. `declared: false` is what carries that
+         * fact forward; `["GET"]` alone would look identical to a genuinely
+         * declared one.
+         *
+         * Three real declarations, in the order checked:
+         *
+         * 1. A method-restricting decorator on the view function itself —
+         *    `require_GET`/`require_POST`/`require_http_methods`/`api_view`.
+         * 2. A class-based view's own verb-named methods — Django's actual
+         *    dispatch mechanism (`View.dispatch` calls `getattr(self,
+         *    request.method.lower())`), read from source rather than guessed.
+         *    Same file first; `classFileOf` — the chain every ORM/DTO/test-suite
+         *    base lookup in this file already walks — follows one import hop
+         *    (and, same as those callers, further re-export hops up to its own
+         *    depth cap) when the class is registered from a different module
+         *    than it is defined in.
+         * 3. Neither: `declared: false`, GET recorded as the default it is.
          */
         const djangoRouteMethods = (route) => {
-            if (route.viewClassLocal === null)
-                return ["GET"];
-            const declarations = input.parsed.files[route.file]?.declarations ?? [];
+            if (route.viewClassLocal === null) {
+                const target = resolveViewDeclaration(route.file, route.viewText);
+                const decorated = target === undefined ? null : declaredHttpMethods(target.declaration);
+                return decorated !== null
+                    ? { methods: decorated, declared: true }
+                    : { methods: ["GET"], declared: false };
+            }
+            const owner = classFileOf(route.file, route.viewClassLocal);
+            const declarations = owner === undefined ? [] : (input.parsed.files[owner]?.declarations ?? []);
             const found = declarations
                 .filter((d) => d.kind === "function" &&
                 d.path.length === 2 &&
                 d.path[0] === route.viewClassLocal &&
                 HTTP_METHODS.has(d.path[1]))
                 .map((d) => d.path[1].toUpperCase());
-            return found.length > 0 ? found : ["GET"];
+            return found.length > 0 ? { methods: found, declared: true } : { methods: ["GET"], declared: false };
+        };
+        /**
+         * The specific function this verb's route calls — using exactly the same
+         * resolution reach `djangoRouteMethods` uses to find the verb in the
+         * first place, so the two stay consistent by construction rather than by
+         * a second check: a class-based view resolves through `classFileOf`
+         * (same one-hop-across-an-import allowance `djangoRouteMethods` applies
+         * when reading its verb methods), and a function-based view resolves
+         * through `resolveViewDeclaration` (the same one used to read a bare or
+         * `module.attr` view's decorators). Either can still fail — a target
+         * this run cannot bind to a real declaration, or one that resolves to
+         * something not callable — and that failure is disclosed, never guessed.
+         */
+        const djangoRouteHandler = (route, method) => {
+            if (route.viewClassLocal !== null) {
+                const owner = classFileOf(route.file, route.viewClassLocal);
+                const fullName = `${route.viewClassLocal}.${method.toLowerCase()}`;
+                return {
+                    declared: owner === undefined ? undefined : resolveSameFileHandler(owner, fullName),
+                    rawTarget: fullName,
+                    reason: "routeHandlerCrossFile",
+                };
+            }
+            const rawTarget = route.viewText.trim();
+            const target = resolveViewDeclaration(route.file, rawTarget);
+            return {
+                declared: target !== undefined && isCallableNodeType(target.type) ? target : undefined,
+                rawTarget,
+                reason: "routeHandlerCrossFile",
+            };
         };
-        const emitDjangoRoute = (file, line, served, method, level, framework) => {
+        const emitDjangoRoute = (file, line, served, method, methodDeclared, level, framework, handler) => {
             const from = { id: moduleNodeId.get(file) };
             const routeId = nodeId(scope, "API_ROUTE", `${method} ${served}`, LANGUAGE);
+            let isNewRoute = false;
             if (!routeSeen.has(routeId)) {
                 routeSeen.add(routeId);
+                isNewRoute = true;
                 nodes.push({
                     id: routeId,
                     type: "API_ROUTE",
@@ -2032,12 +2321,32 @@ export function extract(input) {
                     language: LANGUAGE,
                     producedBy: input.producedBy,
                     resolution: level,
-                    attrs: { method, pathTemplate: normaliseEndpointPath(served), rawTemplate: served, framework },
+                    attrs: {
+                        method,
+                        pathTemplate: normaliseEndpointPath(served),
+                        rawTemplate: served,
+                        framework,
+                        methodDeclared,
+                    },
                 });
+                if (!methodDeclared) {
+                    disclose(from, "SERVES_API", `${method} ${served}`, file, line, "djangoMethodNotDeclared");
+                }
             }
             else {
                 disclose(from, "SERVES_API", `${method} ${served}`, file, line, "routeIdCollision");
             }
+            if (handler !== undefined) {
+                if (isNewRoute) {
+                    emitHandlerCalls(routeId, handler.declared, handler.rawTarget, file, line, handler.reason, 0);
+                }
+                else {
+                    // Consistent with the SERVES_API drop just above: the second of two
+                    // declarations colliding on one method+path does not get to claim a
+                    // handler either.
+                    disclose({ id: routeId }, "CALLS", `${method} ${served}`, file, line, "routeIdCollision");
+                }
+            }
             const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(method, served), null);
             if (!routeSeen.has(endpointId)) {
                 routeSeen.add(endpointId);
@@ -2070,8 +2379,9 @@ export function extract(input) {
             if (level > input.reached)
                 continue;
             const served = joinPath(chain.prefix, route.path);
-            for (const method of djangoRouteMethods(route)) {
-                emitDjangoRoute(route.file, route.line, served, method, level, "django");
+            const { methods, declared } = djangoRouteMethods(route);
+            for (const method of methods) {
+                emitDjangoRoute(route.file, route.line, served, method, declared, level, "django", djangoRouteHandler(route, method));
             }
         }
         // --- DRF: router.register(prefix, ViewSetClass) — the fixed action table
@@ -2098,7 +2408,18 @@ export function extract(input) {
             const basePath = joinPath(chain.prefix, reg.prefix);
             for (const action of DRF_ACTIONS) {
                 const served = joinPath(basePath, action.suffix);
-                emitDjangoRoute(reg.file, reg.line, served, action.method, level, "django");
+                // The router's own fixed action table, not a guess — every one of
+                // these methods is genuinely declared by registering the viewset.
+                // Handler resolution is same-file only: `action.action` is DRF's own
+                // dispatch method name, and resolving it finds only the (uncommon)
+                // case where this viewset overrides it in source rather than
+                // inheriting it from DRF's own installed mixins.
+                const fullName = `${reg.viewSetText.trim()}.${action.action}`;
+                emitDjangoRoute(reg.file, reg.line, served, action.method, true, level, "django", {
+                    declared: resolveSameFileHandler(reg.file, fullName),
+                    rawTarget: fullName,
+                    reason: "drfActionNotOverridden",
+                });
             }
         }
         // --- Odoo: @http.route(...) — path already absolute, nothing to resolve -
@@ -2116,8 +2437,10 @@ export function extract(input) {
             const served = normaliseEndpointPath(route.path).startsWith("/") ? route.path : `/${route.path}`;
             for (const method of route.methods) {
                 const routeId = nodeId(scope, "API_ROUTE", `${method} ${served}`, LANGUAGE);
+                let isNewRoute = false;
                 if (!routeSeen.has(routeId)) {
                     routeSeen.add(routeId);
+                    isNewRoute = true;
                     nodes.push({
                         id: routeId,
                         type: "API_ROUTE",
@@ -2133,6 +2456,13 @@ export function extract(input) {
                 else {
                     disclose(from, "SERVES_API", `${method} ${served}`, route.file, route.line, "routeIdCollision");
                 }
+                if (isNewRoute) {
+                    const handler = route.handler === null ? undefined : resolveSameFileHandler(route.file, route.handler.join("."));
+                    emitHandlerCalls(routeId, handler, route.handler === null ? `${method} ${served}` : route.handler.join("."), route.file, route.line, "routeHandlerUnresolved", 0);
+                }
+                else {
+                    disclose({ id: routeId }, "CALLS", `${method} ${served}`, route.file, route.line, "routeIdCollision");
+                }
                 const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(method, served), null);
                 if (!routeSeen.has(endpointId)) {
                     routeSeen.add(endpointId);
@@ -2244,7 +2574,7 @@ export function extract(input) {
                         const level = (field.file === schema.file ? 0 : 1);
                         if (level > input.reached)
                             continue;
-                        emitDjangoRoute(field.file, field.line, operationPath(slot, field.name), GRAPHQL_METHOD, level, "strawberry");
+                        emitDjangoRoute(field.file, field.line, operationPath(slot, field.name), GRAPHQL_METHOD, true, level, "strawberry");
                     }
                 }
             }
@@ -2354,11 +2684,15 @@ export function extract(input) {
             if (container === undefined || container.type !== "FUNCTION")
                 continue;
             // A local instantiation (`org = Organization()`) first, a parameter's
-            // own annotation (`def get(org: Organization)`) second — the ground
-            // truth this pass exists to catch is the second shape, which
-            // `instantiatedType` alone has never been able to see.
+            // own annotation (`def get(org: Organization)`) second, a local
+            // variable's own annotation (`org: Organization | None = await
+            // get_org_for_user(...)`) third — the ground truth this pass exists to
+            // catch is the third shape (`sherpa-backend`'s `src/apis/reviews.py`),
+            // which neither `instantiatedType` nor `parameterAnnotatedType` alone
+            // has ever been able to see.
             const receiverType = instantiatedType(file, reference.scope, reference.receiver) ??
-                parameterAnnotatedType(container, reference.receiver);
+                parameterAnnotatedType(container, reference.receiver) ??
+                localAnnotatedType(file, reference.scope, reference.receiver);
             if (receiverType === undefined)
                 continue;
             // **A mapped column is a declared member, and `fields` cannot see one.**
@@ -2371,6 +2705,13 @@ export function extract(input) {
                 (ormShapes.get(receiverType.id)?.fields ?? []).some((f) => f.name === reference.name);
             if (!declaresField && !attributeExistenceIsProvable(receiverType))
                 continue;
+            // `BaseModel`'s own members (`model_dump`, `model_fields_set`, ...) are
+            // not a declared field, but they are also not an undeclared one — see
+            // `isPydanticModelMember`. Neither `fields` (a data-field claim) nor
+            // `unresolvedFields` (an absence claim) fits; the read is simply not
+            // evidence either way, so it contributes nothing to this edge.
+            if (!declaresField && isPydanticModelMember(receiverType, reference.name))
+                continue;
             const edgeType = isWrite ? "WRITES" : "READS";
             const key = `${container.id}|${receiverType.id}|${edgeType}`;
             const entry = fieldsByEdge.get(key) ?? {