@suss/ir-core 0.33.0 → 0.34.0

package/dist/index.js

@@ -9,6 +9,7 @@ import {
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
+  IoSemanticsSchema,
   MessageBusSemanticsSchema,
   MetricSemanticsSchema,
   RestSemanticsSchema,
@@ -32,6 +33,8 @@ import {
   formatChannel,
   gqlIdentityKey,
   hasNameHole,
+  ioIdentityKey,
+  isModuleName,
   methodsAgree,
   metricIdentityKey,
   namePatternFromSub,
@@ -59,7 +62,7 @@ import {
   typeDefinitionKey,
   unitIdentityKey,
   withDefinitionsInlined
-} from "./chunk-N564FH5U.js";
+} from "./chunk-WOXA5GBL.js";
 
 // src/semconv.ts
 function semconvAttributes(binding) {
@@ -139,6 +142,9 @@ function boundaryLabel(binding) {
 function displayLabel(binding) {
   return boundaryLabel(binding) ?? `${binding.semantics.name}:${binding.recognition}`;
 }
+function labelWithDetail(binding, detail) {
+  return `${boundaryLabel(binding) ?? binding.semantics.name} ${detail}`;
+}
 function normalizeRuleBoundary(raw) {
   const trimmed = raw.trim();
   for (const behavior of allBehaviors()) {
@@ -319,39 +325,45 @@ var SuppressionSideSchema = z2.object({
 }).optional();
 var SuppressionRuleSchema = z2.object({
   /**
-   * The finding kind to match, behavioural or intent. It is an open
-   * string here because this package is below both IRs, and the loader
-   * is what validates it against the published kind enums.
+   * The finding kind to match, behavioral or intent. The schema accepts
+   * any string because ir-core cannot import either IR's kind enum. The
+   * CLI's loader checks it against both.
    */
   kind: z2.string().optional(),
   /**
-   * Boundary as a human-readable key, e.g. "GET /pet/{petId}" or
-   * "fn:@acme/api::getUser". REST keys are normalized via the same
-   * path normalizer the checkers use, so `:id` and `{id}` compare
-   * equal.
+   * The boundary's human-readable key, such as "GET /pet/{petId}" or
+   * "fn:@acme/api::getUser". A REST key goes through the same path
+   * normalizer the checkers use, so `:id` and `{id}` compare equal.
    */
   boundary: z2.string().optional(),
   /**
-   * Consumer-side discriminators, the narrowest useful match. These
-   * mean something only for behavioural findings: a rule that
-   * specifies `consumer` never matches an intent finding, because an
-   * intent finding has no consumer side.
+   * Consumer-side discriminators, the narrowest useful match. They
+   * apply only to behavioral findings. A rule that sets `consumer`
+   * never matches an intent finding, because an intent finding has no
+   * consumer side.
    */
   consumer: SuppressionSideSchema,
   /**
-   * Provider-side discriminators, the mirror of `consumer`. A finding
-   * about a status the provider produces has its transition id on this
-   * side, and that id is the only handle narrow enough to pick out
-   * that one finding. As with `consumer`, a rule that specifies
-   * `provider` never matches an intent finding.
+   * Provider-side discriminators, matching the same fields as
+   * `consumer`. A finding about a status the provider produces has its
+   * transition id on this side, and that id is the only value narrow
+   * enough to pick out that one finding. As with `consumer`, a rule
+   * that sets `provider` never matches an intent finding.
    */
   provider: SuppressionSideSchema,
   /**
-   * "narrow", the default, requires kind plus one of boundary,
-   * consumer.transitionId, or provider.transitionId, which is enough
-   * to target a specific class of finding. "broad" opts in to
-   * kind-only or boundary-only matches, which also silence future
-   * regressions in that category.
+   * The title of one PRD scenario. A PRD finding's boundary is the
+   * whole PRD, so without this a rule accepts every scenario in it,
+   * including one added later. A rule that sets `scenario` matches
+   * only intent findings about a scenario with that title.
+   */
+  scenario: z2.string().optional(),
+  /**
+   * "narrow", the default, requires `kind` plus one of `boundary`,
+   * `scenario`, `consumer.transitionId` or `provider.transitionId`, so
+   * the rule targets a specific class of finding. "broad" allows a
+   * match on kind alone or boundary alone, and such a rule also
+   * silences future regressions in that category.
    */
   scope: z2.enum(["narrow", "broad"]).default("narrow"),
   /** Required human-written justification. */
@@ -365,18 +377,19 @@ var SuppressionFileSchema = z2.object({
 }).strict();
 function validateRule(rule) {
   if (rule.scope === "broad") {
-    if (rule.kind === void 0 && rule.boundary === void 0 && rule.consumer === void 0 && rule.provider === void 0) {
-      return "broad-scope rule must constrain at least one field (kind, boundary, consumer, or provider)";
+    if (rule.kind === void 0 && rule.boundary === void 0 && rule.scenario === void 0 && rule.consumer === void 0 && rule.provider === void 0) {
+      return "broad-scope rule must constrain at least one field (kind, boundary, scenario, consumer, or provider)";
     }
     return null;
   }
   const hasKind = rule.kind !== void 0;
   const hasBoundary = rule.boundary !== void 0;
+  const hasScenario = rule.scenario !== void 0;
   const hasTransition = rule.consumer?.transitionId !== void 0 || rule.provider?.transitionId !== void 0;
-  if (hasKind && (hasBoundary || hasTransition)) {
+  if (hasKind && (hasBoundary || hasScenario || hasTransition)) {
     return null;
   }
-  return "narrow-scope rule must specify kind AND (boundary OR consumer.transitionId OR provider.transitionId); set scope: 'broad' to silence wider categories";
+  return "narrow-scope rule must specify kind AND (boundary OR scenario OR consumer.transitionId OR provider.transitionId); set scope: 'broad' to silence wider categories";
 }
 function ruleBoundaryMatchesKey(ruleBoundary, key) {
   if (key === null) {
@@ -428,6 +441,12 @@ function countsForThreshold(finding) {
   return finding.suppressed.effect === "downgrade";
 }
 
+// src/testName.ts
+var TEST_TITLE_SEPARATOR = " > ";
+function testUnitName(titles) {
+  return titles.join(TEST_TITLE_SEPARATOR);
+}
+
 // src/typeShapeMatch.ts
 function bodyShapesMatch(actual, declared) {
   if (actual.type === "unknown" || declared.type === "unknown") {
@@ -615,6 +634,14 @@ function packageExportBinding(opts) {
     exportPath: opts.exportPath
   });
 }
+function moduleExportBinding(opts) {
+  return functionCallBinding({
+    transport: "in-process",
+    recognition: opts.recognition,
+    module: opts.module,
+    exportName: opts.exportName
+  });
+}
 function graphqlResolverBinding(opts) {
   return {
     transport: opts.transport,
@@ -697,6 +724,13 @@ function metricBinding(opts) {
     recognition: opts.recognition
   };
 }
+function ioBinding(opts) {
+  return {
+    transport: "in-process",
+    semantics: { name: "io", target: namedOrNull(opts.target, "io target") },
+    recognition: opts.recognition
+  };
+}
 export {
   BoundaryBindingSchema,
   ConfidenceInfoSchema,
@@ -709,6 +743,7 @@ export {
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
+  IoSemanticsSchema,
   MessageBusSemanticsSchema,
   MetricSemanticsSchema,
   NOTHING_DEPLOYED,
@@ -721,6 +756,7 @@ export {
   StorageSemanticsSchema,
   SuppressionFileSchema,
   SuppressionRuleSchema,
+  TEST_TITLE_SEPARATOR,
   TypeShapeSchema,
   UnitInvocationSemanticsSchema,
   applySuppressionsToFindings,
@@ -754,12 +790,17 @@ export {
   groundBinding,
   groundedPairingKey,
   hasNameHole,
+  ioBinding,
+  ioIdentityKey,
   isGraphqlOperationBinding,
+  isModuleName,
+  labelWithDetail,
   leavesTheProcess,
   messageBusBinding,
   methodsAgree,
   metricBinding,
   metricIdentityKey,
+  moduleExportBinding,
   namePatternFromSub,
   namePatternKey,
   nameReference,
@@ -799,6 +840,7 @@ export {
   storageContainerLabel,
   storageLabel,
   storageSystemLabel,
+  testUnitName,
   typeDefinitionKey,
   unitIdentityKey,
   unitInvocationBinding,

package/dist/{schemas-CIns0fqF.d.cts → schemas-CghZNwSE.d.cts}

@@ -40,6 +40,12 @@ declare const FunctionCallSemanticsSchema: z.ZodObject<{
     exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 type FunctionCallSemantics = z.infer<typeof FunctionCallSemanticsSchema>;
+/**
+ * Whether `module` is the name a project gave one of its modules rather
+ * than a path. A path always has a separator in it, and a module name
+ * never does, so a rewrite that makes paths relative leaves a name alone.
+ */
+declare function isModuleName(module: string): boolean;
 
 declare const GraphqlOperationSemanticsSchema: z.ZodObject<{
     name: z.ZodLiteral<"graphql-operation">;
@@ -80,20 +86,19 @@ declare const MessageBusSemanticsSchema: z.ZodObject<{
 }, z.core.$strip>;
 type MessageBusSemantics = z.infer<typeof MessageBusSemanticsSchema>;
 /**
- * The bus technologies the schema allows. It comes from the enum, so a
- * value added there cannot drift from a hand-written copy elsewhere.
+ * The bus technologies the schema allows. It is derived from the enum,
+ * so there is no hand-written copy to fall out of step.
  */
 type MessageBusTechnology = MessageBusSemantics["messageBus"];
 
 /**
- * Where the protocol modules come together.
+ * The list of protocol definitions, and the lookups built from it.
  *
- * Each protocol under this directory exports one
- * `BoundarySemanticsDefinition`. This file lists them twice, once for
- * the schema union and once for the behavior lookup, and the type check
- * at the bottom fails compilation if the two lists ever cover different
- * sets. Adding a protocol changes this file and no other, by one line in
- * each list.
+ * Each protocol module in this directory exports one
+ * `BoundarySemanticsDefinition`. They are listed twice, once for the
+ * schema union and once for the behavior lookup, and the type check at
+ * the bottom fails compilation if the two lists differ. Besides its own
+ * module, a new protocol needs one line in each list.
  */
 
 /**
@@ -171,6 +176,9 @@ declare const SemanticsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>;
     name: z.ZodLiteral<"unit-invocation">;
     instanceName: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"io">;
+    target: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>], "name">;
 type Semantics = z.infer<typeof SemanticsSchema>;
 
@@ -191,44 +199,43 @@ type RestSemantics = z.infer<typeof RestSemanticsSchema>;
  */
 declare function normalizePath(path: string): string;
 /**
- * A path with every parameter reduced to its position. `/users/{id}`
- * and `/users/:userId` both come out `/users/{}`, which is the set of
- * requests each one serves, and what deciding whether two sides
- * describe one endpoint rests on. The name a parameter is written
- * under is worth keeping in a report and worth nothing in a comparison.
- * A parameter's range stays, since `{tenant?}` serves a different set
- * of requests from `{tenant}`.
+ * A path with every parameter name removed, for comparing two paths.
+ * `/users/{id}` and `/users/:userId` both become `/users/{}`, since a
+ * parameter's name does not change which requests the path serves. A
+ * parameter's range stays, since `{tenant?}` serves a different set of
+ * requests from `{tenant}`.
  */
 declare function pathShape(path: string): string;
 /**
  * Whether two REST methods mean the same thing. Equal methods agree,
- * and `"*"` agrees with any stated method, because a handler that
- * responds to every method responds to this one. A null method was never
- * stated, so it agrees with nothing: there is no claim to agree with.
+ * and `"*"` agrees with any given method, because a handler that
+ * responds to every method responds to this one. A null method means
+ * the source never gave one, so it agrees with nothing.
  *
- * This is the counterpart of `busesAgree`. No list of methods appears
- * here, so a wildcard pairs with whatever methods consumers write.
+ * This is the REST counterpart of `busesAgree`. There is no list of
+ * known methods, so a wildcard pairs with whatever methods consumers
+ * write.
  */
 declare function methodsAgree(a: string | null, b: string | null): boolean;
 /**
  * Whether a declared route path admits a concrete request path. Both
- * sides compare on their normalized forms, and a hole in the request
- * is text like any other, so a route inside a mount pattern is admitted
- * by it and a wider route is not.
+ * are normalized first. A hole in the request path is compared as plain
+ * text, so a mount pattern admits a route inside it and rejects a wider
+ * route.
  */
 declare function routePathAdmits(declaredPath: string, requestPath: string): boolean;
 /** Whether two declared route paths serve at least one request in common. */
 declare function routePathsMeet(a: string, b: string): boolean;
 
 /**
- * The pairing key is `(deploymentTarget, instanceName)`, which is
- * exactly a deployable unit, so the two fields come from
- * `DeployableUnitSchema` instead of being written out a second time.
+ * The dedicated pass pairs on `(deploymentTarget, instanceName)`, which
+ * is a deployable unit, so the two fields come from
+ * `DeployableUnitSchema`.
  *
- * A provider states both. The reading side is the code, which knows it
- * reads its configuration and not which deployment will run it, so a
- * recognizer standing at a read leaves both off rather than guessing.
- * The pairing pass takes the deployment from the provider anyway.
+ * A provider sets both. The reading side is code, and code does not say
+ * which deployment will run it, so a recognizer at a read leaves both
+ * out and does not guess. The pairing pass takes the deployment from
+ * the provider.
  */
 declare const RuntimeConfigSemanticsSchema: z.ZodObject<{
     deploymentTarget: z.ZodOptional<z.ZodEnum<{
@@ -252,37 +259,36 @@ declare const StorageSemanticsSchema: z.ZodObject<{
 }, z.core.$strip>;
 type StorageSemantics = z.infer<typeof StorageSemanticsSchema>;
 /**
- * `postgresql:invoices`, `aws.dynamodb:editions#by-publication`. The
- * pairing pass has no key to fall back on here, so a reader who types
- * this back at `suss ask`, the pass that indexes accesses by it, and an
- * intent doc that says which store a write reaches all read this one.
+ * The store's label, such as `postgresql:invoices` or
+ * `aws.dynamodb:editions#by-publication`. Storage has no identity key,
+ * so `suss ask`, the pass that indexes accesses, and an intent doc all
+ * refer to a store by this label.
  */
 declare function storageLabel(semantics: StorageSemantics): string;
-/** The engine, or the words a report writes where nobody settled one. */
+/** The storage system, or `<unknown engine>` when it is null. */
 declare function storageSystemLabel(semantics: StorageSemantics): string;
 /**
- * What an access writes for its columns when it asked for all of them,
- * which is a query with no explicit projection. It covers every column
- * rather than saying which one, so anything comparing column lists has
- * to tell it apart from a list of columns.
+ * The column list an access records when it reads every column, as a
+ * query without an explicit projection does. It means all columns and
+ * does not list any, so code comparing column lists has to handle it
+ * separately.
  */
 declare const EVERY_FIELD = "*";
-/** The store on its own, which a finding writes without the system. */
+/** The store's label without the storage system, as a finding writes it. */
 declare function storageContainerLabel(semantics: StorageSemantics): string;
 
 /**
- * @suss/ir-core schemas: primitives shared by every suss IR.
+ * The zod schemas for the primitives every suss IR uses.
  *
- * These are the types that any IR built on suss references: the
- * structure of a value (`TypeShape`), the identity of a boundary
- * (`BoundaryBinding` and its `Semantics` variants), where something is
- * in the source (`SourceLocation`), and how much to trust a claim
- * (`Confidence`). Behavioural summaries, intent docs, and later on
- * observation records all speak in these terms, so they are defined
- * here, in one place none of those IRs needs another IR to reach.
+ * `TypeShape` is the structure of a value. `BoundaryBinding` and its
+ * `Semantics` variants identify a boundary. `SourceLocation` says where
+ * something is in the source, and `Confidence` says how much to trust a
+ * claim. Behavioral summaries and intent docs are both built from these,
+ * so they live in a package of their own and neither IR depends on the
+ * other.
  *
- * The schemas are the single source of truth, and the package's
- * `index.ts` derives the types from them with `z.infer`.
+ * The schemas are the source of truth. The package index derives the
+ * types from them with `z.infer`.
  */
 
 declare const ConfidenceSourceSchema: z.ZodEnum<{
@@ -297,17 +303,17 @@ declare const ConfidenceLevelSchema: z.ZodEnum<{
     low: "low";
 }>;
 /**
- * What came of corroborating a claim by running the code
- * (`suss corroborate`). Inputs that satisfy the claim's own conditions
- * are generated and run through the function, and the observation
- * either agreed every time (`observed`), disagreed at least once
- * (`refuted`, which is either an extractor bug or a surprise, and the
- * counterexample says which input), or never produced a verdict
- * (`untested`, meaning no satisfying input was found, or every
- * satisfying run hit a dependency the harness cannot supply).
+ * The result of checking a claim by running the code (`suss
+ * corroborate`). The harness generates inputs that satisfy the claim's
+ * own conditions and runs the function on them.
+ *
+ * - `observed`: every run agreed with the claim.
+ * - `refuted`: at least one run disagreed, which is either an extractor
+ *   bug or a surprise. `counterexample` gives the input.
+ * - `untested`: no run produced a verdict. No satisfying input was
+ *   found, or every run hit a dependency the harness cannot supply.
  *
- * Corroboration adds observations to a derivation. It is extra
- * evidence, and it never rewrites the derived claim.
+ * Corroboration adds evidence to a derived claim and never rewrites it.
  */
 declare const CorroborationSchema: z.ZodObject<{
     outcome: z.ZodEnum<{
@@ -354,6 +360,7 @@ declare const SourceLocationSchema: z.ZodObject<{
     }, z.core.$strip>>;
     exportName: z.ZodNullable<z.ZodString>;
     workspace: z.ZodOptional<z.ZodString>;
+    module: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const BoundaryBindingSchema: z.ZodObject<{
     transport: z.ZodString;
@@ -428,6 +435,9 @@ declare const BoundaryBindingSchema: z.ZodObject<{
         }>;
         name: z.ZodLiteral<"unit-invocation">;
         instanceName: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodLiteral<"io">;
+        target: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>], "name">;
     recognition: z.ZodString;
 }, z.core.$strip>;
@@ -478,24 +488,22 @@ type TypeShape = {
     def?: string | undefined;
     /**
      * The file that declares this type, when the project declares it.
-     * Absent for a name the language or a dependency owns, which means
-     * the same thing everywhere.
+     * Absent for a name the language or a dependency defines, which
+     * means the same thing everywhere.
      *
-     * A name on its own does not identify a type. Two modules each
-     * declaring a `User` produce the same ref, and a checker comparing
-     * them has nothing to go on. This is what tells them apart.
+     * A name on its own does not identify a type. Two modules that each
+     * declare a `User` produce the same ref, and `from` is the only
+     * field that tells them apart.
      */
     from?: string | undefined;
 } | {
     type: "unknown";
 };
 /**
- * The key a table of definitions uses for the type a ref points at.
- *
- * A ref has the name and the file that declares it, and that pair
- * already identifies the type, so a table keyed on it needs nothing new
- * on the ref. A name that the language or a dependency owns has no
- * file, and keys on the name alone.
+ * The key a table of definitions uses for the type a ref points at,
+ * which is the ref's `def`. Null for a ref without one, such as a name
+ * the language or a dependency defines, and such a ref is never looked
+ * up.
  */
 declare function typeDefinitionKey(ref: {
     def?: string | undefined;
@@ -505,16 +513,15 @@ declare const TypeShapeSchema: z.ZodType<TypeShape>;
  * A shape with the definitions it refers to substituted back into it.
  *
  * Comparing two shapes means comparing their structure, and a ref has
- * none. Rather than teach every comparison to look in a table, the
- * definitions go back into the shape once and everything downstream
- * reads what it always read.
+ * none. Substituting the definitions once means no comparison has to
+ * look anything up in a table.
  *
- * Substituting a definition is not a level of nesting, so it does not
- * spend depth. Counting it meant a type six deep came back three deep,
- * and a consumer reading a field past that was told the provider did
- * not have it. A type that refers to itself is stopped by the names
- * already substituted on this path, the shape walk's own cycle guard.
+ * Substituting a definition does not count as a level of nesting. If it
+ * did, a type six levels deep would come back three deep, and a
+ * consumer reading a field past that would be told the provider lacks
+ * it. A type that refers to itself stops at a key already substituted
+ * on this path, the same cycle guard the shape walk uses.
  */
 declare function withDefinitionsInlined(shape: TypeShape, definitions: Record<string, TypeShape> | undefined, depth?: number, inProgress?: ReadonlySet<string>): TypeShape;
 
-export { storageSystemLabel as A, BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, EVERY_FIELD as E, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, typeDefinitionKey as H, withDefinitionsInlined as I, type MessageBusSemantics as M, type RestSemantics as R, type Semantics as S, type TypeShape as T, ConfidenceLevelSchema as a, ConfidenceSourceSchema as b, CorroborationSchema as c, SourceLocationSchema as d, type MessageBusTechnology as e, DeployableUnitSchema as f, FunctionCallSemanticsSchema as g, GraphqlOperationSemanticsSchema as h, type GraphqlResolverSemantics as i, GraphqlResolverSemanticsSchema as j, MessageBusSemanticsSchema as k, RestSemanticsSchema as l, type RuntimeConfigSemantics as m, RuntimeConfigSemanticsSchema as n, SemanticsSchema as o, type StorageSemantics as p, StorageSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, pathShape as v, routePathAdmits as w, routePathsMeet as x, storageContainerLabel as y, storageLabel as z };
+export { storageLabel as A, BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, EVERY_FIELD as E, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, storageSystemLabel as H, typeDefinitionKey as I, withDefinitionsInlined as J, type MessageBusSemantics as M, type RestSemantics as R, type Semantics as S, type TypeShape as T, ConfidenceLevelSchema as a, ConfidenceSourceSchema as b, CorroborationSchema as c, SourceLocationSchema as d, type MessageBusTechnology as e, DeployableUnitSchema as f, FunctionCallSemanticsSchema as g, GraphqlOperationSemanticsSchema as h, type GraphqlResolverSemantics as i, GraphqlResolverSemanticsSchema as j, MessageBusSemanticsSchema as k, RestSemanticsSchema as l, type RuntimeConfigSemantics as m, RuntimeConfigSemanticsSchema as n, SemanticsSchema as o, type StorageSemantics as p, StorageSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, isModuleName as t, methodsAgree as u, normalizePath as v, pathShape as w, routePathAdmits as x, routePathsMeet as y, storageContainerLabel as z };