@suss/adapter-python 0.28.0 → 0.30.0

package/dist/index.cjs

@@ -1887,6 +1887,79 @@ function assignedValue(right) {
   const first = fields(right, "subscript")[0];
   return outer?.text === "Annotated" && first !== void 0 ? first : right;
 }
+function sideBesidesNone(node) {
+  const left = field(node, "left");
+  const right = field(node, "right");
+  if (right?.type === "none") {
+    return left;
+  }
+  if (left?.type === "none") {
+    return right;
+  }
+  return null;
+}
+function annotatedClass(node) {
+  if (node === void 0) {
+    return null;
+  }
+  if (node.type === "identifier" || node.type === "string") {
+    return node;
+  }
+  if (node.type === "type") {
+    return annotatedClass(children(node)[0]);
+  }
+  if (node.type === "generic_type") {
+    const parameter = children(node).find(
+      (child) => child.type === "type_parameter"
+    );
+    return annotatedClass(
+      parameter === void 0 ? void 0 : children(parameter)[0]
+    );
+  }
+  if (node.type === "binary_operator") {
+    return annotatedClass(sideBesidesNone(node) ?? void 0);
+  }
+  return null;
+}
+function classReferenceKey(emitter, node) {
+  if (node.type === "identifier") {
+    return valueKey(emitter, node);
+  }
+  const written = stringLiteralValue(node);
+  if (written === null) {
+    return null;
+  }
+  return nameKey(emitter.filePath, emitter.enclosing, written);
+}
+function firstPositional(call) {
+  const args = field(call, "arguments");
+  for (const argument of args === null ? [] : children(args)) {
+    if (argument.type !== "keyword_argument") {
+      return argument;
+    }
+  }
+  return null;
+}
+function fieldClassKey(emitter, assignment2, call) {
+  const annotation = field(assignment2, "type");
+  const annotated = annotation === null ? null : annotatedClass(annotation);
+  if (annotated !== null) {
+    return classReferenceKey(emitter, annotated);
+  }
+  const first = firstPositional(call);
+  return first === null ? null : classReferenceKey(emitter, first);
+}
+function emitFieldCall(emitter, classKey, name, assignment2, value) {
+  if (value.type !== "call") {
+    return;
+  }
+  const callee = field(value, "function");
+  const target = callee === null ? null : fieldClassKey(emitter, assignment2, value);
+  if (callee === null || target === null) {
+    return;
+  }
+  add(emitter, "fieldCall", classKey, name, valueKey(emitter, callee), target);
+}
 function declaredBy(statement) {
   if (statement.type === "decorated_definition") {
     return field(statement, "definition") ?? statement;
@@ -1905,12 +1978,19 @@ function declaredMemberKey(emitter, member, classKey) {
   }
   return null;
 }
+function writtenBaseName(base) {
+  return base.type === "identifier" || base.type === "attribute" ? base.text : null;
+}
 function emitClassFacts(emitter, cls) {
   const classKey = nodeId(emitter.filePath, cls);
   add(emitter, "objectValue", classKey);
   const bases = field(cls, "superclasses");
   for (const base of bases === null ? [] : children(bases)) {
     add(emitter, "extends", classKey, valueKey(emitter, base));
+    const written = writtenBaseName(base);
+    if (written !== null) {
+      add(emitter, "extendsNamed", classKey, written);
+    }
   }
   const body = field(cls, "body");
   for (const statement of body === null ? [] : children(body)) {
@@ -1926,6 +2006,7 @@ function emitClassFacts(emitter, cls) {
           left.text,
           valueKey(emitter, right)
         );
+        emitFieldCall(emitter, classKey, left.text, member, right);
       }
       continue;
     }
@@ -5356,7 +5437,12 @@ function matchedChains(calls, options) {
     }
     const pattern = resolvedMethodPattern(options, callee);
     if (pattern !== void 0) {
-      matched.push({ chain, pattern, operation: chain.operation });
+      const returnedOnly = chain.last === chain.root;
+      matched.push({
+        chain,
+        pattern,
+        operation: returnedOnly ? null : chain.operation
+      });
     }
   }
   return matched;
@@ -7646,6 +7732,37 @@ function reportUnresolvedProjectModules(options, db) {
     }
   }
 }
+function emitModelQueryFacts(db, packs) {
+  for (const pack of packs) {
+    for (const model of pack.models ?? []) {
+      for (const base of model.baseNames) {
+        for (const method of model.givesBack) {
+          db.add("givesBackOne", [base, method]);
+        }
+        for (const entry of model.entryMethods) {
+          db.add("givesBackOneOfArgument", [
+            base,
+            entry.method,
+            String(entry.argument)
+          ]);
+        }
+      }
+      for (const entry of model.entryFunctions) {
+        db.add("givesBackOneOfImport", [
+          entry.module,
+          entry.name,
+          String(entry.argument)
+        ]);
+      }
+      for (const relationship of model.relationships ?? []) {
+        db.add("associationConstructor", [
+          relationship.module,
+          relationship.name
+        ]);
+      }
+    }
+  }
+}
 async function extractPythonProject(options) {
   const timer = options.onTiming !== void 0 ? (0, import_extractor10.createTimer)() : (0, import_extractor10.noopTimer)();
   const cacheDir = adapterStamp.declineWhenRunFromSource(
@@ -7693,8 +7810,9 @@ async function extractPythonProject(options) {
   );
   const storagePatterns = options.packs.flatMap((pack) => pack.storage ?? []);
   const rawSqlPatterns = options.packs.flatMap((pack) => pack.rawSql ?? []);
+  const modelQueries = options.packs.flatMap((pack) => pack.models ?? []);
   const discovers = options.packs.some((pack) => pack.discovery.length > 0);
-  const needsValues = discovers || mountsRouters || storagePatterns.length > 0;
+  const needsValues = discovers || mountsRouters || storagePatterns.length > 0 || modelQueries.length > 0;
   const definitions = /* @__PURE__ */ new Map();
   timer.time("discover", () => {
     for (const { file, root, module: moduleBinding } of bound) {
@@ -7707,6 +7825,7 @@ async function extractPythonProject(options) {
     if (needsValues) {
       bindEvaluator(db, { files: bound, definitions });
     }
+    emitModelQueryFacts(db, options.packs);
   });
   reportUnresolvedProjectModules(options, db);
   const couldMatch = timer.time(

package/dist/index.d.cts

@@ -109,6 +109,8 @@ interface PythonPack {
     clients?: PyClientCall[];
     /** What the library's own database queries look like. The README says how one is matched. */
     storage?: StoragePattern[];
+    /** Which of the library's calls give back one of a model class. The README says what a chain of them composes into. */
+    models?: PyModelQueries[];
     /** How the library lets a project hand the database SQL it wrote itself. */
     rawSql?: RawSqlPattern[];
 }
@@ -148,6 +150,52 @@ interface StoragePattern {
     /** Which database the library is talking to, for the boundary binding. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
+/**
+ * What a library gives back when a call is passed one of a project's
+ * model classes, so a method read off the result runs the one that
+ * class declares. SQLAlchemy and SQLModel take the class as an argument,
+ * `session.get(User, id)` and `select(User)`, rather than as the
+ * receiver a Rails finder is called on.
+ */
+interface PyModelQueries {
+    /**
+     * The names a model's ancestry arrives at: a base class the library
+     * exports, `DeclarativeBase`, or the function that builds one,
+     * `declarative_base`.
+     */
+    baseNames: string[];
+    /** Methods whose result is the model again: one row, or a query a later read narrows to one. */
+    givesBack: string[];
+    /** Methods that take the model class and give back one of it, with the position it is written at. */
+    entryMethods: PyModelEntryMethod[];
+    /** Functions the library exports that do the same, called on their own rather than read off a session. */
+    entryFunctions: PyModelEntryFunction[];
+    /** The library's own constructors for a field that reaches another model. */
+    relationships?: PyRelationshipConstructor[];
+}
+/**
+ * `items: list[Item] = Relationship(...)`: the callable a model's field
+ * is given to say it reaches another model, and where it comes from. A
+ * project function spelled the same way is somebody else's, so the
+ * import is what settles a match.
+ */
+interface PyRelationshipConstructor {
+    /** The module it is imported from, `sqlmodel` or `sqlalchemy.orm`. */
+    module: string;
+    /** Its name, `Relationship` or `relationship`. */
+    name: string;
+}
+/** `session.get(User, id)`: the method, and where the class is written. */
+interface PyModelEntryMethod {
+    method: string;
+    argument: number;
+}
+/** `select(User)`: the function, the module it comes from, and where the class is written. */
+interface PyModelEntryFunction {
+    module: string;
+    name: string;
+    argument: number;
+}
 /**
  * The function a library gives a project for handing the database a
  * statement written as SQL, and where it comes from. SQLAlchemy exports
@@ -1042,4 +1090,4 @@ declare function pythonImportEvidence(options: PythonImportEvidenceOptions): Pro
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };

package/dist/index.d.ts

@@ -109,6 +109,8 @@ interface PythonPack {
     clients?: PyClientCall[];
     /** What the library's own database queries look like. The README says how one is matched. */
     storage?: StoragePattern[];
+    /** Which of the library's calls give back one of a model class. The README says what a chain of them composes into. */
+    models?: PyModelQueries[];
     /** How the library lets a project hand the database SQL it wrote itself. */
     rawSql?: RawSqlPattern[];
 }
@@ -148,6 +150,52 @@ interface StoragePattern {
     /** Which database the library is talking to, for the boundary binding. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
+/**
+ * What a library gives back when a call is passed one of a project's
+ * model classes, so a method read off the result runs the one that
+ * class declares. SQLAlchemy and SQLModel take the class as an argument,
+ * `session.get(User, id)` and `select(User)`, rather than as the
+ * receiver a Rails finder is called on.
+ */
+interface PyModelQueries {
+    /**
+     * The names a model's ancestry arrives at: a base class the library
+     * exports, `DeclarativeBase`, or the function that builds one,
+     * `declarative_base`.
+     */
+    baseNames: string[];
+    /** Methods whose result is the model again: one row, or a query a later read narrows to one. */
+    givesBack: string[];
+    /** Methods that take the model class and give back one of it, with the position it is written at. */
+    entryMethods: PyModelEntryMethod[];
+    /** Functions the library exports that do the same, called on their own rather than read off a session. */
+    entryFunctions: PyModelEntryFunction[];
+    /** The library's own constructors for a field that reaches another model. */
+    relationships?: PyRelationshipConstructor[];
+}
+/**
+ * `items: list[Item] = Relationship(...)`: the callable a model's field
+ * is given to say it reaches another model, and where it comes from. A
+ * project function spelled the same way is somebody else's, so the
+ * import is what settles a match.
+ */
+interface PyRelationshipConstructor {
+    /** The module it is imported from, `sqlmodel` or `sqlalchemy.orm`. */
+    module: string;
+    /** Its name, `Relationship` or `relationship`. */
+    name: string;
+}
+/** `session.get(User, id)`: the method, and where the class is written. */
+interface PyModelEntryMethod {
+    method: string;
+    argument: number;
+}
+/** `select(User)`: the function, the module it comes from, and where the class is written. */
+interface PyModelEntryFunction {
+    module: string;
+    name: string;
+    argument: number;
+}
 /**
  * The function a library gives a project for handing the database a
  * statement written as SQL, and where it comes from. SQLAlchemy exports
@@ -1042,4 +1090,4 @@ declare function pythonImportEvidence(options: PythonImportEvidenceOptions): Pro
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };

package/dist/index.js

@@ -1839,6 +1839,79 @@ function assignedValue(right) {
   const first = fields(right, "subscript")[0];
   return outer?.text === "Annotated" && first !== void 0 ? first : right;
 }
+function sideBesidesNone(node) {
+  const left = field(node, "left");
+  const right = field(node, "right");
+  if (right?.type === "none") {
+    return left;
+  }
+  if (left?.type === "none") {
+    return right;
+  }
+  return null;
+}
+function annotatedClass(node) {
+  if (node === void 0) {
+    return null;
+  }
+  if (node.type === "identifier" || node.type === "string") {
+    return node;
+  }
+  if (node.type === "type") {
+    return annotatedClass(children(node)[0]);
+  }
+  if (node.type === "generic_type") {
+    const parameter = children(node).find(
+      (child) => child.type === "type_parameter"
+    );
+    return annotatedClass(
+      parameter === void 0 ? void 0 : children(parameter)[0]
+    );
+  }
+  if (node.type === "binary_operator") {
+    return annotatedClass(sideBesidesNone(node) ?? void 0);
+  }
+  return null;
+}
+function classReferenceKey(emitter, node) {
+  if (node.type === "identifier") {
+    return valueKey(emitter, node);
+  }
+  const written = stringLiteralValue(node);
+  if (written === null) {
+    return null;
+  }
+  return nameKey(emitter.filePath, emitter.enclosing, written);
+}
+function firstPositional(call) {
+  const args = field(call, "arguments");
+  for (const argument of args === null ? [] : children(args)) {
+    if (argument.type !== "keyword_argument") {
+      return argument;
+    }
+  }
+  return null;
+}
+function fieldClassKey(emitter, assignment2, call) {
+  const annotation = field(assignment2, "type");
+  const annotated = annotation === null ? null : annotatedClass(annotation);
+  if (annotated !== null) {
+    return classReferenceKey(emitter, annotated);
+  }
+  const first = firstPositional(call);
+  return first === null ? null : classReferenceKey(emitter, first);
+}
+function emitFieldCall(emitter, classKey, name, assignment2, value) {
+  if (value.type !== "call") {
+    return;
+  }
+  const callee = field(value, "function");
+  const target = callee === null ? null : fieldClassKey(emitter, assignment2, value);
+  if (callee === null || target === null) {
+    return;
+  }
+  add(emitter, "fieldCall", classKey, name, valueKey(emitter, callee), target);
+}
 function declaredBy(statement) {
   if (statement.type === "decorated_definition") {
     return field(statement, "definition") ?? statement;
@@ -1857,12 +1930,19 @@ function declaredMemberKey(emitter, member, classKey) {
   }
   return null;
 }
+function writtenBaseName(base) {
+  return base.type === "identifier" || base.type === "attribute" ? base.text : null;
+}
 function emitClassFacts(emitter, cls) {
   const classKey = nodeId(emitter.filePath, cls);
   add(emitter, "objectValue", classKey);
   const bases = field(cls, "superclasses");
   for (const base of bases === null ? [] : children(bases)) {
     add(emitter, "extends", classKey, valueKey(emitter, base));
+    const written = writtenBaseName(base);
+    if (written !== null) {
+      add(emitter, "extendsNamed", classKey, written);
+    }
   }
   const body = field(cls, "body");
   for (const statement of body === null ? [] : children(body)) {
@@ -1878,6 +1958,7 @@ function emitClassFacts(emitter, cls) {
           left.text,
           valueKey(emitter, right)
         );
+        emitFieldCall(emitter, classKey, left.text, member, right);
       }
       continue;
     }
@@ -5329,7 +5410,12 @@ function matchedChains(calls, options) {
     }
     const pattern = resolvedMethodPattern(options, callee);
     if (pattern !== void 0) {
-      matched.push({ chain, pattern, operation: chain.operation });
+      const returnedOnly = chain.last === chain.root;
+      matched.push({
+        chain,
+        pattern,
+        operation: returnedOnly ? null : chain.operation
+      });
     }
   }
   return matched;
@@ -7658,6 +7744,37 @@ function reportUnresolvedProjectModules(options, db) {
     }
   }
 }
+function emitModelQueryFacts(db, packs) {
+  for (const pack of packs) {
+    for (const model of pack.models ?? []) {
+      for (const base of model.baseNames) {
+        for (const method of model.givesBack) {
+          db.add("givesBackOne", [base, method]);
+        }
+        for (const entry of model.entryMethods) {
+          db.add("givesBackOneOfArgument", [
+            base,
+            entry.method,
+            String(entry.argument)
+          ]);
+        }
+      }
+      for (const entry of model.entryFunctions) {
+        db.add("givesBackOneOfImport", [
+          entry.module,
+          entry.name,
+          String(entry.argument)
+        ]);
+      }
+      for (const relationship of model.relationships ?? []) {
+        db.add("associationConstructor", [
+          relationship.module,
+          relationship.name
+        ]);
+      }
+    }
+  }
+}
 async function extractPythonProject(options) {
   const timer = options.onTiming !== void 0 ? createTimer() : noopTimer();
   const cacheDir = adapterStamp.declineWhenRunFromSource(
@@ -7705,8 +7822,9 @@ async function extractPythonProject(options) {
   );
   const storagePatterns = options.packs.flatMap((pack) => pack.storage ?? []);
   const rawSqlPatterns = options.packs.flatMap((pack) => pack.rawSql ?? []);
+  const modelQueries = options.packs.flatMap((pack) => pack.models ?? []);
   const discovers = options.packs.some((pack) => pack.discovery.length > 0);
-  const needsValues = discovers || mountsRouters || storagePatterns.length > 0;
+  const needsValues = discovers || mountsRouters || storagePatterns.length > 0 || modelQueries.length > 0;
   const definitions = /* @__PURE__ */ new Map();
   timer.time("discover", () => {
     for (const { file, root, module: moduleBinding } of bound) {
@@ -7719,6 +7837,7 @@ async function extractPythonProject(options) {
     if (needsValues) {
       bindEvaluator(db, { files: bound, definitions });
     }
+    emitModelQueryFacts(db, options.packs);
   });
   reportUnresolvedProjectModules(options, db);
   const couldMatch = timer.time(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/adapter-python",
-  "version": "0.28.0",
+  "version": "0.30.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.28.0",
-    "@suss/datalog": "0.28.0",
-    "@suss/extractor": "0.28.0",
-    "@suss/ir-core": "0.28.0",
-    "@suss/resolution": "0.28.0",
-    "@suss/sql": "0.28.0",
-    "@suss/values": "0.28.0",
+    "@suss/behavioral-ir": "0.30.0",
+    "@suss/datalog": "0.30.0",
+    "@suss/extractor": "0.30.0",
+    "@suss/ir-core": "0.30.0",
+    "@suss/resolution": "0.30.0",
+    "@suss/sql": "0.30.0",
+    "@suss/values": "0.30.0",
     "web-tree-sitter": "^0.26.11"
   },
   "devDependencies": {