@descryy/adapter-python 0.1.0 → 0.3.0

package/dist/extract.js

@@ -34,7 +34,7 @@ import { databaseTableNodesFromModel, edgeId, endpointQsp, isTypeLikeNodeType, n
 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";
@@ -85,8 +85,12 @@ const REASONS = {
     callPathFromLocal: "an HTTP call whose path is a local assembled earlier in the function. Distinguished from an " +
         "opaque path because it is reachable by further work, and filing the two together would " +
         "report one number for two populations.",
-    routeNeverMounted: "this route is declared on a router that no source file mounts, so the path it serves is " +
-        "unknowable. Commonly a plugin router mounted by the framework at runtime.",
+    routeNeverMounted: "this route is declared on a router that no source file mounts, so this run cannot prove it " +
+        "is ever served. The API_ROUTE node is still emitted, with attrs.mounted: false and the path " +
+        "it would serve if mounted at the application root with no further prefix — but no " +
+        "API_ENDPOINT or SERVES_API edge, because minting one would claim a path this application " +
+        "does not actually expose. Sometimes a real defect (a router nobody registered); sometimes a " +
+        "plugin router mounted by the framework at runtime, outside what this reader can see.",
     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.",
@@ -741,6 +745,23 @@ export function extract(input) {
             ...(parsed.migrationOps !== undefined && parsed.migrationOps.length > 0
                 ? { migrationOps: parsed.migrationOps }
                 : {}),
+            // `migrationRevision`/`migrationDownRevision`/`migrationDir`: the
+            // Alembic chain a consumer needs for "the revision graph is broken" and
+            // "this migration lives outside the migrations directory" — neither
+            // check exists yet, but both need this to exist first. `migrationDir`
+            // is the file's own containing directory, repeated here rather than
+            // left for a consumer to re-derive from `file` on the node, because
+            // deriving it is a POSIX-path detail with one right answer, not a
+            // judgement — the judgement (which directory is *the* migrations
+            // directory, and whether this one disagrees with it) stays a
+            // consumer's to make.
+            ...(parsed.migrationRevision != null
+                ? {
+                    migrationRevision: parsed.migrationRevision.revision,
+                    migrationDownRevision: parsed.migrationRevision.downRevision,
+                    migrationDir: file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : "",
+                }
+                : {}),
         };
         nodes.push({
             id: moduleId,
@@ -1092,6 +1113,172 @@ export function extract(input) {
         const target = followName(file, chosen.typeName);
         return target !== undefined && isTypeLikeNodeType(target.type) ? target : undefined;
     }
+    /**
+     * A function parameter's own declared type — the receiver-type source
+     * `instantiatedType` cannot see, because a parameter is never a bare
+     * `x = ClassName()` instantiation. `def get(org: Organization)` is exactly
+     * the shape UAT round 3's ground truth needs (`src/apis/reviews.py:31-32`
+     * reads two attributes `Organization` does not declare, on a parameter, not
+     * a local).
+     *
+     * Requires the annotation to resolve to **exactly one** type-like
+     * declaration. `Optional[Organization]`, `Organization | None` and
+     * `Union[Organization, Business]` all name more than one identifier once
+     * `typing`'s own constructors are in the mix; only the unambiguous case is
+     * read, because attributing an access to the wrong half of a union would be
+     * a worse error than not attributing it at all.
+     */
+    function parameterAnnotatedType(container, local) {
+        const param = container.declaration.params?.find((p) => p.name === local);
+        if (param === undefined)
+            return undefined;
+        const candidates = typeNamesIn(param.annotation)
+            .map((name) => followName(container.file, name))
+            .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?
+     *
+     * Two hazards, both real and both measured against a shipped framework
+     * rather than imagined:
+     *
+     * 1. **Field inheritance is not resolved anywhere in this adapter.** A
+     *    mixin's own fields never merge into a subclass's `declaration.fields`
+     *    — `class Organization(Base, TimestampMixin)` would have `created_at`
+     *    genuinely declared and this reader would not know it. Every base must
+     *    therefore resolve to *nothing in this repository* (the framework's own
+     *    external root, `BaseModel`/`Base`/`Model`) for this class's own field
+     *    list to be complete rather than partial. A base written and unreadable
+     *    (`null`) is treated the same as a resolvable in-repo one: unknown, so
+     *    unsafe.
+     * 2. **Two of the four framework shapes this adapter recognises inject
+     *    fields no source line ever names.** Django gives every model an
+     *    implicit `id`/`pk` whether or not the class declares one, and a DRF
+     *    `ModelSerializer` can populate its whole field list from
+     *    `Meta.fields = "__all__"` — `dtoShapes` holds a DRF shape and a
+     *    Pydantic shape indistinguishably (both `drfShapeOf`/`dtoShapeOf`
+     *    produce a `DtoShape`), so `isPydanticClass` is asked directly rather
+     *    than trusted from `dtoShapes`' bare presence. Plain Pydantic
+     *    (`BaseModel`, validation rejects unknown fields, no implicit ones) and
+     *    SQLAlchemy (columns are always explicit) carry neither hazard.
+     */
+    function attributeExistenceIsProvable(receiverType) {
+        const orm = ormShapes.get(receiverType.id);
+        const safeFramework = orm !== undefined
+            ? orm.framework === "sqlalchemy"
+            : dtoShapes.has(receiverType.id) &&
+                isPydanticClass(receiverType.file, receiverType.declaration.path[0] ?? "");
+        if (!safeFramework)
+            return false;
+        const bases = receiverType.declaration.bases ?? [];
+        return bases.every((base) => {
+            if (base === null)
+                return false;
+            const leaf = base.split(".").pop().split("[")[0];
+            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
+     * framework's own root, `DeclarativeBase`/`BaseModel`) or an in-repo class
+     * that itself declares no attributes of its own.
+     *
+     * The distinction this exists for: SQLAlchemy 2.0's own idiom is a
+     * **project-local, field-free** declarative base —
+     * `class Base(DeclarativeBase): pass` then `class Organization(Base):` —
+     * and treating every in-repo base as an unknown-fields hazard would refuse
+     * to ever run on exactly that shape. A base that *does* declare its own
+     * attributes (`class TimestampMixin: created_at = Column(...)`) is the
+     * genuine hazard `attributeExistenceIsProvable`'s docstring names, and
+     * still stops the walk.
+     */
+    function baseChainIsFieldFree(file, name, seen = new Set()) {
+        const key = `${file}:${name}`;
+        if (seen.has(key) || seen.size > 32)
+            return false; // a cycle or runaway depth: unsafe, not a guess
+        seen.add(key);
+        const target = followName(file, name);
+        if (target === undefined)
+            return true; // resolves to nothing this run declares: an external, framework-owned name
+        const ownFields = (target.declaration.attributes ?? []).length > 0 || (target.declaration.fields ?? []).length > 0;
+        if (ownFields)
+            return false;
+        const parentBases = target.declaration.bases ?? [];
+        return parentBases.every((base) => {
+            if (base === null)
+                return false;
+            const leaf = base.split(".").pop().split("[")[0];
+            return baseChainIsFieldFree(target.file, leaf, seen);
+        });
+    }
     for (const file of files) {
         const parsed = input.parsed.files[file];
         const byFull = byFullName.get(file);
@@ -1605,8 +1792,14 @@ export function extract(input) {
             return result;
         };
         /**
-         * Every type name a route's contract mentions — its handler's parameter
-         * annotations, its `response_model=`, and its return annotation.
+         * Every type name a route's contract mentions, split by which side of the
+         * contract wrote it — `adapter-openapi`'s own `roles` vocabulary
+         * (`adapter-openapi/src/adapter.ts` ~L355-370), matched rather than
+         * reinvented so the contract engine sees one convention from either
+         * producer. A parameter's own annotation is the request shape; a
+         * `response_model=` or the handler's return annotation is the response
+         * shape. Both are read straight off the route declaration — no inference,
+         * so no extra resolution beyond what the route pass already needs.
          *
          * Names, not resolutions: the caller decides which of them is a `DTO`. A
          * route naming a type that is not a validated shape produces no edge and
@@ -1617,17 +1810,17 @@ export function extract(input) {
             const handler = route.handler === null
                 ? undefined
                 : parsed?.declarations.find((d) => d.name === route.handler.join("."));
-            const written = [
-                route.responseModel,
-                handler?.returns ?? null,
-                ...(handler?.params ?? []).map((p) => p.annotation),
-            ];
-            const out = new Set();
-            for (const annotation of written) {
+            const request = new Set();
+            for (const param of handler?.params ?? []) {
+                for (const name of typeNamesIn(param.annotation))
+                    request.add(name);
+            }
+            const response = new Set();
+            for (const annotation of [route.responseModel, handler?.returns ?? null]) {
                 for (const name of typeNamesIn(annotation))
-                    out.add(name);
+                    response.add(name);
             }
-            return [...out];
+            return { request, response };
         };
         for (const route of routeDecls) {
             const key = lookupRouter(route.file, route.scope, route.routerLocal);
@@ -1658,9 +1851,16 @@ export function extract(input) {
             const level = (chain.level === 1 || crossesFile(route.file, route.routerLocal) ? 1 : 0);
             if (level > input.reached)
                 continue;
-            // A router nothing mounts serves nothing, and the mount is where the
-            // served path is decided. dispatch declares four such routes in a Slack
-            // plugin whose router is mounted by plugin machinery at runtime.
+            // A router nothing mounts serves nothing at the path this run can prove,
+            // and the mount is where the served path used to be decided — but a
+            // route declared on an unmounted router is a fact in its own right
+            // (UAT round 3, item 2: `documents/process/descry-notes-sherpa-backend-3.md`
+            // in `descry-core`), not a reason to withhold the node entirely. dispatch
+            // declares four such routes in a Slack plugin whose router is mounted by
+            // plugin machinery at runtime — `mounted: false` on the node is the
+            // honest fact for that case too, not a defect claim; the check that
+            // reads it decides which of the two this is, this adapter only reports
+            // what the graph can prove.
             //
             // **The guard used to fire only when the router had no prefix of its own**
             // — `!parentOf.has(key) && routers.get(key)?.prefix === ""` — which meant
@@ -1668,10 +1868,17 @@ export function extract(input) {
             // anyway. It happened to produce correct paths on flask because those
             // blueprints *are* registered, so the reasoning was unsound while the
             // answer was right, which is the combination that survives a draw.
-            if (!parentOf.has(key) && !isApplicationRouter(router)) {
+            const mounted = parentOf.has(key) || isApplicationRouter(router);
+            if (!mounted) {
                 disclose(from, "SERVES_API", `${route.methods.join("/")} ${route.path}`, route.file, route.line, "routeNeverMounted");
-                continue;
             }
+            // `prefix` is the router's own local prefix chain when nothing mounts
+            // it — real, local information (DEC-069's own standard: a fact read off
+            // this router's own declaration), never a guess about where an external
+            // caller mounts it. It is exactly the path this route would serve if
+            // mounted at the application's root with no further prefix, and
+            // `attrs.mounted` on the node below is what keeps that conditional
+            // honest rather than implied.
             const served = joinPath(prefix, route.path);
             for (const method of route.methods) {
                 // The route keeps the template AS WRITTEN in its identity and the
@@ -1695,6 +1902,13 @@ export function extract(input) {
                             pathTemplate: normaliseEndpointPath(served),
                             rawTemplate: served,
                             framework: router.framework,
+                            // A stated fact, not an inference: whether *this run's* mount
+                            // graph reaches this router. `false` is exactly the shape
+                            // "declared and not mounted" needs — a route with no
+                            // corresponding `SERVES_API` edge below, which is how "declared
+                            // but unreachable" is expressed inside the frozen 15/15
+                            // vocabulary rather than through a new edge type.
+                            mounted,
                         },
                     });
                 }
@@ -1707,29 +1921,39 @@ export function extract(input) {
                     // one declaration exists".
                     disclose(from, "SERVES_API", `${method} ${served}`, route.file, route.line, "routeIdCollision");
                 }
-                // Fileless AND language-less (DEC-014). `nodeId` throws if a fileless
-                // type is hashed with a language, which is the guard against an id that
-                // disagrees with the node it labels — a failure whose only symptom
-                // would be a join that silently does not happen.
-                const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(method, served), null);
-                if (!routeSeen.has(endpointId)) {
-                    routeSeen.add(endpointId);
-                    nodes.push({
-                        id: endpointId,
-                        type: "API_ENDPOINT",
-                        name: `${method} ${normaliseEndpointPath(served)}`,
-                        file: null,
-                        range: null,
-                        language: null,
-                        producedBy: input.producedBy,
-                        resolution: level,
-                        attrs: { method, pathTemplate: normaliseEndpointPath(served) },
-                    });
+                // **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`
+                // for it would let an unrelated caller in another repository join to
+                // a path this application does not actually expose. The route's own
+                // contract (`USES_TYPE`, below) still holds regardless — a shape is a
+                // fact about the handler, not about routing — so only the endpoint and
+                // `SERVES_API` are withheld here.
+                if (mounted) {
+                    // Fileless AND language-less (DEC-014). `nodeId` throws if a fileless
+                    // type is hashed with a language, which is the guard against an id that
+                    // disagrees with the node it labels — a failure whose only symptom
+                    // would be a join that silently does not happen.
+                    const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(method, served), null);
+                    if (!routeSeen.has(endpointId)) {
+                        routeSeen.add(endpointId);
+                        nodes.push({
+                            id: endpointId,
+                            type: "API_ENDPOINT",
+                            name: `${method} ${normaliseEndpointPath(served)}`,
+                            file: null,
+                            range: null,
+                            language: null,
+                            producedBy: input.producedBy,
+                            resolution: level,
+                            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.
+                    push({ from: routeId, to: endpointId, type: "SERVES_API" }, level);
                 }
-                // `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.
-                push({ from: routeId, to: endpointId, type: "SERVES_API" }, level);
                 // The route's contract: which validated shapes it names. `USES_TYPE`
                 // is the edge `adapter-openapi` already emits from a route to a schema
                 // it names, and matching it is not cosmetic — two producers describing
@@ -1739,12 +1963,31 @@ export function extract(input) {
                 // **R2, and gated.** Deciding which `OrderRead` a name means is
                 // reference resolution through re-exports, which is what R2 buys and
                 // what `CALLS` and `USES_TYPE` already claim in this adapter.
+                //
+                // **`attrs.roles`, `adapter-openapi`'s own convention.** Without it the
+                // contract engine cannot tell a request schema from a response schema
+                // on this edge — `contracts/engine.ts` ~L325-330 refuses to run shape
+                // comparison at all until every route->DTO edge carries one. A name
+                // seen on both sides of the contract (a `PUT` taking and returning the
+                // same shape) carries both roles on the one edge DEC-012 allows, never
+                // two edges for one `hash(from, to, type)`.
                 if (input.reached >= 2) {
-                    for (const name of routeContractNames(route)) {
+                    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))
                             continue;
-                        push({ from: routeId, to: target.id, type: "USES_TYPE" }, 2);
+                        const roles = [];
+                        if (request.has(name))
+                            roles.push("request");
+                        if (response.has(name))
+                            roles.push("response");
+                        push({
+                            from: routeId,
+                            to: target.id,
+                            type: "USES_TYPE",
+                            ...(roles.length === 0 ? {} : { attrs: { roles } }),
+                        }, 2);
                     }
                 }
             }
@@ -2175,7 +2418,16 @@ export function extract(input) {
             const container = containerOf(reference.scope);
             if (container === undefined || container.type !== "FUNCTION")
                 continue;
-            const receiverType = instantiatedType(file, reference.scope, reference.receiver);
+            // A local instantiation (`org = Organization()`) first, a parameter's
+            // 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) ??
+                localAnnotatedType(file, reference.scope, reference.receiver);
             if (receiverType === undefined)
                 continue;
             // **A mapped column is a declared member, and `fields` cannot see one.**
@@ -2186,7 +2438,14 @@ export function extract(input) {
             // absence would have looked like a language limit rather than an oversight.
             const declaresField = (receiverType.declaration.fields ?? []).some((f) => f.name === reference.name) ||
                 (ormShapes.get(receiverType.id)?.fields ?? []).some((f) => f.name === reference.name);
-            if (!declaresField)
+            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}`;
@@ -2195,12 +2454,24 @@ export function extract(input) {
                 to: receiverType,
                 type: edgeType,
                 fields: new Set(),
+                unresolvedFields: new Set(),
             };
-            entry.fields.add(reference.name);
+            if (declaresField)
+                entry.fields.add(reference.name);
+            else
+                entry.unresolvedFields.add(reference.name);
             fieldsByEdge.set(key, entry);
         }
-        for (const { from, to, type, fields } of fieldsByEdge.values()) {
-            push({ from: from.id, to: to.id, type, attrs: { fields: [...fields].sort() } }, 3);
+        for (const { from, to, type, fields, unresolvedFields } of fieldsByEdge.values()) {
+            push({
+                from: from.id,
+                to: to.id,
+                type,
+                attrs: {
+                    ...(fields.size > 0 ? { fields: [...fields].sort() } : {}),
+                    ...(unresolvedFields.size > 0 ? { unresolvedFields: [...unresolvedFields].sort() } : {}),
+                },
+            }, 3);
         }
     }
     // --- the repository-level test-discovery audit -----------------------------