@suss/adapter-python 0.34.1 → 0.35.1

package/dist/index.js

@@ -985,10 +985,14 @@ function objectReturnedBy(db, callKey) {
 
 // src/facts/values.ts
 import {
+  addEntryRows,
+  addTemplateRows,
   NAMED_STORE_NAME,
   RECEIVER_STORE_NAME,
+  SPREAD_ENTRY,
   startsAtName,
   UNPLACED_STORE_NAME,
+  VALUE_ENTRY,
   valueLeftByWrites,
   writesRunInOrder
 } from "@suss/resolution";
@@ -999,6 +1003,8 @@ var CONVERTING_BUILTINS = /* @__PURE__ */ new Set([
   "str",
   "float"
 ]);
+var ATTRIBUTE_GETTER = "getattr";
+var POSITION_COUNTER = "enumerate";
 
 // src/facts/values.ts
 function nodeId(filePath, node) {
@@ -1170,8 +1176,7 @@ function emitConversion(emitter, call, callKey) {
     return;
   }
   const name = callee.text;
-  const builtin = nameKey(emitter.filePath, emitter.enclosing, name) === nameId(emitter.filePath, name) && !emitter.moduleNames().has(name);
-  if (builtin) {
+  if (isBuiltin(emitter, name)) {
     add(emitter, "converts", callKey, valueKey(emitter, first.node), name);
   }
 }
@@ -1220,6 +1225,7 @@ function emitSequence(emitter, sequence) {
   const objectKey = nodeId(emitter.filePath, sequence);
   add(emitter, "objectValue", objectKey);
   let position = 0;
+  const entries = [];
   for (const element of children(sequence)) {
     add(
       emitter,
@@ -1229,12 +1235,21 @@ function emitSequence(emitter, sequence) {
       valueKey(emitter, element)
     );
     position += 1;
+    if (element.type !== "comment") {
+      entries.push(writtenEntry(emitter, element));
+    }
   }
+  addEntryRows(rowsOf(emitter), objectKey, entries);
 }
 function emitDictionary(emitter, dictionary) {
   const objectKey = nodeId(emitter.filePath, dictionary);
   add(emitter, "objectValue", objectKey);
+  const entries = [];
   for (const pair of children(dictionary)) {
+    if (SPREAD_TYPES.has(pair.type)) {
+      entries.push(writtenEntry(emitter, pair));
+      continue;
+    }
     if (pair.type !== "pair") {
       continue;
     }
@@ -1243,6 +1258,7 @@ function emitDictionary(emitter, dictionary) {
     if (key === null || value === null) {
       continue;
     }
+    entries.push(writtenEntry(emitter, value));
     if (key.type !== "string") {
       add(emitter, "holdsUnderKey", objectKey, valueKey(emitter, value));
       continue;
@@ -1255,6 +1271,15 @@ function emitDictionary(emitter, dictionary) {
       valueKey(emitter, value)
     );
   }
+  addEntryRows(rowsOf(emitter), objectKey, entries);
+}
+var SPREAD_TYPES = /* @__PURE__ */ new Set(["list_splat", "dictionary_splat"]);
+function writtenEntry(emitter, entry) {
+  const unpacked = SPREAD_TYPES.has(entry.type) ? children(entry)[0] : void 0;
+  return unpacked === void 0 ? { key: valueKey(emitter, entry), form: VALUE_ENTRY } : { key: valueKey(emitter, unpacked), form: SPREAD_ENTRY };
+}
+function rowsOf(emitter) {
+  return (relation, row) => add(emitter, relation, ...row);
 }
 function emitAttribute(emitter, attribute) {
   const object = field(attribute, "object");
@@ -1319,13 +1344,50 @@ function emitKeyedRead(emitter, site, container, key) {
   if (WRITTEN_KEY_TYPES.has(key.type)) {
     return;
   }
-  add(
-    emitter,
-    "readsKeyed",
-    nodeId(emitter.filePath, site),
-    valueKey(emitter, container),
-    valueKey(emitter, key)
+  const siteKey = nodeId(emitter.filePath, site);
+  const containerKey = valueKey(emitter, container);
+  add(emitter, "readsKeyed", siteKey, containerKey, valueKey(emitter, key));
+  add(emitter, "choosesEntry", siteKey, containerKey);
+}
+function emitAttributeChoice(emitter, call) {
+  const callee = field(call, "function");
+  const [target, name] = callArguments(call);
+  if (callee?.type !== "identifier" || callee.text !== ATTRIBUTE_GETTER || !isBuiltin(emitter, callee.text) || target?.kind !== "positional" || name?.kind !== "positional") {
+    return;
+  }
+  const siteKey = nodeId(emitter.filePath, call);
+  const targetKey = valueKey(emitter, target.node);
+  const written = plainStringOf(name.node);
+  if (written !== null) {
+    add(emitter, "choosesNamedEntry", siteKey, targetKey, written);
+    return;
+  }
+  const ends = writtenEnds(name.node);
+  if (ends === null) {
+    add(emitter, "choosesEntry", siteKey, targetKey);
+    return;
+  }
+  add(emitter, "choosesEntryLike", siteKey, targetKey, ends.start, ends.end);
+}
+function writtenEnds(node) {
+  if (node.type !== "string") {
+    return null;
+  }
+  const parts = children(node).filter(
+    (part) => part.type !== "string_start" && part.type !== "string_end"
   );
+  const written = (part) => part.type === "string_content";
+  const firstComputed = parts.findIndex((part) => !written(part));
+  if (firstComputed === -1) {
+    return null;
+  }
+  const lastComputed = parts.length - 1 - [...parts].reverse().findIndex((part) => !written(part));
+  const start = parts.slice(0, firstComputed).map((part) => part.text).join("");
+  const end = parts.slice(lastComputed + 1).map((part) => part.text).join("");
+  return start === "" && end === "" ? null : { start, end };
+}
+function isBuiltin(emitter, name) {
+  return nameKey(emitter.filePath, emitter.enclosing, name) === nameId(emitter.filePath, name) && !emitter.moduleNames().has(name);
 }
 function emitWrittenKeyRead(emitter, site, container, key) {
   const name = plainStringOf(key);
@@ -1461,6 +1523,86 @@ function emitComprehensionElement(emitter, comprehension) {
     );
   }
 }
+var PAIR_TARGET_TYPES = /* @__PURE__ */ new Set(["pattern_list", "tuple_pattern"]);
+function emitElementVariables(emitter, clause) {
+  const target = field(clause, "left");
+  const over = field(clause, "right");
+  if (target === null || over === null) {
+    return;
+  }
+  const names = PAIR_TARGET_TYPES.has(target.type) ? children(target) : [];
+  const [position, element] = names;
+  const counted = countedCollection(emitter, over);
+  if (counted !== null && names.length === 2 && position?.type === "identifier" && element !== void 0) {
+    emitElementTaken(emitter, element, valueKey(emitter, counted), position);
+    return;
+  }
+  emitElementTaken(emitter, target, valueKey(emitter, over), null);
+}
+function emitElementTaken(emitter, target, overKey, position) {
+  const variables = target.type === "identifier" ? [{ node: target, part: null }] : partsTakenApart(target);
+  for (const variable of variables) {
+    const key = valueKey(emitter, variable.node);
+    if (variable.part === null) {
+      add(emitter, "elementOf", key, overKey);
+      continue;
+    }
+    add(emitter, "elementPartOf", key, overKey, variable.part);
+  }
+  const [first] = variables;
+  if (position !== null && first !== void 0) {
+    add(
+      emitter,
+      "positionOf",
+      valueKey(emitter, position),
+      valueKey(emitter, first.node)
+    );
+  }
+}
+function partsTakenApart(target) {
+  const parts = [];
+  if (!PAIR_TARGET_TYPES.has(target.type)) {
+    return parts;
+  }
+  for (const [position, part] of children(target).entries()) {
+    if (part.type === "list_splat_pattern") {
+      break;
+    }
+    if (part.type === "identifier") {
+      parts.push({ node: part, part: String(position) });
+    }
+  }
+  return parts;
+}
+function countedCollection(emitter, over) {
+  const callee = over.type === "call" ? field(over, "function") : null;
+  const args = field(over, "arguments");
+  const [first] = callArguments(over);
+  if (callee?.type !== "identifier" || callee.text !== POSITION_COUNTER || !isBuiltin(emitter, POSITION_COUNTER) || args === null || writtenArgumentCount(args) !== 1 || first?.kind !== "positional") {
+    return null;
+  }
+  return first.node;
+}
+function interpolatedPieces(emitter, string2) {
+  const parts = children(string2);
+  if (!parts.some((part) => part.type === "interpolation")) {
+    return [];
+  }
+  return parts.flatMap((part) => {
+    if (part.type === "string_content") {
+      return [{ text: stringContentValue(part) }];
+    }
+    const expression = part.type === "interpolation" ? field(part, "expression") ?? children(part)[0] : void 0;
+    return expression === void 0 ? [] : [{ hole: valueKey(emitter, expression) }];
+  });
+}
+function adjacentPieces(emitter, joined2) {
+  return children(joined2).filter((part) => part.type !== "comment").map((part) => ({ hole: valueKey(emitter, part) }));
+}
+var TEMPLATE_PIECES = {
+  string: interpolatedPieces,
+  concatenated_string: adjacentPieces
+};
 function emitExpressionFact(emitter, child, type) {
   if (type === "call") {
     emitCall(emitter, child);
@@ -1468,6 +1610,7 @@ function emitExpressionFact(emitter, child, type) {
     if (mapping !== null) {
       emitKeyedRead(emitter, child, mapping.container, mapping.key);
     }
+    emitAttributeChoice(emitter, child);
   }
   if (type === "subscript") {
     const index = singleSubscript(child);
@@ -1497,6 +1640,13 @@ function emitExpressionFact(emitter, child, type) {
   if (COMPREHENSION_TYPES.has(type)) {
     emitComprehensionElement(emitter, child);
   }
+  if (type === "for_in_clause") {
+    emitElementVariables(emitter, child);
+  }
+  const pieces = TEMPLATE_PIECES[type]?.(emitter, child) ?? [];
+  if (pieces.length > 0) {
+    addTemplateRows(rowsOf(emitter), nodeId(emitter.filePath, child), pieces);
+  }
   const branches = fallbackBranchesOf(child, type);
   if (branches !== null) {
     for (const branch of branches) {
@@ -2015,6 +2165,9 @@ function readUnderName(emitter, statement, funcKey, accessed) {
 function emitNestedDefinitions(emitter, node) {
   for (const child of children(node)) {
     const type = child.type;
+    if (type === "decorated_definition") {
+      emitDecoratorCalls(emitter, child);
+    }
     if (FUNCTION_TYPES.has(type)) {
       emitFunctionFacts(emitter, child);
       if (emitter.enclosing !== null) {
@@ -2034,6 +2187,20 @@ function emitNestedDefinitions(emitter, node) {
     emitNestedDefinitions(emitter, child);
   }
 }
+function emitDecoratorCalls(emitter, decorated) {
+  const { definition, decorators } = stripDecorators(decorated);
+  let applied = nodeId(emitter.filePath, definition);
+  for (const decorator of [...decorators].reverse()) {
+    const [expression] = children(decorator);
+    if (expression === void 0) {
+      continue;
+    }
+    const callKey = nodeId(emitter.filePath, decorator);
+    add(emitter, "call", callKey, valueKey(emitter, expression));
+    add(emitter, "callArg", callKey, "0", applied);
+    applied = callKey;
+  }
+}
 var readingsByTree = /* @__PURE__ */ new WeakMap();
 function scopeReadingOf(fn, given) {
   const tree = fn.tree;
@@ -4771,13 +4938,37 @@ function modelColumn(node) {
   }
   return field(node, "attribute")?.text ?? null;
 }
-function selectorOf(chain, valueMethods) {
+function selectorOf(chain, valueMethods, model) {
+  const picking = laterCalls(chain).filter(
+    (call) => !valueMethods.includes(methodNameOf(call))
+  );
   return [
-    ...new Set(
-      laterCalls(chain).filter((call) => !valueMethods.includes(methodNameOf(call))).flatMap((call) => pickedBy(call).map((one) => one.name))
-    )
+    .../* @__PURE__ */ new Set([
+      ...picking.flatMap((call) => pickedBy(call).map((one) => one.name)),
+      ...model === null ? [] : picking.flatMap((call) => columnsComparedBy(call, model))
+    ])
   ];
 }
+var COMBINED_TESTS = ["and_", "or_", "not_"];
+function columnsComparedBy(call, model) {
+  const args = field(call, "arguments");
+  return (args === null ? [] : children(args)).flatMap(
+    (argument) => columnsCompared(argument, model)
+  );
+}
+function columnsCompared(node, model) {
+  if (node.type === "call" && COMBINED_TESTS.includes(methodNameOf(node))) {
+    return columnsComparedBy(node, model);
+  }
+  if (node.type !== "comparison_operator") {
+    return [];
+  }
+  return children(node).flatMap((side) => {
+    const object = side.type === "attribute" ? field(side, "object") : null;
+    const column = object?.text === model ? field(side, "attribute") : null;
+    return column === null ? [] : [column.text];
+  });
+}
 var TABLE_METHODS = ["select_from", "join"];
 function modelOf(chain, options) {
   const fromRoot = modelArgument(chain.root, chain.root, options);
@@ -4842,14 +5033,15 @@ function isClassName(name) {
 }
 function effectFor2(pattern, chain, operation, options) {
   const valueMethods = pattern.valueMethods ?? [];
-  const picked = selectorOf(chain, valueMethods);
+  const model = modelOf(chain, options);
+  const picked = selectorOf(chain, valueMethods, model);
   const effect = {
     type: "interaction",
     binding: storageBinding2({
       recognition: "python-storage",
       storageSystem: pattern.storageSystem,
       scope: "default",
-      container: modelOf(chain, options)
+      container: model
     }),
     callee: chain.last.text,
     interaction: {
@@ -6580,7 +6772,7 @@ function isStdlibModule(node, scope, module) {
   const binding = resolveName(scope, node.text);
   return binding?.kind === "import" && binding.module === module && binding.relativeLevel === 0;
 }
-function isBuiltin(node, scope, name) {
+function isBuiltin2(node, scope, name) {
   return node.type === "identifier" && node.text === name && resolveName(scope, name) === null;
 }
 function isStdlibMember(node, scope, module, name) {
@@ -6628,7 +6820,7 @@ function streamWriteAt(call, scope) {
   }
   const written = callArguments(call);
   const positional = written.filter((argument) => argument.kind === "positional").map((argument) => argument.node);
-  if (callee.type === "identifier" && isBuiltin(callee, scope, "print")) {
+  if (callee.type === "identifier" && isBuiltin2(callee, scope, "print")) {
     const file = written.find(
       (argument) => argument.kind === "keyword" && argument.name === "file"
     );
@@ -8068,6 +8260,7 @@ import {
   placeArgTargets as placeArgTargets2,
   placeCalleeParameters as placeCalleeParameters2,
   placeCalls as placeCalls2,
+  placePossibleCalls as placePossibleCalls2,
   recordParameterGaps as recordParameterGaps2,
   summaryIdFromParts,
   unfollowedCallGap as unfollowedCallGap2
@@ -8079,10 +8272,12 @@ import {
   createCacheLayer,
   createTimer,
   effectToIR,
+  extractionCacheDirFor,
   extractionConfigStamp,
   KeptParses,
   moduleInitStructure,
   noopTimer,
+  ownersWhereWritten,
   runDigest,
   stampModuleImports,
   stampModules
@@ -8163,12 +8358,12 @@ function exitSiteAt(statement, scope) {
     return endsTheProcess(callee, scope) ? { statement, code, raised: false } : null;
   }
   if (statement.type === "raise_statement") {
-    return isBuiltin(callee, scope, "SystemExit") ? { statement, code, raised: true } : null;
+    return isBuiltin2(callee, scope, "SystemExit") ? { statement, code, raised: true } : null;
   }
   return null;
 }
 function endsTheProcess(callee, scope) {
-  return isStdlibMember(callee, scope, "sys", "exit") || isBuiltin(callee, scope, "exit") || isBuiltin(callee, scope, "quit");
+  return isStdlibMember(callee, scope, "sys", "exit") || isBuiltin2(callee, scope, "exit") || isBuiltin2(callee, scope, "quit");
 }
 function firstArgument(call) {
   return callArguments(call).find(
@@ -8329,6 +8524,7 @@ import {
   placeArgTargets,
   placeCalleeParameters,
   placeCalls,
+  placePossibleCalls,
   recordParameterGaps,
   StopList,
   TargetPlacements,
@@ -8429,6 +8625,7 @@ function methodCalledOn(call) {
 import {
   calleeOutcomeOf,
   calleeOutcomes,
+  dispatchOutcomes,
   noteKeyRead as noteKeyRead3,
   RECEIVER_STORE_NAME as RECEIVER_STORE_NAME2,
   writtenSourcesOf
@@ -8498,6 +8695,40 @@ function instancesHaveAttribute(facts, classKey, name) {
 function namedOutcomes(keys, ctx) {
   return calleeOutcomes(ctx.facts, [...new Set(keys)]);
 }
+function dispatchedCalls(calls, ctx) {
+  const byKey = new Map(
+    calls.map(({ call, site }) => [nodeId(site.file.file, call), call])
+  );
+  const found = /* @__PURE__ */ new Map();
+  for (const [key, outcome] of dispatchOutcomes(ctx.facts, [...byKey.keys()])) {
+    const call = byKey.get(key);
+    if (call === void 0) {
+      continue;
+    }
+    const targets = /* @__PURE__ */ new Map();
+    for (const fn of outcome.functions) {
+      for (const target of reachedThrough(fn, outcome.through, ctx)) {
+        targets.set(nodeId(target.file.file, target.node), target);
+      }
+    }
+    found.set(call.id, {
+      targets: [...targets.values()],
+      certain: outcome.certain && outcome.functions.every((fn) => !isLambda(fn, ctx)),
+      unresolved: outcome.unresolved
+    });
+  }
+  return found;
+}
+function reachedThrough(key, through, ctx) {
+  const keys = isLambda(key, ctx) ? through.get(key) ?? [] : [key];
+  return keys.flatMap((one) => {
+    const target = isLambda(one, ctx) ? null : functionAt(one, ctx);
+    return target === null ? [] : [target];
+  });
+}
+function isLambda(key, ctx) {
+  return ctx.definitions.get(key)?.type === "lambda";
+}
 function functionNamed(nameKey2, ctx, read) {
   if (assignedElsewhere(ctx.facts, nameKey2)) {
     return null;
@@ -8716,6 +8947,7 @@ function reachedFunctions(seeds, options) {
   const targetsByKey = /* @__PURE__ */ new Map();
   const stopsByKey = /* @__PURE__ */ new Map();
   const argTargetsByKey = /* @__PURE__ */ new Map();
+  const possibleTargetsByKey = /* @__PURE__ */ new Map();
   const parameterCallsByKey = /* @__PURE__ */ new Map();
   const callsByKey = /* @__PURE__ */ new Map();
   const passedPositions = /* @__PURE__ */ new Set();
@@ -8778,6 +9010,7 @@ function reachedFunctions(seeds, options) {
       }
       targetsByKey.set(key, scan.targets);
       argTargetsByKey.set(key, scan.argTargets);
+      possibleTargetsByKey.set(key, scan.possibleTargets);
       if (scan.parameterCalls.length > 0) {
         parameterCallsByKey.set(key, scan.parameterCalls);
       }
@@ -8828,6 +9061,7 @@ function reachedFunctions(seeds, options) {
       }
       placeCalls(summary2, targetsByKey.get(key));
       placeArgTargets(summary2, argTargetsByKey.get(key));
+      placePossibleCalls(summary2, possibleTargetsByKey.get(key));
       placeCalleeParameters(summary2, parameterCallsByKey.get(key));
       return summary2;
     };
@@ -8851,6 +9085,7 @@ function reachedFunctions(seeds, options) {
     targetsByKey,
     stopsByKey,
     argTargetsByKey,
+    possibleTargetsByKey,
     parameterCallsByKey,
     callsByKey,
     passedPositions,
@@ -8874,24 +9109,42 @@ function chargeOf(charges, key) {
   }
   return charge;
 }
+function dispatchedAmong(written, spellings, ctx) {
+  return dispatchedCalls(
+    written.filter(({ call, site }) => {
+      if (!ENTRY_CALLEE_TYPES.has(field(call, "function")?.type ?? "")) {
+        return false;
+      }
+      const outcome = resolveCallee2(call, site, ctx, spellings);
+      return outcome.kind === "stopped" && outcome.reason !== "callerSupplied";
+    }),
+    ctx
+  );
+}
+var ENTRY_CALLEE_TYPES = /* @__PURE__ */ new Set(["subscript", "call", "identifier"]);
 function batchedReads(round, ctx) {
   const bodies = round.flatMap(
     (entry) => "source" in entry ? [{ key: entry.key, source: entry.source, ...bodyOf(entry.source) }] : []
   );
-  const spellings = calleeSpellings(
-    bodies.flatMap((body) => body.written),
-    ctx
-  );
+  const written = bodies.flatMap((body) => body.written);
+  const spellings = calleeSpellings(written, ctx);
   const passed = namedOutcomes(
     bodies.flatMap(
-      ({ source, written }) => written.flatMap(({ call }) => passedNameKeys(source.file, call))
+      ({ source, written: written2 }) => written2.flatMap(({ call }) => passedNameKeys(source.file, call))
     ),
     ctx
   );
+  const dispatched = dispatchedAmong(written, spellings, ctx);
   return new Map(
     bodies.map((body) => [
       body.key,
-      { body: body.body, written: body.written, spellings, passed }
+      {
+        body: body.body,
+        written: body.written,
+        spellings,
+        passed,
+        dispatched
+      }
     ])
   );
 }
@@ -8922,13 +9175,15 @@ function scanOnce(source, key, ctx, options, read, charges) {
 }
 function ownReads(source, ctx) {
   const body = bodyOf(source);
+  const spellings = calleeSpellings(body.written, ctx);
   return {
     ...body,
-    spellings: calleeSpellings(body.written, ctx),
+    spellings,
     passed: namedOutcomes(
       body.written.flatMap(({ call }) => passedNameKeys(source.file, call)),
       ctx
-    )
+    ),
+    dispatched: dispatchedAmong(body.written, spellings, ctx)
   };
 }
 function storedScan(scan) {
@@ -8944,6 +9199,10 @@ function storedScan(scan) {
       callee,
       [...byPosition]
     ]),
+    possibleTargets: [...scan.possibleTargets].map(([callee, places]) => [
+      callee,
+      [...places]
+    ]),
     parameterCalls: [...scan.parameterCalls],
     passedPositions: [...scan.passedPositions]
   };
@@ -8959,6 +9218,7 @@ function scanFromStored(stored, functionFor) {
         new Map(byPosition)
       ])
     ),
+    possibleTargets: new Map(stored.possibleTargets),
     parameterCalls: stored.parameterCalls,
     passedPositions: new Set(stored.passedPositions)
   };
@@ -8987,6 +9247,7 @@ var EMPTY_SCAN = {
   stops: [],
   targets: /* @__PURE__ */ new Map(),
   argTargets: /* @__PURE__ */ new Map(),
+  possibleTargets: /* @__PURE__ */ new Map(),
   parameterCalls: [],
   passedPositions: /* @__PURE__ */ new Set()
 };
@@ -9063,12 +9324,25 @@ function scanBody(source, ctx, recognized, read, implied) {
     return EMPTY_SCAN;
   }
   const ownParameters = callParameterNames(node, source.exportPath.length > 1);
+  const follow = (target) => {
+    const key = keyOf2(target);
+    if (!seen.has(key)) {
+      seen.add(key);
+      followed.push(target);
+    }
+  };
   const recordPassedArgs = (call, callee, calleeKey2) => {
     const args = field(call, "arguments");
     if (args === null) {
       return;
     }
     children(args).forEach((arg, position) => {
+      if (arg.type === "lambda") {
+        if (calleeKey2 !== null) {
+          passedPositions.add(`${calleeKey2}#${position}`);
+        }
+        return;
+      }
       const nameKey2 = passedNameKeyOf(file, arg);
       if (nameKey2 === null) {
         return;
@@ -9077,11 +9351,7 @@ function scanBody(source, ctx, recognized, read, implied) {
       if (resolved === null) {
         return;
       }
-      const key = keyOf2(resolved);
-      if (!seen.has(key)) {
-        seen.add(key);
-        followed.push(resolved);
-      }
+      follow(resolved);
       placements.placeArg(callee, position, {
         file: resolved.file.displayPath,
         span: spanOf(resolved.node)
@@ -9091,9 +9361,30 @@ function scanBody(source, ctx, recognized, read, implied) {
       }
     });
   };
+  const recordPossible = (call, callee, dispatched) => {
+    dispatched.targets.forEach(follow);
+    placements.placePossible(
+      callee,
+      dispatched.targets.map((target) => ({
+        file: target.file.displayPath,
+        span: spanOf(target.node)
+      }))
+    );
+    recordPassedArgs(call, callee, null);
+    if (dispatched.unresolved > 0 && !recognized.has(call.id)) {
+      stops.add({ callee, reason: "unsettledValue" });
+    }
+  };
   const record = (call, site) => {
     const callee = calleeText(call);
-    const outcome = resolveCallee2(call, site, ctx, spellings);
+    const settled = resolveCallee2(call, site, ctx, spellings);
+    const dispatched = settled.kind === "stopped" ? read.dispatched.get(call.id) : void 0;
+    const [only] = dispatched?.targets ?? [];
+    if (dispatched !== void 0 && only !== void 0 && !dispatched.certain) {
+      recordPossible(call, callee, dispatched);
+      return;
+    }
+    const outcome = only === void 0 ? settled : { kind: "followed", target: only };
     placeCallee(placements, callee, outcome, call, file);
     recordPassedArgs(
       call,
@@ -9117,11 +9408,7 @@ function scanBody(source, ctx, recognized, read, implied) {
       }
       return;
     }
-    const key = keyOf2(outcome.target);
-    if (!seen.has(key)) {
-      seen.add(key);
-      followed.push(outcome.target);
-    }
+    follow(outcome.target);
   };
   for (const { call, site } of written) {
     record(call, site);
@@ -9131,17 +9418,14 @@ function scanBody(source, ctx, recognized, read, implied) {
       file: target.file.displayPath,
       span: spanOf(target.node)
     });
-    const key = keyOf2(target);
-    if (!seen.has(key)) {
-      seen.add(key);
-      followed.push(target);
-    }
+    follow(target);
   }
   return {
     followed,
     stops: stops.stops,
     targets: placements.targets,
     argTargets: placements.argTargets,
+    possibleTargets: placements.possibleTargets,
     parameterCalls,
     passedPositions
   };
@@ -9465,6 +9749,10 @@ var PackPositions = class {
     const [packAt, patternAt] = id.split("/").map(Number);
     return this.packs[packAt ?? -1]?.discovery[patternAt ?? -1];
   }
+  packOf(id) {
+    const [packAt] = id.split("/").map(Number);
+    return this.packs[packAt ?? -1];
+  }
   formAt(at) {
     const pack = this.packs[at[0]];
     const pattern = pack?.discovery[at[1]];
@@ -11559,7 +11847,10 @@ var PythonWrapperIndex = class {
   /** By wrapper reference: the parameters a dependency function declares, and its file. */
   dependencyParameterTable = /* @__PURE__ */ new Map();
   unitsByFile = /* @__PURE__ */ new Map();
-  /** Told about every registration, so a cache can repeat the ones a file's discovery made. */
+  /**
+   * Told about every registration, a pack's form or a project decorator's
+   * closure, so a cache can repeat the ones a file's discovery made.
+   */
   onRegistered = null;
   /**
    * The same lookup `wrappersFor` noted under `id`, made again over this
@@ -11640,6 +11931,25 @@ var PythonWrapperIndex = class {
     }
     return { reference, form: declared.form };
   }
+  /**
+   * The unit for the closure a project's decorator hands back, built once
+   * however many routes the decorator is written on. Its name is what
+   * calling the decorator writes, since the decorator may have a summary
+   * of its own under its name.
+   */
+  registeredClosure(target, closure) {
+    this.onRegistered?.(target, closure);
+    const span = spanOf(target.node);
+    const key = `${target.file.file}:${span.start}-${span.end}`;
+    if (!this.unitsByKey.has(key)) {
+      const unit = closureUnit(target, closure, 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 { file: target.file.displayPath, name: target.name };
+  }
   /**
    * The parameters the dependencies among these wrappers declare, and
    * whether one is declared through a parameter source such as `Query()`.
@@ -11671,9 +11981,13 @@ var PythonWrapperIndex = class {
       pattern: query.pattern,
       form
     }));
-    if (file === void 0 || forms.length === 0) {
+    if (file === void 0) {
       return [];
     }
+    const decorators = this.decoratorLayers(query, file);
+    if (forms.length === 0) {
+      return decorators;
+    }
     const own = this.ownRoutesOf(query);
     const found = [
       ...this.noted(
@@ -11711,7 +12025,68 @@ var PythonWrapperIndex = class {
       seen.add(key);
       ordered.push(wrapper.reference);
     }
-    return ordered;
+    return [
+      ...ordered.filter((one) => one.onThrow !== true),
+      ...decorators,
+      ...ordered.filter((one) => one.onThrow === true)
+    ];
+  }
+  /**
+   * The decorators written on the route's function below the one that
+   * registers it, outermost first. Each wraps the function the library
+   * calls. None has a summary: a library's has no body in the run, and a
+   * project's own is not composed into the route yet, so a project
+   * decorator goes by what calling it writes, `require_admin(fn)`, which
+   * no summary is named. The decorators the packs read, such as the
+   * route's own and the namespace's `@ns.doc`, are left out.
+   */
+  decoratorLayers(query, file) {
+    const decorated = query.definitionNode.parent;
+    if (decorated === null || decorated.type !== "decorated_definition") {
+      return [];
+    }
+    const written = stripDecorators(decorated).decorators;
+    const routeAt = written.findIndex(
+      (decorator) => sameRange(rangeOf(decorator), query.classification.range)
+    );
+    return written.slice(routeAt + 1).flatMap((decorator) => this.decoratorLayer(decorator, query, file));
+  }
+  decoratorLayer(decorator, query, file) {
+    const facts = this.options.facts;
+    const direct = classifyDecorator(decorator, query.module, facts);
+    const written = decoratorCallee(decorator);
+    if (written === null || direct.module !== null && readByAPack(direct.module, this.options) || direct.objectName !== null && direct.objectName === query.classification.objectName || unwrapDecorator(decorator, facts) !== null) {
+      return [];
+    }
+    const project = written.type === "identifier" ? this.functionCalled(file.file, written.text) : null;
+    if (project !== null) {
+      if (facts !== void 0) {
+        noteKeyRead6(facts, project.file.file);
+      }
+      return [this.projectDecoratorLayer(project, query)];
+    }
+    return [{ file: direct.module ?? file.displayPath, name: written.text }];
+  }
+  /**
+   * The layer a project's own decorator puts around the route. When it
+   * hands back a closure written inside it that returns what calling the
+   * function it was given returns, the closure is summarized and
+   * composed into the route. Any other decorator, including one whose
+   * closure keeps going after that call, goes by the same name with no
+   * summary behind it.
+   */
+  projectDecoratorLayer(decorator, query) {
+    const continuation = parameterNamesOf(decorator.node)[0] ?? "";
+    const name = `${decorator.name}(${continuation})`;
+    const closure = closureReturnedBy(decorator.node);
+    const handsOn = closure === null || continuation === "" ? [] : callsThrough(closure, continuation);
+    if (closure === null || handsOn.length === 0 || !handsOn.every((statement) => returnsCallTo(statement, continuation))) {
+      return { file: decorator.file.displayPath, name };
+    }
+    return this.registeredClosure(
+      { file: decorator.file, node: closure, name, exportPath: [] },
+      { pack: query.pack, pattern: query.pattern, continuation }
+    );
   }
   /**
    * What the mounts above the route's router register on the way down:
@@ -11872,6 +12247,21 @@ var PythonWrapperIndex = class {
 function referenceKey(reference) {
   return `${reference.file}::${reference.name}`;
 }
+function readByAPack(module, options) {
+  return options.packs.some(
+    (pack) => pack.discovery.some((pattern) => pattern.importModule.includes(module))
+  );
+}
+function decoratorCallee(decorator) {
+  const written = decorator.namedChild(0);
+  if (written === null) {
+    return null;
+  }
+  return written.type === "call" ? field(written, "function") : written;
+}
+function sameRange(a, b) {
+  return a.start === b.start && a.end === b.end;
+}
 function parameterNamesOf(definition) {
   return children(field(definition, "parameters")).flatMap((parameter) => {
     const named = parameterNameAndType(parameter);
@@ -12059,16 +12449,42 @@ function parameterDependencies(definitionNode, form) {
   return names;
 }
 function wrapperUnit(target, declared, options) {
+  return unitAround(
+    target,
+    declared.pattern,
+    {
+      continuations: continuationStatements(target.node, declared.form),
+      continuationName: null,
+      form: declared.form,
+      nameKind: "binding"
+    },
+    options
+  );
+}
+function closureUnit(target, closure, options) {
+  return unitAround(
+    target,
+    closure.pattern,
+    {
+      continuations: callsThrough(target.node, closure.continuation),
+      continuationName: closure.continuation,
+      form: null,
+      nameKind: "label"
+    },
+    options
+  );
+}
+function unitAround(target, pattern, reading, options) {
   const { file, node, name, exportPath } = target;
   const body = field(node, "body");
   const range = rangeOf(node);
   const raised = raisedResponses(body, {
-    calls: declared.pattern.responseStatusCalls ?? [],
+    calls: pattern.responseStatusCalls ?? [],
     module: file.module,
     facts: options.facts,
-    constants: declared.pattern.statusCodeConstants ?? {}
+    constants: pattern.statusCodeConstants ?? {}
   });
-  const continuations = continuationStatements(node, declared.form);
+  const continuations = reading.continuations;
   const terminals = bodyTerminals(body, raised, continuations);
   const effects = invocationEffects(node, options.facts);
   const extra = recognizedBodyEffects(
@@ -12077,7 +12493,7 @@ function wrapperUnit(target, declared, options) {
     options.storageFor(file),
     options.facts
   );
-  const delegate = (at) => ({
+  const delegate = (at, to = null) => ({
     terminal: {
       kind: "delegate",
       statusCode: null,
@@ -12086,18 +12502,18 @@ function wrapperUnit(target, declared, options) {
       message: null,
       component: null,
       renderTree: null,
-      delegateTarget: null,
+      delegateTarget: to,
       emitEvent: null,
       location: rangeOf(at)
     },
     location: rangeOf(at)
   });
   const respond = (statement) => returnBranch(statement, {
-    pattern: declared.pattern,
+    pattern,
     responseShape: { reading: absentReading2 },
     declaredStatus: {
       reading: absentReading2,
-      ...declared.pattern.defaultStatusCode !== void 0 ? { libraryDefault: declared.pattern.defaultStatusCode } : {}
+      ...pattern.defaultStatusCode !== void 0 ? { libraryDefault: pattern.defaultStatusCode } : {}
     },
     module: file.module,
     facts: options.facts
@@ -12109,7 +12525,10 @@ function wrapperUnit(target, declared, options) {
         location: rangeOf(terminal.statement)
       };
     }
-    if (terminal.type === "continuation" || returnHandsOn(terminal.statement, declared.form)) {
+    if (terminal.type === "continuation") {
+      return delegate(terminal.statement, reading.continuationName);
+    }
+    if (reading.form !== null && returnHandsOn(terminal.statement, reading.form)) {
       return delegate(terminal.statement);
     }
     return respond(terminal.statement);
@@ -12126,7 +12545,7 @@ function wrapperUnit(target, declared, options) {
   return {
     identity: {
       name,
-      nameKind: "binding",
+      nameKind: reading.nameKind,
       kind: "middleware",
       file: file.displayPath,
       range,
@@ -12162,23 +12581,45 @@ function continuationStatements(node, form) {
   const params = children(field(node, "parameters"));
   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 [];
-  }
+  return continuation === null ? [] : callsThrough(node, continuation);
+}
+function callsThrough(node, callee) {
   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;
+    const called = field(call, "function");
+    const statement = called?.type === "identifier" && called.text === callee ? enclosingStatement(call, body) : null;
     if (statement !== null) {
       found.push(statement);
     }
   }
   return found;
 }
+function returnsCallTo(statement, callee) {
+  if (statement.type !== "return_statement") {
+    return false;
+  }
+  const value = statement.namedChild(0);
+  const call = value?.type === "await" ? value.namedChild(0) : value;
+  return call?.type === "call" && field(call, "function")?.text === callee;
+}
+function closureReturnedBy(decorator) {
+  const statements = children(field(decorator, "body"));
+  const returned = statements.find((statement) => statement.type === "return_statement")?.namedChild(0);
+  if (returned?.type !== "identifier") {
+    return null;
+  }
+  for (const statement of statements) {
+    const { definition } = stripDecorators(statement);
+    if (definition.type === "function_definition" && field(definition, "name")?.text === returned.text) {
+      return definition;
+    }
+  }
+  return null;
+}
 
 // src/project.ts
 function keptPythonParses() {
@@ -12273,7 +12714,7 @@ async function extractPythonProject(options) {
   const { roots, unreadManifests } = rootsOfRun(options);
   const timer = options.onTiming !== void 0 ? createTimer() : noopTimer();
   const cacheDir = adapterStamp.declineWhenRunFromSource(
-    options.cacheDir === null ? null : options.cacheDir ?? (options.projectRoot !== void 0 ? path5.join(options.projectRoot, ".suss", "cache") : null)
+    options.cacheDir === null ? null : options.cacheDir ?? (options.projectRoot !== void 0 ? extractionCacheDirFor(options.projectRoot) : null)
   );
   const layer = createCacheLayer(cacheDir);
   const packsDigest = `${adapterStamp.packsDigest(
@@ -12296,11 +12737,14 @@ async function extractPythonProject(options) {
     "cache.lookup",
     () => layer.lookup(input)
   );
+  const composed = (stored) => composeWrappers(stored, {
+    gapHandling: options.gapHandling ?? "permissive"
+  });
   if (lookup.kind === "hit") {
     options.onCacheDiagnostic?.(lookup.diagnostic);
     options.onTiming?.(timer.report());
     return {
-      summaries: lookup.summaries,
+      summaries: composed(lookup.summaries),
       facts: new Database2(),
       roots,
       unreadManifests
@@ -12315,7 +12759,7 @@ async function extractPythonProject(options) {
     options.onCacheDiagnostic?.({ kind: "hit" });
     options.onTiming?.(timer.report());
     return {
-      summaries: plan.allSummaries(),
+      summaries: composed(plan.allSummaries()),
       facts: new Database2(),
       roots,
       unreadManifests
@@ -12497,15 +12941,10 @@ async function runPython(options, roots, cache, previous) {
   });
   let registering = null;
   if (ledger !== null) {
-    wrapperIndex.onRegistered = (target, declared) => {
-      const form = positions.positionOf(declared);
-      if (registering !== null && form !== void 0) {
-        registering.push({
-          key: nodeId(target.file.file, target.node),
-          name: target.name,
-          exportPath: target.exportPath,
-          form
-        });
+    wrapperIndex.onRegistered = (target, how) => {
+      const stored = storedRegistration(target, how, positions);
+      if (registering !== null && stored !== null) {
+        registering.push(stored);
       }
     };
   }
@@ -12518,12 +12957,11 @@ async function runPython(options, roots, cache, previous) {
     if (record !== void 0) {
       discoveries.set(file, record);
       for (const registration of record.registrations) {
-        const declared = positions.formAt(registration.form);
-        const target = storedFunction(registration, definitions, filesByPath);
-        if (declared === void 0 || target === null) {
-          throw new ReplayFailed(registration.key);
-        }
-        wrapperIndex.registered(target, declared);
+        registerAgain(registration, {
+          positions,
+          wrapperIndex,
+          target: storedFunction(registration, definitions, filesByPath)
+        });
       }
       continue;
     }
@@ -12692,6 +13130,7 @@ async function runPython(options, roots, cache, previous) {
     }
     placeCalls2(summary, reached.targetsByKey.get(key));
     placeArgTargets2(summary, reached.argTargetsByKey.get(key));
+    placePossibleCalls2(summary, reached.possibleTargetsByKey.get(key));
     placeCalleeParameters2(summary, reached.parameterCallsByKey.get(key));
   };
   for (const [key, owners] of summariesBySeed) {
@@ -12781,16 +13220,20 @@ async function runPython(options, roots, cache, previous) {
     markExitCodeFunctions(summaries, exits, db, options.workspaceRoot);
     return composeWrappers(summaries, { gapHandling });
   });
+  const walkedFiles = new Map(
+    bound.map(({ file, displayPath }) => [displayPath, file])
+  );
   await timer.timeAsync("cache.write", async () => {
-    if (cacheDir === null || composed.length === 0) {
+    if (cacheDir === null || summaries.length === 0) {
       return;
     }
     try {
       await cache.layer.write(
         cache.input,
-        composed,
+        summaries,
         log === null || ledger === null || overBudget ? void 0 : pythonAttribution({
-          composed,
+          summaries,
+          walkedFileOf: (locationFile) => walkedFiles.get(locationFile),
           discoveries,
           charges,
           unitDrafts,
@@ -12845,6 +13288,39 @@ async function runPython(options, roots, cache, previous) {
   options.onTiming?.(timer.report());
   return { summaries: composed, facts: db };
 }
+function storedRegistration(target, how, positions) {
+  const at = {
+    key: nodeId(target.file.file, target.node),
+    name: target.name,
+    exportPath: target.exportPath
+  };
+  if ("continuation" in how) {
+    const pattern = positions.idOf(how.pattern);
+    return pattern === void 0 ? null : { ...at, pattern, continuation: how.continuation };
+  }
+  const form = positions.positionOf(how);
+  return form === void 0 ? null : { ...at, form };
+}
+function registerAgain(registration, context) {
+  const { positions, wrapperIndex, target } = context;
+  const how = howRegistered(registration, positions);
+  if (target === null || how === null) {
+    throw new ReplayFailed(registration.key);
+  }
+  if ("continuation" in how) {
+    wrapperIndex.registeredClosure(target, how);
+    return;
+  }
+  wrapperIndex.registered(target, how);
+}
+function howRegistered(registration, positions) {
+  if (!("continuation" in registration)) {
+    return positions.formAt(registration.form) ?? null;
+  }
+  const pack = positions.packOf(registration.pattern);
+  const pattern = positions.patternOf(registration.pattern);
+  return pack === void 0 || pattern === void 0 ? null : { pack, pattern, continuation: registration.continuation };
+}
 function pythonAttribution(args) {
   const walkedByFile = walkRecordsByFile({
     scans: args.reached.scans,
@@ -12873,7 +13349,10 @@ function pythonAttribution(args) {
       }
     };
   });
-  return { roots, owners: args.composed.map(() => []) };
+  return {
+    roots,
+    owners: ownersWhereWritten(args.summaries, args.walkedFileOf)
+  };
 }
 var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set([
   "__pycache__",