@suss/adapter-python 0.25.0 → 0.27.0

package/dist/index.d.cts

@@ -25,167 +25,43 @@ declare function preloadPythonGrammar(): Promise<void>;
 declare function parsePythonSync(source: string): Tree;
 
 /**
- * The lexical binder. It builds module, class, and function scopes over one
- * file's parse tree and records how each name in each scope came to be bound,
- * whether that was an import, an assignment, a def, a parameter, or a `global`
- * or `nonlocal` redirect to another scope.
+ * Maps a dotted import onto the file in the repo it refers to.
  *
- * It never has to be complete, because "I could not resolve this name" is a
- * legal answer everywhere a name is read. What it has to avoid is being wrong.
- * So it only binds names written directly in a body's own statement list. A
- * definition or import nested inside an `if`, `try`, or `with` block is not
- * found, and a read of it comes back unresolved rather than as a guess.
- */
-
-type ScopeKind = "module" | "class" | "function";
-interface Scope {
-    kind: ScopeKind;
-    /** The module node, or the class_definition / function_definition this scope belongs to. */
-    node: Node;
-    parent: Scope | null;
-    bindings: Map<string, Binding>;
-}
-/**
- * `relativeLevel` is 0 for an absolute import and the dot count for a
- * relative one. `module` is the dotted path after the dots, empty for
- * a bare `from . import c`.
+ * The search walks a small set of configured roots. Finding out what `sys.path`
+ * actually is would mean running Python, so when more than one root offers a
+ * candidate, the resolver abstains rather than picking one.
  */
-type Binding = {
-    kind: "import";
-    module: string;
-    relativeLevel: number;
-    localName: string;
-} | {
-    kind: "importFrom";
+interface RelativeModuleSpec {
+    /** The dotted path after the leading dots. It is empty for a bare `from . import x`. */
     module: string;
+    /** Dot count: 0 means absolute, 1 is `.`, 2 is `..`, and so on. */
     relativeLevel: number;
-    importedName: string;
-} | {
-    kind: "classDef";
-    node: Node;
-} | {
-    kind: "functionDef";
-    node: Node;
-} | {
-    kind: "parameter";
-}
-/** The right-hand side, when there is one, so we can trace a decorator's base object one hop back to whatever constructed it. */
- | {
-    kind: "assignment";
-    value: Node | null;
-}
-/** `global x` inside a function: reads of `x` in this scope resolve in the module scope instead. */
- | {
-    kind: "global";
-}
-/** `nonlocal x` inside a function: reads of `x` resolve in the nearest enclosing function scope. */
- | {
-    kind: "nonlocal";
-};
-interface ModuleBinding {
-    moduleScope: Scope;
-    /** The scope a class_definition, a function_definition, or the module node opens, keyed by that node's id. */
-    scopeFor: Map<number, Scope>;
-    /** The modules a `from X import *` pulls in. We cannot list what a wildcard brings in, so nothing expands them here. */
-    openImports: string[];
-}
-declare function bindModule(root: Node): ModuleBinding;
-/**
- * Python does not put a class body's namespace on the lookup chain of a function
- * nested inside it, so a class scope's own bindings only count when the search
- * starts there. A `global` or `nonlocal` marker sends the lookup to the scope it
- * points at.
- */
-declare function resolveName(scope: Scope, name: string): Binding | null;
-
-/**
- * Turns a Python annotation into an IR type shape.
- *
- * Nothing here infers anything. A value nobody annotated has no shape at all,
- * and an annotation this module does not recognize comes back as a `ref` by
- * name, which says only what the source called it.
- */
-
-/**
- * `definitions` stores each converted class shape once, however many annotations
- * mention it. `scopeFor` is here so a name written inside a referenced class's
- * body resolves too, not only one written at the annotation's use site.
- */
-interface AnnotationContext {
-    scopeFor: Map<number, Scope>;
-    definitions: Map<string, TypeShape | null>;
-}
-/** `scope` is where the annotation is written, which is how we tell a project-local class from an external name. */
-declare function annotationToShape(typeNode: Node, scope: Scope, ctx: AnnotationContext): TypeShape;
-/** Exported so a decorator keyword that gives a class name reads the same way as that name written in annotation position. */
-declare function shapeFromName(name: string, scope: Scope, ctx: AnnotationContext): TypeShape;
-
-interface Range {
-    start: number;
-    end: number;
 }
-
-/** An argument as written, plus its node so a reader can evaluate what it comes down to. */
-type DecoratorArg = DecoratorArgShape & {
-    readonly node: Node;
-};
-type DecoratorArgShape = {
-    kind: "string";
-    value: string;
-} | {
-    kind: "number";
-    value: number;
-} | {
-    kind: "boolean";
-    value: boolean;
-} | {
-    kind: "none";
-}
-/** A bare name. The caller resolves it, using the scope it already has. */
- | {
-    kind: "identifier";
-    name: string;
-}
-/** One dotted hop, `routers.orders`. The caller decides what the object is. */
- | {
-    kind: "attribute";
-    objectName: string;
-    attributeName: string;
-} | {
-    kind: "list";
-    items: DecoratorArg[];
+type ModuleResolution = {
+    status: "resolved";
+    file: string;
 } | {
-    kind: "other";
-};
-interface DecoratorClassification {
-    /** The name as its source module exports it, not the local alias or attribute path it was written under. */
-    importedName: string | null;
-    /** The dotted module the name was imported from. It is null whenever `importedName` is null. */
-    module: string | null;
-    /** The local variable an attribute decorator hangs on, `app` in `@app.get(...)`. */
-    objectName: string | null;
-    relativeLevel: number;
-    args: DecoratorArg[];
-    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;
+    status: "unresolved";
     /**
-     * The call the rules say built the object this decorator hangs on, when
-     * the lexical scope could not say. A router prefix is looked up by this
-     * call rather than by a variable name, because there may not be one.
+     * "external": no configured root has a file for it. "ambiguous": more
+     * than one does. "outsideRoots": a relative import had enough dots to walk
+     * up past every configured root.
      */
-    subjectConstruction?: {
-        key: string;
-        constructorName: string;
-    };
+    reason: "external" | "ambiguous" | "outsideRoots";
+};
+interface ModuleResolverOptions {
+    /** The directories an absolute dotted import is resolved against. We cannot see `sys.path` order, since that only exists at runtime. */
+    roots: string[];
 }
-declare function classifyDecorator(decoratorNode: Node, scope: Scope): DecoratorClassification;
+declare function resolveAbsoluteModule(dotted: string, options: ModuleResolverOptions): ModuleResolution;
+/**
+ * The search starts in the importing file's own directory, because Python
+ * resolves a relative import against `__package__` and not against `sys.path`.
+ * `options.roots` only limits how far the dots can walk up, so a deeply relative
+ * import cannot land in an unrelated checkout.
+ */
+declare function resolveRelativeModule(importingFile: string, spec: RelativeModuleSpec, options: ModuleResolverOptions): ModuleResolution;
+declare function resolveModule(importingFile: string, spec: RelativeModuleSpec, options: ModuleResolverOptions): ModuleResolution;
 
 /**
  * The Python adapter's own pattern-pack contract.
@@ -312,7 +188,7 @@ interface PyClientCall {
     };
     /** Constructors whose instances take the same calls, `Session`. */
     receiverConstructors?: string[];
-    /** What the response object gives a caller, so a guard on it reads as a guard on a status. */
+    /** What the response object gives a caller, so a guard on one of its members counts as a guard on a status. */
     response?: PyClientResponse;
 }
 /**
@@ -355,7 +231,7 @@ interface RouteConventions {
     defaultStatusCode?: number;
     /**
      * Set it only when the library reads a status out of the tuple a handler
-     * returns, which is what Flask does with `return body, 201`. Without it
+     * returns, as Flask does with `return body, 201`. Without it
      * the library default applies whatever the body returns, and a route
      * that sets its own status would be reported at the default.
      */
@@ -375,7 +251,7 @@ interface RouteConventions {
      * own status; a return of anything else keeps the declared one.
      */
     responseConstructors?: PyStatusCall[];
-    /** Unset means the library has no router mounting, and a route's decorator path stands as written. */
+    /** Unset means the library has no router mounting, and a route's decorator path is used as written. */
     routerComposition?: RouterComposition;
     /** The ways the library runs a project's own function around a route. The README lists what each one covers. */
     wrappers?: PyWrapperForm[];
@@ -431,7 +307,7 @@ interface PyDecoratedWrapperForm {
     continuationParam?: number;
     /**
      * Set when a value returned ends the request and only a bare return
-     * hands on, which is what Flask does with `before_request`.
+     * hands on. Flask's `before_request` works this way.
      */
     returnedValueResponds?: boolean;
     /** The position the library hands the raised exception at. Set on an error handler, which runs only when the handler raised. */
@@ -576,57 +452,78 @@ type NoValuePrefix = "unstated" | "unreadable";
 type PathRepeatedSlashes = "kept" | "merged";
 
 /**
- * What discovery uses for one file. `factsPath` is the path the facts were
- * keyed under, which is the absolute one, while a summary shows the short one.
+ * The lexical binder. It builds module, class, and function scopes over one
+ * file's parse tree and records how each name in each scope came to be bound,
+ * whether that was an import, an assignment, a def, a parameter, or a `global`
+ * or `nonlocal` redirect to another scope.
+ *
+ * It never has to be complete, because "I could not resolve this name" is a
+ * legal answer everywhere a name is read. What it has to avoid is being wrong.
+ * So it only binds names written directly in a body's own statement list. A
+ * definition or import nested inside an `if`, `try`, or `with` block is not
+ * found, and a read of it comes back unresolved rather than as a guess.
  */
-interface StorageLookup {
-    readonly facts: Database;
-    readonly factsPath: string;
-    readonly patterns: readonly StoragePattern[];
-    readonly definitionAt: (key: string) => Node | undefined;
-    readonly couldMatch: ReadonlySet<string>;
-    /** What a pack says about statements a project writes as SQL itself. */
-    readonly rawSql?: readonly RawSqlPattern[];
-}
 
+type ScopeKind = "module" | "class" | "function";
+interface Scope {
+    kind: ScopeKind;
+    /** The module node, or the class_definition / function_definition this scope belongs to. */
+    node: Node;
+    parent: Scope | null;
+    bindings: Map<string, Binding>;
+}
 /**
- * Maps a dotted import onto the file in the repo it refers to.
- *
- * The search walks a small set of configured roots. Finding out what `sys.path`
- * actually is would mean running Python, so when more than one root offers a
- * candidate, the resolver abstains rather than picking one.
+ * `relativeLevel` is 0 for an absolute import and the dot count for a
+ * relative one. `module` is the dotted path after the dots, empty for
+ * a bare `from . import c`.
  */
-interface RelativeModuleSpec {
-    /** The dotted path after the leading dots. It is empty for a bare `from . import x`. */
+type Binding = {
+    kind: "import";
     module: string;
-    /** Dot count: 0 means absolute, 1 is `.`, 2 is `..`, and so on. */
     relativeLevel: number;
-}
-type ModuleResolution = {
-    status: "resolved";
-    file: string;
+    localName: string;
 } | {
-    status: "unresolved";
-    /**
-     * "external": no configured root has a file for it. "ambiguous": more
-     * than one does. "outsideRoots": a relative import had enough dots to walk
-     * up past every configured root.
-     */
-    reason: "external" | "ambiguous" | "outsideRoots";
+    kind: "importFrom";
+    module: string;
+    relativeLevel: number;
+    importedName: string;
+} | {
+    kind: "classDef";
+    node: Node;
+} | {
+    kind: "functionDef";
+    node: Node;
+} | {
+    kind: "parameter";
+}
+/** The right-hand side, when there is one, so we can trace a decorator's base object one hop back to whatever constructed it. */
+ | {
+    kind: "assignment";
+    value: Node | null;
+}
+/** `global x` inside a function: reads of `x` in this scope resolve in the module scope instead. */
+ | {
+    kind: "global";
+}
+/** `nonlocal x` inside a function: reads of `x` resolve in the nearest enclosing function scope. */
+ | {
+    kind: "nonlocal";
 };
-interface ModuleResolverOptions {
-    /** The directories an absolute dotted import is resolved against. We cannot see `sys.path` order, since that only exists at runtime. */
-    roots: string[];
+interface ModuleBinding {
+    moduleScope: Scope;
+    /** The scope a class_definition, a function_definition, or the module node opens, keyed by that node's id. */
+    scopeFor: Map<number, Scope>;
+    /** The modules a `from X import *` pulls in. We cannot list what a wildcard brings in, so nothing expands them here. */
+    openImports: string[];
 }
-declare function resolveAbsoluteModule(dotted: string, options: ModuleResolverOptions): ModuleResolution;
+declare function bindModule(root: Node): ModuleBinding;
 /**
- * The search starts in the importing file's own directory, because Python
- * resolves a relative import against `__package__` and not against `sys.path`.
- * `options.roots` only limits how far the dots can walk up, so a deeply relative
- * import cannot land in an unrelated checkout.
+ * Python does not put a class body's namespace on the lookup chain of a function
+ * nested inside it, so a class scope's own bindings only count when the search
+ * starts there. A `global` or `nonlocal` marker sends the lookup to the scope it
+ * points at.
  */
-declare function resolveRelativeModule(importingFile: string, spec: RelativeModuleSpec, options: ModuleResolverOptions): ModuleResolution;
-declare function resolveModule(importingFile: string, spec: RelativeModuleSpec, options: ModuleResolverOptions): ModuleResolution;
+declare function resolveName(scope: Scope, name: string): Binding | null;
 
 /** One file, already parsed and bound. `buildRouterIndex` takes a project as a list of these. */
 interface BoundPythonFile {
@@ -688,6 +585,137 @@ interface RouterIndexOptions extends ModuleResolverOptions {
 }
 declare function buildRouterIndex(files: BoundPythonFile[], packs: PythonPack[], resolverOptions: RouterIndexOptions): RouterIndex;
 
+/**
+ * Where an imported name is defined, when the project defines it.
+ *
+ * The binder resolves a name inside one file only, so `item_in: ItemCreate`
+ * with `ItemCreate` imported from a models module comes back as an import
+ * binding and nothing more. This asks the resolution rules where the name
+ * came from, through any re-exports on the way, and returns the class or
+ * the assigned value the defining file binds it to, along with that file's
+ * scopes so the definition can be read in the scope it is written in.
+ */
+
+interface ImportedDefinition {
+    /** The class_definition, or the value an assignment gave the name. */
+    node: Node;
+    /** The module scope of the file the definition is written in. */
+    moduleScope: Scope;
+    /** The scopes of that file, keyed by the node that opens each one. */
+    scopeFor: Map<number, Scope>;
+}
+/** `scope` is where the name is read, which is what keys the import in the facts. */
+type ImportedDefinitionLookup = (scope: Scope, name: string) => ImportedDefinition | null;
+
+/**
+ * Turns a Python annotation into an IR type shape.
+ *
+ * Nothing here infers anything. A value nobody annotated has no shape at all,
+ * and an annotation this module does not recognize comes back as a `ref` by
+ * name, which says only what the source called it.
+ */
+
+/**
+ * `definitions` stores each converted class shape once, however many annotations
+ * mention it. `scopeMaps` is here so a name written inside a referenced class's
+ * body resolves too, not only one written at the annotation's use site; a class
+ * read from another file brings that file's scopes along. `importedDefinition`
+ * is absent when a caller reads one file on its own, and an imported name is
+ * then a ref by name and nothing more.
+ */
+interface AnnotationContext {
+    scopeMaps: Map<number, Scope>[];
+    definitions: Map<string, TypeShape | null>;
+    importedDefinition: ImportedDefinitionLookup | null;
+    /** The alias values being expanded, so `A = B` and `B = A` end rather than recurse. */
+    expanding: Set<number>;
+}
+/** `scope` is where the annotation is written, which is how we tell a project-local class from an external name. */
+declare function annotationToShape(typeNode: Node, scope: Scope, ctx: AnnotationContext): TypeShape;
+/** Exported so a decorator keyword that gives a class name reads the same way as that name written in annotation position. */
+declare function shapeFromName(name: string, scope: Scope, ctx: AnnotationContext): TypeShape;
+
+interface Range {
+    start: number;
+    end: number;
+}
+
+/** An argument as written, plus its node so a reader can evaluate what it comes down to. */
+type DecoratorArg = DecoratorArgShape & {
+    readonly node: Node;
+};
+type DecoratorArgShape = {
+    kind: "string";
+    value: string;
+} | {
+    kind: "number";
+    value: number;
+} | {
+    kind: "boolean";
+    value: boolean;
+} | {
+    kind: "none";
+}
+/** A bare name. The caller resolves it, using the scope it already has. */
+ | {
+    kind: "identifier";
+    name: string;
+}
+/** One dotted hop, `routers.orders`. The caller decides what the object is. */
+ | {
+    kind: "attribute";
+    objectName: string;
+    attributeName: string;
+} | {
+    kind: "list";
+    items: DecoratorArg[];
+} | {
+    kind: "other";
+};
+interface DecoratorClassification {
+    /** The name as its source module exports it, not the local alias or attribute path it was written under. */
+    importedName: string | null;
+    /** The dotted module the name was imported from. It is null whenever `importedName` is null. */
+    module: string | null;
+    /** The local variable an attribute decorator hangs on, `app` in `@app.get(...)`. */
+    objectName: string | null;
+    relativeLevel: number;
+    args: DecoratorArg[];
+    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;
+    /**
+     * The call the rules say built the object this decorator hangs on, when
+     * the lexical scope could not say. A router prefix is looked up by this
+     * call rather than by a variable name, because there may not be one.
+     */
+    subjectConstruction?: {
+        key: string;
+        constructorName: string;
+    };
+}
+declare function classifyDecorator(decoratorNode: Node, scope: Scope): DecoratorClassification;
+
+/**
+ * What discovery uses for one file. `factsPath` is the path the facts were
+ * keyed under, which is the absolute one, while a summary shows the short one.
+ */
+interface StorageLookup {
+    readonly facts: Database;
+    readonly factsPath: string;
+    readonly patterns: readonly StoragePattern[];
+    readonly definitionAt: (key: string) => Node | undefined;
+    readonly couldMatch: ReadonlySet<string>;
+    /** What a pack says about statements a project writes as SQL itself. */
+    readonly rawSql?: readonly RawSqlPattern[];
+}
+
 /**
  * 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
@@ -810,6 +838,8 @@ interface DiscoveryOptions {
     facts?: Database | undefined;
     /** What the project registered around its routes. Absent when no pack declares a wrapper form, or when a caller reads one file on its own. */
     wrappers?: PythonWrapperIndex | undefined;
+    /** Where a name another file defines is written, so an imported model or alias reads as the class or value behind it. Absent when a caller reads one file on its own. */
+    importedDefinition?: ImportedDefinitionLookup | undefined;
 }
 declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];