@suss/contract-aws-apigateway 0.3.2 → 0.5.0

package/README.md

@@ -4,11 +4,11 @@ Generate suss `BehavioralSummary[]` for AWS API Gateway resources (REST + HTTP A
 
 ## What this package is
 
-`@suss/contract-aws-apigateway` is a **resource-semantics stub**: it knows what an API Gateway endpoint *does* (status codes, authorizer behavior, CORS preflight, throttling) given a normalized configuration. It does **not** know how that configuration was authored; that's the job of a manifest reader (`@suss/contract-cloudformation`, future CDK/Terraform readers), which parses its source format and hands a normalized config to this package.
+`@suss/contract-aws-apigateway` is a **resource-semantics stub**: given a normalized configuration, it knows what an API Gateway endpoint *does* (status codes, authorizer behavior, CORS preflight, throttling). It does **not** know how someone wrote that configuration; a manifest reader does that job (`@suss/contract-cloudformation`, future CDK/Terraform readers), parsing its source format and handing a normalized config to this package.
 
 This separation means: configure your API in CloudFormation, CDK, SAM, or Terraform, and the same resource semantics produce the same summary.
 
-## Where it sits
+## Where it fits
 
 ```
 packages/contract/
@@ -23,7 +23,7 @@ packages/contract/
 
 A handler that only returns `200` produces a *much* larger behavioral envelope once it's deployed behind API Gateway: an authorizer adds `401`/`403`, request validation adds `400`, throttling adds `429`, integration timeouts add `504`, CORS adds an `OPTIONS` preflight endpoint. Without modeling these, a consumer that handles `429` looks like it has a dead branch, when in reality the platform produces `429` even though the handler doesn't.
 
-These transitions are emitted with `confidence.source: "derived"` and an opaque `Predicate` of the form `platform:apiGateway:<contract>`. Per-transition `metadata` carries attribution (which configuration field introduced this transition) for `inspect`/`diff` output, without forcing consumers to disambiguate platform causes.
+These transitions are emitted with `confidence.source: "derived"` and an opaque `Predicate` of the form `platform:apiGateway:<contract>`. Each transition's `metadata` records where the transition came from (which configuration field introduced it) for `inspect`/`diff` output, so consumers do not have to work out the platform cause themselves.
 
 ## Coverage
 

package/dist/index.cjs

@@ -303,11 +303,13 @@ function buildRouteSummary(route, parsed, api, sourceFile) {
     transitions,
     gaps: [],
     confidence: { source: "derived", level: "high" },
-    metadata: {
-      apiId: api.id,
-      apiVersion: "v2",
-      integrationType: route.integration.type,
-      http: {
+    metadata: (0, import_behavioral_ir2.withHttpMetadata)(
+      {
+        apiId: api.id,
+        apiVersion: "v2",
+        integrationType: route.integration.type
+      },
+      {
         declaredContract: {
           framework: FRAMEWORK,
           provenance: "independent",
@@ -321,7 +323,7 @@ function buildRouteSummary(route, parsed, api, sourceFile) {
         // REST binding.
         ...route.implementingHandler !== void 0 ? { implementingHandler: route.implementingHandler } : {}
       }
-    }
+    )
   };
 }
 function collectPlatformContributions(route, api) {
@@ -475,16 +477,19 @@ function buildEndpointSummary(endpoint, api, sourceFile) {
     transitions,
     gaps: [],
     confidence: { source: "derived", level: "high" },
-    metadata: {
-      apiId: api.id,
-      integrationType: endpoint.integration.type,
-      http: {
+    metadata: (0, import_behavioral_ir3.withHttpMetadata)(
+      {
+        apiId: api.id,
+        integrationType: endpoint.integration.type
+      },
+      {
         // The integration's declared status codes (from MethodResponses
-        // in the CFN template) are the declared contract here. Platform-
-        // injected transitions (authorizer 401/403, throttle 429, etc.)
-        // come from SEPARATE config fields and so are independent from
-        // this contract — contract-consistency comparison is meaningful
-        // and will surface template-internal inconsistencies.
+        // in the CFN template) are the declared contract here.
+        // Platform-injected transitions (authorizer 401/403, throttle
+        // 429, etc.) come from SEPARATE config fields and so are
+        // independent from this contract: contract-consistency
+        // comparison is meaningful and will surface template-internal
+        // inconsistencies.
         declaredContract: {
           framework: FRAMEWORK,
           provenance: "independent",
@@ -498,7 +503,7 @@ function buildEndpointSummary(endpoint, api, sourceFile) {
         // same REST binding.
         ...endpoint.implementingHandler !== void 0 ? { implementingHandler: endpoint.implementingHandler } : {}
       }
-    }
+    )
   };
 }
 function collectPlatformContributions2(endpoint, api) {

package/dist/index.d.cts

@@ -55,13 +55,13 @@ interface RequestValidationConfig {
 /**
  * Pointer from a declared route to the code that implements it. A
  * manifest reader (CFN/SAM, CDK, Terraform) fills this in when it knows
- * which module + export backs the route — e.g. a SAM Lambda proxy
- * integration whose `Handler` names the file and export. The fields are
+ * which module + export backs the route, e.g. a SAM Lambda proxy
+ * integration whose `Handler` gives the file and export. The fields are
  * generic "where is the code" identity, not any one manifest's
- * semantics; `aws-apigateway` carries the pointer onto the summary
+ * semantics; `aws-apigateway` puts the pointer onto the summary
  * (`metadata.http.implementingHandler`) without interpreting it, so a
  * checker can later correlate the declared route with the extracted
- * handler summary that carries the same REST binding.
+ * handler summary with the same REST binding.
  */
 interface HandlerPointer {
     /** Raw handler reference, e.g. "src/handlers/confirmToken.handler". */
@@ -90,7 +90,7 @@ interface IntegrationConfig {
      * Status codes the backend integration can produce. For proxy
      * integrations this is what the handler emits; for non-proxy it's
      * what `IntegrationResponses` map to. Empty array is allowed and
-     * means "we don't know" — only platform-injected transitions will
+     * means "we don't know", only platform-injected transitions will
      * be emitted.
      */
     statusCodes: number[];
@@ -122,7 +122,7 @@ interface RestEndpointConfig {
      */
     name?: string;
     /**
-     * Code that implements this endpoint, when the manifest names it
+     * Code that implements this endpoint, when the manifest says which
      * (SAM Lambda proxy `Handler`). Emitted as
      * `metadata.http.implementingHandler`; purely additive.
      */
@@ -138,7 +138,7 @@ interface RestApiConfig {
     /** API-level defaults that cascade onto endpoints unless overridden. */
     defaultAuthorizer?: AuthorizerConfig;
     defaultThrottle?: ThrottleConfig;
-    /** API-level CORS — produces an OPTIONS endpoint per resource path. */
+    /** API-level CORS: produces an OPTIONS endpoint per resource path. */
     cors?: CorsConfig;
     /** Binary media types declared on the API; doesn't affect transitions. */
     binaryMediaTypes?: string[];
@@ -161,7 +161,7 @@ interface HttpRouteConfig {
     throttle?: ThrottleConfig;
     name?: string;
     /**
-     * Code that implements this route, when the manifest names it (SAM
+     * Code that implements this route, when the manifest says which (SAM
      * Lambda proxy `Handler`). Emitted as
      * `metadata.http.implementingHandler`; purely additive.
      */

package/dist/index.d.ts

@@ -55,13 +55,13 @@ interface RequestValidationConfig {
 /**
  * Pointer from a declared route to the code that implements it. A
  * manifest reader (CFN/SAM, CDK, Terraform) fills this in when it knows
- * which module + export backs the route — e.g. a SAM Lambda proxy
- * integration whose `Handler` names the file and export. The fields are
+ * which module + export backs the route, e.g. a SAM Lambda proxy
+ * integration whose `Handler` gives the file and export. The fields are
  * generic "where is the code" identity, not any one manifest's
- * semantics; `aws-apigateway` carries the pointer onto the summary
+ * semantics; `aws-apigateway` puts the pointer onto the summary
  * (`metadata.http.implementingHandler`) without interpreting it, so a
  * checker can later correlate the declared route with the extracted
- * handler summary that carries the same REST binding.
+ * handler summary with the same REST binding.
  */
 interface HandlerPointer {
     /** Raw handler reference, e.g. "src/handlers/confirmToken.handler". */
@@ -90,7 +90,7 @@ interface IntegrationConfig {
      * Status codes the backend integration can produce. For proxy
      * integrations this is what the handler emits; for non-proxy it's
      * what `IntegrationResponses` map to. Empty array is allowed and
-     * means "we don't know" — only platform-injected transitions will
+     * means "we don't know", only platform-injected transitions will
      * be emitted.
      */
     statusCodes: number[];
@@ -122,7 +122,7 @@ interface RestEndpointConfig {
      */
     name?: string;
     /**
-     * Code that implements this endpoint, when the manifest names it
+     * Code that implements this endpoint, when the manifest says which
      * (SAM Lambda proxy `Handler`). Emitted as
      * `metadata.http.implementingHandler`; purely additive.
      */
@@ -138,7 +138,7 @@ interface RestApiConfig {
     /** API-level defaults that cascade onto endpoints unless overridden. */
     defaultAuthorizer?: AuthorizerConfig;
     defaultThrottle?: ThrottleConfig;
-    /** API-level CORS — produces an OPTIONS endpoint per resource path. */
+    /** API-level CORS: produces an OPTIONS endpoint per resource path. */
     cors?: CorsConfig;
     /** Binary media types declared on the API; doesn't affect transitions. */
     binaryMediaTypes?: string[];
@@ -161,7 +161,7 @@ interface HttpRouteConfig {
     throttle?: ThrottleConfig;
     name?: string;
     /**
-     * Code that implements this route, when the manifest names it (SAM
+     * Code that implements this route, when the manifest says which (SAM
      * Lambda proxy `Handler`). Emitted as
      * `metadata.http.implementingHandler`; purely additive.
      */

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/http.ts
-import { restBinding as restBinding2 } from "@suss/behavioral-ir";
+import { restBinding as restBinding2, withHttpMetadata } from "@suss/behavioral-ir";
 
 // src/shared.ts
 import { restBinding } from "@suss/behavioral-ir";
@@ -276,11 +276,13 @@ function buildRouteSummary(route, parsed, api, sourceFile) {
     transitions,
     gaps: [],
     confidence: { source: "derived", level: "high" },
-    metadata: {
-      apiId: api.id,
-      apiVersion: "v2",
-      integrationType: route.integration.type,
-      http: {
+    metadata: withHttpMetadata(
+      {
+        apiId: api.id,
+        apiVersion: "v2",
+        integrationType: route.integration.type
+      },
+      {
         declaredContract: {
           framework: FRAMEWORK,
           provenance: "independent",
@@ -294,7 +296,7 @@ function buildRouteSummary(route, parsed, api, sourceFile) {
         // REST binding.
         ...route.implementingHandler !== void 0 ? { implementingHandler: route.implementingHandler } : {}
       }
-    }
+    )
   };
 }
 function collectPlatformContributions(route, api) {
@@ -362,7 +364,7 @@ function uniquePaths(routes) {
 }
 
 // src/rest.ts
-import { restBinding as restBinding3 } from "@suss/behavioral-ir";
+import { restBinding as restBinding3, withHttpMetadata as withHttpMetadata2 } from "@suss/behavioral-ir";
 function restApiToSummaries(config) {
   const sourceFile = config.source ?? `aws-apigateway:${config.id}`;
   const summaries = [];
@@ -448,16 +450,19 @@ function buildEndpointSummary(endpoint, api, sourceFile) {
     transitions,
     gaps: [],
     confidence: { source: "derived", level: "high" },
-    metadata: {
-      apiId: api.id,
-      integrationType: endpoint.integration.type,
-      http: {
+    metadata: withHttpMetadata2(
+      {
+        apiId: api.id,
+        integrationType: endpoint.integration.type
+      },
+      {
         // The integration's declared status codes (from MethodResponses
-        // in the CFN template) are the declared contract here. Platform-
-        // injected transitions (authorizer 401/403, throttle 429, etc.)
-        // come from SEPARATE config fields and so are independent from
-        // this contract — contract-consistency comparison is meaningful
-        // and will surface template-internal inconsistencies.
+        // in the CFN template) are the declared contract here.
+        // Platform-injected transitions (authorizer 401/403, throttle
+        // 429, etc.) come from SEPARATE config fields and so are
+        // independent from this contract: contract-consistency
+        // comparison is meaningful and will surface template-internal
+        // inconsistencies.
         declaredContract: {
           framework: FRAMEWORK,
           provenance: "independent",
@@ -471,7 +476,7 @@ function buildEndpointSummary(endpoint, api, sourceFile) {
         // same REST binding.
         ...endpoint.implementingHandler !== void 0 ? { implementingHandler: endpoint.implementingHandler } : {}
       }
-    }
+    )
   };
 }
 function collectPlatformContributions2(endpoint, api) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-aws-apigateway",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "Generate suss behavioral summaries for AWS API Gateway resources (REST + HTTP API), independent of how they were deployed.",
   "keywords": [
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.3.2"
+    "@suss/behavioral-ir": "0.5.0"
   },
   "devDependencies": {
     "tsup": "*",