@suss/manifest-aws 0.33.0 → 0.34.0

package/README.md

@@ -4,11 +4,11 @@ Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides o
 
 Reads a CloudFormation or SAM template into plain data: the resources, what each one declares, the globals every function inherits, the nested stacks, and the ARNs and event patterns written across them.
 
-Two kinds of reader work from that data. `@suss/contract-cloudformation` and `@suss/contract-serverless` turn a template into summaries, and the Lambda pack pairs a handler in code against the route or queue the template gives it. Both used to parse the template themselves, and they disagreed about what it said.
+Two kinds of reader work from that data. `@suss/contract-cloudformation` and `@suss/contract-serverless` turn a template into summaries. The Lambda pack pairs a handler in code with the route or queue the template assigns to it. Both used to parse the template themselves, and they disagreed about its contents.
 
 ## Where it fits
 
-It depends on `@suss/behavioral-ir` and a YAML parser, and it produces data rather than summaries. Nothing here decides what a resource means; a reader does.
+It depends on `@suss/ir-core` and a YAML parser. It produces plain data, and the readers build summaries from it. The readers also decide what each resource means, and this package leaves that to them.
 
 ## More
 

package/dist/index.d.cts

@@ -2,13 +2,12 @@ import YAML from 'yaml';
 export { ParsedHandler, parseHandler } from '@suss/ir-core';
 
 /**
- * templateLoader.ts parses a CloudFormation or SAM template file into a
- * plain object, resolving the shorthand YAML tags CFN uses for intrinsics.
+ * 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.
+ * The contract readers and the code-side handler pairing both load
+ * templates through this module, so YAML and JSON parsing and intrinsic
+ * tag handling are written once.
  */
 
 interface CloudFormationResource {
@@ -51,18 +50,18 @@ declare function loadCloudFormationTemplate(templatePath: string): CloudFormatio
 declare function refTarget(value: unknown): string | null;
 
 /**
- * appsyncResolvers.ts works out which GraphQL field each Lambda serves.
+ * 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
+ * of writing that are read here: 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.
+ * Like the rest of this package, it 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.
+ * matches the schema, is left to the reader that consumes these bindings.
  */
 
 /** One GraphQL field and the Lambdas behind it. */
@@ -84,8 +83,8 @@ 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.
+ * 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
@@ -100,9 +99,9 @@ declare function readAppSyncResolvers(template: CloudFormationTemplate): AppSync
  * 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.
+ * Returns null for any other intrinsic, such as `Fn::ImportValue` or
+ * `Fn::Join`, since resolving those needs a stack this package does not
+ * read. A `Ref` to a parameter comes back as the parameter's name.
  */
 declare function resolveResourceChannel(value: unknown, service: string): string | null;
 /**
@@ -122,8 +121,8 @@ declare function resolveTopicChannel(value: unknown): string | null;
 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.
+ * 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
@@ -143,9 +142,9 @@ type PatternReduction = {
 };
 /**
  * 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.
+ * matches. Only a literal `detail-type` array reduces. Anything else,
+ * such as a missing detail-type, a content filter or an empty array,
+ * comes back unresolvable with a reason, and the checker reports it.
  */
 declare function reduceEventPattern(pattern: unknown): PatternReduction;
 /**
@@ -157,9 +156,9 @@ declare function reduceEventPattern(pattern: unknown): PatternReduction;
 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.
+ * 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
@@ -167,8 +166,8 @@ declare function resolveEventBusToken(value: unknown): string;
  *
  * 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.
+ * else is replaced outright. Because maps merge by key, a function that sets
+ * one environment variable of its own still gets the section's others.
  */
 
 /**
@@ -180,16 +179,15 @@ declare function resourcesWithGlobals(template: CloudFormationTemplate): Record<
 /**
  * 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 difference, because a variable every function in the
- * document receives tells you about the document, not about one
- * function.
+ * consumer that treats a function's environment as that function's
+ * contract needs the difference, because every function in the document
+ * receives these variables.
  */
 declare function inheritedEnvVars(template: CloudFormationTemplate): Record<string, string[]>;
 
 /**
- * nestedStacks.ts reads a template and every child template it embeds, as a
- * list of documents.
+ * 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
@@ -199,7 +197,7 @@ declare function inheritedEnvVars(template: CloudFormationTemplate): Record<stri
  *
  * 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.
+ * child's output. Both point at no resource, like any other unresolved reference.
  */
 
 /**
@@ -254,7 +252,7 @@ interface TemplateTree {
  * The root template plus every template it embeds, directly or through
  * another child.
  *
- * A missing or malformed ROOT throws, matching
+ * A missing or malformed root template throws, matching
  * `loadCloudFormationTemplate`: the caller asked for that file by name.
  * A child that cannot be read never throws; it lands in `unfollowed` so
  * the caller can report which one and why.
@@ -271,16 +269,15 @@ declare function qualifiedLogicalId(stackPath: string[], logicalId: string): str
 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.
+ * 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.
+ * The contract readers expand SAM Events into API Gateway route summaries.
+ * The code-side pairing needs something else from the template: where each
+ * handler's implementation is, and which routes it is bound to. CodeUri
+ * inheritance from Globals and the difference between Api and HttpApi
+ * Events are handled here, so a framework pack does not work them out again.
  */
 
 /** A route-bearing SAM Event (`Type: Api` or `Type: HttpApi`). */

package/dist/index.d.ts

@@ -2,13 +2,12 @@ import YAML from 'yaml';
 export { ParsedHandler, parseHandler } from '@suss/ir-core';
 
 /**
- * templateLoader.ts parses a CloudFormation or SAM template file into a
- * plain object, resolving the shorthand YAML tags CFN uses for intrinsics.
+ * 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.
+ * The contract readers and the code-side handler pairing both load
+ * templates through this module, so YAML and JSON parsing and intrinsic
+ * tag handling are written once.
  */
 
 interface CloudFormationResource {
@@ -51,18 +50,18 @@ declare function loadCloudFormationTemplate(templatePath: string): CloudFormatio
 declare function refTarget(value: unknown): string | null;
 
 /**
- * appsyncResolvers.ts works out which GraphQL field each Lambda serves.
+ * 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
+ * of writing that are read here: 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.
+ * Like the rest of this package, it 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.
+ * matches the schema, is left to the reader that consumes these bindings.
  */
 
 /** One GraphQL field and the Lambdas behind it. */
@@ -84,8 +83,8 @@ 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.
+ * 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
@@ -100,9 +99,9 @@ declare function readAppSyncResolvers(template: CloudFormationTemplate): AppSync
  * 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.
+ * Returns null for any other intrinsic, such as `Fn::ImportValue` or
+ * `Fn::Join`, since resolving those needs a stack this package does not
+ * read. A `Ref` to a parameter comes back as the parameter's name.
  */
 declare function resolveResourceChannel(value: unknown, service: string): string | null;
 /**
@@ -122,8 +121,8 @@ declare function resolveTopicChannel(value: unknown): string | null;
 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.
+ * 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
@@ -143,9 +142,9 @@ type PatternReduction = {
 };
 /**
  * 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.
+ * matches. Only a literal `detail-type` array reduces. Anything else,
+ * such as a missing detail-type, a content filter or an empty array,
+ * comes back unresolvable with a reason, and the checker reports it.
  */
 declare function reduceEventPattern(pattern: unknown): PatternReduction;
 /**
@@ -157,9 +156,9 @@ declare function reduceEventPattern(pattern: unknown): PatternReduction;
 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.
+ * 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
@@ -167,8 +166,8 @@ declare function resolveEventBusToken(value: unknown): string;
  *
  * 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.
+ * else is replaced outright. Because maps merge by key, a function that sets
+ * one environment variable of its own still gets the section's others.
  */
 
 /**
@@ -180,16 +179,15 @@ declare function resourcesWithGlobals(template: CloudFormationTemplate): Record<
 /**
  * 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 difference, because a variable every function in the
- * document receives tells you about the document, not about one
- * function.
+ * consumer that treats a function's environment as that function's
+ * contract needs the difference, because every function in the document
+ * receives these variables.
  */
 declare function inheritedEnvVars(template: CloudFormationTemplate): Record<string, string[]>;
 
 /**
- * nestedStacks.ts reads a template and every child template it embeds, as a
- * list of documents.
+ * 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
@@ -199,7 +197,7 @@ declare function inheritedEnvVars(template: CloudFormationTemplate): Record<stri
  *
  * 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.
+ * child's output. Both point at no resource, like any other unresolved reference.
  */
 
 /**
@@ -254,7 +252,7 @@ interface TemplateTree {
  * The root template plus every template it embeds, directly or through
  * another child.
  *
- * A missing or malformed ROOT throws, matching
+ * A missing or malformed root template throws, matching
  * `loadCloudFormationTemplate`: the caller asked for that file by name.
  * A child that cannot be read never throws; it lands in `unfollowed` so
  * the caller can report which one and why.
@@ -271,16 +269,15 @@ declare function qualifiedLogicalId(stackPath: string[], logicalId: string): str
 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.
+ * 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.
+ * The contract readers expand SAM Events into API Gateway route summaries.
+ * The code-side pairing needs something else from the template: where each
+ * handler's implementation is, and which routes it is bound to. CodeUri
+ * inheritance from Globals and the difference between Api and HttpApi
+ * Events are handled here, so a framework pack does not work them out again.
  */
 
 /** A route-bearing SAM Event (`Type: Api` or `Type: HttpApi`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/manifest-aws",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "description": "Parse a CloudFormation or SAM template into plain data, the facts every suss reader of an AWS template works from.",
   "keywords": [
@@ -13,7 +13,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/manifest/aws#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -46,7 +46,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/ir-core": "0.33.0",
+    "@suss/ir-core": "0.34.0",
     "yaml": "^2.4.0"
   },
   "devDependencies": {