@suss/adapter-python 0.26.0 → 0.28.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.
@@ -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 {
@@ -689,12 +586,146 @@ interface RouterIndexOptions extends ModuleResolverOptions {
 declare function buildRouterIndex(files: BoundPythonFile[], packs: PythonPack[], resolverOptions: RouterIndexOptions): RouterIndex;
 
 /**
- * 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.
+ * 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: 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. */
@@ -726,6 +757,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. */
@@ -759,6 +792,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;
@@ -810,14 +845,12 @@ 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[];
 
-/**
- * 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
@@ -827,6 +860,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.
@@ -838,6 +884,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
@@ -991,4 +1042,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 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 };