@suss/ir-core 0.3.2 → 0.4.0

package/README.md

@@ -1,12 +1,12 @@
 # @suss/ir-core
 
-Primitives shared across suss's intermediate representations: the shapes every IR references, in one place that none of them depend on each other to reach.
+Primitives shared across suss's intermediate representations: the pieces every IR references, in one place that each of them can reach without depending on the others.
 
 ## What this package is
 
 The types that any suss IR is built from:
 
-- `TypeShape`: the structural shape of a value, for body / payload / field comparison.
+- `TypeShape`: the structure of a value, for body / payload / field comparison.
 - `BoundaryBinding` + the `Semantics` variants (rest, function-call, graphql-resolver, graphql-operation, runtime-config, storage-relational, message-bus), plus the eight blessed binding constructors (`restBinding`, `functionCallBinding`, …).
 - `SourceLocation` and `Confidence` (`source` + `level`).
 
@@ -21,11 +21,19 @@ const binding = restBinding({
 });
 ```
 
+## Message-bus channels
+
+A channel is a subject, optionally qualified by the bus that carries it, written `${bus}#${subject}`. Two channels pair when their subjects are equal and their buses agree, and buses agree when they are the same or when either side does not know its bus.
+
+The two sides rarely know the same amount. A CloudFormation template gives both the bus and the detail-type, and it goes out of its way to distinguish one bus from another, so when a side does know its bus we keep that precision. Code usually knows only the subject: the code pack reads `subject: 'order.placed'` from a handler's config, but which bus actually reaches that handler is deployment configuration the code never mentions. So `default#order.placed` pairs with `order.placed`, while `staging#order.placed` does not pair with `default#order.placed`.
+
+The boundary key uses only the subject, so both forms end up in the same bucket and `channelsPair` compares the buses within it.
+
 Schemas are the single source of truth (`@suss/ir-core/schemas`); the types are derived from them. The recursive `TypeShape` is a hand-written named export so consuming packages reference it by name across the package boundary rather than inlining the recursion.
 
-## Where it sits in suss
+## Where it fits in suss
 
-The base both `@suss/behavioral-ir` (what code does) and `@suss/intent-ir` (what the team meant) build on, so neither IR depends on the other. They describe boundaries in the same vocabulary and are compared rather than merged. `@suss/behavioral-ir` re-exports these primitives, so existing consumers keep importing them from there unchanged.
+Both `@suss/behavioral-ir` (what code does) and `@suss/intent-ir` (what the team meant) build on this package, so neither IR depends on the other. They describe boundaries in the same vocabulary, and suss compares them rather than merging them. `@suss/behavioral-ir` re-exports these primitives, so existing consumers keep importing them from there unchanged.
 
 ## Status
 

package/dist/chunk-5KE7OWN3.js

@@ -0,0 +1,597 @@
+// src/schemas.ts
+import { z as z10 } from "zod";
+
+// src/semantics/registry.ts
+import { z as z9 } from "zod";
+
+// src/semantics/functionCall.ts
+import { z } from "zod";
+
+// src/semantics/definition.ts
+function defineBoundarySemantics(definition) {
+  return definition;
+}
+
+// src/semantics/functionCall.ts
+var FunctionCallSemanticsSchema = z.object({
+  name: z.literal("function-call"),
+  /**
+   * Optional module identifier for cross-unit references
+   * (e.g. `"./components/Button"` for a React component, or the TS
+   * module path for a bare function export). Packs that don't do
+   * cross-module pairing can leave it unset.
+   */
+  module: z.string().optional(),
+  /** Named export within the module, when applicable. */
+  exportName: z.string().optional(),
+  /**
+   * Package name, as written in `package.json`, when this identity
+   * refers to a public package export, for example
+   * `"@suss/behavioral-ir"`. Packs that resolve a package's public
+   * surface (the `packageExports` discovery variant) set it alongside
+   * `exportPath`. It is different from `module`, which is a
+   * repo-relative module path used for pairing inside one repo.
+   */
+  package: z.string().optional(),
+  /**
+   * Path to the exported binding within the package, starting with the
+   * sub-path key when one is used. Examples:
+   *   `["parseSummary"]`: a root export
+   *   `["schemas", "BoundaryBindingSchema"]`: the sub-path `./schemas`
+   *
+   * The first segment is the sub-path without the leading `./`, and
+   * `"."` is left out. The last segment is the exported name.
+   */
+  exportPath: z.array(z.string()).optional()
+});
+var functionCallSemantics = defineBoundarySemantics({
+  name: "function-call",
+  schema: FunctionCallSemanticsSchema,
+  behavior: {
+    /** A call returns a value, which is not a status and a body. */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    /**
+     * `"fn:<package>::<exportPath>"` when both are set. Other in-process
+     * function-call units, such as components and bare handlers inside
+     * one repo, have no key at all.
+     */
+    identityKey(semantics) {
+      if (semantics.package !== void 0 && semantics.exportPath !== void 0 && semantics.exportPath.length > 0) {
+        return `fn:${semantics.package}::${semantics.exportPath.join(".")}`;
+      }
+      return null;
+    }
+  }
+});
+
+// src/semantics/graphqlOperation.ts
+import { z as z2 } from "zod";
+var GraphqlOperationSemanticsSchema = z2.object({
+  name: z2.literal("graphql-operation"),
+  /** Optional operation name. An anonymous query or mutation leaves it unset. */
+  operationName: z2.string().optional(),
+  operationType: z2.enum(["query", "mutation", "subscription"])
+});
+var graphqlOperationSemantics = defineBoundarySemantics({
+  name: "graphql-operation",
+  schema: GraphqlOperationSemanticsSchema,
+  behavior: {
+    /**
+     * An operation gets a data-and-errors document back, which the
+     * GraphQL contract checker reads. Status codes say nothing here.
+     */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    identityKey: () => null,
+    /** "query GetUser". The contract checker pairs it, the key does not. */
+    displayLabel(semantics) {
+      return `${semantics.operationType} ${semantics.operationName ?? "<anonymous>"}`;
+    }
+  }
+});
+
+// src/semantics/graphqlResolver.ts
+import { z as z3 } from "zod";
+var GraphqlResolverSemanticsSchema = z3.object({
+  name: z3.literal("graphql-resolver"),
+  /**
+   * GraphQL type the resolver attaches to: "Query", "Mutation",
+   * "Subscription", or an object-type name. Null when the source never
+   * says which one, as with a `@Resolver()` class that has no argument.
+   */
+  typeName: z3.string().min(1).nullable(),
+  /** Field name on that type. */
+  fieldName: z3.string()
+});
+var graphqlResolverSemantics = defineBoundarySemantics({
+  name: "graphql-resolver",
+  schema: GraphqlResolverSemanticsSchema,
+  behavior: {
+    /** A resolver returns a field value, not a status and a body. */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    /**
+     * `"gql:<TypeName>.<fieldName>"`, or null when the type is null or
+     * the field is empty, which is how a resolver reports that the
+     * source never gave them.
+     */
+    identityKey(semantics) {
+      if (semantics.typeName === null || semantics.fieldName === "") {
+        return null;
+      }
+      return `gql:${semantics.typeName}.${semantics.fieldName}`;
+    }
+  }
+});
+
+// src/semantics/messageBus.ts
+import { z as z4 } from "zod";
+
+// src/channel.ts
+function parseChannel(channel) {
+  const hash = channel.indexOf("#");
+  if (hash === -1) {
+    return { bus: null, subject: channel };
+  }
+  return { bus: channel.slice(0, hash), subject: channel.slice(hash + 1) };
+}
+function formatChannel(bus, subject) {
+  if (bus === null) {
+    return subject;
+  }
+  return `${bus}#${subject}`;
+}
+function busesAgree(a, b) {
+  return a === null || b === null || a === b;
+}
+function channelsPair(a, b) {
+  const left = parseChannel(a);
+  const right = parseChannel(b);
+  return left.subject === right.subject && busesAgree(left.bus, right.bus);
+}
+
+// src/semantics/messageBus.ts
+var MessageBusSemanticsSchema = z4.object({
+  name: z4.literal("message-bus"),
+  messageBus: z4.enum([
+    "sqs",
+    "sns",
+    "s3",
+    "eventbridge",
+    "bullmq",
+    "kafka",
+    "nats"
+  ]),
+  /**
+   * Stable channel identifier: a CFN logical id, a queue or topic name,
+   * a subject pattern, or `bus#detailType`. Null when this source does
+   * not say which channel, as with a send whose queue the code picks at
+   * runtime, or a receive whose queue the event-source mapping states.
+   */
+  channel: z4.string().min(1).nullable()
+});
+var messageBusSemantics = defineBoundarySemantics({
+  name: "message-bus",
+  schema: MessageBusSemanticsSchema,
+  behavior: {
+    /** A message goes onto the channel and nothing comes back. */
+    exchangesHttpResponses: false,
+    /**
+     * `checkMessageBus` looks at every channel, including the unused
+     * ones, so the generic unmatched lists leave them alone.
+     */
+    reportsUnpairedItself: true,
+    /**
+     * `"bus:<messageBus> <subject>"`, or null when the channel is null
+     * or its subject is empty.
+     *
+     * The key has the subject in it and leaves out the bus, so a
+     * template writing `default#order.placed` and a handler writing
+     * `order.placed` land in one bucket, where `sidesAgree` compares the
+     * buses. A side that cannot know its bus would otherwise be keyed
+     * away from the side that can.
+     *
+     * The bus technology stays in, because a queue and an event router
+     * are different destinations even with the same subject. Case stays
+     * too, because AWS compares detail-types and queue ids byte for byte.
+     */
+    identityKey(semantics) {
+      if (semantics.channel === null) {
+        return null;
+      }
+      const { subject } = parseChannel(semantics.channel);
+      if (subject === "") {
+        return null;
+      }
+      return `bus:${semantics.messageBus} ${subject}`;
+    },
+    sidesAgree(a, b) {
+      if (a.channel === null || b.channel === null) {
+        return false;
+      }
+      return channelsPair(a.channel, b.channel);
+    },
+    /**
+     * The whole channel, bus included, unlike the identity key, which
+     * has the subject alone. Someone reading a list of unmatched
+     * channels wants to see which bus each one was on.
+     */
+    displayLabel(semantics) {
+      if (semantics.channel === null) {
+        return `bus:${semantics.messageBus} (channel named at runtime)`;
+      }
+      return `bus:${semantics.messageBus} ${semantics.channel}`;
+    }
+  }
+});
+
+// src/semantics/rest.ts
+import { z as z5 } from "zod";
+var RestSemanticsSchema = z5.object({
+  name: z5.literal("rest"),
+  /**
+   * Uppercase HTTP method ("GET", "POST", …), `"*"` for a handler that
+   * responds to every method, or null when this source does not say
+   * which method.
+   */
+  method: z5.string().min(1).nullable(),
+  /** Normalized route path ("/users/{id}"), or null when this source does not give one. */
+  path: z5.string().min(1).nullable(),
+  /**
+   * Status codes the producing source explicitly declared (OpenAPI
+   * responses, CFN MethodResponses, ts-rest router statuses). They are
+   * kept here so the pairing layer can see them without unwrapping any
+   * metadata. Absent, or empty, for a source that was inferred.
+   */
+  declaredResponses: z5.array(z5.number()).optional()
+});
+function normalizePath(path) {
+  let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  normalized = normalized.replace(
+    /\{[^}]+\}|[^{]+/g,
+    (segment) => segment.startsWith("{") ? segment : segment.toLowerCase()
+  );
+  return normalized;
+}
+function methodsAgree(a, b) {
+  if (a === null || b === null) {
+    return false;
+  }
+  return a === b || a === "*" || b === "*";
+}
+function routePathRegex(pattern) {
+  const source = pattern.split(/(\{[^}]+\}|\*)/g).map((part) => {
+    if (part === "*") {
+      return ".*";
+    }
+    if (part.startsWith("{") && part.endsWith("}")) {
+      return "[^/]+";
+    }
+    return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  return new RegExp(`^${source}$`);
+}
+function routePathAdmits(declaredPath, requestPath) {
+  return routePathRegex(normalizePath(declaredPath)).test(
+    normalizePath(requestPath)
+  );
+}
+var restSemantics = defineBoundarySemantics({
+  name: "rest",
+  schema: RestSemanticsSchema,
+  behavior: {
+    /** A request goes out, a status and a body come back. */
+    exchangesHttpResponses: true,
+    reportsUnpairedItself: false,
+    /** `"METHOD /normalized/path"`, or null when either half is missing. */
+    identityKey(semantics) {
+      if (semantics.method === null || semantics.path === null) {
+        return null;
+      }
+      return `${semantics.method.toUpperCase()} ${normalizePath(semantics.path)}`;
+    },
+    /**
+     * The bucket has only the path in it, so a `"*"` route lands with
+     * the consumers that each specify a method, and `methodsAgree`
+     * settles it inside the bucket. The identity key stays what a reader
+     * sees and a suppression targets ("GET /users", "* /users"), and
+     * this key groups what a reader still tells apart.
+     */
+    pairingKey(semantics) {
+      if (semantics.method === null || semantics.path === null) {
+        return null;
+      }
+      return `rest ${normalizePath(semantics.path)}`;
+    },
+    sidesAgree(a, b) {
+      return methodsAgree(a.method, b.method);
+    },
+    /**
+     * What the identity key says, with a missing half still readable:
+     * ANY when no method was stated, and ? when no path was. Null when
+     * neither was stated, because then there is nothing to show.
+     */
+    displayLabel(semantics) {
+      if (semantics.method === null && semantics.path === null) {
+        return null;
+      }
+      const method = semantics.method === null ? "ANY" : semantics.method.toUpperCase();
+      const path = semantics.path === null ? "?" : normalizePath(semantics.path);
+      return `${method} ${path}`;
+    },
+    /**
+     * A route with both halves stated decides for itself: the method
+     * through `methodsAgree` (so a `"*"` route matches every method),
+     * and the path through `routePathAdmits`. A route missing either
+     * half might still be the one that handles the request, and nothing
+     * here can settle that, so it abstains instead of refusing.
+     */
+    servesRequest(semantics, method, path) {
+      if (semantics.method === null || semantics.path === null) {
+        return "unknown";
+      }
+      if (!methodsAgree(semantics.method, method.toUpperCase())) {
+        return "nomatch";
+      }
+      return routePathAdmits(semantics.path, path) ? "match" : "nomatch";
+    },
+    ruleBoundary: {
+      // "METHOD /path": one leading token, then an absolute path.
+      claims(raw) {
+        return /^\S+ +\//.test(raw.trim());
+      },
+      normalize(raw) {
+        const trimmed = raw.trim();
+        const spaceIdx = trimmed.indexOf(" ");
+        const method = trimmed.slice(0, spaceIdx).toUpperCase();
+        return `${method} ${normalizePath(trimmed.slice(spaceIdx + 1).trim())}`;
+      }
+    }
+  }
+});
+
+// src/semantics/runtimeConfig.ts
+import { z as z7 } from "zod";
+
+// src/deployableUnit.ts
+import { z as z6 } from "zod";
+var DeployableUnitSchema = z6.object({
+  deploymentTarget: z6.enum([
+    "lambda",
+    "ecs-task",
+    "container",
+    "k8s-deployment"
+  ]),
+  // An empty name would agree with every other empty name, so a unit
+  // with no name has to leave the field off instead.
+  instanceName: z6.string().min(1)
+});
+function ecsContainerInstanceName(taskDefinitionLogicalId, containerName) {
+  return `${taskDefinitionLogicalId}/${containerName}`;
+}
+
+// src/semantics/runtimeConfig.ts
+var RuntimeConfigSemanticsSchema = DeployableUnitSchema.extend({
+  name: z7.literal("runtime-config")
+});
+var runtimeConfigSemantics = defineBoundarySemantics({
+  name: "runtime-config",
+  schema: RuntimeConfigSemanticsSchema,
+  behavior: {
+    /** A process reads its config at startup, and nothing replies. */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    identityKey: () => null
+  }
+});
+
+// src/semantics/storageRelational.ts
+import { z as z8 } from "zod";
+var StorageRelationalSemanticsSchema = z8.object({
+  name: z8.literal("storage-relational"),
+  storageSystem: z8.enum(["postgres", "mysql", "sqlite"]),
+  /**
+   * The ORM or driver scope. A single-database setup uses `"default"`,
+   * and a monorepo with several schemas gives each one its own value.
+   */
+  scope: z8.string(),
+  /** The table or model name, as declared in the schema. */
+  table: z8.string()
+});
+var storageRelationalSemantics = defineBoundarySemantics({
+  name: "storage-relational",
+  schema: StorageRelationalSemanticsSchema,
+  behavior: {
+    /** A query returns rows, not a status and a body. */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    identityKey: () => null
+  }
+});
+
+// src/semantics/registry.ts
+var SemanticsSchema = z9.discriminatedUnion("name", [
+  restSemantics.schema,
+  functionCallSemantics.schema,
+  graphqlResolverSemantics.schema,
+  graphqlOperationSemantics.schema,
+  runtimeConfigSemantics.schema,
+  storageRelationalSemantics.schema,
+  messageBusSemantics.schema
+]);
+var DEFINITIONS = [
+  restSemantics,
+  functionCallSemantics,
+  graphqlResolverSemantics,
+  graphqlOperationSemantics,
+  runtimeConfigSemantics,
+  storageRelationalSemantics,
+  messageBusSemantics
+];
+var BY_NAME = new Map(
+  DEFINITIONS.map((d) => [d.name, d])
+);
+function behaviorOf(semantics) {
+  const definition = BY_NAME.get(semantics.name);
+  if (definition === void 0) {
+    throw new Error(`no boundary behavior for semantics "${semantics.name}"`);
+  }
+  return definition.behavior;
+}
+function allBehaviors() {
+  return DEFINITIONS.map((d) => d.behavior);
+}
+
+// src/schemas.ts
+var ConfidenceSourceSchema = z10.enum([
+  "inferred_static",
+  "inferred_ai",
+  "declared",
+  "derived"
+]);
+var ConfidenceLevelSchema = z10.enum(["high", "medium", "low"]);
+var CorroborationSchema = z10.object({
+  outcome: z10.enum(["observed", "refuted", "untested"]),
+  /** Executions that produced a verdict for this claim. */
+  runs: z10.number(),
+  /** Present when refuted: the input and observation that disagreed. */
+  counterexample: z10.unknown().optional(),
+  /** Present when untested: why no verdict was reachable. */
+  reason: z10.string().optional()
+});
+var ConfidenceInfoSchema = z10.object({
+  source: ConfidenceSourceSchema,
+  level: ConfidenceLevelSchema,
+  corroboration: CorroborationSchema.optional()
+});
+var SourceLocationSchema = z10.object({
+  file: z10.string(),
+  range: z10.object({ start: z10.number(), end: z10.number() }),
+  exportName: z10.string().nullable(),
+  /**
+   * The project the extract was pointed at, by the name that project
+   * calls itself.
+   *
+   * Paths are relative to wherever the extract ran, so two services in
+   * one repository both report `src/handlers.ts`, and merging their
+   * summaries puts them on top of each other. This field is what tells
+   * them apart, and what a reader groups by.
+   */
+  workspace: z10.string().optional()
+});
+var BoundaryBindingSchema = z10.object({
+  transport: z10.string(),
+  semantics: SemanticsSchema,
+  recognition: z10.string()
+});
+function typeDefinitionKey(ref) {
+  return ref.def ?? null;
+}
+var TypeShapeSchema = z10.lazy(
+  () => z10.discriminatedUnion("type", [
+    z10.object({
+      type: z10.literal("record"),
+      properties: z10.record(z10.string(), TypeShapeSchema),
+      spreads: z10.array(z10.object({ sourceText: z10.string() })).optional()
+    }),
+    z10.object({ type: z10.literal("dictionary"), values: TypeShapeSchema }),
+    z10.object({ type: z10.literal("array"), items: TypeShapeSchema }),
+    z10.object({
+      type: z10.literal("literal"),
+      value: z10.union([z10.string(), z10.number(), z10.boolean()]),
+      raw: z10.string().optional()
+    }),
+    z10.object({ type: z10.literal("text") }),
+    z10.object({ type: z10.literal("integer") }),
+    z10.object({ type: z10.literal("number") }),
+    z10.object({ type: z10.literal("boolean") }),
+    z10.object({ type: z10.literal("null") }),
+    z10.object({ type: z10.literal("undefined") }),
+    z10.object({
+      type: z10.literal("union"),
+      variants: z10.array(TypeShapeSchema)
+    }),
+    z10.object({
+      type: z10.literal("ref"),
+      name: z10.string(),
+      from: z10.string().optional(),
+      def: z10.string().optional()
+    }),
+    z10.object({ type: z10.literal("unknown") })
+  ])
+);
+var MAX_DEFINITION_DEPTH = 6;
+function withDefinitionsInlined(shape, definitions, depth = 0, inProgress = /* @__PURE__ */ new Set()) {
+  if (definitions === void 0 || depth >= MAX_DEFINITION_DEPTH) {
+    return shape;
+  }
+  const deeper = (inner) => withDefinitionsInlined(inner, definitions, depth + 1, inProgress);
+  if (shape.type === "ref") {
+    const key = typeDefinitionKey(shape);
+    if (key === null) {
+      return shape;
+    }
+    const defined = definitions[key];
+    if (defined === void 0 || inProgress.has(key)) {
+      return shape;
+    }
+    return withDefinitionsInlined(
+      defined,
+      definitions,
+      depth,
+      /* @__PURE__ */ new Set([...inProgress, key])
+    );
+  }
+  if (shape.type === "record") {
+    const properties = {};
+    for (const [name, value] of Object.entries(shape.properties)) {
+      properties[name] = deeper(value);
+    }
+    return { ...shape, properties };
+  }
+  if (shape.type === "array") {
+    return { ...shape, items: deeper(shape.items) };
+  }
+  if (shape.type === "dictionary") {
+    return { ...shape, values: deeper(shape.values) };
+  }
+  if (shape.type === "union") {
+    return { ...shape, variants: shape.variants.map(deeper) };
+  }
+  return shape;
+}
+
+export {
+  FunctionCallSemanticsSchema,
+  GraphqlOperationSemanticsSchema,
+  GraphqlResolverSemanticsSchema,
+  parseChannel,
+  formatChannel,
+  busesAgree,
+  channelsPair,
+  MessageBusSemanticsSchema,
+  RestSemanticsSchema,
+  normalizePath,
+  methodsAgree,
+  routePathAdmits,
+  DeployableUnitSchema,
+  ecsContainerInstanceName,
+  RuntimeConfigSemanticsSchema,
+  StorageRelationalSemanticsSchema,
+  SemanticsSchema,
+  behaviorOf,
+  allBehaviors,
+  ConfidenceSourceSchema,
+  ConfidenceLevelSchema,
+  CorroborationSchema,
+  ConfidenceInfoSchema,
+  SourceLocationSchema,
+  BoundaryBindingSchema,
+  typeDefinitionKey,
+  TypeShapeSchema,
+  withDefinitionsInlined
+};