@suss/adapter-python 0.3.2-0

package/dist/index.d.cts

@@ -0,0 +1,459 @@
+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';
+
+/**
+ * A new `Parser` for every call, so that parses running at the same time do
+ * not fight over one parser's mutable `language` field. The compiled `Language`
+ * is loaded once per process and shared.
+ */
+declare function parsePython(source: string): Promise<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.
+ *
+ * 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`.
+ */
+type Binding = {
+    kind: "import";
+    module: string;
+    relativeLevel: number;
+    localName: string;
+} | {
+    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 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;
+
+/**
+ * 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;
+}
+
+type DecoratorArg = {
+    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;
+} | {
+    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;
+}
+declare function classifyDecorator(decoratorNode: Node, scope: Scope): DecoratorClassification;
+
+/**
+ * The Python adapter's own pattern-pack contract.
+ *
+ * This is deliberately not the TypeScript adapter's `PatternPack`. That type
+ * dispatches its discovery variants through ts-morph-specific handlers, and
+ * Python's two route shapes have no exact match in its union anyway. Match
+ * shapes stay per-language until a second implementation shows what is actually
+ * shared, and this is the per-language one for Python.
+ *
+ * A pack is still plain data, following the same rule the TypeScript packs
+ * follow: it describes what a library defines, never anything a project chose.
+ */
+interface PythonPack {
+    name: string;
+    /** Wire protocol for the produced boundary bindings, e.g. "http". */
+    protocol: string;
+    discovery: PythonDiscoveryPattern[];
+}
+type PythonDiscoveryPattern = DecoratedClassRoute | DecoratedFunctionRoute;
+/** 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. */
+    pathParamSyntax?: string;
+    /** Set it only when the library itself binds an annotated local class to the request body. */
+    annotatedClassIsRequestBody?: boolean;
+    /**
+     * Callables the library uses to inject a parameter rather than read it
+     * off the request. FastAPI's `Depends` and `Security` are these: the
+     * server supplies the value and the client sends nothing, so a
+     * parameter defaulted to one of them is no part of the request however
+     * its annotation reads.
+     */
+    injectedParameterCallees?: string[];
+    /**
+     * What the library serves when a composed path ends up with repeated
+     * slashes in it. Werkzeug serves the merged path and redirects
+     * the written one, so "merged" is what Flask needs; "kept" is the
+     * default and is what Starlette does.
+     */
+    pathRepeatedSlashes?: PathRepeatedSlashes;
+    /** The status the library returns for a declared response when the route does not give one. Library-defined. */
+    defaultStatusCode?: number;
+    /**
+     * Set it only when the library reads a status out of the tuple a handler
+     * returns, which is what Flask does with `return body, 201`. Without it
+     * the library default applies whatever the body returns, and a route
+     * that sets its own status would be reported at the default.
+     */
+    statusFromReturnedTuple?: boolean;
+    /** Unset means the library has no router mounting, and a route's decorator path stands as written. */
+    routerComposition?: RouterComposition;
+}
+/**
+ * A class has a decorator whose first string-literal argument is the route path,
+ * and each method in its body named after an HTTP verb becomes its own unit,
+ * with the verb taken from the method name.
+ */
+interface DecoratedClassRoute extends RouteConventions {
+    type: "decoratedClassRoute";
+    /** The library's own module, plus any wrapper module the person configuring the pack lists alongside it. */
+    importModule: string[];
+    /** The decorator's name as the library exports it, "route" for flask-restx's `Namespace.route`. */
+    decoratorName: string;
+    /** Method name written in the class body, mapped to the HTTP verb it dispatches. */
+    verbMethodNames: Record<string, string>;
+}
+/**
+ * A function has a decorator whose attribute name is the HTTP verb and whose
+ * first string-literal argument is the route path, the `@app.get(path)`
+ * convention. The object it hangs on may be imported, or built one hop away by
+ * a call to something imported.
+ */
+interface DecoratedFunctionRoute extends RouteConventions {
+    type: "decoratedFunctionRoute";
+    importModule: string[];
+    /** Decorator attribute name, mapped to the HTTP verb it means. */
+    verbAttributeNames: Record<string, string>;
+    /** Unset leaves the return annotation as the only source for the response shape. */
+    responseModelKeyword?: string;
+    statusCodeKeyword?: string;
+}
+/**
+ * What a library calls the pieces of router mounting, so a route's served path
+ * can be built from the literal prefixes written along the way: the router
+ * constructor's own, the one at the call that mounts it, and, where the pack
+ * says so, the prefix on the object the mount is called on. What each spelling
+ * of a prefix means, and what makes a composition abstain, is the grid in the
+ * adapter's README.
+ */
+interface RouterComposition {
+    /** Constructor whose call builds a mountable router, FastAPI's `APIRouter`. */
+    routerConstructorName: string;
+    /** Method that mounts a router onto the app, FastAPI's `include_router`. */
+    includeMethodName: string;
+    /** One keyword serves the constructor and the mount alike. A library that spells them apart needs two fields here. */
+    prefixKeyword: string;
+    /** Default "prefixes". */
+    mountPrefixEffect?: MountPrefixEffect;
+    /** Set it when the library works out a path for a router that gives no prefix. We cannot work that path out, so such routes abstain. */
+    constructorPrefixRequired?: boolean;
+    /** Default "unreadable". The same setting covers the constructor and the mount. */
+    noValuePrefix?: NoValuePrefix;
+    /** Default "kept". */
+    constructorPrefixTrailingSlash?: PrefixTrailingSlash;
+    /**
+     * Where the object the mount is called on states a prefix of its
+     * own, in front of everything the constructor and the mount state.
+     * Unset means it states none, which is FastAPI's behavior: an app
+     * serves a mounted router exactly where the two prefixes put it.
+     */
+    mountObjectPrefix?: MountObjectPrefix;
+}
+/**
+ * The prefix the object a mount is called on states, and where it is
+ * written. flask-restx needs both halves: `Api(prefix=...)` states one
+ * on the object itself, and the Flask blueprint the `Api` was built
+ * from states another with `Blueprint(name, __name__,
+ * url_prefix=...)`. The library serves a route under the blueprint's
+ * prefix, then the `Api`'s, then whatever the namespace and the route
+ * say.
+ */
+interface MountObjectPrefix {
+    /** Keyword stating a prefix on the mount object's own construction (flask-restx's `Api(prefix=...)`). */
+    prefixKeyword?: string;
+    /** The object handed to that construction which states a prefix of its own. */
+    carrier?: MountObjectCarrier;
+}
+/**
+ * An object handed to the mount object's constructor, one hop further
+ * out, with a prefix of its own (the Flask blueprint behind an
+ * `Api`). Naming it here is what lets the adapter tell that object
+ * apart from the plain app that appears in the same argument position and
+ * has no prefix at all.
+ */
+interface MountObjectCarrier {
+    /** Modules the carrier's constructor is imported from (Flask's `flask`). */
+    importModule: string[];
+    /** Constructor building the carrier, as its library exports it (Flask's `Blueprint`). */
+    constructorName: string;
+    /** Position of the carrier among the mount object's constructor arguments. */
+    argumentIndex: number;
+    /** Keyword stating the carrier's prefix, at its construction and at its registration alike (Flask's `url_prefix`). */
+    prefixKeyword: string;
+    /**
+     * Method handing the carrier to an already-built mount object
+     * (flask-restx's `init_app`, the application-factory spelling of
+     * `Api(blueprint)`). Unset means the constructor argument is the
+     * only way in.
+     */
+    handoffMethodName?: string;
+    /**
+     * Method registering the carrier somewhere else (Flask's
+     * `register_blueprint`). The adapter reads it only to abstain: a
+     * registration restating the prefix, putting the carrier inside
+     * another carrier, or happening twice moves the served path
+     * somewhere the carrier's own construction no longer says.
+     */
+    registerMethodName: string;
+}
+type MountPrefixEffect = "prefixes" | "replaces";
+type PrefixTrailingSlash = "kept" | "trimmed";
+type NoValuePrefix = "unstated" | "unreadable";
+/**
+ * Werkzeug serves the merged path and redirects the written one, so Flask
+ * needs "merged". Starlette leaves the path as composed, so FastAPI keeps
+ * the default.
+ */
+type PathRepeatedSlashes = "kept" | "merged";
+
+/**
+ * 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.
+ */
+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;
+}
+type ModuleResolution = {
+    status: "resolved";
+    file: 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";
+};
+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 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;
+
+/** One file, already parsed and bound. `buildRouterIndex` takes a project as a list of these. */
+interface BoundPythonFile {
+    /** The absolute path, which is what module resolution joins on. */
+    file: string;
+    /** The path a gap refers to this file by, which a reader has to be able to open. */
+    displayPath: string;
+    root: Node;
+    module: ModuleBinding;
+}
+/**
+ * What the object a decorator hangs on turns out to be. `notRouter` covers the
+ * app itself and anything the index never saw constructed, so the decorator's
+ * own path stands as written. `composed` gives the prefix to put in front of
+ * that path. An `abstain` reason is written to follow "the router this route is
+ * declared on ...".
+ */
+type RoutePrefixResolution = {
+    kind: "notRouter";
+} | {
+    kind: "composed";
+    value: string;
+} | {
+    kind: "abstain";
+    reason: string;
+};
+interface RouterIndex {
+    resolve(pattern: PythonDiscoveryPattern, module: ModuleBinding, objectName: string): RoutePrefixResolution;
+}
+declare function buildRouterIndex(files: BoundPythonFile[], packs: PythonPack[], resolverOptions: ModuleResolverOptions): RouterIndex;
+
+/**
+ * Finds decorated routes and turns each one into a `RawCodeStructure`.
+ *
+ * Only decorated module-level functions and classes that are declared
+ * unconditionally get discovered, the same boundary the binder in scope.ts
+ * draws. Nothing here reads into a unit's body, so a route's summary comes out
+ * with no branches at all, or with exactly one branch describing what an
+ * annotation or a decorator keyword already states, such as a FastAPI
+ * `response_model` or `status_code`, or a return annotation.
+ *
+ * That is enough to pair a route against a caller by method and path, and it
+ * claims nothing about behavior nobody read.
+ */
+
+interface DiscoveryOptions {
+    packs: PythonPack[];
+    /** Repo-relative or absolute path recorded on each summary's `location.file`. */
+    filePath: string;
+    /** Without it, every route object looks like the app itself and paths stand as written. */
+    routerIndex?: RouterIndex;
+    /** Under "strict" a route whose unit cannot be built stops the run instead of abstaining. */
+    gapHandling?: ExtractorOptions["gapHandling"];
+}
+declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];
+
+/**
+ * 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
+ * alone would drop one of them.
+ */
+declare function unitKey(filePath: string, range: {
+    start: number;
+    end: number;
+}, name: string): string;
+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. */
+declare function emitModuleImportFacts(db: Database, filePath: string, module: ModuleBinding, resolverOptions: ModuleResolverOptions): void;
+
+interface ExtractPythonOptions {
+    /** Absolute paths of the files to parse and extract. */
+    files: string[];
+    packs: PythonPack[];
+    /** Directories an absolute import is resolved against. */
+    roots: string[];
+    /** When set, `location.file` on each summary is relativized against this. */
+    workspaceRoot?: 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"];
+}
+interface ExtractPythonResult {
+    summaries: BehavioralSummary[];
+    facts: Database;
+}
+declare function extractPythonProject(options: ExtractPythonOptions): Promise<ExtractPythonResult>;
+/** 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 };