@suss/manifest-aws 0.3.2 → 0.4.0

package/dist/index.cjs

@@ -39,7 +39,13 @@ __export(index_exports, {
   qualifiedLogicalId: () => qualifiedLogicalId,
   readAppSyncResolvers: () => readAppSyncResolvers,
   readServerlessFunctions: () => readServerlessFunctions,
+  reduceEventPattern: () => reduceEventPattern,
   refTarget: () => refTarget,
+  resolveBucketChannel: () => resolveBucketChannel,
+  resolveEventBusToken: () => resolveEventBusToken,
+  resolveQueueChannel: () => resolveQueueChannel,
+  resolveResourceChannel: () => resolveResourceChannel,
+  resolveTopicChannel: () => resolveTopicChannel,
   resourcesWithGlobals: () => resourcesWithGlobals,
   unfollowedStackMessage: () => unfollowedStackMessage
 });
@@ -63,7 +69,11 @@ var getAttParts = (value) => {
     return value.map(String);
   }
   const text = String(value);
-  return text.includes(".") ? text.split(".") : [text];
+  const dot = text.indexOf(".");
+  if (dot === -1) {
+    return [text];
+  }
+  return [text.slice(0, dot), text.slice(dot + 1)];
 };
 var CLOUDFORMATION_YAML_TAGS = [
   ...everyNodeKind("!Ref", (value) => ({ Ref: value })),
@@ -115,8 +125,7 @@ function refTarget(value) {
     return getAtt[0];
   }
   if (typeof getAtt === "string") {
-    const dot = getAtt.indexOf(".");
-    return dot === -1 ? getAtt : getAtt.slice(0, dot);
+    return getAttParts(getAtt)[0] ?? null;
   }
   return null;
 }
@@ -280,6 +289,102 @@ function stringOf(value) {
   return typeof value === "string" ? value : null;
 }
 
+// src/arn.ts
+function resolveResourceChannel(value, service) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "string") {
+    const resource = resolveArnResource(value, service);
+    return resource ?? value;
+  }
+  return refTarget(value);
+}
+function resolveArnResource(value, service) {
+  const parts = value.split(":");
+  if (parts[0] !== "arn" || parts[2] !== service) {
+    return null;
+  }
+  const region = parts[3];
+  const account = parts[4];
+  const resource = parts.slice(5).join(":");
+  if (service === "s3") {
+    if (region !== "" || account !== "" || resource === "") {
+      return null;
+    }
+    const slash = resource.indexOf("/");
+    const bucket = slash === -1 ? resource : resource.slice(0, slash);
+    return bucket === "" ? null : bucket;
+  }
+  if (!region || !account || resource === "") {
+    return null;
+  }
+  return resource;
+}
+function resolveQueueChannel(value) {
+  return resolveResourceChannel(value, "sqs");
+}
+function resolveTopicChannel(value) {
+  return resolveResourceChannel(value, "sns");
+}
+function resolveBucketChannel(value) {
+  return resolveResourceChannel(value, "s3");
+}
+
+// src/eventPattern.ts
+function reduceEventPattern(pattern) {
+  if (pattern === null || typeof pattern !== "object") {
+    return {
+      kind: "unresolvable",
+      reason: "rule declares no EventPattern"
+    };
+  }
+  const detailType = pattern["detail-type"];
+  if (detailType === void 0) {
+    return {
+      kind: "unresolvable",
+      reason: "EventPattern has no detail-type; v0 reduces routing to exact detail-type match only"
+    };
+  }
+  if (!Array.isArray(detailType)) {
+    return {
+      kind: "unresolvable",
+      reason: "detail-type is not a plain array of string literals"
+    };
+  }
+  const detailTypes = [];
+  for (const entry of detailType) {
+    if (typeof entry !== "string") {
+      return {
+        kind: "unresolvable",
+        reason: "detail-type contains a content filter (prefix / anything-but / etc.); pattern subsumption is out of v0 scope"
+      };
+    }
+    detailTypes.push(entry);
+  }
+  if (detailTypes.length === 0) {
+    return { kind: "unresolvable", reason: "detail-type array is empty" };
+  }
+  return { kind: "exact", detailTypes };
+}
+function resolveEventBusToken(value) {
+  if (value === null || value === void 0) {
+    return "default";
+  }
+  if (typeof value === "object") {
+    const logicalId = refTarget(value);
+    return logicalId ?? "default";
+  }
+  if (typeof value === "string") {
+    const arnMatch = value.match(/:event-bus\/(.+)$/);
+    if (arnMatch !== null) {
+      return arnMatch[1];
+    }
+    return value;
+  }
+  return "default";
+}
+
 // src/globals.ts
 var GLOBALS_SECTION_TYPES = {
   Api: "AWS::Serverless::Api",
@@ -594,7 +699,13 @@ function readServerlessFunctions(template) {
   qualifiedLogicalId,
   readAppSyncResolvers,
   readServerlessFunctions,
+  reduceEventPattern,
   refTarget,
+  resolveBucketChannel,
+  resolveEventBusToken,
+  resolveQueueChannel,
+  resolveResourceChannel,
+  resolveTopicChannel,
   resourcesWithGlobals,
   unfollowedStackMessage
 });

package/dist/index.d.cts

@@ -1,5 +1,15 @@
 import YAML from 'yaml';
 
+/**
+ * templateLoader.ts parses a CloudFormation or SAM template file into a
+ * plain object, resolving the shorthand YAML tags CFN uses for intrinsics.
+ *
+ * This is the one place that turns a template on disk into data. The
+ * summary-generation paths and the code-side handler pairing both read
+ * through it, so the YAML and JSON parsing, along with the handling of
+ * intrinsic tags, lives here instead of being repeated per consumer.
+ */
+
 interface CloudFormationResource {
     Type?: string;
     Properties?: Record<string, unknown>;
@@ -8,7 +18,7 @@ interface CloudFormationResource {
 interface CloudFormationTemplate {
     /**
      * SAM `Globals` block. Section keys (`Function`, `Api`, `HttpApi`)
-     * hold defaults that individual resources inherit unless they
+     * contain defaults that individual resources inherit unless they
      * override the property themselves.
      */
     Globals?: Record<string, Record<string, unknown>>;
@@ -16,29 +26,44 @@ interface CloudFormationTemplate {
 }
 declare const CLOUDFORMATION_YAML_TAGS: YAML.CollectionTag[];
 /**
- * Load a CloudFormation / SAM template from disk. Format is detected by
- * extension; `.json` parses as JSON, everything else (including
- * `.yaml` / `.yml` / `.template`) goes through the YAML parser with the
+ * Load a CloudFormation or SAM template from disk. The format comes from
+ * the extension: `.json` parses as JSON, and everything else (including
+ * `.yaml`, `.yml`, and `.template`) goes through the YAML parser with the
  * intrinsic tags registered.
  *
- * Throws when the file is missing or the parsed value isn't an object —
- * a malformed manifest is a load-time error, not a silent empty result.
+ * Throws when the file is missing or the parsed value isn't an object. A
+ * malformed manifest is a load-time error rather than an empty result.
  */
 declare function loadCloudFormationTemplate(templatePath: string): CloudFormationTemplate;
 /**
- * CloudFormation references show up in four shapes after parsing:
+ * CloudFormation references come out of the parser in four forms:
  *   - { Ref: "LogicalId" }
  *   - { "Fn::GetAtt": ["LogicalId", "Attr"] }
  *   - { "Fn::GetAtt": "LogicalId.Attr" }, the full-form spelling of the
  *     `!GetAtt` short form, which templates written by hand still use
  *   - the bare logical id when the parser doesn't recognise the YAML tag
  *
- * Every CloudFormation property that names another resource accepts all
- * of them, so anything reading such a property should come through here
- * rather than matching one shape.
+ * Every CloudFormation property that points at another resource accepts
+ * all four, so anything reading such a property should go through here
+ * instead of matching a single form.
  */
 declare function refTarget(value: unknown): string | null;
 
+/**
+ * appsyncResolvers.ts works out which GraphQL field each Lambda serves.
+ *
+ * AppSync does not wire a field to a handler in code. The template does it,
+ * over three hops: a resolver points at a pipeline function, the function
+ * points at a data source, and the data source points at a Lambda. Both ways
+ * of writing that are covered, the raw AWS::AppSync::* resources and the SAM
+ * AWS::Serverless::GraphQLApi shorthand whose DataSources, Functions, and
+ * Resolvers blocks the transform expands into those same resources.
+ *
+ * Like the rest of this package, this reports only what the template says.
+ * Whether a field has an implementation, and whether that implementation
+ * matches the schema, is for a reader above to decide.
+ */
+
 /** One GraphQL field and the Lambdas behind it. */
 interface AppSyncResolverBinding {
     typeName: string;
@@ -46,10 +71,10 @@ interface AppSyncResolverBinding {
     /**
      * Every Lambda a request for this field runs, in pipeline order.
      * Usually one. A pipeline can chain several, and nothing in the
-     * template says which of them is the one that produces the value:
-     * the first is as often an auth step as it is the resolver, and the
-     * last is as often a formatter. So all of them are reported, and a
-     * reader that needs to pick says so itself.
+     * template says which of them produces the value: the first is as
+     * often an auth step as it is the resolver, and the last is as often
+     * a formatter. So all of them are reported, and a reader that needs
+     * to pick one decides for itself.
      *
      * Empty when the field is served by something other than a Lambda.
      */
@@ -57,21 +82,125 @@ interface AppSyncResolverBinding {
 }
 declare function readAppSyncResolvers(template: CloudFormationTemplate): AppSyncResolverBinding[];
 
+/**
+ * arn.ts resolves the references AWS manifests use to point at a queue, a
+ * topic, or a bucket, down to the channel string suss keys the boundary on.
+ *
+ * Every manifest language that targets AWS writes a reference one of three
+ * ways: as a CFN intrinsic (`!Ref X`, `!GetAtt X.Arn`), as a plain ARN
+ * string, or as a bare name. The CloudFormation reader and the Serverless
+ * Framework reader both resolve them here, so a queue written two different
+ * ways in two manifest languages still ends up on one channel.
+ */
+/**
+ * Resolve a reference (`!Ref X`, `!GetAtt X.Arn`, plain string ARN) to
+ * the referenced resource's channel string. `service` is the ARN
+ * segment a plain string is checked against (`"sqs"`, `"sns"`, `"s3"`),
+ * so a queue ARN, a topic ARN, and a bucket ARN all resolve through the
+ * same code.
+ *
+ * Returns null when the reference is dynamic (a parameter, an import,
+ * or an Fn::Join that points at nothing this template declares); those
+ * need cross-stack resolution that's out of scope for v0.
+ */
+declare function resolveResourceChannel(value: unknown, service: string): string | null;
+/**
+ * Resolve a Queue reference (`!Ref X`, `!GetAtt X.Arn`, plain string
+ * ARN) to the queue's channel string.
+ */
+declare function resolveQueueChannel(value: unknown): string | null;
+/**
+ * Resolve a Topic reference (`!Ref X`, `!GetAtt X.Arn`, plain string
+ * ARN) to the topic's channel string.
+ */
+declare function resolveTopicChannel(value: unknown): string | null;
+/**
+ * Resolve a Bucket reference (`!Ref X`, `!GetAtt X.Arn`, plain string
+ * ARN) to the bucket's channel string.
+ */
+declare function resolveBucketChannel(value: unknown): string | null;
+
+/**
+ * eventPattern.ts reads what an EventBridge rule says about the events it
+ * matches, and which bus those events arrive on.
+ *
+ * A rule's EventPattern and its EventBusName are written the same way in a
+ * CloudFormation template and in a serverless.yml eventBridge event, so
+ * both readers reduce them here.
+ */
+/**
+ * How far a rule's EventPattern reduced: either to the exact
+ * detail-types it lists, or not at all, along with a reason someone can
+ * read.
+ */
+type PatternReduction = {
+    kind: "exact";
+    detailTypes: string[];
+} | {
+    kind: "unresolvable";
+    reason: string;
+};
+/**
+ * Reduce a rule's EventPattern to the exact set of DetailTypes it
+ * matches. v0 handles only a literal `detail-type` array; anything else
+ * (absent detail-type, content-filter objects, empty array) is
+ * unresolvable, surfaced by the checker, never silently dropped.
+ */
+declare function reduceEventPattern(pattern: unknown): PatternReduction;
+/**
+ * Resolve a rule's EventBusName to the channel's bus token: the CFN
+ * logical id when it's a Ref/GetAtt, the name segment of an event-bus
+ * ARN, the literal string otherwise, or "default" when it's left out
+ * (the EventBridge default event bus).
+ */
+declare function resolveEventBusToken(value: unknown): string;
+
+/**
+ * globals.ts folds the SAM `Globals` section into the resources that
+ * inherit from it, so every reader sees one set of properties per resource
+ * and none of them has to know that `Globals` exists.
+ *
+ * SAM applies a section's properties to each resource of the matching type,
+ * and the resource's own value wins where both declare one, per
+ * https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification-template-anatomy-globals.html
+ *
+ * That page has the combining rules too. A map is merged key by key, a list
+ * becomes the section's entries followed by the resource's, and anything
+ * else is replaced outright. Merging keys is what makes a function that sets
+ * one environment variable of its own still get the section's others.
+ */
+
 /**
  * The template's resources with each `Globals` section already applied
- * to the resources it covers. A resource of a type no section names, or
- * a template with no `Globals`, comes back untouched.
+ * to the resources it covers. A resource whose type no section covers,
+ * or a template with no `Globals`, comes back untouched.
  */
 declare function resourcesWithGlobals(template: CloudFormationTemplate): Record<string, CloudFormationResource>;
 /**
  * Per function logical id, the environment variables the `Function`
  * section supplies that the function does not declare for itself. A
  * consumer that treats a function's environment as its own contract
- * needs the distinction: a name every function in the document receives
- * says something about the document, not about any one function.
+ * needs the difference, because a variable every function in the
+ * document receives tells you about the document, not about one
+ * function.
  */
 declare function inheritedEnvVars(template: CloudFormationTemplate): Record<string, string[]>;
 
+/**
+ * nestedStacks.ts reads a template and every child template it embeds, as a
+ * list of documents.
+ *
+ * A stack resource points at another template, and CloudFormation deploys that
+ * template's resources alongside the parent's. Each document keeps its own
+ * namespace, its own SAM `Globals` section, and its own directory, so the tree
+ * stays a list of documents. Merging them would apply one document's defaults
+ * to another's resources, and let two logical ids spelled the same way collide.
+ *
+ * A child's reference to one of its own parameters is not followed to what the
+ * parent bound, and a `Fn::GetAtt` on a stack resource is not followed to the
+ * child's output. Both point at nothing, like any reference we can't resolve.
+ */
+
 /**
  * How deep the reader follows children. CloudFormation itself allows
  * deeper nesting; a template chain this long in a repository is far
@@ -79,7 +208,7 @@ declare function inheritedEnvVars(template: CloudFormationTemplate): Record<stri
  * rather than applied silently.
  */
 declare const MAX_STACK_DEPTH = 10;
-/** One template file, and where it sits in the tree that reached it. */
+/** One template file, and where it lives in the tree that reached it. */
 interface TemplateDocument {
     /** Absolute path of the file this document was read from. */
     path: string;
@@ -92,8 +221,8 @@ interface TemplateDocument {
 }
 /**
  * Why a child template was not read. Every value is a limit on what the
- * reader could reach, so a consumer should report it as reading that
- * stopped rather than treat the child as a template holding nothing.
+ * reader could reach, so a consumer should report it as a read that
+ * stopped rather than treat the child as an empty template.
  */
 type UnfollowedReason = "remoteUrl" | "notALiteralPath" | "fileMissing" | "unreadable" | "cycle" | "depthLimit";
 /** A child template the reader could not open, and what stopped it. */
@@ -105,7 +234,7 @@ interface UnfollowedStack {
     /** The template location as the document writes it, when it is a string. */
     templateUrl: string | null;
     reason: UnfollowedReason;
-    /** One phrase naming what stopped the read, for a message to a person. */
+    /** One phrase saying what stopped the read, for a message to a person. */
     detail: string;
 }
 interface TemplateTree {
@@ -125,14 +254,27 @@ interface TemplateTree {
 declare function loadTemplateTree(rootPath: string): TemplateTree;
 /**
  * A logical id qualified by the stack path that reaches it, so two
- * documents that both declare `HandlerFunction` name two different
+ * documents that both declare `HandlerFunction` refer to two different
  * deployed things. A resource in the root document keeps its bare id,
  * which is also what CloudFormation shows for it.
  */
 declare function qualifiedLogicalId(stackPath: string[], logicalId: string): string;
-/** A line naming one child the reader could not open, and why. */
+/** A line saying which child the reader could not open, and why. */
 declare function unfollowedStackMessage(stack: UnfollowedStack): string;
 
+/**
+ * serverlessFunctions.ts reads AWS::Serverless::Function resources into a
+ * code-facing view: which module and export each function points at, and
+ * which route and non-route Events it declares.
+ *
+ * The summary-generation paths expand SAM Events into API Gateway route
+ * summaries. This reader covers the other question the code-side pairing
+ * needs: given the template, where is each handler's implementation, and
+ * what routes is it bound to? The manifest semantics (how a Handler string
+ * is laid out, how CodeUri is inherited from Globals, Api versus HttpApi
+ * Events) stay here rather than being reconstructed in a framework pack.
+ */
+
 /** A route-bearing SAM Event (`Type: Api` or `Type: HttpApi`). */
 interface ServerlessHttpRoute {
     /** Key of the event in the function's `Events` map. */
@@ -147,9 +289,10 @@ interface ServerlessHttpRoute {
     apiId: string | null;
 }
 /**
- * A recognized SAM Event that isn't an HTTP route — SQS / Schedule /
- * SNS / S3 / etc. Surfaced (not dropped) so the code side can account
- * for handlers it recognizes but deliberately doesn't extract as HTTP.
+ * A recognized SAM Event that isn't an HTTP route (SQS, Schedule, SNS,
+ * S3, and so on). These are reported rather than dropped, so the code
+ * side can account for handlers it recognizes but deliberately doesn't
+ * extract as HTTP.
  */
 interface ServerlessNonHttpEvent {
     eventId: string;
@@ -163,7 +306,7 @@ interface ServerlessFunctionInfo {
     handler: string;
     /** Module-path portion of the handler (everything before the final dot). */
     modulePath: string;
-    /** Exported symbol the handler names (everything after the final dot). */
+    /** Exported symbol the handler points at (everything after the final dot). */
     exportName: string;
     /**
      * CodeUri base directory the handler resolves against: the function's
@@ -181,16 +324,16 @@ interface ParsedHandler {
  * Split a SAM Handler string into its module path and exported symbol.
  * The final dot separates them: `"src/handlers/confirmToken.handler"` →
  * `{ modulePath: "src/handlers/confirmToken", exportName: "handler" }`.
- * Returns null when there's no dot (nothing names an export to bind to).
+ * Returns null when there's no dot, since there's no export to bind to.
  */
 declare function parseHandler(handler: string): ParsedHandler | null;
 /**
  * Read every AWS::Serverless::Function resource in the template into a
  * code-facing `ServerlessFunctionInfo`. Functions without a parseable
- * Handler are skipped (there's no export to bind). Functions with no
- * Events still appear (empty route + non-route lists) so a consumer can
- * see them.
+ * Handler are skipped, since there's no export to bind. Functions with
+ * no Events still appear, with both event lists empty, so a consumer
+ * can see them.
  */
 declare function readServerlessFunctions(template: CloudFormationTemplate): ServerlessFunctionInfo[];
 
-export { type AppSyncResolverBinding, CLOUDFORMATION_YAML_TAGS, type CloudFormationResource, type CloudFormationTemplate, MAX_STACK_DEPTH, type ParsedHandler, type ServerlessFunctionInfo, type ServerlessHttpRoute, type ServerlessNonHttpEvent, type TemplateDocument, type TemplateTree, type UnfollowedReason, type UnfollowedStack, inheritedEnvVars, loadCloudFormationTemplate, loadTemplateTree, parseHandler, qualifiedLogicalId, readAppSyncResolvers, readServerlessFunctions, refTarget, resourcesWithGlobals, unfollowedStackMessage };
+export { type AppSyncResolverBinding, CLOUDFORMATION_YAML_TAGS, type CloudFormationResource, type CloudFormationTemplate, MAX_STACK_DEPTH, type ParsedHandler, type PatternReduction, type ServerlessFunctionInfo, type ServerlessHttpRoute, type ServerlessNonHttpEvent, type TemplateDocument, type TemplateTree, type UnfollowedReason, type UnfollowedStack, inheritedEnvVars, loadCloudFormationTemplate, loadTemplateTree, parseHandler, qualifiedLogicalId, readAppSyncResolvers, readServerlessFunctions, reduceEventPattern, refTarget, resolveBucketChannel, resolveEventBusToken, resolveQueueChannel, resolveResourceChannel, resolveTopicChannel, resourcesWithGlobals, unfollowedStackMessage };

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 import YAML from 'yaml';
 
+/**
+ * templateLoader.ts parses a CloudFormation or SAM template file into a
+ * plain object, resolving the shorthand YAML tags CFN uses for intrinsics.
+ *
+ * This is the one place that turns a template on disk into data. The
+ * summary-generation paths and the code-side handler pairing both read
+ * through it, so the YAML and JSON parsing, along with the handling of
+ * intrinsic tags, lives here instead of being repeated per consumer.
+ */
+
 interface CloudFormationResource {
     Type?: string;
     Properties?: Record<string, unknown>;
@@ -8,7 +18,7 @@ interface CloudFormationResource {
 interface CloudFormationTemplate {
     /**
      * SAM `Globals` block. Section keys (`Function`, `Api`, `HttpApi`)
-     * hold defaults that individual resources inherit unless they
+     * contain defaults that individual resources inherit unless they
      * override the property themselves.
      */
     Globals?: Record<string, Record<string, unknown>>;
@@ -16,29 +26,44 @@ interface CloudFormationTemplate {
 }
 declare const CLOUDFORMATION_YAML_TAGS: YAML.CollectionTag[];
 /**
- * Load a CloudFormation / SAM template from disk. Format is detected by
- * extension; `.json` parses as JSON, everything else (including
- * `.yaml` / `.yml` / `.template`) goes through the YAML parser with the
+ * Load a CloudFormation or SAM template from disk. The format comes from
+ * the extension: `.json` parses as JSON, and everything else (including
+ * `.yaml`, `.yml`, and `.template`) goes through the YAML parser with the
  * intrinsic tags registered.
  *
- * Throws when the file is missing or the parsed value isn't an object —
- * a malformed manifest is a load-time error, not a silent empty result.
+ * Throws when the file is missing or the parsed value isn't an object. A
+ * malformed manifest is a load-time error rather than an empty result.
  */
 declare function loadCloudFormationTemplate(templatePath: string): CloudFormationTemplate;
 /**
- * CloudFormation references show up in four shapes after parsing:
+ * CloudFormation references come out of the parser in four forms:
  *   - { Ref: "LogicalId" }
  *   - { "Fn::GetAtt": ["LogicalId", "Attr"] }
  *   - { "Fn::GetAtt": "LogicalId.Attr" }, the full-form spelling of the
  *     `!GetAtt` short form, which templates written by hand still use
  *   - the bare logical id when the parser doesn't recognise the YAML tag
  *
- * Every CloudFormation property that names another resource accepts all
- * of them, so anything reading such a property should come through here
- * rather than matching one shape.
+ * Every CloudFormation property that points at another resource accepts
+ * all four, so anything reading such a property should go through here
+ * instead of matching a single form.
  */
 declare function refTarget(value: unknown): string | null;
 
+/**
+ * appsyncResolvers.ts works out which GraphQL field each Lambda serves.
+ *
+ * AppSync does not wire a field to a handler in code. The template does it,
+ * over three hops: a resolver points at a pipeline function, the function
+ * points at a data source, and the data source points at a Lambda. Both ways
+ * of writing that are covered, the raw AWS::AppSync::* resources and the SAM
+ * AWS::Serverless::GraphQLApi shorthand whose DataSources, Functions, and
+ * Resolvers blocks the transform expands into those same resources.
+ *
+ * Like the rest of this package, this reports only what the template says.
+ * Whether a field has an implementation, and whether that implementation
+ * matches the schema, is for a reader above to decide.
+ */
+
 /** One GraphQL field and the Lambdas behind it. */
 interface AppSyncResolverBinding {
     typeName: string;
@@ -46,10 +71,10 @@ interface AppSyncResolverBinding {
     /**
      * Every Lambda a request for this field runs, in pipeline order.
      * Usually one. A pipeline can chain several, and nothing in the
-     * template says which of them is the one that produces the value:
-     * the first is as often an auth step as it is the resolver, and the
-     * last is as often a formatter. So all of them are reported, and a
-     * reader that needs to pick says so itself.
+     * template says which of them produces the value: the first is as
+     * often an auth step as it is the resolver, and the last is as often
+     * a formatter. So all of them are reported, and a reader that needs
+     * to pick one decides for itself.
      *
      * Empty when the field is served by something other than a Lambda.
      */
@@ -57,21 +82,125 @@ interface AppSyncResolverBinding {
 }
 declare function readAppSyncResolvers(template: CloudFormationTemplate): AppSyncResolverBinding[];
 
+/**
+ * arn.ts resolves the references AWS manifests use to point at a queue, a
+ * topic, or a bucket, down to the channel string suss keys the boundary on.
+ *
+ * Every manifest language that targets AWS writes a reference one of three
+ * ways: as a CFN intrinsic (`!Ref X`, `!GetAtt X.Arn`), as a plain ARN
+ * string, or as a bare name. The CloudFormation reader and the Serverless
+ * Framework reader both resolve them here, so a queue written two different
+ * ways in two manifest languages still ends up on one channel.
+ */
+/**
+ * Resolve a reference (`!Ref X`, `!GetAtt X.Arn`, plain string ARN) to
+ * the referenced resource's channel string. `service` is the ARN
+ * segment a plain string is checked against (`"sqs"`, `"sns"`, `"s3"`),
+ * so a queue ARN, a topic ARN, and a bucket ARN all resolve through the
+ * same code.
+ *
+ * Returns null when the reference is dynamic (a parameter, an import,
+ * or an Fn::Join that points at nothing this template declares); those
+ * need cross-stack resolution that's out of scope for v0.
+ */
+declare function resolveResourceChannel(value: unknown, service: string): string | null;
+/**
+ * Resolve a Queue reference (`!Ref X`, `!GetAtt X.Arn`, plain string
+ * ARN) to the queue's channel string.
+ */
+declare function resolveQueueChannel(value: unknown): string | null;
+/**
+ * Resolve a Topic reference (`!Ref X`, `!GetAtt X.Arn`, plain string
+ * ARN) to the topic's channel string.
+ */
+declare function resolveTopicChannel(value: unknown): string | null;
+/**
+ * Resolve a Bucket reference (`!Ref X`, `!GetAtt X.Arn`, plain string
+ * ARN) to the bucket's channel string.
+ */
+declare function resolveBucketChannel(value: unknown): string | null;
+
+/**
+ * eventPattern.ts reads what an EventBridge rule says about the events it
+ * matches, and which bus those events arrive on.
+ *
+ * A rule's EventPattern and its EventBusName are written the same way in a
+ * CloudFormation template and in a serverless.yml eventBridge event, so
+ * both readers reduce them here.
+ */
+/**
+ * How far a rule's EventPattern reduced: either to the exact
+ * detail-types it lists, or not at all, along with a reason someone can
+ * read.
+ */
+type PatternReduction = {
+    kind: "exact";
+    detailTypes: string[];
+} | {
+    kind: "unresolvable";
+    reason: string;
+};
+/**
+ * Reduce a rule's EventPattern to the exact set of DetailTypes it
+ * matches. v0 handles only a literal `detail-type` array; anything else
+ * (absent detail-type, content-filter objects, empty array) is
+ * unresolvable, surfaced by the checker, never silently dropped.
+ */
+declare function reduceEventPattern(pattern: unknown): PatternReduction;
+/**
+ * Resolve a rule's EventBusName to the channel's bus token: the CFN
+ * logical id when it's a Ref/GetAtt, the name segment of an event-bus
+ * ARN, the literal string otherwise, or "default" when it's left out
+ * (the EventBridge default event bus).
+ */
+declare function resolveEventBusToken(value: unknown): string;
+
+/**
+ * globals.ts folds the SAM `Globals` section into the resources that
+ * inherit from it, so every reader sees one set of properties per resource
+ * and none of them has to know that `Globals` exists.
+ *
+ * SAM applies a section's properties to each resource of the matching type,
+ * and the resource's own value wins where both declare one, per
+ * https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification-template-anatomy-globals.html
+ *
+ * That page has the combining rules too. A map is merged key by key, a list
+ * becomes the section's entries followed by the resource's, and anything
+ * else is replaced outright. Merging keys is what makes a function that sets
+ * one environment variable of its own still get the section's others.
+ */
+
 /**
  * The template's resources with each `Globals` section already applied
- * to the resources it covers. A resource of a type no section names, or
- * a template with no `Globals`, comes back untouched.
+ * to the resources it covers. A resource whose type no section covers,
+ * or a template with no `Globals`, comes back untouched.
  */
 declare function resourcesWithGlobals(template: CloudFormationTemplate): Record<string, CloudFormationResource>;
 /**
  * Per function logical id, the environment variables the `Function`
  * section supplies that the function does not declare for itself. A
  * consumer that treats a function's environment as its own contract
- * needs the distinction: a name every function in the document receives
- * says something about the document, not about any one function.
+ * needs the difference, because a variable every function in the
+ * document receives tells you about the document, not about one
+ * function.
  */
 declare function inheritedEnvVars(template: CloudFormationTemplate): Record<string, string[]>;
 
+/**
+ * nestedStacks.ts reads a template and every child template it embeds, as a
+ * list of documents.
+ *
+ * A stack resource points at another template, and CloudFormation deploys that
+ * template's resources alongside the parent's. Each document keeps its own
+ * namespace, its own SAM `Globals` section, and its own directory, so the tree
+ * stays a list of documents. Merging them would apply one document's defaults
+ * to another's resources, and let two logical ids spelled the same way collide.
+ *
+ * A child's reference to one of its own parameters is not followed to what the
+ * parent bound, and a `Fn::GetAtt` on a stack resource is not followed to the
+ * child's output. Both point at nothing, like any reference we can't resolve.
+ */
+
 /**
  * How deep the reader follows children. CloudFormation itself allows
  * deeper nesting; a template chain this long in a repository is far
@@ -79,7 +208,7 @@ declare function inheritedEnvVars(template: CloudFormationTemplate): Record<stri
  * rather than applied silently.
  */
 declare const MAX_STACK_DEPTH = 10;
-/** One template file, and where it sits in the tree that reached it. */
+/** One template file, and where it lives in the tree that reached it. */
 interface TemplateDocument {
     /** Absolute path of the file this document was read from. */
     path: string;
@@ -92,8 +221,8 @@ interface TemplateDocument {
 }
 /**
  * Why a child template was not read. Every value is a limit on what the
- * reader could reach, so a consumer should report it as reading that
- * stopped rather than treat the child as a template holding nothing.
+ * reader could reach, so a consumer should report it as a read that
+ * stopped rather than treat the child as an empty template.
  */
 type UnfollowedReason = "remoteUrl" | "notALiteralPath" | "fileMissing" | "unreadable" | "cycle" | "depthLimit";
 /** A child template the reader could not open, and what stopped it. */
@@ -105,7 +234,7 @@ interface UnfollowedStack {
     /** The template location as the document writes it, when it is a string. */
     templateUrl: string | null;
     reason: UnfollowedReason;
-    /** One phrase naming what stopped the read, for a message to a person. */
+    /** One phrase saying what stopped the read, for a message to a person. */
     detail: string;
 }
 interface TemplateTree {
@@ -125,14 +254,27 @@ interface TemplateTree {
 declare function loadTemplateTree(rootPath: string): TemplateTree;
 /**
  * A logical id qualified by the stack path that reaches it, so two
- * documents that both declare `HandlerFunction` name two different
+ * documents that both declare `HandlerFunction` refer to two different
  * deployed things. A resource in the root document keeps its bare id,
  * which is also what CloudFormation shows for it.
  */
 declare function qualifiedLogicalId(stackPath: string[], logicalId: string): string;
-/** A line naming one child the reader could not open, and why. */
+/** A line saying which child the reader could not open, and why. */
 declare function unfollowedStackMessage(stack: UnfollowedStack): string;
 
+/**
+ * serverlessFunctions.ts reads AWS::Serverless::Function resources into a
+ * code-facing view: which module and export each function points at, and
+ * which route and non-route Events it declares.
+ *
+ * The summary-generation paths expand SAM Events into API Gateway route
+ * summaries. This reader covers the other question the code-side pairing
+ * needs: given the template, where is each handler's implementation, and
+ * what routes is it bound to? The manifest semantics (how a Handler string
+ * is laid out, how CodeUri is inherited from Globals, Api versus HttpApi
+ * Events) stay here rather than being reconstructed in a framework pack.
+ */
+
 /** A route-bearing SAM Event (`Type: Api` or `Type: HttpApi`). */
 interface ServerlessHttpRoute {
     /** Key of the event in the function's `Events` map. */
@@ -147,9 +289,10 @@ interface ServerlessHttpRoute {
     apiId: string | null;
 }
 /**
- * A recognized SAM Event that isn't an HTTP route — SQS / Schedule /
- * SNS / S3 / etc. Surfaced (not dropped) so the code side can account
- * for handlers it recognizes but deliberately doesn't extract as HTTP.
+ * A recognized SAM Event that isn't an HTTP route (SQS, Schedule, SNS,
+ * S3, and so on). These are reported rather than dropped, so the code
+ * side can account for handlers it recognizes but deliberately doesn't
+ * extract as HTTP.
  */
 interface ServerlessNonHttpEvent {
     eventId: string;
@@ -163,7 +306,7 @@ interface ServerlessFunctionInfo {
     handler: string;
     /** Module-path portion of the handler (everything before the final dot). */
     modulePath: string;
-    /** Exported symbol the handler names (everything after the final dot). */
+    /** Exported symbol the handler points at (everything after the final dot). */
     exportName: string;
     /**
      * CodeUri base directory the handler resolves against: the function's
@@ -181,16 +324,16 @@ interface ParsedHandler {
  * Split a SAM Handler string into its module path and exported symbol.
  * The final dot separates them: `"src/handlers/confirmToken.handler"` →
  * `{ modulePath: "src/handlers/confirmToken", exportName: "handler" }`.
- * Returns null when there's no dot (nothing names an export to bind to).
+ * Returns null when there's no dot, since there's no export to bind to.
  */
 declare function parseHandler(handler: string): ParsedHandler | null;
 /**
  * Read every AWS::Serverless::Function resource in the template into a
  * code-facing `ServerlessFunctionInfo`. Functions without a parseable
- * Handler are skipped (there's no export to bind). Functions with no
- * Events still appear (empty route + non-route lists) so a consumer can
- * see them.
+ * Handler are skipped, since there's no export to bind. Functions with
+ * no Events still appear, with both event lists empty, so a consumer
+ * can see them.
  */
 declare function readServerlessFunctions(template: CloudFormationTemplate): ServerlessFunctionInfo[];
 
-export { type AppSyncResolverBinding, CLOUDFORMATION_YAML_TAGS, type CloudFormationResource, type CloudFormationTemplate, MAX_STACK_DEPTH, type ParsedHandler, type ServerlessFunctionInfo, type ServerlessHttpRoute, type ServerlessNonHttpEvent, type TemplateDocument, type TemplateTree, type UnfollowedReason, type UnfollowedStack, inheritedEnvVars, loadCloudFormationTemplate, loadTemplateTree, parseHandler, qualifiedLogicalId, readAppSyncResolvers, readServerlessFunctions, refTarget, resourcesWithGlobals, unfollowedStackMessage };
+export { type AppSyncResolverBinding, CLOUDFORMATION_YAML_TAGS, type CloudFormationResource, type CloudFormationTemplate, MAX_STACK_DEPTH, type ParsedHandler, type PatternReduction, type ServerlessFunctionInfo, type ServerlessHttpRoute, type ServerlessNonHttpEvent, type TemplateDocument, type TemplateTree, type UnfollowedReason, type UnfollowedStack, inheritedEnvVars, loadCloudFormationTemplate, loadTemplateTree, parseHandler, qualifiedLogicalId, readAppSyncResolvers, readServerlessFunctions, reduceEventPattern, refTarget, resolveBucketChannel, resolveEventBusToken, resolveQueueChannel, resolveResourceChannel, resolveTopicChannel, resourcesWithGlobals, unfollowedStackMessage };

package/dist/index.js

@@ -16,7 +16,11 @@ var getAttParts = (value) => {
     return value.map(String);
   }
   const text = String(value);
-  return text.includes(".") ? text.split(".") : [text];
+  const dot = text.indexOf(".");
+  if (dot === -1) {
+    return [text];
+  }
+  return [text.slice(0, dot), text.slice(dot + 1)];
 };
 var CLOUDFORMATION_YAML_TAGS = [
   ...everyNodeKind("!Ref", (value) => ({ Ref: value })),
@@ -68,8 +72,7 @@ function refTarget(value) {
     return getAtt[0];
   }
   if (typeof getAtt === "string") {
-    const dot = getAtt.indexOf(".");
-    return dot === -1 ? getAtt : getAtt.slice(0, dot);
+    return getAttParts(getAtt)[0] ?? null;
   }
   return null;
 }
@@ -233,6 +236,102 @@ function stringOf(value) {
   return typeof value === "string" ? value : null;
 }
 
+// src/arn.ts
+function resolveResourceChannel(value, service) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "string") {
+    const resource = resolveArnResource(value, service);
+    return resource ?? value;
+  }
+  return refTarget(value);
+}
+function resolveArnResource(value, service) {
+  const parts = value.split(":");
+  if (parts[0] !== "arn" || parts[2] !== service) {
+    return null;
+  }
+  const region = parts[3];
+  const account = parts[4];
+  const resource = parts.slice(5).join(":");
+  if (service === "s3") {
+    if (region !== "" || account !== "" || resource === "") {
+      return null;
+    }
+    const slash = resource.indexOf("/");
+    const bucket = slash === -1 ? resource : resource.slice(0, slash);
+    return bucket === "" ? null : bucket;
+  }
+  if (!region || !account || resource === "") {
+    return null;
+  }
+  return resource;
+}
+function resolveQueueChannel(value) {
+  return resolveResourceChannel(value, "sqs");
+}
+function resolveTopicChannel(value) {
+  return resolveResourceChannel(value, "sns");
+}
+function resolveBucketChannel(value) {
+  return resolveResourceChannel(value, "s3");
+}
+
+// src/eventPattern.ts
+function reduceEventPattern(pattern) {
+  if (pattern === null || typeof pattern !== "object") {
+    return {
+      kind: "unresolvable",
+      reason: "rule declares no EventPattern"
+    };
+  }
+  const detailType = pattern["detail-type"];
+  if (detailType === void 0) {
+    return {
+      kind: "unresolvable",
+      reason: "EventPattern has no detail-type; v0 reduces routing to exact detail-type match only"
+    };
+  }
+  if (!Array.isArray(detailType)) {
+    return {
+      kind: "unresolvable",
+      reason: "detail-type is not a plain array of string literals"
+    };
+  }
+  const detailTypes = [];
+  for (const entry of detailType) {
+    if (typeof entry !== "string") {
+      return {
+        kind: "unresolvable",
+        reason: "detail-type contains a content filter (prefix / anything-but / etc.); pattern subsumption is out of v0 scope"
+      };
+    }
+    detailTypes.push(entry);
+  }
+  if (detailTypes.length === 0) {
+    return { kind: "unresolvable", reason: "detail-type array is empty" };
+  }
+  return { kind: "exact", detailTypes };
+}
+function resolveEventBusToken(value) {
+  if (value === null || value === void 0) {
+    return "default";
+  }
+  if (typeof value === "object") {
+    const logicalId = refTarget(value);
+    return logicalId ?? "default";
+  }
+  if (typeof value === "string") {
+    const arnMatch = value.match(/:event-bus\/(.+)$/);
+    if (arnMatch !== null) {
+      return arnMatch[1];
+    }
+    return value;
+  }
+  return "default";
+}
+
 // src/globals.ts
 var GLOBALS_SECTION_TYPES = {
   Api: "AWS::Serverless::Api",
@@ -546,7 +645,13 @@ export {
   qualifiedLogicalId,
   readAppSyncResolvers,
   readServerlessFunctions,
+  reduceEventPattern,
   refTarget,
+  resolveBucketChannel,
+  resolveEventBusToken,
+  resolveQueueChannel,
+  resolveResourceChannel,
+  resolveTopicChannel,
   resourcesWithGlobals,
   unfollowedStackMessage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/manifest-aws",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "description": "Parse AWS CloudFormation / SAM templates into plain data — the shared facts layer contract readers and manifest-driven framework packs both consume.",
   "keywords": [
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/ir-core": "0.3.2",
+    "@suss/ir-core": "0.4.0",
     "yaml": "^2.4.0"
   },
   "devDependencies": {