@suss/adapter-python 0.5.1 → 0.5.3

package/dist/index.cjs

@@ -666,6 +666,82 @@ function classifyDecorator(decoratorNode, scope) {
   }
   return { ...resolveCallee(expr, scope), args: [], keywordArgs: {}, range };
 }
+function unwrapDecorator(decoratorNode, scope, ownModule, moduleDef) {
+  const expr = decoratorNode.namedChild(0);
+  if (expr === null || expr.type !== "call") {
+    return null;
+  }
+  const callee = field(expr, "function");
+  if (callee === null || callee.type !== "identifier") {
+    return null;
+  }
+  const wrapper = wrapperBehind(callee.text, scope, ownModule, moduleDef);
+  if (wrapper === null) {
+    return null;
+  }
+  const inner = singleReturnedCall(wrapper.node);
+  if (inner === null) {
+    return null;
+  }
+  const innerCallee = field(inner, "function");
+  if (innerCallee === null || innerCallee.type !== "attribute") {
+    return null;
+  }
+  if (!passesParametersThrough(wrapper.node, inner)) {
+    return null;
+  }
+  const resolved = resolveCallee(innerCallee, wrapper.module.moduleScope);
+  if (resolved.importedName === null) {
+    return null;
+  }
+  const argumentList = field(expr, "arguments");
+  const { args, keywordArgs } = argumentList?.type === "argument_list" ? readCallArguments(argumentList) : { args: [], keywordArgs: {} };
+  return {
+    ...resolved,
+    args,
+    keywordArgs,
+    range: rangeOf(decoratorNode),
+    objectModule: wrapper.module
+  };
+}
+function wrapperBehind(name, scope, ownModule, moduleDef) {
+  const binding = resolveName(scope, name);
+  if (binding?.kind === "functionDef") {
+    return { node: binding.node, module: ownModule };
+  }
+  if (binding?.kind === "importFrom") {
+    return moduleDef(
+      { module: binding.module, relativeLevel: binding.relativeLevel },
+      binding.importedName
+    );
+  }
+  return null;
+}
+function singleReturnedCall(def) {
+  const body = field(def, "body");
+  if (body === null) {
+    return null;
+  }
+  const statements = body.namedChildren.filter(
+    (child) => child !== null && child.type !== "comment"
+  );
+  if (statements.length !== 1 || statements[0]?.type !== "return_statement") {
+    return null;
+  }
+  const returned = statements[0].namedChildren[0];
+  return returned !== null && returned?.type === "call" ? returned : null;
+}
+function passesParametersThrough(def, inner) {
+  const params = field(def, "parameters");
+  const names = (params?.namedChildren ?? []).filter((child) => child?.type === "identifier").map((child) => child.text);
+  const argumentList = field(inner, "arguments");
+  const positional = (argumentList?.namedChildren ?? []).filter(
+    (child) => child !== null && child.type !== "keyword_argument"
+  );
+  return positional.length === names.length && positional.every(
+    (argument, at) => argument.type === "identifier" && argument.text === names[at]
+  );
+}
 
 // src/discovery.ts
 var import_behavioral_ir = require("@suss/behavioral-ir");
@@ -17177,33 +17253,51 @@ function discoverUnits(root, module2, options) {
     }
     const { definition, decorators } = stripDecorators(stmt);
     for (const decoratorNode of decorators) {
-      const classification = classifyDecorator(
-        decoratorNode,
-        module2.moduleScope
+      const direct = classifyDecorator(decoratorNode, module2.moduleScope);
+      const classifications = direct.module !== null && acceptedByAnyPattern(direct.module, options) ? [direct] : [
+        unwrapDecorator(
+          decoratorNode,
+          module2.moduleScope,
+          module2,
+          (spec, name) => options.routerIndex?.moduleDef(
+            options.absoluteFile ?? options.filePath,
+            spec,
+            name
+          ) ?? null
+        )
+      ].filter(
+        (candidate) => candidate !== null
       );
-      if (classification.module === null) {
-        continue;
-      }
-      const decoratorModule = classification.module;
-      for (const pack of options.packs) {
-        for (const pattern of pack.discovery) {
-          units.push(
-            ...unitsFor(
-              pattern,
-              pack,
-              decoratorModule,
-              classification,
-              definition,
-              module2,
-              options
-            )
-          );
+      for (const classification of classifications) {
+        if (classification.module === null) {
+          continue;
+        }
+        const decoratorModule = classification.module;
+        for (const pack of options.packs) {
+          for (const pattern of pack.discovery) {
+            units.push(
+              ...unitsFor(
+                pattern,
+                pack,
+                decoratorModule,
+                classification,
+                definition,
+                module2,
+                options
+              )
+            );
+          }
         }
       }
     }
   }
   return units;
 }
+function acceptedByAnyPattern(module2, options) {
+  return options.packs.some(
+    (pack) => pack.discovery.some((pattern) => pattern.importModule.includes(module2))
+  );
+}
 function unitsFor(pattern, pack, decoratorModule, classification, definition, module2, options) {
   if (!pattern.importModule.includes(decoratorModule)) {
     return [];
@@ -17381,7 +17475,7 @@ function readRouterPrefix(pattern, classification, module2, options, range) {
   }
   const resolution = options.routerIndex.resolve(
     pattern,
-    module2,
+    classification.objectModule ?? module2,
     classification.objectName
   );
   if (resolution.kind === "abstain") {
@@ -18126,7 +18220,28 @@ function buildRouterIndex(files, packs, resolverOptions) {
       }
     }
   }
+  const byFile = /* @__PURE__ */ new Map();
+  const displayPaths = /* @__PURE__ */ new Map();
+  for (const file2 of files) {
+    byFile.set(file2.file, file2);
+    displayPaths.set(file2.module, file2.displayPath);
+  }
   return {
+    moduleDef(fromFile, spec, name) {
+      const resolution = resolveModule(fromFile, spec, resolverOptions);
+      if (resolution.status !== "resolved") {
+        return null;
+      }
+      const bound = byFile.get(resolution.file);
+      if (bound === void 0) {
+        return null;
+      }
+      const binding = bound.module.moduleScope.bindings.get(name);
+      if (binding?.kind !== "functionDef") {
+        return null;
+      }
+      return { node: binding.node, module: bound.module };
+    },
     resolve(pattern, module2, objectName) {
       const index = byPattern.get(pattern);
       if (index === void 0) {
@@ -18149,14 +18264,15 @@ function buildRouterIndex(files, packs, resolverOptions) {
       if (ownPrefix.kind === "abstain") {
         return ownPrefix;
       }
+      const routerPath = displayPaths.get(module2);
       const mount = index.mounts.get(construction);
       if (mount === void 0) {
-        return { kind: "abstain", reason: unmountedReason(index) };
+        return { kind: "abstain", reason: unmountedReason(index, routerPath) };
       }
       if (mount.kind === "abstain") {
         return { kind: "abstain", reason: mount.reason };
       }
-      const rivalled = rivalRegistration(index, mount.site);
+      const rivalled = rivalRegistration(index, mount.site, routerPath);
       if (rivalled !== null) {
         return { kind: "abstain", reason: rivalled };
       }
@@ -18190,24 +18306,32 @@ function loopsClause(loops, verb) {
   }
   return `loops at ${locations.join(", ")} ${verb}`;
 }
-function unmountedReason(index) {
-  const loops = [...index.unenumerableLoops.values()];
-  if (loops.length === 0) {
-    return "is never mounted through a single variable binding in the files read";
+function couldReach(loop, routerPath) {
+  if (routerPath === void 0) {
+    return true;
   }
+  const directory = loop.file.slice(0, loop.file.lastIndexOf("/") + 1);
+  return routerPath.startsWith(directory);
+}
+function unmountedReason(index, routerPath) {
+  const loops = [...index.unenumerableLoops.values()];
   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`;
+  const reachable = loops.filter((loop) => couldReach(loop, routerPath));
+  if (reachable.length === 0) {
+    return "is never mounted through a single variable binding in the files read";
+  }
+  return `is not mounted by name in the files read, and ${loopsClause(reachable, "mount")} routers read out of a call this reading does not follow`;
 }
-function rivalRegistration(index, site) {
+function rivalRegistration(index, site, routerPath) {
   if (site.kind === "module") {
     return null;
   }
   const rivals = [...index.unenumerableLoops.values()].filter(
-    (loop) => !sameSite(loop.site, site)
+    (loop) => !sameSite(loop.site, site) && couldReach(loop, routerPath)
   );
   if (rivals.length === 0) {
     return null;
@@ -18680,6 +18804,7 @@ function mountedConstructions(arg, position, scan) {
     }
     scan.index.unenumerableLoops.set(target.location, {
       site: position.site,
+      file: scan.bound.displayPath,
       location: target.location,
       ...returned.kind === "unmatched" ? { unmatched: returned } : {}
     });
@@ -18687,6 +18812,7 @@ function mountedConstructions(arg, position, scan) {
   }
   scan.index.unenumerableLoops.set(target.location, {
     site: position.site,
+    file: scan.bound.displayPath,
     location: target.location
   });
   return [];
@@ -19015,6 +19141,7 @@ async function extractPythonProject(options) {
     const rawUnits = discoverUnits(root, moduleBinding, {
       packs: options.packs,
       filePath: displayPath,
+      absoluteFile: file2,
       routerIndex,
       gapHandling,
       ...storagePatterns.length > 0 ? {

package/dist/index.d.cts

@@ -146,6 +146,12 @@ interface DecoratorClassification {
     keywordArgs: Record<string, DecoratorArg>;
     /** Where the decorator is written. Anything we read out of its arguments uses this as its provenance. */
     range: Range;
+    /**
+     * The module the decorator's object lives in, when the decorator was read
+     * through a project wrapper written in another file. The router prefix is
+     * resolved there, since that is where the namespace is constructed.
+     */
+    objectModule?: ModuleBinding;
 }
 declare function classifyDecorator(decoratorNode: Node, scope: Scope): DecoratorClassification;
 
@@ -417,6 +423,18 @@ type RoutePrefixResolution = {
 };
 interface RouterIndex {
     resolve(pattern: PythonDiscoveryPattern, module: ModuleBinding, objectName: string): RoutePrefixResolution;
+    /**
+     * The module-level def a name in another module refers to, with that
+     * module's own bindings, so a decorator written through a project wrapper
+     * can be read where the wrapper is written.
+     */
+    moduleDef(fromFile: string, spec: {
+        module: string;
+        relativeLevel: number;
+    }, name: string): {
+        node: Node;
+        module: ModuleBinding;
+    } | null;
 }
 interface RouterIndexOptions extends ModuleResolverOptions {
     /** The project's facts, so a loop over a call can be settled by the rules. */
@@ -448,6 +466,8 @@ interface DiscoveryOptions {
     gapHandling?: ExtractorOptions["gapHandling"];
     /** What a pack needs to say a call talks to the database. Absent when no pack does. */
     storage?: StorageLookup | undefined;
+    /** The file's absolute path, which module resolution wants; `filePath` may be shortened for display. */
+    absoluteFile?: string | undefined;
 }
 declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];
 

package/dist/index.d.ts

@@ -146,6 +146,12 @@ interface DecoratorClassification {
     keywordArgs: Record<string, DecoratorArg>;
     /** Where the decorator is written. Anything we read out of its arguments uses this as its provenance. */
     range: Range;
+    /**
+     * The module the decorator's object lives in, when the decorator was read
+     * through a project wrapper written in another file. The router prefix is
+     * resolved there, since that is where the namespace is constructed.
+     */
+    objectModule?: ModuleBinding;
 }
 declare function classifyDecorator(decoratorNode: Node, scope: Scope): DecoratorClassification;
 
@@ -417,6 +423,18 @@ type RoutePrefixResolution = {
 };
 interface RouterIndex {
     resolve(pattern: PythonDiscoveryPattern, module: ModuleBinding, objectName: string): RoutePrefixResolution;
+    /**
+     * The module-level def a name in another module refers to, with that
+     * module's own bindings, so a decorator written through a project wrapper
+     * can be read where the wrapper is written.
+     */
+    moduleDef(fromFile: string, spec: {
+        module: string;
+        relativeLevel: number;
+    }, name: string): {
+        node: Node;
+        module: ModuleBinding;
+    } | null;
 }
 interface RouterIndexOptions extends ModuleResolverOptions {
     /** The project's facts, so a loop over a call can be settled by the rules. */
@@ -448,6 +466,8 @@ interface DiscoveryOptions {
     gapHandling?: ExtractorOptions["gapHandling"];
     /** What a pack needs to say a call talks to the database. Absent when no pack does. */
     storage?: StorageLookup | undefined;
+    /** The file's absolute path, which module resolution wants; `filePath` may be shortened for display. */
+    absoluteFile?: string | undefined;
 }
 declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];
 

package/dist/index.js

@@ -612,6 +612,82 @@ function classifyDecorator(decoratorNode, scope) {
   }
   return { ...resolveCallee(expr, scope), args: [], keywordArgs: {}, range };
 }
+function unwrapDecorator(decoratorNode, scope, ownModule, moduleDef) {
+  const expr = decoratorNode.namedChild(0);
+  if (expr === null || expr.type !== "call") {
+    return null;
+  }
+  const callee = field(expr, "function");
+  if (callee === null || callee.type !== "identifier") {
+    return null;
+  }
+  const wrapper = wrapperBehind(callee.text, scope, ownModule, moduleDef);
+  if (wrapper === null) {
+    return null;
+  }
+  const inner = singleReturnedCall(wrapper.node);
+  if (inner === null) {
+    return null;
+  }
+  const innerCallee = field(inner, "function");
+  if (innerCallee === null || innerCallee.type !== "attribute") {
+    return null;
+  }
+  if (!passesParametersThrough(wrapper.node, inner)) {
+    return null;
+  }
+  const resolved = resolveCallee(innerCallee, wrapper.module.moduleScope);
+  if (resolved.importedName === null) {
+    return null;
+  }
+  const argumentList = field(expr, "arguments");
+  const { args, keywordArgs } = argumentList?.type === "argument_list" ? readCallArguments(argumentList) : { args: [], keywordArgs: {} };
+  return {
+    ...resolved,
+    args,
+    keywordArgs,
+    range: rangeOf(decoratorNode),
+    objectModule: wrapper.module
+  };
+}
+function wrapperBehind(name, scope, ownModule, moduleDef) {
+  const binding = resolveName(scope, name);
+  if (binding?.kind === "functionDef") {
+    return { node: binding.node, module: ownModule };
+  }
+  if (binding?.kind === "importFrom") {
+    return moduleDef(
+      { module: binding.module, relativeLevel: binding.relativeLevel },
+      binding.importedName
+    );
+  }
+  return null;
+}
+function singleReturnedCall(def) {
+  const body = field(def, "body");
+  if (body === null) {
+    return null;
+  }
+  const statements = body.namedChildren.filter(
+    (child) => child !== null && child.type !== "comment"
+  );
+  if (statements.length !== 1 || statements[0]?.type !== "return_statement") {
+    return null;
+  }
+  const returned = statements[0].namedChildren[0];
+  return returned !== null && returned?.type === "call" ? returned : null;
+}
+function passesParametersThrough(def, inner) {
+  const params = field(def, "parameters");
+  const names = (params?.namedChildren ?? []).filter((child) => child?.type === "identifier").map((child) => child.text);
+  const argumentList = field(inner, "arguments");
+  const positional = (argumentList?.namedChildren ?? []).filter(
+    (child) => child !== null && child.type !== "keyword_argument"
+  );
+  return positional.length === names.length && positional.every(
+    (argument, at) => argument.type === "identifier" && argument.text === names[at]
+  );
+}
 
 // src/discovery.ts
 import { dispatchByType, restBinding } from "@suss/behavioral-ir";
@@ -17133,33 +17209,51 @@ function discoverUnits(root, module, options) {
     }
     const { definition, decorators } = stripDecorators(stmt);
     for (const decoratorNode of decorators) {
-      const classification = classifyDecorator(
-        decoratorNode,
-        module.moduleScope
+      const direct = classifyDecorator(decoratorNode, module.moduleScope);
+      const classifications = direct.module !== null && acceptedByAnyPattern(direct.module, options) ? [direct] : [
+        unwrapDecorator(
+          decoratorNode,
+          module.moduleScope,
+          module,
+          (spec, name) => options.routerIndex?.moduleDef(
+            options.absoluteFile ?? options.filePath,
+            spec,
+            name
+          ) ?? null
+        )
+      ].filter(
+        (candidate) => candidate !== null
       );
-      if (classification.module === null) {
-        continue;
-      }
-      const decoratorModule = classification.module;
-      for (const pack of options.packs) {
-        for (const pattern of pack.discovery) {
-          units.push(
-            ...unitsFor(
-              pattern,
-              pack,
-              decoratorModule,
-              classification,
-              definition,
-              module,
-              options
-            )
-          );
+      for (const classification of classifications) {
+        if (classification.module === null) {
+          continue;
+        }
+        const decoratorModule = classification.module;
+        for (const pack of options.packs) {
+          for (const pattern of pack.discovery) {
+            units.push(
+              ...unitsFor(
+                pattern,
+                pack,
+                decoratorModule,
+                classification,
+                definition,
+                module,
+                options
+              )
+            );
+          }
         }
       }
     }
   }
   return units;
 }
+function acceptedByAnyPattern(module, options) {
+  return options.packs.some(
+    (pack) => pack.discovery.some((pattern) => pattern.importModule.includes(module))
+  );
+}
 function unitsFor(pattern, pack, decoratorModule, classification, definition, module, options) {
   if (!pattern.importModule.includes(decoratorModule)) {
     return [];
@@ -17337,7 +17431,7 @@ function readRouterPrefix(pattern, classification, module, options, range) {
   }
   const resolution = options.routerIndex.resolve(
     pattern,
-    module,
+    classification.objectModule ?? module,
     classification.objectName
   );
   if (resolution.kind === "abstain") {
@@ -18082,7 +18176,28 @@ function buildRouterIndex(files, packs, resolverOptions) {
       }
     }
   }
+  const byFile = /* @__PURE__ */ new Map();
+  const displayPaths = /* @__PURE__ */ new Map();
+  for (const file2 of files) {
+    byFile.set(file2.file, file2);
+    displayPaths.set(file2.module, file2.displayPath);
+  }
   return {
+    moduleDef(fromFile, spec, name) {
+      const resolution = resolveModule(fromFile, spec, resolverOptions);
+      if (resolution.status !== "resolved") {
+        return null;
+      }
+      const bound = byFile.get(resolution.file);
+      if (bound === void 0) {
+        return null;
+      }
+      const binding = bound.module.moduleScope.bindings.get(name);
+      if (binding?.kind !== "functionDef") {
+        return null;
+      }
+      return { node: binding.node, module: bound.module };
+    },
     resolve(pattern, module, objectName) {
       const index = byPattern.get(pattern);
       if (index === void 0) {
@@ -18105,14 +18220,15 @@ function buildRouterIndex(files, packs, resolverOptions) {
       if (ownPrefix.kind === "abstain") {
         return ownPrefix;
       }
+      const routerPath = displayPaths.get(module);
       const mount = index.mounts.get(construction);
       if (mount === void 0) {
-        return { kind: "abstain", reason: unmountedReason(index) };
+        return { kind: "abstain", reason: unmountedReason(index, routerPath) };
       }
       if (mount.kind === "abstain") {
         return { kind: "abstain", reason: mount.reason };
       }
-      const rivalled = rivalRegistration(index, mount.site);
+      const rivalled = rivalRegistration(index, mount.site, routerPath);
       if (rivalled !== null) {
         return { kind: "abstain", reason: rivalled };
       }
@@ -18146,24 +18262,32 @@ function loopsClause(loops, verb) {
   }
   return `loops at ${locations.join(", ")} ${verb}`;
 }
-function unmountedReason(index) {
-  const loops = [...index.unenumerableLoops.values()];
-  if (loops.length === 0) {
-    return "is never mounted through a single variable binding in the files read";
+function couldReach(loop, routerPath) {
+  if (routerPath === void 0) {
+    return true;
   }
+  const directory = loop.file.slice(0, loop.file.lastIndexOf("/") + 1);
+  return routerPath.startsWith(directory);
+}
+function unmountedReason(index, routerPath) {
+  const loops = [...index.unenumerableLoops.values()];
   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`;
+  const reachable = loops.filter((loop) => couldReach(loop, routerPath));
+  if (reachable.length === 0) {
+    return "is never mounted through a single variable binding in the files read";
+  }
+  return `is not mounted by name in the files read, and ${loopsClause(reachable, "mount")} routers read out of a call this reading does not follow`;
 }
-function rivalRegistration(index, site) {
+function rivalRegistration(index, site, routerPath) {
   if (site.kind === "module") {
     return null;
   }
   const rivals = [...index.unenumerableLoops.values()].filter(
-    (loop) => !sameSite(loop.site, site)
+    (loop) => !sameSite(loop.site, site) && couldReach(loop, routerPath)
   );
   if (rivals.length === 0) {
     return null;
@@ -18636,6 +18760,7 @@ function mountedConstructions(arg, position, scan) {
     }
     scan.index.unenumerableLoops.set(target.location, {
       site: position.site,
+      file: scan.bound.displayPath,
       location: target.location,
       ...returned.kind === "unmatched" ? { unmatched: returned } : {}
     });
@@ -18643,6 +18768,7 @@ function mountedConstructions(arg, position, scan) {
   }
   scan.index.unenumerableLoops.set(target.location, {
     site: position.site,
+    file: scan.bound.displayPath,
     location: target.location
   });
   return [];
@@ -18971,6 +19097,7 @@ async function extractPythonProject(options) {
     const rawUnits = discoverUnits(root, moduleBinding, {
       packs: options.packs,
       filePath: displayPath,
+      absoluteFile: file2,
       routerIndex,
       gapHandling,
       ...storagePatterns.length > 0 ? {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/adapter-python",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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.5.1",
-    "@suss/datalog": "0.5.1",
-    "@suss/extractor": "0.5.1",
+    "@suss/behavioral-ir": "0.5.3",
+    "@suss/datalog": "0.5.3",
+    "@suss/extractor": "0.5.3",
     "web-tree-sitter": "^0.26.11"
   },
   "devDependencies": {