@suss/recognize 0.20.0 → 0.21.1

package/dist/ast.d.cts

@@ -1,5 +1,5 @@
 import { CallOps } from '@suss/extractor';
-import { L as LinkFunction } from './chain-_S93eC3O.cjs';
+import { L as LinkFunction } from './chain-IogmSi0t.cjs';
 import '@suss/behavioral-ir';
 
 /**

package/dist/ast.d.ts

@@ -1,5 +1,5 @@
 import { CallOps } from '@suss/extractor';
-import { L as LinkFunction } from './chain-_S93eC3O.js';
+import { L as LinkFunction } from './chain-IogmSi0t.js';
 import '@suss/behavioral-ir';
 
 /**

package/dist/{chain-_S93eC3O.d.cts → chain-IogmSi0t.d.cts}

@@ -1,4 +1,4 @@
-import { MessageBusSemantics } from '@suss/behavioral-ir';
+import { MessageBusSemantics, DeployableUnit } from '@suss/behavioral-ir';
 import { ReceiverOrigin, ValueOps, CallOps, UnsettledName } from '@suss/extractor';
 
 /**
@@ -136,6 +136,13 @@ interface AccessPathLink {
 interface ContainersLink {
     readonly asks: "containers";
     readonly in: OneArgument;
+    /**
+     * What one of them is. An entry keys the container by name and says
+     * what the call did there, which is how a batch write is written. A
+     * name is the container on its own, which is how a call that reads
+     * several parameters at once is written. Defaults to an entry.
+     */
+    readonly each?: "entry" | "name";
 }
 /**
  * Where a call states its inputs, when it states them as one object
@@ -307,9 +314,15 @@ interface MessageSendMethod {
     /** Where the call states the message, or the collection of them. */
     readonly input: OneArgument;
 }
+/**
+ * What one invoke method does. An invoke states its whole request as
+ * one object the same way a send does, so both say where that object
+ * is and nothing else.
+ */
+type UnitInvokeMethod = MessageSendMethod;
 type MethodMeaning = StorageMethod | SqlMethod | MessageSendMethod;
 /** What a chain produces when every link matches. */
-type Ending = StorageEnding | SqlEnding | MessageSendEnding;
+type Ending = StorageEnding | SqlEnding | MessageSendEnding | UnitInvokeEnding;
 /** A storage access: one call, one thing it read or wrote. */
 interface StorageEnding {
     readonly yields: "storageAccess";
@@ -377,8 +390,13 @@ interface ManyIn {
  * the same way, so a pack states the parts in the order they join.
  */
 interface ChannelPart {
-    /** The property the message states this part on. */
-    readonly property: string;
+    /**
+     * The properties the message may state this part on, tried in order.
+     * A library that lets one destination be written more than one way
+     * lists each spelling: an SNS publish writes its topic as `TopicArn`
+     * or as `TargetArn`, and the two are the same part of the channel.
+     */
+    readonly property: readonly string[];
     /**
      * Where the property is written. A batch command states the queue
      * once beside the list of messages, so its channel part reads off
@@ -425,6 +443,29 @@ interface MessageSendEnding {
      */
     readonly unsettledName: UnsettledName;
 }
+/**
+ * A call that hands a payload to one deployed unit, named on the call.
+ *
+ * The unit's name is read off the call's own input rather than off a
+ * message, because there is one callee per call however many messages a
+ * send takes. A name written as a fully-qualified cloud id is reduced
+ * to the resource segment, so an ARN and a bare name come out the same.
+ */
+interface UnitInvokeEnding {
+    readonly yields: "unitInvoke";
+    /** The platform running the unit, in the IR's deployable-unit words. */
+    readonly platform: DeployableUnit["deploymentTarget"];
+    /** The properties the call may name the unit on, tried in order. */
+    readonly named: readonly string[];
+    /** The property the call states its payload on, when the pack can say. */
+    readonly payload?: string;
+    /**
+     * What a reader gives back for a name nothing in the source settles.
+     * A function name usually arrives through an env var, whose name both
+     * sides agree on, so `"reference"` keeps it.
+     */
+    readonly unsettledName: UnsettledName;
+}
 /**
  * A pack's declaration for one kind of call: the links, the ending, and
  * a line of code it matches.
@@ -436,4 +477,4 @@ interface Chain<TMeaning = MethodMeaning> {
     readonly example: string | null;
 }
 
-export type { ArgumentPick as A, StorageEnding as B, Chain as C, SubjectLink as D, Ending as E, FromReceiver as F, ToReceiver as G, InterpolatesLink as I, KindAsAsked as K, LinkFunction as L, MethodMeaning as M, OneArgument as O, SqlMethod as S, ToArgument as T, MessageSendMethod as a, MessageLocation as b, ChannelPart as c, CallStep as d, StorageMethod as e, AccessKind as f, AccessPathLink as g, ArgumentsFrom as h, CallsLink as i, ContainerArgument as j, ContainerLink as k, ContainerRule as l, ContainersLink as m, InputLink as n, InputRule as o, Link as p, ManyIn as q, MatchStart as r, MessageSendEnding as s, MethodsLink as t, OneMessage as u, SelectorParamPick as v, SqlEnding as w, StartLink as x, StatedInputs as y, StatedRule as z };
+export type { ArgumentPick as A, StorageEnding as B, Chain as C, SubjectLink as D, Ending as E, FromReceiver as F, ToReceiver as G, UnitInvokeEnding as H, InterpolatesLink as I, KindAsAsked as K, LinkFunction as L, MethodMeaning as M, OneArgument as O, SqlMethod as S, ToArgument as T, UnitInvokeMethod as U, MessageSendMethod as a, MessageLocation as b, ChannelPart as c, CallStep as d, StorageMethod as e, AccessKind as f, AccessPathLink as g, ArgumentsFrom as h, CallsLink as i, ContainerArgument as j, ContainerLink as k, ContainerRule as l, ContainersLink as m, InputLink as n, InputRule as o, Link as p, ManyIn as q, MatchStart as r, MessageSendEnding as s, MethodsLink as t, OneMessage as u, SelectorParamPick as v, SqlEnding as w, StartLink as x, StatedInputs as y, StatedRule as z };

package/dist/{chain-_S93eC3O.d.ts → chain-IogmSi0t.d.ts}

@@ -1,4 +1,4 @@
-import { MessageBusSemantics } from '@suss/behavioral-ir';
+import { MessageBusSemantics, DeployableUnit } from '@suss/behavioral-ir';
 import { ReceiverOrigin, ValueOps, CallOps, UnsettledName } from '@suss/extractor';
 
 /**
@@ -136,6 +136,13 @@ interface AccessPathLink {
 interface ContainersLink {
     readonly asks: "containers";
     readonly in: OneArgument;
+    /**
+     * What one of them is. An entry keys the container by name and says
+     * what the call did there, which is how a batch write is written. A
+     * name is the container on its own, which is how a call that reads
+     * several parameters at once is written. Defaults to an entry.
+     */
+    readonly each?: "entry" | "name";
 }
 /**
  * Where a call states its inputs, when it states them as one object
@@ -307,9 +314,15 @@ interface MessageSendMethod {
     /** Where the call states the message, or the collection of them. */
     readonly input: OneArgument;
 }
+/**
+ * What one invoke method does. An invoke states its whole request as
+ * one object the same way a send does, so both say where that object
+ * is and nothing else.
+ */
+type UnitInvokeMethod = MessageSendMethod;
 type MethodMeaning = StorageMethod | SqlMethod | MessageSendMethod;
 /** What a chain produces when every link matches. */
-type Ending = StorageEnding | SqlEnding | MessageSendEnding;
+type Ending = StorageEnding | SqlEnding | MessageSendEnding | UnitInvokeEnding;
 /** A storage access: one call, one thing it read or wrote. */
 interface StorageEnding {
     readonly yields: "storageAccess";
@@ -377,8 +390,13 @@ interface ManyIn {
  * the same way, so a pack states the parts in the order they join.
  */
 interface ChannelPart {
-    /** The property the message states this part on. */
-    readonly property: string;
+    /**
+     * The properties the message may state this part on, tried in order.
+     * A library that lets one destination be written more than one way
+     * lists each spelling: an SNS publish writes its topic as `TopicArn`
+     * or as `TargetArn`, and the two are the same part of the channel.
+     */
+    readonly property: readonly string[];
     /**
      * Where the property is written. A batch command states the queue
      * once beside the list of messages, so its channel part reads off
@@ -425,6 +443,29 @@ interface MessageSendEnding {
      */
     readonly unsettledName: UnsettledName;
 }
+/**
+ * A call that hands a payload to one deployed unit, named on the call.
+ *
+ * The unit's name is read off the call's own input rather than off a
+ * message, because there is one callee per call however many messages a
+ * send takes. A name written as a fully-qualified cloud id is reduced
+ * to the resource segment, so an ARN and a bare name come out the same.
+ */
+interface UnitInvokeEnding {
+    readonly yields: "unitInvoke";
+    /** The platform running the unit, in the IR's deployable-unit words. */
+    readonly platform: DeployableUnit["deploymentTarget"];
+    /** The properties the call may name the unit on, tried in order. */
+    readonly named: readonly string[];
+    /** The property the call states its payload on, when the pack can say. */
+    readonly payload?: string;
+    /**
+     * What a reader gives back for a name nothing in the source settles.
+     * A function name usually arrives through an env var, whose name both
+     * sides agree on, so `"reference"` keeps it.
+     */
+    readonly unsettledName: UnsettledName;
+}
 /**
  * A pack's declaration for one kind of call: the links, the ending, and
  * a line of code it matches.
@@ -436,4 +477,4 @@ interface Chain<TMeaning = MethodMeaning> {
     readonly example: string | null;
 }
 
-export type { ArgumentPick as A, StorageEnding as B, Chain as C, SubjectLink as D, Ending as E, FromReceiver as F, ToReceiver as G, InterpolatesLink as I, KindAsAsked as K, LinkFunction as L, MethodMeaning as M, OneArgument as O, SqlMethod as S, ToArgument as T, MessageSendMethod as a, MessageLocation as b, ChannelPart as c, CallStep as d, StorageMethod as e, AccessKind as f, AccessPathLink as g, ArgumentsFrom as h, CallsLink as i, ContainerArgument as j, ContainerLink as k, ContainerRule as l, ContainersLink as m, InputLink as n, InputRule as o, Link as p, ManyIn as q, MatchStart as r, MessageSendEnding as s, MethodsLink as t, OneMessage as u, SelectorParamPick as v, SqlEnding as w, StartLink as x, StatedInputs as y, StatedRule as z };
+export type { ArgumentPick as A, StorageEnding as B, Chain as C, SubjectLink as D, Ending as E, FromReceiver as F, ToReceiver as G, UnitInvokeEnding as H, InterpolatesLink as I, KindAsAsked as K, LinkFunction as L, MethodMeaning as M, OneArgument as O, SqlMethod as S, ToArgument as T, UnitInvokeMethod as U, MessageSendMethod as a, MessageLocation as b, ChannelPart as c, CallStep as d, StorageMethod as e, AccessKind as f, AccessPathLink as g, ArgumentsFrom as h, CallsLink as i, ContainerArgument as j, ContainerLink as k, ContainerRule as l, ContainersLink as m, InputLink as n, InputRule as o, Link as p, ManyIn as q, MatchStart as r, MessageSendEnding as s, MethodsLink as t, OneMessage as u, SelectorParamPick as v, SqlEnding as w, StartLink as x, StatedInputs as y, StatedRule as z };

package/dist/index.cjs

@@ -30,7 +30,8 @@ __export(index_exports, {
   pack: () => pack,
   runExamples: () => runExamples,
   sqlStatements: () => sqlStatements,
-  storageCalls: () => storageCalls
+  storageCalls: () => storageCalls,
+  unitInvokes: () => unitInvokes
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -192,7 +193,8 @@ function startsHere(chain, subject) {
 var YIELD = {
   storageAccess,
   sqlAccess,
-  messageSend
+  messageSend,
+  unitInvoke
 };
 function storageAccess(matched) {
   const { subject, chain } = matched;
@@ -223,7 +225,7 @@ function accessEffect(matched, access) {
       storageSystem: ending.system,
       ...ending.transport === void 0 ? {} : { transport: ending.transport },
       scope: ending.scope,
-      container: reached.entry === null ? containerOf(chain, selector, subject, unsettled) : reached.container,
+      container: reached.stated ? reached.container : containerOf(chain, selector, subject, unsettled),
       accessPath: accessPathOf(chain, subject, unsettled)
     }),
     callee: ops.calleeText(),
@@ -238,11 +240,24 @@ function accessEffect(matched, access) {
 }
 function reachedBy(chain, subject, unsettled) {
   const link = linkIn(chain, "containers");
-  const map = link === null ? null : statedValue(subject, link.in);
-  if (map === null) {
-    return [{ container: null, entry: null }];
-  }
-  return map.entries(unsettled).map((entry) => ({ container: entry.key, entry: entry.value }));
+  const alone = [{ container: null, entry: null, stated: false }];
+  const stated = link === null ? null : statedValue(subject, link.in);
+  if (link === null || stated === null) {
+    return alone;
+  }
+  if (link.each === "name") {
+    const named = stated.items().map((item) => ({
+      container: item.name(unsettled),
+      entry: null,
+      stated: true
+    }));
+    return named.length === 0 ? alone : named;
+  }
+  return stated.entries(unsettled).map((entry) => ({
+    container: entry.key,
+    entry: entry.value,
+    stated: true
+  }));
 }
 function kindOf(kind, subject, unsettled) {
   if (typeof kind === "string") {
@@ -382,7 +397,7 @@ function channelOf(message, input, ending) {
   const parts = [];
   for (const part of ending.channel) {
     const holder = part.on === "theInput" ? input : message;
-    const written = holder.property(part.property);
+    const written = firstWritten(holder, part.property);
     if (written === null) {
       if (part.whenAbsent === void 0) {
         return null;
@@ -398,6 +413,15 @@ function channelOf(message, input, ending) {
   }
   return parts.join(ending.channelSeparator ?? "#");
 }
+function firstWritten(holder, properties) {
+  for (const property of properties) {
+    const written = holder.property(property);
+    if (written !== null) {
+      return written;
+    }
+  }
+  return null;
+}
 function bodyOf(message, ending) {
   if (ending.body === void 0) {
     return {};
@@ -414,6 +438,50 @@ function routingKeyOf(message, ending) {
   const stated = message.property(ending.routingKey)?.text() ?? null;
   return stated === null || stated === "" ? {} : { routingKey: stated };
 }
+function unitInvoke(matched) {
+  const { ops, subject, chain, recognition } = matched;
+  const ending = chain.ending;
+  const input = statedValue(
+    subject,
+    matched.meaning.input
+  );
+  if (input === null) {
+    return null;
+  }
+  return [
+    {
+      type: "interaction",
+      binding: (0, import_behavioral_ir.unitInvocationBinding)({
+        recognition,
+        deploymentTarget: ending.platform,
+        instanceName: invokedUnitIn(input, ending)
+      }),
+      callee: ops.calleeText(),
+      interaction: {
+        class: "unit-invoke",
+        ...payloadOf(input, ending)
+      }
+    }
+  ];
+}
+function invokedUnitIn(input, ending) {
+  for (const property of ending.named) {
+    const stated = input.property(property)?.name(ending.unsettledName) ?? null;
+    if (stated !== null && stated !== "") {
+      return (0, import_behavioral_ir.resourceNameIn)(stated);
+    }
+  }
+  return null;
+}
+function payloadOf(input, ending) {
+  if (ending.payload === void 0) {
+    return {};
+  }
+  const stated = (0, import_extractor.unwrapJsonStringify)(
+    input.property(ending.payload)?.asArg() ?? null
+  );
+  return stated === null ? {} : { payload: stated };
+}
 function sqlAccess(matched) {
   const { ops, subject, method, chain, recognition } = matched;
   const ending = chain.ending;
@@ -517,7 +585,8 @@ function chainFrom(declared) {
 var DISPATCHED_ON = {
   storageAccess: "invocation",
   sqlAccess: "access",
-  messageSend: "invocation"
+  messageSend: "invocation",
+  unitInvoke: "invocation"
 };
 function walkedBy(chains, walk2, recognizedAs) {
   return chains.filter((chain) => DISPATCHED_ON[chain.ending.yields] === walk2).map((chain) => compile(chain, recognizedAs));
@@ -541,6 +610,7 @@ function pack(name, matches, spec) {
       ...spec.recognizers ?? []
     ],
     ...access.length === 0 ? {} : { accessRecognizers: access },
+    ...spec.projectHelpers === void 0 ? {} : { projectHelpers: spec.projectHelpers },
     declarations: declarationsIn(matches)
   };
 }
@@ -551,10 +621,19 @@ function wireOf(ending) {
   if (ending.yields === "messageSend") {
     return ending.wire;
   }
+  if (ending.yields === "unitInvoke") {
+    return ending.platform;
+  }
   return ending.transport ?? ending.system;
 }
 function declaredName(ending) {
-  return ending.yields === "messageSend" ? ending.wire : ending.system;
+  if (ending.yields === "messageSend") {
+    return ending.wire;
+  }
+  if (ending.yields === "unitInvoke") {
+    return ending.platform;
+  }
+  return ending.system;
 }
 function protocolOf(chains) {
   const wires = new Set(chains.map((chain) => wireOf(chain.ending)));
@@ -716,11 +795,43 @@ function chainFrom3(declared) {
       typeof says === "function" ? { asks: "container", from: says } : { asks: "container", argument: says }
     ),
     accessPath: (says) => adding({ asks: "accessPath", argument: says }),
-    containersIn: (says) => adding({ asks: "containers", in: says }),
+    containersIn: (says, options) => adding({
+      asks: "containers",
+      in: says,
+      each: options?.each ?? "entry"
+    }),
     input: (says) => adding({ asks: "input", at: says }),
     example: (code) => chainFrom3({ ...declared, example: code })
   };
 }
+
+// src/unitInvokes.ts
+function unitInvokes(spec) {
+  const ending = {
+    yields: "unitInvoke",
+    platform: spec.platform,
+    named: spec.named,
+    ...spec.payload === void 0 ? {} : { payload: spec.payload },
+    unsettledName: spec.unsettledName ?? "reference"
+  };
+  return chainFrom4({
+    links: chainStart(spec.client),
+    ending,
+    example: null
+  });
+}
+function chainFrom4(declared) {
+  const adding = (link) => chainFrom4({ ...declared, links: [...declared.links, link] });
+  return {
+    declared,
+    methods: (table, options) => adding({
+      asks: "methods",
+      table,
+      ignoringCase: options?.ignoringCase ?? false
+    }),
+    example: (code) => chainFrom4({ ...declared, example: code })
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   compile,
@@ -733,5 +844,6 @@ function chainFrom3(declared) {
   pack,
   runExamples,
   sqlStatements,
-  storageCalls
+  storageCalls,
+  unitInvokes
 });

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { ConstructedFrom, DeclaredBy, CallOps, InvocationRecognizer, PatternPack, UnsettledName, ReceiverOrigin, PackDeclarations } from '@suss/extractor';
-export { CallOps, ConstructedFrom, DeclaredBy, DeclaredMatch, OpsCarrier, PackDeclarations, PatternPack, ReceiverOrigin, UnsettledName, ValueEntry, ValueOps } from '@suss/extractor';
-import { C as Chain, M as MethodMeaning, a as MessageSendMethod, b as MessageLocation, c as ChannelPart, S as SqlMethod, I as InterpolatesLink, d as CallStep, e as StorageMethod, A as ArgumentPick, L as LinkFunction, O as OneArgument } from './chain-_S93eC3O.cjs';
-export { f as AccessKind, g as AccessPathLink, h as ArgumentsFrom, i as CallsLink, j as ContainerArgument, k as ContainerLink, l as ContainerRule, m as ContainersLink, E as Ending, F as FromReceiver, n as InputLink, o as InputRule, K as KindAsAsked, p as Link, q as ManyIn, r as MatchStart, s as MessageSendEnding, t as MethodsLink, u as OneMessage, v as SelectorParamPick, w as SqlEnding, x as StartLink, y as StatedInputs, z as StatedRule, B as StorageEnding, D as SubjectLink, T as ToArgument, G as ToReceiver } from './chain-_S93eC3O.cjs';
-import { Effect, MessageBusSemantics } from '@suss/behavioral-ir';
+import { ConstructedFrom, DeclaredBy, CallOps, InvocationRecognizer, PatternPack, UnsettledName, ReceiverOrigin, ProjectHelpers, PackDeclarations } from '@suss/extractor';
+export { CallOps, ConstructedFrom, DeclaredBy, DeclaredMatch, HelperDeclarations, HelperSink, HelperValue, OpsCarrier, PackDeclarations, PatternPack, ProjectHelper, ProjectHelpers, ReceiverOrigin, UnsettledName, ValueEntry, ValueOps } from '@suss/extractor';
+import { C as Chain, M as MethodMeaning, a as MessageSendMethod, b as MessageLocation, c as ChannelPart, S as SqlMethod, I as InterpolatesLink, d as CallStep, e as StorageMethod, A as ArgumentPick, L as LinkFunction, O as OneArgument, U as UnitInvokeMethod } from './chain-IogmSi0t.cjs';
+export { f as AccessKind, g as AccessPathLink, h as ArgumentsFrom, i as CallsLink, j as ContainerArgument, k as ContainerLink, l as ContainerRule, m as ContainersLink, E as Ending, F as FromReceiver, n as InputLink, o as InputRule, K as KindAsAsked, p as Link, q as ManyIn, r as MatchStart, s as MessageSendEnding, t as MethodsLink, u as OneMessage, v as SelectorParamPick, w as SqlEnding, x as StartLink, y as StatedInputs, z as StatedRule, B as StorageEnding, D as SubjectLink, T as ToArgument, G as ToReceiver, H as UnitInvokeEnding } from './chain-IogmSi0t.cjs';
+import { Effect, MessageBusSemantics, DeployableUnit } from '@suss/behavioral-ir';
 
 /**
  * The small builders a pack writes its origins with, and the vocabulary
@@ -188,6 +188,12 @@ interface PackSpec {
      * function links, so the cost of staying here is visible.
      */
     recognizers?: InvocationRecognizer[];
+    /**
+     * Functions the project wrote in front of this library, read once
+     * across the project before extraction. What the pack makes of them
+     * joins the chains above for the rest of the run.
+     */
+    projectHelpers?: ProjectHelpers;
 }
 /** A pack, assembled from the calls it says it matches. */
 declare function pack(name: string, matches: readonly Match[], spec: PackSpec): PatternPack;
@@ -303,9 +309,12 @@ interface StorageCalls {
     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.
+     * Each entry becomes one effect, against the container its key says,
+     * or against the name itself where the call lists names alone.
      */
-    containersIn(says: OneArgument): StorageCalls;
+    containersIn(says: OneArgument, options?: {
+        each?: "entry" | "name";
+    }): 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
@@ -320,4 +329,46 @@ interface StorageCalls {
 /** A pack that recognizes calls against a store. */
 declare function storageCalls(spec: StorageCallsSpec): StorageCalls;
 
-export { ArgumentPick, CallStep, Chain, ChannelPart, InterpolatesLink, LinkFunction, type Match, MessageLocation, MessageSendMethod, type MessageSends, type MessageSendsSpec, MethodMeaning, OneArgument, type PackSpec, type RanExample, type RunOverCode, SqlMethod, type SqlStatements, type SqlStatementsSpec, type StorageCalls, type StorageCallsSpec, StorageMethod, compile, constructedFrom, declarationsIn, declaredBy, examplesMissing, messageSends, opsIn, pack, runExamples, sqlStatements, storageCalls };
+/**
+ * unitInvokes.ts: a pack that recognizes a call invoking one deployed
+ * unit by name.
+ *
+ * The AWS SDK shape is the one this was written against, and it is the
+ * same shape a send has: an operation is a command class and its
+ * arguments are one object, so the pack says which command and which of
+ * its properties says which unit the call reaches.
+ *
+ *   client.send(new InvokeCommand({ FunctionName, Payload }))
+ */
+
+interface UnitInvokesSpec {
+    /** The platform running the unit, in the IR's deployable-unit words. */
+    platform: DeployableUnit["deploymentTarget"];
+    /** The properties the call may name the unit on, tried in order. */
+    named: readonly string[];
+    /** The property the call states its payload on. */
+    payload?: string;
+    /**
+     * What a reader gives back for a name nothing settles. Defaults to
+     * keeping the reference, since a function name reaches the code
+     * through an env var far more often than it is written out.
+     */
+    unsettledName?: UnsettledName;
+    /** How the pack pins down the client its calls are on. */
+    client?: ReceiverOrigin;
+}
+/** A chain over invokes, and the links that can still be added. */
+interface UnitInvokes {
+    /** Which methods invoke, and where each one states its request. */
+    methods(table: Readonly<Record<string, UnitInvokeMethod>>, options?: {
+        ignoringCase?: boolean;
+    }): UnitInvokes;
+    /** A line of code this matches, which the pack's tests run. */
+    example(code: string): UnitInvokes;
+    /** The links and the ending, as data. */
+    readonly declared: Chain<UnitInvokeMethod>;
+}
+/** A pack that recognizes a call invoking a deployed unit. */
+declare function unitInvokes(spec: UnitInvokesSpec): UnitInvokes;
+
+export { ArgumentPick, CallStep, Chain, ChannelPart, InterpolatesLink, LinkFunction, type Match, MessageLocation, MessageSendMethod, type MessageSends, type MessageSendsSpec, MethodMeaning, OneArgument, type PackSpec, type RanExample, type RunOverCode, SqlMethod, type SqlStatements, type SqlStatementsSpec, type StorageCalls, type StorageCallsSpec, StorageMethod, UnitInvokeMethod, type UnitInvokes, type UnitInvokesSpec, compile, constructedFrom, declarationsIn, declaredBy, examplesMissing, messageSends, opsIn, pack, runExamples, sqlStatements, storageCalls, unitInvokes };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { ConstructedFrom, DeclaredBy, CallOps, InvocationRecognizer, PatternPack, UnsettledName, ReceiverOrigin, PackDeclarations } from '@suss/extractor';
-export { CallOps, ConstructedFrom, DeclaredBy, DeclaredMatch, OpsCarrier, PackDeclarations, PatternPack, ReceiverOrigin, UnsettledName, ValueEntry, ValueOps } from '@suss/extractor';
-import { C as Chain, M as MethodMeaning, a as MessageSendMethod, b as MessageLocation, c as ChannelPart, S as SqlMethod, I as InterpolatesLink, d as CallStep, e as StorageMethod, A as ArgumentPick, L as LinkFunction, O as OneArgument } from './chain-_S93eC3O.js';
-export { f as AccessKind, g as AccessPathLink, h as ArgumentsFrom, i as CallsLink, j as ContainerArgument, k as ContainerLink, l as ContainerRule, m as ContainersLink, E as Ending, F as FromReceiver, n as InputLink, o as InputRule, K as KindAsAsked, p as Link, q as ManyIn, r as MatchStart, s as MessageSendEnding, t as MethodsLink, u as OneMessage, v as SelectorParamPick, w as SqlEnding, x as StartLink, y as StatedInputs, z as StatedRule, B as StorageEnding, D as SubjectLink, T as ToArgument, G as ToReceiver } from './chain-_S93eC3O.js';
-import { Effect, MessageBusSemantics } from '@suss/behavioral-ir';
+import { ConstructedFrom, DeclaredBy, CallOps, InvocationRecognizer, PatternPack, UnsettledName, ReceiverOrigin, ProjectHelpers, PackDeclarations } from '@suss/extractor';
+export { CallOps, ConstructedFrom, DeclaredBy, DeclaredMatch, HelperDeclarations, HelperSink, HelperValue, OpsCarrier, PackDeclarations, PatternPack, ProjectHelper, ProjectHelpers, ReceiverOrigin, UnsettledName, ValueEntry, ValueOps } from '@suss/extractor';
+import { C as Chain, M as MethodMeaning, a as MessageSendMethod, b as MessageLocation, c as ChannelPart, S as SqlMethod, I as InterpolatesLink, d as CallStep, e as StorageMethod, A as ArgumentPick, L as LinkFunction, O as OneArgument, U as UnitInvokeMethod } from './chain-IogmSi0t.js';
+export { f as AccessKind, g as AccessPathLink, h as ArgumentsFrom, i as CallsLink, j as ContainerArgument, k as ContainerLink, l as ContainerRule, m as ContainersLink, E as Ending, F as FromReceiver, n as InputLink, o as InputRule, K as KindAsAsked, p as Link, q as ManyIn, r as MatchStart, s as MessageSendEnding, t as MethodsLink, u as OneMessage, v as SelectorParamPick, w as SqlEnding, x as StartLink, y as StatedInputs, z as StatedRule, B as StorageEnding, D as SubjectLink, T as ToArgument, G as ToReceiver, H as UnitInvokeEnding } from './chain-IogmSi0t.js';
+import { Effect, MessageBusSemantics, DeployableUnit } from '@suss/behavioral-ir';
 
 /**
  * The small builders a pack writes its origins with, and the vocabulary
@@ -188,6 +188,12 @@ interface PackSpec {
      * function links, so the cost of staying here is visible.
      */
     recognizers?: InvocationRecognizer[];
+    /**
+     * Functions the project wrote in front of this library, read once
+     * across the project before extraction. What the pack makes of them
+     * joins the chains above for the rest of the run.
+     */
+    projectHelpers?: ProjectHelpers;
 }
 /** A pack, assembled from the calls it says it matches. */
 declare function pack(name: string, matches: readonly Match[], spec: PackSpec): PatternPack;
@@ -303,9 +309,12 @@ interface StorageCalls {
     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.
+     * Each entry becomes one effect, against the container its key says,
+     * or against the name itself where the call lists names alone.
      */
-    containersIn(says: OneArgument): StorageCalls;
+    containersIn(says: OneArgument, options?: {
+        each?: "entry" | "name";
+    }): 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
@@ -320,4 +329,46 @@ interface StorageCalls {
 /** A pack that recognizes calls against a store. */
 declare function storageCalls(spec: StorageCallsSpec): StorageCalls;
 
-export { ArgumentPick, CallStep, Chain, ChannelPart, InterpolatesLink, LinkFunction, type Match, MessageLocation, MessageSendMethod, type MessageSends, type MessageSendsSpec, MethodMeaning, OneArgument, type PackSpec, type RanExample, type RunOverCode, SqlMethod, type SqlStatements, type SqlStatementsSpec, type StorageCalls, type StorageCallsSpec, StorageMethod, compile, constructedFrom, declarationsIn, declaredBy, examplesMissing, messageSends, opsIn, pack, runExamples, sqlStatements, storageCalls };
+/**
+ * unitInvokes.ts: a pack that recognizes a call invoking one deployed
+ * unit by name.
+ *
+ * The AWS SDK shape is the one this was written against, and it is the
+ * same shape a send has: an operation is a command class and its
+ * arguments are one object, so the pack says which command and which of
+ * its properties says which unit the call reaches.
+ *
+ *   client.send(new InvokeCommand({ FunctionName, Payload }))
+ */
+
+interface UnitInvokesSpec {
+    /** The platform running the unit, in the IR's deployable-unit words. */
+    platform: DeployableUnit["deploymentTarget"];
+    /** The properties the call may name the unit on, tried in order. */
+    named: readonly string[];
+    /** The property the call states its payload on. */
+    payload?: string;
+    /**
+     * What a reader gives back for a name nothing settles. Defaults to
+     * keeping the reference, since a function name reaches the code
+     * through an env var far more often than it is written out.
+     */
+    unsettledName?: UnsettledName;
+    /** How the pack pins down the client its calls are on. */
+    client?: ReceiverOrigin;
+}
+/** A chain over invokes, and the links that can still be added. */
+interface UnitInvokes {
+    /** Which methods invoke, and where each one states its request. */
+    methods(table: Readonly<Record<string, UnitInvokeMethod>>, options?: {
+        ignoringCase?: boolean;
+    }): UnitInvokes;
+    /** A line of code this matches, which the pack's tests run. */
+    example(code: string): UnitInvokes;
+    /** The links and the ending, as data. */
+    readonly declared: Chain<UnitInvokeMethod>;
+}
+/** A pack that recognizes a call invoking a deployed unit. */
+declare function unitInvokes(spec: UnitInvokesSpec): UnitInvokes;
+
+export { ArgumentPick, CallStep, Chain, ChannelPart, InterpolatesLink, LinkFunction, type Match, MessageLocation, MessageSendMethod, type MessageSends, type MessageSendsSpec, MethodMeaning, OneArgument, type PackSpec, type RanExample, type RunOverCode, SqlMethod, type SqlStatements, type SqlStatementsSpec, type StorageCalls, type StorageCallsSpec, StorageMethod, UnitInvokeMethod, type UnitInvokes, type UnitInvokesSpec, compile, constructedFrom, declarationsIn, declaredBy, examplesMissing, messageSends, opsIn, pack, runExamples, sqlStatements, storageCalls, unitInvokes };

package/dist/index.js

@@ -1,5 +1,10 @@
 // src/compile.ts
-import { messageBusBinding, storageBinding } from "@suss/behavioral-ir";
+import {
+  messageBusBinding,
+  resourceNameIn,
+  storageBinding,
+  unitInvocationBinding
+} from "@suss/behavioral-ir";
 import { unwrapJsonStringify } from "@suss/extractor";
 import { readSqlAccess, sqlFromParts } from "@suss/sql";
 
@@ -156,7 +161,8 @@ function startsHere(chain, subject) {
 var YIELD = {
   storageAccess,
   sqlAccess,
-  messageSend
+  messageSend,
+  unitInvoke
 };
 function storageAccess(matched) {
   const { subject, chain } = matched;
@@ -187,7 +193,7 @@ function accessEffect(matched, access) {
       storageSystem: ending.system,
       ...ending.transport === void 0 ? {} : { transport: ending.transport },
       scope: ending.scope,
-      container: reached.entry === null ? containerOf(chain, selector, subject, unsettled) : reached.container,
+      container: reached.stated ? reached.container : containerOf(chain, selector, subject, unsettled),
       accessPath: accessPathOf(chain, subject, unsettled)
     }),
     callee: ops.calleeText(),
@@ -202,11 +208,24 @@ function accessEffect(matched, access) {
 }
 function reachedBy(chain, subject, unsettled) {
   const link = linkIn(chain, "containers");
-  const map = link === null ? null : statedValue(subject, link.in);
-  if (map === null) {
-    return [{ container: null, entry: null }];
-  }
-  return map.entries(unsettled).map((entry) => ({ container: entry.key, entry: entry.value }));
+  const alone = [{ container: null, entry: null, stated: false }];
+  const stated = link === null ? null : statedValue(subject, link.in);
+  if (link === null || stated === null) {
+    return alone;
+  }
+  if (link.each === "name") {
+    const named = stated.items().map((item) => ({
+      container: item.name(unsettled),
+      entry: null,
+      stated: true
+    }));
+    return named.length === 0 ? alone : named;
+  }
+  return stated.entries(unsettled).map((entry) => ({
+    container: entry.key,
+    entry: entry.value,
+    stated: true
+  }));
 }
 function kindOf(kind, subject, unsettled) {
   if (typeof kind === "string") {
@@ -346,7 +365,7 @@ function channelOf(message, input, ending) {
   const parts = [];
   for (const part of ending.channel) {
     const holder = part.on === "theInput" ? input : message;
-    const written = holder.property(part.property);
+    const written = firstWritten(holder, part.property);
     if (written === null) {
       if (part.whenAbsent === void 0) {
         return null;
@@ -362,6 +381,15 @@ function channelOf(message, input, ending) {
   }
   return parts.join(ending.channelSeparator ?? "#");
 }
+function firstWritten(holder, properties) {
+  for (const property of properties) {
+    const written = holder.property(property);
+    if (written !== null) {
+      return written;
+    }
+  }
+  return null;
+}
 function bodyOf(message, ending) {
   if (ending.body === void 0) {
     return {};
@@ -378,6 +406,50 @@ function routingKeyOf(message, ending) {
   const stated = message.property(ending.routingKey)?.text() ?? null;
   return stated === null || stated === "" ? {} : { routingKey: stated };
 }
+function unitInvoke(matched) {
+  const { ops, subject, chain, recognition } = matched;
+  const ending = chain.ending;
+  const input = statedValue(
+    subject,
+    matched.meaning.input
+  );
+  if (input === null) {
+    return null;
+  }
+  return [
+    {
+      type: "interaction",
+      binding: unitInvocationBinding({
+        recognition,
+        deploymentTarget: ending.platform,
+        instanceName: invokedUnitIn(input, ending)
+      }),
+      callee: ops.calleeText(),
+      interaction: {
+        class: "unit-invoke",
+        ...payloadOf(input, ending)
+      }
+    }
+  ];
+}
+function invokedUnitIn(input, ending) {
+  for (const property of ending.named) {
+    const stated = input.property(property)?.name(ending.unsettledName) ?? null;
+    if (stated !== null && stated !== "") {
+      return resourceNameIn(stated);
+    }
+  }
+  return null;
+}
+function payloadOf(input, ending) {
+  if (ending.payload === void 0) {
+    return {};
+  }
+  const stated = unwrapJsonStringify(
+    input.property(ending.payload)?.asArg() ?? null
+  );
+  return stated === null ? {} : { payload: stated };
+}
 function sqlAccess(matched) {
   const { ops, subject, method, chain, recognition } = matched;
   const ending = chain.ending;
@@ -481,7 +553,8 @@ function chainFrom(declared) {
 var DISPATCHED_ON = {
   storageAccess: "invocation",
   sqlAccess: "access",
-  messageSend: "invocation"
+  messageSend: "invocation",
+  unitInvoke: "invocation"
 };
 function walkedBy(chains, walk2, recognizedAs) {
   return chains.filter((chain) => DISPATCHED_ON[chain.ending.yields] === walk2).map((chain) => compile(chain, recognizedAs));
@@ -505,6 +578,7 @@ function pack(name, matches, spec) {
       ...spec.recognizers ?? []
     ],
     ...access.length === 0 ? {} : { accessRecognizers: access },
+    ...spec.projectHelpers === void 0 ? {} : { projectHelpers: spec.projectHelpers },
     declarations: declarationsIn(matches)
   };
 }
@@ -515,10 +589,19 @@ function wireOf(ending) {
   if (ending.yields === "messageSend") {
     return ending.wire;
   }
+  if (ending.yields === "unitInvoke") {
+    return ending.platform;
+  }
   return ending.transport ?? ending.system;
 }
 function declaredName(ending) {
-  return ending.yields === "messageSend" ? ending.wire : ending.system;
+  if (ending.yields === "messageSend") {
+    return ending.wire;
+  }
+  if (ending.yields === "unitInvoke") {
+    return ending.platform;
+  }
+  return ending.system;
 }
 function protocolOf(chains) {
   const wires = new Set(chains.map((chain) => wireOf(chain.ending)));
@@ -680,11 +763,43 @@ function chainFrom3(declared) {
       typeof says === "function" ? { asks: "container", from: says } : { asks: "container", argument: says }
     ),
     accessPath: (says) => adding({ asks: "accessPath", argument: says }),
-    containersIn: (says) => adding({ asks: "containers", in: says }),
+    containersIn: (says, options) => adding({
+      asks: "containers",
+      in: says,
+      each: options?.each ?? "entry"
+    }),
     input: (says) => adding({ asks: "input", at: says }),
     example: (code) => chainFrom3({ ...declared, example: code })
   };
 }
+
+// src/unitInvokes.ts
+function unitInvokes(spec) {
+  const ending = {
+    yields: "unitInvoke",
+    platform: spec.platform,
+    named: spec.named,
+    ...spec.payload === void 0 ? {} : { payload: spec.payload },
+    unsettledName: spec.unsettledName ?? "reference"
+  };
+  return chainFrom4({
+    links: chainStart(spec.client),
+    ending,
+    example: null
+  });
+}
+function chainFrom4(declared) {
+  const adding = (link) => chainFrom4({ ...declared, links: [...declared.links, link] });
+  return {
+    declared,
+    methods: (table, options) => adding({
+      asks: "methods",
+      table,
+      ignoringCase: options?.ignoringCase ?? false
+    }),
+    example: (code) => chainFrom4({ ...declared, example: code })
+  };
+}
 export {
   compile,
   constructedFrom,
@@ -696,5 +811,6 @@ export {
   pack,
   runExamples,
   sqlStatements,
-  storageCalls
+  storageCalls,
+  unitInvokes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/recognize",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "type": "module",
   "description": "Write a pack as data: a chain of named links that any language adapter with the executor ops can run.",
   "keywords": [
@@ -49,9 +49,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.20.0",
-    "@suss/extractor": "0.20.0",
-    "@suss/sql": "0.20.0"
+    "@suss/behavioral-ir": "0.21.1",
+    "@suss/extractor": "0.21.1",
+    "@suss/sql": "0.21.1"
   },
   "devDependencies": {
     "tsup": "*",