@suss/adapter-python 0.4.0 → 0.5.0

package/README.md

@@ -186,8 +186,18 @@ call that starts the chain is the one resolved, and the method the chain ends
 with tells a read from a write. A method a base and a subclass both declare
 gives two, and nothing is claimed.
 
-`fields` and `selector` come back empty, so an effect says which model and
-which operation and not which columns. Raw SQL handed to `execute` is not read
+A query built from a function the library exports has no project method in
+between for its return to be read off, so a pack lists those by name and a call
+site importing one matches on that:
+
+```ts
+queryFunctions: ["select", "insert", "update", "delete"]
+```
+
+`fields` comes from the columns a query names, `User.id` in
+`select(User.id, User.email)`. `selector` comes from the keywords the chain
+picks rows by, `id` in `filter_by(id=user_id)`, gathered from every call in
+the chain rather than only the last. Raw SQL handed to `execute` is not read
 at all.
 
 ## Where a mount is written

package/dist/index.cjs

@@ -16233,21 +16233,22 @@ var RESOLUTION_RULES = [
     ]
   ),
   // Which calls a function, found by the name the call is written as
-  // rather than by resolving every callee in the project. Asking what
-  // reaches a parameter means looking for call sites, and looking for
-  // them the other way round costs a whole-project resolution.
+  // rather than by resolving every callee in the project. A caller knows
+  // the function and wants its call sites, so both of these start from
+  // the function. Starting from `call` instead asks what every call in
+  // the project imports, which was 72% of everything derived.
   (0, import_datalog.rule)(
     "callsFunction",
     [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")],
-    [(0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")), (0, import_datalog.lit)("binds", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f"))]
+    [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f")), (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c"))]
   ),
   (0, import_datalog.rule)(
     "callsFunction",
     [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")],
     [
-      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
+      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("f")),
       (0, import_datalog.lit)("imports", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")),
-      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("f"))
+      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c"))
     ]
   ),
   // A function whose return is itself a call arrives at the same object
@@ -16941,11 +16942,85 @@ function chainsIn(calls) {
       root: call,
       last,
       subject: subjectOf(call),
-      operation: methodName(last)
+      operation: methodName(last),
+      between: calls.filter(
+        (other) => other !== call && other !== last && other.startIndex >= call.startIndex && other.endIndex <= last.endIndex
+      )
     });
   }
   return chains;
 }
+function importedQueryFunction(options, chain) {
+  const callee = field(chain.root, "function");
+  if (callee === null || callee.type !== "identifier") {
+    return void 0;
+  }
+  const from = options.facts.facts("pyImportedName").find((row) => String(row[0]) === `${options.filePath}#${callee.text}`);
+  if (from === void 0) {
+    return void 0;
+  }
+  return options.patterns.find(
+    (pattern) => String(from[1]) === pattern.module && (pattern.queryFunctions ?? []).includes(String(from[2]))
+  );
+}
+function fieldsOf(chain) {
+  const args = field(chain.root, "arguments");
+  const named = [];
+  for (const argument of args === null ? [] : children3(args)) {
+    if (argument.type === "keyword_argument") {
+      const name = field(argument, "name");
+      if (name !== null) {
+        named.push(name.text);
+      }
+      continue;
+    }
+    if (argument.type === "attribute") {
+      const property = field(argument, "attribute");
+      if (property !== null) {
+        named.push(property.text);
+      }
+    }
+  }
+  return named;
+}
+function selectorOf(call) {
+  const args = field(call, "arguments");
+  const picked = [];
+  for (const argument of args === null ? [] : children3(args)) {
+    if (argument.type === "keyword_argument") {
+      const name = field(argument, "name");
+      if (name !== null) {
+        picked.push(name.text);
+      }
+    }
+  }
+  return picked;
+}
+function effectFor(pattern, chain, options) {
+  const picked = [
+    ...new Set([chain.last, ...chain.between].flatMap(selectorOf))
+  ];
+  return {
+    type: "interaction",
+    binding: storageRelationalBinding({
+      recognition: "python-storage",
+      storageSystem: pattern.storageSystem,
+      scope: pattern.module,
+      table: chain.subject
+    }),
+    callee: chain.last.text,
+    interaction: {
+      class: "storage-access",
+      kind: pattern.writes.includes(chain.operation) ? "write" : "read",
+      fields: fieldsOf(chain),
+      operation: chain.operation,
+      ...picked.length > 0 ? { selector: picked } : {}
+    }
+  };
+}
+function children3(node) {
+  return node.namedChildren.filter((child) => child !== null);
+}
 function fileOf(key) {
   const at = key.lastIndexOf(":");
   return at === -1 ? key : key.slice(0, at);
@@ -16960,26 +17035,90 @@ function returnTypeName(node) {
   }
   return annotation.type === "subscript" ? field(annotation, "value")?.text ?? null : annotation.text;
 }
+function callsIn(node, found = []) {
+  for (const child of node.namedChildren) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "call") {
+      found.push(child);
+    }
+    callsIn(child, found);
+  }
+  return found;
+}
+function storageEffects(calls, options) {
+  const seen = /* @__PURE__ */ new Set();
+  const asked = new Set(
+    options.facts.facts("wanted").map((row) => String(row[0]))
+  );
+  const gather = (inCalls, filePath) => {
+    const found = [...directStorageEffects(inCalls, { ...options, filePath })];
+    resolveCalls(
+      options.facts,
+      inCalls.filter((call) => options.leadsToStorage.has(methodName(call))).map((call) => field(call, "function")).filter((callee) => callee !== null).map((callee) => calleeKeyOf(filePath, callee)).filter((key) => {
+        const fresh = !asked.has(key);
+        asked.add(key);
+        return fresh;
+      })
+    );
+    for (const call of inCalls) {
+      const callee = field(call, "function");
+      if (callee === null || !options.leadsToStorage.has(methodName(call))) {
+        continue;
+      }
+      const key = resolvedOnce(options, calleeKeyOf(filePath, callee));
+      const body = key === void 0 ? void 0 : options.definitionAt(key);
+      if (key === void 0 || body === void 0 || seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      const name = field(body, "name")?.text;
+      const origin = {
+        file: fileOf(key),
+        line: body.startPosition.row + 1,
+        ...name === void 0 ? {} : { function: name }
+      };
+      found.push(
+        ...gather(callsIn(body), fileOf(key)).map(
+          (effect) => effect.type === "interaction" && effect.origin === void 0 ? { ...effect, origin } : effect
+        )
+      );
+    }
+    return found;
+  };
+  return gather(calls, options.filePath);
+}
+function calleeKeyOf(filePath, callee) {
+  return callee.type === "identifier" ? `${filePath}#${callee.text}` : nodeId(filePath, callee);
+}
+function resolvedOnce(options, calleeKey) {
+  const resolved = options.facts.facts("wantedResolves").filter((row) => String(row[0]) === calleeKey).map((row) => String(row[1]));
+  return resolved.length === 1 ? resolved[0] : void 0;
+}
 function storageCallees(calls, filePath, couldMatch) {
   return chainsIn(calls).filter((chain) => couldMatch.has(methodName(chain.root))).map((chain) => field(chain.root, "function")).filter((callee) => callee !== null).map((callee) => nodeId(filePath, callee));
 }
-function storageEffects(calls, options) {
+function directStorageEffects(calls, options) {
   if (options.patterns.length === 0) {
     return [];
   }
+  const named = new Set(
+    options.patterns.flatMap((pattern) => pattern.queryFunctions ?? [])
+  );
   const chains = chainsIn(calls).filter(
-    (chain) => options.couldMatch.has(methodName(chain.root))
+    (chain) => options.couldMatch.has(methodName(chain.root)) || named.has(methodName(chain.root))
   );
   if (chains.length === 0) {
     return [];
   }
-  const asked = new Set(
+  const alreadyAsked = new Set(
     options.facts.facts("wanted").map((row) => String(row[0]))
   );
   resolveCalls(
     options.facts,
     storageCallees(calls, options.filePath, options.couldMatch).filter(
-      (key) => !asked.has(key)
+      (key) => !alreadyAsked.has(key)
     )
   );
   const effects = [];
@@ -16988,6 +17127,11 @@ function storageEffects(calls, options) {
     if (callee === null) {
       continue;
     }
+    const imported = importedQueryFunction(options, chain);
+    if (imported !== void 0) {
+      effects.push(effectFor(imported, chain, options));
+      continue;
+    }
     const resolved = options.facts.facts("wantedResolves").filter((row) => String(row[0]) === nodeId(options.filePath, callee)).map((row) => String(row[1]));
     const settled = resolved.length === 1 ? resolved[0] : void 0;
     if (settled === void 0) {
@@ -17005,22 +17149,7 @@ function storageEffects(calls, options) {
     if (pattern === void 0) {
       continue;
     }
-    effects.push({
-      type: "interaction",
-      binding: storageRelationalBinding({
-        recognition: "python-storage",
-        storageSystem: pattern.storageSystem,
-        scope: pattern.module,
-        table: chain.subject
-      }),
-      callee: chain.last.text,
-      interaction: {
-        class: "storage-access",
-        kind: pattern.writes.includes(chain.operation) ? "write" : "read",
-        fields: [],
-        operation: chain.operation
-      }
-    });
+    effects.push(effectFor(pattern, chain, options));
   }
   return effects;
 }
@@ -17597,7 +17726,7 @@ function buildRouteUnit(options) {
   const branches = (perReturn ?? []).map(
     (branch) => storage.length === 0 ? branch : { ...branch, extraEffects: storage }
   );
-  if (perReturn === null && (responseShape.reading.kind !== "absent" || statusCode.reading.kind !== "absent" || storage.length > 0)) {
+  if (perReturn === null && (responseShape.reading.kind !== "absent" || statusCode.reading.kind !== "absent" || storage.length > 0 || effects.length > 0)) {
     branches.push({
       conditions: [],
       terminal: {
@@ -17897,6 +18026,11 @@ function emitModuleImportFacts(db, filePath, module2, resolverOptions) {
       moduleText,
       resolution.status === "resolved" ? "resolved" : resolution.reason
     ]);
+    db.add("pyImportedName", [
+      `${filePath}#${localName}`,
+      moduleText,
+      binding.kind === "import" ? binding.localName : binding.importedName
+    ]);
     if (resolution.status === "resolved") {
       db.add("pyImportResolved", [filePath, moduleText, resolution.file]);
       db.add("imports", [
@@ -18047,6 +18181,11 @@ function unmountedReason(index) {
   if (loops.length === 0) {
     return "is never mounted through a single variable binding in the files read";
   }
+  const stopped = loops.find((loop) => loop.unmatched !== void 0);
+  if (stopped?.unmatched !== void 0) {
+    const { name, resolvedTo, matched, of } = stopped.unmatched;
+    return `is not mounted by name in the files read, and a loop at ${stopped.location} mounts a list this reading resolved, where ${matched} of ${of} entries matched a router and ${name} did not (it resolved to ${resolvedTo}), so the whole list is declined rather than most of it mounted`;
+  }
   return `is not mounted by name in the files read, and ${loopsClause(loops, "mount")} routers read out of a call this reading does not follow`;
 }
 function rivalRegistration(index, site) {
@@ -18474,25 +18613,32 @@ function mountCallOf(stmt, scope, scan) {
 function constructionsReturnedBy(target, index) {
   const facts = index.facts;
   if (facts === void 0) {
-    return [];
+    return { kind: "unread" };
   }
   const callKey = nodeId(target.file, target.call);
   resolveCalls(facts, [callKey]);
   const returned = objectReturnedBy(facts, callKey);
   if (returned === null) {
-    return [];
+    return { kind: "unread" };
   }
   const contained = containedValues(facts, returned);
   resolveCalls(facts, contained);
   const found = [];
   for (const value of contained) {
-    const construction = index.byValueKey.get(resolvedValueKey(facts, value));
+    const resolved = resolvedValueKey(facts, value);
+    const construction = index.byValueKey.get(resolved);
     if (construction === void 0) {
-      return [];
+      return {
+        kind: "unmatched",
+        name: value,
+        resolvedTo: resolved,
+        matched: found.length,
+        of: contained.length
+      };
     }
     found.push(construction);
   }
-  return found;
+  return { kind: "settled", found };
 }
 function resolvedValueKey(facts, value) {
   const row = facts.facts("wantedIsWrittenAs").find((entry) => String(entry[0]) === value);
@@ -18514,10 +18660,16 @@ function mountedConstructions(arg, position, scan) {
     return target.elements.flatMap(named);
   }
   if (target.kind === "call") {
-    const settled = constructionsReturnedBy(target, scan.index);
-    if (settled.length > 0) {
-      return settled;
-    }
+    const returned = constructionsReturnedBy(target, scan.index);
+    if (returned.kind === "settled" && returned.found.length > 0) {
+      return returned.found;
+    }
+    scan.index.unenumerableLoops.set(target.location, {
+      site: position.site,
+      location: target.location,
+      ...returned.kind === "unmatched" ? { unmatched: returned } : {}
+    });
+    return [];
   }
   scan.index.unenumerableLoops.set(target.location, {
     site: position.site,
@@ -18835,6 +18987,11 @@ async function extractPythonProject(options) {
     }
   }
   const couldMatch = methodsDeclaredNear(db, storagePatterns, definitions);
+  const startsAQuery = /* @__PURE__ */ new Set([
+    ...couldMatch,
+    ...storagePatterns.flatMap((pattern) => pattern.queryFunctions ?? [])
+  ]);
+  const leadsToStorage = functionsReachingStorage(definitions, startsAQuery);
   const routerIndex = buildRouterIndex(bound, options.packs, {
     roots: options.roots,
     ...mountsRouters ? { facts: db } : {}
@@ -18852,7 +19009,8 @@ async function extractPythonProject(options) {
           factsPath: file2,
           patterns: storagePatterns,
           definitionAt: (key) => definitions.get(key),
-          couldMatch
+          couldMatch,
+          leadsToStorage
         }
       } : {}
     });
@@ -18918,6 +19076,52 @@ function methodsDeclaredNear(db, patterns, definitions) {
   }
   return found;
 }
+function calledName(call) {
+  const callee = field(call, "function");
+  if (callee === null) {
+    return "";
+  }
+  return callee.type === "attribute" ? field(callee, "attribute")?.text ?? "" : callee.text;
+}
+function callsUnder(node, found = []) {
+  for (const child of node.namedChildren) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "call") {
+      found.push(child);
+    }
+    callsUnder(child, found);
+  }
+  return found;
+}
+function functionsReachingStorage(definitions, couldMatch) {
+  const bodies = [];
+  for (const node of definitions.values()) {
+    const name = field(node, "name");
+    if (name === null) {
+      continue;
+    }
+    bodies.push({ name: name.text, calls: callsUnder(node).map(calledName) });
+  }
+  const reaching = /* @__PURE__ */ new Set();
+  for (const body of bodies) {
+    if (body.calls.some((called) => couldMatch.has(called))) {
+      reaching.add(body.name);
+    }
+  }
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const body of bodies) {
+      if (reaching.has(body.name) || !body.calls.some((c) => reaching.has(c))) {
+        continue;
+      }
+      reaching.add(body.name);
+      grew = true;
+    }
+  }
+  return reaching;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   annotationToShape,

package/dist/index.d.cts

@@ -182,6 +182,12 @@ interface StoragePattern {
     queryTypes: string[];
     /** Chain-ending methods that change what is stored. Anything else reads. */
     writes: string[];
+    /**
+     * Functions the library exports that start a query on their own, for the
+     * case where a call site imports one rather than reaching it through a
+     * project class. `select(...)` in SQLAlchemy 2.0 is one.
+     */
+    queryFunctions?: string[];
     /** Which database the library is talking to, for the boundary binding. */
     storageSystem: "postgres" | "mysql" | "sqlite";
 }
@@ -336,16 +342,13 @@ type NoValuePrefix = "unstated" | "unreadable";
  */
 type PathRepeatedSlashes = "kept" | "merged";
 
-/**
- * What discovery uses for one file. `factsPath` is the path the facts were
- * keyed under, which is the absolute one, while a summary shows the short one.
- */
 interface StorageLookup {
     readonly facts: Database;
     readonly factsPath: string;
     readonly patterns: readonly StoragePattern[];
     readonly definitionAt: (key: string) => Node | undefined;
     readonly couldMatch: ReadonlySet<string>;
+    readonly leadsToStorage: ReadonlySet<string>;
 }
 
 /**

package/dist/index.d.ts

@@ -182,6 +182,12 @@ interface StoragePattern {
     queryTypes: string[];
     /** Chain-ending methods that change what is stored. Anything else reads. */
     writes: string[];
+    /**
+     * Functions the library exports that start a query on their own, for the
+     * case where a call site imports one rather than reaching it through a
+     * project class. `select(...)` in SQLAlchemy 2.0 is one.
+     */
+    queryFunctions?: string[];
     /** Which database the library is talking to, for the boundary binding. */
     storageSystem: "postgres" | "mysql" | "sqlite";
 }
@@ -336,16 +342,13 @@ type NoValuePrefix = "unstated" | "unreadable";
  */
 type PathRepeatedSlashes = "kept" | "merged";
 
-/**
- * What discovery uses for one file. `factsPath` is the path the facts were
- * keyed under, which is the absolute one, while a summary shows the short one.
- */
 interface StorageLookup {
     readonly facts: Database;
     readonly factsPath: string;
     readonly patterns: readonly StoragePattern[];
     readonly definitionAt: (key: string) => Node | undefined;
     readonly couldMatch: ReadonlySet<string>;
+    readonly leadsToStorage: ReadonlySet<string>;
 }
 
 /**

package/dist/index.js

@@ -16189,21 +16189,22 @@ var RESOLUTION_RULES = [
     ]
   ),
   // Which calls a function, found by the name the call is written as
-  // rather than by resolving every callee in the project. Asking what
-  // reaches a parameter means looking for call sites, and looking for
-  // them the other way round costs a whole-project resolution.
+  // rather than by resolving every callee in the project. A caller knows
+  // the function and wants its call sites, so both of these start from
+  // the function. Starting from `call` instead asks what every call in
+  // the project imports, which was 72% of everything derived.
   rule(
     "callsFunction",
     [v("r"), v("f")],
-    [lit("call", v("r"), v("c")), lit("binds", v("c"), v("f"))]
+    [lit("binds", v("c"), v("f")), lit("call", v("r"), v("c"))]
   ),
   rule(
     "callsFunction",
     [v("r"), v("f")],
     [
-      lit("call", v("r"), v("c")),
+      lit("moduleExport", v("m"), v("n"), v("f")),
       lit("imports", v("c"), v("m"), v("n")),
-      lit("moduleExport", v("m"), v("n"), v("f"))
+      lit("call", v("r"), v("c"))
     ]
   ),
   // A function whose return is itself a call arrives at the same object
@@ -16897,11 +16898,85 @@ function chainsIn(calls) {
       root: call,
       last,
       subject: subjectOf(call),
-      operation: methodName(last)
+      operation: methodName(last),
+      between: calls.filter(
+        (other) => other !== call && other !== last && other.startIndex >= call.startIndex && other.endIndex <= last.endIndex
+      )
     });
   }
   return chains;
 }
+function importedQueryFunction(options, chain) {
+  const callee = field(chain.root, "function");
+  if (callee === null || callee.type !== "identifier") {
+    return void 0;
+  }
+  const from = options.facts.facts("pyImportedName").find((row) => String(row[0]) === `${options.filePath}#${callee.text}`);
+  if (from === void 0) {
+    return void 0;
+  }
+  return options.patterns.find(
+    (pattern) => String(from[1]) === pattern.module && (pattern.queryFunctions ?? []).includes(String(from[2]))
+  );
+}
+function fieldsOf(chain) {
+  const args = field(chain.root, "arguments");
+  const named = [];
+  for (const argument of args === null ? [] : children3(args)) {
+    if (argument.type === "keyword_argument") {
+      const name = field(argument, "name");
+      if (name !== null) {
+        named.push(name.text);
+      }
+      continue;
+    }
+    if (argument.type === "attribute") {
+      const property = field(argument, "attribute");
+      if (property !== null) {
+        named.push(property.text);
+      }
+    }
+  }
+  return named;
+}
+function selectorOf(call) {
+  const args = field(call, "arguments");
+  const picked = [];
+  for (const argument of args === null ? [] : children3(args)) {
+    if (argument.type === "keyword_argument") {
+      const name = field(argument, "name");
+      if (name !== null) {
+        picked.push(name.text);
+      }
+    }
+  }
+  return picked;
+}
+function effectFor(pattern, chain, options) {
+  const picked = [
+    ...new Set([chain.last, ...chain.between].flatMap(selectorOf))
+  ];
+  return {
+    type: "interaction",
+    binding: storageRelationalBinding({
+      recognition: "python-storage",
+      storageSystem: pattern.storageSystem,
+      scope: pattern.module,
+      table: chain.subject
+    }),
+    callee: chain.last.text,
+    interaction: {
+      class: "storage-access",
+      kind: pattern.writes.includes(chain.operation) ? "write" : "read",
+      fields: fieldsOf(chain),
+      operation: chain.operation,
+      ...picked.length > 0 ? { selector: picked } : {}
+    }
+  };
+}
+function children3(node) {
+  return node.namedChildren.filter((child) => child !== null);
+}
 function fileOf(key) {
   const at = key.lastIndexOf(":");
   return at === -1 ? key : key.slice(0, at);
@@ -16916,26 +16991,90 @@ function returnTypeName(node) {
   }
   return annotation.type === "subscript" ? field(annotation, "value")?.text ?? null : annotation.text;
 }
+function callsIn(node, found = []) {
+  for (const child of node.namedChildren) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "call") {
+      found.push(child);
+    }
+    callsIn(child, found);
+  }
+  return found;
+}
+function storageEffects(calls, options) {
+  const seen = /* @__PURE__ */ new Set();
+  const asked = new Set(
+    options.facts.facts("wanted").map((row) => String(row[0]))
+  );
+  const gather = (inCalls, filePath) => {
+    const found = [...directStorageEffects(inCalls, { ...options, filePath })];
+    resolveCalls(
+      options.facts,
+      inCalls.filter((call) => options.leadsToStorage.has(methodName(call))).map((call) => field(call, "function")).filter((callee) => callee !== null).map((callee) => calleeKeyOf(filePath, callee)).filter((key) => {
+        const fresh = !asked.has(key);
+        asked.add(key);
+        return fresh;
+      })
+    );
+    for (const call of inCalls) {
+      const callee = field(call, "function");
+      if (callee === null || !options.leadsToStorage.has(methodName(call))) {
+        continue;
+      }
+      const key = resolvedOnce(options, calleeKeyOf(filePath, callee));
+      const body = key === void 0 ? void 0 : options.definitionAt(key);
+      if (key === void 0 || body === void 0 || seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      const name = field(body, "name")?.text;
+      const origin = {
+        file: fileOf(key),
+        line: body.startPosition.row + 1,
+        ...name === void 0 ? {} : { function: name }
+      };
+      found.push(
+        ...gather(callsIn(body), fileOf(key)).map(
+          (effect) => effect.type === "interaction" && effect.origin === void 0 ? { ...effect, origin } : effect
+        )
+      );
+    }
+    return found;
+  };
+  return gather(calls, options.filePath);
+}
+function calleeKeyOf(filePath, callee) {
+  return callee.type === "identifier" ? `${filePath}#${callee.text}` : nodeId(filePath, callee);
+}
+function resolvedOnce(options, calleeKey) {
+  const resolved = options.facts.facts("wantedResolves").filter((row) => String(row[0]) === calleeKey).map((row) => String(row[1]));
+  return resolved.length === 1 ? resolved[0] : void 0;
+}
 function storageCallees(calls, filePath, couldMatch) {
   return chainsIn(calls).filter((chain) => couldMatch.has(methodName(chain.root))).map((chain) => field(chain.root, "function")).filter((callee) => callee !== null).map((callee) => nodeId(filePath, callee));
 }
-function storageEffects(calls, options) {
+function directStorageEffects(calls, options) {
   if (options.patterns.length === 0) {
     return [];
   }
+  const named = new Set(
+    options.patterns.flatMap((pattern) => pattern.queryFunctions ?? [])
+  );
   const chains = chainsIn(calls).filter(
-    (chain) => options.couldMatch.has(methodName(chain.root))
+    (chain) => options.couldMatch.has(methodName(chain.root)) || named.has(methodName(chain.root))
   );
   if (chains.length === 0) {
     return [];
   }
-  const asked = new Set(
+  const alreadyAsked = new Set(
     options.facts.facts("wanted").map((row) => String(row[0]))
   );
   resolveCalls(
     options.facts,
     storageCallees(calls, options.filePath, options.couldMatch).filter(
-      (key) => !asked.has(key)
+      (key) => !alreadyAsked.has(key)
     )
   );
   const effects = [];
@@ -16944,6 +17083,11 @@ function storageEffects(calls, options) {
     if (callee === null) {
       continue;
     }
+    const imported = importedQueryFunction(options, chain);
+    if (imported !== void 0) {
+      effects.push(effectFor(imported, chain, options));
+      continue;
+    }
     const resolved = options.facts.facts("wantedResolves").filter((row) => String(row[0]) === nodeId(options.filePath, callee)).map((row) => String(row[1]));
     const settled = resolved.length === 1 ? resolved[0] : void 0;
     if (settled === void 0) {
@@ -16961,22 +17105,7 @@ function storageEffects(calls, options) {
     if (pattern === void 0) {
       continue;
     }
-    effects.push({
-      type: "interaction",
-      binding: storageRelationalBinding({
-        recognition: "python-storage",
-        storageSystem: pattern.storageSystem,
-        scope: pattern.module,
-        table: chain.subject
-      }),
-      callee: chain.last.text,
-      interaction: {
-        class: "storage-access",
-        kind: pattern.writes.includes(chain.operation) ? "write" : "read",
-        fields: [],
-        operation: chain.operation
-      }
-    });
+    effects.push(effectFor(pattern, chain, options));
   }
   return effects;
 }
@@ -17553,7 +17682,7 @@ function buildRouteUnit(options) {
   const branches = (perReturn ?? []).map(
     (branch) => storage.length === 0 ? branch : { ...branch, extraEffects: storage }
   );
-  if (perReturn === null && (responseShape.reading.kind !== "absent" || statusCode.reading.kind !== "absent" || storage.length > 0)) {
+  if (perReturn === null && (responseShape.reading.kind !== "absent" || statusCode.reading.kind !== "absent" || storage.length > 0 || effects.length > 0)) {
     branches.push({
       conditions: [],
       terminal: {
@@ -17853,6 +17982,11 @@ function emitModuleImportFacts(db, filePath, module, resolverOptions) {
       moduleText,
       resolution.status === "resolved" ? "resolved" : resolution.reason
     ]);
+    db.add("pyImportedName", [
+      `${filePath}#${localName}`,
+      moduleText,
+      binding.kind === "import" ? binding.localName : binding.importedName
+    ]);
     if (resolution.status === "resolved") {
       db.add("pyImportResolved", [filePath, moduleText, resolution.file]);
       db.add("imports", [
@@ -18003,6 +18137,11 @@ function unmountedReason(index) {
   if (loops.length === 0) {
     return "is never mounted through a single variable binding in the files read";
   }
+  const stopped = loops.find((loop) => loop.unmatched !== void 0);
+  if (stopped?.unmatched !== void 0) {
+    const { name, resolvedTo, matched, of } = stopped.unmatched;
+    return `is not mounted by name in the files read, and a loop at ${stopped.location} mounts a list this reading resolved, where ${matched} of ${of} entries matched a router and ${name} did not (it resolved to ${resolvedTo}), so the whole list is declined rather than most of it mounted`;
+  }
   return `is not mounted by name in the files read, and ${loopsClause(loops, "mount")} routers read out of a call this reading does not follow`;
 }
 function rivalRegistration(index, site) {
@@ -18430,25 +18569,32 @@ function mountCallOf(stmt, scope, scan) {
 function constructionsReturnedBy(target, index) {
   const facts = index.facts;
   if (facts === void 0) {
-    return [];
+    return { kind: "unread" };
   }
   const callKey = nodeId(target.file, target.call);
   resolveCalls(facts, [callKey]);
   const returned = objectReturnedBy(facts, callKey);
   if (returned === null) {
-    return [];
+    return { kind: "unread" };
   }
   const contained = containedValues(facts, returned);
   resolveCalls(facts, contained);
   const found = [];
   for (const value of contained) {
-    const construction = index.byValueKey.get(resolvedValueKey(facts, value));
+    const resolved = resolvedValueKey(facts, value);
+    const construction = index.byValueKey.get(resolved);
     if (construction === void 0) {
-      return [];
+      return {
+        kind: "unmatched",
+        name: value,
+        resolvedTo: resolved,
+        matched: found.length,
+        of: contained.length
+      };
     }
     found.push(construction);
   }
-  return found;
+  return { kind: "settled", found };
 }
 function resolvedValueKey(facts, value) {
   const row = facts.facts("wantedIsWrittenAs").find((entry) => String(entry[0]) === value);
@@ -18470,10 +18616,16 @@ function mountedConstructions(arg, position, scan) {
     return target.elements.flatMap(named);
   }
   if (target.kind === "call") {
-    const settled = constructionsReturnedBy(target, scan.index);
-    if (settled.length > 0) {
-      return settled;
-    }
+    const returned = constructionsReturnedBy(target, scan.index);
+    if (returned.kind === "settled" && returned.found.length > 0) {
+      return returned.found;
+    }
+    scan.index.unenumerableLoops.set(target.location, {
+      site: position.site,
+      location: target.location,
+      ...returned.kind === "unmatched" ? { unmatched: returned } : {}
+    });
+    return [];
   }
   scan.index.unenumerableLoops.set(target.location, {
     site: position.site,
@@ -18791,6 +18943,11 @@ async function extractPythonProject(options) {
     }
   }
   const couldMatch = methodsDeclaredNear(db, storagePatterns, definitions);
+  const startsAQuery = /* @__PURE__ */ new Set([
+    ...couldMatch,
+    ...storagePatterns.flatMap((pattern) => pattern.queryFunctions ?? [])
+  ]);
+  const leadsToStorage = functionsReachingStorage(definitions, startsAQuery);
   const routerIndex = buildRouterIndex(bound, options.packs, {
     roots: options.roots,
     ...mountsRouters ? { facts: db } : {}
@@ -18808,7 +18965,8 @@ async function extractPythonProject(options) {
           factsPath: file2,
           patterns: storagePatterns,
           definitionAt: (key) => definitions.get(key),
-          couldMatch
+          couldMatch,
+          leadsToStorage
         }
       } : {}
     });
@@ -18874,6 +19032,52 @@ function methodsDeclaredNear(db, patterns, definitions) {
   }
   return found;
 }
+function calledName(call) {
+  const callee = field(call, "function");
+  if (callee === null) {
+    return "";
+  }
+  return callee.type === "attribute" ? field(callee, "attribute")?.text ?? "" : callee.text;
+}
+function callsUnder(node, found = []) {
+  for (const child of node.namedChildren) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "call") {
+      found.push(child);
+    }
+    callsUnder(child, found);
+  }
+  return found;
+}
+function functionsReachingStorage(definitions, couldMatch) {
+  const bodies = [];
+  for (const node of definitions.values()) {
+    const name = field(node, "name");
+    if (name === null) {
+      continue;
+    }
+    bodies.push({ name: name.text, calls: callsUnder(node).map(calledName) });
+  }
+  const reaching = /* @__PURE__ */ new Set();
+  for (const body of bodies) {
+    if (body.calls.some((called) => couldMatch.has(called))) {
+      reaching.add(body.name);
+    }
+  }
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const body of bodies) {
+      if (reaching.has(body.name) || !body.calls.some((c) => reaching.has(c))) {
+        continue;
+      }
+      reaching.add(body.name);
+      grew = true;
+    }
+  }
+  return reaching;
+}
 export {
   annotationToShape,
   bindModule,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/adapter-python",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Python language adapter for suss — parses source with tree-sitter (WASM), resolves names with a lexical binder, and emits raw extractions for the suss pipeline.",
   "keywords": [
@@ -47,9 +47,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.4.0",
-    "@suss/datalog": "0.4.0",
-    "@suss/extractor": "0.4.0",
+    "@suss/behavioral-ir": "0.5.0",
+    "@suss/datalog": "0.5.0",
+    "@suss/extractor": "0.5.0",
     "web-tree-sitter": "^0.26.11"
   },
   "devDependencies": {