@suss/adapter-python 0.22.4 → 0.24.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
+import { TypeShape, WrapperReference, 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, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
+import { RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
 
 /**
@@ -229,6 +229,8 @@ interface PythonPack {
      * and never says why (#188).
      */
     projectModules?: string[];
+    /** The callables the library gives a project for making a request. */
+    clients?: PyClientCall[];
     /** What the library's own database queries look like. The README says how one is matched. */
     storage?: StoragePattern[];
     /** How the library lets a project hand the database SQL it wrote itself. */
@@ -285,6 +287,49 @@ interface RawSqlPattern {
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
 type PythonDiscoveryPattern = DecoratedClassRoute | DecoratedFunctionRoute;
+/**
+ * The callables a library gives a project for making a request. A
+ * function that calls one of them is a client of the boundary that call
+ * states, and gets a unit bound to its method and path.
+ */
+interface PyClientCall {
+    type: "clientCall";
+    /** The module the callables come from, `requests`. */
+    importModule: string[];
+    /** Attribute names that state the method themselves: `get` means GET. */
+    verbAttributeNames: Record<string, string>;
+    /** Where a call whose name states the method states its URL. */
+    url: {
+        position: number;
+        keyword: string;
+    };
+    /** A call that takes the method as an argument instead, `request("GET", url)`. */
+    methodCall?: {
+        attribute: string;
+        methodPosition: number;
+        methodKeyword?: string;
+        urlPosition: number;
+    };
+    /** 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. */
+    response?: PyClientResponse;
+}
+/**
+ * The members a library's response object gives a caller. A caller that
+ * tests one of them is saying which statuses it handles, and the
+ * checker compares that against what the other side produces.
+ */
+interface PyClientResponse {
+    /** Members whose value is the status code: `status_code`. */
+    statusCode?: string[];
+    /** Members that say the request succeeded, meaning a status in 200 to 299: `ok`. */
+    success?: string[];
+    /** Members that give the body: `json`, `text`, `content`. */
+    body?: string[];
+    /** Whether a refused request comes back as a response or raises where it was made. */
+    failureDelivery?: "response" | "exception";
+}
 /** Conventions both kinds of route share. Each one describes what the library does, never a project's choice. */
 interface RouteConventions {
     /** How the library spells a path parameter. The README lists the syntaxes we know how to read. */
@@ -323,8 +368,74 @@ interface RouteConventions {
      * and one it does cover comes out as the response the library sends.
      */
     responseStatusCalls?: PyStatusCall[];
+    /**
+     * The library's own classes whose instance, when a body returns it, is
+     * the response the library sends, and where each takes the status:
+     * Starlette's `JSONResponse(status_code=...)`. A return of one says its
+     * 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. */
     routerComposition?: RouterComposition;
+    /** The ways the library runs a project's own function around a route. The README lists what each one covers. */
+    wrappers?: PyWrapperForm[];
+}
+type PyWrapperForm = PyDependencyForm | PyDecoratedWrapperForm;
+/** Where a wrapper is registered, and which routes the registration reaches. */
+interface PyWrapperRegistrar {
+    /** The constructor of the object the registration is written on, as the library exports it: `FastAPI`, `APIRouter`. */
+    constructorName: string;
+    /** Where the constructor is imported from, when that is not the pattern's own `importModule`: `flask` for the app a flask-restx API is served by. */
+    importModule?: string[];
+    /**
+     * `everyRoute` for the app, whose registration reaches every route of
+     * the pack in the run. `ownRoutes` for a router or a blueprint, whose
+     * registration reaches the routes decorated on that same object.
+     */
+    covers: "everyRoute" | "ownRoutes";
+}
+/**
+ * The library calls a project function before the handler, given as an
+ * argument to one of its own callables: FastAPI's `Depends(get_user)`.
+ * One may be written as a parameter default or inside `Annotated[...]`
+ * on the route, or in a list under `keyword` on the route decorator or
+ * on one of the registrars. The function runs before the handler and
+ * ends the request by raising, so it is a wrapper whose every return
+ * hands on.
+ */
+interface PyDependencyForm {
+    type: "dependency";
+    /** The callables that take the function: `Depends`, `Security`. */
+    callees: string[];
+    /** The keyword a list of them is written under: `dependencies`. */
+    keyword: string;
+    registrars: PyWrapperRegistrar[];
+}
+/**
+ * A project function decorated with a method on the app or a router:
+ * `@app.middleware("http")`, `@app.exception_handler(ValueError)`,
+ * `@app.before_request`. What the decorated function's returns mean
+ * depends on which of the three fields below is set; with none set,
+ * every return hands the request on.
+ */
+interface PyDecoratedWrapperForm {
+    type: "decoratedWrapper";
+    /** The decorator's attribute name on the registrar: `middleware`. */
+    attribute: string;
+    registrars: PyWrapperRegistrar[];
+    /**
+     * The position of the parameter the wrapper calls to run what it
+     * wraps, `call_next` at 1 for Starlette middleware. A return before
+     * that call ends the request with what is returned.
+     */
+    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`.
+     */
+    returnedValueResponds?: boolean;
+    /** The position the library hands the raised exception at. Set on an error handler, which runs only when the handler raised. */
+    throwParam?: number;
 }
 /**
  * One callable that ends the request, and where it takes the status.
@@ -577,6 +688,98 @@ 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.
+ */
+
+/** A function in this run, and the export path its summary gets. */
+interface ReachedFunction {
+    readonly file: BoundPythonFile;
+    /** The `function_definition` node. */
+    readonly node: Node;
+    readonly name: string;
+    /** `[name]` for a module function, `[Class, name]` for a method. */
+    readonly exportPath: string[];
+}
+
+/**
+ * The project functions a library runs around a route, read from where
+ * they are registered: a dependency on a route's parameter or decorator,
+ * a dependency list on the app or a router, a function decorated with
+ * `@app.middleware(...)` or `@app.exception_handler(...)`. Each one
+ * becomes a unit of its own, and every route it reaches lists it, so the
+ * extractor can fold its outcomes into the route's. The README says which
+ * registrations are read and which are not.
+ *
+ * A registration on the app reaches every route of the pack in the run,
+ * since an app is one per run for every pack that has one. A registration
+ * on a router reaches the routes decorated on that same router object,
+ * and nothing mounted onto it.
+ */
+
+interface WrapperIndexOptions {
+    packs: readonly PythonPack[];
+    roots: string[];
+    facts: Database | undefined;
+    storageFor: (file: BoundPythonFile) => StorageLookup | undefined;
+}
+/** The route asking which wrappers reach it: the decorator it was found by, and where that decorator was read. */
+interface RouteWrapperQuery {
+    pack: PythonPack;
+    pattern: PythonDiscoveryPattern;
+    /** The absolute path of the file the route is written in. */
+    file: string;
+    module: ModuleBinding;
+    classification: DecoratorClassification;
+    definitionNode: Node;
+}
+/** A wrapper the index has a unit for, and the form it was registered through. */
+interface Registered {
+    reference: WrapperReference;
+    form: PyWrapperForm;
+}
+interface FormOf {
+    pack: PythonPack;
+    pattern: PythonDiscoveryPattern;
+    form: PyWrapperForm;
+}
+/** What every registration in the run reaches, asked once per route and then once per file for the wrapper units. */
+declare class PythonWrapperIndex {
+    readonly options: WrapperIndexOptions;
+    readonly filesByPath: ReadonlyMap<string, BoundPythonFile>;
+    /** By pack name: what the app registered, in the order the forms are declared and then the order the files were read. */
+    private readonly everyRoute;
+    /** By construction key: what a router or a blueprint registered. */
+    private readonly ownRoutes;
+    private readonly unitsByKey;
+    private readonly unitsByFile;
+    constructor(options: WrapperIndexOptions, filesByPath: ReadonlyMap<string, BoundPythonFile>);
+    register(covers: {
+        kind: "everyRoute";
+        pack: string;
+    } | {
+        kind: "ownRoutes";
+        key: string;
+    }, target: ReachedFunction, declared: FormOf): void;
+    /** The unit for a function, built once however many registrations point at it. */
+    registered(target: ReachedFunction, declared: FormOf): Registered;
+    wrappersFor(query: RouteWrapperQuery): WrapperReference[];
+    private ownRoutesOf;
+    /**
+     * Where the decorator's object was built: the route's own file, the file
+     * a project wrapper function is written in, or the file an imported
+     * router comes from. The name is the one that file binds it under.
+     */
+    private objectSiteOf;
+    private fileOfModule;
+    unitsIn(file: string): RawCodeStructure[];
+}
+
 /**
  * Finds decorated routes and turns each one into a `RawCodeStructure`.
  *
@@ -605,6 +808,8 @@ interface DiscoveryOptions {
     absoluteFile?: string | undefined;
     /** The project's facts, so the rules can say what an object no scope has a binding for was built by. */
     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;
 }
 declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];
 

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
+import { TypeShape, WrapperReference, 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, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
+import { RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
 
 /**
@@ -229,6 +229,8 @@ interface PythonPack {
      * and never says why (#188).
      */
     projectModules?: string[];
+    /** The callables the library gives a project for making a request. */
+    clients?: PyClientCall[];
     /** What the library's own database queries look like. The README says how one is matched. */
     storage?: StoragePattern[];
     /** How the library lets a project hand the database SQL it wrote itself. */
@@ -285,6 +287,49 @@ interface RawSqlPattern {
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
 type PythonDiscoveryPattern = DecoratedClassRoute | DecoratedFunctionRoute;
+/**
+ * The callables a library gives a project for making a request. A
+ * function that calls one of them is a client of the boundary that call
+ * states, and gets a unit bound to its method and path.
+ */
+interface PyClientCall {
+    type: "clientCall";
+    /** The module the callables come from, `requests`. */
+    importModule: string[];
+    /** Attribute names that state the method themselves: `get` means GET. */
+    verbAttributeNames: Record<string, string>;
+    /** Where a call whose name states the method states its URL. */
+    url: {
+        position: number;
+        keyword: string;
+    };
+    /** A call that takes the method as an argument instead, `request("GET", url)`. */
+    methodCall?: {
+        attribute: string;
+        methodPosition: number;
+        methodKeyword?: string;
+        urlPosition: number;
+    };
+    /** 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. */
+    response?: PyClientResponse;
+}
+/**
+ * The members a library's response object gives a caller. A caller that
+ * tests one of them is saying which statuses it handles, and the
+ * checker compares that against what the other side produces.
+ */
+interface PyClientResponse {
+    /** Members whose value is the status code: `status_code`. */
+    statusCode?: string[];
+    /** Members that say the request succeeded, meaning a status in 200 to 299: `ok`. */
+    success?: string[];
+    /** Members that give the body: `json`, `text`, `content`. */
+    body?: string[];
+    /** Whether a refused request comes back as a response or raises where it was made. */
+    failureDelivery?: "response" | "exception";
+}
 /** Conventions both kinds of route share. Each one describes what the library does, never a project's choice. */
 interface RouteConventions {
     /** How the library spells a path parameter. The README lists the syntaxes we know how to read. */
@@ -323,8 +368,74 @@ interface RouteConventions {
      * and one it does cover comes out as the response the library sends.
      */
     responseStatusCalls?: PyStatusCall[];
+    /**
+     * The library's own classes whose instance, when a body returns it, is
+     * the response the library sends, and where each takes the status:
+     * Starlette's `JSONResponse(status_code=...)`. A return of one says its
+     * 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. */
     routerComposition?: RouterComposition;
+    /** The ways the library runs a project's own function around a route. The README lists what each one covers. */
+    wrappers?: PyWrapperForm[];
+}
+type PyWrapperForm = PyDependencyForm | PyDecoratedWrapperForm;
+/** Where a wrapper is registered, and which routes the registration reaches. */
+interface PyWrapperRegistrar {
+    /** The constructor of the object the registration is written on, as the library exports it: `FastAPI`, `APIRouter`. */
+    constructorName: string;
+    /** Where the constructor is imported from, when that is not the pattern's own `importModule`: `flask` for the app a flask-restx API is served by. */
+    importModule?: string[];
+    /**
+     * `everyRoute` for the app, whose registration reaches every route of
+     * the pack in the run. `ownRoutes` for a router or a blueprint, whose
+     * registration reaches the routes decorated on that same object.
+     */
+    covers: "everyRoute" | "ownRoutes";
+}
+/**
+ * The library calls a project function before the handler, given as an
+ * argument to one of its own callables: FastAPI's `Depends(get_user)`.
+ * One may be written as a parameter default or inside `Annotated[...]`
+ * on the route, or in a list under `keyword` on the route decorator or
+ * on one of the registrars. The function runs before the handler and
+ * ends the request by raising, so it is a wrapper whose every return
+ * hands on.
+ */
+interface PyDependencyForm {
+    type: "dependency";
+    /** The callables that take the function: `Depends`, `Security`. */
+    callees: string[];
+    /** The keyword a list of them is written under: `dependencies`. */
+    keyword: string;
+    registrars: PyWrapperRegistrar[];
+}
+/**
+ * A project function decorated with a method on the app or a router:
+ * `@app.middleware("http")`, `@app.exception_handler(ValueError)`,
+ * `@app.before_request`. What the decorated function's returns mean
+ * depends on which of the three fields below is set; with none set,
+ * every return hands the request on.
+ */
+interface PyDecoratedWrapperForm {
+    type: "decoratedWrapper";
+    /** The decorator's attribute name on the registrar: `middleware`. */
+    attribute: string;
+    registrars: PyWrapperRegistrar[];
+    /**
+     * The position of the parameter the wrapper calls to run what it
+     * wraps, `call_next` at 1 for Starlette middleware. A return before
+     * that call ends the request with what is returned.
+     */
+    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`.
+     */
+    returnedValueResponds?: boolean;
+    /** The position the library hands the raised exception at. Set on an error handler, which runs only when the handler raised. */
+    throwParam?: number;
 }
 /**
  * One callable that ends the request, and where it takes the status.
@@ -577,6 +688,98 @@ 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.
+ */
+
+/** A function in this run, and the export path its summary gets. */
+interface ReachedFunction {
+    readonly file: BoundPythonFile;
+    /** The `function_definition` node. */
+    readonly node: Node;
+    readonly name: string;
+    /** `[name]` for a module function, `[Class, name]` for a method. */
+    readonly exportPath: string[];
+}
+
+/**
+ * The project functions a library runs around a route, read from where
+ * they are registered: a dependency on a route's parameter or decorator,
+ * a dependency list on the app or a router, a function decorated with
+ * `@app.middleware(...)` or `@app.exception_handler(...)`. Each one
+ * becomes a unit of its own, and every route it reaches lists it, so the
+ * extractor can fold its outcomes into the route's. The README says which
+ * registrations are read and which are not.
+ *
+ * A registration on the app reaches every route of the pack in the run,
+ * since an app is one per run for every pack that has one. A registration
+ * on a router reaches the routes decorated on that same router object,
+ * and nothing mounted onto it.
+ */
+
+interface WrapperIndexOptions {
+    packs: readonly PythonPack[];
+    roots: string[];
+    facts: Database | undefined;
+    storageFor: (file: BoundPythonFile) => StorageLookup | undefined;
+}
+/** The route asking which wrappers reach it: the decorator it was found by, and where that decorator was read. */
+interface RouteWrapperQuery {
+    pack: PythonPack;
+    pattern: PythonDiscoveryPattern;
+    /** The absolute path of the file the route is written in. */
+    file: string;
+    module: ModuleBinding;
+    classification: DecoratorClassification;
+    definitionNode: Node;
+}
+/** A wrapper the index has a unit for, and the form it was registered through. */
+interface Registered {
+    reference: WrapperReference;
+    form: PyWrapperForm;
+}
+interface FormOf {
+    pack: PythonPack;
+    pattern: PythonDiscoveryPattern;
+    form: PyWrapperForm;
+}
+/** What every registration in the run reaches, asked once per route and then once per file for the wrapper units. */
+declare class PythonWrapperIndex {
+    readonly options: WrapperIndexOptions;
+    readonly filesByPath: ReadonlyMap<string, BoundPythonFile>;
+    /** By pack name: what the app registered, in the order the forms are declared and then the order the files were read. */
+    private readonly everyRoute;
+    /** By construction key: what a router or a blueprint registered. */
+    private readonly ownRoutes;
+    private readonly unitsByKey;
+    private readonly unitsByFile;
+    constructor(options: WrapperIndexOptions, filesByPath: ReadonlyMap<string, BoundPythonFile>);
+    register(covers: {
+        kind: "everyRoute";
+        pack: string;
+    } | {
+        kind: "ownRoutes";
+        key: string;
+    }, target: ReachedFunction, declared: FormOf): void;
+    /** The unit for a function, built once however many registrations point at it. */
+    registered(target: ReachedFunction, declared: FormOf): Registered;
+    wrappersFor(query: RouteWrapperQuery): WrapperReference[];
+    private ownRoutesOf;
+    /**
+     * Where the decorator's object was built: the route's own file, the file
+     * a project wrapper function is written in, or the file an imported
+     * router comes from. The name is the one that file binds it under.
+     */
+    private objectSiteOf;
+    private fileOfModule;
+    unitsIn(file: string): RawCodeStructure[];
+}
+
 /**
  * Finds decorated routes and turns each one into a `RawCodeStructure`.
  *
@@ -605,6 +808,8 @@ interface DiscoveryOptions {
     absoluteFile?: string | undefined;
     /** The project's facts, so the rules can say what an object no scope has a binding for was built by. */
     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;
 }
 declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];