@suss/contract-appsync 0.33.1 → 0.34.0

package/README.md

@@ -1,17 +1,17 @@
 # @suss/contract-appsync
 
-Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
+Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and reports where the two disagree.
 
-Generate suss `BehavioralSummary[]` from an [AWS AppSync](https://docs.aws.amazon.com/appsync/) API declared in a CloudFormation or [SAM](https://aws.amazon.com/serverless/sam/) template. AppSync is schema-first: the SDL is authored by hand and the template binds each `(TypeName, FieldName)` pair to a data source. This reader turns that wiring into resolver summaries you can check consumers against, without deploying the stack or exporting anything from AWS.
+This package builds suss `BehavioralSummary[]` from an [AWS AppSync](https://docs.aws.amazon.com/appsync/) API declared in a CloudFormation or [SAM](https://aws.amazon.com/serverless/sam/) template. AppSync is schema-first: you write the SDL by hand, and the template binds each `(TypeName, FieldName)` pair to a data source. This reader turns that wiring into resolver summaries you can check consumers against, without deploying the stack or exporting anything from AWS.
 
 ## What this package reads
 
-`@suss/contract-appsync` walks the template's `Resources` map and covers both ways an AppSync API gets written:
+`@suss/contract-appsync` walks the template's `Resources` map, and covers both ways of writing an AppSync API:
 
-- **Raw resources**: `AWS::AppSync::GraphQLApi`, `AWS::AppSync::GraphQLSchema`, `AWS::AppSync::Resolver`, `AWS::AppSync::FunctionConfiguration`, and `AWS::AppSync::DataSource`.
-- **The SAM shorthand** `AWS::Serverless::GraphQLApi`, whose inline `SchemaInline` / `SchemaUri`, `DataSources`, `Functions`, and `Resolvers` blocks are normalized into the same model before any summary is built. Synthesized logical ids are prefixed with the API's logical id, so two GraphQL APIs in one template stay apart.
+- **Raw resources**: `AWS::AppSync::GraphQLApi`, `AWS::AppSync::GraphQLSchema`, `AWS::AppSync::Resolver`, `AWS::AppSync::FunctionConfiguration` and `AWS::AppSync::DataSource`.
+- **The SAM shorthand** `AWS::Serverless::GraphQLApi`. Its inline `SchemaInline` / `SchemaUri`, `DataSources`, `Functions` and `Resolvers` blocks are converted into the same model before any summary is built. Generated logical ids are prefixed with the API's logical id, so two GraphQL APIs in one template stay apart.
 
-The SDL comes from the inline `Definition` / `SchemaInline` property, or from a local file when `DefinitionS3Location` / `SchemaUri` is a path (resolved against the template's directory). An `s3://` or `http(s)://` URI cannot be fetched by a static reader, and neither can a location the template computes through an intrinsic. Both cases are recorded under `metadata.appsync.schemaSource` with a `status` of `"unresolved"` and a reason, so a schema the reader could not open is never silent.
+The SDL comes from the inline `Definition` / `SchemaInline` property, or from a local file when `DefinitionS3Location` / `SchemaUri` is a path, resolved against the template's directory. A static reader cannot fetch an `s3://` or `http(s)://` URI, or a location the template computes with an intrinsic. Both cases are recorded under `metadata.appsync.schemaSource` with a `status` of `"unresolved"` and a reason, so a schema the reader could not open is always reported.
 
 ## What it produces
 
@@ -19,23 +19,23 @@ One `resolver`-kind summary per resolver, plus one `library`-kind summary per AP
 
 Each resolver summary has:
 
-- `identity.name`: `Type.field`, and a `graphql-resolver` boundary binding with `transport: "aws-https"`, `recognition: "appsync"`, plus the type and field names. That pairs against resolvers the Apollo and NestJS packs extract from code, and against clients that cross the same field.
+- `identity.name`: `Type.field`, and a `graphql-resolver` boundary binding with `transport: "aws-https"`, `recognition: "appsync"`, and the type and field names. It pairs with resolvers that the Apollo and NestJS packs extract from code, and with clients that use the same field.
 - Inputs from the SDL field's arguments, each with `role: "args"` and the argument's type converted to a suss `TypeShape`.
-- Two transitions: a default success returning the field's declared shape, and a generic throw for the GraphQL `errors[]` path.
-- `metadata.appsync`: the API's logical id and name, the data source's logical id, the Lambda function behind that data source, the resolver kind (`UNIT` or `PIPELINE`), the authentication type, the `CodeUri` and runtime for SAM resolvers written as JS or VTL, whether the schema declared the field (`schemaMatched`), and, for pipeline resolvers, the ordered function chain with each step's own data source and Lambda.
+- Two transitions: a default success that returns the field's declared shape, and a generic throw for the GraphQL `errors[]` path.
+- `metadata.appsync`: the API's logical id and name, the data source's logical id, the Lambda function behind that data source, the resolver kind (`UNIT` or `PIPELINE`), and the authentication type. For SAM resolvers written as JS or VTL it also has the `CodeUri` and runtime. It records whether the schema declared the field (`schemaMatched`), and for pipeline resolvers, the ordered chain of functions, with each step's own data source and Lambda.
 
-A resolver whose field the SDL never declares still gets a summary. AppSync rejects that stack at deploy time, and reporting the boundary is more useful than dropping it. Its success transition returns `unknown` and `schemaMatched` is `false`.
+A resolver whose field the SDL never declares still gets a summary. AppSync rejects that stack at deploy time, so reporting the boundary helps more than dropping it. Its success transition returns `unknown`, and `schemaMatched` is `false`.
 
-The `library` summary is where the SDL itself goes. Type definitions belong to the schema rather than to any one field, so each resolver points at that document through a source-document label, and the checker follows the label to resolve a consumer's nested selections against the resolver's return type. It binds to no boundary, so pairing records it as taking no part.
+The `library` summary contains the SDL itself. Type definitions belong to the schema as a whole, so each resolver points at that document through a source-document label. The checker follows the label to resolve a consumer's nested selections against the resolver's return type. The `library` summary does not bind to a boundary, so pairing records it as taking no part.
 
-Data source types are normalized from `AWS_LAMBDA`, `AMAZON_DYNAMODB`, `AMAZON_ELASTICSEARCH`, `AMAZON_OPENSEARCH_SERVICE`, `HTTP`, `RELATIONAL_DATABASE`, `AMAZON_EVENTBRIDGE`, and `NONE`. Anything else comes back as `"unknown"`.
+Data source types are normalized from `AWS_LAMBDA`, `AMAZON_DYNAMODB`, `AMAZON_ELASTICSEARCH`, `AMAZON_OPENSEARCH_SERVICE`, `HTTP`, `RELATIONAL_DATABASE`, `AMAZON_EVENTBRIDGE` and `NONE`. Anything else comes back as `"unknown"`.
 
 ## What it does not read
 
-- **Resolver code.** A SAM resolver's `CodeUri` and runtime are recorded, and the file behind them is never opened. VTL request and response mapping templates on raw `AWS::AppSync::Resolver` resources are ignored.
-- **Dynamic intrinsics.** A resolver whose `TypeName` or `FieldName` comes from a `!Ref` or an `Fn::Join` is skipped rather than guessed at. A pipeline whose `Functions` array cannot be resolved statically still reports `kind: "PIPELINE"` with an empty chain.
+- **Resolver code.** A SAM resolver's `CodeUri` and runtime are recorded, but the file behind them is never opened. VTL request and response mapping templates on raw `AWS::AppSync::Resolver` resources are ignored.
+- **Dynamic intrinsics.** A resolver whose `TypeName` or `FieldName` comes from a `!Ref` or an `Fn::Join` is skipped, so the reader never guesses. A pipeline whose `Functions` array cannot be resolved statically still reports `kind: "PIPELINE"`, with an empty chain.
 - **Remote schemas.** Nothing is fetched over the network.
-- **Authorization.** The API's `AuthenticationType` is recorded on each resolver and does not become extra transitions.
+- **Authorization.** The API's `AuthenticationType` is recorded on each resolver, and does not add transitions.
 - **Nested stacks.** Only the template you point at is walked.
 
 ## Worked example
@@ -67,9 +67,9 @@ Resources:
 suss contract --from appsync template.yaml -o summaries/appsync.json
 ```
 
-That gives a `Query.order` resolver summary with one `id` input of type `ID`, a success transition returning a `ref` to `Order`, and the SDL under the API's schema document summary.
+That produces a `Query.order` resolver summary with one `id` input of type `ID` and a success transition that returns a `ref` to `Order`. The SDL goes in the API's schema document summary.
 
-Or programmatically, when you already have the template in memory (a CDK `Template.fromStack`, JSON from a build tool):
+If you already have the template in memory, such as a CDK `Template.fromStack` or JSON from a build tool, call it from code:
 
 ```ts
 import { appsyncToSummaries } from "@suss/contract-appsync";
@@ -79,7 +79,7 @@ const summaries = appsyncToSummaries(template, { baseDir: "infra" });
 
 ## Where it fits in suss
 
-Depends on `@suss/behavioral-ir` (for the IR types it produces), `@suss/contract-graphql` (for SDL parsing, the type conversion, and loading an external schema file), `@suss/manifest-aws` (for template loading, including CloudFormation YAML intrinsic shorthand), and `graphql`. It does not extract from source code and is independent of the language adapters.
+The package depends on `@suss/behavioral-ir` for the IR types it produces, `@suss/contract-graphql` for SDL parsing, type conversion and loading an external schema file, `@suss/manifest-aws` for loading templates (including CloudFormation's YAML shorthand for intrinsics), and `graphql`. It does not extract from source code and does not use the language adapters.
 
 ## More
 

package/dist/index.cjs

@@ -393,8 +393,8 @@ function parseSchema(sdl) {
     return index;
   }
   for (const def of doc.definitions) {
-    if (def.kind !== import_graphql.Kind.OBJECT_TYPE_DEFINITION && def.kind !== import_graphql.Kind.OBJECT_TYPE_EXTENSION && def.kind !== import_graphql.Kind.INTERFACE_TYPE_DEFINITION && // A schema splits an interface the same way it splits a type, so
-    // wherever an interface counts, so does an extension of one.
+    if (def.kind !== import_graphql.Kind.OBJECT_TYPE_DEFINITION && def.kind !== import_graphql.Kind.OBJECT_TYPE_EXTENSION && def.kind !== import_graphql.Kind.INTERFACE_TYPE_DEFINITION && // `extend interface` splits an interface the same way `extend type`
+    // splits a type.
     def.kind !== import_graphql.Kind.INTERFACE_TYPE_EXTENSION) {
       continue;
     }
@@ -570,10 +570,7 @@ function buildOne(resolver, indexes, resolvedByApi, schemasByApi, sourceFile) {
       name: ownerKey,
       exportPath: null,
       boundaryBinding: (0, import_behavioral_ir.graphqlResolverBinding)({
-        // AppSync is invoked over HTTPS-to-AWS. Keeping transport
-        // explicit here matches the aws-apigateway reader's posture
-        // and leaves room for a future AWS-SDK-direct transport
-        // ("aws-sdk") once Lambda-invoke semantics land.
+        // Clients reach AppSync over HTTPS to an AWS endpoint.
         transport: "aws-https",
         recognition: "appsync",
         typeName: resolver.typeName,
@@ -611,28 +608,22 @@ function buildAppsyncMetadata(resolver, api, resolved, field, indexes) {
     apiLogicalId: resolver.apiLogicalId,
     apiName: api?.name ?? null,
     dataSourceLogicalId: resolver.dataSourceLogicalId,
-    // Lambda behind this resolver's own data source (UNIT resolvers).
-    // PIPELINE resolvers attribute per-function below; their top-level
-    // data source is null, so this is null too.
+    // Only a UNIT resolver has its own data source. A pipeline records
+    // the Lambda behind each of its functions instead.
     lambdaFunctionLogicalId: lambdaBehind(
       resolver.dataSourceLogicalId,
       indexes
     ),
     kind: resolver.kind,
     authenticationType: api?.authenticationType ?? null,
-    // SAM JS/VTL resolver code location + runtime (null for raw
-    // AWS::AppSync::Resolver resources).
     codeUri: resolver.codeUri,
     runtime: resolver.runtime,
-    // Distinguish "schema said X" from "we didn't see a schema at all"
-    // (field-level), and record how the SDL itself was obtained
-    // (source-level) so a genuinely-remote schema is never silent.
+    // Keeps a field the SDL does not declare apart from a schema that was
+    // never read, such as a remote one.
     schemaMatched: field !== null,
     schemaSource: schemaSourceMetadata(resolved),
-    // For PIPELINE resolvers, surface the ordered function chain so
-    // downstream tools can show the dispatch path. Empty for UNIT
-    // resolvers; empty with `kind: "PIPELINE"` means the Functions
-    // array was dynamically-referenced and we couldn't resolve it.
+    // Left out for a UNIT resolver, and for a pipeline whose Functions
+    // list cannot be read statically.
     ...pipelineFunctions.length > 0 ? { pipelineFunctions } : {}
   };
 }

package/dist/index.d.cts

@@ -1,5 +1,13 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
+/**
+ * Reads the raw AWS::AppSync resources in a template and adds what the
+ * SAM AWS::Serverless::GraphQLApi reader finds, so both ways of writing
+ * an API reach the summary builder as one model.
+ *
+ * A value written with a dynamic intrinsic, such as `!Ref` to a
+ * parameter, is left unresolved and reported. The reader never guesses it.
+ */
 interface CfnTemplate {
     Resources?: Record<string, CfnResource | undefined>;
 }
@@ -8,27 +16,33 @@ interface CfnResource {
     Properties?: Record<string, unknown>;
 }
 
+/**
+ * Reads an AWS AppSync API from a CloudFormation or SAM template and
+ * writes one resolver summary per resolver. Each is keyed by type and
+ * field name, the same way as a resolver found in code, so the two pair
+ * directly. The Lambda behind each data source is recorded so the
+ * summary can later be matched to handler code.
+ *
+ * The README lists the resources and schema sources this reads.
+ */
+
 interface AppsyncToSummariesOptions {
-    /** Logical source path recorded on each summary's `location.file`. */
+    /** Path recorded on each summary's `location.file`. */
     source?: string;
     /**
-     * Directory used to resolve relative external schema paths
-     * (`DefinitionS3Location` / `SchemaUri`). `appsyncFileToSummaries`
-     * sets this to the template's directory; in-memory callers pass it
-     * when their schema references are relative.
+     * The directory a relative `DefinitionS3Location` or `SchemaUri`
+     * resolves against. `appsyncFileToSummaries` sets it to the template's.
      */
     baseDir?: string;
 }
 /**
- * Convert an already-parsed CloudFormation / SAM template to AppSync
- * resolver summaries. Call this when the caller has a template object in
- * memory (CDK `Template.fromStack`, JSON from a build tool, etc.).
+ * Converts a template already in memory, such as a CDK
+ * `Template.fromStack` result, to AppSync resolver summaries.
  */
 declare function appsyncToSummaries(template: CfnTemplate, options?: AppsyncToSummariesOptions): BehavioralSummary[];
 /**
- * Read a CloudFormation / SAM template from disk and emit resolver
- * summaries. Accepts JSON and YAML (SAM / CDK-synth shapes). Relative
- * external schema paths resolve against the template's directory.
+ * Reads a CloudFormation or SAM template, in JSON or YAML, and converts
+ * it. A relative schema path resolves against the template's directory.
  */
 declare function appsyncFileToSummaries(filePath: string, options?: AppsyncToSummariesOptions): BehavioralSummary[];
 

package/dist/index.d.ts

@@ -1,5 +1,13 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
+/**
+ * Reads the raw AWS::AppSync resources in a template and adds what the
+ * SAM AWS::Serverless::GraphQLApi reader finds, so both ways of writing
+ * an API reach the summary builder as one model.
+ *
+ * A value written with a dynamic intrinsic, such as `!Ref` to a
+ * parameter, is left unresolved and reported. The reader never guesses it.
+ */
 interface CfnTemplate {
     Resources?: Record<string, CfnResource | undefined>;
 }
@@ -8,27 +16,33 @@ interface CfnResource {
     Properties?: Record<string, unknown>;
 }
 
+/**
+ * Reads an AWS AppSync API from a CloudFormation or SAM template and
+ * writes one resolver summary per resolver. Each is keyed by type and
+ * field name, the same way as a resolver found in code, so the two pair
+ * directly. The Lambda behind each data source is recorded so the
+ * summary can later be matched to handler code.
+ *
+ * The README lists the resources and schema sources this reads.
+ */
+
 interface AppsyncToSummariesOptions {
-    /** Logical source path recorded on each summary's `location.file`. */
+    /** Path recorded on each summary's `location.file`. */
     source?: string;
     /**
-     * Directory used to resolve relative external schema paths
-     * (`DefinitionS3Location` / `SchemaUri`). `appsyncFileToSummaries`
-     * sets this to the template's directory; in-memory callers pass it
-     * when their schema references are relative.
+     * The directory a relative `DefinitionS3Location` or `SchemaUri`
+     * resolves against. `appsyncFileToSummaries` sets it to the template's.
      */
     baseDir?: string;
 }
 /**
- * Convert an already-parsed CloudFormation / SAM template to AppSync
- * resolver summaries. Call this when the caller has a template object in
- * memory (CDK `Template.fromStack`, JSON from a build tool, etc.).
+ * Converts a template already in memory, such as a CDK
+ * `Template.fromStack` result, to AppSync resolver summaries.
  */
 declare function appsyncToSummaries(template: CfnTemplate, options?: AppsyncToSummariesOptions): BehavioralSummary[];
 /**
- * Read a CloudFormation / SAM template from disk and emit resolver
- * summaries. Accepts JSON and YAML (SAM / CDK-synth shapes). Relative
- * external schema paths resolve against the template's directory.
+ * Reads a CloudFormation or SAM template, in JSON or YAML, and converts
+ * it. A relative schema path resolves against the template's directory.
  */
 declare function appsyncFileToSummaries(filePath: string, options?: AppsyncToSummariesOptions): BehavioralSummary[];
 

package/dist/index.js

@@ -361,8 +361,8 @@ function parseSchema(sdl) {
     return index;
   }
   for (const def of doc.definitions) {
-    if (def.kind !== Kind.OBJECT_TYPE_DEFINITION && def.kind !== Kind.OBJECT_TYPE_EXTENSION && def.kind !== Kind.INTERFACE_TYPE_DEFINITION && // A schema splits an interface the same way it splits a type, so
-    // wherever an interface counts, so does an extension of one.
+    if (def.kind !== Kind.OBJECT_TYPE_DEFINITION && def.kind !== Kind.OBJECT_TYPE_EXTENSION && def.kind !== Kind.INTERFACE_TYPE_DEFINITION && // `extend interface` splits an interface the same way `extend type`
+    // splits a type.
     def.kind !== Kind.INTERFACE_TYPE_EXTENSION) {
       continue;
     }
@@ -543,10 +543,7 @@ function buildOne(resolver, indexes, resolvedByApi, schemasByApi, sourceFile) {
       name: ownerKey,
       exportPath: null,
       boundaryBinding: graphqlResolverBinding({
-        // AppSync is invoked over HTTPS-to-AWS. Keeping transport
-        // explicit here matches the aws-apigateway reader's posture
-        // and leaves room for a future AWS-SDK-direct transport
-        // ("aws-sdk") once Lambda-invoke semantics land.
+        // Clients reach AppSync over HTTPS to an AWS endpoint.
         transport: "aws-https",
         recognition: "appsync",
         typeName: resolver.typeName,
@@ -584,28 +581,22 @@ function buildAppsyncMetadata(resolver, api, resolved, field, indexes) {
     apiLogicalId: resolver.apiLogicalId,
     apiName: api?.name ?? null,
     dataSourceLogicalId: resolver.dataSourceLogicalId,
-    // Lambda behind this resolver's own data source (UNIT resolvers).
-    // PIPELINE resolvers attribute per-function below; their top-level
-    // data source is null, so this is null too.
+    // Only a UNIT resolver has its own data source. A pipeline records
+    // the Lambda behind each of its functions instead.
     lambdaFunctionLogicalId: lambdaBehind(
       resolver.dataSourceLogicalId,
       indexes
     ),
     kind: resolver.kind,
     authenticationType: api?.authenticationType ?? null,
-    // SAM JS/VTL resolver code location + runtime (null for raw
-    // AWS::AppSync::Resolver resources).
     codeUri: resolver.codeUri,
     runtime: resolver.runtime,
-    // Distinguish "schema said X" from "we didn't see a schema at all"
-    // (field-level), and record how the SDL itself was obtained
-    // (source-level) so a genuinely-remote schema is never silent.
+    // Keeps a field the SDL does not declare apart from a schema that was
+    // never read, such as a remote one.
     schemaMatched: field !== null,
     schemaSource: schemaSourceMetadata(resolved),
-    // For PIPELINE resolvers, surface the ordered function chain so
-    // downstream tools can show the dispatch path. Empty for UNIT
-    // resolvers; empty with `kind: "PIPELINE"` means the Functions
-    // array was dynamically-referenced and we couldn't resolve it.
+    // Left out for a UNIT resolver, and for a pipeline whose Functions
+    // list cannot be read statically.
     ...pipelineFunctions.length > 0 ? { pipelineFunctions } : {}
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-appsync",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "type": "module",
   "description": "Turn the AppSync API in a CloudFormation or SAM template into a suss contract and check it against the resolvers and clients on either side of it.",
   "keywords": [
@@ -15,7 +15,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/appsync#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -48,9 +48,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.33.1",
-    "@suss/contract-graphql": "0.33.1",
-    "@suss/manifest-aws": "0.33.1",
+    "@suss/behavioral-ir": "0.34.0",
+    "@suss/contract-graphql": "0.34.0",
+    "@suss/manifest-aws": "0.34.0",
     "graphql": "^16.8.0"
   },
   "devDependencies": {