@suss/adapter-python 0.22.3 → 0.23.0

package/dist/index.js

@@ -808,9 +808,7 @@ import {
   absentReading,
   ambiguousReading,
   andThenReading,
-  enumerateOrDegrade as enumerateOrDegrade2,
   firstWrittenReading,
-  guardsHoldOn,
   mapReading,
   unreadableReading,
   valueToReadFurtherFrom,
@@ -1032,11 +1030,11 @@ function subjectConstructions(db, valueKeys) {
       continue;
     }
     const deeper = calls.has(direct) ? writtenThroughCall.get(direct) : void 0;
-    const constructionKey = deeper ?? direct;
+    const constructionKey2 = deeper ?? direct;
     const originOf2 = deeper === void 0 ? valueKey2 : direct;
-    const from = origins.get(`${originOf2}|${constructionKey}`);
+    const from = origins.get(`${originOf2}|${constructionKey2}`);
     if (from !== void 0) {
-      found.set(valueKey2, { constructionKey, origins: from });
+      found.set(valueKey2, { constructionKey: constructionKey2, origins: from });
     }
   }
   return found;
@@ -1443,8 +1441,8 @@ function emitValueFacts(db, filePath, root) {
   emitExpressionFacts(emitter, root);
 }
 
-// src/paths/effects.ts
-import { enumerateOrDegrade, sharedGatingConditions } from "@suss/extractor";
+// src/paths/bodyBranches.ts
+import { enumerateOrDegrade, guardsHoldOn } from "@suss/extractor";
 
 // src/paths/lowering.ts
 var EXIT_KINDS = {
@@ -1719,7 +1717,89 @@ function predicateOf(node) {
   return opaqueOf(node);
 }
 
+// src/paths/bodyBranches.ts
+function returnStatements(node, found = []) {
+  for (const child of node?.namedChildren ?? []) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "function_definition" || child.type === "lambda") {
+      continue;
+    }
+    if (child.type === "return_statement") {
+      found.push(child);
+    }
+    returnStatements(child, found);
+  }
+  return found;
+}
+function bodyTerminals(body, raised, continuations = []) {
+  const handsOn = new NodeSet(continuations);
+  const found = [
+    ...returnStatements(body).filter((statement) => !handsOn.has(statement)).map((statement) => ({ type: "return", statement })),
+    ...raised.map(
+      (response) => ({
+        type: "raise",
+        statement: response.statement,
+        terminal: response.terminal
+      })
+    ),
+    ...continuations.map(
+      (statement) => ({ type: "continuation", statement })
+    )
+  ];
+  return found.sort((a, b) => a.statement.startIndex - b.statement.startIndex);
+}
+function effectsReaching(effects, conditions) {
+  return effects.filter(
+    (effect) => guardsHoldOn(effect.preconditions, conditions)
+  );
+}
+function enumerateBodyBranches(options) {
+  const statements = options.terminals.map((found) => found.statement);
+  const leavesByCall = new NodeSet([
+    ...options.raised.filter((response) => response.thrownByCall).map((response) => response.statement),
+    ...options.terminals.filter((found) => found.type === "continuation").map((found) => found.statement)
+  ]);
+  const lowered = lowerPythonBody(options.body, statements, leavesByCall);
+  const enumerated = enumerateOrDegrade(
+    {
+      statements: lowered.statements,
+      terminalsByStmt: lowered.terminalsByStmt
+    },
+    statements
+  );
+  const branches = [];
+  const push = (branch, paths) => {
+    for (const path6 of paths) {
+      const conditions = path6.map((condition) => ({
+        sourceText: condition.sourceText,
+        structured: condition.expression === null ? null : predicateOf(condition.expression),
+        polarity: condition.polarity,
+        source: condition.source
+      }));
+      branches.push({
+        ...branch,
+        conditions,
+        effects: effectsReaching(options.effects, conditions),
+        isDefault: path6.length === 0
+      });
+    }
+  };
+  for (const found of options.terminals) {
+    const paths = enumerated.byTerminal.get(found.statement);
+    if (paths !== void 0) {
+      push(options.branchOf(found), paths);
+    }
+  }
+  if (options.fallthrough !== void 0) {
+    push(options.fallthrough, enumerated.fallthrough);
+  }
+  return branches;
+}
+
 // src/paths/effects.ts
+import { enumerateOrDegrade as enumerateOrDegrade2, sharedGatingConditions } from "@suss/extractor";
 var NESTED_DEFINITION_TYPES = /* @__PURE__ */ new Set(["function_definition"]);
 var LITERAL_ARGS = {
   string: (node) => ({ kind: "string", value: node.text.slice(1, -1) }),
@@ -1798,7 +1878,7 @@ function invocationEffects(definitionNode) {
     statements.push(statement);
   }
   const lowered = lowerPythonBody(body, statements);
-  const enumerated = enumerateOrDegrade(
+  const enumerated = enumerateOrDegrade2(
     {
       statements: lowered.statements,
       terminalsByStmt: lowered.terminalsByStmt
@@ -2708,6 +2788,18 @@ function raisedResponseOf(statement, options) {
     terminal: terminalOf(statement, callee, call, declared, options.facts)
   };
 }
+function returnedResponseStatus(statement, options) {
+  const returned = statement.namedChildren[0];
+  if (options.calls.length === 0 || returned === void 0 || returned === null || returned.type !== "call") {
+    return null;
+  }
+  const callee = field(returned, "function");
+  if (callee === null) {
+    return null;
+  }
+  const declared = declaredCallFor(callee, options);
+  return declared === void 0 ? null : statusOf(declared, returned, options.facts);
+}
 function calleeOf(expression, call) {
   return call === null ? expression : field(call, "function") ?? expression;
 }
@@ -3542,7 +3634,7 @@ function classRouteUnits(pattern, pack, classification, classNode, module, optio
             routePath: entry.routePath,
             ...entry.mount !== void 0 ? { mount: entry.mount } : {},
             requestBodyFromAnnotatedClass: pattern.annotatedClassIsRequestBody === true,
-            readsReturnedStatus: pattern.statusFromReturnedTuple === true,
+            pattern,
             responseStatusCalls: pattern.responseStatusCalls ?? [],
             facts: options.facts,
             injectedCallees: new Set(pattern.injectedParameterCallees ?? []),
@@ -3553,10 +3645,21 @@ function classRouteUnits(pattern, pack, classification, classNode, module, optio
             skipReceiverParam: true,
             responseShape: absentReading,
             statusCode: defaultedStatus(
-              readReturnedStatus(pattern, maybeMethod),
+              readReturnedStatus(pattern, maybeMethod, {
+                module,
+                facts: options.facts
+              }),
               pattern
             ),
-            storage: options.storage
+            storage: options.storage,
+            wrappers: wrappersAround(
+              pattern,
+              pack,
+              classification,
+              maybeMethod,
+              module,
+              options
+            )
           },
           options
         )
@@ -3686,21 +3789,6 @@ function readStatusCode(pattern, classification) {
     classification.range
   );
 }
-function returnStatements(node, found = []) {
-  for (const child of node?.namedChildren ?? []) {
-    if (child === null) {
-      continue;
-    }
-    if (child.type === "function_definition" || child.type === "lambda") {
-      continue;
-    }
-    if (child.type === "return_statement") {
-      found.push(child);
-    }
-    returnStatements(child, found);
-  }
-  return found;
-}
 function statusFromReturnedValue(node) {
   if (node === void 0) {
     return null;
@@ -3724,27 +3812,19 @@ function statusOfReturn(statement) {
   const status = statusFromReturnedValue(returned.namedChildren[1]);
   return status === null ? { kind: "unreadable" } : { kind: "status", value: status };
 }
-function effectsReaching(effects, conditions) {
-  return effects.filter(
-    (effect) => guardsHoldOn(effect.preconditions, conditions)
-  );
-}
 function returnStatusReading(statement, ctx) {
-  if (!ctx.readsReturnedStatus) {
-    return ctx.declaredStatus.reading;
-  }
-  const read = statusOfReturn(statement);
+  const read = statusOfReturnIn(statement, ctx.pattern, ctx);
   const range = rangeOf(statement);
   if (read.kind === "status") {
     return writtenReading(read.value, range);
   }
-  if (read.kind === "none") {
-    return absentReading;
+  if (read.kind === "unreadable") {
+    return unreadableReading(
+      "This return gives a status this reading cannot resolve to a number, so this outcome claims none",
+      range
+    );
   }
-  return unreadableReading(
-    "This return gives a status this reading cannot resolve to a number, so this outcome claims none",
-    range
-  );
+  return ctx.pattern.statusFromReturnedTuple === true ? absentReading : ctx.declaredStatus.reading;
 }
 function returnBranch(statement, ctx) {
   const range = rangeOf(statement);
@@ -3780,74 +3860,49 @@ function terminalBranchOf(found, ctx) {
     raise: (variant) => ({
       terminal: variant.terminal,
       location: rangeOf(variant.statement)
-    })
+    }),
+    // A route has no continuation, so none is ever collected for it.
+    continuation: (variant) => returnBranch(variant.statement, ctx)
   };
   return dispatchByType(table, found);
 }
-function routeTerminals(body, raised) {
-  const found = [
-    ...returnStatements(body).map(
-      (statement) => ({ type: "return", statement })
-    ),
-    ...raised.map(
-      (response) => ({
-        type: "raise",
-        statement: response.statement,
-        terminal: response.terminal
-      })
-    )
-  ];
-  return found.sort((a, b) => a.statement.startIndex - b.statement.startIndex);
-}
 function branchesPerTerminal(options) {
   const body = field(options.definitionNode, "body");
   const raised = raisedResponses(body, {
     calls: options.responseStatusCalls,
+    module: options.ctx.module,
+    facts: options.ctx.facts
+  });
+  const terminals = bodyTerminals(body, raised);
+  const soleReturnWritesBody = terminals.length === 1 && terminals[0]?.type === "return" && returnedBodyShape(terminals[0].statement) !== null;
+  if (terminals.length < 2 && !soleReturnWritesBody) {
+    return null;
+  }
+  const branches = enumerateBodyBranches({
+    body,
+    terminals,
+    raised,
+    effects: options.effects,
+    branchOf: (found) => terminalBranchOf(found, options.ctx)
+  });
+  return branches.length > 1 || soleReturnWritesBody ? branches : null;
+}
+function statusOfReturnIn(statement, pattern, options) {
+  const constructed = returnedResponseStatus(statement, {
+    calls: pattern.responseConstructors ?? [],
     module: options.module,
     facts: options.facts
   });
-  const terminals = routeTerminals(body, raised);
-  if (terminals.length < 2) {
-    return null;
+  if (constructed !== null) {
+    return constructed.type === "literal" ? { kind: "status", value: constructed.value } : { kind: "unreadable" };
   }
-  const statements = terminals.map((found) => found.statement);
-  const thrownByCall = new NodeSet(
-    raised.filter((response) => response.thrownByCall).map((response) => response.statement)
-  );
-  const lowered = lowerPythonBody(body, statements, thrownByCall);
-  const enumerated = enumerateOrDegrade2(
-    {
-      statements: lowered.statements,
-      terminalsByStmt: lowered.terminalsByStmt
-    },
-    statements
-  );
-  const branches = [];
-  for (const found of terminals) {
-    const paths = enumerated.byTerminal.get(found.statement);
-    if (paths === void 0) {
-      continue;
-    }
-    const branch = terminalBranchOf(found, options.ctx);
-    for (const path6 of paths) {
-      const conditions = path6.map((condition) => ({
-        sourceText: condition.sourceText,
-        structured: condition.expression === null ? null : predicateOf(condition.expression),
-        polarity: condition.polarity,
-        source: condition.source
-      }));
-      branches.push({
-        ...branch,
-        conditions,
-        effects: effectsReaching(options.effects, conditions),
-        isDefault: path6.length === 0
-      });
-    }
+  if (pattern.statusFromReturnedTuple !== true) {
+    return { kind: "none" };
   }
-  return branches.length > 1 ? branches : null;
+  return statusOfReturn(statement);
 }
-function readReturnedStatus(pattern, definitionNode) {
-  if (pattern.statusFromReturnedTuple !== true) {
+function readReturnedStatus(pattern, definitionNode, options) {
+  if (pattern.statusFromReturnedTuple !== true && (pattern.responseConstructors ?? []).length === 0) {
     return absentReading;
   }
   const range = rangeOf(definitionNode);
@@ -3855,7 +3910,7 @@ function readReturnedStatus(pattern, definitionNode) {
   let plainReturns = 0;
   let unreadable = 0;
   for (const statement of returnStatements(field(definitionNode, "body"))) {
-    const read = statusOfReturn(statement);
+    const read = statusOfReturnIn(statement, pattern, options);
     if (read.kind === "status") {
       statuses.add(read.value);
     } else if (read.kind === "none") {
@@ -3943,7 +3998,7 @@ function functionRouteUnits(pattern, pack, verb, classification, functionNode, m
         routePath: entry.routePath,
         ...entry.mount !== void 0 ? { mount: entry.mount } : {},
         requestBodyFromAnnotatedClass: pattern.annotatedClassIsRequestBody === true,
-        readsReturnedStatus: pattern.statusFromReturnedTuple === true,
+        pattern,
         responseStatusCalls: pattern.responseStatusCalls ?? [],
         facts: options.facts,
         injectedCallees: new Set(pattern.injectedParameterCallees ?? []),
@@ -3956,17 +4011,41 @@ function functionRouteUnits(pattern, pack, verb, classification, functionNode, m
         statusCode: defaultedStatus(
           declaredOrReturnedStatus(
             readStatusCode(pattern, classification),
-            readReturnedStatus(pattern, functionNode)
+            readReturnedStatus(pattern, functionNode, {
+              module,
+              facts: options.facts
+            })
           ),
           pattern
         ),
         definitionsCtx: ctx,
-        storage: options.storage
+        storage: options.storage,
+        wrappers: wrappersAround(
+          pattern,
+          pack,
+          classification,
+          functionNode,
+          module,
+          options
+        )
       },
       options
     )
   );
 }
+function wrappersAround(pattern, pack, classification, definitionNode, module, options) {
+  if (options.wrappers === void 0) {
+    return [];
+  }
+  return options.wrappers.wrappersFor({
+    pack,
+    pattern,
+    file: options.absoluteFile ?? options.filePath,
+    module,
+    classification,
+    definitionNode
+  });
+}
 function readResponseShape(declared, readAnnotation) {
   if (declared.kind === "written") {
     return { reading: declared, passedOver: [] };
@@ -4026,7 +4105,7 @@ function buildRouteUnit(options) {
     method,
     routePath,
     requestBodyFromAnnotatedClass,
-    readsReturnedStatus,
+    pattern,
     injectedCallees,
     definitionNode,
     enclosingScope,
@@ -4057,10 +4136,14 @@ function buildRouteUnit(options) {
   const perTerminal = branchesPerTerminal({
     definitionNode,
     effects,
-    module,
-    facts: options.facts,
     responseStatusCalls: options.responseStatusCalls,
-    ctx: { readsReturnedStatus, responseShape, declaredStatus: statusCode }
+    ctx: {
+      pattern,
+      responseShape,
+      declaredStatus: statusCode,
+      module,
+      facts: options.facts
+    }
   });
   const branches = (perTerminal ?? []).map(
     (branch) => extra.length === 0 ? branch : { ...branch, extraEffects: extra }
@@ -4119,7 +4202,8 @@ function buildRouteUnit(options) {
       ...responseShape.passedOver
     ],
     ...collectedDefinitions(ctx) !== null ? { definitions: collectedDefinitions(ctx) } : {},
-    ...options.mount !== void 0 ? { mount: options.mount } : {}
+    ...options.mount !== void 0 ? { mount: options.mount } : {},
+    ...options.wrappers !== void 0 && options.wrappers.length > 0 ? { wrappers: options.wrappers } : {}
   };
 }
 function unreadRoleReadings(parameters, range) {
@@ -4479,6 +4563,7 @@ import {
 import { Database as Database2 } from "@suss/datalog";
 import {
   assembleSummary as assembleSummary2,
+  composeWrappers,
   createCacheLayer,
   createTimer,
   moduleInitStructure,
@@ -5201,12 +5286,8 @@ function buildRouterIndex(files, packs, resolverOptions) {
   }
   return {
     moduleDef(fromFile, spec, name) {
-      const resolution = resolveModule(fromFile, spec, resolverOptions);
-      if (resolution.status !== "resolved") {
-        return null;
-      }
-      const bound = byFile.get(resolution.file);
-      if (bound === void 0) {
+      const bound = boundModuleAt(fromFile, spec, byFile, resolverOptions);
+      if (bound === null) {
         return null;
       }
       const binding = bound.module.moduleScope.bindings.get(name);
@@ -5232,12 +5313,12 @@ function buildRouterIndex(files, packs, resolverOptions) {
       }
       return composedPrefixOf(index, construction, displayPaths.get(module));
     },
-    resolveConstruction(pattern, module, constructorName, constructionKey) {
+    resolveConstruction(pattern, module, constructorName, constructionKey2) {
       const index = byPattern.get(pattern);
       if (index === void 0) {
         return NOT_ROUTER;
       }
-      const construction = index.byValueKey.get(constructionKey);
+      const construction = index.byValueKey.get(constructionKey2);
       if (construction !== void 0) {
         return composedPrefixOf(index, construction, displayPaths.get(module));
       }
@@ -5473,6 +5554,13 @@ function buildPatternIndex(files, importModule, composition, resolverOptions) {
   }
   return index;
 }
+function boundModuleAt(fromFile, spec, byFile, resolverOptions) {
+  const resolution = resolveModule(fromFile, spec, resolverOptions);
+  if (resolution.status !== "resolved") {
+    return null;
+  }
+  return byFile.get(resolution.file) ?? null;
+}
 function constructionOf(name, scope, importModule) {
   const binding = resolveName(scope, name);
   if (binding?.kind !== "assignment" || binding.value?.type !== "call") {
@@ -5681,16 +5769,13 @@ function constructionNamed(name, scope, scan, constructions = scan.index.constru
       if (binding.kind !== "importFrom") {
         return null;
       }
-      const resolution = resolveModule(
+      const target = boundModuleAt(
         scan.bound.file,
         { module: binding.module, relativeLevel: binding.relativeLevel },
+        scan.byFile,
         scan.resolverOptions
       );
-      if (resolution.status !== "resolved") {
-        return null;
-      }
-      const target = scan.byFile.get(resolution.file);
-      if (target === void 0) {
+      if (target === null) {
         return null;
       }
       return constructions.get(target.module)?.get(binding.importedName) ?? null;
@@ -5708,10 +5793,10 @@ function constructionThroughFacts(name, scope, scan) {
     return null;
   }
   const nameKey = `${scan.bound.file}#${name}`;
-  const constructionKey = subjectConstructions(facts, [nameKey]).get(
+  const constructionKey2 = subjectConstructions(facts, [nameKey]).get(
     nameKey
   )?.constructionKey;
-  return constructionKey === void 0 ? null : scan.index.byValueKey.get(constructionKey) ?? null;
+  return constructionKey2 === void 0 ? null : scan.index.byValueKey.get(constructionKey2) ?? null;
 }
 var MOUNT_STATE_BY_EFFECT = {
   prefixes: (statedPrefix, site) => ({
@@ -5948,12 +6033,13 @@ function constructionThroughModule(arg, scope, scan) {
   if (spec === null) {
     return null;
   }
-  const resolution = resolveModule(scan.bound.file, spec, scan.resolverOptions);
-  if (resolution.status !== "resolved") {
-    return null;
-  }
-  const target = scan.byFile.get(resolution.file);
-  if (target === void 0) {
+  const target = boundModuleAt(
+    scan.bound.file,
+    spec,
+    scan.byFile,
+    scan.resolverOptions
+  );
+  if (target === null) {
     return null;
   }
   return scan.index.constructions.get(target.module)?.get(arg.attributeName) ?? null;
@@ -6304,6 +6390,472 @@ var adapterStamp = createAdapterStamp({
   version: ADAPTER_VERSION
 });
 
+// src/wrappers.ts
+import { absentReading as absentReading2, walkDescendants as walkDescendants4 } from "@suss/extractor";
+function buildWrapperIndex(files, options) {
+  const forms = declaredForms(options.packs);
+  const filesByPath = new Map(files.map((file) => [file.file, file]));
+  const index = new PythonWrapperIndex(options, filesByPath);
+  if (forms.length > 0) {
+    for (const file of files) {
+      for (const declared of forms) {
+        registerFrom(file, declared, index);
+      }
+    }
+  }
+  return index;
+}
+function declaredForms(packs) {
+  return packs.flatMap(
+    (pack) => pack.discovery.flatMap(
+      (pattern) => (pattern.wrappers ?? []).map((form) => ({ pack, pattern, form }))
+    )
+  );
+}
+var PythonWrapperIndex = class {
+  constructor(options, filesByPath) {
+    this.options = options;
+    this.filesByPath = filesByPath;
+  }
+  options;
+  filesByPath;
+  /** By pack name: what the app registered, in the order the forms are declared and then the order the files were read. */
+  everyRoute = /* @__PURE__ */ new Map();
+  /** By construction key: what a router or a blueprint registered. */
+  ownRoutes = /* @__PURE__ */ new Map();
+  unitsByKey = /* @__PURE__ */ new Map();
+  unitsByFile = /* @__PURE__ */ new Map();
+  register(covers, target, declared) {
+    const registered = this.registered(target, declared);
+    const table = covers.kind === "everyRoute" ? this.everyRoute : this.ownRoutes;
+    const key = covers.kind === "everyRoute" ? covers.pack : covers.key;
+    const list = table.get(key) ?? [];
+    list.push(registered);
+    table.set(key, list);
+  }
+  /** The unit for a function, built once however many registrations point at it. */
+  registered(target, declared) {
+    const span = spanOf(target.node);
+    const key = `${target.file.file}:${span.start}-${span.end}`;
+    if (!this.unitsByKey.has(key)) {
+      const unit = wrapperUnit(target, declared, this.options);
+      this.unitsByKey.set(key, unit);
+      const inFile = this.unitsByFile.get(target.file.file) ?? [];
+      inFile.push(unit);
+      this.unitsByFile.set(target.file.file, inFile);
+    }
+    return {
+      reference: {
+        file: target.file.displayPath,
+        name: target.name,
+        ...isThrowForm(declared.form) ? { onThrow: true } : {}
+      },
+      form: declared.form
+    };
+  }
+  wrappersFor(query) {
+    const file = this.filesByPath.get(query.file);
+    const forms = (query.pattern.wrappers ?? []).map((form) => ({
+      pack: query.pack,
+      pattern: query.pattern,
+      form
+    }));
+    if (file === void 0 || forms.length === 0) {
+      return [];
+    }
+    const found = [
+      ...this.everyRoute.get(query.pack.name) ?? [],
+      ...this.ownRoutesOf(query)
+    ];
+    for (const declared of forms) {
+      if (declared.form.type !== "dependency") {
+        continue;
+      }
+      const site = {
+        file,
+        scope: query.module.moduleScope,
+        rebound: /* @__PURE__ */ new Set()
+      };
+      const targets = [
+        ...decoratorDependencies(query.classification, declared.form),
+        ...parameterDependencies(query.definitionNode, declared.form)
+      ];
+      for (const name of targets) {
+        const target = resolveNamedFunctionArgument(name, site, {
+          filesByPath: this.filesByPath,
+          roots: this.options.roots
+        });
+        if (target !== null) {
+          found.push(this.registered(target, declared));
+        }
+      }
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const ordered = [];
+    for (const wrapper of [...found].sort(
+      (a, b) => runOrder(a.form) - runOrder(b.form)
+    )) {
+      const key = `${wrapper.reference.file}::${wrapper.reference.name}::${wrapper.reference.onThrow === true}`;
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      ordered.push(wrapper.reference);
+    }
+    return ordered;
+  }
+  ownRoutesOf(query) {
+    const site = this.objectSiteOf(query);
+    if (site === null) {
+      return [];
+    }
+    for (const form of query.pattern.wrappers ?? []) {
+      const match = registrarOf(site.name, site.scope, {
+        pack: query.pack,
+        pattern: query.pattern,
+        form
+      });
+      if (match !== null && match.registrar.covers === "ownRoutes") {
+        return this.ownRoutes.get(constructionKey(site.file, match.call)) ?? [];
+      }
+    }
+    return [];
+  }
+  /**
+   * Where the decorator's object was built: the route's own file, the file
+   * a project wrapper function is written in, or the file an imported
+   * router comes from. The name is the one that file binds it under.
+   */
+  objectSiteOf(query) {
+    const name = query.classification.objectName;
+    if (name === null) {
+      return null;
+    }
+    const wrapperModule = query.classification.objectModule;
+    if (wrapperModule !== void 0) {
+      const file = this.fileOfModule(wrapperModule);
+      return file === null ? null : { file, scope: wrapperModule.moduleScope, name };
+    }
+    const binding = resolveName(query.module.moduleScope, name);
+    if (binding?.kind !== "importFrom") {
+      return { file: query.file, scope: query.module.moduleScope, name };
+    }
+    const target = boundModuleAt(
+      query.file,
+      { module: binding.module, relativeLevel: binding.relativeLevel },
+      this.filesByPath,
+      { roots: this.options.roots }
+    );
+    return target === null ? null : {
+      file: target.file,
+      scope: target.module.moduleScope,
+      name: binding.importedName
+    };
+  }
+  fileOfModule(module) {
+    for (const file of this.filesByPath.values()) {
+      if (file.module === module) {
+        return file.file;
+      }
+    }
+    return null;
+  }
+  unitsIn(file) {
+    return this.unitsByFile.get(file) ?? [];
+  }
+};
+function isThrowForm(form) {
+  return form.type === "decoratedWrapper" && form.throwParam !== void 0;
+}
+function runOrder(form) {
+  if (isThrowForm(form)) {
+    return 2;
+  }
+  return form.type === "decoratedWrapper" ? 0 : 1;
+}
+function registrarOf(name, scope, declared) {
+  const modules = [
+    ...declared.pattern.importModule,
+    ...declared.form.registrars.flatMap(
+      (registrar2) => registrar2.importModule ?? []
+    )
+  ];
+  const construction = constructionOf(name, scope, modules);
+  if (construction === null) {
+    return null;
+  }
+  const registrar = declared.form.registrars.find(
+    (candidate) => candidate.constructorName === construction.constructorName
+  );
+  return registrar === void 0 ? null : { registrar, call: construction.call };
+}
+function constructionKey(file, call) {
+  return `${file}#${call.startIndex}`;
+}
+function registerFrom(file, declared, index) {
+  const table = {
+    dependency: () => registerConstructorDependencies(
+      file,
+      declared,
+      declared.form,
+      index
+    ),
+    decoratedWrapper: () => registerDecorated(
+      file,
+      declared,
+      declared.form,
+      index
+    )
+  };
+  table[declared.form.type]();
+}
+function registerConstructorDependencies(file, declared, form, index) {
+  const scope = file.module.moduleScope;
+  for (const stmt of file.root.namedChildren) {
+    const assignment2 = stmt?.type === "expression_statement" ? stmt.namedChildren.find((child) => child?.type === "assignment") : void 0;
+    const left = assignment2 === void 0 || assignment2 === null ? null : field(assignment2, "left");
+    if (left?.type !== "identifier") {
+      continue;
+    }
+    const match = registrarOf(left.text, scope, declared);
+    if (match === null) {
+      continue;
+    }
+    const { keywordArgs } = readCallArguments(field(match.call, "arguments"));
+    const listed = keywordArgs[form.keyword];
+    if (listed === void 0) {
+      continue;
+    }
+    const site = { file, scope, rebound: /* @__PURE__ */ new Set() };
+    for (const name of dependencyNamesIn(listed.node, form)) {
+      const target = resolveNamedFunctionArgument(name, site, {
+        filesByPath: index.filesByPath,
+        roots: index.options.roots
+      });
+      if (target !== null) {
+        index.register(
+          coverageOf(match, file, declared.pack),
+          target,
+          declared
+        );
+      }
+    }
+  }
+}
+function coverageOf(match, file, pack) {
+  return match.registrar.covers === "everyRoute" ? { kind: "everyRoute", pack: pack.name } : { kind: "ownRoutes", key: constructionKey(file.file, match.call) };
+}
+function registerDecorated(file, declared, form, index) {
+  walkDescendants4(file.root, file.module.moduleScope, {
+    at: (node, scope) => {
+      if (node.type !== "decorated_definition") {
+        return;
+      }
+      const { definition, decorators } = stripDecorators(node);
+      if (definition.type !== "function_definition") {
+        return;
+      }
+      for (const decorator of decorators) {
+        const receiver = decoratorReceiver(decorator);
+        if (receiver === null || receiver.attributeName !== form.attribute || receiver.object.type !== "identifier") {
+          continue;
+        }
+        const match = registrarOf(receiver.object.text, scope, declared);
+        const name = field(definition, "name")?.text;
+        if (match === null || name === void 0) {
+          continue;
+        }
+        index.register(
+          coverageOf(match, file, declared.pack),
+          { file, node: definition, name, exportPath: [name] },
+          declared
+        );
+      }
+    },
+    into: (node, scope) => file.module.scopeFor.get(node.id) ?? scope
+  });
+}
+function dependencyNamesIn(node, form) {
+  const calls = node.type === "list" ? node.namedChildren : [node];
+  const names = [];
+  for (const call of calls) {
+    const name = call === null ? null : dependencyNameOf(call, form);
+    if (name !== null) {
+      names.push(name);
+    }
+  }
+  return names;
+}
+function dependencyNameOf(node, form) {
+  if (node.type !== "call") {
+    return null;
+  }
+  const callee = field(node, "function");
+  const calleeName3 = callee?.type === "identifier" ? callee.text : callee?.type === "attribute" ? field(callee, "attribute")?.text ?? null : null;
+  if (calleeName3 === null || !form.callees.includes(calleeName3)) {
+    return null;
+  }
+  const first = field(node, "arguments")?.namedChildren[0];
+  return first?.type === "identifier" ? first.text : null;
+}
+function decoratorDependencies(classification, form) {
+  const listed = classification.keywordArgs[form.keyword];
+  return listed === void 0 ? [] : dependencyNamesIn(listed.node, form);
+}
+var MAX_ANNOTATION_DEPTH2 = 6;
+function parameterDependencies(definitionNode, form) {
+  const names = [];
+  const findIn = (node, depth) => {
+    if (node === null || depth > MAX_ANNOTATION_DEPTH2) {
+      return null;
+    }
+    const direct = dependencyNameOf(node, form);
+    if (direct !== null) {
+      return direct;
+    }
+    for (const child of node.namedChildren) {
+      const found = findIn(child, depth + 1);
+      if (found !== null) {
+        return found;
+      }
+    }
+    return null;
+  };
+  for (const param of field(definitionNode, "parameters")?.namedChildren ?? []) {
+    if (param === null) {
+      continue;
+    }
+    const inDefault = field(param, "value");
+    const found = inDefault === null ? findIn(field(param, "type"), 0) : dependencyNameOf(inDefault, form);
+    if (found !== null) {
+      names.push(found);
+    }
+  }
+  return names;
+}
+function wrapperUnit(target, declared, options) {
+  const { file, node, name, exportPath } = target;
+  const body = field(node, "body");
+  const range = rangeOf(node);
+  const raised = raisedResponses(body, {
+    calls: declared.pattern.responseStatusCalls ?? [],
+    module: file.module,
+    facts: options.facts
+  });
+  const continuations = continuationStatements(node, declared.form);
+  const terminals = bodyTerminals(body, raised, continuations);
+  const effects = invocationEffects(node);
+  const extra = recognizedBodyEffects(
+    node,
+    file.module,
+    options.storageFor(file)
+  );
+  const delegate = (at) => ({
+    terminal: {
+      kind: "delegate",
+      statusCode: null,
+      body: null,
+      exceptionType: null,
+      message: null,
+      component: null,
+      renderTree: null,
+      delegateTarget: null,
+      emitEvent: null,
+      location: rangeOf(at)
+    },
+    location: rangeOf(at)
+  });
+  const respond = (statement) => returnBranch(statement, {
+    pattern: declared.pattern,
+    responseShape: { reading: absentReading2 },
+    declaredStatus: {
+      reading: absentReading2,
+      ...declared.pattern.defaultStatusCode !== void 0 ? { libraryDefault: declared.pattern.defaultStatusCode } : {}
+    },
+    module: file.module,
+    facts: options.facts
+  });
+  const branchOf = (terminal) => {
+    if (terminal.type === "raise") {
+      return {
+        terminal: terminal.terminal,
+        location: rangeOf(terminal.statement)
+      };
+    }
+    if (terminal.type === "continuation" || returnHandsOn(terminal.statement, declared.form)) {
+      return delegate(terminal.statement);
+    }
+    return respond(terminal.statement);
+  };
+  const branches = enumerateBodyBranches({
+    body,
+    terminals,
+    raised,
+    effects,
+    branchOf,
+    fallthrough: delegate(node)
+  }).map(
+    (branch) => extra.length === 0 ? branch : { ...branch, extraEffects: extra }
+  );
+  return {
+    identity: {
+      name,
+      nameKind: "binding",
+      kind: "middleware",
+      file: file.displayPath,
+      range,
+      span: spanOf(node),
+      exportName: exportPath[0] ?? name,
+      exportPath
+    },
+    boundaryBinding: null,
+    parameters: [],
+    branches,
+    bodyContent: body === null ? "absent" : bodyContentOf(body),
+    dependencyCalls: [],
+    declaredContract: null
+  };
+}
+function returnHandsOn(statement, form) {
+  if (form.type === "dependency") {
+    return true;
+  }
+  if (form.continuationParam !== void 0 || form.throwParam !== void 0) {
+    return false;
+  }
+  if (form.returnedValueResponds === true) {
+    const returned = statement.namedChildren[0];
+    return returned === void 0 || returned === null || returned.type === "none";
+  }
+  return true;
+}
+function continuationStatements(node, form) {
+  if (form.type !== "decoratedWrapper" || form.continuationParam === void 0) {
+    return [];
+  }
+  const params = (field(node, "parameters")?.namedChildren ?? []).filter(
+    (param2) => param2 !== null
+  );
+  const param = params[form.continuationParam];
+  const continuation = param === void 0 ? null : field(param, "name")?.text ?? (param.type === "identifier" ? param.text : null);
+  if (continuation === null) {
+    return [];
+  }
+  const body = field(node, "body");
+  if (body === null) {
+    return [];
+  }
+  const found = [];
+  for (const call of bodyCalls(body)) {
+    const callee = field(call, "function");
+    const statement = callee?.type === "identifier" && callee.text === continuation ? enclosingStatement(call, body) : null;
+    if (statement !== null) {
+      found.push(statement);
+    }
+  }
+  return found;
+}
+
 // src/project.ts
 function reportUnresolvedProjectModules(options, db) {
   const imported = new Set(db.facts("pyImport").map((row) => String(row[1])));
@@ -6401,24 +6953,43 @@ async function extractPythonProject(options) {
     couldMatch,
     rawSql: rawSqlPatterns
   } : void 0;
-  const seeds = [];
-  const summariesBySeed = /* @__PURE__ */ new Map();
+  const wrapperIndex = timer.time(
+    "discover",
+    () => buildWrapperIndex(bound, {
+      packs: options.packs,
+      roots: options.roots,
+      facts: needsValues ? db : void 0,
+      storageFor
+    })
+  );
+  const discovered = /* @__PURE__ */ new Map();
   for (const boundFile of bound) {
     const { file, root, module: moduleBinding } = boundFile;
-    const displayPath = displayPathOf(file);
     const storage = storageFor(boundFile);
     const rawUnits = timer.time(
       "discover",
       () => discoverUnits(root, moduleBinding, {
         packs: options.packs,
-        filePath: displayPath,
+        filePath: displayPathOf(file),
         absoluteFile: file,
         routerIndex,
         gapHandling,
+        wrappers: wrapperIndex,
         ...needsValues ? { facts: db } : {},
         ...storage === void 0 ? {} : { storage }
       })
     );
+    discovered.set(file, rawUnits);
+  }
+  const seeds = [];
+  const summariesBySeed = /* @__PURE__ */ new Map();
+  for (const boundFile of bound) {
+    const { file, root, module: moduleBinding } = boundFile;
+    const displayPath = displayPathOf(file);
+    const rawUnits = [
+      ...discovered.get(file) ?? [],
+      ...wrapperIndex.unitsIn(file)
+    ];
     for (const raw of rawUnits) {
       const summary = timer.time(
         "summarize",
@@ -6506,12 +7077,16 @@ async function extractPythonProject(options) {
   }
   disambiguateSummaryIds(summaries);
   linkCallsToSummaries(summaries);
+  const composed = timer.time(
+    "summarize",
+    () => composeWrappers(summaries, { gapHandling })
+  );
   await timer.timeAsync("cache.write", async () => {
-    if (cacheDir === null || summaries.length === 0) {
+    if (cacheDir === null || composed.length === 0) {
       return;
     }
     try {
-      await cache.write(cacheInput, summaries);
+      await cache.write(cacheInput, composed);
     } catch {
     }
   });
@@ -6520,11 +7095,11 @@ async function extractPythonProject(options) {
       packs: options.packs,
       tallies,
       filesWalked: options.files.length,
-      summaries
+      summaries: composed
     })
   );
   options.onTiming?.(timer.report());
-  return { summaries, facts: db };
+  return { summaries: composed, facts: db };
 }
 function resolvedImportsOf(db, displayPathOf) {
   const importsByFile = /* @__PURE__ */ new Map();