@suss/adapter-python 0.3.2-0 → 0.4.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as PyNode, Tree as PyTree } from 'web-tree-sitter';
-import { ExtractorOptions, RawCodeStructure } from '@suss/extractor';
 import { Database } from '@suss/datalog';
+import { ExtractorOptions, RawCodeStructure } from '@suss/extractor';
 
 /**
  * A new `Parser` for every call, so that parses running at the same time do
@@ -107,15 +107,6 @@ declare function annotationToShape(typeNode: Node, scope: Scope, ctx: Annotation
 /** 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;
 
-/**
- * Small helpers for reading a tree-sitter-python parse tree.
- *
- * The node-type strings here come from tree-sitter-python's grammar, at the
- * version the grammar README gives. Read a node through these helpers rather
- * than calling `childForFieldName` or `.type` inline, so that a grammar upgrade
- * that renames a field only has to be fixed in one place.
- */
-
 interface Range {
     start: number;
     end: number;
@@ -175,6 +166,24 @@ interface PythonPack {
     /** Wire protocol for the produced boundary bindings, e.g. "http". */
     protocol: string;
     discovery: PythonDiscoveryPattern[];
+    /** What the library's own database queries look like. The README says how one is matched. */
+    storage?: StoragePattern[];
+}
+/**
+ * A call talks to the database when the method behind it says it returns one
+ * of the library's query types. Matching on the return rather than on the
+ * import is what reads a project base class that wraps the library, which is
+ * how the measured corpus writes every one of its queries.
+ */
+interface StoragePattern {
+    /** The module a query type is imported from, `sqlalchemy.orm` for a Session. */
+    module: string;
+    /** Type names that mean the value is a query against the database. */
+    queryTypes: string[];
+    /** Chain-ending methods that change what is stored. Anything else reads. */
+    writes: string[];
+    /** Which database the library is talking to, for the boundary binding. */
+    storageSystem: "postgres" | "mysql" | "sqlite";
 }
 type PythonDiscoveryPattern = DecoratedClassRoute | DecoratedFunctionRoute;
 /** Conventions both kinds of route share. Each one describes what the library does, never a project's choice. */
@@ -327,6 +336,18 @@ 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.
+ */
+interface StorageLookup {
+    readonly facts: Database;
+    readonly factsPath: string;
+    readonly patterns: readonly StoragePattern[];
+    readonly definitionAt: (key: string) => Node | undefined;
+    readonly couldMatch: ReadonlySet<string>;
+}
+
 /**
  * Maps a dotted import onto the file in the repo it refers to.
  *
@@ -394,7 +415,11 @@ type RoutePrefixResolution = {
 interface RouterIndex {
     resolve(pattern: PythonDiscoveryPattern, module: ModuleBinding, objectName: string): RoutePrefixResolution;
 }
-declare function buildRouterIndex(files: BoundPythonFile[], packs: PythonPack[], resolverOptions: ModuleResolverOptions): RouterIndex;
+interface RouterIndexOptions extends ModuleResolverOptions {
+    /** The project's facts, so a loop over a call can be settled by the rules. */
+    facts?: Database;
+}
+declare function buildRouterIndex(files: BoundPythonFile[], packs: PythonPack[], resolverOptions: RouterIndexOptions): RouterIndex;
 
 /**
  * Finds decorated routes and turns each one into a `RawCodeStructure`.
@@ -418,9 +443,37 @@ interface DiscoveryOptions {
     routerIndex?: RouterIndex;
     /** Under "strict" a route whose unit cannot be built stops the run instead of abstaining. */
     gapHandling?: ExtractorOptions["gapHandling"];
+    /** What a pack needs to say a call talks to the database. Absent when no pack does. */
+    storage?: StorageLookup | 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.
+ */
+declare function resolveCalls(db: Database, callKeys: readonly string[]): void;
+/**
+ * The values an object contains under its own keys, in the order the source
+ * writes them. Empty when nothing said what the object contains.
+ */
+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;
+
+/**
+ * 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.
+ */
+declare function nodeId(filePath: string, node: Node): 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
+ * them.
+ */
+declare function emitValueFacts(db: Database, filePath: string, root: Node): void;
+
 /**
  * The name is part of the key because the range is measured in lines, two
  * units can start on the same line, and `entry` is a set, so keying on the range
@@ -434,7 +487,11 @@ declare function emitEntryFact(db: Database, filePath: string, range: {
     start: number;
     end: number;
 }, name: string): void;
-/** Module scope only. A function- or class-scoped import is not recorded. */
+/**
+ * Every import in the file, wherever it is written. Python code puts an import
+ * inside a function to break a cycle between two modules, and a chain through
+ * one of those functions stops dead without it.
+ */
 declare function emitModuleImportFacts(db: Database, filePath: string, module: ModuleBinding, resolverOptions: ModuleResolverOptions): void;
 
 interface ExtractPythonOptions {
@@ -456,4 +513,4 @@ declare function extractPythonProject(options: ExtractPythonOptions): Promise<Ex
 /** Every `.py` file under `root`, depth-first, skipping the usual non-source directories. */
 declare function findPythonFiles(root: string): string[];
 
-export { 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 PythonDiscoveryPattern, type PythonPack, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, discoverUnits, emitEntryFact, emitModuleImportFacts, extractPythonProject, findPythonFiles, parsePython, resolveAbsoluteModule, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+export { 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 PythonDiscoveryPattern, type PythonPack, 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, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as PyNode, Tree as PyTree } from 'web-tree-sitter';
-import { ExtractorOptions, RawCodeStructure } from '@suss/extractor';
 import { Database } from '@suss/datalog';
+import { ExtractorOptions, RawCodeStructure } from '@suss/extractor';
 
 /**
  * A new `Parser` for every call, so that parses running at the same time do
@@ -107,15 +107,6 @@ declare function annotationToShape(typeNode: Node, scope: Scope, ctx: Annotation
 /** 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;
 
-/**
- * Small helpers for reading a tree-sitter-python parse tree.
- *
- * The node-type strings here come from tree-sitter-python's grammar, at the
- * version the grammar README gives. Read a node through these helpers rather
- * than calling `childForFieldName` or `.type` inline, so that a grammar upgrade
- * that renames a field only has to be fixed in one place.
- */
-
 interface Range {
     start: number;
     end: number;
@@ -175,6 +166,24 @@ interface PythonPack {
     /** Wire protocol for the produced boundary bindings, e.g. "http". */
     protocol: string;
     discovery: PythonDiscoveryPattern[];
+    /** What the library's own database queries look like. The README says how one is matched. */
+    storage?: StoragePattern[];
+}
+/**
+ * A call talks to the database when the method behind it says it returns one
+ * of the library's query types. Matching on the return rather than on the
+ * import is what reads a project base class that wraps the library, which is
+ * how the measured corpus writes every one of its queries.
+ */
+interface StoragePattern {
+    /** The module a query type is imported from, `sqlalchemy.orm` for a Session. */
+    module: string;
+    /** Type names that mean the value is a query against the database. */
+    queryTypes: string[];
+    /** Chain-ending methods that change what is stored. Anything else reads. */
+    writes: string[];
+    /** Which database the library is talking to, for the boundary binding. */
+    storageSystem: "postgres" | "mysql" | "sqlite";
 }
 type PythonDiscoveryPattern = DecoratedClassRoute | DecoratedFunctionRoute;
 /** Conventions both kinds of route share. Each one describes what the library does, never a project's choice. */
@@ -327,6 +336,18 @@ 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.
+ */
+interface StorageLookup {
+    readonly facts: Database;
+    readonly factsPath: string;
+    readonly patterns: readonly StoragePattern[];
+    readonly definitionAt: (key: string) => Node | undefined;
+    readonly couldMatch: ReadonlySet<string>;
+}
+
 /**
  * Maps a dotted import onto the file in the repo it refers to.
  *
@@ -394,7 +415,11 @@ type RoutePrefixResolution = {
 interface RouterIndex {
     resolve(pattern: PythonDiscoveryPattern, module: ModuleBinding, objectName: string): RoutePrefixResolution;
 }
-declare function buildRouterIndex(files: BoundPythonFile[], packs: PythonPack[], resolverOptions: ModuleResolverOptions): RouterIndex;
+interface RouterIndexOptions extends ModuleResolverOptions {
+    /** The project's facts, so a loop over a call can be settled by the rules. */
+    facts?: Database;
+}
+declare function buildRouterIndex(files: BoundPythonFile[], packs: PythonPack[], resolverOptions: RouterIndexOptions): RouterIndex;
 
 /**
  * Finds decorated routes and turns each one into a `RawCodeStructure`.
@@ -418,9 +443,37 @@ interface DiscoveryOptions {
     routerIndex?: RouterIndex;
     /** Under "strict" a route whose unit cannot be built stops the run instead of abstaining. */
     gapHandling?: ExtractorOptions["gapHandling"];
+    /** What a pack needs to say a call talks to the database. Absent when no pack does. */
+    storage?: StorageLookup | 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.
+ */
+declare function resolveCalls(db: Database, callKeys: readonly string[]): void;
+/**
+ * The values an object contains under its own keys, in the order the source
+ * writes them. Empty when nothing said what the object contains.
+ */
+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;
+
+/**
+ * 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.
+ */
+declare function nodeId(filePath: string, node: Node): 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
+ * them.
+ */
+declare function emitValueFacts(db: Database, filePath: string, root: Node): void;
+
 /**
  * The name is part of the key because the range is measured in lines, two
  * units can start on the same line, and `entry` is a set, so keying on the range
@@ -434,7 +487,11 @@ declare function emitEntryFact(db: Database, filePath: string, range: {
     start: number;
     end: number;
 }, name: string): void;
-/** Module scope only. A function- or class-scoped import is not recorded. */
+/**
+ * Every import in the file, wherever it is written. Python code puts an import
+ * inside a function to break a cycle between two modules, and a chain through
+ * one of those functions stops dead without it.
+ */
 declare function emitModuleImportFacts(db: Database, filePath: string, module: ModuleBinding, resolverOptions: ModuleResolverOptions): void;
 
 interface ExtractPythonOptions {
@@ -456,4 +513,4 @@ declare function extractPythonProject(options: ExtractPythonOptions): Promise<Ex
 /** Every `.py` file under `root`, depth-first, skipping the usual non-source directories. */
 declare function findPythonFiles(root: string): string[];
 
-export { 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 PythonDiscoveryPattern, type PythonPack, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, discoverUnits, emitEntryFact, emitModuleImportFacts, extractPythonProject, findPythonFiles, parsePython, resolveAbsoluteModule, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+export { 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 PythonDiscoveryPattern, type PythonPack, 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, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };