@suss/adapter-python 0.5.0 → 0.5.2

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");
@@ -994,12 +1070,26 @@ function argsOf(call) {
 function calleeText(call) {
   return field(call, "function")?.text ?? call.text;
 }
+function withoutChainLinks(calls) {
+  const isLink = /* @__PURE__ */ new Set();
+  for (const call of calls) {
+    const callee = field(call, "function");
+    if (callee === null || callee.type !== "attribute") {
+      continue;
+    }
+    const object2 = field(callee, "object");
+    if (object2 !== null && object2.type === "call") {
+      isLink.add(object2.id);
+    }
+  }
+  return calls.filter((call) => !isLink.has(call.id));
+}
 function invocationEffects(definitionNode) {
   const body = field(definitionNode, "body");
   if (body === null) {
     return [];
   }
-  const calls = bodyCalls(body);
+  const calls = withoutChainLinks(bodyCalls(body));
   if (calls.length === 0) {
     return [];
   }
@@ -17163,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 [];
@@ -17367,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") {
@@ -18112,7 +18220,26 @@ function buildRouterIndex(files, packs, resolverOptions) {
       }
     }
   }
+  const byFile = /* @__PURE__ */ new Map();
+  for (const file2 of files) {
+    byFile.set(file2.file, file2);
+  }
   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) {
@@ -19001,6 +19128,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";
@@ -950,12 +1026,26 @@ function argsOf(call) {
 function calleeText(call) {
   return field(call, "function")?.text ?? call.text;
 }
+function withoutChainLinks(calls) {
+  const isLink = /* @__PURE__ */ new Set();
+  for (const call of calls) {
+    const callee = field(call, "function");
+    if (callee === null || callee.type !== "attribute") {
+      continue;
+    }
+    const object2 = field(callee, "object");
+    if (object2 !== null && object2.type === "call") {
+      isLink.add(object2.id);
+    }
+  }
+  return calls.filter((call) => !isLink.has(call.id));
+}
 function invocationEffects(definitionNode) {
   const body = field(definitionNode, "body");
   if (body === null) {
     return [];
   }
-  const calls = bodyCalls(body);
+  const calls = withoutChainLinks(bodyCalls(body));
   if (calls.length === 0) {
     return [];
   }
@@ -17119,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 [];
@@ -17323,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") {
@@ -18068,7 +18176,26 @@ function buildRouterIndex(files, packs, resolverOptions) {
       }
     }
   }
+  const byFile = /* @__PURE__ */ new Map();
+  for (const file2 of files) {
+    byFile.set(file2.file, file2);
+  }
   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) {
@@ -18957,6 +19084,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.0",
+  "version": "0.5.2",
   "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.0",
-    "@suss/datalog": "0.5.0",
-    "@suss/extractor": "0.5.0",
+    "@suss/behavioral-ir": "0.5.2",
+    "@suss/datalog": "0.5.2",
+    "@suss/extractor": "0.5.2",
     "web-tree-sitter": "^0.26.11"
   },
   "devDependencies": {