@suss/ir-core 0.19.0 → 0.21.0

package/dist/index.cjs

@@ -26,11 +26,14 @@ __export(index_exports, {
   ConfidenceSourceSchema: () => ConfidenceSourceSchema,
   CorroborationSchema: () => CorroborationSchema,
   DeployableUnitSchema: () => DeployableUnitSchema,
+  EVERY_FIELD: () => EVERY_FIELD,
+  EffectRelationSchema: () => EffectRelationSchema,
   FunctionCallSemanticsSchema: () => FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema: () => GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema: () => GraphqlResolverSemanticsSchema,
   MessageBusSemanticsSchema: () => MessageBusSemanticsSchema,
   MetricSemanticsSchema: () => MetricSemanticsSchema,
+  RelationSchema: () => RelationSchema,
   RestSemanticsSchema: () => RestSemanticsSchema,
   RuntimeConfigSemanticsSchema: () => RuntimeConfigSemanticsSchema,
   SemanticsSchema: () => SemanticsSchema,
@@ -39,7 +42,10 @@ __export(index_exports, {
   SuppressionFileSchema: () => SuppressionFileSchema,
   SuppressionRuleSchema: () => SuppressionRuleSchema,
   TypeShapeSchema: () => TypeShapeSchema,
+  UnitInvocationSemanticsSchema: () => UnitInvocationSemanticsSchema,
   applySuppressionsToFindings: () => applySuppressionsToFindings,
+  bindingIs: () => bindingIs,
+  bindingTokens: () => bindingTokens,
   bodyShapesMatch: () => bodyShapesMatch,
   boundaryKey: () => boundaryKey,
   boundaryLabel: () => boundaryLabel,
@@ -72,6 +78,8 @@ __export(index_exports, {
   namePatternFromSub: () => namePatternFromSub,
   namePatternKey: () => namePatternKey,
   namesAgree: () => namesAgree,
+  namesBoundary: () => namesBoundary,
+  namesBoundaryExactly: () => namesBoundaryExactly,
   namesNothing: () => namesNothing,
   normalizePath: () => normalizePath,
   normalizeRuleBoundary: () => normalizeRuleBoundary,
@@ -86,6 +94,7 @@ __export(index_exports, {
   referenceName: () => referenceName,
   referenceOf: () => referenceOf,
   reportsUnpairedItself: () => reportsUnpairedItself,
+  resourceNameIn: () => resourceNameIn,
   restBinding: () => restBinding,
   routePathAdmits: () => routePathAdmits,
   ruleBoundaryMatchesKey: () => ruleBoundaryMatchesKey,
@@ -93,11 +102,18 @@ __export(index_exports, {
   semanticsAgree: () => semanticsAgree,
   semconvAttributes: () => semconvAttributes,
   servesRequest: () => servesRequest,
+  spellingTokens: () => spellingTokens,
   statesAnOrigin: () => statesAnOrigin,
   storageBinding: () => storageBinding,
+  storageContainerLabel: () => storageContainerLabel,
+  storageLabel: () => storageLabel,
   typeDefinitionKey: () => typeDefinitionKey,
+  unitIdentityKey: () => unitIdentityKey,
+  unitInvocationBinding: () => unitInvocationBinding,
   validateRule: () => validateRule,
-  withDefinitionsInlined: () => withDefinitionsInlined
+  withDefinitionsInlined: () => withDefinitionsInlined,
+  withRewrittenPaths: () => withRewrittenPaths,
+  withinScope: () => withinScope
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -150,15 +166,18 @@ function fnIdentityKey(packageName, exportPath) {
 function busIdentityKey(messageBus, subject) {
   return `bus:${messageBus} ${subject}`;
 }
+function unitIdentityKey(deploymentTarget, instanceName) {
+  return `unit:${deploymentTarget} ${instanceName}`;
+}
 function metricIdentityKey(metricSystem, metricType) {
   return `metric:${metricSystem} ${metricType}`;
 }
 
 // src/schemas.ts
-var import_zod11 = require("zod");
+var import_zod12 = require("zod");
 
 // src/semantics/registry.ts
-var import_zod10 = require("zod");
+var import_zod11 = require("zod");
 
 // src/semantics/functionCall.ts
 var import_zod2 = require("zod");
@@ -210,14 +229,24 @@ var functionCallSemantics = defineBoundarySemantics({
      */
     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.
+     * `"fn:<package>::<exportPath>"` when both are set, and
+     * `"fn:<module>::<exportName>"` for an in-repo unit that states its
+     * module, the way a server action does. Components and bare
+     * handlers state neither and have no key at all.
      */
+    rewritePaths(semantics, rewrite) {
+      if (semantics.module === void 0) {
+        return semantics;
+      }
+      return { ...semantics, module: rewrite(semantics.module) };
+    },
     identityKey(semantics) {
       if (semantics.package !== void 0 && semantics.exportPath !== void 0 && semantics.exportPath.length > 0) {
         return fnIdentityKey(semantics.package, semantics.exportPath);
       }
+      if (semantics.module !== void 0 && semantics.exportName !== void 0) {
+        return fnIdentityKey(semantics.module, [semantics.exportName]);
+      }
       return null;
     }
   }
@@ -558,6 +587,14 @@ var restSemantics = defineBoundarySemantics({
       }
       return routePathAdmits(semantics.path, path) ? "match" : "nomatch";
     },
+    /**
+     * A route the registration pattern admits is inside it. A route
+     * whose path this source never gave is left outside, because
+     * nothing here can show it is one the pattern covers.
+     */
+    withinScope(semantics, scope) {
+      return semantics.path !== null && routePathAdmits(scope, semantics.path);
+    },
     /**
      * A call whose base URL the deployment fills in, resolved to the
      * path it reaches.
@@ -693,12 +730,71 @@ var storageSemantics = defineBoundarySemantics({
     /** A query returns rows or items, not a status and a body. */
     exchangesHttpResponses: false,
     reportsUnpairedItself: false,
-    identityKey: () => null
+    identityKey: () => null,
+    displayLabel: storageLabel
+  }
+});
+function storageLabel(semantics) {
+  return `${semantics.storageSystem}:${storageContainerLabel(semantics)}`;
+}
+var EVERY_FIELD = "*";
+function storageContainerLabel(semantics) {
+  const container = semantics.container ?? "<unnamed container>";
+  const addressed = semantics.accessPath === null ? container : `${container}#${semantics.accessPath}`;
+  return semantics.scope === "default" ? addressed : `${semantics.scope}/${addressed}`;
+}
+
+// src/semantics/unitInvocation.ts
+var import_zod10 = require("zod");
+var UnitInvocationSemanticsSchema = DeployableUnitSchema.extend({
+  name: import_zod10.z.literal("unit-invocation"),
+  instanceName: DeployableUnitSchema.shape.instanceName.nullable()
+});
+var unitInvocationSemantics = defineBoundarySemantics({
+  name: "unit-invocation",
+  schema: UnitInvocationSemanticsSchema,
+  // faas.name is the deployed function's own name and instanceName is
+  // the deployment template's logical id, which is a different string.
+  // Runtime config leaves the pair off for the same reason.
+  semconv: {},
+  behavior: {
+    /**
+     * A synchronous invoke gives back whatever the handler returned,
+     * which is a value rather than a status and a body. A handler's
+     * return only becomes an HTTP response under a proxy integration,
+     * and that route gets a REST binding instead of this one.
+     */
+    exchangesHttpResponses: false,
+    /**
+     * A unit nothing in the run invokes is the ordinary case, since
+     * most services are reached from a stack suss never read. So an
+     * uninvoked unit stays in the generic unmatched list rather than
+     * being reported as a problem here.
+     */
+    reportsUnpairedItself: false,
+    identityKey(semantics) {
+      if (semantics.instanceName === null) {
+        return null;
+      }
+      return unitIdentityKey(
+        semantics.deploymentTarget,
+        semantics.instanceName
+      );
+    },
+    displayLabel(semantics) {
+      if (semantics.instanceName === null) {
+        return `unit:${semantics.deploymentTarget} (named at runtime)`;
+      }
+      return unitIdentityKey(
+        semantics.deploymentTarget,
+        semantics.instanceName
+      );
+    }
   }
 });
 
 // src/semantics/registry.ts
-var SemanticsSchema = import_zod10.z.discriminatedUnion("name", [
+var SemanticsSchema = import_zod11.z.discriminatedUnion("name", [
   restSemantics.schema,
   functionCallSemantics.schema,
   graphqlResolverSemantics.schema,
@@ -706,7 +802,8 @@ var SemanticsSchema = import_zod10.z.discriminatedUnion("name", [
   runtimeConfigSemantics.schema,
   storageSemantics.schema,
   messageBusSemantics.schema,
-  metricSemantics.schema
+  metricSemantics.schema,
+  unitInvocationSemantics.schema
 ]);
 var DEFINITIONS = [
   restSemantics,
@@ -716,7 +813,8 @@ var DEFINITIONS = [
   runtimeConfigSemantics,
   storageSemantics,
   messageBusSemantics,
-  metricSemantics
+  metricSemantics,
+  unitInvocationSemantics
 ];
 var BY_NAME = new Map(
   DEFINITIONS.map((d) => [d.name, d])
@@ -739,31 +837,40 @@ function allBehaviors() {
 }
 
 // src/schemas.ts
-var ConfidenceSourceSchema = import_zod11.z.enum([
+var ConfidenceSourceSchema = import_zod12.z.enum([
   "inferred_static",
   "inferred_ai",
   "declared",
   "derived"
 ]);
-var ConfidenceLevelSchema = import_zod11.z.enum(["high", "medium", "low"]);
-var CorroborationSchema = import_zod11.z.object({
-  outcome: import_zod11.z.enum(["observed", "refuted", "untested"]),
+var ConfidenceLevelSchema = import_zod12.z.enum(["high", "medium", "low"]);
+var CorroborationSchema = import_zod12.z.object({
+  outcome: import_zod12.z.enum(["observed", "refuted", "untested"]),
   /** Executions that produced a verdict for this claim. */
-  runs: import_zod11.z.number(),
+  runs: import_zod12.z.number(),
   /** Present when refuted: the input and observation that disagreed. */
-  counterexample: import_zod11.z.unknown().optional(),
+  counterexample: import_zod12.z.unknown().optional(),
   /** Present when untested: why no verdict was reachable. */
-  reason: import_zod11.z.string().optional()
+  reason: import_zod12.z.string().optional()
 });
-var ConfidenceInfoSchema = import_zod11.z.object({
+var ConfidenceInfoSchema = import_zod12.z.object({
   source: ConfidenceSourceSchema,
   level: ConfidenceLevelSchema,
   corroboration: CorroborationSchema.optional()
 });
-var SourceLocationSchema = import_zod11.z.object({
-  file: import_zod11.z.string(),
-  range: import_zod11.z.object({ start: import_zod11.z.number(), end: import_zod11.z.number() }),
-  exportName: import_zod11.z.string().nullable(),
+var SourceLocationSchema = import_zod12.z.object({
+  file: import_zod12.z.string(),
+  /** Line numbers, for a person reading the summary or an editor link. */
+  range: import_zod12.z.object({ start: import_zod12.z.number(), end: import_zod12.z.number() }),
+  /**
+   * Character offsets of the unit in its file. Identity and joins
+   * measure with these, since two functions can share a line and never
+   * an offset range; the line `range` above is the presentation of the
+   * same place. Absent on summaries no source position backs, a
+   * contract artifact's say.
+   */
+  span: import_zod12.z.object({ start: import_zod12.z.number(), end: import_zod12.z.number() }).optional(),
+  exportName: import_zod12.z.string().nullable(),
   /**
    * The project the extract was pointed at, by the name that project
    * calls itself.
@@ -773,47 +880,47 @@ var SourceLocationSchema = import_zod11.z.object({
    * summaries puts them on top of each other. This field is what tells
    * them apart, and what a reader groups by.
    */
-  workspace: import_zod11.z.string().optional()
+  workspace: import_zod12.z.string().optional()
 });
-var BoundaryBindingSchema = import_zod11.z.object({
-  transport: import_zod11.z.string(),
+var BoundaryBindingSchema = import_zod12.z.object({
+  transport: import_zod12.z.string(),
   semantics: SemanticsSchema,
-  recognition: import_zod11.z.string()
+  recognition: import_zod12.z.string()
 });
 function typeDefinitionKey(ref) {
   return ref.def ?? null;
 }
-var TypeShapeSchema = import_zod11.z.lazy(
-  () => import_zod11.z.discriminatedUnion("type", [
-    import_zod11.z.object({
-      type: import_zod11.z.literal("record"),
-      properties: import_zod11.z.record(import_zod11.z.string(), TypeShapeSchema),
-      spreads: import_zod11.z.array(import_zod11.z.object({ sourceText: import_zod11.z.string() })).optional()
+var TypeShapeSchema = import_zod12.z.lazy(
+  () => import_zod12.z.discriminatedUnion("type", [
+    import_zod12.z.object({
+      type: import_zod12.z.literal("record"),
+      properties: import_zod12.z.record(import_zod12.z.string(), TypeShapeSchema),
+      spreads: import_zod12.z.array(import_zod12.z.object({ sourceText: import_zod12.z.string() })).optional()
     }),
-    import_zod11.z.object({ type: import_zod11.z.literal("dictionary"), values: TypeShapeSchema }),
-    import_zod11.z.object({ type: import_zod11.z.literal("array"), items: TypeShapeSchema }),
-    import_zod11.z.object({
-      type: import_zod11.z.literal("literal"),
-      value: import_zod11.z.union([import_zod11.z.string(), import_zod11.z.number(), import_zod11.z.boolean()]),
-      raw: import_zod11.z.string().optional()
+    import_zod12.z.object({ type: import_zod12.z.literal("dictionary"), values: TypeShapeSchema }),
+    import_zod12.z.object({ type: import_zod12.z.literal("array"), items: TypeShapeSchema }),
+    import_zod12.z.object({
+      type: import_zod12.z.literal("literal"),
+      value: import_zod12.z.union([import_zod12.z.string(), import_zod12.z.number(), import_zod12.z.boolean()]),
+      raw: import_zod12.z.string().optional()
     }),
-    import_zod11.z.object({ type: import_zod11.z.literal("text") }),
-    import_zod11.z.object({ type: import_zod11.z.literal("integer") }),
-    import_zod11.z.object({ type: import_zod11.z.literal("number") }),
-    import_zod11.z.object({ type: import_zod11.z.literal("boolean") }),
-    import_zod11.z.object({ type: import_zod11.z.literal("null") }),
-    import_zod11.z.object({ type: import_zod11.z.literal("undefined") }),
-    import_zod11.z.object({
-      type: import_zod11.z.literal("union"),
-      variants: import_zod11.z.array(TypeShapeSchema)
+    import_zod12.z.object({ type: import_zod12.z.literal("text") }),
+    import_zod12.z.object({ type: import_zod12.z.literal("integer") }),
+    import_zod12.z.object({ type: import_zod12.z.literal("number") }),
+    import_zod12.z.object({ type: import_zod12.z.literal("boolean") }),
+    import_zod12.z.object({ type: import_zod12.z.literal("null") }),
+    import_zod12.z.object({ type: import_zod12.z.literal("undefined") }),
+    import_zod12.z.object({
+      type: import_zod12.z.literal("union"),
+      variants: import_zod12.z.array(TypeShapeSchema)
     }),
-    import_zod11.z.object({
-      type: import_zod11.z.literal("ref"),
-      name: import_zod11.z.string(),
-      from: import_zod11.z.string().optional(),
-      def: import_zod11.z.string().optional()
+    import_zod12.z.object({
+      type: import_zod12.z.literal("ref"),
+      name: import_zod12.z.string(),
+      from: import_zod12.z.string().optional(),
+      def: import_zod12.z.string().optional()
     }),
-    import_zod11.z.object({ type: import_zod11.z.literal("unknown") })
+    import_zod12.z.object({ type: import_zod12.z.literal("unknown") })
   ])
 );
 var MAX_DEFINITION_DEPTH = 6;
@@ -877,9 +984,22 @@ function semconvAttributes(binding) {
 }
 
 // src/boundaryKey.ts
+function bindingIs(binding, name) {
+  return binding?.semantics.name === name;
+}
 function boundaryKey(binding) {
   return behaviorOf(binding.semantics).identityKey(binding.semantics);
 }
+function withRewrittenPaths(binding, rewrite) {
+  const behavior = behaviorOf(binding.semantics);
+  if (behavior.rewritePaths === void 0) {
+    return binding;
+  }
+  return {
+    ...binding,
+    semantics: behavior.rewritePaths(binding.semantics, rewrite)
+  };
+}
 function groundedPairingKey(binding, deployedAs) {
   const behavior = behaviorOf(binding.semantics);
   const grounded = behavior.groundName?.(binding.semantics, deployedAs) ?? null;
@@ -934,6 +1054,10 @@ function servesRequest(binding, method, path) {
   }
   return serves(binding.semantics, method, path);
 }
+function withinScope(binding, scope) {
+  const within = behaviorOf(binding.semantics).withinScope;
+  return within === void 0 ? false : within(binding.semantics, scope);
+}
 
 // src/dispatch.ts
 function dispatchByType(table, value) {
@@ -1070,6 +1194,57 @@ function referenceFromName(name) {
   return referenceOf(parseBoundaryName(name));
 }
 
+// src/boundarySpelling.ts
+function resourceNameIn(spelling) {
+  if (spelling.startsWith("arn:")) {
+    const segments2 = spelling.split(":");
+    return segments2[6] ?? segments2[5] ?? spelling;
+  }
+  const segments = spelling.split("/");
+  if (segments.length >= 4 && segments.length % 2 === 0) {
+    return segments[segments.length - 1] ?? spelling;
+  }
+  return spelling;
+}
+function spellingTokens(text) {
+  return text.toLowerCase().replace(/[{}]/g, " ").split(/[\s:#,()/]+/).filter((token) => token.length > 0);
+}
+function bindingTokens(binding) {
+  const tokens = new Set(spellingTokens(displayLabel(binding)));
+  for (const value of Object.values(binding.semantics)) {
+    if (typeof value === "string") {
+      for (const token of spellingTokens(value)) {
+        tokens.add(token);
+      }
+    }
+  }
+  for (const token of [...tokens]) {
+    for (const part of token.split(".")) {
+      tokens.add(part);
+    }
+  }
+  return tokens;
+}
+function namesBoundaryExactly(subject, binding) {
+  const wanted = new Set(spellingTokens(subject));
+  if (wanted.size === 0) {
+    return false;
+  }
+  const spelled = new Set(spellingTokens(displayLabel(binding)));
+  if (spelled.size !== wanted.size) {
+    return false;
+  }
+  return [...spelled].every((token) => wanted.has(token));
+}
+function namesBoundary(subject, binding) {
+  const wanted = spellingTokens(subject);
+  if (wanted.length === 0) {
+    return false;
+  }
+  const tokens = bindingTokens(binding);
+  return wanted.every((token) => tokens.has(token));
+}
+
 // src/codeScope.ts
 function codeScopePath(raw) {
   return raw.trim().replace(/^\.\//, "").replace(/\/+$/, "");
@@ -1083,26 +1258,36 @@ function fileInCodeScope(file, scope) {
   return path === prefix || path.startsWith(`${prefix}/`);
 }
 
+// src/relation.ts
+var import_zod13 = require("zod");
+var RelationSchema = import_zod13.z.enum([
+  "provides",
+  "reads",
+  "writes",
+  "invokes"
+]);
+var EffectRelationSchema = RelationSchema.exclude(["provides"]);
+
 // src/suppressions.ts
-var import_zod12 = require("zod");
-var SuppressionSideSchema = import_zod12.z.object({
-  summary: import_zod12.z.string().optional(),
-  transitionId: import_zod12.z.string().optional()
+var import_zod14 = require("zod");
+var SuppressionSideSchema = import_zod14.z.object({
+  summary: import_zod14.z.string().optional(),
+  transitionId: import_zod14.z.string().optional()
 }).optional();
-var SuppressionRuleSchema = import_zod12.z.object({
+var SuppressionRuleSchema = import_zod14.z.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.
    */
-  kind: import_zod12.z.string().optional(),
+  kind: import_zod14.z.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.
    */
-  boundary: import_zod12.z.string().optional(),
+  boundary: import_zod14.z.string().optional(),
   /**
    * Consumer-side discriminators, the narrowest useful match. These
    * mean something only for behavioural findings: a rule that
@@ -1125,15 +1310,15 @@ var SuppressionRuleSchema = import_zod12.z.object({
    * kind-only or boundary-only matches, which also silence future
    * regressions in that category.
    */
-  scope: import_zod12.z.enum(["narrow", "broad"]).default("narrow"),
+  scope: import_zod14.z.enum(["narrow", "broad"]).default("narrow"),
   /** Required human-written justification. */
-  reason: import_zod12.z.string().min(1),
+  reason: import_zod14.z.string().min(1),
   /** What to do when a finding matches. */
-  effect: import_zod12.z.enum(["mark", "downgrade", "hide"]).default("mark")
+  effect: import_zod14.z.enum(["mark", "downgrade", "hide"]).default("mark")
 }).strict();
-var SuppressionFileSchema = import_zod12.z.object({
-  version: import_zod12.z.literal(1),
-  rules: import_zod12.z.array(SuppressionRuleSchema)
+var SuppressionFileSchema = import_zod14.z.object({
+  version: import_zod14.z.literal(1),
+  rules: import_zod14.z.array(SuppressionRuleSchema)
 }).strict();
 function validateRule(rule) {
   if (rule.scope === "broad") {
@@ -1423,6 +1608,17 @@ function runtimeConfigBinding(opts) {
     recognition: opts.recognition
   };
 }
+function unitInvocationBinding(opts) {
+  return {
+    transport: "invoke",
+    semantics: {
+      name: "unit-invocation",
+      deploymentTarget: opts.deploymentTarget,
+      instanceName: namedOrNull(opts.instanceName, "invoked unit")
+    },
+    recognition: opts.recognition
+  };
+}
 function storageBinding(opts) {
   return {
     transport: opts.transport ?? opts.storageSystem,
@@ -1466,11 +1662,14 @@ function metricBinding(opts) {
   ConfidenceSourceSchema,
   CorroborationSchema,
   DeployableUnitSchema,
+  EVERY_FIELD,
+  EffectRelationSchema,
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
   MessageBusSemanticsSchema,
   MetricSemanticsSchema,
+  RelationSchema,
   RestSemanticsSchema,
   RuntimeConfigSemanticsSchema,
   SemanticsSchema,
@@ -1479,7 +1678,10 @@ function metricBinding(opts) {
   SuppressionFileSchema,
   SuppressionRuleSchema,
   TypeShapeSchema,
+  UnitInvocationSemanticsSchema,
   applySuppressionsToFindings,
+  bindingIs,
+  bindingTokens,
   bodyShapesMatch,
   boundaryKey,
   boundaryLabel,
@@ -1512,6 +1714,8 @@ function metricBinding(opts) {
   namePatternFromSub,
   namePatternKey,
   namesAgree,
+  namesBoundary,
+  namesBoundaryExactly,
   namesNothing,
   normalizePath,
   normalizeRuleBoundary,
@@ -1526,6 +1730,7 @@ function metricBinding(opts) {
   referenceName,
   referenceOf,
   reportsUnpairedItself,
+  resourceNameIn,
   restBinding,
   routePathAdmits,
   ruleBoundaryMatchesKey,
@@ -1533,9 +1738,16 @@ function metricBinding(opts) {
   semanticsAgree,
   semconvAttributes,
   servesRequest,
+  spellingTokens,
   statesAnOrigin,
   storageBinding,
+  storageContainerLabel,
+  storageLabel,
   typeDefinitionKey,
+  unitIdentityKey,
+  unitInvocationBinding,
   validateRule,
-  withDefinitionsInlined
+  withDefinitionsInlined,
+  withRewrittenPaths,
+  withinScope
 });