@suss/adapter-python 0.27.0 → 0.28.0

package/dist/index.d.cts

@@ -717,12 +717,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 +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. */
@@ -787,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;
@@ -843,11 +850,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 +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.
@@ -868,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
@@ -1021,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 };

package/dist/index.d.ts

@@ -717,12 +717,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 +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. */
@@ -787,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;
@@ -843,11 +850,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 +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.
@@ -868,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
@@ -1021,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 };