@suss/recognize 0.11.0 → 0.13.0

package/dist/chain-DTSij2Mn.d.cts

@@ -1,197 +0,0 @@
-/**
- * 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.
- */
-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 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.
- */
-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;
-    /** 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 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. Only the effects ending is built; the others 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;
-}
-/** 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.
- *
- * The call in hand 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 ContainerLink {
-    readonly asks: "container";
-    readonly from: LinkFunction<[readonly string[], CallOps], string | null>;
-}
-/** One question in a chain, and the answer the pack gave for it. */
-type Link<TMeaning> = StartLink | MethodsLink<TMeaning> | ContainerLink;
-/** Which argument or arguments say what a call reached. */
-type ArgumentPick = {
-    readonly at: number;
-} | {
-    readonly from: number;
-};
-/** What one method of a storage client does. */
-interface StorageMethod {
-    readonly kind: "read" | "write";
-    /** Which argument or arguments say what the call reached. */
-    readonly selector?: ArgumentPick;
-    /** Which argument says which field inside it, when the method takes one. */
-    readonly fields?: ArgumentPick;
-}
-/** What a chain produces when every link matches. */
-type Ending = StorageEnding;
-/** 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";
-}
-/**
- * A pack's declaration for one kind of call: the links, the ending, and
- * a line of code it matches.
- */
-interface Chain<TMeaning = StorageMethod> {
-    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, type CallOps as C, type DeclaredBy as D, type Ending as E, type FromReceiver as F, type LinkFunction as L, type MatchStart as M, type OpsCarrier as O, type ReceiverOrigin as R, type StorageMethod as S, type UnsettledName as U, type Chain as a, type ConstructedFrom as b, type ContainerLink as c, type Link as d, type MethodsLink as e, type StartLink as f, type StorageEnding as g, constructedFrom as h, declaredBy as i, opsIn as o };

package/dist/chain-DTSij2Mn.d.ts

@@ -1,197 +0,0 @@
-/**
- * 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.
- */
-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 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.
- */
-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;
-    /** 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 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. Only the effects ending is built; the others 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;
-}
-/** 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.
- *
- * The call in hand 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 ContainerLink {
-    readonly asks: "container";
-    readonly from: LinkFunction<[readonly string[], CallOps], string | null>;
-}
-/** One question in a chain, and the answer the pack gave for it. */
-type Link<TMeaning> = StartLink | MethodsLink<TMeaning> | ContainerLink;
-/** Which argument or arguments say what a call reached. */
-type ArgumentPick = {
-    readonly at: number;
-} | {
-    readonly from: number;
-};
-/** What one method of a storage client does. */
-interface StorageMethod {
-    readonly kind: "read" | "write";
-    /** Which argument or arguments say what the call reached. */
-    readonly selector?: ArgumentPick;
-    /** Which argument says which field inside it, when the method takes one. */
-    readonly fields?: ArgumentPick;
-}
-/** What a chain produces when every link matches. */
-type Ending = StorageEnding;
-/** 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";
-}
-/**
- * A pack's declaration for one kind of call: the links, the ending, and
- * a line of code it matches.
- */
-interface Chain<TMeaning = StorageMethod> {
-    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, type CallOps as C, type DeclaredBy as D, type Ending as E, type FromReceiver as F, type LinkFunction as L, type MatchStart as M, type OpsCarrier as O, type ReceiverOrigin as R, type StorageMethod as S, type UnsettledName as U, type Chain as a, type ConstructedFrom as b, type ContainerLink as c, type Link as d, type MethodsLink as e, type StartLink as f, type StorageEnding as g, constructedFrom as h, declaredBy as i, opsIn as o };