@suss/adapter-python 0.35.0 → 0.36.0

package/dist/index.js

@@ -989,6 +989,8 @@ import {
   addTemplateRows,
   NAMED_STORE_NAME,
   RECEIVER_STORE_NAME,
+  SELF_AS_CLASS_NAME,
+  SELF_AS_INSTANCE_NAME,
   SPREAD_ENTRY,
   startsAtName,
   UNPLACED_STORE_NAME,
@@ -1005,6 +1007,8 @@ var CONVERTING_BUILTINS = /* @__PURE__ */ new Set([
 ]);
 var ATTRIBUTE_GETTER = "getattr";
 var POSITION_COUNTER = "enumerate";
+var CLASS_METHOD_DECORATOR = "classmethod";
+var STATIC_METHOD_DECORATOR = "staticmethod";
 
 // src/facts/values.ts
 function nodeId(filePath, node) {
@@ -1684,6 +1688,26 @@ function yieldedValue(node) {
   }
   return children(node).find((child) => child?.type !== "comment") ?? null;
 }
+function emitReceiver(emitter, fn, paramKey, classKey) {
+  const form = receiverFormOf(fn);
+  if (form === SELF_AS_CLASS_NAME) {
+    add(emitter, "binds", paramKey, classKey);
+  } else {
+    add(emitter, "instanceOf", paramKey, classKey);
+  }
+  if (form !== null) {
+    add(emitter, "selfReceiver", nodeId(emitter.filePath, fn), paramKey, form);
+  }
+}
+function receiverFormOf(fn) {
+  const decorators = fn.parent?.type === "decorated_definition" ? stripDecorators(fn.parent).decorators.map(
+    (decorator) => decorator.text.slice(1).trim()
+  ) : [];
+  if (decorators.includes(STATIC_METHOD_DECORATOR)) {
+    return null;
+  }
+  return decorators.includes(CLASS_METHOD_DECORATOR) ? SELF_AS_CLASS_NAME : SELF_AS_INSTANCE_NAME;
+}
 function emitFunctionFacts(emitter, fn, classKey) {
   const funcKey = nodeId(emitter.filePath, fn);
   add(emitter, "func", funcKey);
@@ -1707,7 +1731,7 @@ function emitFunctionFacts(emitter, fn, classKey) {
       }
       if (classKey !== void 0 && position === -1) {
         receiver = { classKey, name: paramName.text };
-        add(emitter, "instanceOf", paramKey, classKey);
+        emitReceiver(emitter, fn, paramKey, classKey);
       }
       add(emitter, "paramNamed", funcKey, paramName.text, paramKey);
       const fallback2 = field(param, "value");
@@ -3796,6 +3820,7 @@ import {
   absentReading,
   ambiguousReading,
   andThenReading,
+  effectsFiringOn as effectsFiringOn2,
   firstWrittenReading,
   mapReading,
   unreadableReading,
@@ -3816,7 +3841,7 @@ import { redirectDeliveryWhenSet } from "@suss/extractor";
 import { hostOf, pathOf, scalarOf } from "@suss/values";
 
 // src/paths/bodyBranches.ts
-import { enumerateOrDegrade as enumerateOrDegrade2, guardsHoldOn } from "@suss/extractor";
+import { effectsFiringOn, enumerateOrDegrade } from "@suss/extractor";
 
 // src/provenance.ts
 import { sourceRefsOf } from "@suss/extractor";
@@ -3953,7 +3978,7 @@ import { storageBinding as storageBinding2 } from "@suss/ir-core";
 import { answersFor } from "@suss/resolution";
 
 // src/paths/effects.ts
-import { enumerateOrDegrade, sharedGatingConditions } from "@suss/extractor";
+import { sharedGatingConditions, statementSites } from "@suss/extractor";
 import { constantOf as constantOf2, literalOf as literalOf4 } from "@suss/values";
 
 // src/paths/lowering.ts
@@ -4067,6 +4092,7 @@ var Lowerer = class {
     ) ?? null;
     return {
       kind: "try",
+      lines: rangeOf(node),
       tryBody: this.lowerBlock(field(node, "body")),
       catchBody: excepts.length > 0 ? excepts.flatMap((clause) => this.lowerBlock(childBlock(clause))) : null,
       finallyBody: finallyClause === null ? null : this.lowerBlock(childBlock(finallyClause)),
@@ -4107,12 +4133,19 @@ var Lowerer = class {
     }
     if (node.type === "while_statement" || node.type === "for_statement") {
       const header = node.type === "while_statement" ? field(node, "condition") : field(node, "right");
+      const body = field(node, "body");
       return this.attach(
         {
           kind: "loop",
           condition: handleOf(header),
-          body: this.lowerBlock(field(node, "body")),
-          exitKind: exitKindOf(node, this.thrown)
+          body: this.lowerBlock(body),
+          exitKind: exitKindOf(node, this.thrown),
+          // An `else` clause runs once the loop is done, so it is no part
+          // of what repeats.
+          lines: {
+            start: rangeOf(node).start,
+            end: rangeOf(body ?? node).end
+          }
         },
         [header]
       );
@@ -4144,6 +4177,9 @@ function lowerPythonBody(body, terminals, thrown = new NodeSet()) {
 // src/paths/effects.ts
 var NESTED_DEFINITION_TYPES = /* @__PURE__ */ new Set(["function_definition"]);
 function literalArgOf(node, facts) {
+  if (node.type === "none") {
+    return { kind: "null" };
+  }
   const value = evaluatedValue(node, facts);
   const text2 = literalOf4(value);
   if (text2 !== null) {
@@ -4221,9 +4257,6 @@ function argsOf(call, facts) {
 function calleeText(call) {
   return field(call, "function")?.text ?? call.text;
 }
-function invocationEffects(definitionNode, facts) {
-  return invocationSites(definitionNode, facts).map((site) => site.effect);
-}
 function invocationSites(definitionNode, facts) {
   const body = field(definitionNode, "body");
   if (body === null) {
@@ -4279,33 +4312,26 @@ function gatingInputs(body, gatingOf, facts) {
   );
   return operands.length === 0 ? void 0 : guardInputs(operands, { facts, unit });
 }
+function sitesIn(body, nodes) {
+  return statementSites(nodes, {
+    statementOf: (node) => enclosingStatement(node, body),
+    lower: (statements) => lowerPythonBody(body, statements),
+    firstLine: (node) => rangeOf(node).start
+  });
+}
+function effectSitesIn(body, nodes) {
+  if (body === null || nodes.length === 0) {
+    return (node) => ({ line: rangeOf(node).start });
+  }
+  return sitesIn(body, nodes).plainSiteOf;
+}
 function invocationEffectsIn(body, written, facts) {
   const calls = [...written].sort((a, b) => a.endIndex - b.endIndex);
   if (calls.length === 0) {
     return [];
   }
-  const statementOf3 = /* @__PURE__ */ new Map();
-  const statements = [];
-  for (const call of calls) {
-    const statement = enclosingStatement(call, body);
-    if (statement === null) {
-      continue;
-    }
-    statementOf3.set(call.id, statement);
-    statements.push(statement);
-  }
-  const lowered = lowerPythonBody(body, statements);
-  const enumerated = enumerateOrDegrade(
-    {
-      statements: lowered.statements,
-      terminalsByStmt: lowered.terminalsByStmt
-    },
-    statements
-  );
-  const gatingOf = calls.map((call) => {
-    const statement = statementOf3.get(call.id);
-    return statement === void 0 ? void 0 : enumerated.byTerminal.get(statement);
-  });
+  const sites = sitesIn(body, calls);
+  const gatingOf = calls.map((call) => sites.pathsTo(call));
   askWrittenValues(
     calls.flatMap((call, index) => effectValueNodes(call, gatingOf[index])),
     facts
@@ -4323,8 +4349,10 @@ function invocationEffectsIn(body, written, facts) {
         callee: calleeText(call),
         args: argsOf(call, facts),
         async: false,
-        ...conditions.length > 0 ? { preconditions: conditions } : {}
-      }
+        ...conditions.length > 0 ? { preconditions: conditions } : {},
+        location: rangeOf(call)
+      },
+      site: sites.siteOf(call, conditions)
     };
   });
 }
@@ -4429,7 +4457,7 @@ function rawSqlEffects(calls, options) {
   for (const match of matchesIn(calls, options)) {
     for (const access of match.accesses) {
       const effect = effectFor(match, access);
-      found.effects.push(effect);
+      found.effects.push({ effect, at: match.call });
       for (const slot of boundSlots(access, match.binds)) {
         found.slots.push({ ...slot, effect });
       }
@@ -4536,7 +4564,8 @@ function effectFor(match, access) {
       fields: access.fields,
       ...access.selector.length > 0 ? { selector: access.selector } : {},
       operation
-    }
+    },
+    location: rangeOf(match.call)
   };
 }
 var NO_GROUP = "default";
@@ -5050,7 +5079,8 @@ function effectFor2(pattern, chain, operation, options) {
       fields: fieldsOf(chain, valueMethods),
       operation,
       ...picked.length > 0 ? { selector: picked } : {}
-    }
+    },
+    location: rangeOf(chain.last)
   };
   if (options.statesSlots !== void 0) {
     const slots = slotsOf(chain, valueMethods);
@@ -5147,7 +5177,12 @@ function storageCallIds(calls, options) {
 }
 function storageEffects(calls, options) {
   return matchedChains(calls, options).flatMap(
-    ({ chain, pattern, operation }) => operation === null ? [] : [effectFor2(pattern, chain, operation, options)]
+    ({ chain, pattern, operation }) => operation === null ? [] : [
+      {
+        effect: effectFor2(pattern, chain, operation, options),
+        at: chain.last
+      }
+    ]
   );
 }
 var storageByScope = /* @__PURE__ */ new WeakMap();
@@ -5345,11 +5380,6 @@ function bodyTerminals(body, raised, continuations = []) {
   ];
   return found.sort((a, b) => a.statement.startIndex - b.statement.startIndex);
 }
-function effectsReaching(effects, conditions) {
-  return effects.filter(
-    (effect) => guardsHoldOn(effect.preconditions, conditions)
-  );
-}
 function conditionInputs(pathSets, options) {
   const unit = options.body?.parent ?? null;
   if (options.facts === void 0 || unit === null) {
@@ -5371,7 +5401,7 @@ function enumerateBodyBranches(options) {
     ...options.terminals.filter((found) => found.type === "continuation").map((found) => found.statement)
   ]);
   const lowered = lowerPythonBody(options.body, statements, leavesByCall);
-  const enumerated = enumerateOrDegrade2(
+  const enumerated = enumerateOrDegrade(
     {
       statements: lowered.statements,
       terminalsByStmt: lowered.terminalsByStmt,
@@ -5384,7 +5414,8 @@ function enumerateBodyBranches(options) {
     options
   );
   const branches = [];
-  const push = (branch, paths) => {
+  const push = (branch, paths, placement) => {
+    const loopAround = placement?.loopAround;
     for (const path8 of paths) {
       const conditions = path8.map((condition) => ({
         sourceText: condition.sourceText,
@@ -5392,10 +5423,14 @@ function enumerateBodyBranches(options) {
         polarity: condition.polarity,
         source: condition.source
       }));
-      branches.push({
+      const ending = {
         ...branch,
         conditions,
-        effects: effectsReaching(options.effects, conditions),
+        ...loopAround === void 0 ? {} : { loopAround }
+      };
+      branches.push({
+        ...ending,
+        effects: effectsFiringOn(options.effects, ending),
         isDefault: path8.length === 0
       });
     }
@@ -5403,11 +5438,15 @@ function enumerateBodyBranches(options) {
   for (const found of options.terminals) {
     const paths = enumerated.byTerminal.get(found.statement);
     if (paths !== void 0) {
-      push(options.branchOf(found), paths);
+      push(
+        options.branchOf(found),
+        paths,
+        enumerated.placement.get(found.statement)
+      );
     }
   }
   if (options.fallthrough !== void 0) {
-    push(options.fallthrough, enumerated.fallthrough);
+    push(options.fallthrough, enumerated.fallthrough, void 0);
   }
   return branches;
 }
@@ -5582,15 +5621,10 @@ function writtenMessageOf(call) {
 import { helperPathsOnVariables, splitAtHandOffs } from "@suss/extractor";
 function throughResponseHelpers(branches, sites, options) {
   const handOffs = [];
-  for (const { call, effect } of sites) {
+  for (const { call, site } of sites) {
     const helper = helperBranchesAt(call, options);
     if (helper !== null) {
-      handOffs.push({
-        helper,
-        preconditions: effect.preconditions,
-        line: rangeOf(call).start,
-        at: rangeOf(call)
-      });
+      handOffs.push({ ...site, helper, at: rangeOf(call) });
     }
   }
   return handOffs.length === 0 ? [...branches] : branches.flatMap((branch) => splitAtHandOffs(branch, handOffs));
@@ -5837,7 +5871,7 @@ function callerBranches(definition, reading) {
     body,
     terminals: bodyTerminals(body, raised),
     raised,
-    effects,
+    effects: sites,
     branchOf: (found2) => found2.type === "raise" ? { terminal: found2.terminal, location: rangeOf(found2.statement) } : handsBackAt(rangeOf(found2.statement)),
     fallthrough: handsBackAt(range),
     facts: reading.facts,
@@ -6417,9 +6451,7 @@ function envReadEffects(root, module, facts) {
       const syntax = envReadSyntaxAt(node, scope);
       if (syntax !== null) {
         const name = stringLiteralValue(syntax.name);
-        if (name !== null) {
-          slots.push({ read: { name, defaulted: syntax.defaulted } });
-        }
+        slots.push({ read: { name, defaulted: syntax.defaulted }, at: node });
         return;
       }
       if (readsHelpers && node.type === "call") {
@@ -6439,21 +6471,25 @@ function envReadEffects(root, module, facts) {
   );
   return slots.flatMap((slot) => {
     if ("read" in slot) {
-      return [configReadEffect(slot.read)];
+      return [{ effect: configReadEffect(slot.read, slot.at), at: slot.at }];
     }
-    return throughHelpers.get(slot.call.id) ?? [];
+    return (throughHelpers.get(slot.call.id) ?? []).map((effect) => ({
+      effect,
+      at: slot.call
+    }));
   });
 }
-function configReadEffect(read) {
+function configReadEffect(read, at) {
   return {
     type: "interaction",
     binding: runtimeConfigBinding({ recognition: PYTHON_ENV_RECOGNITION }),
-    callee: `os.environ["${read.name}"]`,
+    callee: read.name === null ? at.text : `os.environ["${read.name}"]`,
     interaction: {
       class: "config-read",
       name: read.name,
       defaulted: read.defaulted
-    }
+    },
+    location: rangeOf(at)
   };
 }
 function envReadSyntaxAt(node, scope) {
@@ -6659,6 +6695,15 @@ function argumentsByParameter(db, call, calleeKey2) {
   }
   return argumentAt2;
 }
+function handsOnParameter(argument) {
+  const caller = enclosingFunction(argument);
+  if (argument.type !== "identifier" || caller === null) {
+    return false;
+  }
+  return children(field(caller, "parameters")).some(
+    (param) => parameterIdentifier(param)?.text === argument.text
+  );
+}
 function readsThroughHelper(db, call, argumentAt2, siteById, named) {
   const reads = /* @__PURE__ */ new Map();
   for (const [parameter, argument] of argumentAt2) {
@@ -6668,7 +6713,7 @@ function readsThroughHelper(db, call, argumentAt2, siteById, named) {
       `${NAMED_PARAMETER}${parameter}`,
       describeSites(sites, siteById)
     );
-    if (sites === void 0) {
+    if (sites === void 0 || handsOnParameter(argument)) {
       continue;
     }
     const name = stringLiteralValue(argument) ?? stringValueOf(argument, db);
@@ -6685,7 +6730,7 @@ function readsThroughHelper(db, call, argumentAt2, siteById, named) {
   }
   const defaultedAtCall = isDefaultedAt(call);
   return [...reads].map(
-    ([name, defaulted]) => configReadEffect({ name, defaulted: defaulted || defaultedAtCall })
+    ([name, defaulted]) => configReadEffect({ name, defaulted: defaulted || defaultedAtCall }, call)
   );
 }
 
@@ -6762,7 +6807,12 @@ function returnedBodyShape(statement) {
 
 // src/streamWrites.ts
 import { ioBinding } from "@suss/behavioral-ir";
-import { SKIP_CHILDREN as SKIP_CHILDREN2, walkDescendants as walkDescendants2 } from "@suss/extractor";
+import {
+  callSiteKey,
+  numberRepeatedCallSites,
+  SKIP_CHILDREN as SKIP_CHILDREN2,
+  walkDescendants as walkDescendants2
+} from "@suss/extractor";
 
 // src/stdlibNames.ts
 function isStdlibModule(node, scope, module) {
@@ -6792,6 +6842,11 @@ var PYTHON_STREAM_RECOGNITION = "python-stdlib";
 var STREAMS = /* @__PURE__ */ new Set(["stdout", "stderr"]);
 var DEFERRED_BODY_TYPES2 = /* @__PURE__ */ new Set(["function_definition", "lambda"]);
 function streamWriteEffects(root, module) {
+  return numberRepeatedCallSites(
+    writesUnder(root, module).map((write) => [write])
+  ).flat();
+}
+function writesUnder(root, module) {
   const found = [];
   const startScope = module.scopeFor.get(root.id) ?? module.moduleScope;
   walkDescendants2(root, startScope, children, {
@@ -6801,7 +6856,7 @@ function streamWriteEffects(root, module) {
       }
       const write = streamWriteAt(node, scope);
       if (write !== null) {
-        found.push(write);
+        found.push({ effect: write, at: node });
       }
     },
     into: (node, scope) => {
@@ -6840,16 +6895,17 @@ function standardStream(node, scope) {
 }
 function writeEffect(site) {
   const { call, callee, target } = site;
-  return {
+  const effect = {
     type: "interaction",
     binding: ioBinding({ recognition: PYTHON_STREAM_RECOGNITION, target }),
     callee,
-    groupId: `${call.startPosition.row + 1}:${call.startPosition.column + 1}`,
     interaction: {
       class: "stream-write",
       ...payloadOf(site.positional, site.scope)
-    }
+    },
+    location: rangeOf(call)
   };
+  return { ...effect, groupId: callSiteKey(effect) };
 }
 function payloadOf(args, scope) {
   const only = args[0];
@@ -7710,7 +7766,8 @@ function buildRouteUnit(options) {
     options.responseShape,
     () => readReturnAnnotation(definitionNode, enclosingScope, ctx)
   );
-  const effects = invocationEffects(definitionNode, options.facts);
+  const calls = invocationSites(definitionNode, options.facts);
+  const effects = calls.map((call) => call.effect);
   const extra = recognizedBodyEffects(
     definitionNode,
     module,
@@ -7719,7 +7776,7 @@ function buildRouteUnit(options) {
   );
   const perTerminal = branchesPerTerminal({
     definitionNode,
-    effects,
+    effects: calls,
     responseStatusCalls: options.responseStatusCalls,
     ctx: {
       pattern,
@@ -7862,12 +7919,17 @@ function unreadRoleReadings(parameters, range) {
 }
 function recognizedBodyEffects(definitionNode, module, storageLookup, facts) {
   const storage = storageLookup === void 0 ? { effects: [], slots: [] } : bodyStorage(definitionNode, storageLookup);
+  const found = [
+    ...envReadEffects(definitionNode, module, facts),
+    ...storage.effects,
+    ...streamWriteEffects(definitionNode, module)
+  ];
+  const siteOf2 = effectSitesIn(
+    field(definitionNode, "body"),
+    found.map((one) => one.at)
+  );
   return {
-    effects: [
-      ...envReadEffects(definitionNode, module, facts),
-      ...storage.effects,
-      ...streamWriteEffects(definitionNode, module)
-    ],
+    effects: found.map(({ effect, at }) => ({ effect, site: siteOf2(at) })),
     provenance: storage.slots.length === 0 || storageLookup === void 0 ? [] : slotProvenance(storage.slots, {
       facts: storageLookup.facts,
       unit: definitionNode
@@ -7875,12 +7937,13 @@ function recognizedBodyEffects(definitionNode, module, storageLookup, facts) {
   };
 }
 function withBodyEffects(branch, extra) {
-  if (extra.effects.length === 0) {
+  const effects = effectsFiringOn2(extra.effects, branch);
+  if (effects.length === 0) {
     return branch;
   }
   return {
     ...branch,
-    extraEffects: extra.effects,
+    extraEffects: effects,
     ...extra.provenance.length === 0 ? {} : { provenance: extra.provenance }
   };
 }
@@ -8315,6 +8378,33 @@ function buildPythonExtractionReport(args) {
   });
 }
 
+// src/reach/closure.ts
+import {
+  functionCallBinding,
+  placeArgTargets,
+  placeCalleeParameters,
+  placeCalls,
+  placePossibleCalls,
+  recordParameterGaps,
+  StopList,
+  sameDeclarations,
+  TargetPlacements,
+  unfollowedCallGap,
+  worthRecording
+} from "@suss/behavioral-ir";
+import { Database, evaluate, lit, rule, variable as v } from "@suss/datalog";
+import {
+  assembleSummary,
+  SKIP_CHILDREN as SKIP_CHILDREN5,
+  walkDescendants as walkDescendants6
+} from "@suss/extractor";
+import {
+  keptVariants,
+  noDependencies,
+  plainKeyOf,
+  variantKey
+} from "@suss/resolution";
+
 // src/exits.ts
 import {
   markReturnsAsExitCode,
@@ -8451,96 +8541,6 @@ function returnTerminal(shape, location) {
   };
 }
 
-// src/importedDefinitions.ts
-import { isObserved, noteKeyRead as noteKeyRead2 } from "@suss/resolution";
-function importedDefinitionLookup(db, files) {
-  const fileOfModuleScope = /* @__PURE__ */ new Map();
-  const byFile = /* @__PURE__ */ new Map();
-  for (const file of files) {
-    fileOfModuleScope.set(file.module.moduleScope.node.id, file.file);
-    byFile.set(file.file, file);
-  }
-  const found = /* @__PURE__ */ new Map();
-  return (scope, name) => {
-    const fromFile = fileOfModuleScope.get(moduleScopeOf(scope).node.id);
-    if (fromFile === void 0) {
-      return null;
-    }
-    const key = `${fromFile}#${name}`;
-    let definition = found.get(key);
-    if (definition === void 0) {
-      definition = definitionAmong(originsOf(db, key), byFile);
-      found.set(key, definition);
-    } else if (isObserved(db)) {
-      originsOf(db, key);
-    }
-    if (definition !== null) {
-      noteKeyRead2(db, definition.file);
-    }
-    return definition;
-  };
-}
-function definitionAmong(origins, byFile) {
-  for (const origin of origins) {
-    const file = byFile.get(origin.module);
-    const binding = file?.module.moduleScope.bindings.get(origin.name);
-    if (file === void 0 || binding === void 0) {
-      continue;
-    }
-    const node = definedNodeOf(binding);
-    if (node !== null) {
-      return {
-        node,
-        file: file.file,
-        moduleScope: file.module.moduleScope,
-        scopeFor: file.module.scopeFor
-      };
-    }
-  }
-  return null;
-}
-function definedNodeOf(binding) {
-  if (binding.kind === "classDef") {
-    return binding.node;
-  }
-  if (binding.kind === "assignment") {
-    return binding.value;
-  }
-  return null;
-}
-
-// src/moduleSurface.ts
-import { moduleExportBinding } from "@suss/behavioral-ir";
-import {
-  MODULE_SURFACE_RECOGNITION,
-  moduleOfFile,
-  settleModules
-} from "@suss/extractor";
-import { noteKeyRead as noteKeyRead4 } from "@suss/resolution";
-
-// src/reach/closure.ts
-import {
-  functionCallBinding,
-  placeArgTargets,
-  placeCalleeParameters,
-  placeCalls,
-  placePossibleCalls,
-  recordParameterGaps,
-  StopList,
-  TargetPlacements,
-  unfollowedCallGap,
-  worthRecording
-} from "@suss/behavioral-ir";
-import { Database, evaluate, lit, rule, variable as v } from "@suss/datalog";
-import {
-  assembleSummary,
-  SKIP_CHILDREN as SKIP_CHILDREN5,
-  walkDescendants as walkDescendants6
-} from "@suss/extractor";
-import {
-  noDependencies
-} from "@suss/resolution";
-
 // src/flags.ts
 import { SKIP_CHILDREN as SKIP_CHILDREN4, walkDescendants as walkDescendants5 } from "@suss/extractor";
 var PARSE_METHODS = /* @__PURE__ */ new Set(["parse_args", "parse_known_args"]);
@@ -8623,11 +8623,19 @@ function methodCalledOn(call) {
 
 // src/reach/resolveCallee.ts
 import {
+  answersFor as answersFor2,
   calleeOutcomeOf,
   calleeOutcomes,
   dispatchOutcomes,
-  noteKeyRead as noteKeyRead3,
+  fileOfKey,
+  memberOf,
+  nodeOfKey as nodeOfKey2,
+  noteKeyRead as noteKeyRead2,
   RECEIVER_STORE_NAME as RECEIVER_STORE_NAME2,
+  resolutionProgram as resolutionProgram2,
+  SELF_AS_CLASS_NAME as SELF_AS_CLASS_NAME2,
+  selfFormOf,
+  selfResultOf,
   writtenSourcesOf
 } from "@suss/resolution";
 var STOP_FOR = {
@@ -8643,14 +8651,21 @@ var NO_DECLARATION = {
 function calleeSpellings(calls, ctx) {
   const spellingOf = /* @__PURE__ */ new Map();
   const keys = /* @__PURE__ */ new Set();
+  const receivers = /* @__PURE__ */ new Set();
   for (const { call, site } of calls) {
     const spelling = spellingFor2(call, site, ctx);
     spellingOf.set(call.id, spelling);
     if (spelling.kind === "key") {
       keys.add(spelling.key);
     }
+    const receiver = receiverOf(call, site);
+    if (receiver !== null) {
+      receivers.add(receiver.key);
+    }
   }
-  return { spellingOf, outcomes: calleeOutcomes(ctx.facts, [...keys]) };
+  const outcomes = calleeOutcomes(ctx.facts, [...keys]);
+  resolveCalls(ctx.facts, [...receivers]);
+  return { spellingOf, outcomes };
 }
 function resolveCallee2(call, site, ctx, read) {
   const spelling = read?.spellingOf.get(call.id) ?? spellingFor2(call, site, ctx);
@@ -8658,10 +8673,100 @@ function resolveCallee2(call, site, ctx, read) {
     return spelling;
   }
   const outcome = read?.outcomes.get(spelling.key) ?? calleeOutcomeOf(ctx.facts, spelling.key);
-  if (selfCallInMixin(call, outcome, site, ctx)) {
-    return { kind: "stopped", reason: "selfCallInMixin" };
+  const settled = selfCallInMixin(call, outcome, site, ctx) ? { kind: "stopped", reason: "selfCallInMixin" } : asCallee(outcome, site.owner, ctx);
+  return onReceiverClass(call, site, ctx, settled) ?? settled;
+}
+function receiverOf(call, site) {
+  const callee = readThrough(field(call, "function"));
+  const object = callee?.type === "attribute" ? field(callee, "object") : null;
+  const name = callee === null ? void 0 : field(callee, "attribute")?.text;
+  if (object === null || name === void 0) {
+    return null;
+  }
+  return {
+    key: readKey(site.file.file, object, enclosingFunction(object)),
+    name
+  };
+}
+function onReceiverClass(call, site, ctx, settled) {
+  const own = ownReceiverOf(site, ctx);
+  const callee = readThrough(field(call, "function"));
+  if (callee?.type === "identifier") {
+    const calleeKey2 = readKey(
+      site.file.file,
+      callee,
+      enclosingFunction(callee)
+    );
+    return own !== null && selfFormOf(ctx.facts, calleeKey2, own.key) === SELF_AS_CLASS_NAME2 ? methodOn(own.cls, CONSTRUCTOR_METHOD, ctx) : null;
+  }
+  const read = receiverOf(call, site);
+  if (read === null) {
+    return null;
+  }
+  if (own !== null && selfFormOf(ctx.facts, read.key, own.key) !== null) {
+    return methodOn(own.cls, read.name, ctx);
+  }
+  const sentTo = classReturnedTo(read.key, own, ctx);
+  if (sentTo !== null) {
+    return methodOn(sentTo, read.name, ctx);
+  }
+  const receiverClass = settled.kind === "followed" ? onlyClassOf(read.key, ctx) : null;
+  return receiverClass === null || settled.kind !== "followed" ? null : { kind: "followed", target: runningOn(settled.target, receiverClass) };
+}
+function ownReceiverOf(site, ctx) {
+  const [row] = ctx.facts.lookup("selfReceiver", 0, site.owner);
+  const cls = site.receiverClass ?? classOfFunction(site.owner, ctx);
+  return row === void 0 || cls === null ? null : { key: String(row[1]), cls };
+}
+function classReturnedTo(key, own, ctx) {
+  const returned = selfResultOf(ctx.facts, key);
+  if (returned === null) {
+    return null;
+  }
+  if (own !== null && returned.receiver === own.key) {
+    return own.cls;
   }
-  return asCallee(outcome, site.owner, ctx);
+  resolveCalls(ctx.facts, [returned.receiver]);
+  return onlyClassOf(returned.receiver, ctx);
+}
+var CONSTRUCTOR_METHOD = "__init__";
+function methodOn(cls, name, ctx) {
+  const key = memberOf(ctx.facts, cls.key, name, resolutionProgram2());
+  const found = key === null ? null : functionCallee(key, ctx);
+  if (found === null || found.kind !== "followed") {
+    return null;
+  }
+  return { kind: "followed", target: runningOn(found.target, cls) };
+}
+function runningOn(target, cls) {
+  const owner = ownerClassOf(target.node);
+  if (owner === null || nodeId(target.file.file, owner) === cls.key) {
+    return target;
+  }
+  return {
+    ...target,
+    exportPath: [cls.name, target.name],
+    receiverClass: cls
+  };
+}
+function classOfFunction(functionKey2, ctx) {
+  const node = ctx.definitions.get(functionKey2);
+  const owner = node === void 0 ? null : ownerClassOf(node);
+  return owner === null ? null : subclassAt(owner, fileOfKey(functionKey2));
+}
+function onlyClassOf(key, ctx) {
+  const objects = answersFor2(ctx.facts, "wantedObjectOf", key);
+  const [only] = objects;
+  if (objects.length !== 1 || only === void 0) {
+    return null;
+  }
+  const file = ctx.filesByPath.get(fileOfKey(only));
+  const node = file === void 0 ? null : nodeOfKey2(/* @__PURE__ */ new Map([[file.file, file.root]]), only);
+  return node?.type === "class_definition" ? subclassAt(node, file?.file ?? fileOfKey(only)) : null;
+}
+function subclassAt(cls, file) {
+  const name = field(cls, "name")?.text;
+  return name === void 0 ? null : { key: nodeId(file, cls), name, file };
 }
 function selfCallInMixin(call, outcome, site, ctx) {
   if (outcome.kind !== "callerSupplied" || !outcome.key.startsWith(`${site.owner}#`)) {
@@ -8920,7 +9025,7 @@ function moduleNamed(from, module, relativeLevel, ctx) {
   if (file === void 0) {
     return null;
   }
-  noteKeyRead3(ctx.facts, file.file);
+  noteKeyRead2(ctx.facts, file.file);
   return { kind: "module", file };
 }
 
@@ -9018,7 +9123,10 @@ function reachedFunctions(seeds, options) {
         passedPositions.add(position);
       }
       const called = [];
-      for (const target of scan.followed) {
+      const calledHere = scan.followed.flatMap(
+        (target) => target.receiverClass === void 0 ? [target] : [plainOf(target), target]
+      );
+      for (const target of calledHere) {
         const calleeKey2 = keyOf2(target);
         if (!functionByKey.has(calleeKey2)) {
           functionByKey.set(calleeKey2, target);
@@ -9035,11 +9143,30 @@ function reachedFunctions(seeds, options) {
   if (ledger === void 0) {
     settleBodyValues(reached, functionByKey, options);
   }
+  const placementsOf = (key) => ({
+    targets: targetsByKey.get(key),
+    argTargets: argTargetsByKey.get(key),
+    possibleTargets: possibleTargetsByKey.get(key)
+  });
+  const onSubclass = keptVariants(
+    reached.flatMap(
+      (key) => functionByKey.get(key)?.receiverClass === void 0 ? [] : [
+        {
+          key,
+          differs: !sameDeclarations(
+            placementsOf(key),
+            placementsOf(plainKeyOf(key))
+          ),
+          calls: callsByKey.get(key) ?? []
+        }
+      ]
+    )
+  );
   const summaries = [];
   const summariesByKey = /* @__PURE__ */ new Map();
   for (const key of reached) {
     const target = functionByKey.get(key);
-    if (target === void 0) {
+    if (target === void 0 || target.receiverClass !== void 0 && !onSubclass.has(key)) {
       continue;
     }
     const kept = replay?.summaryOf(key);
@@ -9054,6 +9181,9 @@ function reachedFunctions(seeds, options) {
       const summary2 = assembleSummary(libraryUnit(target, options), {
         gapHandling: options.gapHandling
       });
+      if (target.receiverClass !== void 0) {
+        summary2.receiverClass = displayedClass(target.receiverClass, ctx);
+      }
       if (options.gapHandling !== "silent") {
         summary2.gaps.push(
           ...(stopsByKey.get(key) ?? []).map(unfollowedCallGap)
@@ -9191,7 +9321,8 @@ function storedScan(scan) {
     followed: scan.followed.map((target) => ({
       key: keyOf2(target),
       name: target.name,
-      exportPath: target.exportPath
+      exportPath: target.exportPath,
+      ...target.receiverClass === void 0 ? {} : { receiverClass: target.receiverClass }
     })),
     stops: scan.stops,
     targets: [...scan.targets],
@@ -9224,14 +9355,25 @@ function scanFromStored(stored, functionFor) {
   };
 }
 function keyOf2(target) {
-  return nodeId(target.file.file, target.node);
+  const key = nodeId(target.file.file, target.node);
+  return target.receiverClass === void 0 ? key : variantKey(key, target.receiverClass);
+}
+function plainOf(target) {
+  return reachedFunctionOf(target.file, target.node);
+}
+function placeOf(target, ctx) {
+  const place = { file: target.file.displayPath, span: spanOf(target.node) };
+  return target.receiverClass === void 0 ? place : { ...place, receiverClass: displayedClass(target.receiverClass, ctx) };
+}
+function displayedClass(cls, ctx) {
+  return {
+    name: cls.name,
+    file: ctx.filesByPath.get(cls.file)?.displayPath ?? cls.file
+  };
 }
-function placeCallee(placements, callee, outcome, call, file) {
+function placeCallee(placements, callee, outcome, call, file, ctx) {
   if (outcome.kind === "followed") {
-    placements.place(callee, {
-      file: outcome.target.file.displayPath,
-      span: spanOf(outcome.target.node)
-    });
+    placements.place(callee, placeOf(outcome.target, ctx));
     return;
   }
   if (outcome.reason === "noDeclaration" && !isMethodCall(call)) {
@@ -9259,9 +9401,13 @@ function bodyOf(source) {
   }
   return {
     body,
-    written: callsWritten(file, body, scopeAt2(file, node), keyOf2(source), {
-      descendsInto: isModule(node) ? runsAtModuleLoad : outsideNestedDef
-    })
+    written: callsWritten(
+      file,
+      body,
+      scopeAt2(file, node),
+      { owner: nodeId(file.file, node), receiverClass: source.receiverClass },
+      { descendsInto: isModule(node) ? runsAtModuleLoad : outsideNestedDef }
+    )
   };
 }
 function outsideNestedDef(node) {
@@ -9331,16 +9477,20 @@ function scanBody(source, ctx, recognized, read, implied) {
       followed.push(target);
     }
   };
-  const recordPassedArgs = (call, callee, calleeKey2) => {
+  const recordPassedArgs = (call, callee, target) => {
     const args = field(call, "arguments");
     if (args === null) {
       return;
     }
+    const calleeKeys = target === null ? [] : [keyOf2(target), keyOf2(plainOf(target))];
+    const passes = (position) => {
+      for (const calleeKey2 of calleeKeys) {
+        passedPositions.add(`${calleeKey2}#${position}`);
+      }
+    };
     children(args).forEach((arg, position) => {
       if (arg.type === "lambda") {
-        if (calleeKey2 !== null) {
-          passedPositions.add(`${calleeKey2}#${position}`);
-        }
+        passes(position);
         return;
       }
       const nameKey2 = passedNameKeyOf(file, arg);
@@ -9352,23 +9502,15 @@ function scanBody(source, ctx, recognized, read, implied) {
         return;
       }
       follow(resolved);
-      placements.placeArg(callee, position, {
-        file: resolved.file.displayPath,
-        span: spanOf(resolved.node)
-      });
-      if (calleeKey2 !== null) {
-        passedPositions.add(`${calleeKey2}#${position}`);
-      }
+      placements.placeArg(callee, position, placeOf(resolved, ctx));
+      passes(position);
     });
   };
   const recordPossible = (call, callee, dispatched) => {
     dispatched.targets.forEach(follow);
     placements.placePossible(
       callee,
-      dispatched.targets.map((target) => ({
-        file: target.file.displayPath,
-        span: spanOf(target.node)
-      }))
+      dispatched.targets.map((target) => placeOf(target, ctx))
     );
     recordPassedArgs(call, callee, null);
     if (dispatched.unresolved > 0 && !recognized.has(call.id)) {
@@ -9385,11 +9527,11 @@ function scanBody(source, ctx, recognized, read, implied) {
       return;
     }
     const outcome = only === void 0 ? settled : { kind: "followed", target: only };
-    placeCallee(placements, callee, outcome, call, file);
+    placeCallee(placements, callee, outcome, call, file, ctx);
     recordPassedArgs(
       call,
       callee,
-      outcome.kind === "followed" ? keyOf2(outcome.target) : null
+      outcome.kind === "followed" ? outcome.target : null
     );
     if (outcome.kind === "stopped") {
       if (!recognized.has(call.id) && worthRecording(outcome.reason)) {
@@ -9430,12 +9572,12 @@ function scanBody(source, ctx, recognized, read, implied) {
     passedPositions
   };
 }
-function callsWritten(file, body, outer, owner, limit) {
+function callsWritten(file, body, outer, scanned, limit) {
   const found = [];
   walkDescendants6(body, outer, children, {
     at: (child, scope) => {
       if (child.type === "call") {
-        found.push({ call: child, site: { file, scope, owner } });
+        found.push({ call: child, site: { file, scope, ...scanned } });
       }
     },
     into: (child, scope) => limit.descendsInto(child) ? file.module.scopeFor.get(child.id) ?? scope : SKIP_CHILDREN5
@@ -9484,13 +9626,8 @@ function libraryUnit(target, options, binding = functionCallBinding({
     file.module,
     parameters.map((parameter) => parameter.name)
   );
-  const effects = invocationEffects(node, options.facts);
-  const branches = exitingBranches(
-    node,
-    file.module,
-    effects,
-    options.facts
-  ) ?? [
+  const calls = invocationSites(node, options.facts);
+  const branches = exitingBranches(node, file.module, calls, options.facts) ?? [
     {
       conditions: [],
       terminal: {
@@ -9505,7 +9642,7 @@ function libraryUnit(target, options, binding = functionCallBinding({
         emitEvent: null,
         location: range
       },
-      effects,
+      effects: calls.map((call) => call.effect),
       location: range,
       isDefault: true
     }
@@ -9602,7 +9739,131 @@ function parameterName2(param) {
   return identifiersUnder(param)[0] ?? null;
 }
 
+// src/entryPoints.ts
+function declaredEntryUnits(file, packs, options) {
+  const units = [];
+  for (const pack of packs) {
+    for (const entry of pack.entryPoints?.(file.file) ?? []) {
+      const binding = file.module.moduleScope.bindings.get(entry.name);
+      if (binding?.kind !== "functionDef") {
+        continue;
+      }
+      for (const declared of entry.units) {
+        const raw = libraryUnit(
+          {
+            file,
+            node: binding.node,
+            name: declared.name,
+            exportPath: [entry.name]
+          },
+          options,
+          declared.binding
+        );
+        units.push({
+          ...raw,
+          identity: { ...raw.identity, kind: declared.kind },
+          deployableUnit: declared.deployableUnit,
+          ...declared.metadata !== void 0 ? { packMetadata: declared.metadata } : {}
+        });
+      }
+    }
+  }
+  return units;
+}
+
+// src/importedDefinitions.ts
+import { isObserved, noteKeyRead as noteKeyRead3 } from "@suss/resolution";
+function importedDefinitionLookup(db, files) {
+  const fileOfModuleScope = /* @__PURE__ */ new Map();
+  const byFile = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    fileOfModuleScope.set(file.module.moduleScope.node.id, file.file);
+    byFile.set(file.file, file);
+  }
+  const found = /* @__PURE__ */ new Map();
+  return (scope, name) => {
+    const fromFile = fileOfModuleScope.get(moduleScopeOf(scope).node.id);
+    if (fromFile === void 0) {
+      return null;
+    }
+    const key = `${fromFile}#${name}`;
+    let definition = found.get(key);
+    if (definition === void 0) {
+      definition = definitionAmong(originsOf(db, key), byFile);
+      found.set(key, definition);
+    } else if (isObserved(db)) {
+      originsOf(db, key);
+    }
+    if (definition !== null) {
+      noteKeyRead3(db, definition.file);
+    }
+    return definition;
+  };
+}
+function definitionAmong(origins, byFile) {
+  for (const origin of origins) {
+    const file = byFile.get(origin.module);
+    const binding = file?.module.moduleScope.bindings.get(origin.name);
+    if (file === void 0 || binding === void 0) {
+      continue;
+    }
+    const node = definedNodeOf(binding);
+    if (node !== null) {
+      return {
+        node,
+        file: file.file,
+        moduleScope: file.module.moduleScope,
+        scopeFor: file.module.scopeFor
+      };
+    }
+  }
+  return null;
+}
+function definedNodeOf(binding) {
+  if (binding.kind === "classDef") {
+    return binding.node;
+  }
+  if (binding.kind === "assignment") {
+    return binding.value;
+  }
+  return null;
+}
+
+// src/libraryEnvReads.ts
+import { libraryEnvReadMarker } from "@suss/extractor";
+function libraryEnvReadMarkers(files, packs) {
+  const markers = [];
+  for (const pack of packs) {
+    for (const declared of pack.libraryEnvVars ?? []) {
+      const importer = files.find(
+        (file) => importsModule(file, declared.module)
+      );
+      if (importer !== void 0) {
+        markers.push(
+          libraryEnvReadMarker(pack.name, declared, importer.displayPath)
+        );
+      }
+    }
+  }
+  return markers;
+}
+function importsModule(file, prefix) {
+  for (const binding of file.module.moduleScope.bindings.values()) {
+    if ((binding.kind === "import" || binding.kind === "importFrom") && binding.relativeLevel === 0 && binding.module.startsWith(prefix)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 // src/moduleSurface.ts
+import { moduleExportBinding } from "@suss/behavioral-ir";
+import {
+  MODULE_SURFACE_RECOGNITION,
+  moduleOfFile,
+  settleModules
+} from "@suss/extractor";
+import { noteKeyRead as noteKeyRead4 } from "@suss/resolution";
 function settlePythonModules(modules) {
   return settleModules(modules, ["__init__.py"]);
 }
@@ -9690,7 +9951,13 @@ function exportsOf(file, node, exportName) {
 }
 
 // src/reuse.ts
-import { EntryReuse, fileOfKey, noteLookup as noteLookup2 } from "@suss/resolution";
+import {
+  EntryReuse,
+  fileOfKey as fileOfKey2,
+  noteLookup as noteLookup2,
+  plainKeyOf as plainKeyOf2,
+  variantKey as variantKey2
+} from "@suss/resolution";
 function seedsOfRecord(record) {
   return [
     ...record.module.seedKey === null ? [] : [record.module.seedKey],
@@ -9703,9 +9970,20 @@ function pythonEntryReuse(records, changedFiles, changes) {
   return new EntryReuse(records, changedFiles, changes, seedsOfRecord);
 }
 function storedFunction(target, definitions, filesByPath) {
-  const node = definitions.get(target.key);
-  const file = filesByPath.get(fileOfKey(target.key));
-  return node === void 0 || file === void 0 ? null : { file, node, name: target.name, exportPath: target.exportPath };
+  const plainKey = plainKeyOf2(target.key);
+  const node = definitions.get(plainKey);
+  const file = filesByPath.get(fileOfKey2(target.key));
+  const key = target.receiverClass === void 0 ? plainKey : variantKey2(plainKey, target.receiverClass);
+  if (node === void 0 || file === void 0 || key !== target.key) {
+    return null;
+  }
+  const found = {
+    file,
+    node,
+    name: target.name,
+    exportPath: target.exportPath
+  };
+  return target.receiverClass === void 0 ? found : { ...found, receiverClass: target.receiverClass };
 }
 var WalkReplay = class {
   constructor(reuse, definitions, filesByPath) {
@@ -12486,7 +12764,7 @@ function unitAround(target, pattern, reading, options) {
   });
   const continuations = reading.continuations;
   const terminals = bodyTerminals(body, raised, continuations);
-  const effects = invocationEffects(node, options.facts);
+  const effects = invocationSites(node, options.facts);
   const extra = recognizedBodyEffects(
     node,
     file.module,
@@ -12821,7 +13099,9 @@ async function runPython(options, roots, cache, previous) {
   const sqlClients = options.packs.flatMap((pack) => pack.sqlClients ?? []);
   const modelQueries = options.packs.flatMap((pack) => pack.models ?? []);
   const declaredModules = settlePythonModules(options.modules);
-  const discovers = declaredModules.length > 0 || options.packs.some((pack) => pack.discovery.length > 0);
+  const discovers = declaredModules.length > 0 || options.packs.some(
+    (pack) => pack.discovery.length > 0 || pack.entryPoints !== void 0
+  );
   const buildsReceivers = options.packs.some(
     (pack) => (pack.clients ?? []).some(
       (client) => (client.receiverConstructors ?? []).length > 0
@@ -12984,6 +13264,10 @@ async function runPython(options, roots, cache, previous) {
         facts: db,
         storageFor
       }),
+      ...declaredEntryUnits(boundFile, options.packs, {
+        facts: db,
+        storageFor
+      }),
       ...tests === null ? [] : tests.unitsIn(boundFile, { storageFor, facts: db })
     ];
     const charge = noDependencies2();
@@ -13093,7 +13377,10 @@ async function runPython(options, roots, cache, previous) {
     }
     const loadTimeReads = record !== void 0 && discoveries.get(file) === record ? null : timer.time(
       "discover",
-      () => charged(file, () => envReadEffects(root, moduleBinding, db))
+      () => charged(
+        file,
+        () => envReadEffects(root, moduleBinding, db).map((one) => one.effect)
+      )
     );
     const moduleKey = nodeId(file, root);
     if (!summariesBySeed.has(moduleKey)) {
@@ -13196,6 +13483,7 @@ async function runPython(options, roots, cache, previous) {
     });
   }
   summaries.push(...reached.summaries);
+  summaries.push(...libraryEnvReadMarkers(bound, options.packs));
   const spend = underQuestionSpend(db);
   const overBudget = spend.abandoned + spend.skipped > 0;
   if (overBudget && reuse !== null) {