@suss/contract-appsync 0.36.0 → 0.37.0

package/README.md

@@ -11,7 +11,11 @@ This package builds suss `BehavioralSummary[]` from an [AWS AppSync](https://doc
 - **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. 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.
+A resolver or a pipeline function can point at its data source by logical id or by the data source's `Name`. A name is looked up among the data sources of the same API, so two APIs can each have a data source called `orders`.
+
+The reader also reads every template the file embeds through an `AWS::CloudFormation::Stack` or `AWS::Serverless::Application`, and treats them as one API surface. A child's resources get the stack path in front of their logical id, as in `DirectoryStack/DirectoryFunction`, the same id the aws-lambda pack gives that function. When a parent passes a resource to a child as a parameter, such as `ApiId: !GetAtt Api.ApiId`, the child's `!Ref ApiId` reads as that resource, so a child's resolvers attach to the API and schema the root declares. A child it cannot open is reported by name.
+
+The SDL comes from the inline `Definition` / `SchemaInline` property, or from a local file when `DefinitionS3Location` / `SchemaUri` is a path, resolved against the directory of the template that declares it. 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
 
@@ -36,7 +40,7 @@ Data source types are normalized from `AWS_LAMBDA`, `AMAZON_DYNAMODB`, `AMAZON_E
 - **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 add transitions.
-- **Nested stacks.** Only the template you point at is walked.
+- **Stack outputs.** A parent that reads a child's resource through `!GetAtt Child.Outputs.X` points at nothing the reader follows.
 
 ## Worked example
 

package/dist/index.cjs

@@ -36,12 +36,22 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_node_path2 = __toESM(require("path"), 1);
 var import_files = require("@suss/behavioral-ir/files");
-var import_manifest_aws2 = require("@suss/manifest-aws");
+var import_manifest_aws4 = require("@suss/manifest-aws");
+
+// src/cfn.ts
+var import_manifest_aws3 = require("@suss/manifest-aws");
 
 // src/refs.ts
 var import_manifest_aws = require("@suss/manifest-aws");
-function resolveLogicalRef(value) {
-  return (0, import_manifest_aws.refTarget)(value);
+var OWN_DOCUMENT = {
+  own: (logicalId) => logicalId,
+  ref: (value) => (0, import_manifest_aws.refTarget)(value)
+};
+function documentRefsOf(document) {
+  return {
+    own: (logicalId) => (0, import_manifest_aws.qualifiedLogicalId)(document.stackPath, logicalId),
+    ref: (value) => (0, import_manifest_aws.documentRef)(document, value)
+  };
 }
 function stringField(value) {
   return typeof value === "string" ? value : null;
@@ -54,6 +64,7 @@ function asRecord(value) {
 }
 
 // src/sam.ts
+var import_manifest_aws2 = require("@suss/manifest-aws");
 var RESOLVER_ROOT_TYPES = ["Query", "Mutation", "Subscription"];
 var DATA_SOURCE_CATEGORIES = {
   Lambda: "lambda",
@@ -68,7 +79,7 @@ var DATA_SOURCE_CATEGORIES = {
   RelationalDatabases: "relational",
   None: "none"
 };
-function readServerlessGraphQLApis(resources) {
+function readServerlessGraphQLApis(resources, refs) {
   const out = {
     apis: [],
     resolvers: [],
@@ -79,18 +90,20 @@ function readServerlessGraphQLApis(resources) {
     if (resource?.Type !== "AWS::Serverless::GraphQLApi") {
       continue;
     }
-    readOne(logicalId, resource.Properties ?? {}, out);
+    readOne(refs.own(logicalId), resource.Properties ?? {}, out, refs);
   }
   return out;
 }
-function readOne(apiLogicalId, props, out) {
+function readOne(apiLogicalId, props, out, refs) {
   out.apis.push({
     logicalId: apiLogicalId,
     name: stringField(props.Name),
     schemaSource: readSchemaSource(props),
     authenticationType: readAuthType(props.Auth)
   });
-  out.dataSources.push(...readDataSources(apiLogicalId, props.DataSources));
+  out.dataSources.push(
+    ...readDataSources(apiLogicalId, props.DataSources, refs)
+  );
   out.functions.push(...readFunctions(apiLogicalId, props.Functions));
   out.resolvers.push(...readResolvers(apiLogicalId, props.Resolvers));
 }
@@ -112,7 +125,7 @@ function readAuthType(auth) {
   const record = asRecord(auth);
   return record === null ? null : stringField(record.Type);
 }
-function readDataSources(apiLogicalId, raw) {
+function readDataSources(apiLogicalId, raw, refs) {
   const dataSources = asRecord(raw);
   if (dataSources === null) {
     return [];
@@ -129,8 +142,9 @@ function readDataSources(apiLogicalId, raw) {
       out.push({
         logicalId: dataSourceId(apiLogicalId, name),
         apiLogicalId,
+        name,
         type,
-        lambdaFunctionLogicalId: type === "lambda" && def !== null ? resolveLogicalRef(def.FunctionArn) : null
+        lambdaFunctionLogicalId: type === "lambda" && def !== null ? refs.ref(def.FunctionArn) : null
       });
     }
   }
@@ -149,6 +163,7 @@ function readFunctions(apiLogicalId, raw) {
       apiLogicalId,
       name,
       dataSourceLogicalId: referencedDataSourceId(apiLogicalId, def.DataSource),
+      dataSourceWritten: null,
       codeUri: stringField(def.CodeUri),
       runtime: readRuntime(def.Runtime)
     });
@@ -182,6 +197,7 @@ function buildResolver(apiLogicalId, typeName, fieldName, def) {
     typeName,
     fieldName,
     dataSourceLogicalId: isPipeline ? null : referencedDataSourceId(apiLogicalId, def.DataSource),
+    dataSourceWritten: null,
     kind: isPipeline ? "PIPELINE" : "UNIT",
     pipelineFunctionLogicalIds: pipeline,
     codeUri: stringField(def.CodeUri),
@@ -194,7 +210,7 @@ function readPipeline(apiLogicalId, raw) {
   }
   const out = [];
   for (const entry of raw) {
-    const name = stringField(entry) ?? resolveLogicalRef(entry);
+    const name = stringField(entry) ?? (0, import_manifest_aws2.refTarget)(entry);
     if (name !== null) {
       out.push(functionId(apiLogicalId, name));
     }
@@ -217,15 +233,15 @@ function functionId(apiLogicalId, name) {
 }
 
 // src/cfn.ts
-function readAppSyncFromCfn(template) {
+function readAppSyncFromCfn(template, refs = OWN_DOCUMENT) {
   const resources = template.Resources ?? {};
   const raw = {
-    apis: collectApis(resources),
-    resolvers: collectResolvers(resources),
-    functions: collectFunctions(resources),
-    dataSources: collectDataSources(resources)
+    apis: collectApis(resources, refs),
+    resolvers: collectResolvers(resources, refs),
+    functions: collectFunctions(resources, refs),
+    dataSources: collectDataSources(resources, refs)
   };
-  const sam = readServerlessGraphQLApis(resources);
+  const sam = readServerlessGraphQLApis(resources, refs);
   return {
     apis: [...raw.apis, ...sam.apis],
     resolvers: [...raw.resolvers, ...sam.resolvers],
@@ -233,31 +249,63 @@ function readAppSyncFromCfn(template) {
     dataSources: [...raw.dataSources, ...sam.dataSources]
   };
 }
-function collectApis(resources) {
+function mergeConfigs(configs) {
+  const merged = {
+    apis: configs.flatMap((c) => c.apis),
+    resolvers: configs.flatMap((c) => c.resolvers),
+    functions: configs.flatMap((c) => c.functions),
+    dataSources: configs.flatMap((c) => c.dataSources)
+  };
+  return withDataSourcesByName(merged);
+}
+function withDataSourcesByName(config) {
+  const byId = new Set(config.dataSources.map((ds) => ds.logicalId));
+  const byName = /* @__PURE__ */ new Map();
+  for (const ds of config.dataSources) {
+    if (ds.name !== null) {
+      byName.set((0, import_manifest_aws3.apiScopedKey)(ds.apiLogicalId, ds.name), ds.logicalId);
+    }
+  }
+  const resolve = (entry) => {
+    const { dataSourceLogicalId, dataSourceWritten } = entry;
+    if (dataSourceLogicalId !== null && byId.has(dataSourceLogicalId)) {
+      return entry;
+    }
+    const named = dataSourceWritten === null ? void 0 : byName.get((0, import_manifest_aws3.apiScopedKey)(entry.apiLogicalId, dataSourceWritten));
+    return named === void 0 ? entry : { ...entry, dataSourceLogicalId: named };
+  };
+  return {
+    ...config,
+    resolvers: config.resolvers.map(resolve),
+    functions: config.functions.map(resolve)
+  };
+}
+function collectApis(resources, refs) {
   const apis = [];
-  const schemaByApi = indexSchemasByApi(resources);
+  const schemaByApi = indexSchemasByApi(resources, refs);
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource?.Type !== "AWS::AppSync::GraphQLApi") {
       continue;
     }
     const props = resource.Properties ?? {};
+    const id = refs.own(logicalId);
     apis.push({
-      logicalId,
+      logicalId: id,
       name: stringField(props.Name),
-      schemaSource: schemaByApi.get(logicalId) ?? { kind: "absent" },
+      schemaSource: schemaByApi.get(id) ?? { kind: "absent" },
       authenticationType: stringField(props.AuthenticationType)
     });
   }
   return apis;
 }
-function indexSchemasByApi(resources) {
+function indexSchemasByApi(resources, refs) {
   const out = /* @__PURE__ */ new Map();
   for (const resource of Object.values(resources)) {
     if (resource?.Type !== "AWS::AppSync::GraphQLSchema") {
       continue;
     }
     const props = resource.Properties ?? {};
-    const apiRef = resolveLogicalRef(props.ApiId);
+    const apiRef = refs.ref(props.ApiId);
     if (apiRef === null) {
       continue;
     }
@@ -277,7 +325,7 @@ function indexSchemasByApi(resources) {
   }
   return out;
 }
-function collectResolvers(resources) {
+function collectResolvers(resources, refs) {
   const out = [];
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource?.Type !== "AWS::AppSync::Resolver") {
@@ -290,20 +338,24 @@ function collectResolvers(resources) {
       continue;
     }
     out.push({
-      logicalId,
-      apiLogicalId: resolveLogicalRef(props.ApiId),
+      logicalId: refs.own(logicalId),
+      apiLogicalId: refs.ref(props.ApiId),
       typeName,
       fieldName,
-      dataSourceLogicalId: resolveLogicalRef(props.DataSourceName),
+      dataSourceLogicalId: refs.ref(props.DataSourceName),
+      dataSourceWritten: stringField(props.DataSourceName),
       kind: resolverKind(stringField(props.Kind)),
-      pipelineFunctionLogicalIds: pipelineFunctionIds(props.PipelineConfig),
+      pipelineFunctionLogicalIds: pipelineFunctionIds(
+        props.PipelineConfig,
+        refs
+      ),
       codeUri: null,
       runtime: null
     });
   }
   return out;
 }
-function pipelineFunctionIds(pipelineConfig) {
+function pipelineFunctionIds(pipelineConfig, refs) {
   const config = asRecord(pipelineConfig);
   if (config === null) {
     return [];
@@ -314,14 +366,14 @@ function pipelineFunctionIds(pipelineConfig) {
   }
   const out = [];
   for (const entry of functions) {
-    const ref = resolveLogicalRef(entry);
+    const ref = refs.ref(entry);
     if (ref !== null) {
       out.push(ref);
     }
   }
   return out;
 }
-function collectFunctions(resources) {
+function collectFunctions(resources, refs) {
   const out = [];
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource?.Type !== "AWS::AppSync::FunctionConfiguration") {
@@ -329,17 +381,18 @@ function collectFunctions(resources) {
     }
     const props = resource.Properties ?? {};
     out.push({
-      logicalId,
-      apiLogicalId: resolveLogicalRef(props.ApiId),
+      logicalId: refs.own(logicalId),
+      apiLogicalId: refs.ref(props.ApiId),
       name: stringField(props.Name),
-      dataSourceLogicalId: resolveLogicalRef(props.DataSourceName),
+      dataSourceLogicalId: refs.ref(props.DataSourceName),
+      dataSourceWritten: stringField(props.DataSourceName),
       codeUri: null,
       runtime: null
     });
   }
   return out;
 }
-function collectDataSources(resources) {
+function collectDataSources(resources, refs) {
   const out = [];
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource?.Type !== "AWS::AppSync::DataSource") {
@@ -348,10 +401,11 @@ function collectDataSources(resources) {
     const props = resource.Properties ?? {};
     const lambdaConfig = asRecord(props.LambdaConfig);
     out.push({
-      logicalId,
-      apiLogicalId: resolveLogicalRef(props.ApiId),
+      logicalId: refs.own(logicalId),
+      apiLogicalId: refs.ref(props.ApiId),
+      name: stringField(props.Name),
       type: dataSourceType(stringField(props.Type)),
-      lambdaFunctionLogicalId: lambdaConfig === null ? null : resolveLogicalRef(lambdaConfig.LambdaFunctionArn)
+      lambdaFunctionLogicalId: lambdaConfig === null ? null : refs.ref(lambdaConfig.LambdaFunctionArn)
     });
   }
   return out;
@@ -720,18 +774,31 @@ function buildTransitions(ownerKey, resolver, field) {
 
 // src/index.ts
 function appsyncToSummaries(template, options = {}) {
-  const config = readAppSyncFromCfn(template);
+  const config = mergeConfigs([readAppSyncFromCfn(template)]);
   const baseDir = options.baseDir ?? null;
-  const resolvedByApi = resolveSchemas(config, baseDir);
+  return summariesOf(
+    config,
+    new Map(config.apis.map((api) => [api.logicalId, baseDir])),
+    options.source
+  );
+}
+function summariesOf(config, baseDirByApi, source) {
+  const resolvedByApi = resolveSchemas(config, baseDirByApi);
   const schemasByApi = indexSchemas(resolvedByApi);
   return buildResolverSummaries(config, resolvedByApi, schemasByApi, {
-    ...options.source !== void 0 ? { source: options.source } : {}
+    ...source !== void 0 ? { source } : {}
   });
 }
-function resolveSchemas(config, baseDir) {
+function resolveSchemas(config, baseDirByApi) {
   const out = /* @__PURE__ */ new Map();
   for (const api of config.apis) {
-    out.set(api.logicalId, resolveSchemaSource(api.schemaSource, baseDir));
+    out.set(
+      api.logicalId,
+      resolveSchemaSource(
+        api.schemaSource,
+        baseDirByApi.get(api.logicalId) ?? null
+      )
+    );
   }
   return out;
 }
@@ -745,12 +812,34 @@ function indexSchemas(resolvedByApi) {
   return out;
 }
 function appsyncFileToSummaries(filePath, options = {}) {
-  const template = (0, import_manifest_aws2.loadCloudFormationTemplate)(filePath);
-  const root = options.projectRoot ?? (0, import_files.defaultProjectRoot)(filePath);
-  return appsyncToSummaries(template, {
-    source: options.source ?? (0, import_files.pathInProject)(filePath, root),
-    baseDir: options.baseDir ?? import_node_path2.default.dirname(filePath)
+  const tree = (0, import_manifest_aws4.loadTemplateTree)(filePath);
+  for (const stack of tree.unfollowed) {
+    const message = (0, import_manifest_aws4.unfollowedStackMessage)(stack);
+    if (options.warnings !== void 0) {
+      options.warnings.push(message);
+      continue;
+    }
+    process.stderr.write(`[suss] appsync: ${message}
+`);
+  }
+  const baseDirByApi = /* @__PURE__ */ new Map();
+  const configs = tree.documents.map((document) => {
+    const config = readAppSyncFromCfn(
+      document.template,
+      documentRefsOf(document)
+    );
+    const baseDir = document.stackPath.length === 0 && options.baseDir !== void 0 ? options.baseDir : import_node_path2.default.dirname(document.path);
+    for (const api of config.apis) {
+      baseDirByApi.set(api.logicalId, baseDir);
+    }
+    return config;
   });
+  const root = options.projectRoot ?? (0, import_files.defaultProjectRoot)(filePath);
+  return summariesOf(
+    mergeConfigs(configs),
+    baseDirByApi,
+    options.source ?? (0, import_files.pathInProject)(filePath, root)
+  );
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -5,9 +5,12 @@ import { BehavioralSummary } from '@suss/behavioral-ir';
  * 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.
+ * A value written with a dynamic intrinsic is left unresolved and
+ * reported. The reader never guesses it. A `!Ref` to a parameter the
+ * parent stack sets to a resource is read as that resource, which is how
+ * a nested stack's resolvers find the API their parent declares.
  */
+
 interface CfnTemplate {
     Resources?: Record<string, CfnResource | undefined>;
 }
@@ -38,6 +41,8 @@ interface AppsyncToSummariesOptions {
 interface AppsyncFileToSummariesOptions extends AppsyncToSummariesOptions {
     /** Absolute. The directory the template's path is measured from. */
     projectRoot?: string;
+    /** Collects each child template that could not be opened. Without it, each goes to stderr. */
+    warnings?: string[];
 }
 /**
  * Converts a template already in memory, such as a CDK
@@ -45,8 +50,11 @@ interface AppsyncFileToSummariesOptions extends AppsyncToSummariesOptions {
  */
 declare function appsyncToSummaries(template: CfnTemplate, options?: AppsyncToSummariesOptions): BehavioralSummary[];
 /**
- * Reads a CloudFormation or SAM template, in JSON or YAML, and converts
- * it. A relative schema path resolves against the template's directory.
+ * Reads a CloudFormation or SAM template, in JSON or YAML, and every
+ * template it embeds as a nested stack, and converts them as one API
+ * surface. A child's resolvers often belong to an API the root declares
+ * and passes down as a parameter. A relative schema path resolves
+ * against the directory of the template that declares it.
  */
 declare function appsyncFileToSummaries(filePath: string, options?: AppsyncFileToSummariesOptions): BehavioralSummary[];
 

package/dist/index.d.ts

@@ -5,9 +5,12 @@ import { BehavioralSummary } from '@suss/behavioral-ir';
  * 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.
+ * A value written with a dynamic intrinsic is left unresolved and
+ * reported. The reader never guesses it. A `!Ref` to a parameter the
+ * parent stack sets to a resource is read as that resource, which is how
+ * a nested stack's resolvers find the API their parent declares.
  */
+
 interface CfnTemplate {
     Resources?: Record<string, CfnResource | undefined>;
 }
@@ -38,6 +41,8 @@ interface AppsyncToSummariesOptions {
 interface AppsyncFileToSummariesOptions extends AppsyncToSummariesOptions {
     /** Absolute. The directory the template's path is measured from. */
     projectRoot?: string;
+    /** Collects each child template that could not be opened. Without it, each goes to stderr. */
+    warnings?: string[];
 }
 /**
  * Converts a template already in memory, such as a CDK
@@ -45,8 +50,11 @@ interface AppsyncFileToSummariesOptions extends AppsyncToSummariesOptions {
  */
 declare function appsyncToSummaries(template: CfnTemplate, options?: AppsyncToSummariesOptions): BehavioralSummary[];
 /**
- * Reads a CloudFormation or SAM template, in JSON or YAML, and converts
- * it. A relative schema path resolves against the template's directory.
+ * Reads a CloudFormation or SAM template, in JSON or YAML, and every
+ * template it embeds as a nested stack, and converts them as one API
+ * surface. A child's resolvers often belong to an API the root declares
+ * and passes down as a parameter. A relative schema path resolves
+ * against the directory of the template that declares it.
  */
 declare function appsyncFileToSummaries(filePath: string, options?: AppsyncFileToSummariesOptions): BehavioralSummary[];
 

package/dist/index.js

@@ -1,12 +1,26 @@
 // src/index.ts
 import path2 from "path";
 import { defaultProjectRoot, pathInProject } from "@suss/behavioral-ir/files";
-import { loadCloudFormationTemplate } from "@suss/manifest-aws";
+import { loadTemplateTree, unfollowedStackMessage } from "@suss/manifest-aws";
+
+// src/cfn.ts
+import { apiScopedKey } from "@suss/manifest-aws";
 
 // src/refs.ts
-import { refTarget } from "@suss/manifest-aws";
-function resolveLogicalRef(value) {
-  return refTarget(value);
+import {
+  documentRef,
+  qualifiedLogicalId,
+  refTarget
+} from "@suss/manifest-aws";
+var OWN_DOCUMENT = {
+  own: (logicalId) => logicalId,
+  ref: (value) => refTarget(value)
+};
+function documentRefsOf(document) {
+  return {
+    own: (logicalId) => qualifiedLogicalId(document.stackPath, logicalId),
+    ref: (value) => documentRef(document, value)
+  };
 }
 function stringField(value) {
   return typeof value === "string" ? value : null;
@@ -19,6 +33,7 @@ function asRecord(value) {
 }
 
 // src/sam.ts
+import { refTarget as refTarget2 } from "@suss/manifest-aws";
 var RESOLVER_ROOT_TYPES = ["Query", "Mutation", "Subscription"];
 var DATA_SOURCE_CATEGORIES = {
   Lambda: "lambda",
@@ -33,7 +48,7 @@ var DATA_SOURCE_CATEGORIES = {
   RelationalDatabases: "relational",
   None: "none"
 };
-function readServerlessGraphQLApis(resources) {
+function readServerlessGraphQLApis(resources, refs) {
   const out = {
     apis: [],
     resolvers: [],
@@ -44,18 +59,20 @@ function readServerlessGraphQLApis(resources) {
     if (resource?.Type !== "AWS::Serverless::GraphQLApi") {
       continue;
     }
-    readOne(logicalId, resource.Properties ?? {}, out);
+    readOne(refs.own(logicalId), resource.Properties ?? {}, out, refs);
   }
   return out;
 }
-function readOne(apiLogicalId, props, out) {
+function readOne(apiLogicalId, props, out, refs) {
   out.apis.push({
     logicalId: apiLogicalId,
     name: stringField(props.Name),
     schemaSource: readSchemaSource(props),
     authenticationType: readAuthType(props.Auth)
   });
-  out.dataSources.push(...readDataSources(apiLogicalId, props.DataSources));
+  out.dataSources.push(
+    ...readDataSources(apiLogicalId, props.DataSources, refs)
+  );
   out.functions.push(...readFunctions(apiLogicalId, props.Functions));
   out.resolvers.push(...readResolvers(apiLogicalId, props.Resolvers));
 }
@@ -77,7 +94,7 @@ function readAuthType(auth) {
   const record = asRecord(auth);
   return record === null ? null : stringField(record.Type);
 }
-function readDataSources(apiLogicalId, raw) {
+function readDataSources(apiLogicalId, raw, refs) {
   const dataSources = asRecord(raw);
   if (dataSources === null) {
     return [];
@@ -94,8 +111,9 @@ function readDataSources(apiLogicalId, raw) {
       out.push({
         logicalId: dataSourceId(apiLogicalId, name),
         apiLogicalId,
+        name,
         type,
-        lambdaFunctionLogicalId: type === "lambda" && def !== null ? resolveLogicalRef(def.FunctionArn) : null
+        lambdaFunctionLogicalId: type === "lambda" && def !== null ? refs.ref(def.FunctionArn) : null
       });
     }
   }
@@ -114,6 +132,7 @@ function readFunctions(apiLogicalId, raw) {
       apiLogicalId,
       name,
       dataSourceLogicalId: referencedDataSourceId(apiLogicalId, def.DataSource),
+      dataSourceWritten: null,
       codeUri: stringField(def.CodeUri),
       runtime: readRuntime(def.Runtime)
     });
@@ -147,6 +166,7 @@ function buildResolver(apiLogicalId, typeName, fieldName, def) {
     typeName,
     fieldName,
     dataSourceLogicalId: isPipeline ? null : referencedDataSourceId(apiLogicalId, def.DataSource),
+    dataSourceWritten: null,
     kind: isPipeline ? "PIPELINE" : "UNIT",
     pipelineFunctionLogicalIds: pipeline,
     codeUri: stringField(def.CodeUri),
@@ -159,7 +179,7 @@ function readPipeline(apiLogicalId, raw) {
   }
   const out = [];
   for (const entry of raw) {
-    const name = stringField(entry) ?? resolveLogicalRef(entry);
+    const name = stringField(entry) ?? refTarget2(entry);
     if (name !== null) {
       out.push(functionId(apiLogicalId, name));
     }
@@ -182,15 +202,15 @@ function functionId(apiLogicalId, name) {
 }
 
 // src/cfn.ts
-function readAppSyncFromCfn(template) {
+function readAppSyncFromCfn(template, refs = OWN_DOCUMENT) {
   const resources = template.Resources ?? {};
   const raw = {
-    apis: collectApis(resources),
-    resolvers: collectResolvers(resources),
-    functions: collectFunctions(resources),
-    dataSources: collectDataSources(resources)
+    apis: collectApis(resources, refs),
+    resolvers: collectResolvers(resources, refs),
+    functions: collectFunctions(resources, refs),
+    dataSources: collectDataSources(resources, refs)
   };
-  const sam = readServerlessGraphQLApis(resources);
+  const sam = readServerlessGraphQLApis(resources, refs);
   return {
     apis: [...raw.apis, ...sam.apis],
     resolvers: [...raw.resolvers, ...sam.resolvers],
@@ -198,31 +218,63 @@ function readAppSyncFromCfn(template) {
     dataSources: [...raw.dataSources, ...sam.dataSources]
   };
 }
-function collectApis(resources) {
+function mergeConfigs(configs) {
+  const merged = {
+    apis: configs.flatMap((c) => c.apis),
+    resolvers: configs.flatMap((c) => c.resolvers),
+    functions: configs.flatMap((c) => c.functions),
+    dataSources: configs.flatMap((c) => c.dataSources)
+  };
+  return withDataSourcesByName(merged);
+}
+function withDataSourcesByName(config) {
+  const byId = new Set(config.dataSources.map((ds) => ds.logicalId));
+  const byName = /* @__PURE__ */ new Map();
+  for (const ds of config.dataSources) {
+    if (ds.name !== null) {
+      byName.set(apiScopedKey(ds.apiLogicalId, ds.name), ds.logicalId);
+    }
+  }
+  const resolve = (entry) => {
+    const { dataSourceLogicalId, dataSourceWritten } = entry;
+    if (dataSourceLogicalId !== null && byId.has(dataSourceLogicalId)) {
+      return entry;
+    }
+    const named = dataSourceWritten === null ? void 0 : byName.get(apiScopedKey(entry.apiLogicalId, dataSourceWritten));
+    return named === void 0 ? entry : { ...entry, dataSourceLogicalId: named };
+  };
+  return {
+    ...config,
+    resolvers: config.resolvers.map(resolve),
+    functions: config.functions.map(resolve)
+  };
+}
+function collectApis(resources, refs) {
   const apis = [];
-  const schemaByApi = indexSchemasByApi(resources);
+  const schemaByApi = indexSchemasByApi(resources, refs);
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource?.Type !== "AWS::AppSync::GraphQLApi") {
       continue;
     }
     const props = resource.Properties ?? {};
+    const id = refs.own(logicalId);
     apis.push({
-      logicalId,
+      logicalId: id,
       name: stringField(props.Name),
-      schemaSource: schemaByApi.get(logicalId) ?? { kind: "absent" },
+      schemaSource: schemaByApi.get(id) ?? { kind: "absent" },
       authenticationType: stringField(props.AuthenticationType)
     });
   }
   return apis;
 }
-function indexSchemasByApi(resources) {
+function indexSchemasByApi(resources, refs) {
   const out = /* @__PURE__ */ new Map();
   for (const resource of Object.values(resources)) {
     if (resource?.Type !== "AWS::AppSync::GraphQLSchema") {
       continue;
     }
     const props = resource.Properties ?? {};
-    const apiRef = resolveLogicalRef(props.ApiId);
+    const apiRef = refs.ref(props.ApiId);
     if (apiRef === null) {
       continue;
     }
@@ -242,7 +294,7 @@ function indexSchemasByApi(resources) {
   }
   return out;
 }
-function collectResolvers(resources) {
+function collectResolvers(resources, refs) {
   const out = [];
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource?.Type !== "AWS::AppSync::Resolver") {
@@ -255,20 +307,24 @@ function collectResolvers(resources) {
       continue;
     }
     out.push({
-      logicalId,
-      apiLogicalId: resolveLogicalRef(props.ApiId),
+      logicalId: refs.own(logicalId),
+      apiLogicalId: refs.ref(props.ApiId),
       typeName,
       fieldName,
-      dataSourceLogicalId: resolveLogicalRef(props.DataSourceName),
+      dataSourceLogicalId: refs.ref(props.DataSourceName),
+      dataSourceWritten: stringField(props.DataSourceName),
       kind: resolverKind(stringField(props.Kind)),
-      pipelineFunctionLogicalIds: pipelineFunctionIds(props.PipelineConfig),
+      pipelineFunctionLogicalIds: pipelineFunctionIds(
+        props.PipelineConfig,
+        refs
+      ),
       codeUri: null,
       runtime: null
     });
   }
   return out;
 }
-function pipelineFunctionIds(pipelineConfig) {
+function pipelineFunctionIds(pipelineConfig, refs) {
   const config = asRecord(pipelineConfig);
   if (config === null) {
     return [];
@@ -279,14 +335,14 @@ function pipelineFunctionIds(pipelineConfig) {
   }
   const out = [];
   for (const entry of functions) {
-    const ref = resolveLogicalRef(entry);
+    const ref = refs.ref(entry);
     if (ref !== null) {
       out.push(ref);
     }
   }
   return out;
 }
-function collectFunctions(resources) {
+function collectFunctions(resources, refs) {
   const out = [];
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource?.Type !== "AWS::AppSync::FunctionConfiguration") {
@@ -294,17 +350,18 @@ function collectFunctions(resources) {
     }
     const props = resource.Properties ?? {};
     out.push({
-      logicalId,
-      apiLogicalId: resolveLogicalRef(props.ApiId),
+      logicalId: refs.own(logicalId),
+      apiLogicalId: refs.ref(props.ApiId),
       name: stringField(props.Name),
-      dataSourceLogicalId: resolveLogicalRef(props.DataSourceName),
+      dataSourceLogicalId: refs.ref(props.DataSourceName),
+      dataSourceWritten: stringField(props.DataSourceName),
       codeUri: null,
       runtime: null
     });
   }
   return out;
 }
-function collectDataSources(resources) {
+function collectDataSources(resources, refs) {
   const out = [];
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource?.Type !== "AWS::AppSync::DataSource") {
@@ -313,10 +370,11 @@ function collectDataSources(resources) {
     const props = resource.Properties ?? {};
     const lambdaConfig = asRecord(props.LambdaConfig);
     out.push({
-      logicalId,
-      apiLogicalId: resolveLogicalRef(props.ApiId),
+      logicalId: refs.own(logicalId),
+      apiLogicalId: refs.ref(props.ApiId),
+      name: stringField(props.Name),
       type: dataSourceType(stringField(props.Type)),
-      lambdaFunctionLogicalId: lambdaConfig === null ? null : resolveLogicalRef(lambdaConfig.LambdaFunctionArn)
+      lambdaFunctionLogicalId: lambdaConfig === null ? null : refs.ref(lambdaConfig.LambdaFunctionArn)
     });
   }
   return out;
@@ -693,18 +751,31 @@ function buildTransitions(ownerKey, resolver, field) {
 
 // src/index.ts
 function appsyncToSummaries(template, options = {}) {
-  const config = readAppSyncFromCfn(template);
+  const config = mergeConfigs([readAppSyncFromCfn(template)]);
   const baseDir = options.baseDir ?? null;
-  const resolvedByApi = resolveSchemas(config, baseDir);
+  return summariesOf(
+    config,
+    new Map(config.apis.map((api) => [api.logicalId, baseDir])),
+    options.source
+  );
+}
+function summariesOf(config, baseDirByApi, source) {
+  const resolvedByApi = resolveSchemas(config, baseDirByApi);
   const schemasByApi = indexSchemas(resolvedByApi);
   return buildResolverSummaries(config, resolvedByApi, schemasByApi, {
-    ...options.source !== void 0 ? { source: options.source } : {}
+    ...source !== void 0 ? { source } : {}
   });
 }
-function resolveSchemas(config, baseDir) {
+function resolveSchemas(config, baseDirByApi) {
   const out = /* @__PURE__ */ new Map();
   for (const api of config.apis) {
-    out.set(api.logicalId, resolveSchemaSource(api.schemaSource, baseDir));
+    out.set(
+      api.logicalId,
+      resolveSchemaSource(
+        api.schemaSource,
+        baseDirByApi.get(api.logicalId) ?? null
+      )
+    );
   }
   return out;
 }
@@ -718,12 +789,34 @@ function indexSchemas(resolvedByApi) {
   return out;
 }
 function appsyncFileToSummaries(filePath, options = {}) {
-  const template = loadCloudFormationTemplate(filePath);
-  const root = options.projectRoot ?? defaultProjectRoot(filePath);
-  return appsyncToSummaries(template, {
-    source: options.source ?? pathInProject(filePath, root),
-    baseDir: options.baseDir ?? path2.dirname(filePath)
+  const tree = loadTemplateTree(filePath);
+  for (const stack of tree.unfollowed) {
+    const message = unfollowedStackMessage(stack);
+    if (options.warnings !== void 0) {
+      options.warnings.push(message);
+      continue;
+    }
+    process.stderr.write(`[suss] appsync: ${message}
+`);
+  }
+  const baseDirByApi = /* @__PURE__ */ new Map();
+  const configs = tree.documents.map((document) => {
+    const config = readAppSyncFromCfn(
+      document.template,
+      documentRefsOf(document)
+    );
+    const baseDir = document.stackPath.length === 0 && options.baseDir !== void 0 ? options.baseDir : path2.dirname(document.path);
+    for (const api of config.apis) {
+      baseDirByApi.set(api.logicalId, baseDir);
+    }
+    return config;
   });
+  const root = options.projectRoot ?? defaultProjectRoot(filePath);
+  return summariesOf(
+    mergeConfigs(configs),
+    baseDirByApi,
+    options.source ?? pathInProject(filePath, root)
+  );
 }
 export {
   appsyncFileToSummaries,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-appsync",
-  "version": "0.36.0",
+  "version": "0.37.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": [
@@ -48,9 +48,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.36.0",
-    "@suss/contract-graphql": "0.36.0",
-    "@suss/manifest-aws": "0.36.0",
+    "@suss/behavioral-ir": "0.37.0",
+    "@suss/contract-graphql": "0.37.0",
+    "@suss/manifest-aws": "0.37.0",
     "graphql": "^16.8.0"
   },
   "devDependencies": {