@suss/recognize 0.31.2 → 0.33.0

package/README.md

@@ -35,10 +35,10 @@ implement the ops.
 
 ## More
 
-- [Write a pack](https://nimbuscloud-ai.github.io/suss/guides/writing-a-pack)
-- [How packs work](https://nimbuscloud-ai.github.io/suss/packs)
+- [Write a pack](https://suss.sh/packs/write-a-pack)
+- [How packs work](https://suss.sh/packs/what-a-pack-is)
 - [What a declaration compiles to](./DESIGN.md)
-- [Documentation](https://nimbuscloud-ai.github.io/suss/)
+- [Documentation](https://suss.sh/)
 - [Source and issues](https://github.com/nimbuscloud-ai/suss)
 
 ![coverage](../../.github/badges/coverage-recognize.svg)

package/dist/ast.d.cts

@@ -1,5 +1,5 @@
 import { CallOps } from '@suss/extractor';
-import { L as LinkFunction } from './chain-IogmSi0t.cjs';
+import { L as LinkFunction } from './chain-CVG6Jnr-.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-IogmSi0t.js';
+import { L as LinkFunction } from './chain-CVG6Jnr-.js';
 import '@suss/behavioral-ir';
 
 /**

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

@@ -126,6 +126,17 @@ interface AccessPathLink {
     readonly asks: "accessPath";
     readonly argument: ArgumentPick;
 }
+/**
+ * Which of the store's namespaces a call reached, when the call says
+ * rather than the pack. Most clients connect to one namespace and the
+ * pack states it once, but a BigQuery caller names the dataset on the
+ * way to the table, so a project reading two datasets would otherwise
+ * record both accesses under the same scope.
+ */
+interface ScopeLink {
+    readonly asks: "scope";
+    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
@@ -172,7 +183,7 @@ interface InterpolatesLink {
     readonly from?: ReceiverOrigin;
 }
 /** One question in a chain, and the answer the pack gave for it. */
-type Link<TMeaning> = StartLink | SubjectLink | MethodsLink<TMeaning> | CallsLink<TMeaning> | ContainerLink | AccessPathLink | ContainersLink | InputLink | InterpolatesLink;
+type Link<TMeaning> = StartLink | SubjectLink | MethodsLink<TMeaning> | CallsLink<TMeaning> | ContainerLink | AccessPathLink | ScopeLink | ContainersLink | InputLink | InterpolatesLink;
 /**
  * The meaning of a bare call of the tracked client itself. A store
  * hook is the case: `useAppStore((s) => s.bears)` reaches for no
@@ -305,8 +316,13 @@ 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.
+     *
+     * A list is tried in order until one of the picks reaches text. One
+     * library takes the statement either way round: `query(sql)` and
+     * `query({ query: sql })` are the same call, and the pack says both
+     * rather than picking whichever its author happened to meet first.
      */
-    readonly statement: OneArgument;
+    readonly statement: OneArgument | readonly OneArgument[];
 }
 /** What one method table can say a method does. */
 /** What one send method does, as the message-send ending reads it. */
@@ -477,4 +493,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, 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 };
+export type { ArgumentPick as A, StatedRule as B, Chain as C, StorageEnding as D, Ending as E, FromReceiver as F, SubjectLink as G, ToReceiver as H, InterpolatesLink as I, UnitInvokeEnding as J, 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, ScopeLink as v, SelectorParamPick as w, SqlEnding as x, StartLink as y, StatedInputs as z };

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

@@ -126,6 +126,17 @@ interface AccessPathLink {
     readonly asks: "accessPath";
     readonly argument: ArgumentPick;
 }
+/**
+ * Which of the store's namespaces a call reached, when the call says
+ * rather than the pack. Most clients connect to one namespace and the
+ * pack states it once, but a BigQuery caller names the dataset on the
+ * way to the table, so a project reading two datasets would otherwise
+ * record both accesses under the same scope.
+ */
+interface ScopeLink {
+    readonly asks: "scope";
+    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
@@ -172,7 +183,7 @@ interface InterpolatesLink {
     readonly from?: ReceiverOrigin;
 }
 /** One question in a chain, and the answer the pack gave for it. */
-type Link<TMeaning> = StartLink | SubjectLink | MethodsLink<TMeaning> | CallsLink<TMeaning> | ContainerLink | AccessPathLink | ContainersLink | InputLink | InterpolatesLink;
+type Link<TMeaning> = StartLink | SubjectLink | MethodsLink<TMeaning> | CallsLink<TMeaning> | ContainerLink | AccessPathLink | ScopeLink | ContainersLink | InputLink | InterpolatesLink;
 /**
  * The meaning of a bare call of the tracked client itself. A store
  * hook is the case: `useAppStore((s) => s.bears)` reaches for no
@@ -305,8 +316,13 @@ 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.
+     *
+     * A list is tried in order until one of the picks reaches text. One
+     * library takes the statement either way round: `query(sql)` and
+     * `query({ query: sql })` are the same call, and the pack says both
+     * rather than picking whichever its author happened to meet first.
      */
-    readonly statement: OneArgument;
+    readonly statement: OneArgument | readonly OneArgument[];
 }
 /** What one method table can say a method does. */
 /** What one send method does, as the message-send ending reads it. */
@@ -477,4 +493,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, 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 };
+export type { ArgumentPick as A, StatedRule as B, Chain as C, StorageEnding as D, Ending as E, FromReceiver as F, SubjectLink as G, ToReceiver as H, InterpolatesLink as I, UnitInvokeEnding as J, 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, ScopeLink as v, SelectorParamPick as w, SqlEnding as x, StartLink as y, StatedInputs as z };

package/dist/index.cjs

@@ -224,7 +224,7 @@ function accessEffect(matched, access) {
       recognition,
       storageSystem: ending.system,
       ...ending.transport === void 0 ? {} : { transport: ending.transport },
-      scope: ending.scope,
+      scope: scopeOf(chain, subject, unsettled) ?? ending.scope,
       container: reached.stated ? reached.container : containerOf(chain, selector, subject, unsettled),
       accessPath: accessPathOf(chain, subject, unsettled)
     }),
@@ -282,6 +282,10 @@ function accessPathOf(chain, subject, unsettled) {
   const link = linkIn(chain, "accessPath");
   return link === null ? null : namesAt(subject, link.argument, unsettled)[0] ?? null;
 }
+function scopeOf(chain, subject, unsettled) {
+  const link = linkIn(chain, "scope");
+  return link === null ? null : namesAt(subject, link.argument, unsettled)[0] ?? null;
+}
 function statedValue(subject, pick) {
   for (const ops of walk([subject], pick.of ?? [])) {
     const stated = ops.valueAt(pick.at);
@@ -485,12 +489,15 @@ function payloadOf(input, ending) {
 function sqlAccess(matched) {
   const { ops, subject, method, chain, recognition } = matched;
   const ending = chain.ending;
-  const stated = statedValue(subject, matched.meaning.statement);
-  const parts = stated?.parts() ?? null;
-  if (stated === null || parts === null) {
+  const stated = statementIn(subject, matched.meaning.statement);
+  if (stated === null) {
     return null;
   }
-  const statement = (0, import_sql.sqlFromParts)(parts, namesInHoles(chain, stated));
+  const statement = (0, import_sql.sqlFromParts)(
+    stated.parts,
+    namesInHoles(chain, stated.value),
+    settledHoles(stated.value)
+  );
   const accesses = (0, import_sql.readSqlAccess)(statement, { dialect: ending.dialect });
   return accesses.length === 0 ? null : accesses.map((access) => ({
     type: "interaction",
@@ -498,7 +505,10 @@ function sqlAccess(matched) {
       recognition,
       storageSystem: ending.system,
       ...ending.transport === void 0 ? {} : { transport: ending.transport },
-      scope: ending.scope,
+      // A statement that qualifies its table says which namespace
+      // the access is in, and the pack's own scope is the fallback
+      // for a statement that leaves it out.
+      scope: access.qualifier[access.qualifier.length - 1] ?? ending.scope,
       container: access.table
     }),
     callee: ops.calleeText(),
@@ -511,6 +521,20 @@ function sqlAccess(matched) {
     }
   }));
 }
+function statementIn(subject, says) {
+  const picks = Array.isArray(says) ? says : [says];
+  for (const pick of picks) {
+    const value = statedValue(subject, pick);
+    const parts = value?.parts() ?? null;
+    if (value !== null && parts !== null) {
+      return { value, parts };
+    }
+  }
+  return null;
+}
+function settledHoles(stated) {
+  return (stated.interpolated?.() ?? []).map((hole) => hole.name("nothing"));
+}
 function namesInHoles(chain, stated) {
   const link = linkIn(chain, "interpolates");
   if (link === null) {
@@ -795,6 +819,7 @@ function chainFrom3(declared) {
       typeof says === "function" ? { asks: "container", from: says } : { asks: "container", argument: says }
     ),
     accessPath: (says) => adding({ asks: "accessPath", argument: says }),
+    scope: (says) => adding({ asks: "scope", argument: says }),
     containersIn: (says, options) => adding({
       asks: "containers",
       in: says,

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 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 { 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-CVG6Jnr-.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 ScopeLink, w as SelectorParamPick, x as SqlEnding, y as StartLink, z as StatedInputs, B as StatedRule, D as StorageEnding, G as SubjectLink, T as ToArgument, H as ToReceiver, J as UnitInvokeEnding } from './chain-CVG6Jnr-.cjs';
 import { Effect, MessageBusSemantics, DeployableUnit } from '@suss/behavioral-ir';
 
 /**
@@ -307,6 +307,12 @@ interface StorageCalls {
     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;
+    /**
+     * Which namespace the call reached, when the call says rather than
+     * the pack. Without this every access records the scope the chain
+     * was built with.
+     */
+    scope(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,

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 { 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-CVG6Jnr-.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 ScopeLink, w as SelectorParamPick, x as SqlEnding, y as StartLink, z as StatedInputs, B as StatedRule, D as StorageEnding, G as SubjectLink, T as ToArgument, H as ToReceiver, J as UnitInvokeEnding } from './chain-CVG6Jnr-.js';
 import { Effect, MessageBusSemantics, DeployableUnit } from '@suss/behavioral-ir';
 
 /**
@@ -307,6 +307,12 @@ interface StorageCalls {
     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;
+    /**
+     * Which namespace the call reached, when the call says rather than
+     * the pack. Without this every access records the scope the chain
+     * was built with.
+     */
+    scope(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,

package/dist/index.js

@@ -192,7 +192,7 @@ function accessEffect(matched, access) {
       recognition,
       storageSystem: ending.system,
       ...ending.transport === void 0 ? {} : { transport: ending.transport },
-      scope: ending.scope,
+      scope: scopeOf(chain, subject, unsettled) ?? ending.scope,
       container: reached.stated ? reached.container : containerOf(chain, selector, subject, unsettled),
       accessPath: accessPathOf(chain, subject, unsettled)
     }),
@@ -250,6 +250,10 @@ function accessPathOf(chain, subject, unsettled) {
   const link = linkIn(chain, "accessPath");
   return link === null ? null : namesAt(subject, link.argument, unsettled)[0] ?? null;
 }
+function scopeOf(chain, subject, unsettled) {
+  const link = linkIn(chain, "scope");
+  return link === null ? null : namesAt(subject, link.argument, unsettled)[0] ?? null;
+}
 function statedValue(subject, pick) {
   for (const ops of walk([subject], pick.of ?? [])) {
     const stated = ops.valueAt(pick.at);
@@ -453,12 +457,15 @@ function payloadOf(input, ending) {
 function sqlAccess(matched) {
   const { ops, subject, method, chain, recognition } = matched;
   const ending = chain.ending;
-  const stated = statedValue(subject, matched.meaning.statement);
-  const parts = stated?.parts() ?? null;
-  if (stated === null || parts === null) {
+  const stated = statementIn(subject, matched.meaning.statement);
+  if (stated === null) {
     return null;
   }
-  const statement = sqlFromParts(parts, namesInHoles(chain, stated));
+  const statement = sqlFromParts(
+    stated.parts,
+    namesInHoles(chain, stated.value),
+    settledHoles(stated.value)
+  );
   const accesses = readSqlAccess(statement, { dialect: ending.dialect });
   return accesses.length === 0 ? null : accesses.map((access) => ({
     type: "interaction",
@@ -466,7 +473,10 @@ function sqlAccess(matched) {
       recognition,
       storageSystem: ending.system,
       ...ending.transport === void 0 ? {} : { transport: ending.transport },
-      scope: ending.scope,
+      // A statement that qualifies its table says which namespace
+      // the access is in, and the pack's own scope is the fallback
+      // for a statement that leaves it out.
+      scope: access.qualifier[access.qualifier.length - 1] ?? ending.scope,
       container: access.table
     }),
     callee: ops.calleeText(),
@@ -479,6 +489,20 @@ function sqlAccess(matched) {
     }
   }));
 }
+function statementIn(subject, says) {
+  const picks = Array.isArray(says) ? says : [says];
+  for (const pick of picks) {
+    const value = statedValue(subject, pick);
+    const parts = value?.parts() ?? null;
+    if (value !== null && parts !== null) {
+      return { value, parts };
+    }
+  }
+  return null;
+}
+function settledHoles(stated) {
+  return (stated.interpolated?.() ?? []).map((hole) => hole.name("nothing"));
+}
 function namesInHoles(chain, stated) {
   const link = linkIn(chain, "interpolates");
   if (link === null) {
@@ -763,6 +787,7 @@ function chainFrom3(declared) {
       typeof says === "function" ? { asks: "container", from: says } : { asks: "container", argument: says }
     ),
     accessPath: (says) => adding({ asks: "accessPath", argument: says }),
+    scope: (says) => adding({ asks: "scope", argument: says }),
     containersIn: (says, options) => adding({
       asks: "containers",
       in: says,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/recognize",
-  "version": "0.31.2",
+  "version": "0.33.0",
   "type": "module",
   "description": "Teach suss to read a library you use, by writing a pack as data rather than code, which any language adapter can run.",
   "keywords": [
@@ -51,9 +51,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.31.2",
-    "@suss/extractor": "0.31.2",
-    "@suss/sql": "0.31.2"
+    "@suss/behavioral-ir": "0.33.0",
+    "@suss/extractor": "0.33.0",
+    "@suss/sql": "0.33.0"
   },
   "devDependencies": {
     "tsup": "*",