@suss/recognize 0.12.0 → 0.13.0

package/dist/chain-BaxjT_-k.d.ts

@@ -0,0 +1,530 @@
+/**
+ * The operations a chain performs at one call site, and what a language
+ * adapter has to be able to work out for it.
+ *
+ * A chain is data, so something has to turn "did this module declare
+ * the method" into a yes or no about a particular program. That is the
+ * adapter's job, and this interface is the whole of what a chain asks
+ * for. An adapter implements it once and every declared pack runs
+ * there, which is what lets one pack drive several languages.
+ *
+ * Nothing here mentions a syntax tree. A link that needs the tree goes
+ * through `@suss/recognize/ast`, a separate import so that reaching for
+ * it shows up in a diff and in the pack health report.
+ */
+/**
+ * How a pack pins down the receiver a call is on.
+ *
+ * The migration plan for #542 lists four more: `factoryMade` (`app =
+ * express()`), `imported`, `anchored` (a chain read from its anchor
+ * call), `inherits` (a Ruby or Python receiver matched by ancestry) and
+ * `global` (`process.env`, bare `fetch`). Each arrives as a member here
+ * with an entry in every adapter's dispatch table. The README beside
+ * this file says which starts are not receiver-shaped at all.
+ */
+type ReceiverOrigin = DeclaredBy | ConstructedFrom;
+/**
+ * A receiver whose method one of these modules declared.
+ *
+ * This is the origin for a client the source never spells out. `const
+ * redis = await this.getClient()` says nothing about ioredis, and the
+ * declaration behind `redis.get` says everything.
+ */
+interface DeclaredBy {
+    readonly origin: "declaredBy";
+    /** The modules whose declarations settle the call. */
+    readonly importedFrom: readonly string[];
+}
+/**
+ * A client made from a module's export, however the program caches it.
+ * Asked of the receiver itself, so it still works where the method is untyped
+ * and `declaredBy` finds nothing to read. A call that reaches for no
+ * receiver, `new GetObjectCommand(...)`, is made by its own callee.
+ */
+interface ConstructedFrom {
+    readonly origin: "constructed";
+    /** The modules whose export the client was made from. */
+    readonly importedFrom: readonly string[];
+}
+/**
+ * A receiver whose method one of these modules declared. Pass every
+ * module that ships the same client, the way three packages all speak
+ * one wire protocol.
+ */
+declare function declaredBy(...importedFrom: readonly string[]): DeclaredBy;
+/** A client made from one of these modules' exports. */
+declare function constructedFrom(...importedFrom: readonly string[]): ConstructedFrom;
+/**
+ * What a reader gives back for a name nothing in the source settles.
+ * `"nothing"` gives null, `"reference"` gives the value to go and ask
+ * about instead.
+ */
+type UnsettledName = "nothing" | "reference";
+/**
+ * One value a call states, as the questions a pack can ask about it.
+ *
+ * `CallOps` reaches a call beside the one in hand, and this reaches the
+ * values that are not calls. A library that takes one request object
+ * puts everything the call is doing inside it, sometimes as a list and
+ * sometimes as a string in a little language of the library's own, and
+ * a pack that reads those is handed this rather than the adapter's own
+ * node. So the rule it writes runs wherever the ops do.
+ */
+interface ValueOps {
+    /** The text of the string the source wrote, or null for anything else. */
+    text(): string | null;
+    /**
+     * The yes or no the source wrote here, or null for anything else. A
+     * library that asks which fields a call wants states them as a map of
+     * flags, `{ name: 1, password: 0 }`, and a number and a boolean mean
+     * the same thing in one of those.
+     */
+    flag(): boolean | null;
+    /** What this object states, entry by entry. Empty for anything else. */
+    entries(unsettled: UnsettledName): readonly ValueEntry[];
+    /** What this list states, item by item. Empty for anything else. */
+    items(): readonly ValueOps[];
+    /** What one named property of this object states, or null for none. */
+    property(name: string): ValueOps | null;
+    /**
+     * The pieces of text the source wrote here, in order, with whatever
+     * it interpolated between them left out. A string is one piece and a
+     * template is one piece per hole plus one, so a reader that means to
+     * put its own placeholders in the holes can. Null when the source
+     * wrote neither.
+     */
+    parts(): readonly string[] | null;
+    /**
+     * What the source interpolated between those pieces, in order, each
+     * as the call it was written as. There is one per gap, one fewer than
+     * `parts` gives, and a hole the source wrote as something other than
+     * a call is null rather than being dropped, so the two lists stay in
+     * step.
+     *
+     * What a hole comes to is the pack's to say. This says what was
+     * there, so a query that hands over a table object can still be read.
+     */
+    holes(): readonly (CallOps | null)[];
+}
+/** One entry of an object a call states. */
+interface ValueEntry {
+    /**
+     * What the entry is called. A key the source computes,
+     * `{ [table]: ... }`, is read the way any other name is.
+     */
+    readonly key: string | null;
+    /** What the entry says. */
+    readonly value: ValueOps;
+}
+/**
+ * One call site, as the questions a chain asks about it.
+ *
+ * An adapter builds one of these per call and hands it to the
+ * recognizer through its context. Every member is about the call in
+ * hand, so there is no node to pass around and no place for a pack to
+ * reach past what it declared.
+ *
+ * Two members give back another `CallOps`, which is how these questions
+ * reach a call next to this one. A chain of calls and a command object
+ * are both these same questions asked one step along, so neither needed
+ * a question of its own.
+ */
+interface CallOps {
+    /** Which method the call reaches for, spelled as the source spells it. */
+    method(): string | null;
+    /** Whether the receiver came from where the origin says. */
+    receiverIsFrom(origin: ReceiverOrigin): boolean;
+    /**
+     * Whether the call itself came from where the origin says, which is
+     * the same question asked of the callee rather than of what it was
+     * called on. `new GetCommand(...)` is the case: a pack that steps to
+     * an argument asks this of it before reading anything, so it never
+     * reads an argument that was never the one.
+     */
+    isFrom(origin: ReceiverOrigin): boolean;
+    /** How many arguments the call passes. */
+    argumentCount(): number;
+    /** The name the argument in this position gives. */
+    nameAt(index: number, unsettled: UnsettledName): string | null;
+    /** The callee, as the source writes it. */
+    calleeText(): string;
+    /**
+     * The call the receiver is, or null when the receiver is not a call.
+     * A receiver the source wrote into a variable comes back as the call
+     * it was written as.
+     */
+    receiver(): CallOps | null;
+    /**
+     * The call the argument in this position is, or null when that
+     * argument is neither a call nor a construction. `new
+     * GetObjectCommand(...)` comes back as a call whose callee is the
+     * class, the same as any other call.
+     */
+    argument(index: number): CallOps | null;
+    /**
+     * The call the callee itself was written as, or null when nothing
+     * wrote it as one. A class a factory made is the case: `new
+     * User({...})` says nothing about what `User` is, and the
+     * `model("User", schema)` call it was declared as says everything.
+     */
+    callee(): CallOps | null;
+    /**
+     * What a named property of the object an argument states says. A
+     * property bag is not a call, so nothing else here reaches into one.
+     */
+    propertyAt(index: number, property: string, unsettled: UnsettledName): string | null;
+    /**
+     * The value the argument in this position states, or null when the
+     * call passes none. `propertyAt` reads one name out of a property
+     * bag, which covers a pack that wants one; this hands the bag over
+     * for a pack whose rule has to walk it.
+     */
+    valueAt(index: number): ValueOps | null;
+}
+/**
+ * The property an adapter puts its ops on, in the context it hands a
+ * recognizer. A context without it belongs to an adapter that has not
+ * implemented the ops, and a declared pack matches nothing there.
+ */
+interface OpsCarrier {
+    ops?: CallOps;
+}
+/** The ops in a recognizer context, or null when the adapter has none. */
+declare function opsIn(ctx: unknown): CallOps | null;
+
+/**
+ * The spine every pack shares, as a chain of links.
+ *
+ * A pack does four jobs, and all four start the same way: match the
+ * receiver, match the method, read the arguments, then yield. What
+ * differs is the ending. Recognition yields effects, discovery yields a
+ * unit, a terminal yields a response write, and a claimed callback
+ * yields a sub-unit. Two recognition endings are built, one that asks
+ * the call what it reached and one that reads the statement the call
+ * was handed; the other three jobs are further members of `Ending`
+ * with an entry in the compile table.
+ *
+ * A link's answer is data wherever it can be. A link given a function
+ * instead is code, that link alone, and pack health says which ones.
+ */
+
+/** A link whose answer a pack wrote as code rather than as data. */
+interface LinkFunction<A extends unknown[], R> {
+    (...args: A): R;
+    /** Set when the function was built through `@suss/recognize/ast`. */
+    readonly reachesAst?: boolean;
+}
+/**
+ * What a match starts from.
+ *
+ * Most of what the shipped packs match starts from a receiver, and none
+ * of what discovery matches does: an exported name, a file path, a
+ * decorator, a parameter's type, a template file beside the module and
+ * a function's return type each start somewhere else. So the start is
+ * its own axis, and a receiver origin is one value on it.
+ */
+type MatchStart = FromReceiver;
+/** A match that starts from the receiver a call is on. */
+interface FromReceiver {
+    readonly starts: "receiver";
+    readonly origin: ReceiverOrigin;
+}
+/** Where the match begins. */
+interface StartLink {
+    readonly asks: "start";
+    readonly at: MatchStart;
+}
+/**
+ * One step from a call to another call it reaches.
+ *
+ * A pack that has to read a chain of calls, or a command a call was
+ * handed, states the steps to it and asks the same questions there. The
+ * steps are data, so a pack that reads three calls still declares three
+ * links rather than one function that walks.
+ */
+type CallStep = ToReceiver | ToArgument;
+/**
+ * The call the receiver is. With a method, the walk keeps going up the
+ * receivers until it reaches a call to that method, which is how a pack
+ * says which hop it means where the shape varies:
+ * `bucket(b).file(p).download()` and `bucket(b).getFiles()` put the
+ * bucket a different distance away.
+ */
+interface ToReceiver {
+    readonly to: "receiver";
+    readonly method?: string;
+}
+/** The call an argument is, when the argument is a call or a construction. */
+interface ToArgument {
+    readonly to: "argument";
+    /** Which argument, or every argument from a position on. */
+    readonly at: number | {
+        readonly from: number;
+    };
+    /**
+     * Where the argument has to have come from, for a step that tries
+     * several. `send(command)` takes one argument and a presigner takes
+     * two, and the one that matters is the command the SDK declares, so
+     * the step says so rather than reading whatever it lands on.
+     */
+    readonly origin?: ReceiverOrigin;
+}
+/**
+ * Which call a chain is about, when it is not the one in hand.
+ *
+ * The method is `send` at every AWS SDK call site in a codebase, and
+ * what the call does is inside the command it was handed. A chain about
+ * the command reads the operation, the container and the selector off
+ * it, and the effect still records the call in hand as its callee.
+ */
+interface SubjectLink {
+    readonly asks: "subject";
+    readonly of: readonly CallStep[];
+}
+/** Which methods count, and what each one does. */
+interface MethodsLink<TMeaning> {
+    readonly asks: "methods";
+    readonly table: Readonly<Record<string, TMeaning>>;
+    /**
+     * Whether two spellings of one method name are the same method. One
+     * client library lower-cases where another camel-cases, and both are
+     * sending the same command.
+     */
+    readonly ignoringCase: boolean;
+}
+/**
+ * Which container a call's selector belongs to, as an argument the call
+ * states or as the pack's own rule over what the call reached.
+ */
+type ContainerLink = ContainerArgument | ContainerRule;
+/** The container as one of the call's own arguments states it. */
+interface ContainerArgument {
+    readonly asks: "container";
+    readonly argument: ArgumentPick;
+}
+/**
+ * The container worked out by the pack. The call the chain is about
+ * comes second so that a rule written over the selector alone, which is
+ * most of them, ignores it. A rule that has to read the syntax tree
+ * goes through `astLink`, which is what puts the call to use.
+ */
+interface ContainerRule {
+    readonly asks: "container";
+    readonly from: LinkFunction<[readonly string[], CallOps], string | null>;
+}
+/** Which way into the container the call took, when it states one. */
+interface AccessPathLink {
+    readonly asks: "accessPath";
+    readonly argument: ArgumentPick;
+}
+/**
+ * Where a call states the containers it reached, for a call that
+ * reaches several at once. A batch or a transaction states them as a
+ * map, one entry per container, so the chain yields one effect per
+ * entry: the entry's own key is what the container is called, and its
+ * value says what the call did there.
+ */
+interface ContainersLink {
+    readonly asks: "containers";
+    readonly in: OneArgument;
+}
+/**
+ * Where a call states its inputs, when it states them as one object
+ * rather than as positional arguments. A call that states none is not
+ * one of these calls, so the chain stops there, and a rule the pack
+ * writes over the inputs is handed the object rather than a position to
+ * go looking in.
+ */
+interface InputLink {
+    readonly asks: "input";
+    readonly at: OneArgument;
+}
+/**
+ * What the values a statement interpolates come to.
+ *
+ * A query that says which table it reached by handing over the schema
+ * object leaves the name out of the text, and a parameter in its place
+ * does not parse. Only the pack knows the object is a table rather than
+ * a value, so the pack says which argument of the call behind it gives
+ * the name, and where that call had to have come from.
+ */
+interface InterpolatesLink {
+    readonly asks: "interpolates";
+    /** Which argument of the call the value was written as gives the name. */
+    readonly named: ArgumentPick;
+    /** Where the value had to have come from. Left out, every hole is read. */
+    readonly from?: ReceiverOrigin;
+}
+/** One question in a chain, and the answer the pack gave for it. */
+type Link<TMeaning> = StartLink | SubjectLink | MethodsLink<TMeaning> | ContainerLink | AccessPathLink | ContainersLink | InputLink | InterpolatesLink;
+/**
+ * Which argument or arguments say what a call reached, and where to go
+ * looking. Without `of` the argument belongs to the chain's subject.
+ */
+type ArgumentPick = OneArgument | ArgumentsFrom;
+/** The argument in one position. */
+interface OneArgument {
+    /** The steps to the call the argument belongs to. */
+    readonly of?: readonly CallStep[];
+    readonly at: number;
+    /**
+     * Properties of the object the argument states, tried in order, when
+     * what the call reached is inside the argument rather than being it.
+     */
+    readonly property?: readonly string[];
+}
+/** Every argument the call passes from one position on. */
+interface ArgumentsFrom {
+    /** The steps to the call the arguments belong to. */
+    readonly of?: readonly CallStep[];
+    readonly from: number;
+    /** Properties of the object each argument states, tried in order. */
+    readonly property?: readonly string[];
+}
+/**
+ * What one method of a storage client does to the store: a read, a
+ * write, or whichever of the two one of its arguments asked for.
+ */
+type AccessKind = "read" | "write" | KindAsAsked;
+/** A method the caller tells which way round it goes. */
+interface KindAsAsked {
+    /** Where the call says what it is for. */
+    readonly asks: ArgumentPick;
+    /** What each thing the caller can ask for comes to. */
+    readonly means: Readonly<Record<string, "read" | "write">>;
+    /**
+     * What it comes to when the call says nothing. Left out, a call that
+     * asks for something the table does not list is not one of these
+     * calls, which is how a pack reads a helper whose operations a
+     * project lists in its own config.
+     */
+    readonly otherwise?: "read" | "write";
+}
+/** What a pack's own rule is handed: one value, and what the call does. */
+interface StatedInputs {
+    /**
+     * The value the rule reads. That is the object the call states its
+     * inputs as when the chain says where with `input`, and the value the
+     * rule was pointed at when it says where for itself. A call that
+     * passed nothing there states nothing, rather than the rule being
+     * skipped: a projection the caller left out is still a read of every
+     * field there is, and only the pack knows that.
+     */
+    readonly input: ValueOps;
+    /** The container's own entry, when the call reached several. */
+    readonly entry: ValueOps | null;
+    /** What the call does to the store. */
+    readonly kind: "read" | "write";
+}
+/**
+ * A pack's own rule over the inputs a call states, for a library that
+ * writes what a reader wants somewhere no pick can reach.
+ */
+type InputRule = LinkFunction<[StatedInputs], readonly string[]>;
+/**
+ * A pack's own rule, pointed at the value it reads.
+ *
+ * `input` says where a call that states one request object states it,
+ * and every rule on that chain reads the one value. A library that
+ * spreads what a reader wants over several places needs each rule
+ * pointed somewhere of its own: Mongoose picks documents by the first
+ * argument and reads the fields the second asks for, and Drizzle puts
+ * the fields, the table and the condition on three calls of one chain,
+ * which the pick's own `of` steps reach.
+ */
+interface StatedRule {
+    /** Which value the rule reads. */
+    readonly of: OneArgument;
+    /** What the pack works out from it. */
+    readonly by: InputRule;
+}
+/** What one method of a storage client does. */
+interface StorageMethod {
+    readonly kind: AccessKind;
+    /**
+     * Which argument says which operation the call performs, when the
+     * name the call goes to does not. A project's own request helper is
+     * the case: every operation goes through the one function.
+     */
+    readonly operation?: ArgumentPick;
+    /**
+     * What the call reached. An argument the call passes, a rule the pack
+     * wrote, or the plain list a method whose own name settles it states
+     * outright: `findById` picks by `_id` however the id is spelt.
+     */
+    readonly selector?: readonly string[] | ArgumentPick | InputRule | StatedRule;
+    /**
+     * Which fields the call touched, said the same three ways. A delete
+     * touches the whole document and states `["*"]`, since nothing in its
+     * arguments says so.
+     */
+    readonly fields?: readonly string[] | ArgumentPick | InputRule | StatedRule;
+}
+/**
+ * What one method of a client that takes a statement written as SQL
+ * does. The statement says which tables it touches and what it does to
+ * each, so the only thing a pack has to state is where the call puts
+ * it.
+ */
+interface SqlMethod {
+    /**
+     * Where the call states the statement. The pick's steps reach a call
+     * beside this one, which is how a pack reads a statement handed to
+     * `execute` as a tagged template rather than written on the call.
+     */
+    readonly statement: OneArgument;
+}
+/** What one method table can say a method does. */
+type MethodMeaning = StorageMethod | SqlMethod;
+/** What a chain produces when every link matches. */
+type Ending = StorageEnding | SqlEnding;
+/** A storage access: one call, one thing it read or wrote. */
+interface StorageEnding {
+    readonly yields: "storageAccess";
+    /** The store, in the words OpenTelemetry's semantic conventions use. */
+    readonly system: string;
+    /** The wire, when it differs from the store's own name. */
+    readonly transport?: string;
+    /** Which of the store's namespaces the call reached. */
+    readonly scope: string;
+    /** What a reader gives back for a name nothing in the source settles. */
+    readonly unsettledName: "nothing" | "reference";
+}
+/**
+ * Every table a statement touches, as one effect each.
+ *
+ * The other ending settles what a call reached by asking the call. This
+ * one settles it by reading the statement, so one call yields as many
+ * effects as the statement has tables, and each of them states its own
+ * kind: a statement that writes one table while reading another says
+ * both.
+ */
+interface SqlEnding {
+    readonly yields: "sqlAccess";
+    /** The store, in the words OpenTelemetry's semantic conventions use. */
+    readonly system: string;
+    /** The wire, when it differs from the store's own name. */
+    readonly transport?: string;
+    /** Which of the store's namespaces the call reached. */
+    readonly scope: string;
+    /**
+     * Which dialect the statements are written in. A pack states it
+     * outright because nothing here can work it out: a Cloudflare D1
+     * database is a store of its own whose statements are SQLite, and a
+     * reader that guessed Postgres for a MySQL project would report the
+     * wrong tables rather than none.
+     */
+    readonly dialect: string;
+}
+/**
+ * A pack's declaration for one kind of call: the links, the ending, and
+ * a line of code it matches.
+ */
+interface Chain<TMeaning = MethodMeaning> {
+    readonly links: readonly Link<TMeaning>[];
+    readonly ending: Ending;
+    /** A line of code this matches, which the pack's tests run. */
+    readonly example: string | null;
+}
+
+export { type ArgumentPick as A, declaredBy as B, type CallOps as C, type DeclaredBy as D, type Ending as E, type FromReceiver as F, opsIn as G, type InterpolatesLink as I, type KindAsAsked as K, type LinkFunction as L, type MethodMeaning as M, type OneArgument as O, type ReceiverOrigin as R, type SqlMethod as S, type ToArgument as T, type UnsettledName as U, type ValueEntry as V, type Chain as a, type CallStep as b, type StorageMethod as c, type AccessKind as d, type AccessPathLink as e, type ArgumentsFrom as f, type ConstructedFrom as g, type ContainerArgument as h, type ContainerLink as i, type ContainerRule as j, type ContainersLink as k, type InputLink as l, type InputRule as m, type Link as n, type MatchStart as o, type MethodsLink as p, type OpsCarrier as q, type SqlEnding as r, type StartLink as s, type StatedInputs as t, type StatedRule as u, type StorageEnding as v, type SubjectLink as w, type ToReceiver as x, type ValueOps as y, constructedFrom as z };