@suss/manifest-aws 0.1.0 → 0.1.1

package/dist/index.cjs

@@ -31,11 +31,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CLOUDFORMATION_YAML_TAGS: () => CLOUDFORMATION_YAML_TAGS,
+  MAX_STACK_DEPTH: () => MAX_STACK_DEPTH,
+  inheritedEnvVars: () => inheritedEnvVars,
   loadCloudFormationTemplate: () => loadCloudFormationTemplate,
+  loadTemplateTree: () => loadTemplateTree,
   parseHandler: () => parseHandler,
+  qualifiedLogicalId: () => qualifiedLogicalId,
   readAppSyncResolvers: () => readAppSyncResolvers,
   readServerlessFunctions: () => readServerlessFunctions,
-  refTarget: () => refTarget
+  refTarget: () => refTarget,
+  resourcesWithGlobals: () => resourcesWithGlobals,
+  unfollowedStackMessage: () => unfollowedStackMessage
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -43,17 +49,27 @@ module.exports = __toCommonJS(index_exports);
 var import_node_fs = __toESM(require("fs"), 1);
 var import_node_path = __toESM(require("path"), 1);
 var import_yaml = __toESM(require("yaml"), 1);
+var everyNodeKind = (tag, resolve) => {
+  const forNode = (value) => resolve(plainly(value));
+  return [
+    { tag, resolve: forNode },
+    { tag, collection: "seq", resolve: forNode },
+    { tag, collection: "map", resolve: forNode }
+  ];
+};
+var plainly = (value) => typeof value === "object" && value !== null && "toJSON" in value && typeof value.toJSON === "function" ? value.toJSON() : value;
+var getAttParts = (value) => {
+  if (Array.isArray(value)) {
+    return value.map(String);
+  }
+  const text = String(value);
+  return text.includes(".") ? text.split(".") : [text];
+};
 var CLOUDFORMATION_YAML_TAGS = [
-  {
-    tag: "!Ref",
-    resolve: (value) => ({ Ref: value })
-  },
-  {
-    tag: "!GetAtt",
-    resolve: (value) => ({
-      "Fn::GetAtt": value.includes(".") ? value.split(".") : [value]
-    })
-  },
+  ...everyNodeKind("!Ref", (value) => ({ Ref: value })),
+  ...everyNodeKind("!GetAtt", (value) => ({
+    "Fn::GetAtt": getAttParts(value)
+  })),
   ...[
     "!Sub",
     "!Join",
@@ -68,7 +84,7 @@ var CLOUDFORMATION_YAML_TAGS = [
     "!And",
     "!Or",
     "!Equals"
-  ].map((tag) => ({ tag, resolve: (value) => value }))
+  ].flatMap((tag) => everyNodeKind(tag, (value) => value))
 ];
 function loadCloudFormationTemplate(templatePath) {
   const resolved = import_node_path.default.resolve(templatePath);
@@ -98,6 +114,10 @@ function refTarget(value) {
   if (Array.isArray(getAtt) && typeof getAtt[0] === "string") {
     return getAtt[0];
   }
+  if (typeof getAtt === "string") {
+    const dot = getAtt.indexOf(".");
+    return dot === -1 ? getAtt : getAtt.slice(0, dot);
+  }
   return null;
 }
 
@@ -260,7 +280,227 @@ function stringOf(value) {
   return typeof value === "string" ? value : null;
 }
 
+// src/globals.ts
+var GLOBALS_SECTION_TYPES = {
+  Api: "AWS::Serverless::Api",
+  Function: "AWS::Serverless::Function",
+  HttpApi: "AWS::Serverless::HttpApi",
+  LayerVersion: "AWS::Serverless::LayerVersion",
+  SimpleTable: "AWS::Serverless::SimpleTable",
+  StateMachine: "AWS::Serverless::StateMachine"
+};
+function resourcesWithGlobals(template) {
+  const resources = template.Resources ?? {};
+  const defaultsByType = defaultsPerResourceType(template.Globals);
+  if (defaultsByType.size === 0) {
+    return resources;
+  }
+  const out = {};
+  for (const [logicalId, resource] of Object.entries(resources)) {
+    const defaults = defaultsByType.get(resource.Type ?? "");
+    out[logicalId] = defaults === void 0 ? resource : {
+      ...resource,
+      Properties: mergedProperties(defaults, resource.Properties ?? {})
+    };
+  }
+  return out;
+}
+function inheritedEnvVars(template) {
+  const sectionVars = envVarNames(template.Globals?.Function);
+  if (sectionVars.length === 0) {
+    return {};
+  }
+  const out = {};
+  for (const [logicalId, resource] of Object.entries(
+    template.Resources ?? {}
+  )) {
+    if (resource.Type !== GLOBALS_SECTION_TYPES.Function) {
+      continue;
+    }
+    const own = new Set(envVarNames(resource.Properties));
+    out[logicalId] = sectionVars.filter((name) => !own.has(name));
+  }
+  return out;
+}
+function envVarNames(properties) {
+  const environment = properties?.Environment;
+  if (!isPlainObject(environment)) {
+    return [];
+  }
+  const variables = environment.Variables;
+  return isPlainObject(variables) ? Object.keys(variables) : [];
+}
+function defaultsPerResourceType(globals) {
+  const byType = /* @__PURE__ */ new Map();
+  if (globals === null || typeof globals !== "object") {
+    return byType;
+  }
+  for (const [section, properties] of Object.entries(globals)) {
+    const resourceType = GLOBALS_SECTION_TYPES[section];
+    if (resourceType === void 0 || !isPlainObject(properties)) {
+      continue;
+    }
+    byType.set(resourceType, properties);
+  }
+  return byType;
+}
+function mergedProperties(defaults, own) {
+  const merged = { ...own };
+  for (const [name, fallback] of Object.entries(defaults)) {
+    merged[name] = name in own ? combined(fallback, own[name]) : fallback;
+  }
+  return merged;
+}
+function combined(fallback, own) {
+  if (Array.isArray(fallback) && Array.isArray(own)) {
+    return [...fallback, ...own];
+  }
+  if (isMergeableMap(fallback) && isMergeableMap(own)) {
+    return mergedProperties(fallback, own);
+  }
+  return own;
+}
+function isMergeableMap(value) {
+  return isPlainObject(value) && !isIntrinsic(value);
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isIntrinsic(value) {
+  const keys = Object.keys(value);
+  return keys.length === 1 && (keys[0] === "Ref" || keys[0].startsWith("Fn::") || keys[0] === "Condition");
+}
+
+// src/nestedStacks.ts
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+var CHILD_TEMPLATE_PROPERTY = {
+  "AWS::CloudFormation::Stack": "TemplateURL",
+  "AWS::Serverless::Application": "Location"
+};
+var MAX_STACK_DEPTH = 10;
+function loadTemplateTree(rootPath) {
+  const rootFile = import_node_path2.default.resolve(rootPath);
+  const root = {
+    path: rootFile,
+    stackPath: [],
+    template: loadCloudFormationTemplate(rootFile)
+  };
+  const documents = [root];
+  const unfollowed = [];
+  const queue = [
+    { document: root, ancestors: [rootFile] }
+  ];
+  for (let i = 0; i < queue.length; i += 1) {
+    const { document, ancestors } = queue[i];
+    for (const child of childStacksOf(document, ancestors)) {
+      if (child.type === "unfollowed") {
+        unfollowed.push(child.stack);
+        continue;
+      }
+      documents.push(child.document);
+      queue.push({
+        document: child.document,
+        ancestors: [...ancestors, child.document.path]
+      });
+    }
+  }
+  return { documents, unfollowed };
+}
+function qualifiedLogicalId(stackPath, logicalId) {
+  return [...stackPath, logicalId].join("/");
+}
+function unfollowedStackMessage(stack) {
+  const name = stack.stackPath.join("/");
+  return `could not follow nested stack ${name} declared in ${stack.declaredIn}: ${stack.detail}`;
+}
+function childStacksOf(document, ancestors) {
+  const out = [];
+  for (const [logicalId, resource] of Object.entries(
+    document.template.Resources ?? {}
+  )) {
+    const property = CHILD_TEMPLATE_PROPERTY[resource.Type ?? ""];
+    if (property === void 0) {
+      continue;
+    }
+    out.push(
+      childStack({
+        document,
+        ancestors,
+        logicalId,
+        location: resource.Properties?.[property]
+      })
+    );
+  }
+  return out;
+}
+function childStack(opts) {
+  const stackPath = [...opts.document.stackPath, opts.logicalId];
+  const report = (reason, detail, templateUrl) => ({
+    type: "unfollowed",
+    stack: {
+      declaredIn: opts.document.path,
+      stackPath,
+      templateUrl,
+      reason,
+      detail
+    }
+  });
+  const url = typeof opts.location === "string" ? opts.location.trim() : null;
+  if (url === null || url === "") {
+    return report(
+      "notALiteralPath",
+      "the template location is not a literal string",
+      null
+    );
+  }
+  if (url.includes("${")) {
+    return report(
+      "notALiteralPath",
+      `${url} holds a substitution nothing here can fill in`,
+      url
+    );
+  }
+  if (hasUrlScheme(url)) {
+    return report("remoteUrl", `${url} is not a path in this repository`, url);
+  }
+  if (stackPath.length > MAX_STACK_DEPTH) {
+    return report(
+      "depthLimit",
+      `nesting is deeper than ${MAX_STACK_DEPTH} stacks`,
+      url
+    );
+  }
+  const childPath = import_node_path2.default.resolve(import_node_path2.default.dirname(opts.document.path), url);
+  if (opts.ancestors.includes(childPath)) {
+    return report("cycle", `${url} is already open further up the tree`, url);
+  }
+  if (!import_node_fs2.default.existsSync(childPath)) {
+    return report("fileMissing", `${url} is not on disk`, url);
+  }
+  try {
+    return {
+      type: "document",
+      document: {
+        path: childPath,
+        stackPath,
+        template: loadCloudFormationTemplate(childPath)
+      }
+    };
+  } catch (err) {
+    return report(
+      "unreadable",
+      `${url} could not be parsed: ${err instanceof Error ? err.message : String(err)}`,
+      url
+    );
+  }
+}
+function hasUrlScheme(location) {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(location);
+}
+
 // src/serverlessFunctions.ts
+var import_ir_core = require("@suss/ir-core");
 function parseHandler(handler) {
   const trimmed = handler.trim();
   const lastDot = trimmed.lastIndexOf(".");
@@ -272,24 +512,12 @@ function parseHandler(handler) {
     exportName: trimmed.slice(lastDot + 1)
   };
 }
-function normalizeCodeUri(raw) {
-  const trimmed = raw.replace(/^\.\//, "").replace(/\/+$/, "");
-  return trimmed === "" ? "." : trimmed;
-}
-function readGlobalsCodeUri(template) {
-  const fnGlobals = template.Globals?.Function;
-  if (fnGlobals === void 0) {
-    return null;
-  }
-  const codeUri = fnGlobals.CodeUri;
-  return typeof codeUri === "string" ? normalizeCodeUri(codeUri) : null;
-}
-function readCodeUri(resource, globalsCodeUri) {
+function readCodeUri(resource) {
   const codeUri = resource.Properties?.CodeUri;
-  if (typeof codeUri === "string") {
-    return normalizeCodeUri(codeUri);
+  if (typeof codeUri !== "string") {
+    return ".";
   }
-  return globalsCodeUri ?? ".";
+  return (0, import_ir_core.codeScopePath)(codeUri) || ".";
 }
 function classifyEvents(events) {
   const httpRoutes = [];
@@ -309,8 +537,8 @@ function classifyEvents(events) {
     }
     const props = event.Properties ?? {};
     const method = String(props.Method ?? "").toUpperCase();
-    const path2 = String(props.Path ?? "");
-    if (method === "" || path2 === "") {
+    const path3 = String(props.Path ?? "");
+    if (method === "" || path3 === "") {
       nonHttpEvents.push({ eventId, eventType: type });
       continue;
     }
@@ -319,15 +547,14 @@ function classifyEvents(events) {
       eventId,
       eventType: type,
       method,
-      path: path2,
+      path: path3,
       apiId: apiRef
     });
   }
   return { httpRoutes, nonHttpEvents };
 }
 function readServerlessFunctions(template) {
-  const resources = template.Resources ?? {};
-  const globalsCodeUri = readGlobalsCodeUri(template);
+  const resources = resourcesWithGlobals(template);
   const out = [];
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource.Type !== "AWS::Serverless::Function") {
@@ -349,7 +576,7 @@ function readServerlessFunctions(template) {
       handler: handlerRaw,
       modulePath: parsed.modulePath,
       exportName: parsed.exportName,
-      codeUri: readCodeUri(resource, globalsCodeUri),
+      codeUri: readCodeUri(resource),
       httpRoutes,
       nonHttpEvents
     });
@@ -359,9 +586,15 @@ function readServerlessFunctions(template) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CLOUDFORMATION_YAML_TAGS,
+  MAX_STACK_DEPTH,
+  inheritedEnvVars,
   loadCloudFormationTemplate,
+  loadTemplateTree,
   parseHandler,
+  qualifiedLogicalId,
   readAppSyncResolvers,
   readServerlessFunctions,
-  refTarget
+  refTarget,
+  resourcesWithGlobals,
+  unfollowedStackMessage
 });

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import YAML from 'yaml';
+
 interface CloudFormationResource {
     Type?: string;
     Properties?: Record<string, unknown>;
@@ -12,20 +14,7 @@ interface CloudFormationTemplate {
     Globals?: Record<string, Record<string, unknown>>;
     Resources?: Record<string, CloudFormationResource>;
 }
-declare const CLOUDFORMATION_YAML_TAGS: ({
-    tag: string;
-    resolve: (value: unknown) => unknown;
-} | {
-    tag: string;
-    resolve: (value: string) => {
-        Ref: string;
-    };
-} | {
-    tag: string;
-    resolve: (value: string) => {
-        "Fn::GetAtt": string[];
-    };
-})[];
+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
@@ -37,10 +26,16 @@ declare const CLOUDFORMATION_YAML_TAGS: ({
  */
 declare function loadCloudFormationTemplate(templatePath: string): CloudFormationTemplate;
 /**
- * CloudFormation references show up in three shapes after parsing:
+ * CloudFormation references show up in four shapes after parsing:
  *   - { 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.
  */
 declare function refTarget(value: unknown): string | null;
 
@@ -62,6 +57,82 @@ interface AppSyncResolverBinding {
 }
 declare function readAppSyncResolvers(template: CloudFormationTemplate): AppSyncResolverBinding[];
 
+/**
+ * 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.
+ */
+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.
+ */
+declare function inheritedEnvVars(template: CloudFormationTemplate): Record<string, string[]>;
+
+/**
+ * How deep the reader follows children. CloudFormation itself allows
+ * deeper nesting; a template chain this long in a repository is far
+ * more likely to be a mistake than a design, and the limit is reported
+ * rather than applied silently.
+ */
+declare const MAX_STACK_DEPTH = 10;
+/** One template file, and where it sits in the tree that reached it. */
+interface TemplateDocument {
+    /** Absolute path of the file this document was read from. */
+    path: string;
+    /**
+     * Logical ids of the stack resources leading from the root document
+     * down to this one. Empty for the root.
+     */
+    stackPath: string[];
+    template: CloudFormationTemplate;
+}
+/**
+ * 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.
+ */
+type UnfollowedReason = "remoteUrl" | "notALiteralPath" | "fileMissing" | "unreadable" | "cycle" | "depthLimit";
+/** A child template the reader could not open, and what stopped it. */
+interface UnfollowedStack {
+    /** Absolute path of the document declaring the stack resource. */
+    declaredIn: string;
+    /** Stack path of the child, ending in this stack resource's logical id. */
+    stackPath: string[];
+    /** 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. */
+    detail: string;
+}
+interface TemplateTree {
+    /** The root document first, then every child that could be read. */
+    documents: TemplateDocument[];
+    unfollowed: UnfollowedStack[];
+}
+/**
+ * The root template plus every template it embeds, directly or through
+ * another child.
+ *
+ * A missing or malformed ROOT 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.
+ */
+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
+ * 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. */
+declare function unfollowedStackMessage(stack: UnfollowedStack): string;
+
 /** A route-bearing SAM Event (`Type: Api` or `Type: HttpApi`). */
 interface ServerlessHttpRoute {
     /** Key of the event in the function's `Events` map. */
@@ -122,4 +193,4 @@ declare function parseHandler(handler: string): ParsedHandler | null;
  */
 declare function readServerlessFunctions(template: CloudFormationTemplate): ServerlessFunctionInfo[];
 
-export { type AppSyncResolverBinding, CLOUDFORMATION_YAML_TAGS, type CloudFormationResource, type CloudFormationTemplate, type ParsedHandler, type ServerlessFunctionInfo, type ServerlessHttpRoute, type ServerlessNonHttpEvent, loadCloudFormationTemplate, parseHandler, readAppSyncResolvers, readServerlessFunctions, refTarget };
+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 };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import YAML from 'yaml';
+
 interface CloudFormationResource {
     Type?: string;
     Properties?: Record<string, unknown>;
@@ -12,20 +14,7 @@ interface CloudFormationTemplate {
     Globals?: Record<string, Record<string, unknown>>;
     Resources?: Record<string, CloudFormationResource>;
 }
-declare const CLOUDFORMATION_YAML_TAGS: ({
-    tag: string;
-    resolve: (value: unknown) => unknown;
-} | {
-    tag: string;
-    resolve: (value: string) => {
-        Ref: string;
-    };
-} | {
-    tag: string;
-    resolve: (value: string) => {
-        "Fn::GetAtt": string[];
-    };
-})[];
+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
@@ -37,10 +26,16 @@ declare const CLOUDFORMATION_YAML_TAGS: ({
  */
 declare function loadCloudFormationTemplate(templatePath: string): CloudFormationTemplate;
 /**
- * CloudFormation references show up in three shapes after parsing:
+ * CloudFormation references show up in four shapes after parsing:
  *   - { 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.
  */
 declare function refTarget(value: unknown): string | null;
 
@@ -62,6 +57,82 @@ interface AppSyncResolverBinding {
 }
 declare function readAppSyncResolvers(template: CloudFormationTemplate): AppSyncResolverBinding[];
 
+/**
+ * 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.
+ */
+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.
+ */
+declare function inheritedEnvVars(template: CloudFormationTemplate): Record<string, string[]>;
+
+/**
+ * How deep the reader follows children. CloudFormation itself allows
+ * deeper nesting; a template chain this long in a repository is far
+ * more likely to be a mistake than a design, and the limit is reported
+ * rather than applied silently.
+ */
+declare const MAX_STACK_DEPTH = 10;
+/** One template file, and where it sits in the tree that reached it. */
+interface TemplateDocument {
+    /** Absolute path of the file this document was read from. */
+    path: string;
+    /**
+     * Logical ids of the stack resources leading from the root document
+     * down to this one. Empty for the root.
+     */
+    stackPath: string[];
+    template: CloudFormationTemplate;
+}
+/**
+ * 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.
+ */
+type UnfollowedReason = "remoteUrl" | "notALiteralPath" | "fileMissing" | "unreadable" | "cycle" | "depthLimit";
+/** A child template the reader could not open, and what stopped it. */
+interface UnfollowedStack {
+    /** Absolute path of the document declaring the stack resource. */
+    declaredIn: string;
+    /** Stack path of the child, ending in this stack resource's logical id. */
+    stackPath: string[];
+    /** 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. */
+    detail: string;
+}
+interface TemplateTree {
+    /** The root document first, then every child that could be read. */
+    documents: TemplateDocument[];
+    unfollowed: UnfollowedStack[];
+}
+/**
+ * The root template plus every template it embeds, directly or through
+ * another child.
+ *
+ * A missing or malformed ROOT 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.
+ */
+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
+ * 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. */
+declare function unfollowedStackMessage(stack: UnfollowedStack): string;
+
 /** A route-bearing SAM Event (`Type: Api` or `Type: HttpApi`). */
 interface ServerlessHttpRoute {
     /** Key of the event in the function's `Events` map. */
@@ -122,4 +193,4 @@ declare function parseHandler(handler: string): ParsedHandler | null;
  */
 declare function readServerlessFunctions(template: CloudFormationTemplate): ServerlessFunctionInfo[];
 
-export { type AppSyncResolverBinding, CLOUDFORMATION_YAML_TAGS, type CloudFormationResource, type CloudFormationTemplate, type ParsedHandler, type ServerlessFunctionInfo, type ServerlessHttpRoute, type ServerlessNonHttpEvent, loadCloudFormationTemplate, parseHandler, readAppSyncResolvers, readServerlessFunctions, refTarget };
+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 };

package/dist/index.js

@@ -2,17 +2,27 @@
 import fs from "fs";
 import path from "path";
 import YAML from "yaml";
+var everyNodeKind = (tag, resolve) => {
+  const forNode = (value) => resolve(plainly(value));
+  return [
+    { tag, resolve: forNode },
+    { tag, collection: "seq", resolve: forNode },
+    { tag, collection: "map", resolve: forNode }
+  ];
+};
+var plainly = (value) => typeof value === "object" && value !== null && "toJSON" in value && typeof value.toJSON === "function" ? value.toJSON() : value;
+var getAttParts = (value) => {
+  if (Array.isArray(value)) {
+    return value.map(String);
+  }
+  const text = String(value);
+  return text.includes(".") ? text.split(".") : [text];
+};
 var CLOUDFORMATION_YAML_TAGS = [
-  {
-    tag: "!Ref",
-    resolve: (value) => ({ Ref: value })
-  },
-  {
-    tag: "!GetAtt",
-    resolve: (value) => ({
-      "Fn::GetAtt": value.includes(".") ? value.split(".") : [value]
-    })
-  },
+  ...everyNodeKind("!Ref", (value) => ({ Ref: value })),
+  ...everyNodeKind("!GetAtt", (value) => ({
+    "Fn::GetAtt": getAttParts(value)
+  })),
   ...[
     "!Sub",
     "!Join",
@@ -27,7 +37,7 @@ var CLOUDFORMATION_YAML_TAGS = [
     "!And",
     "!Or",
     "!Equals"
-  ].map((tag) => ({ tag, resolve: (value) => value }))
+  ].flatMap((tag) => everyNodeKind(tag, (value) => value))
 ];
 function loadCloudFormationTemplate(templatePath) {
   const resolved = path.resolve(templatePath);
@@ -57,6 +67,10 @@ function refTarget(value) {
   if (Array.isArray(getAtt) && typeof getAtt[0] === "string") {
     return getAtt[0];
   }
+  if (typeof getAtt === "string") {
+    const dot = getAtt.indexOf(".");
+    return dot === -1 ? getAtt : getAtt.slice(0, dot);
+  }
   return null;
 }
 
@@ -219,7 +233,227 @@ function stringOf(value) {
   return typeof value === "string" ? value : null;
 }
 
+// src/globals.ts
+var GLOBALS_SECTION_TYPES = {
+  Api: "AWS::Serverless::Api",
+  Function: "AWS::Serverless::Function",
+  HttpApi: "AWS::Serverless::HttpApi",
+  LayerVersion: "AWS::Serverless::LayerVersion",
+  SimpleTable: "AWS::Serverless::SimpleTable",
+  StateMachine: "AWS::Serverless::StateMachine"
+};
+function resourcesWithGlobals(template) {
+  const resources = template.Resources ?? {};
+  const defaultsByType = defaultsPerResourceType(template.Globals);
+  if (defaultsByType.size === 0) {
+    return resources;
+  }
+  const out = {};
+  for (const [logicalId, resource] of Object.entries(resources)) {
+    const defaults = defaultsByType.get(resource.Type ?? "");
+    out[logicalId] = defaults === void 0 ? resource : {
+      ...resource,
+      Properties: mergedProperties(defaults, resource.Properties ?? {})
+    };
+  }
+  return out;
+}
+function inheritedEnvVars(template) {
+  const sectionVars = envVarNames(template.Globals?.Function);
+  if (sectionVars.length === 0) {
+    return {};
+  }
+  const out = {};
+  for (const [logicalId, resource] of Object.entries(
+    template.Resources ?? {}
+  )) {
+    if (resource.Type !== GLOBALS_SECTION_TYPES.Function) {
+      continue;
+    }
+    const own = new Set(envVarNames(resource.Properties));
+    out[logicalId] = sectionVars.filter((name) => !own.has(name));
+  }
+  return out;
+}
+function envVarNames(properties) {
+  const environment = properties?.Environment;
+  if (!isPlainObject(environment)) {
+    return [];
+  }
+  const variables = environment.Variables;
+  return isPlainObject(variables) ? Object.keys(variables) : [];
+}
+function defaultsPerResourceType(globals) {
+  const byType = /* @__PURE__ */ new Map();
+  if (globals === null || typeof globals !== "object") {
+    return byType;
+  }
+  for (const [section, properties] of Object.entries(globals)) {
+    const resourceType = GLOBALS_SECTION_TYPES[section];
+    if (resourceType === void 0 || !isPlainObject(properties)) {
+      continue;
+    }
+    byType.set(resourceType, properties);
+  }
+  return byType;
+}
+function mergedProperties(defaults, own) {
+  const merged = { ...own };
+  for (const [name, fallback] of Object.entries(defaults)) {
+    merged[name] = name in own ? combined(fallback, own[name]) : fallback;
+  }
+  return merged;
+}
+function combined(fallback, own) {
+  if (Array.isArray(fallback) && Array.isArray(own)) {
+    return [...fallback, ...own];
+  }
+  if (isMergeableMap(fallback) && isMergeableMap(own)) {
+    return mergedProperties(fallback, own);
+  }
+  return own;
+}
+function isMergeableMap(value) {
+  return isPlainObject(value) && !isIntrinsic(value);
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isIntrinsic(value) {
+  const keys = Object.keys(value);
+  return keys.length === 1 && (keys[0] === "Ref" || keys[0].startsWith("Fn::") || keys[0] === "Condition");
+}
+
+// src/nestedStacks.ts
+import fs2 from "fs";
+import path2 from "path";
+var CHILD_TEMPLATE_PROPERTY = {
+  "AWS::CloudFormation::Stack": "TemplateURL",
+  "AWS::Serverless::Application": "Location"
+};
+var MAX_STACK_DEPTH = 10;
+function loadTemplateTree(rootPath) {
+  const rootFile = path2.resolve(rootPath);
+  const root = {
+    path: rootFile,
+    stackPath: [],
+    template: loadCloudFormationTemplate(rootFile)
+  };
+  const documents = [root];
+  const unfollowed = [];
+  const queue = [
+    { document: root, ancestors: [rootFile] }
+  ];
+  for (let i = 0; i < queue.length; i += 1) {
+    const { document, ancestors } = queue[i];
+    for (const child of childStacksOf(document, ancestors)) {
+      if (child.type === "unfollowed") {
+        unfollowed.push(child.stack);
+        continue;
+      }
+      documents.push(child.document);
+      queue.push({
+        document: child.document,
+        ancestors: [...ancestors, child.document.path]
+      });
+    }
+  }
+  return { documents, unfollowed };
+}
+function qualifiedLogicalId(stackPath, logicalId) {
+  return [...stackPath, logicalId].join("/");
+}
+function unfollowedStackMessage(stack) {
+  const name = stack.stackPath.join("/");
+  return `could not follow nested stack ${name} declared in ${stack.declaredIn}: ${stack.detail}`;
+}
+function childStacksOf(document, ancestors) {
+  const out = [];
+  for (const [logicalId, resource] of Object.entries(
+    document.template.Resources ?? {}
+  )) {
+    const property = CHILD_TEMPLATE_PROPERTY[resource.Type ?? ""];
+    if (property === void 0) {
+      continue;
+    }
+    out.push(
+      childStack({
+        document,
+        ancestors,
+        logicalId,
+        location: resource.Properties?.[property]
+      })
+    );
+  }
+  return out;
+}
+function childStack(opts) {
+  const stackPath = [...opts.document.stackPath, opts.logicalId];
+  const report = (reason, detail, templateUrl) => ({
+    type: "unfollowed",
+    stack: {
+      declaredIn: opts.document.path,
+      stackPath,
+      templateUrl,
+      reason,
+      detail
+    }
+  });
+  const url = typeof opts.location === "string" ? opts.location.trim() : null;
+  if (url === null || url === "") {
+    return report(
+      "notALiteralPath",
+      "the template location is not a literal string",
+      null
+    );
+  }
+  if (url.includes("${")) {
+    return report(
+      "notALiteralPath",
+      `${url} holds a substitution nothing here can fill in`,
+      url
+    );
+  }
+  if (hasUrlScheme(url)) {
+    return report("remoteUrl", `${url} is not a path in this repository`, url);
+  }
+  if (stackPath.length > MAX_STACK_DEPTH) {
+    return report(
+      "depthLimit",
+      `nesting is deeper than ${MAX_STACK_DEPTH} stacks`,
+      url
+    );
+  }
+  const childPath = path2.resolve(path2.dirname(opts.document.path), url);
+  if (opts.ancestors.includes(childPath)) {
+    return report("cycle", `${url} is already open further up the tree`, url);
+  }
+  if (!fs2.existsSync(childPath)) {
+    return report("fileMissing", `${url} is not on disk`, url);
+  }
+  try {
+    return {
+      type: "document",
+      document: {
+        path: childPath,
+        stackPath,
+        template: loadCloudFormationTemplate(childPath)
+      }
+    };
+  } catch (err) {
+    return report(
+      "unreadable",
+      `${url} could not be parsed: ${err instanceof Error ? err.message : String(err)}`,
+      url
+    );
+  }
+}
+function hasUrlScheme(location) {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(location);
+}
+
 // src/serverlessFunctions.ts
+import { codeScopePath } from "@suss/ir-core";
 function parseHandler(handler) {
   const trimmed = handler.trim();
   const lastDot = trimmed.lastIndexOf(".");
@@ -231,24 +465,12 @@ function parseHandler(handler) {
     exportName: trimmed.slice(lastDot + 1)
   };
 }
-function normalizeCodeUri(raw) {
-  const trimmed = raw.replace(/^\.\//, "").replace(/\/+$/, "");
-  return trimmed === "" ? "." : trimmed;
-}
-function readGlobalsCodeUri(template) {
-  const fnGlobals = template.Globals?.Function;
-  if (fnGlobals === void 0) {
-    return null;
-  }
-  const codeUri = fnGlobals.CodeUri;
-  return typeof codeUri === "string" ? normalizeCodeUri(codeUri) : null;
-}
-function readCodeUri(resource, globalsCodeUri) {
+function readCodeUri(resource) {
   const codeUri = resource.Properties?.CodeUri;
-  if (typeof codeUri === "string") {
-    return normalizeCodeUri(codeUri);
+  if (typeof codeUri !== "string") {
+    return ".";
   }
-  return globalsCodeUri ?? ".";
+  return codeScopePath(codeUri) || ".";
 }
 function classifyEvents(events) {
   const httpRoutes = [];
@@ -268,8 +490,8 @@ function classifyEvents(events) {
     }
     const props = event.Properties ?? {};
     const method = String(props.Method ?? "").toUpperCase();
-    const path2 = String(props.Path ?? "");
-    if (method === "" || path2 === "") {
+    const path3 = String(props.Path ?? "");
+    if (method === "" || path3 === "") {
       nonHttpEvents.push({ eventId, eventType: type });
       continue;
     }
@@ -278,15 +500,14 @@ function classifyEvents(events) {
       eventId,
       eventType: type,
       method,
-      path: path2,
+      path: path3,
       apiId: apiRef
     });
   }
   return { httpRoutes, nonHttpEvents };
 }
 function readServerlessFunctions(template) {
-  const resources = template.Resources ?? {};
-  const globalsCodeUri = readGlobalsCodeUri(template);
+  const resources = resourcesWithGlobals(template);
   const out = [];
   for (const [logicalId, resource] of Object.entries(resources)) {
     if (resource.Type !== "AWS::Serverless::Function") {
@@ -308,7 +529,7 @@ function readServerlessFunctions(template) {
       handler: handlerRaw,
       modulePath: parsed.modulePath,
       exportName: parsed.exportName,
-      codeUri: readCodeUri(resource, globalsCodeUri),
+      codeUri: readCodeUri(resource),
       httpRoutes,
       nonHttpEvents
     });
@@ -317,9 +538,15 @@ function readServerlessFunctions(template) {
 }
 export {
   CLOUDFORMATION_YAML_TAGS,
+  MAX_STACK_DEPTH,
+  inheritedEnvVars,
   loadCloudFormationTemplate,
+  loadTemplateTree,
   parseHandler,
+  qualifiedLogicalId,
   readAppSyncResolvers,
   readServerlessFunctions,
-  refTarget
+  refTarget,
+  resourcesWithGlobals,
+  unfollowedStackMessage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/manifest-aws",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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,6 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@suss/ir-core": "0.1.1",
     "yaml": "^2.4.0"
   },
   "devDependencies": {