@suss/adapter-python 0.28.0 → 0.29.0

package/dist/index.cjs

@@ -1905,12 +1905,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)) {
@@ -7646,6 +7653,31 @@ 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)
+        ]);
+      }
+    }
+  }
+}
 async function extractPythonProject(options) {
   const timer = options.onTiming !== void 0 ? (0, import_extractor10.createTimer)() : (0, import_extractor10.noopTimer)();
   const cacheDir = adapterStamp.declineWhenRunFromSource(
@@ -7693,8 +7725,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 +7740,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,38 @@ 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[];
+}
+/** `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 +1076,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,38 @@ 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[];
+}
+/** `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 +1076,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

@@ -1857,12 +1857,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)) {
@@ -7658,6 +7665,31 @@ 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)
+        ]);
+      }
+    }
+  }
+}
 async function extractPythonProject(options) {
   const timer = options.onTiming !== void 0 ? createTimer() : noopTimer();
   const cacheDir = adapterStamp.declineWhenRunFromSource(
@@ -7705,8 +7737,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 +7752,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.29.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.29.0",
+    "@suss/datalog": "0.29.0",
+    "@suss/extractor": "0.29.0",
+    "@suss/ir-core": "0.29.0",
+    "@suss/resolution": "0.29.0",
+    "@suss/sql": "0.29.0",
+    "@suss/values": "0.29.0",
     "web-tree-sitter": "^0.26.11"
   },
   "devDependencies": {