@suss/recognize 0.11.0 → 0.13.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { InvocationRecognizer, PatternPack } from '@suss/extractor';
+import { InvocationRecognizer, PatternPack, PackDeclarations } from '@suss/extractor';
 export { DeclaredMatch, PackDeclarations, PatternPack } from '@suss/extractor';
-import { a as Chain, S as StorageMethod, L as LinkFunction, C as CallOps, R as ReceiverOrigin } from './chain-DTSij2Mn.cjs';
-export { A as ArgumentPick, b as ConstructedFrom, c as ContainerLink, D as DeclaredBy, E as Ending, F as FromReceiver, d as Link, M as MatchStart, e as MethodsLink, O as OpsCarrier, f as StartLink, g as StorageEnding, U as UnsettledName, h as constructedFrom, i as declaredBy, o as opsIn } from './chain-DTSij2Mn.cjs';
+import { a as Chain, M as MethodMeaning, S as SqlMethod, I as InterpolatesLink, R as ReceiverOrigin, b as CallStep, c as StorageMethod, A as ArgumentPick, L as LinkFunction, C as CallOps, O as OneArgument } from './chain-BaxjT_-k.cjs';
+export { d as AccessKind, e as AccessPathLink, f as ArgumentsFrom, g as ConstructedFrom, h as ContainerArgument, i as ContainerLink, j as ContainerRule, k as ContainersLink, D as DeclaredBy, E as Ending, F as FromReceiver, l as InputLink, m as InputRule, K as KindAsAsked, n as Link, o as MatchStart, p as MethodsLink, q as OpsCarrier, r as SqlEnding, s as StartLink, t as StatedInputs, u as StatedRule, v as StorageEnding, w as SubjectLink, T as ToArgument, x as ToReceiver, U as UnsettledName, V as ValueEntry, y as ValueOps, z as constructedFrom, B as declaredBy, G as opsIn } from './chain-BaxjT_-k.cjs';
 import { Effect } from '@suss/behavioral-ir';
 
 /**
@@ -13,10 +13,14 @@ import { Effect } from '@suss/behavioral-ir';
  * says which questions to ask, not the order to ask them in. A link
  * that changes what the receiver is, the way Prisma's model property
  * does, will need that order back, and the note here is where to start.
+ *
+ * A chain that states a subject asks its questions of a call next to
+ * the one in hand, so the walk lives here. The README beside this file
+ * says what each step reaches and why the walk is bounded.
  */
 
 /** A chain, as the hook the adapter dispatches to on every call. */
-declare function compile(chain: Chain<StorageMethod>, recognition: string): InvocationRecognizer;
+declare function compile(chain: Chain<MethodMeaning>, recognition: string): InvocationRecognizer;
 
 /**
  * Running the example that comes with every declaration.
@@ -49,6 +53,109 @@ declare function runExamples(pack: PatternPack, run: RunOverCode): RanExample[];
 /** The declarations a pack shipped without a line of code to run. */
 declare function examplesMissing(pack: PatternPack): string[];
 
+/**
+ * Assembling declared chains into the pack the adapters load.
+ *
+ * Everything a `PatternPack` needs beyond the chains is either already
+ * in them or the same for every declared pack: the modules the client
+ * came from are the import gate, the store's wire is the protocol, and
+ * a pack of recognizers discovers nothing. What is left is the pack's
+ * own name, the languages it runs on, and the name its effects are
+ * recognized under, which is the npm package callers install.
+ */
+
+/**
+ * One thing a pack matches, as whichever entry point built it hands it
+ * over. `storageCalls` and `sqlStatements` both come out as this.
+ */
+interface Match {
+    readonly declared: Chain<MethodMeaning>;
+}
+/** What a pack says about itself, beyond the calls it matches. */
+interface PackSpec {
+    /** The languages the pack runs on, as the adapters name them. */
+    languages: string[];
+    /**
+     * The name effects from this pack are recorded under, which is the
+     * npm package a user installs.
+     */
+    recognizedAs: string;
+    /**
+     * What the pack calls this build of itself. The extraction cache keys
+     * on it, so a pack that never stamps one serves an earlier build's
+     * results after an edit.
+     */
+    version?: string;
+    /**
+     * What the pack itself speaks, when that is not the wire its accesses
+     * record. An S3 access goes over the AWS SDK and says so on every
+     * effect, while the pack speaks S3.
+     */
+    protocol?: string;
+    /**
+     * Further modules whose presence makes a file worth reading, beyond
+     * the ones the chains match on. A helper a project reaches by a
+     * relative path gives the gate nothing; the library that helper
+     * imports gives it something.
+     */
+    requiresImport?: string[];
+}
+/** A pack, assembled from the calls it says it matches. */
+declare function pack(name: string, matches: readonly Match[], spec: PackSpec): PatternPack;
+/**
+ * What a set of chains cost, for a pack that assembles itself. A pack
+ * part way through the migration still has a hand-rolled walk beside
+ * its declarations, and this is how the part that moved is priced.
+ */
+declare function declarationsIn(matches: readonly Match[]): PackDeclarations;
+
+/**
+ * The entry point for a pack whose calls hand the store a statement
+ * written as SQL.
+ *
+ * A typed client says what it reached in its arguments, so the chain
+ * asks the call. A raw statement says it in the text, so the chain
+ * hands the text to `@suss/sql` and the parse settles the container,
+ * the kind, the fields and the selector of every table the statement
+ * touches. The links up to that point are the same ones every chain
+ * states, which is why this is an ending rather than a grammar of its
+ * own.
+ */
+
+/** What a pack says about the store its statements reach. */
+interface SqlStatementsSpec {
+    /** The store, in the words OpenTelemetry's semantic conventions use. */
+    system: string;
+    /** The wire, when it differs from the store's own name. */
+    transport?: string;
+    /** Which of the store's namespaces the calls reach. Defaults to "default". */
+    scope?: string;
+    /**
+     * Which dialect the statements are written in. Wherever the store is
+     * the database this is the store's own name again, and a pack says it
+     * anyway: a store whose statements are somebody else's SQL is common
+     * enough that a default here would read the wrong tables quietly.
+     */
+    dialect: string;
+    /** How the pack pins down the client its calls are on. */
+    client?: ReceiverOrigin;
+}
+/** A chain over statements, and the links that can still be added. */
+interface SqlStatements {
+    /** Which methods take a statement, and where each one states it. */
+    methods(table: Readonly<Record<string, SqlMethod>>, options?: {
+        ignoringCase?: boolean;
+    }): SqlStatements;
+    /** What the values a statement interpolates come to. */
+    interpolating(says: Omit<InterpolatesLink, "asks">): SqlStatements;
+    /** A line of code this matches, which the pack's tests run. */
+    example(code: string): SqlStatements;
+    /** The links and the ending, as data. */
+    readonly declared: Chain<SqlMethod>;
+}
+/** A pack that recognizes statements written as SQL. */
+declare function sqlStatements(spec: SqlStatementsSpec): SqlStatements;
+
 /**
  * The entry point for a pack that recognizes storage calls, and the
  * chain it builds.
@@ -67,8 +174,12 @@ interface StorageCallsSpec {
     transport?: string;
     /** Which of the store's namespaces the calls reach. Defaults to "default". */
     scope?: string;
-    /** How the pack pins down the client its calls are on. */
-    client: ReceiverOrigin;
+    /**
+     * How the pack pins down the client its calls are on. A pack that
+     * matches a helper a project lists in its own config leaves this out,
+     * because the name that project gave is the whole of what it has.
+     */
+    client?: ReceiverOrigin;
     /**
      * What a reader gives back for a name nothing settles. Defaults to
      * "reference", which says which value to go and ask about.
@@ -77,15 +188,35 @@ interface StorageCallsSpec {
 }
 /** A storage chain, and the links that can still be added to it. */
 interface StorageCalls {
+    /**
+     * Which call the chain is about, when it is not the one in hand. The
+     * steps run from the call in hand, and every other link is asked of
+     * what they reach.
+     */
+    about(...of: readonly CallStep[]): StorageCalls;
     /** Which methods count, and what each one reads or writes. */
     methods(table: Readonly<Record<string, StorageMethod>>, options?: {
         ignoringCase?: boolean;
     }): StorageCalls;
     /**
-     * Which container a call's selector belongs to. Without this the
-     * first name a call reached is the container.
+     * Which container a call's selector belongs to, as an argument or as
+     * the pack's own rule. Without this the first name a call reached is
+     * the container.
+     */
+    container(says: ArgumentPick | LinkFunction<[readonly string[], CallOps], string | null>): StorageCalls;
+    /** Which way into the container the call took, when it states one. */
+    accessPath(says: ArgumentPick): StorageCalls;
+    /**
+     * Where a call that reaches several containers at once states them.
+     * Each entry becomes one effect, against the container its key says.
+     */
+    containersIn(says: OneArgument): StorageCalls;
+    /**
+     * Where a call states its inputs, when it states them as one object.
+     * A call that states none does not match, and a rule the pack wrote
+     * over the inputs is handed the object.
      */
-    container(from: LinkFunction<[readonly string[], CallOps], string | null>): StorageCalls;
+    input(says: OneArgument): StorageCalls;
     /** A line of code this matches, which the pack's tests run. */
     example(code: string): StorageCalls;
     /** The links and the ending, as data. */
@@ -94,34 +225,4 @@ interface StorageCalls {
 /** A pack that recognizes calls against a store. */
 declare function storageCalls(spec: StorageCallsSpec): StorageCalls;
 
-/**
- * Assembling declared chains into the pack the adapters load.
- *
- * Everything a `PatternPack` needs beyond the chains is either already
- * in them or the same for every declared pack: the modules the client
- * came from are the import gate, the store's wire is the protocol, and
- * a pack of recognizers discovers nothing. What is left is the pack's
- * own name, the languages it runs on, and the name its effects are
- * recognized under, which is the npm package callers install.
- */
-
-/** What a pack says about itself, beyond the calls it matches. */
-interface PackSpec {
-    /** The languages the pack runs on, as the adapters name them. */
-    languages: string[];
-    /**
-     * The name effects from this pack are recorded under, which is the
-     * npm package a user installs.
-     */
-    recognizedAs: string;
-    /**
-     * What the pack calls this build of itself. The extraction cache keys
-     * on it, so a pack that never stamps one serves an earlier build's
-     * results after an edit.
-     */
-    version?: string;
-}
-/** A pack, assembled from the calls it says it matches. */
-declare function pack(name: string, matches: readonly StorageCalls[], spec: PackSpec): PatternPack;
-
-export { CallOps, Chain, LinkFunction, type PackSpec, type RanExample, ReceiverOrigin, type RunOverCode, type StorageCalls, type StorageCallsSpec, StorageMethod, compile, examplesMissing, pack, runExamples, storageCalls };
+export { ArgumentPick, CallOps, CallStep, Chain, InterpolatesLink, LinkFunction, type Match, MethodMeaning, OneArgument, type PackSpec, type RanExample, ReceiverOrigin, type RunOverCode, SqlMethod, type SqlStatements, type SqlStatementsSpec, type StorageCalls, type StorageCallsSpec, StorageMethod, compile, declarationsIn, examplesMissing, pack, runExamples, sqlStatements, storageCalls };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { InvocationRecognizer, PatternPack } from '@suss/extractor';
+import { InvocationRecognizer, PatternPack, PackDeclarations } from '@suss/extractor';
 export { DeclaredMatch, PackDeclarations, PatternPack } from '@suss/extractor';
-import { a as Chain, S as StorageMethod, L as LinkFunction, C as CallOps, R as ReceiverOrigin } from './chain-DTSij2Mn.js';
-export { A as ArgumentPick, b as ConstructedFrom, c as ContainerLink, D as DeclaredBy, E as Ending, F as FromReceiver, d as Link, M as MatchStart, e as MethodsLink, O as OpsCarrier, f as StartLink, g as StorageEnding, U as UnsettledName, h as constructedFrom, i as declaredBy, o as opsIn } from './chain-DTSij2Mn.js';
+import { a as Chain, M as MethodMeaning, S as SqlMethod, I as InterpolatesLink, R as ReceiverOrigin, b as CallStep, c as StorageMethod, A as ArgumentPick, L as LinkFunction, C as CallOps, O as OneArgument } from './chain-BaxjT_-k.js';
+export { d as AccessKind, e as AccessPathLink, f as ArgumentsFrom, g as ConstructedFrom, h as ContainerArgument, i as ContainerLink, j as ContainerRule, k as ContainersLink, D as DeclaredBy, E as Ending, F as FromReceiver, l as InputLink, m as InputRule, K as KindAsAsked, n as Link, o as MatchStart, p as MethodsLink, q as OpsCarrier, r as SqlEnding, s as StartLink, t as StatedInputs, u as StatedRule, v as StorageEnding, w as SubjectLink, T as ToArgument, x as ToReceiver, U as UnsettledName, V as ValueEntry, y as ValueOps, z as constructedFrom, B as declaredBy, G as opsIn } from './chain-BaxjT_-k.js';
 import { Effect } from '@suss/behavioral-ir';
 
 /**
@@ -13,10 +13,14 @@ import { Effect } from '@suss/behavioral-ir';
  * says which questions to ask, not the order to ask them in. A link
  * that changes what the receiver is, the way Prisma's model property
  * does, will need that order back, and the note here is where to start.
+ *
+ * A chain that states a subject asks its questions of a call next to
+ * the one in hand, so the walk lives here. The README beside this file
+ * says what each step reaches and why the walk is bounded.
  */
 
 /** A chain, as the hook the adapter dispatches to on every call. */
-declare function compile(chain: Chain<StorageMethod>, recognition: string): InvocationRecognizer;
+declare function compile(chain: Chain<MethodMeaning>, recognition: string): InvocationRecognizer;
 
 /**
  * Running the example that comes with every declaration.
@@ -49,6 +53,109 @@ declare function runExamples(pack: PatternPack, run: RunOverCode): RanExample[];
 /** The declarations a pack shipped without a line of code to run. */
 declare function examplesMissing(pack: PatternPack): string[];
 
+/**
+ * Assembling declared chains into the pack the adapters load.
+ *
+ * Everything a `PatternPack` needs beyond the chains is either already
+ * in them or the same for every declared pack: the modules the client
+ * came from are the import gate, the store's wire is the protocol, and
+ * a pack of recognizers discovers nothing. What is left is the pack's
+ * own name, the languages it runs on, and the name its effects are
+ * recognized under, which is the npm package callers install.
+ */
+
+/**
+ * One thing a pack matches, as whichever entry point built it hands it
+ * over. `storageCalls` and `sqlStatements` both come out as this.
+ */
+interface Match {
+    readonly declared: Chain<MethodMeaning>;
+}
+/** What a pack says about itself, beyond the calls it matches. */
+interface PackSpec {
+    /** The languages the pack runs on, as the adapters name them. */
+    languages: string[];
+    /**
+     * The name effects from this pack are recorded under, which is the
+     * npm package a user installs.
+     */
+    recognizedAs: string;
+    /**
+     * What the pack calls this build of itself. The extraction cache keys
+     * on it, so a pack that never stamps one serves an earlier build's
+     * results after an edit.
+     */
+    version?: string;
+    /**
+     * What the pack itself speaks, when that is not the wire its accesses
+     * record. An S3 access goes over the AWS SDK and says so on every
+     * effect, while the pack speaks S3.
+     */
+    protocol?: string;
+    /**
+     * Further modules whose presence makes a file worth reading, beyond
+     * the ones the chains match on. A helper a project reaches by a
+     * relative path gives the gate nothing; the library that helper
+     * imports gives it something.
+     */
+    requiresImport?: string[];
+}
+/** A pack, assembled from the calls it says it matches. */
+declare function pack(name: string, matches: readonly Match[], spec: PackSpec): PatternPack;
+/**
+ * What a set of chains cost, for a pack that assembles itself. A pack
+ * part way through the migration still has a hand-rolled walk beside
+ * its declarations, and this is how the part that moved is priced.
+ */
+declare function declarationsIn(matches: readonly Match[]): PackDeclarations;
+
+/**
+ * The entry point for a pack whose calls hand the store a statement
+ * written as SQL.
+ *
+ * A typed client says what it reached in its arguments, so the chain
+ * asks the call. A raw statement says it in the text, so the chain
+ * hands the text to `@suss/sql` and the parse settles the container,
+ * the kind, the fields and the selector of every table the statement
+ * touches. The links up to that point are the same ones every chain
+ * states, which is why this is an ending rather than a grammar of its
+ * own.
+ */
+
+/** What a pack says about the store its statements reach. */
+interface SqlStatementsSpec {
+    /** The store, in the words OpenTelemetry's semantic conventions use. */
+    system: string;
+    /** The wire, when it differs from the store's own name. */
+    transport?: string;
+    /** Which of the store's namespaces the calls reach. Defaults to "default". */
+    scope?: string;
+    /**
+     * Which dialect the statements are written in. Wherever the store is
+     * the database this is the store's own name again, and a pack says it
+     * anyway: a store whose statements are somebody else's SQL is common
+     * enough that a default here would read the wrong tables quietly.
+     */
+    dialect: string;
+    /** How the pack pins down the client its calls are on. */
+    client?: ReceiverOrigin;
+}
+/** A chain over statements, and the links that can still be added. */
+interface SqlStatements {
+    /** Which methods take a statement, and where each one states it. */
+    methods(table: Readonly<Record<string, SqlMethod>>, options?: {
+        ignoringCase?: boolean;
+    }): SqlStatements;
+    /** What the values a statement interpolates come to. */
+    interpolating(says: Omit<InterpolatesLink, "asks">): SqlStatements;
+    /** A line of code this matches, which the pack's tests run. */
+    example(code: string): SqlStatements;
+    /** The links and the ending, as data. */
+    readonly declared: Chain<SqlMethod>;
+}
+/** A pack that recognizes statements written as SQL. */
+declare function sqlStatements(spec: SqlStatementsSpec): SqlStatements;
+
 /**
  * The entry point for a pack that recognizes storage calls, and the
  * chain it builds.
@@ -67,8 +174,12 @@ interface StorageCallsSpec {
     transport?: string;
     /** Which of the store's namespaces the calls reach. Defaults to "default". */
     scope?: string;
-    /** How the pack pins down the client its calls are on. */
-    client: ReceiverOrigin;
+    /**
+     * How the pack pins down the client its calls are on. A pack that
+     * matches a helper a project lists in its own config leaves this out,
+     * because the name that project gave is the whole of what it has.
+     */
+    client?: ReceiverOrigin;
     /**
      * What a reader gives back for a name nothing settles. Defaults to
      * "reference", which says which value to go and ask about.
@@ -77,15 +188,35 @@ interface StorageCallsSpec {
 }
 /** A storage chain, and the links that can still be added to it. */
 interface StorageCalls {
+    /**
+     * Which call the chain is about, when it is not the one in hand. The
+     * steps run from the call in hand, and every other link is asked of
+     * what they reach.
+     */
+    about(...of: readonly CallStep[]): StorageCalls;
     /** Which methods count, and what each one reads or writes. */
     methods(table: Readonly<Record<string, StorageMethod>>, options?: {
         ignoringCase?: boolean;
     }): StorageCalls;
     /**
-     * Which container a call's selector belongs to. Without this the
-     * first name a call reached is the container.
+     * Which container a call's selector belongs to, as an argument or as
+     * the pack's own rule. Without this the first name a call reached is
+     * the container.
+     */
+    container(says: ArgumentPick | LinkFunction<[readonly string[], CallOps], string | null>): StorageCalls;
+    /** Which way into the container the call took, when it states one. */
+    accessPath(says: ArgumentPick): StorageCalls;
+    /**
+     * Where a call that reaches several containers at once states them.
+     * Each entry becomes one effect, against the container its key says.
+     */
+    containersIn(says: OneArgument): StorageCalls;
+    /**
+     * Where a call states its inputs, when it states them as one object.
+     * A call that states none does not match, and a rule the pack wrote
+     * over the inputs is handed the object.
      */
-    container(from: LinkFunction<[readonly string[], CallOps], string | null>): StorageCalls;
+    input(says: OneArgument): StorageCalls;
     /** A line of code this matches, which the pack's tests run. */
     example(code: string): StorageCalls;
     /** The links and the ending, as data. */
@@ -94,34 +225,4 @@ interface StorageCalls {
 /** A pack that recognizes calls against a store. */
 declare function storageCalls(spec: StorageCallsSpec): StorageCalls;
 
-/**
- * Assembling declared chains into the pack the adapters load.
- *
- * Everything a `PatternPack` needs beyond the chains is either already
- * in them or the same for every declared pack: the modules the client
- * came from are the import gate, the store's wire is the protocol, and
- * a pack of recognizers discovers nothing. What is left is the pack's
- * own name, the languages it runs on, and the name its effects are
- * recognized under, which is the npm package callers install.
- */
-
-/** What a pack says about itself, beyond the calls it matches. */
-interface PackSpec {
-    /** The languages the pack runs on, as the adapters name them. */
-    languages: string[];
-    /**
-     * The name effects from this pack are recorded under, which is the
-     * npm package a user installs.
-     */
-    recognizedAs: string;
-    /**
-     * What the pack calls this build of itself. The extraction cache keys
-     * on it, so a pack that never stamps one serves an earlier build's
-     * results after an edit.
-     */
-    version?: string;
-}
-/** A pack, assembled from the calls it says it matches. */
-declare function pack(name: string, matches: readonly StorageCalls[], spec: PackSpec): PatternPack;
-
-export { CallOps, Chain, LinkFunction, type PackSpec, type RanExample, ReceiverOrigin, type RunOverCode, type StorageCalls, type StorageCallsSpec, StorageMethod, compile, examplesMissing, pack, runExamples, storageCalls };
+export { ArgumentPick, CallOps, CallStep, Chain, InterpolatesLink, LinkFunction, type Match, MethodMeaning, OneArgument, type PackSpec, type RanExample, ReceiverOrigin, type RunOverCode, SqlMethod, type SqlStatements, type SqlStatementsSpec, type StorageCalls, type StorageCallsSpec, StorageMethod, compile, declarationsIn, examplesMissing, pack, runExamples, sqlStatements, storageCalls };