@suss/adapter-python 0.21.1 → 0.22.0

package/dist/index.d.cts

@@ -2,7 +2,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 { Database } from '@suss/datalog';
-import { ExtractorOptions, RawCodeStructure } from '@suss/extractor';
+import { ExtractorOptions, RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
+import { WhyExplained } from '@suss/resolution';
 
 /**
  * A new `Parser` for every call, so that parses running at the same time do
@@ -10,6 +11,18 @@ import { ExtractorOptions, RawCodeStructure } from '@suss/extractor';
  * is loaded once per process and shared.
  */
 declare function parsePython(source: string): Promise<Tree>;
+/**
+ * Load the grammar ahead of time, for a caller whose own entry point is
+ * async but whose parsing happens later through `parsePythonSync`. Loading
+ * the WASM grammar is the only async part; parsing a tree from it is not.
+ */
+declare function preloadPythonGrammar(): Promise<void>;
+/**
+ * `parsePython` without the await, for a caller that cannot itself be
+ * async. Throws if `preloadPythonGrammar` (or `parsePython`) has not
+ * already loaded the grammar in this process.
+ */
+declare function parsePythonSync(source: string): Tree;
 
 /**
  * The lexical binder. It builds module, class, and function scopes over one
@@ -184,6 +197,22 @@ declare function classifyDecorator(decoratorNode: Node, scope: Scope): Decorator
  */
 interface PythonPack {
     name: string;
+    /**
+     * Pack version stamp, which feeds the cache invalidation key. Bump on
+     * any change that affects discovered units or extracted summaries.
+     * The CLI folds a hash of the loaded pack file and its config into
+     * this stamp on top, so a pack run through the CLI invalidates on an
+     * edit whether or not it declares a version of its own.
+     */
+    version?: string;
+    /**
+     * Files under the project this pack reads that are not among the
+     * `.py` files a run walks, given the files the run is about to walk.
+     * Their content feeds the same cache key the pack's own config does,
+     * so an edit to one of them re-extracts instead of handing back the
+     * previous answer.
+     */
+    discoveryInputs?: (files: readonly string[]) => string[];
     /** Wire protocol for the produced boundary bindings, e.g. "http". */
     protocol: string;
     discovery: PythonDiscoveryPattern[];
@@ -394,13 +423,16 @@ 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>;
-    readonly leadsToStorage: ReadonlySet<string>;
     /** What a pack says about statements a project writes as SQL itself. */
     readonly rawSql?: readonly RawSqlPattern[];
 }
@@ -554,6 +586,12 @@ declare function objectReturnedBy(db: Database, callKey: string): string | null;
  * call and its callee start at the same offset.
  */
 declare function nodeId(filePath: string, node: Node): string;
+/**
+ * The key a read of this expression joins on, for a caller that has an
+ * expression in hand and wants to ask the rules about it. `enclosing` is
+ * the function the expression is written in, or null at module level.
+ */
+declare function readKey(filePath: string, node: Node, enclosing: Node | null): 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
@@ -561,6 +599,59 @@ declare function nodeId(filePath: string, node: Node): string;
  */
 declare function emitValueFacts(db: Database, filePath: string, root: Node): void;
 
+/**
+ * The session behind `suss ask why` on a Python project: a tree-sitter
+ * parse of the asked-about source, a way to point at the expression
+ * somebody spelled, and the witness proof of what it resolved to,
+ * rendered through `@suss/resolution`'s phrases.
+ *
+ * It parses every file under the root and emits the same value facts
+ * `extractPythonProject` does, keeping a location for every fact key so
+ * a proof's atoms can point back at source. A handle this session hands
+ * back pairs a tree-sitter node with the file it came from, since a
+ * node alone does not say which file parsed it.
+ */
+
+interface PythonWhySessionOptions {
+    /** The project root, which paths in every answer come out relative to. */
+    dir: string;
+}
+/** A found node, paired with the file it was parsed from. */
+interface PythonValueHandle {
+    file: string;
+    node: Node;
+}
+declare class PythonWhySession {
+    private readonly root;
+    private readonly db;
+    private readonly locations;
+    private readonly trees;
+    constructor(options: PythonWhySessionOptions);
+    /**
+     * The smallest expression on `line` of `file` whose text is exactly
+     * `text`, or null.
+     */
+    findExpression(file: string, line: number, text: string): PythonValueHandle | null;
+    /**
+     * The callee of the call written as `calleeText` between `startLine`
+     * and `endLine` of `file`, or null.
+     */
+    findCallee(file: string, startLine: number, endLine: number, calleeText: string): PythonValueHandle | null;
+    /**
+     * Why `value` resolves to what it does: the witness proof, flattened
+     * to the chain and rendered. Null when the value does not resolve,
+     * which the caller says in its own words.
+     */
+    explain(value: PythonValueHandle, options?: {
+        maxDepth?: number;
+    }): WhyExplained | null;
+    private locate;
+    private rootOf;
+    private pathOf;
+    /** A file path said relative to the root, or as given when it is outside the root. */
+    private displayPath;
+}
+
 /**
  * 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
@@ -589,8 +680,18 @@ interface ExtractPythonOptions {
     roots: string[];
     /** When set, `location.file` on each summary is relativized against this. */
     workspaceRoot?: string;
+    /** The directory a summary's id measures its file from, when that differs from `workspaceRoot`. */
+    projectRoot?: string;
     /** As well as deciding how much of what nobody could read reaches a summary, "strict" lets a route that cannot be built stop the run. */
     gapHandling?: ExtractorOptions["gapHandling"];
+    /** Called once with the run's per-phase wall time, for `suss extract --timing`. */
+    onTiming?: (report: TimingReport) => void;
+    /** Called once with the file-by-file funnel, for `suss extract --explain`. */
+    onExtractionReport?: (report: ExtractionReport) => void;
+    /** Called once with what the cache decided, for `suss extract --timing`. */
+    onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
+    /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
+    cacheDir?: string | null;
 }
 interface ExtractPythonResult {
     summaries: BehavioralSummary[];
@@ -600,4 +701,48 @@ 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 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, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+/**
+ * Evidence for drafting a project-wrapper dependency stub: every
+ * import, anywhere in the project, of the asked module or one of its
+ * submodules. A Python decorator pattern matches a wrapper's import
+ * module exactly (see discovery.ts's `importModule.includes`), so a
+ * stub covers one imported module at a time rather than one package,
+ * and this groups by the exact module text a project writes.
+ *
+ * This walks every node rather than going through the binder in
+ * scope.ts, so an import inside an `if` or `try` still counts as
+ * evidence even though the binder would not resolve a name through it.
+ */
+interface PythonImportSite {
+    /** The name imported at this site, null for a bare `import module`, which binds the whole module rather than one name from it. */
+    name: string | null;
+    file: string;
+    line: number;
+}
+interface PythonImportEvidence {
+    /** The full dotted module text, exactly as a stub's `package` would spell it. */
+    module: string;
+    sites: PythonImportSite[];
+}
+interface PythonImportEvidenceOptions {
+    packageName: string;
+    directory: string;
+}
+/**
+ * Every import of `packageName`, or a submodule of it, across the
+ * project's own files, grouped by the exact module each was imported
+ * from.
+ */
+declare function pythonImportEvidence(options: PythonImportEvidenceOptions): Promise<PythonImportEvidence[]>;
+
+/**
+ * version.ts: this adapter's own half of the cache key.
+ *
+ * `ADAPTER_VERSION` is the hand-bumped semver. Bump it on any change
+ * that affects extraction output: IR shape, discovery semantics,
+ * terminal classification, anything that would invalidate previously
+ * cached summaries.
+ */
+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 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 };

package/dist/index.d.ts

@@ -2,7 +2,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 { Database } from '@suss/datalog';
-import { ExtractorOptions, RawCodeStructure } from '@suss/extractor';
+import { ExtractorOptions, RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
+import { WhyExplained } from '@suss/resolution';
 
 /**
  * A new `Parser` for every call, so that parses running at the same time do
@@ -10,6 +11,18 @@ import { ExtractorOptions, RawCodeStructure } from '@suss/extractor';
  * is loaded once per process and shared.
  */
 declare function parsePython(source: string): Promise<Tree>;
+/**
+ * Load the grammar ahead of time, for a caller whose own entry point is
+ * async but whose parsing happens later through `parsePythonSync`. Loading
+ * the WASM grammar is the only async part; parsing a tree from it is not.
+ */
+declare function preloadPythonGrammar(): Promise<void>;
+/**
+ * `parsePython` without the await, for a caller that cannot itself be
+ * async. Throws if `preloadPythonGrammar` (or `parsePython`) has not
+ * already loaded the grammar in this process.
+ */
+declare function parsePythonSync(source: string): Tree;
 
 /**
  * The lexical binder. It builds module, class, and function scopes over one
@@ -184,6 +197,22 @@ declare function classifyDecorator(decoratorNode: Node, scope: Scope): Decorator
  */
 interface PythonPack {
     name: string;
+    /**
+     * Pack version stamp, which feeds the cache invalidation key. Bump on
+     * any change that affects discovered units or extracted summaries.
+     * The CLI folds a hash of the loaded pack file and its config into
+     * this stamp on top, so a pack run through the CLI invalidates on an
+     * edit whether or not it declares a version of its own.
+     */
+    version?: string;
+    /**
+     * Files under the project this pack reads that are not among the
+     * `.py` files a run walks, given the files the run is about to walk.
+     * Their content feeds the same cache key the pack's own config does,
+     * so an edit to one of them re-extracts instead of handing back the
+     * previous answer.
+     */
+    discoveryInputs?: (files: readonly string[]) => string[];
     /** Wire protocol for the produced boundary bindings, e.g. "http". */
     protocol: string;
     discovery: PythonDiscoveryPattern[];
@@ -394,13 +423,16 @@ 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>;
-    readonly leadsToStorage: ReadonlySet<string>;
     /** What a pack says about statements a project writes as SQL itself. */
     readonly rawSql?: readonly RawSqlPattern[];
 }
@@ -554,6 +586,12 @@ declare function objectReturnedBy(db: Database, callKey: string): string | null;
  * call and its callee start at the same offset.
  */
 declare function nodeId(filePath: string, node: Node): string;
+/**
+ * The key a read of this expression joins on, for a caller that has an
+ * expression in hand and wants to ask the rules about it. `enclosing` is
+ * the function the expression is written in, or null at module level.
+ */
+declare function readKey(filePath: string, node: Node, enclosing: Node | null): 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
@@ -561,6 +599,59 @@ declare function nodeId(filePath: string, node: Node): string;
  */
 declare function emitValueFacts(db: Database, filePath: string, root: Node): void;
 
+/**
+ * The session behind `suss ask why` on a Python project: a tree-sitter
+ * parse of the asked-about source, a way to point at the expression
+ * somebody spelled, and the witness proof of what it resolved to,
+ * rendered through `@suss/resolution`'s phrases.
+ *
+ * It parses every file under the root and emits the same value facts
+ * `extractPythonProject` does, keeping a location for every fact key so
+ * a proof's atoms can point back at source. A handle this session hands
+ * back pairs a tree-sitter node with the file it came from, since a
+ * node alone does not say which file parsed it.
+ */
+
+interface PythonWhySessionOptions {
+    /** The project root, which paths in every answer come out relative to. */
+    dir: string;
+}
+/** A found node, paired with the file it was parsed from. */
+interface PythonValueHandle {
+    file: string;
+    node: Node;
+}
+declare class PythonWhySession {
+    private readonly root;
+    private readonly db;
+    private readonly locations;
+    private readonly trees;
+    constructor(options: PythonWhySessionOptions);
+    /**
+     * The smallest expression on `line` of `file` whose text is exactly
+     * `text`, or null.
+     */
+    findExpression(file: string, line: number, text: string): PythonValueHandle | null;
+    /**
+     * The callee of the call written as `calleeText` between `startLine`
+     * and `endLine` of `file`, or null.
+     */
+    findCallee(file: string, startLine: number, endLine: number, calleeText: string): PythonValueHandle | null;
+    /**
+     * Why `value` resolves to what it does: the witness proof, flattened
+     * to the chain and rendered. Null when the value does not resolve,
+     * which the caller says in its own words.
+     */
+    explain(value: PythonValueHandle, options?: {
+        maxDepth?: number;
+    }): WhyExplained | null;
+    private locate;
+    private rootOf;
+    private pathOf;
+    /** A file path said relative to the root, or as given when it is outside the root. */
+    private displayPath;
+}
+
 /**
  * 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
@@ -589,8 +680,18 @@ interface ExtractPythonOptions {
     roots: string[];
     /** When set, `location.file` on each summary is relativized against this. */
     workspaceRoot?: string;
+    /** The directory a summary's id measures its file from, when that differs from `workspaceRoot`. */
+    projectRoot?: string;
     /** As well as deciding how much of what nobody could read reaches a summary, "strict" lets a route that cannot be built stop the run. */
     gapHandling?: ExtractorOptions["gapHandling"];
+    /** Called once with the run's per-phase wall time, for `suss extract --timing`. */
+    onTiming?: (report: TimingReport) => void;
+    /** Called once with the file-by-file funnel, for `suss extract --explain`. */
+    onExtractionReport?: (report: ExtractionReport) => void;
+    /** Called once with what the cache decided, for `suss extract --timing`. */
+    onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
+    /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
+    cacheDir?: string | null;
 }
 interface ExtractPythonResult {
     summaries: BehavioralSummary[];
@@ -600,4 +701,48 @@ 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 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, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+/**
+ * Evidence for drafting a project-wrapper dependency stub: every
+ * import, anywhere in the project, of the asked module or one of its
+ * submodules. A Python decorator pattern matches a wrapper's import
+ * module exactly (see discovery.ts's `importModule.includes`), so a
+ * stub covers one imported module at a time rather than one package,
+ * and this groups by the exact module text a project writes.
+ *
+ * This walks every node rather than going through the binder in
+ * scope.ts, so an import inside an `if` or `try` still counts as
+ * evidence even though the binder would not resolve a name through it.
+ */
+interface PythonImportSite {
+    /** The name imported at this site, null for a bare `import module`, which binds the whole module rather than one name from it. */
+    name: string | null;
+    file: string;
+    line: number;
+}
+interface PythonImportEvidence {
+    /** The full dotted module text, exactly as a stub's `package` would spell it. */
+    module: string;
+    sites: PythonImportSite[];
+}
+interface PythonImportEvidenceOptions {
+    packageName: string;
+    directory: string;
+}
+/**
+ * Every import of `packageName`, or a submodule of it, across the
+ * project's own files, grouped by the exact module each was imported
+ * from.
+ */
+declare function pythonImportEvidence(options: PythonImportEvidenceOptions): Promise<PythonImportEvidence[]>;
+
+/**
+ * version.ts: this adapter's own half of the cache key.
+ *
+ * `ADAPTER_VERSION` is the hand-bumped semver. Bump it on any change
+ * that affects extraction output: IR shape, discovery semantics,
+ * terminal classification, anything that would invalidate previously
+ * cached summaries.
+ */
+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 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 };