@descryy/adapter-python 0.5.2 → 0.6.0

package/dist/extract.js

@@ -35,6 +35,7 @@ import { importRoots, modulePathOf, moduleNameOf, resolveImport, } from "./modul
 import { attributeExternal, externalImportTable, ownNamespaces, STDLIB_BASIS, } from "./external.js";
 import { DECLARATIVE_BASE_FACTORIES, ORM_BASE_MODULES, isFrameworkBaseName, ormShapeOf, } from "./orm.js";
 import { globToRegExp, PYTEST_DEFAULTS } from "./pytest-config.js";
+import { celeryProducerCallsIn, celeryTaskDeclarationsIn } from "./celery.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";
@@ -55,6 +56,70 @@ const EXTERNAL_RESOLUTION = 1;
  * and 83% of its edges claimed a level they had not earned.
  */
 const CONFIDENCE = { 0: 0.5, 1: 0.7, 2: 0.9, 3: 0.95 };
+// --- Django page rendering (golden pattern 23) ------------------------------
+/** `django.shortcuts.render`/`render_to_response` — provenance, not a name
+ *  guess, the same standing `ORM_BASE_MODULES` has for a MODEL base. */
+const DJANGO_RENDER_MODULES = new Set(["django.shortcuts"]);
+const DJANGO_TEMPLATE_RESPONSE_MODULES = new Set(["django.template.response"]);
+const DJANGO_VIEW_MODULES = new Set([
+    "django.views.generic",
+    "django.views.generic.base",
+    "django.views.generic.list",
+    "django.views.generic.detail",
+    "django.views.generic.edit",
+]);
+const DJANGO_VIEW_BASE_NAMES = new Set([
+    "View",
+    "TemplateView",
+    "ListView",
+    "DetailView",
+    "CreateView",
+    "UpdateView",
+    "DeleteView",
+    "FormView",
+]);
+/** A positional argument's own written constant, when `extract.py` read one. */
+function positionalLiteral(call, index) {
+    if (call.hasLiterals[index] !== true)
+        return undefined;
+    const value = call.literals[index];
+    return typeof value === "string" ? value : undefined;
+}
+function keywordLiteral(call, key) {
+    const value = call.keywords[key];
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * The page template a function-based Django view's call names, or the three
+ * states rule 2/rule 7 require: `undefined` — not a render-family call at
+ * all, silently skipped; `null` — a recognised render call whose template
+ * argument is not a bare literal, disclosed; a `string` — the template name,
+ * read straight off the call.
+ *
+ * `render(request, template_name, …)` / `render_to_response(template_name,
+ * …)` / `TemplateResponse(request, template, …)` are Django's own three, each
+ * gated on the callee's own import — `from django.shortcuts import render`
+ * states the provenance in the file, needing no cross-file resolution at all.
+ */
+function djangoPageTemplateOfCall(call, imports) {
+    const callee = call.callee;
+    if (callee === null)
+        return undefined;
+    const root = callee.split(".")[0];
+    const leaf = callee.split(".").pop();
+    const importedFrom = (modules) => imports.some((record) => modules.has(record.module ?? "") && (record.local === root || record.local === leaf));
+    if ((leaf === "render" || leaf === "render_to_response") && importedFrom(DJANGO_RENDER_MODULES)) {
+        const template = leaf === "render"
+            ? (positionalLiteral(call, 1) ?? keywordLiteral(call, "template_name"))
+            : (positionalLiteral(call, 0) ?? keywordLiteral(call, "template_name"));
+        return template ?? null;
+    }
+    if (leaf === "TemplateResponse" && importedFrom(DJANGO_TEMPLATE_RESPONSE_MODULES)) {
+        const template = positionalLiteral(call, 1) ?? keywordLiteral(call, "template");
+        return template ?? null;
+    }
+    return undefined;
+}
 const REASONS = {
     outside: "resolves to a name this run did not analyse — the standard library, an installed package, " +
         "or a module outside the analysed set. A scope boundary, not an analysis gap.",
@@ -133,6 +198,10 @@ const REASONS = {
         "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.",
+    celeryTaskNameNotLiteral: "a Celery task decorator (@app.task/@shared_task) whose name= is written but is not a " +
+        "literal, so the queue name Celery actually registers this task under is not knowable from " +
+        "source — nor is the module-qualified default, since a written name= always wins it. " +
+        "Emitting a queue here would attach a producer to a topic that does not exist.",
     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 — " +
@@ -153,6 +222,21 @@ const REASONS = {
     graphqlRootSlotUnreadable: "a strawberry.Schema(...) whose query=/mutation=/subscription= slot is written as something " +
         "other than a bare class name, so the root type it puts in that slot cannot be followed. " +
         "The operations under it are real and unreadable from here.",
+    grpcServicerHandlerUnresolved: "this RPC's servicer implementation does not resolve to a class method declared in this same " +
+        "file — the impl argument is not a bare constructor call or a local this file binds to one, " +
+        "the resolved class does not declare a method of this exact name, or the servicer is " +
+        "constructed and registered from two different files, which this reader does not follow " +
+        "(the same same-file-only restriction every other route -> handler edge in this adapter " +
+        "already holds itself to). The route is real; the code implementing it is not established.",
+    djangoRenderTemplateNotLiteral: "a Django render()/render_to_response()/TemplateResponse() call, or a class-based view's own " +
+        "template_name, whose template argument is not a bare string literal — computed, an f-string, " +
+        "or a name bound earlier. A computed template name is not a written fact (rule 2): emitting a " +
+        "PAGE for it would name a template that may not exist under that path at all.",
+    djangoTemplateFileNotFound: "the template name is a written literal, but no file under an app's own templates/ directory " +
+        "or a project-level templates/ directory matches it. The IR boundary requires a PAGE's file " +
+        "to be a real, batch-scoped path, so rule 2 discloses the render instead of minting a node " +
+        "with none — the name may be assembled at a template-loader search path this reader does not " +
+        "evaluate, or the template may simply not exist in this repository.",
 };
 // --- pytest -----------------------------------------------------------------
 /**
@@ -608,6 +692,43 @@ export function extract(input) {
         }
         return false;
     }
+    /**
+     * Is this class a Django generic view — golden pattern 23's class-based
+     * form? Same shape as `isTestSuiteClass`/`ormFrameworkOf`'s rule 1 and rule
+     * 3: the base's own name has to match a known Django view AND come from a
+     * `django.views.generic*` import (provenance, not a name guess), followed
+     * across files the same way a shared in-repo base class already is for a
+     * MODEL or a test suite.
+     */
+    function isDjangoViewClass(file, name, seen = new Set()) {
+        const key = `${file}:${name}`;
+        if (seen.has(key) || seen.size > 32)
+            return false;
+        seen.add(key);
+        const bases = basesOf.get(file)?.get(name);
+        if (bases === undefined)
+            return false;
+        const parsed = input.parsed.files[file];
+        for (const base of bases) {
+            if (base === "")
+                continue;
+            const root = base.split(".")[0];
+            const leaf = base.split(".").pop();
+            if (DJANGO_VIEW_BASE_NAMES.has(leaf)) {
+                const fromDjango = parsed.imports.some((record) => {
+                    if (!DJANGO_VIEW_MODULES.has(record.module ?? ""))
+                        return false;
+                    return record.local === root || record.local === leaf;
+                });
+                if (fromDjango)
+                    return true;
+            }
+            const owner = classFileOf(file, leaf);
+            if (owner !== undefined && isDjangoViewClass(owner, leaf, seen))
+                return true;
+        }
+        return false;
+    }
     // --- which classes are ORM models, decided from evidence not from names ----
     //
     // The same three-rule shape as `isTestSuiteClass`, with rule 2 deliberately
@@ -1206,8 +1327,107 @@ export function extract(input) {
     // or compares a shape, so R2 was over-claiming and R3 would be the inflation
     // DEC-058 removed once already.
     emitRoutes();
+    // --- gRPC (DEC-NEXT-grpc-client-and-queue-endpoint-convention) -------------
+    //
+    // Its own pass, not folded into `emitRoutes()`: a gRPC service has no HTTP
+    // verb, no mount chain and no decorator — the generated `_pb2_grpc.py` file
+    // is the whole of its evidence, read the same way `adapter-go`'s reader
+    // reads `_FullMethodName` consts, never assembled from an unrelated name.
+    emitGrpc();
     if (input.reached < 1)
         return { nodes, edges, unresolved };
+    // --- Django page rendering (golden pattern 23) ------------------------------
+    //
+    // A backend handler renders a page directly through Django's own render
+    // call — `render(request, "orders/index.html")` / `render_to_response(...)`
+    // / `TemplateResponse(request, "...")` — or, for a class-based view, through
+    // its own `template_name = "..."` class attribute (`TemplateView`,
+    // `ListView`, `DetailView`, …). Both R1: a written, unambiguous instruction
+    // read directly off the call site or the class body, with no cross-file
+    // resolution beyond confirming the base class's own import — the same
+    // standing `ormFrameworkOf`'s rule 1 already has for a `MODEL` base.
+    //
+    // NOT built here: `SomeView.as_view(template_name="...")` written directly
+    // in `urls.py`, overriding a class's own `template_name` at the URL level —
+    // a disclosed scope reduction, not a silent gap. This reader mints the
+    // CLASS's own `template_name` when it declares one; a URL-level override
+    // needs following a nested call one hop further than this pass does, and is
+    // left for a future lane (see `DEC-NEXT-server-rendered-page-extractor-capability.md`).
+    {
+        const pageSeen = new Set();
+        const templateFiles = input.templateFiles ?? new Map();
+        // The IR boundary rejects a PAGE with `file: null` (`MISSING_FILE`) — see
+        // `documents/decisions-inbox/DEC-NEXT-server-rendered-page-file-is-its-template.md`
+        // in descry-core. A template NAME is not enough; only a real file
+        // confirmed present under a templates/ directory backs a PAGE at all —
+        // rule 2: when no such file exists, disclose the render as unresolved
+        // rather than mint a node the IR would drop anyway.
+        const mintDjangoPage = (declared, templateName, level, file, line) => {
+            const templateFile = templateFiles.get(templateName);
+            if (templateFile === undefined) {
+                disclose(declared, "RETURNS", templateName, file, line, "djangoTemplateFileNotFound");
+                return;
+            }
+            const pageId = nodeId(scope, "PAGE", symbolQsp(pkg, [templateName]), LANGUAGE);
+            if (!pageSeen.has(pageId)) {
+                pageSeen.add(pageId);
+                nodes.push({
+                    id: pageId,
+                    type: "PAGE",
+                    name: templateName,
+                    file: templateFile,
+                    range: null,
+                    language: LANGUAGE,
+                    producedBy: input.producedBy,
+                    resolution: level,
+                    attrs: { framework: "django" },
+                });
+            }
+            push({ from: declared.id, to: pageId, type: "RETURNS" }, level);
+        };
+        for (const file of files) {
+            const parsed = input.parsed.files[file];
+            const byName = declaredIn.get(file);
+            // Function-based views: render()/render_to_response()/TemplateResponse(),
+            // read off the module-and-one-level-deep call table `extract.py` already
+            // builds for every other framework reader in this file (route
+            // decorators, ORM Meta options, HTTP client calls).
+            for (const call of parsed.calls ?? []) {
+                if (call.scope.length !== 1)
+                    continue;
+                const declared = byName.get(call.scope[0]);
+                if (declared === undefined || declared.type !== "FUNCTION")
+                    continue;
+                const template = djangoPageTemplateOfCall(call, parsed.imports);
+                if (template === undefined)
+                    continue;
+                if (template === null) {
+                    disclose(declared, "RETURNS", call.callee ?? "(render call)", file, call.line, "djangoRenderTemplateNotLiteral");
+                    continue;
+                }
+                mintDjangoPage(declared, template, 1, file, call.line);
+            }
+            // Class-based views: a class whose own base resolves to a Django
+            // generic view, with its OWN `template_name = "..."` class attribute.
+            for (const declaration of parsed.declarations) {
+                if (declaration.kind !== "class" || declaration.path.length !== 1)
+                    continue;
+                if (!isDjangoViewClass(file, declaration.name))
+                    continue;
+                const declared = byName.get(declaration.path[0]);
+                if (declared === undefined)
+                    continue;
+                const templateAttr = (declaration.attributes ?? []).find((a) => a.name === "template_name");
+                if (templateAttr === undefined)
+                    continue;
+                if (typeof templateAttr.literal !== "string") {
+                    disclose(declared, "RETURNS", "template_name", file, templateAttr.line, "djangoRenderTemplateNotLiteral");
+                    continue;
+                }
+                mintDjangoPage(declared, templateAttr.literal, 1, file, templateAttr.line);
+            }
+        }
+    }
     // --- pass 2: import edges, off the resolution pass 0 already did ----------
     for (const file of files) {
         const fromId = moduleNodeId.get(file);
@@ -1224,6 +1444,11 @@ export function extract(input) {
     }
     if (input.reached < 2)
         return { nodes, edges, unresolved };
+    // --- Celery queues (DEC-NEXT-grpc-client-and-queue-endpoint-convention.md) -
+    //
+    // R2, same gate as the HTTP client/route passes below: producer resolution
+    // crosses files (`followName`), which needs the import graph.
+    emitQueues();
     /**
      * Follow a name to the declaration that defines it, through however many
      * package re-exports stand in the way.
@@ -2954,6 +3179,315 @@ export function extract(input) {
             }, 2);
         }
     }
+    /**
+     * gRPC — both boundary halves off `grpcio`'s own generated `_pb2_grpc.py`
+     * evidence, mirroring `adapter-go`'s `grpc.ts` exactly: the wire path is
+     * read, never assembled, and a client/server construct is admitted only by
+     * the literal generated name, corroborated against that evidence — never a
+     * name-alone guess.
+     *
+     * **Where the wire path is read.** `protoc`'s Python plugin writes the
+     * full, wire-accurate path as a literal first argument to
+     * `channel.unary_unary(...)`/`unary_stream`/`stream_unary`/`stream_stream`
+     * inside `<Service>Stub.__init__` — the Python analogue of Go's
+     * `<Service>_<Method>_FullMethodName` const. `defs` is keyed by the stub
+     * class's own name with its `Stub` suffix stripped, which is also the
+     * token `add_<Service>Servicer_to_server` embeds in its own name — the two
+     * sides of one join, read by name, never inferred.
+     *
+     * **Scope, disclosed rather than attempted and missed.** `channel.x(...)`
+     * sits inside `<Service>Stub.__init__`, one level below what `_call_record`
+     * captures unconditionally (`len(scope) <= 1`) — reached only when the
+     * generated file's own `import grpc` puts it in `deep_call_modules`
+     * (`GRPC_MODULES`, unioned into `deepCallModules` in `adapter.ts`, the
+     * same mechanism `CLIENT_MODULES` already uses for `requests`/`httpx`).
+     * The servicer impl argument to `add_<Service>Servicer_to_server(...)` is
+     * resolved only against a bare constructor call or a same-file local this
+     * file itself instantiates — never across an import, the same restriction
+     * `resolveSameFileHandler` already holds every other route -> handler edge
+     * in this adapter to. A stub or servicer stored on `self.<x>` rather than
+     * a bare local is a real, disclosed gap this pass does not reach: `visit_
+     * Assign`'s `constructions`/`instantiations` tables only ever record a
+     * bare-`Name` assignment target, matching every other caller half this
+     * adapter already reads that way.
+     */
+    function emitGrpc() {
+        if (input.reached < 2)
+            return;
+        const CHANNEL_RPC_METHODS = new Set([
+            "unary_unary",
+            "unary_stream",
+            "stream_unary",
+            "stream_stream",
+        ]);
+        const STUB_SUFFIX = /^(.+)Stub$/;
+        const SERVICER_REGISTRATION = /^add_([A-Za-z0-9_]+)Servicer_to_server$/;
+        // Service base name (the stub class's own name, `Stub` stripped) -> its
+        // methods, method name -> full wire path. Repo-wide, not per-file: the
+        // stub class and the file registering a server for it are almost always
+        // different files, the same reason `adapter-go`'s own table spans every
+        // file in a resolved package rather than just one.
+        const defs = new Map();
+        for (const file of files) {
+            const parsed = input.parsed.files[file];
+            for (const call of parsed.calls ?? []) {
+                if (call.receiver !== "channel" || call.attribute === null)
+                    continue;
+                if (!CHANNEL_RPC_METHODS.has(call.attribute))
+                    continue;
+                if (call.scope.length === 0)
+                    continue;
+                const match = STUB_SUFFIX.exec(call.scope[0]);
+                if (match === null)
+                    continue;
+                const path = call.hasLiterals[0] === true ? call.literals[0] : undefined;
+                if (typeof path !== "string" || !path.startsWith("/"))
+                    continue;
+                const method = path.slice(path.lastIndexOf("/") + 1);
+                if (method === "")
+                    continue;
+                const base = match[1];
+                const def = defs.get(base) ?? { methods: new Map() };
+                def.methods.set(method, path);
+                defs.set(base, def);
+            }
+        }
+        if (defs.size === 0)
+            return;
+        const mintEndpoint = (path) => {
+            const template = normaliseEndpointPath(path);
+            const id = nodeId(scope, "API_ENDPOINT", endpointQsp("RPC", path), null);
+            if (!routeSeen.has(id)) {
+                routeSeen.add(id);
+                nodes.push({
+                    id,
+                    type: "API_ENDPOINT",
+                    name: `RPC ${template}`,
+                    file: null,
+                    range: null,
+                    language: null,
+                    producedBy: input.producedBy,
+                    resolution: 2,
+                    attrs: { method: "RPC", pathTemplate: template },
+                });
+            }
+            return id;
+        };
+        // --- the provider's half: add_<Service>Servicer_to_server(impl, server) --
+        for (const file of files) {
+            const parsed = input.parsed.files[file];
+            for (const call of parsed.calls ?? []) {
+                if (call.attribute === null)
+                    continue;
+                const match = SERVICER_REGISTRATION.exec(call.attribute);
+                if (match === null)
+                    continue;
+                const base = match[1];
+                const def = defs.get(base);
+                // No corroborating stub evidence anywhere in the analysed set is not
+                // proof this is really a generated gRPC registration — the same
+                // naming-coincidence standard `adapter-go`'s `readGrpcRegistrations`
+                // holds itself to. Stay silent, don't disclose.
+                if (def === undefined)
+                    continue;
+                const implClass = call.argCalls[0]?.callee ??
+                    parsed.instantiations.find((i) => i.local === call.argNames[0])?.typeName;
+                for (const [method, path] of def.methods) {
+                    const template = normaliseEndpointPath(path);
+                    const name = `RPC ${path}`;
+                    const routeId = nodeId(scope, "API_ROUTE", name, LANGUAGE);
+                    if (!routeSeen.has(routeId)) {
+                        routeSeen.add(routeId);
+                        nodes.push({
+                            id: routeId,
+                            type: "API_ROUTE",
+                            name,
+                            file,
+                            range: { startLine: call.line, endLine: call.line },
+                            language: LANGUAGE,
+                            producedBy: input.producedBy,
+                            resolution: 2,
+                            attrs: { method: "RPC", pathTemplate: template, rawTemplate: path, framework: "grpc" },
+                        });
+                    }
+                    const endpointId = mintEndpoint(path);
+                    push({ from: routeId, to: endpointId, type: "SERVES_API" }, 2);
+                    const handler = implClass === undefined ? undefined : resolveSameFileHandler(file, `${implClass}.${method}`);
+                    if (handler !== undefined) {
+                        push({ from: routeId, to: handler.id, type: "CALLS" }, 2);
+                    }
+                    else {
+                        disclose({ id: routeId }, "CALLS", implClass === undefined ? `${base}.${method}` : `${implClass}.${method}`, file, call.line, "grpcServicerHandlerUnresolved");
+                    }
+                }
+            }
+        }
+        // --- the caller's half: <pkg>_pb2_grpc.<Service>Stub(channel) ------------
+        for (const file of files) {
+            const parsed = input.parsed.files[file];
+            const calls = parsed.calls ?? [];
+            // local -> service base, from `stub = order_pb2_grpc.OrderServiceStub(channel)`.
+            const stubLocals = new Map();
+            for (const construction of parsed.constructions ?? []) {
+                if (construction.callee === null)
+                    continue;
+                const leaf = construction.callee.includes(".")
+                    ? construction.callee.slice(construction.callee.lastIndexOf(".") + 1)
+                    : construction.callee;
+                const match = STUB_SUFFIX.exec(leaf);
+                if (match === null || !defs.has(match[1]))
+                    continue;
+                stubLocals.set(construction.local, match[1]);
+            }
+            if (stubLocals.size === 0)
+                continue;
+            const fileDecls = byFullName.get(file);
+            const containerFor = (scopePath) => {
+                if (fileDecls !== undefined) {
+                    for (let depth = scopePath.length; depth > 0; depth -= 1) {
+                        const found = fileDecls.get(scopePath.slice(0, depth).join("."));
+                        if (found !== undefined)
+                            return found.id;
+                    }
+                }
+                return moduleNodeId.get(file);
+            };
+            for (const call of calls) {
+                const receiver = call.receiver;
+                const attribute = call.attribute;
+                if (receiver === null || attribute === null)
+                    continue;
+                const base = stubLocals.get(receiver);
+                const path = base === undefined ? undefined : defs.get(base)?.methods.get(attribute);
+                if (path === undefined)
+                    continue;
+                const containerId = containerFor(call.scope);
+                if (containerId === undefined)
+                    continue;
+                const endpointId = mintEndpoint(path);
+                push({ from: containerId, to: endpointId, type: "USES_API", attrs: { via: attribute } }, 2);
+            }
+        }
+    }
+    /**
+     * Celery: a `@app.task`/`@shared_task`-decorated function is both the
+     * queue's registration and its handler — no separate subscribe/run
+     * correlation is needed, unlike `adapter-typescript`'s kafkajs/BullMQ
+     * reader. See `celery.ts`'s module doc for the precision tradeoff
+     * (a lighter gate than `routes.ts`'s router-provenance table) and the
+     * name-derivation rule.
+     */
+    function emitQueues() {
+        const mintedEndpoints = new Set();
+        const mintedRoutes = new Set();
+        /** Declared FUNCTION node id -> the topic Celery registers it under —
+         *  only for tasks this run could actually name a topic for. */
+        const taskTopicById = new Map();
+        const importsCelery = (imports) => imports.some((record) => {
+            const named = record.module ?? record.name;
+            return named === "celery" || (named?.startsWith("celery.") ?? false);
+        });
+        // --- Pass 1: task declarations, gated per file on that file importing
+        // `celery` at all — before any decorator text in it is even read.
+        for (const file of files) {
+            const parsed = input.parsed.files[file];
+            if (!importsCelery(parsed.imports))
+                continue;
+            const byFull = byFullName.get(file);
+            if (byFull === undefined)
+                continue;
+            for (const candidate of celeryTaskDeclarationsIn(parsed.declarations)) {
+                const declared = byFull.get(candidate.path.join("."));
+                if (declared === undefined || !isCallableNodeType(declared.type))
+                    continue;
+                if (candidate.nameOpaque) {
+                    disclose(declared, "SERVES_API", declared.name, file, candidate.line, "celeryTaskNameNotLiteral");
+                    continue;
+                }
+                const topic = candidate.explicitName ?? `${modulePathOf(file).join(".")}.${candidate.path.join(".")}`;
+                taskTopicById.set(declared.id, topic);
+                // Fileless AND language-less (DEC-014), same as every other
+                // `API_ENDPOINT` this adapter mints.
+                const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp("PUBLISH", topic), null);
+                if (!mintedEndpoints.has(endpointId)) {
+                    mintedEndpoints.add(endpointId);
+                    nodes.push({
+                        id: endpointId,
+                        type: "API_ENDPOINT",
+                        name: `PUBLISH ${topic}`,
+                        file: null,
+                        range: null,
+                        language: null,
+                        producedBy: input.producedBy,
+                        resolution: 2,
+                        attrs: { method: "PUBLISH", pathTemplate: topic },
+                    });
+                }
+                const routeId = nodeId(scope, "API_ROUTE", `queue:celery:${topic}`, LANGUAGE);
+                if (!mintedRoutes.has(routeId)) {
+                    mintedRoutes.add(routeId);
+                    nodes.push({
+                        id: routeId,
+                        type: "API_ROUTE",
+                        name: `PUBLISH ${topic}`,
+                        file,
+                        range: { startLine: candidate.line, endLine: declared.range.endLine },
+                        language: LANGUAGE,
+                        producedBy: input.producedBy,
+                        resolution: 2,
+                        attrs: { method: "PUBLISH", pathTemplate: topic, framework: "celery" },
+                    });
+                }
+                push({ from: routeId, to: endpointId, type: "SERVES_API" }, 2);
+                // The decorated function IS the handler — nothing to resolve, unlike
+                // an inline callback argument.
+                push({ from: routeId, to: declared.id, type: "CALLS" }, 2);
+            }
+        }
+        // --- Pass 2: producer call sites, now every file's tasks are known -----
+        for (const file of files) {
+            const parsed = input.parsed.files[file];
+            const calls = parsed.calls ?? [];
+            const byFull = byFullName.get(file);
+            const containerFor = (scopePath) => {
+                if (byFull !== undefined) {
+                    for (let depth = scopePath.length; depth > 0; depth -= 1) {
+                        const found = byFull.get(scopePath.slice(0, depth).join("."));
+                        if (found !== undefined)
+                            return found;
+                    }
+                }
+                const moduleId = moduleNodeId.get(file);
+                return moduleId === undefined ? undefined : { id: moduleId };
+            };
+            for (const call of celeryProducerCallsIn(calls)) {
+                // `receiver` is non-null by `celeryProducerCallsIn`'s own filter.
+                const target = followName(file, call.receiver);
+                // Not a name this run can trace at all — silently out of scope, the
+                // same as a `.add()` on a BullMQ receiver this reader never tied to
+                // a `new Queue(...)` (`adapter-typescript`'s `queues.ts`): nothing
+                // here says this is a computed *topic* name, only that this call's
+                // receiver isn't one this reader resolved.
+                if (target === undefined)
+                    continue;
+                const topic = taskTopicById.get(target.id);
+                // Resolved, but not a confirmed Celery task (or a task whose own
+                // name= this run could not read) — same silent-out-of-scope reasoning.
+                if (topic === undefined)
+                    continue;
+                const container = containerFor(call.scope);
+                if (container === undefined)
+                    continue;
+                const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp("PUBLISH", topic), null);
+                push({
+                    from: container.id,
+                    to: endpointId,
+                    type: "USES_API",
+                    attrs: { framework: "celery", via: call.attribute },
+                }, 2);
+            }
+        }
+    }
     if (input.reached < 3)
         return { nodes, edges, unresolved };
     // --- pass 3: R3 — shapes ---------------------------------------------------