@suss/ir-core 0.5.10 → 0.6.0

package/dist/chunk-FFPB2UKY.js

@@ -1,625 +0,0 @@
-// 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/identityKeys.ts
-function gqlIdentityKey(typeName, fieldName) {
-  return `gql:${typeName}.${fieldName}`;
-}
-function fnIdentityKey(packageName, exportPath) {
-  return `fn:${packageName}::${exportPath.join(".")}`;
-}
-function busIdentityKey(messageBus, subject) {
-  return `bus:${messageBus} ${subject}`;
-}
-
-// 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,
-    /**
-     * In-repo units (components, bare handlers) are keyless by design
-     * and pair through call edges rather than the keyed pass, so a
-     * missing key is not a boundary nothing can reach.
-     */
-    canPair: () => true,
-    /**
-     * `"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 fnIdentityKey(semantics.package, semantics.exportPath);
-      }
-      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,
-    /** Keyless by design; the dedicated pass pairs it by its document. */
-    canPair: () => true,
-    /** "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 gqlIdentityKey(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,
-    /**
-     * A channel unnamed here can still pair: the dedicated pass
-     * collapses env chains before comparing, so a consumer whose
-     * channel arrives at runtime meets the template that declares it.
-     */
-    canPair: () => 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 busIdentityKey(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 {
-  GraphqlOperationSemanticsSchema,
-  gqlIdentityKey,
-  fnIdentityKey,
-  busIdentityKey,
-  FunctionCallSemanticsSchema,
-  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
-};