@suss/packs 0.11.0

package/dist/aws-lambda.js

@@ -0,0 +1,382 @@
+// ../framework/aws-lambda/dist/index.js
+import fs from "fs";
+import path from "path";
+import {
+  loadTemplateTree,
+  qualifiedLogicalId,
+  readAppSyncResolvers,
+  readServerlessFunctions,
+  unfollowedStackMessage
+} from "@suss/manifest-aws";
+var TEMPLATE_NAMES = ["template.yaml", "template.yml", "template.json"];
+var dirToTemplate = /* @__PURE__ */ new Map();
+var templateToIndex = /* @__PURE__ */ new Map();
+function findTemplate(startDir) {
+  const chain = [];
+  let dir = startDir;
+  while (true) {
+    const cached = dirToTemplate.get(dir);
+    if (cached !== void 0) {
+      for (const d of chain) {
+        dirToTemplate.set(d, cached);
+      }
+      return cached;
+    }
+    chain.push(dir);
+    const found = TEMPLATE_NAMES.map((name) => path.join(dir, name)).find(
+      (candidate) => fs.existsSync(candidate)
+    ) ?? null;
+    if (found !== null) {
+      for (const d of chain) {
+        dirToTemplate.set(d, found);
+      }
+      return found;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      for (const d of chain) {
+        dirToTemplate.set(d, null);
+      }
+      return null;
+    }
+    dir = parent;
+  }
+}
+function indexForTemplate(templatePath) {
+  const cached = templateToIndex.get(templatePath);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const index = /* @__PURE__ */ new Map();
+  try {
+    const tree = loadTemplateTree(templatePath);
+    for (const stack of tree.unfollowed) {
+      process.stderr.write(
+        `[suss] aws-lambda: ${unfollowedStackMessage(stack)}
+`
+      );
+    }
+    for (const document of tree.documents) {
+      const templateDir = path.dirname(document.path);
+      const fieldsByFunction = groupFieldsByFunction(
+        readAppSyncResolvers(document.template)
+      );
+      for (const fn of readServerlessFunctions(document.template)) {
+        const resolvedModule = path.resolve(
+          templateDir,
+          fn.codeUri,
+          fn.modulePath
+        );
+        const list = index.get(resolvedModule) ?? [];
+        list.push({
+          functionLogicalId: qualifiedLogicalId(
+            document.stackPath,
+            fn.logicalId
+          ),
+          graphqlFields: fieldsByFunction.get(fn.logicalId) ?? [],
+          handler: fn.handler,
+          exportName: fn.exportName,
+          httpRoutes: fn.httpRoutes,
+          nonHttpEvents: fn.nonHttpEvents
+        });
+        index.set(resolvedModule, list);
+      }
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[suss] aws-lambda: failed to read ${templatePath}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+  templateToIndex.set(templatePath, index);
+  return index;
+}
+function toModulePath(filePath) {
+  const resolved = path.resolve(filePath);
+  const ext = path.extname(resolved);
+  return ext === "" ? resolved : resolved.slice(0, -ext.length);
+}
+function groupFieldsByFunction(bindings) {
+  const out = /* @__PURE__ */ new Map();
+  for (const binding of bindings) {
+    for (const logicalId of binding.lambdaFunctionLogicalIds) {
+      const fields = out.get(logicalId) ?? [];
+      fields.push({ typeName: binding.typeName, fieldName: binding.fieldName });
+      out.set(logicalId, fields);
+    }
+  }
+  return out;
+}
+function handlersForFile(filePath) {
+  const templatePath = findTemplate(path.dirname(path.resolve(filePath)));
+  if (templatePath === null) {
+    return [];
+  }
+  const index = indexForTemplate(templatePath);
+  return index.get(toModulePath(filePath)) ?? [];
+}
+var HTTP_TERMINALS = [
+  {
+    // `return { statusCode, body, headers? }`, written at the return site or
+    // built by a helper the adapter follows into. `body` contains the
+    // serialized payload, so unwrap `JSON.stringify(x)` to the shape of `x`.
+    kind: "response",
+    match: { type: "returnShape", requiredProperties: ["statusCode"] },
+    extraction: {
+      statusCode: { from: "property", name: "statusCode" },
+      body: { from: "property", name: "body", unwrapJsonStringify: true }
+    }
+  },
+  {
+    // `return { batchItemFailures }`, which is how a consumer tells Lambda
+    // which records to retry and which to drop. Lambda defines this shape, so
+    // the pack can match on it, the same way it matches the envelope above.
+    kind: "return",
+    match: {
+      type: "returnShape",
+      requiredProperties: ["batchItemFailures"]
+    },
+    extraction: {}
+  },
+  {
+    // `throw new SomeError(...)`. An uncaught throw becomes a
+    // throw-output transition; API Gateway maps it to a 5xx, but the
+    // specific status is the platform's, not the handler's.
+    kind: "throw",
+    match: { type: "throwExpression" },
+    extraction: {}
+  }
+];
+var NON_HTTP_TERMINALS = [
+  ...HTTP_TERMINALS,
+  {
+    kind: "return",
+    match: { type: "returnShape" },
+    extraction: {}
+  },
+  {
+    // A queue consumer acknowledges a batch by not throwing: it processes the
+    // records, falls off the end, and Lambda reads the absence of an error as
+    // the ack. Without this the handler has no terminal, so it gets no
+    // transition, and everything it does goes with it.
+    kind: "return",
+    match: { type: "functionFallthrough" },
+    extraction: {}
+  }
+];
+var METADATA_NAMESPACE = "awsLambda";
+function deployableUnit(entry) {
+  return { deploymentTarget: "lambda", instanceName: entry.functionLogicalId };
+}
+function httpRouteUnits(entry, func) {
+  const units = [];
+  for (const route of entry.httpRoutes) {
+    if (route.method === "ANY") {
+      continue;
+    }
+    units.push({
+      func,
+      kind: "handler",
+      name: `${entry.functionLogicalId}.${entry.exportName}`,
+      routeInfo: { method: route.method, path: route.path },
+      deployableUnit: deployableUnit(entry),
+      metadata: {
+        [METADATA_NAMESPACE]: {
+          handler: entry.handler,
+          eventId: route.eventId,
+          apiEventType: route.eventType
+        }
+      }
+    });
+  }
+  return units;
+}
+var OPERATION_ROOT_TYPES = ["Query", "Mutation", "Subscription"];
+function operationFields(entry) {
+  return entry.graphqlFields.filter(
+    (f) => OPERATION_ROOT_TYPES.includes(f.typeName)
+  );
+}
+function typeFields(entry) {
+  return entry.graphqlFields.filter(
+    (f) => !OPERATION_ROOT_TYPES.includes(f.typeName)
+  );
+}
+function graphqlResolverUnits(entry, func) {
+  return operationFields(entry).map((field) => ({
+    func,
+    kind: "handler",
+    name: `${entry.functionLogicalId}.${entry.exportName}`,
+    resolverInfo: { typeName: field.typeName, fieldName: field.fieldName },
+    deployableUnit: deployableUnit(entry),
+    metadata: {
+      [METADATA_NAMESPACE]: {
+        handler: entry.handler,
+        recognition: "appsync-resolver"
+      }
+    }
+  }));
+}
+function accountingUnit(entry, func, channel) {
+  const eventTypes = accountedEventTypes(entry);
+  const backs = typeFields(entry);
+  const wire = channel !== null ? "aws_sqs" : messageBusWire(eventTypes);
+  return {
+    func,
+    kind: "handler",
+    name: `${entry.functionLogicalId}.${entry.exportName}`,
+    terminals: NON_HTTP_TERMINALS,
+    ...wire !== null ? { channelInfo: { messageBus: wire, channel } } : {},
+    deployableUnit: deployableUnit(entry),
+    metadata: {
+      [METADATA_NAMESPACE]: {
+        handler: entry.handler,
+        recognition: "recognized-not-http",
+        eventTypes,
+        ...backs.length > 0 ? { graphqlTypeFields: backs } : {}
+      }
+    }
+  };
+}
+function subjectChannel(entry, sf, tsCtx, factories) {
+  const consumesSqs = entry.nonHttpEvents.some((e) => e.eventType === "SQS");
+  if (!consumesSqs) {
+    return null;
+  }
+  for (const factory of factories) {
+    const subject = tsCtx.exportedCallConfigString(
+      sf,
+      entry.exportName,
+      factory
+    );
+    if (subject !== null) {
+      return subject;
+    }
+  }
+  return null;
+}
+var EVENT_WIRES = {
+  SQS: "aws_sqs",
+  SNS: "aws.sns",
+  S3: "s3",
+  Schedule: "eventbridge",
+  ScheduleV2: "eventbridge",
+  EventBridgeRule: "eventbridge",
+  CloudWatchEvent: "eventbridge"
+};
+function messageBusWire(eventTypes) {
+  const wires = new Set(
+    eventTypes.map((type) => EVENT_WIRES[type] ?? null)
+  );
+  if (wires.size !== 1) {
+    return null;
+  }
+  const [wire] = wires;
+  return wire ?? null;
+}
+function accountedEventTypes(entry) {
+  return [
+    ...entry.nonHttpEvents.map((e) => e.eventType),
+    ...entry.httpRoutes.filter((r) => r.method === "ANY").map((r) => r.eventType)
+  ];
+}
+function hasBindableRoute(entry) {
+  return entry.httpRoutes.some((r) => r.method !== "ANY");
+}
+function awsLambdaDiscovery(subjectFactories = []) {
+  return (sourceFile, ctx) => {
+    const sf = sourceFile;
+    const tsCtx = ctx;
+    const filePath = tsCtx.getFilePath(sf);
+    const entries = handlersForFile(filePath);
+    if (entries.length === 0) {
+      return [];
+    }
+    const exported = /* @__PURE__ */ new Map();
+    for (const { name, func } of tsCtx.exportedFunctions(sf)) {
+      exported.set(name, func);
+    }
+    const units = [];
+    for (const entry of entries) {
+      const func = exported.get(entry.exportName);
+      if (func === void 0) {
+        continue;
+      }
+      units.push(...httpRouteUnits(entry, func));
+      units.push(...graphqlResolverUnits(entry, func));
+      const unaccountedEvents = accountedEventTypes(entry);
+      const boundToNothing = !hasBindableRoute(entry) && operationFields(entry).length === 0;
+      if (unaccountedEvents.length > 0 || boundToNothing) {
+        units.push(
+          accountingUnit(
+            entry,
+            func,
+            subjectChannel(entry, sf, tsCtx, subjectFactories)
+          )
+        );
+      }
+    }
+    return units;
+  };
+}
+function awsLambdaFramework(options = {}) {
+  return {
+    name: "aws-lambda",
+    protocol: "http",
+    // Sentry's wrapper is a library call whose body the adapter cannot
+    // read, so the pack states the judgment: the handler is argument 0.
+    // Project-local wrappers need no declaration; the adapter derives
+    // those by reading the factory body.
+    transparentWrappers: [
+      {
+        callee: "Sentry.wrapHandler",
+        argument: 0,
+        module: "@sentry/aws-serverless"
+      }
+    ],
+    languages: ["typescript", "javascript"],
+    // No data-driven discovery: routing lives in the SAM/CFN template,
+    // not in code. The callback resolves handlers against the template.
+    discovery: [],
+    discoverUnits: awsLambdaDiscovery(options.subjectFactories ?? []),
+    // No import gate, on purpose.
+    //
+    // A TypeScript handler writes `import type { APIGatewayProxyHandlerV2 }
+    // from "aws-lambda"`, which TypeScript resolves to
+    // `@types/aws-lambda`, to annotate its export. A JavaScript handler
+    // has nothing to annotate and writes no such import. Gating
+    // discovery on it therefore meant "TypeScript handlers that bothered
+    // to annotate", and every JavaScript Lambda service extracted
+    // nothing.
+    //
+    // The SAM template is the gate instead, and a better one, because it
+    // says which handlers outright. `discoverUnits` looks each file up in
+    // the template reachable from it, and a directory with no template
+    // resolves to null once and stays memoized.
+    // Route units extract against these. Non-HTTP accounting units get their
+    // own wider list, attached per unit by the discovery callback.
+    terminals: HTTP_TERMINALS,
+    // Lambda's handler signature is `(event, context, callback?)`. The
+    // HTTP request data (path params, query, body) lives on `event`;
+    // decomposing it into typed inputs is a follow-up.
+    inputMapping: {
+      type: "positionalParams",
+      params: [
+        { position: 0, role: "event" },
+        { position: 1, role: "context" }
+      ]
+    },
+    // The powertools read their configuration from inside node_modules,
+    // so a template that declares these has a reader no walk ever sees.
+    libraryEnvVars: [
+      {
+        module: "@aws-lambda-powertools/",
+        prefixes: ["POWERTOOLS_"]
+      }
+    ]
+  };
+}
+var index_default = awsLambdaFramework;
+export {
+  index_default as default
+};

package/dist/aws-s3.d.ts

@@ -0,0 +1 @@
+export { default } from '@suss/framework-aws-s3';

package/dist/aws-s3.js

@@ -0,0 +1,120 @@
+// ../framework/aws-s3/dist/index.js
+import { Node as N } from "ts-morph";
+import { readName, rootIdentifier } from "@suss/adapter-typescript";
+import { storageBinding } from "@suss/behavioral-ir";
+var RECOGNITION = "@suss/framework-aws-s3";
+var COMMAND_MODULE = "@aws-sdk/client-s3";
+var COMMANDS = {
+  GetObjectCommand: "read",
+  HeadObjectCommand: "read",
+  ListObjectsV2Command: "read",
+  ListObjectsCommand: "read",
+  PutObjectCommand: "write",
+  DeleteObjectCommand: "write",
+  DeleteObjectsCommand: "write",
+  CopyObjectCommand: "write",
+  // A large object goes up in parts, and each command in that sequence
+  // writes the same object.
+  CreateMultipartUploadCommand: "write",
+  UploadPartCommand: "write",
+  CompleteMultipartUploadCommand: "write",
+  AbortMultipartUploadCommand: "write"
+};
+function s3Recognizer(call, ctx) {
+  const callNode = call;
+  const recognizerCtx = ctx;
+  const resolve = recognizerCtx.resolveWrittenValue ?? (() => null);
+  const built = commandArgument(callNode, resolve);
+  if (built === null) {
+    return null;
+  }
+  const ctorExpr = built.getExpression();
+  const commandName = N.isPropertyAccessExpression(ctorExpr) ? ctorExpr.getName() : ctorExpr.getText();
+  const kind = COMMANDS[commandName];
+  if (kind === void 0 || !fromS3Module(ctorExpr, recognizerCtx)) {
+    return null;
+  }
+  const input = built.getArguments()[0];
+  if (input === void 0 || !N.isObjectLiteralExpression(input)) {
+    return null;
+  }
+  const key = nameOfProperty(input, "Key", resolve);
+  const prefix = nameOfProperty(input, "Prefix", resolve);
+  const addressed = key ?? prefix;
+  return [
+    {
+      type: "interaction",
+      binding: storageBinding({
+        recognition: RECOGNITION,
+        storageSystem: "s3",
+        transport: "aws-sdk",
+        scope: "default",
+        container: nameOfProperty(input, "Bucket", resolve),
+        accessPath: null
+      }),
+      callee: callNode.getExpression().getText(),
+      interaction: {
+        class: "storage-access",
+        kind,
+        // An object has no fields, so a call says nothing about any.
+        fields: [],
+        operation: commandName,
+        ...addressed !== null ? { selector: [addressed] } : {}
+      }
+    }
+  ];
+}
+function commandArgument(call, resolve) {
+  for (const arg of call.getArguments()) {
+    if (N.isNewExpression(arg)) {
+      return arg;
+    }
+    if (!N.isIdentifier(arg) || !typedAsCommand(arg)) {
+      continue;
+    }
+    const written = resolve(arg);
+    if (written !== null && N.isNewExpression(written)) {
+      return written;
+    }
+  }
+  return null;
+}
+function typedAsCommand(value) {
+  const declared = value.getType().getSymbol();
+  return declared !== void 0 && COMMANDS[declared.getName()] !== void 0;
+}
+function fromS3Module(ctorExpr, ctx) {
+  const target = N.isPropertyAccessExpression(ctorExpr) ? rootIdentifier(ctorExpr) : ctorExpr;
+  return target !== null && ctx.isImportedFrom(target, COMMAND_MODULE);
+}
+function nameOfProperty(input, name, resolve) {
+  const written = property(input, name);
+  return written === null ? null : readName(written, { resolve, unsettled: "reference" });
+}
+function property(input, name) {
+  if (!N.isObjectLiteralExpression(input)) {
+    return null;
+  }
+  for (const prop of input.getProperties()) {
+    if (N.isPropertyAssignment(prop) && prop.getName() === name) {
+      return prop.getInitializer() ?? null;
+    }
+  }
+  return null;
+}
+function s3Framework() {
+  return {
+    name: "aws-s3",
+    protocol: "s3",
+    languages: ["typescript", "javascript"],
+    discovery: [],
+    terminals: [],
+    inputMapping: { type: "positionalParams", params: [] },
+    requiresImport: [COMMAND_MODULE],
+    invocationRecognizers: [s3Recognizer]
+  };
+}
+var index_default = s3Framework;
+export {
+  index_default as default
+};

package/dist/aws-sqs.d.ts

@@ -0,0 +1 @@
+export { default } from '@suss/framework-aws-sqs';