@suss/adapter-python 0.27.0 → 0.29.0

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
@@ -717,12 +751,15 @@ interface StorageLookup {
 }
 
 /**
- * What a call's callee is, read through the binder and the import
- * facts: a function in this run the walk can step into, or a reason it
- * cannot. A name is followed only through a binding that says where it
- * came from, so a name that could be two definitions is a stop rather
- * than a guess. The package README lists the spellings that are
- * followed and the ones that stop.
+ * What a call's callee is: a function in this run the walk can step
+ * into, or a reason it cannot.
+ *
+ * The rules in @suss/resolution decide it. Every language feature that
+ * moves a value is a hop they already state, so nothing here reads a
+ * name, an alias, an attribute, or an instance for itself.
+ *
+ * What is left is about files rather than values: a module before the
+ * dot, and a name only a wildcard import could have brought in.
  */
 
 /** A function in this run, and the export path its summary gets. */
@@ -754,6 +791,8 @@ interface WrapperIndexOptions {
     packs: readonly PythonPack[];
     roots: string[];
     facts: Database | undefined;
+    /** The function each function key was read from. */
+    definitions: ReadonlyMap<string, Node>;
     storageFor: (file: BoundPythonFile) => StorageLookup | undefined;
 }
 /** The route asking which wrappers reach it: the decorator it was found by, and where that decorator was read. */
@@ -787,6 +826,8 @@ declare class PythonWrapperIndex {
     private readonly unitsByKey;
     private readonly unitsByFile;
     constructor(options: WrapperIndexOptions, filesByPath: ReadonlyMap<string, BoundPythonFile>);
+    /** The project function a module-level name in this file refers to, or null for anything else. */
+    functionCalled(file: string, name: string): ReachedFunction | null;
     register(covers: {
         kind: "everyRoute";
         pack: string;
@@ -843,11 +884,7 @@ interface DiscoveryOptions {
 }
 declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];
 
-/**
- * Ask what these calls come down to, then derive. Asking about every call in
- * a project costs seconds on a large one and answers questions nobody has,
- * so a caller names the handful it needs.
- */
+/** Ask what these calls come down to, then derive. */
 declare function resolveCalls(db: Database, callKeys: readonly string[]): void;
 /**
  * The values an object contains under its own keys, in the order the source
@@ -857,6 +894,19 @@ declare function containedValues(db: Database, objectKey: string): string[];
 /** What a call comes down to, when the rules settled it on an object. */
 declare function objectReturnedBy(db: Database, callKey: string): string | null;
 
+/**
+ * values.ts: the facts @suss/resolution already joins, emitted for Python.
+ * The relation names and shapes come from that package's own header, so a
+ * Python value follows the same rules a TypeScript one does.
+ *
+ * A name is keyed by the scope that binds it. A function's own names take
+ * the function's key, so two handlers that both write `query` stay apart,
+ * and a module's names take the file's key, which is what another file
+ * imports back out. Every write to a name in one scope is collected in
+ * source order and `valueLeftByWrites` says what the name comes down to,
+ * so a reassigned name states one value or none rather than two.
+ */
+
 /**
  * A node's identity across the whole run. The end is part of it because a
  * call and its callee start at the same offset.
@@ -868,6 +918,11 @@ declare function nodeId(filePath: string, node: Node): string;
  * the function the expression is written in, or null at module level.
  */
 declare function readKey(filePath: string, node: Node, enclosing: Node | null): string;
+/**
+ * The key a name joins on, for a caller holding the name as text and the
+ * function it is written in.
+ */
+declare function nameKeyIn(filePath: string, enclosing: Node | null, name: string): string;
 /**
  * Walk a module and emit the value facts. A nested function is walked in its
  * own right, so a body's returns and calls belong to the function that wrote
@@ -1021,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, 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
@@ -717,12 +751,15 @@ interface StorageLookup {
 }
 
 /**
- * What a call's callee is, read through the binder and the import
- * facts: a function in this run the walk can step into, or a reason it
- * cannot. A name is followed only through a binding that says where it
- * came from, so a name that could be two definitions is a stop rather
- * than a guess. The package README lists the spellings that are
- * followed and the ones that stop.
+ * What a call's callee is: a function in this run the walk can step
+ * into, or a reason it cannot.
+ *
+ * The rules in @suss/resolution decide it. Every language feature that
+ * moves a value is a hop they already state, so nothing here reads a
+ * name, an alias, an attribute, or an instance for itself.
+ *
+ * What is left is about files rather than values: a module before the
+ * dot, and a name only a wildcard import could have brought in.
  */
 
 /** A function in this run, and the export path its summary gets. */
@@ -754,6 +791,8 @@ interface WrapperIndexOptions {
     packs: readonly PythonPack[];
     roots: string[];
     facts: Database | undefined;
+    /** The function each function key was read from. */
+    definitions: ReadonlyMap<string, Node>;
     storageFor: (file: BoundPythonFile) => StorageLookup | undefined;
 }
 /** The route asking which wrappers reach it: the decorator it was found by, and where that decorator was read. */
@@ -787,6 +826,8 @@ declare class PythonWrapperIndex {
     private readonly unitsByKey;
     private readonly unitsByFile;
     constructor(options: WrapperIndexOptions, filesByPath: ReadonlyMap<string, BoundPythonFile>);
+    /** The project function a module-level name in this file refers to, or null for anything else. */
+    functionCalled(file: string, name: string): ReachedFunction | null;
     register(covers: {
         kind: "everyRoute";
         pack: string;
@@ -843,11 +884,7 @@ interface DiscoveryOptions {
 }
 declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];
 
-/**
- * Ask what these calls come down to, then derive. Asking about every call in
- * a project costs seconds on a large one and answers questions nobody has,
- * so a caller names the handful it needs.
- */
+/** Ask what these calls come down to, then derive. */
 declare function resolveCalls(db: Database, callKeys: readonly string[]): void;
 /**
  * The values an object contains under its own keys, in the order the source
@@ -857,6 +894,19 @@ declare function containedValues(db: Database, objectKey: string): string[];
 /** What a call comes down to, when the rules settled it on an object. */
 declare function objectReturnedBy(db: Database, callKey: string): string | null;
 
+/**
+ * values.ts: the facts @suss/resolution already joins, emitted for Python.
+ * The relation names and shapes come from that package's own header, so a
+ * Python value follows the same rules a TypeScript one does.
+ *
+ * A name is keyed by the scope that binds it. A function's own names take
+ * the function's key, so two handlers that both write `query` stay apart,
+ * and a module's names take the file's key, which is what another file
+ * imports back out. Every write to a name in one scope is collected in
+ * source order and `valueLeftByWrites` says what the name comes down to,
+ * so a reassigned name states one value or none rather than two.
+ */
+
 /**
  * A node's identity across the whole run. The end is part of it because a
  * call and its callee start at the same offset.
@@ -868,6 +918,11 @@ declare function nodeId(filePath: string, node: Node): string;
  * the function the expression is written in, or null at module level.
  */
 declare function readKey(filePath: string, node: Node, enclosing: Node | null): string;
+/**
+ * The key a name joins on, for a caller holding the name as text and the
+ * function it is written in.
+ */
+declare function nameKeyIn(filePath: string, enclosing: Node | null, name: string): string;
 /**
  * Walk a module and emit the value facts. A nested function is walked in its
  * own right, so a body's returns and calls belong to the function that wrote
@@ -1021,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, 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 };