@suss/adapter-python 0.31.1 → 0.32.0

package/README.md

@@ -26,6 +26,7 @@ npx suss check --dir summaries/
 - FastAPI and flask-restx routes, including a decorator a project re-exports through a wrapper module, with `response_model` and `status_code` taken as the declared contract.
 - The path a route is served under, composed through `include_router` prefixes, however many mounts deep, including a mount written inside a function or spread out of a dictionary.
 - SQLAlchemy calls, `requests` / `httpx` / `aiohttp` call sites, what a file reads from the environment, and what a handler calls out to, as facts the checker's rules run over.
+- Environment reads written through a project helper: with `def env(key): return os.environ[key]`, a call to `env("DATABASE_URL")` is a read of `DATABASE_URL`, however many helpers the name is handed through on the way. Not covered: a name built with an f-string (`env(f"{prefix}_URL")`), a name the helper takes off a dict, and a callee that is a value rather than a function the project declares (`env = make_reader()`).
 
 How each of those is decided, and where it stops: [how the Python adapter reads a project](./DESIGN.md).
 

package/dist/index.cjs

@@ -784,6 +784,9 @@ var import_resolution = require("@suss/resolution");
 function resolveCalls(db, callKeys) {
   (0, import_resolution.askResolution)(db, callKeys);
 }
+function resolveEnvSites(db, siteIds) {
+  (0, import_resolution.askResolution)(db, siteIds, "wantedEnvSite");
+}
 function writtenValueUnder(db, key, site) {
   if ((0, import_resolution.askResolutionUnder)(db, [[key, site]]) === "abandoned") {
     return null;
@@ -992,31 +995,46 @@ function emitCall(emitter, call) {
   if (!emitter.insideMethod) {
     add(emitter, "callOutsideMethod", callKey);
   }
+  for (const argument of callArguments(call)) {
+    if (argument.kind === "keyword") {
+      add(
+        emitter,
+        "callKeywordArg",
+        callKey,
+        argument.name,
+        valueKey(emitter, argument.node)
+      );
+      continue;
+    }
+    add(
+      emitter,
+      "callArg",
+      callKey,
+      String(argument.position),
+      valueKey(emitter, argument.node)
+    );
+  }
+}
+function callArguments(call) {
+  const args = field(call, "arguments");
+  if (args === null) {
+    return [];
+  }
+  const written = [];
   let position = 0;
   for (const argument of children(args)) {
     if (argument.type === "keyword_argument") {
       const name = field(argument, "name");
       const value = field(argument, "value");
       if (name !== null && value !== null) {
-        add(
-          emitter,
-          "callKeywordArg",
-          callKey,
-          name.text,
-          valueKey(emitter, value)
-        );
+        written.push({ kind: "keyword", name: name.text, node: value });
       }
       continue;
     }
-    add(
-      emitter,
-      "callArg",
-      callKey,
-      String(position),
-      valueKey(emitter, argument)
-    );
+    written.push({ kind: "positional", position, node: argument });
     position += 1;
   }
+  return written;
 }
 function valueKey(emitter, value) {
   if (value.type !== "identifier") {
@@ -2511,6 +2529,10 @@ function writtenNodeOf(node, db) {
   const bound = db === void 0 ? void 0 : projects.get(db);
   return bound?.context.writtenTo(node) ?? null;
 }
+function resolutionKeyOf(node, db) {
+  const bound = db === void 0 ? void 0 : projects.get(db);
+  return bound?.keyOf(node) ?? null;
+}
 var NOTHING_BUILT = { type: "noCall" };
 function constructionBehind(node, db) {
   if (db === void 0) {
@@ -2857,7 +2879,7 @@ function passesParametersThrough(def, inner) {
 // src/discovery.ts
 var import_behavioral_ir4 = require("@suss/behavioral-ir");
 var import_extractor5 = require("@suss/extractor");
-var import_values10 = require("@suss/values");
+var import_values11 = require("@suss/values");
 
 // src/clientCalls.ts
 var import_behavioral_ir2 = require("@suss/behavioral-ir");
@@ -3575,14 +3597,22 @@ var import_behavioral_ir3 = require("@suss/behavioral-ir");
 var import_extractor4 = require("@suss/extractor");
 var PYTHON_ENV_RECOGNITION = "python-env";
 var DEFERRED_BODY_TYPES = /* @__PURE__ */ new Set(["function_definition", "lambda"]);
-function envReadEffects(root, module2) {
-  const effects = [];
+function envReadEffects(root, module2, facts) {
+  const slots = [];
+  const readsHelpers = facts !== void 0 && sitesByDb.has(facts);
   const startScope = module2.scopeFor.get(root.id) ?? module2.moduleScope;
   (0, import_extractor4.walkDescendants)(root, startScope, {
     at: (node, scope) => {
-      const read = envReadAt(node, scope);
-      if (read !== null) {
-        effects.push(configReadEffect(read));
+      const syntax = envReadSyntaxAt(node, scope);
+      if (syntax !== null) {
+        const name = stringLiteralValue(syntax.name);
+        if (name !== null) {
+          slots.push({ read: { name, defaulted: syntax.defaulted } });
+        }
+        return;
+      }
+      if (readsHelpers && node.type === "call") {
+        slots.push({ call: node });
       }
     },
     into: (node, scope) => {
@@ -3592,7 +3622,16 @@ function envReadEffects(root, module2) {
       return module2.scopeFor.get(node.id) ?? scope;
     }
   });
-  return effects;
+  const throughHelpers = helperReadsByCall(
+    slots.flatMap((slot) => "call" in slot ? [slot.call] : []),
+    facts
+  );
+  return slots.flatMap((slot) => {
+    if ("read" in slot) {
+      return [configReadEffect(slot.read)];
+    }
+    return throughHelpers.get(slot.call.id) ?? [];
+  });
 }
 function configReadEffect(read) {
   return {
@@ -3610,7 +3649,7 @@ function configReadEffect(read) {
     }
   };
 }
-function envReadAt(node, scope) {
+function envReadSyntaxAt(node, scope) {
   if (node.type === "subscript") {
     return subscriptRead(node, scope);
   }
@@ -3625,11 +3664,10 @@ function subscriptRead(node, scope) {
   if (value === null || index === null || !isEnviron(value, scope)) {
     return null;
   }
-  const name = stringLiteralValue(index);
-  if (name === null || isAssignedTo(node)) {
+  if (isAssignedTo(node)) {
     return null;
   }
-  return { name, defaulted: isDefaultedAt(node) };
+  return { name: index, defaulted: isDefaultedAt(node) };
 }
 function isAssignedTo(node) {
   const parent = node.parent;
@@ -3643,22 +3681,20 @@ function isAssignedTo(node) {
 }
 function callRead(node, scope) {
   const callee = field(node, "function");
-  const args = field(node, "arguments");
-  if (callee === null || args === null || !isEnvGetter(callee, scope)) {
+  if (callee === null || !isEnvGetter(callee, scope)) {
     return null;
   }
-  const positional = args.namedChildren.filter(
-    (arg) => arg !== null && arg.type !== "keyword_argument"
+  const written = callArguments(node);
+  const name = written.find(
+    (argument) => argument.kind === "positional" && argument.position === 0
   );
-  const name = positional[0] === void 0 ? null : stringLiteralValue(positional[0]);
-  if (name === null) {
+  if (name === void 0) {
     return null;
   }
-  const keywords = args.namedChildren.filter(
-    (arg) => arg !== null && arg.type === "keyword_argument"
+  const hasDefault = written.some(
+    (argument) => argument.kind === "positional" && argument.position === 1 || argument.kind === "keyword" && argument.name === "default"
   );
-  const hasDefault = positional.length > 1 || keywords.some((arg) => field(arg, "name")?.text === "default");
-  return { name, defaulted: hasDefault || isDefaultedAt(node) };
+  return { name: name.node, defaulted: hasDefault || isDefaultedAt(node) };
 }
 function isEnvGetter(callee, scope) {
   if (callee.type === "attribute") {
@@ -3715,9 +3751,153 @@ function isDefaultedAt(node) {
   }
   return false;
 }
+function envNameSites(filePath, root, module2) {
+  const sites = [];
+  (0, import_extractor4.walkDescendants)(root, module2.moduleScope, {
+    at: (node, scope) => {
+      const syntax = envReadSyntaxAt(node, scope);
+      if (syntax === null || stringLiteralValue(syntax.name) !== null) {
+        return;
+      }
+      sites.push({
+        site: nodeId(filePath, node),
+        nameKey: readKey(filePath, syntax.name, enclosingFunction(syntax.name)),
+        defaulted: syntax.defaulted
+      });
+    },
+    into: (node, scope) => module2.scopeFor.get(node.id) ?? scope
+  });
+  return sites;
+}
+var sitesByDb = /* @__PURE__ */ new WeakMap();
+function bindEnvNameSites(db, sites) {
+  if (sites.length === 0) {
+    return;
+  }
+  let index = sitesByDb.get(db);
+  if (index === void 0) {
+    index = { byId: /* @__PURE__ */ new Map(), sitesByParameter: null };
+    sitesByDb.set(db, index);
+  }
+  for (const site of sites) {
+    db.add("readsEnvNamed", [site.site, site.nameKey]);
+    index.byId.set(site.site, site);
+  }
+}
+function sitesEachParameterNames(db, index) {
+  if (index.sitesByParameter !== null) {
+    return index.sitesByParameter;
+  }
+  resolveEnvSites(db, [...index.byId.keys()]);
+  const found = /* @__PURE__ */ new Map();
+  for (const row of db.facts("wantedParamNamesEnv")) {
+    const parameter = String(row[0]);
+    const named = found.get(parameter) ?? [];
+    named.push(String(row[1]));
+    found.set(parameter, named);
+  }
+  index.sitesByParameter = found;
+  return found;
+}
+function helperReadsByCall(calls, db) {
+  const found = /* @__PURE__ */ new Map();
+  const index = db === void 0 ? void 0 : sitesByDb.get(db);
+  if (db === void 0 || index === void 0 || calls.length === 0) {
+    return found;
+  }
+  const named = sitesEachParameterNames(db, index);
+  if (named.size === 0) {
+    return found;
+  }
+  const calleeKeys = /* @__PURE__ */ new Map();
+  for (const call of calls) {
+    const callee = field(call, "function");
+    const key = callee === null ? null : resolutionKeyOf(callee, db);
+    if (key !== null) {
+      calleeKeys.set(call.id, key);
+    }
+  }
+  if (calleeKeys.size === 0) {
+    return found;
+  }
+  resolveCalls(db, [...new Set(calleeKeys.values())]);
+  for (const call of calls) {
+    const key = calleeKeys.get(call.id);
+    if (key === void 0) {
+      continue;
+    }
+    const argumentAt2 = argumentsByParameter(db, call, key);
+    if (argumentAt2.size === 0) {
+      continue;
+    }
+    const reads = readsThroughHelper(db, call, argumentAt2, index.byId, named);
+    if (reads.length > 0) {
+      found.set(call.id, reads);
+    }
+  }
+  return found;
+}
+function argumentsByParameter(db, call, calleeKey) {
+  const written = callArguments(call);
+  if (written.length === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const positional = /* @__PURE__ */ new Map();
+  const byName = /* @__PURE__ */ new Map();
+  for (const argument of written) {
+    if (argument.kind === "keyword") {
+      byName.set(argument.name, argument.node);
+      continue;
+    }
+    positional.set(String(argument.position), argument.node);
+  }
+  const argumentAt2 = /* @__PURE__ */ new Map();
+  for (const resolved of db.lookup("wantedResolves", 0, calleeKey)) {
+    const callee = String(resolved[1]);
+    for (const row of db.lookup("paramOf", 0, callee)) {
+      const at = positional.get(String(row[1]));
+      if (at !== void 0) {
+        argumentAt2.set(String(row[2]), at);
+      }
+    }
+    for (const row of db.lookup("paramNamed", 0, callee)) {
+      const at = byName.get(String(row[1]));
+      if (at !== void 0) {
+        argumentAt2.set(String(row[2]), at);
+      }
+    }
+  }
+  return argumentAt2;
+}
+function readsThroughHelper(db, call, argumentAt2, siteById, named) {
+  const reads = /* @__PURE__ */ new Map();
+  for (const [parameter, argument] of argumentAt2) {
+    const sites = named.get(parameter);
+    if (sites === void 0) {
+      continue;
+    }
+    const name = stringLiteralValue(argument) ?? stringValueOf(argument, db);
+    if (name === null) {
+      continue;
+    }
+    for (const id of sites) {
+      const site = siteById.get(id);
+      if (site !== void 0) {
+        reads.set(name, (reads.get(name) ?? true) && site.defaulted);
+      }
+    }
+  }
+  if (reads.size === 0) {
+    return [];
+  }
+  const defaultedAtCall = isDefaultedAt(call);
+  return [...reads].map(
+    ([name, defaulted]) => configReadEffect({ name, defaulted: defaulted || defaultedAtCall })
+  );
+}
 
 // src/paths/raisedResponses.ts
-var import_values8 = require("@suss/values");
+var import_values9 = require("@suss/values");
 var NESTED_DEFINITION_TYPES2 = /* @__PURE__ */ new Set(["function_definition", "lambda"]);
 function raisedResponses(body, options) {
   if (body === null || options.calls.length === 0) {
@@ -3811,7 +3991,7 @@ function statusOf(declared, call, facts) {
   if (written === null) {
     return declared.defaultStatusCode === void 0 ? null : { type: "literal", value: declared.defaultStatusCode };
   }
-  const value = (0, import_values8.constantOf)(evaluatedValue(written, facts));
+  const value = (0, import_values9.constantOf)(evaluatedValue(written, facts));
   if (typeof value === "number") {
     return { type: "literal", value };
   }
@@ -4584,7 +4764,7 @@ function readPathArgument(classification, options) {
   const first = classification.args[0];
   if (first !== void 0) {
     const value = evaluatedValue(first.node, options.facts);
-    const path6 = (0, import_values10.literalOf)(value) ?? (0, import_values10.pathOf)(value);
+    const path6 = (0, import_values11.literalOf)(value) ?? (0, import_values11.pathOf)(value);
     if (path6 !== void 0) {
       return (0, import_extractor5.writtenReading)(path6, classification.range);
     }
@@ -4831,11 +5011,11 @@ function statusFromReturnedValue(node, facts) {
     return null;
   }
   const value = evaluatedValue(node, facts);
-  const number = (0, import_values10.constantOf)(value);
+  const number = (0, import_values11.constantOf)(value);
   if (typeof number === "number") {
     return Number.isInteger(number) ? number : null;
   }
-  const text2 = (0, import_values10.literalOf)(value);
+  const text2 = (0, import_values11.literalOf)(value);
   if (text2 === null) {
     return null;
   }
@@ -5178,7 +5358,12 @@ function buildRouteUnit(options) {
     () => readReturnAnnotation(definitionNode, enclosingScope, ctx)
   );
   const effects = invocationEffects(definitionNode, options.facts);
-  const extra = recognizedBodyEffects(definitionNode, module2, storageLookup);
+  const extra = recognizedBodyEffects(
+    definitionNode,
+    module2,
+    storageLookup,
+    options.facts
+  );
   const perTerminal = branchesPerTerminal({
     definitionNode,
     effects,
@@ -5263,7 +5448,7 @@ function unreadRoleReadings(parameters, range) {
     )
   ];
 }
-function recognizedBodyEffects(definitionNode, module2, storageLookup) {
+function recognizedBodyEffects(definitionNode, module2, storageLookup, facts) {
   const storage = storageLookup === void 0 ? [] : [
     ...storageEffects(bodyCalls(definitionNode), {
       ...storageLookup,
@@ -5275,7 +5460,7 @@ function recognizedBodyEffects(definitionNode, module2, storageLookup) {
       patterns: storageLookup.rawSql ?? []
     })
   ];
-  return [...envReadEffects(definitionNode, module2), ...storage];
+  return [...envReadEffects(definitionNode, module2, facts), ...storage];
 }
 function recognizedCallIds(definitionNode, storageLookup) {
   if (storageLookup === void 0) {
@@ -6168,7 +6353,8 @@ function libraryUnit(target, options) {
   const extra = recognizedBodyEffects(
     node,
     file.module,
-    options.storageFor(file)
+    options.storageFor(file),
+    options.facts
   );
   const range = rangeOf(node);
   return {
@@ -7749,7 +7935,8 @@ function wrapperUnit(target, declared, options) {
   const extra = recognizedBodyEffects(
     node,
     file.module,
-    options.storageFor(file)
+    options.storageFor(file),
+    options.facts
   );
   const delegate = (at) => ({
     terminal: {
@@ -7907,6 +8094,10 @@ function factsForFile(options) {
     files: [{ file: options.file, root: options.root, module: options.module }],
     definitions
   });
+  bindEnvNameSites(
+    db,
+    envNameSites(options.file, options.root, options.module)
+  );
   (0, import_resolution7.addPackWords)(db, packWordsOf(options.packs));
   return db;
 }
@@ -7964,7 +8155,10 @@ async function extractPythonProject(options) {
       (client) => (client.receiverConstructors ?? []).length > 0
     )
   );
-  const needsValues = discovers || mountsRouters || buildsReceivers || storagePatterns.length > 0 || modelQueries.length > 0;
+  const envSites = bound.flatMap(
+    (boundFile) => envNameSites(boundFile.file, boundFile.root, boundFile.module)
+  );
+  const needsValues = discovers || mountsRouters || buildsReceivers || envSites.length > 0 || storagePatterns.length > 0 || modelQueries.length > 0;
   const definitions = /* @__PURE__ */ new Map();
   timer.time("discover", () => {
     for (const { file, root, module: moduleBinding } of bound) {
@@ -7976,6 +8170,7 @@ async function extractPythonProject(options) {
     }
     if (needsValues) {
       bindEvaluator(db, { files: bound, definitions });
+      bindEnvNameSites(db, envSites);
     }
     (0, import_resolution7.addPackWords)(db, packWordsOf(options.packs));
   });
@@ -8064,7 +8259,7 @@ async function extractPythonProject(options) {
     }
     const loadTimeReads = timer.time(
       "discover",
-      () => envReadEffects(root, moduleBinding)
+      () => envReadEffects(root, moduleBinding, db)
     );
     if (loadTimeReads.length > 0) {
       const summary = timer.time(

package/dist/index.js

@@ -724,6 +724,9 @@ import {
 function resolveCalls(db, callKeys) {
   askResolution(db, callKeys);
 }
+function resolveEnvSites(db, siteIds) {
+  askResolution(db, siteIds, "wantedEnvSite");
+}
 function writtenValueUnder(db, key, site) {
   if (askResolutionUnder(db, [[key, site]]) === "abandoned") {
     return null;
@@ -936,31 +939,46 @@ function emitCall(emitter, call) {
   if (!emitter.insideMethod) {
     add(emitter, "callOutsideMethod", callKey);
   }
+  for (const argument of callArguments(call)) {
+    if (argument.kind === "keyword") {
+      add(
+        emitter,
+        "callKeywordArg",
+        callKey,
+        argument.name,
+        valueKey(emitter, argument.node)
+      );
+      continue;
+    }
+    add(
+      emitter,
+      "callArg",
+      callKey,
+      String(argument.position),
+      valueKey(emitter, argument.node)
+    );
+  }
+}
+function callArguments(call) {
+  const args = field(call, "arguments");
+  if (args === null) {
+    return [];
+  }
+  const written = [];
   let position = 0;
   for (const argument of children(args)) {
     if (argument.type === "keyword_argument") {
       const name = field(argument, "name");
       const value = field(argument, "value");
       if (name !== null && value !== null) {
-        add(
-          emitter,
-          "callKeywordArg",
-          callKey,
-          name.text,
-          valueKey(emitter, value)
-        );
+        written.push({ kind: "keyword", name: name.text, node: value });
       }
       continue;
     }
-    add(
-      emitter,
-      "callArg",
-      callKey,
-      String(position),
-      valueKey(emitter, argument)
-    );
+    written.push({ kind: "positional", position, node: argument });
     position += 1;
   }
+  return written;
 }
 function valueKey(emitter, value) {
   if (value.type !== "identifier") {
@@ -2476,6 +2494,10 @@ function writtenNodeOf(node, db) {
   const bound = db === void 0 ? void 0 : projects.get(db);
   return bound?.context.writtenTo(node) ?? null;
 }
+function resolutionKeyOf(node, db) {
+  const bound = db === void 0 ? void 0 : projects.get(db);
+  return bound?.keyOf(node) ?? null;
+}
 var NOTHING_BUILT = { type: "noCall" };
 function constructionBehind(node, db) {
   if (db === void 0) {
@@ -3550,14 +3572,22 @@ import { runtimeConfigBinding } from "@suss/behavioral-ir";
 import { SKIP_CHILDREN, walkDescendants } from "@suss/extractor";
 var PYTHON_ENV_RECOGNITION = "python-env";
 var DEFERRED_BODY_TYPES = /* @__PURE__ */ new Set(["function_definition", "lambda"]);
-function envReadEffects(root, module) {
-  const effects = [];
+function envReadEffects(root, module, facts) {
+  const slots = [];
+  const readsHelpers = facts !== void 0 && sitesByDb.has(facts);
   const startScope = module.scopeFor.get(root.id) ?? module.moduleScope;
   walkDescendants(root, startScope, {
     at: (node, scope) => {
-      const read = envReadAt(node, scope);
-      if (read !== null) {
-        effects.push(configReadEffect(read));
+      const syntax = envReadSyntaxAt(node, scope);
+      if (syntax !== null) {
+        const name = stringLiteralValue(syntax.name);
+        if (name !== null) {
+          slots.push({ read: { name, defaulted: syntax.defaulted } });
+        }
+        return;
+      }
+      if (readsHelpers && node.type === "call") {
+        slots.push({ call: node });
       }
     },
     into: (node, scope) => {
@@ -3567,7 +3597,16 @@ function envReadEffects(root, module) {
       return module.scopeFor.get(node.id) ?? scope;
     }
   });
-  return effects;
+  const throughHelpers = helperReadsByCall(
+    slots.flatMap((slot) => "call" in slot ? [slot.call] : []),
+    facts
+  );
+  return slots.flatMap((slot) => {
+    if ("read" in slot) {
+      return [configReadEffect(slot.read)];
+    }
+    return throughHelpers.get(slot.call.id) ?? [];
+  });
 }
 function configReadEffect(read) {
   return {
@@ -3585,7 +3624,7 @@ function configReadEffect(read) {
     }
   };
 }
-function envReadAt(node, scope) {
+function envReadSyntaxAt(node, scope) {
   if (node.type === "subscript") {
     return subscriptRead(node, scope);
   }
@@ -3600,11 +3639,10 @@ function subscriptRead(node, scope) {
   if (value === null || index === null || !isEnviron(value, scope)) {
     return null;
   }
-  const name = stringLiteralValue(index);
-  if (name === null || isAssignedTo(node)) {
+  if (isAssignedTo(node)) {
     return null;
   }
-  return { name, defaulted: isDefaultedAt(node) };
+  return { name: index, defaulted: isDefaultedAt(node) };
 }
 function isAssignedTo(node) {
   const parent = node.parent;
@@ -3618,22 +3656,20 @@ function isAssignedTo(node) {
 }
 function callRead(node, scope) {
   const callee = field(node, "function");
-  const args = field(node, "arguments");
-  if (callee === null || args === null || !isEnvGetter(callee, scope)) {
+  if (callee === null || !isEnvGetter(callee, scope)) {
     return null;
   }
-  const positional = args.namedChildren.filter(
-    (arg) => arg !== null && arg.type !== "keyword_argument"
+  const written = callArguments(node);
+  const name = written.find(
+    (argument) => argument.kind === "positional" && argument.position === 0
   );
-  const name = positional[0] === void 0 ? null : stringLiteralValue(positional[0]);
-  if (name === null) {
+  if (name === void 0) {
     return null;
   }
-  const keywords = args.namedChildren.filter(
-    (arg) => arg !== null && arg.type === "keyword_argument"
+  const hasDefault = written.some(
+    (argument) => argument.kind === "positional" && argument.position === 1 || argument.kind === "keyword" && argument.name === "default"
   );
-  const hasDefault = positional.length > 1 || keywords.some((arg) => field(arg, "name")?.text === "default");
-  return { name, defaulted: hasDefault || isDefaultedAt(node) };
+  return { name: name.node, defaulted: hasDefault || isDefaultedAt(node) };
 }
 function isEnvGetter(callee, scope) {
   if (callee.type === "attribute") {
@@ -3690,6 +3726,150 @@ function isDefaultedAt(node) {
   }
   return false;
 }
+function envNameSites(filePath, root, module) {
+  const sites = [];
+  walkDescendants(root, module.moduleScope, {
+    at: (node, scope) => {
+      const syntax = envReadSyntaxAt(node, scope);
+      if (syntax === null || stringLiteralValue(syntax.name) !== null) {
+        return;
+      }
+      sites.push({
+        site: nodeId(filePath, node),
+        nameKey: readKey(filePath, syntax.name, enclosingFunction(syntax.name)),
+        defaulted: syntax.defaulted
+      });
+    },
+    into: (node, scope) => module.scopeFor.get(node.id) ?? scope
+  });
+  return sites;
+}
+var sitesByDb = /* @__PURE__ */ new WeakMap();
+function bindEnvNameSites(db, sites) {
+  if (sites.length === 0) {
+    return;
+  }
+  let index = sitesByDb.get(db);
+  if (index === void 0) {
+    index = { byId: /* @__PURE__ */ new Map(), sitesByParameter: null };
+    sitesByDb.set(db, index);
+  }
+  for (const site of sites) {
+    db.add("readsEnvNamed", [site.site, site.nameKey]);
+    index.byId.set(site.site, site);
+  }
+}
+function sitesEachParameterNames(db, index) {
+  if (index.sitesByParameter !== null) {
+    return index.sitesByParameter;
+  }
+  resolveEnvSites(db, [...index.byId.keys()]);
+  const found = /* @__PURE__ */ new Map();
+  for (const row of db.facts("wantedParamNamesEnv")) {
+    const parameter = String(row[0]);
+    const named = found.get(parameter) ?? [];
+    named.push(String(row[1]));
+    found.set(parameter, named);
+  }
+  index.sitesByParameter = found;
+  return found;
+}
+function helperReadsByCall(calls, db) {
+  const found = /* @__PURE__ */ new Map();
+  const index = db === void 0 ? void 0 : sitesByDb.get(db);
+  if (db === void 0 || index === void 0 || calls.length === 0) {
+    return found;
+  }
+  const named = sitesEachParameterNames(db, index);
+  if (named.size === 0) {
+    return found;
+  }
+  const calleeKeys = /* @__PURE__ */ new Map();
+  for (const call of calls) {
+    const callee = field(call, "function");
+    const key = callee === null ? null : resolutionKeyOf(callee, db);
+    if (key !== null) {
+      calleeKeys.set(call.id, key);
+    }
+  }
+  if (calleeKeys.size === 0) {
+    return found;
+  }
+  resolveCalls(db, [...new Set(calleeKeys.values())]);
+  for (const call of calls) {
+    const key = calleeKeys.get(call.id);
+    if (key === void 0) {
+      continue;
+    }
+    const argumentAt2 = argumentsByParameter(db, call, key);
+    if (argumentAt2.size === 0) {
+      continue;
+    }
+    const reads = readsThroughHelper(db, call, argumentAt2, index.byId, named);
+    if (reads.length > 0) {
+      found.set(call.id, reads);
+    }
+  }
+  return found;
+}
+function argumentsByParameter(db, call, calleeKey) {
+  const written = callArguments(call);
+  if (written.length === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const positional = /* @__PURE__ */ new Map();
+  const byName = /* @__PURE__ */ new Map();
+  for (const argument of written) {
+    if (argument.kind === "keyword") {
+      byName.set(argument.name, argument.node);
+      continue;
+    }
+    positional.set(String(argument.position), argument.node);
+  }
+  const argumentAt2 = /* @__PURE__ */ new Map();
+  for (const resolved of db.lookup("wantedResolves", 0, calleeKey)) {
+    const callee = String(resolved[1]);
+    for (const row of db.lookup("paramOf", 0, callee)) {
+      const at = positional.get(String(row[1]));
+      if (at !== void 0) {
+        argumentAt2.set(String(row[2]), at);
+      }
+    }
+    for (const row of db.lookup("paramNamed", 0, callee)) {
+      const at = byName.get(String(row[1]));
+      if (at !== void 0) {
+        argumentAt2.set(String(row[2]), at);
+      }
+    }
+  }
+  return argumentAt2;
+}
+function readsThroughHelper(db, call, argumentAt2, siteById, named) {
+  const reads = /* @__PURE__ */ new Map();
+  for (const [parameter, argument] of argumentAt2) {
+    const sites = named.get(parameter);
+    if (sites === void 0) {
+      continue;
+    }
+    const name = stringLiteralValue(argument) ?? stringValueOf(argument, db);
+    if (name === null) {
+      continue;
+    }
+    for (const id of sites) {
+      const site = siteById.get(id);
+      if (site !== void 0) {
+        reads.set(name, (reads.get(name) ?? true) && site.defaulted);
+      }
+    }
+  }
+  if (reads.size === 0) {
+    return [];
+  }
+  const defaultedAtCall = isDefaultedAt(call);
+  return [...reads].map(
+    ([name, defaulted]) => configReadEffect({ name, defaulted: defaulted || defaultedAtCall })
+  );
+}
 
 // src/paths/raisedResponses.ts
 import { constantOf as constantOf3 } from "@suss/values";
@@ -5153,7 +5333,12 @@ function buildRouteUnit(options) {
     () => readReturnAnnotation(definitionNode, enclosingScope, ctx)
   );
   const effects = invocationEffects(definitionNode, options.facts);
-  const extra = recognizedBodyEffects(definitionNode, module, storageLookup);
+  const extra = recognizedBodyEffects(
+    definitionNode,
+    module,
+    storageLookup,
+    options.facts
+  );
   const perTerminal = branchesPerTerminal({
     definitionNode,
     effects,
@@ -5238,7 +5423,7 @@ function unreadRoleReadings(parameters, range) {
     )
   ];
 }
-function recognizedBodyEffects(definitionNode, module, storageLookup) {
+function recognizedBodyEffects(definitionNode, module, storageLookup, facts) {
   const storage = storageLookup === void 0 ? [] : [
     ...storageEffects(bodyCalls(definitionNode), {
       ...storageLookup,
@@ -5250,7 +5435,7 @@ function recognizedBodyEffects(definitionNode, module, storageLookup) {
       patterns: storageLookup.rawSql ?? []
     })
   ];
-  return [...envReadEffects(definitionNode, module), ...storage];
+  return [...envReadEffects(definitionNode, module, facts), ...storage];
 }
 function recognizedCallIds(definitionNode, storageLookup) {
   if (storageLookup === void 0) {
@@ -6182,7 +6367,8 @@ function libraryUnit(target, options) {
   const extra = recognizedBodyEffects(
     node,
     file.module,
-    options.storageFor(file)
+    options.storageFor(file),
+    options.facts
   );
   const range = rangeOf(node);
   return {
@@ -7763,7 +7949,8 @@ function wrapperUnit(target, declared, options) {
   const extra = recognizedBodyEffects(
     node,
     file.module,
-    options.storageFor(file)
+    options.storageFor(file),
+    options.facts
   );
   const delegate = (at) => ({
     terminal: {
@@ -7921,6 +8108,10 @@ function factsForFile(options) {
     files: [{ file: options.file, root: options.root, module: options.module }],
     definitions
   });
+  bindEnvNameSites(
+    db,
+    envNameSites(options.file, options.root, options.module)
+  );
   addPackWords(db, packWordsOf(options.packs));
   return db;
 }
@@ -7978,7 +8169,10 @@ async function extractPythonProject(options) {
       (client) => (client.receiverConstructors ?? []).length > 0
     )
   );
-  const needsValues = discovers || mountsRouters || buildsReceivers || storagePatterns.length > 0 || modelQueries.length > 0;
+  const envSites = bound.flatMap(
+    (boundFile) => envNameSites(boundFile.file, boundFile.root, boundFile.module)
+  );
+  const needsValues = discovers || mountsRouters || buildsReceivers || envSites.length > 0 || storagePatterns.length > 0 || modelQueries.length > 0;
   const definitions = /* @__PURE__ */ new Map();
   timer.time("discover", () => {
     for (const { file, root, module: moduleBinding } of bound) {
@@ -7990,6 +8184,7 @@ async function extractPythonProject(options) {
     }
     if (needsValues) {
       bindEvaluator(db, { files: bound, definitions });
+      bindEnvNameSites(db, envSites);
     }
     addPackWords(db, packWordsOf(options.packs));
   });
@@ -8078,7 +8273,7 @@ async function extractPythonProject(options) {
     }
     const loadTimeReads = timer.time(
       "discover",
-      () => envReadEffects(root, moduleBinding)
+      () => envReadEffects(root, moduleBinding, db)
     );
     if (loadTimeReads.length > 0) {
       const summary = timer.time(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/adapter-python",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "type": "module",
   "description": "Read a Python codebase with suss and check what each FastAPI or Flask route returns against the clients, specs and infrastructure that depend on it.",
   "keywords": [
@@ -49,13 +49,13 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.31.1",
-    "@suss/datalog": "0.31.1",
-    "@suss/extractor": "0.31.1",
-    "@suss/ir-core": "0.31.1",
-    "@suss/resolution": "0.31.1",
-    "@suss/sql": "0.31.1",
-    "@suss/values": "0.31.1",
+    "@suss/behavioral-ir": "0.32.0",
+    "@suss/datalog": "0.32.0",
+    "@suss/extractor": "0.32.0",
+    "@suss/ir-core": "0.32.0",
+    "@suss/resolution": "0.32.0",
+    "@suss/sql": "0.32.0",
+    "@suss/values": "0.32.0",
     "web-tree-sitter": "^0.26.11"
   },
   "devDependencies": {