@suss/packs 0.35.1 → 0.36.0

package/dist/chunk-63BQSSQT.js

@@ -0,0 +1,544 @@
+// ../framework/aws-lambda/dist/index.js
+import { z } from "zod";
+import { compile, declarationsIn } from "@suss/recognize";
+import fs from "fs";
+import path from "path";
+import {
+  loadServerlessDocument,
+  SERVICE_FILE_NAMES,
+  translateService
+} from "@suss/contract-serverless";
+import {
+  loadTemplateTree,
+  qualifiedLogicalId,
+  readAppSyncResolvers,
+  readServerlessFunctions,
+  unfollowedStackMessage
+} from "@suss/manifest-aws";
+import { messageBusBinding, unitInvocationBinding } from "@suss/behavioral-ir";
+import { constructedFrom, unitInvokes } from "@suss/recognize";
+var TEMPLATE_NAMES = [
+  "template.yaml",
+  "template.yml",
+  "template.json",
+  ...SERVICE_FILE_NAMES
+];
+var isServiceFile = (file) => SERVICE_FILE_NAMES.includes(path.basename(file));
+function manifestTree(manifestPath) {
+  if (!isServiceFile(manifestPath)) {
+    return loadTemplateTree(manifestPath);
+  }
+  const translated = translateService(loadServerlessDocument(manifestPath));
+  return {
+    documents: [
+      {
+        path: path.resolve(manifestPath),
+        stackPath: [],
+        template: translated.functions
+      }
+    ],
+    unfollowed: []
+  };
+}
+function modulePathsOf(resolvedModule) {
+  const directory = path.dirname(resolvedModule);
+  const base = path.basename(resolvedModule);
+  if (!base.includes(".")) {
+    return [resolvedModule];
+  }
+  return [resolvedModule, path.join(directory, ...base.split("."))];
+}
+var dirToTemplate = /* @__PURE__ */ new Map();
+var templateToIndex = /* @__PURE__ */ new Map();
+var templateToDocuments = /* @__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();
+  const documents = /* @__PURE__ */ new Set([templatePath]);
+  try {
+    const tree = manifestTree(templatePath);
+    for (const document of tree.documents) {
+      documents.add(document.path);
+    }
+    for (const stack of tree.unfollowed) {
+      process.stderr.write(
+        `[suss] aws-lambda: ${unfollowedStackMessage(stack)}
+`
+      );
+      if (stack.templatePath !== null) {
+        documents.add(stack.templatePath);
+      }
+    }
+    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 entry = {
+          functionLogicalId: qualifiedLogicalId(
+            document.stackPath,
+            fn.logicalId
+          ),
+          graphqlFields: fieldsByFunction.get(fn.logicalId) ?? [],
+          handler: fn.handler,
+          exportName: fn.exportName,
+          httpRoutes: fn.httpRoutes,
+          nonHttpEvents: fn.nonHttpEvents
+        };
+        for (const modulePath of modulePathsOf(resolvedModule)) {
+          index.set(modulePath, [...index.get(modulePath) ?? [], entry]);
+        }
+      }
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[suss] aws-lambda: failed to read ${templatePath}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+  templateToIndex.set(templatePath, index);
+  templateToDocuments.set(templatePath, [...documents]);
+  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)) ?? [];
+}
+function templatesForFiles(files) {
+  const roots = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const templatePath = findTemplate(path.dirname(path.resolve(file)));
+    if (templatePath !== null) {
+      roots.add(templatePath);
+    }
+  }
+  const documents = /* @__PURE__ */ new Set();
+  for (const root of roots) {
+    indexForTemplate(root);
+    for (const document of templateToDocuments.get(root) ?? [root]) {
+      documents.add(document);
+    }
+  }
+  return [...documents];
+}
+var HTTP_TERMINALS = [
+  {
+    // `return { statusCode, body, headers? }`, at the return or in a helper
+    // the adapter follows. `body` contains the serialized payload, so
+    // `JSON.stringify(x)` is unwrapped 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 }` makes Lambda retry the records it
+    // lists. 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: {}
+  },
+  {
+    // An uncaught throw becomes a throw-output transition. API Gateway
+    // turns it into a 5xx, and the platform picks which one.
+    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 returning without an error.
+    // Without this pattern the handler has no terminal, so it gets no
+    // transition and everything it does is lost 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) {
+  const eventTypes = accountedEventTypes(entry);
+  const backs = typeFields(entry);
+  const wire = messageBusWire(eventTypes);
+  const unit = deployableUnit(entry);
+  return {
+    func,
+    kind: "handler",
+    name: `${entry.functionLogicalId}.${entry.exportName}`,
+    terminals: NON_HTTP_TERMINALS,
+    ...wire !== null ? { channelInfo: { messageBus: wire, channel: null } } : { invocationInfo: unit },
+    deployableUnit: unit,
+    metadata: {
+      [METADATA_NAMESPACE]: {
+        handler: entry.handler,
+        recognition: "recognized-not-http",
+        eventTypes,
+        ...backs.length > 0 ? { graphqlTypeFields: backs } : {}
+      }
+    }
+  };
+}
+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() {
+  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));
+      }
+    }
+    return units;
+  };
+}
+function lambdaEntryPoints(recognition) {
+  return (filePath) => handlersForFile(filePath).map((entry) => ({
+    name: entry.exportName,
+    units: [handlerUnit(entry, recognition)]
+  }));
+}
+function handlerUnit(entry, recognition) {
+  const eventTypes = [
+    ...entry.httpRoutes.map((route) => route.eventType),
+    ...entry.nonHttpEvents.map((event) => event.eventType)
+  ];
+  return {
+    kind: "handler",
+    name: `${entry.functionLogicalId}.${entry.exportName}`,
+    binding: handlerBinding(entry, eventTypes, recognition),
+    deployableUnit: deployableUnit(entry),
+    metadata: {
+      [METADATA_NAMESPACE]: {
+        handler: entry.handler,
+        recognition: "handler-entry",
+        eventTypes,
+        ...entry.graphqlFields.length > 0 ? { graphqlTypeFields: entry.graphqlFields } : {}
+      }
+    }
+  };
+}
+function handlerBinding(entry, eventTypes, recognition) {
+  const wire = entry.graphqlFields.length > 0 ? null : messageBusWire(eventTypes);
+  if (wire !== null) {
+    return messageBusBinding({ recognition, messageBus: wire, channel: null });
+  }
+  return unitInvocationBinding({ recognition, ...deployableUnit(entry) });
+}
+var LAMBDA = "@aws-sdk/client-lambda";
+var INSIDE_THE_COMMAND = (named) => ({
+  send: {
+    input: {
+      at: 0,
+      of: [
+        {
+          to: "argument",
+          at: 0,
+          origin: constructedFrom({ from: [LAMBDA], named })
+        }
+      ]
+    }
+  }
+});
+function invokeDeclarations() {
+  return [
+    unitInvokes({
+      platform: "lambda",
+      client: constructedFrom(LAMBDA),
+      named: ["FunctionName"],
+      payload: "Payload"
+    }).methods(INSIDE_THE_COMMAND(["InvokeCommand"])).example(
+      'client.send(new InvokeCommand({ FunctionName: "Worker", Payload: "{}" }))'
+    ),
+    unitInvokes({
+      platform: "lambda",
+      client: constructedFrom(LAMBDA),
+      named: ["FunctionName"],
+      payload: "InvokeArgs"
+    }).methods(INSIDE_THE_COMMAND(["InvokeAsyncCommand"])).example(
+      'client.send(new InvokeAsyncCommand({ FunctionName: "Worker", InvokeArgs: "{}" }))'
+    )
+  ];
+}
+var optionsSchema = z.object({}).strict();
+function awsLambdaFramework(_options = {}) {
+  const invokes = invokeDeclarations();
+  return {
+    name: "aws-lambda",
+    protocol: "http",
+    // The adapter cannot read Sentry's wrapper inside the library, so the
+    // pack declares that the handler is argument 0. A wrapper written in
+    // the project needs no entry, because the adapter reads its body.
+    transparentWrappers: [
+      { module: "@sentry/aws-serverless", name: "wrapHandler", argument: 0 }
+    ],
+    languages: ["typescript", "javascript"],
+    // The routing is in the template, so the callback finds handlers
+    // there and the pattern list stays empty.
+    discovery: [],
+    discoverUnits: awsLambdaDiscovery(),
+    // Discovery reads the templates, so they go into the cache key and an
+    // edited template makes the next run read the project again.
+    discoveryInputs: templatesForFiles,
+    // No import gate: a JavaScript handler imports nothing from
+    // `aws-lambda`, so the template acts as the gate. See the README.
+    // A unit that is not HTTP gets a longer list from the discovery
+    // callback in place of this one.
+    terminals: HTTP_TERMINALS,
+    inputMapping: {
+      type: "positionalParams",
+      params: [
+        { position: 0, role: "event" },
+        { position: 1, role: "context" }
+      ]
+    },
+    // A proxy integration passes the handler API Gateway's event, with the
+    // body as a string the handler parses. A read of the body records that
+    // the handler took all of it, with no field name.
+    requestSpelling: {
+      headers: { path: ["event", "headers"], saysWhichField: true },
+      query: {
+        path: ["event", "queryStringParameters"],
+        saysWhichField: true
+      },
+      params: { path: ["event", "pathParameters"], saysWhichField: true },
+      body: { path: ["event", "body"], saysWhichField: false }
+    },
+    // Powertools reads these variables from inside node_modules, where no
+    // walk over the project goes, so without this entry they look unread.
+    libraryEnvVars: [
+      {
+        module: "@aws-lambda-powertools/",
+        prefixes: ["POWERTOOLS_"]
+      }
+    ],
+    // A pack-level `requiresImport` would gate `discoverUnits` too. Each
+    // declaration already checks which SDK its command class came from.
+    invocationRecognizers: invokes.map(
+      (match) => compile(match.declared, "@suss/framework-aws-lambda")
+    ),
+    declarations: declarationsIn(invokes)
+  };
+}
+var declares = {
+  kind: "framework",
+  package: "@suss/framework-aws-lambda",
+  dependencies: [{ ecosystem: "npm", name: "@types/aws-lambda" }],
+  reads: "AWS Lambda HTTP handlers, paired with the routes a SAM template or serverless.yml declares."
+};
+function awsLambdaPython() {
+  const name = "aws-lambda-python";
+  return {
+    name,
+    protocol: "http",
+    discovery: [],
+    discoveryInputs: templatesForFiles,
+    entryPoints: lambdaEntryPoints(name),
+    // Powertools reads these from its own installed package.
+    libraryEnvVars: [
+      { module: "aws_lambda_powertools", prefixes: ["POWERTOOLS_"] }
+    ]
+  };
+}
+var declaresPython = {
+  kind: "framework",
+  package: "@suss/framework-aws-lambda",
+  dependencies: [],
+  reads: "AWS Lambda handlers written in Python, found from the Handler a SAM template or serverless.yml gives each function."
+};
+function awsLambdaRuby() {
+  const name = "aws-lambda-ruby";
+  return {
+    name,
+    protocol: "http",
+    discovery: [],
+    discoveryInputs: templatesForFiles,
+    entryPoints: lambdaEntryPoints(name)
+  };
+}
+var declaresRuby = {
+  kind: "framework",
+  package: "@suss/framework-aws-lambda",
+  dependencies: [],
+  reads: "AWS Lambda handlers written in Ruby, found from the Handler a SAM template or serverless.yml gives each function, including a class method written `file.Module::Class.method`."
+};
+var index_default = awsLambdaFramework;
+
+export {
+  optionsSchema,
+  declares,
+  awsLambdaPython,
+  declaresPython,
+  awsLambdaRuby,
+  declaresRuby,
+  index_default
+};

package/dist/graphql-ruby.js

@@ -4,11 +4,11 @@ import { z } from "zod";
 import { SCALAR_SHAPES } from "@suss/contract-graphql";
 var optionsSchema = z.object({
   /**
-   * The directory the pack looks under for the class a `mutation:` or
-   * `resolver:` field references, for example
-   * `path.join(repoRoot, "app/graphql")`. A relative path resolves
-   * against `configDirectory`, or the working directory when that is
-   * unset.
+   * The directory the pack looks under for a class a `mutation:` or
+   * `resolver:` field references when no file in the run declares it,
+   * for example `path.join(repoRoot, "app/graphql")`. A relative path
+   * resolves against `configDirectory`, or the working directory when
+   * that is unset.
    */
   root: z.string(),
   /**
@@ -29,6 +29,7 @@ var optionsSchema = z.object({
 var GRAPHQL_RUBY_ROOT_CLASS_NAMES = [
   "GraphQL::Schema::Object",
   "GraphQL::Schema::Mutation",
+  "GraphQL::Schema::RelayClassicMutation",
   "GraphQL::Schema::Resolver",
   "GraphQL::Schema::Interface",
   "GraphQL::Schema::InputObject",
@@ -69,6 +70,14 @@ function graphqlRubyFramework(options) {
     argumentCallName: "argument",
     wiringKeywords: ["mutation", "resolver"],
     resolverMethodName: "resolve",
+    resolverMethodKeyword: "resolver_method",
+    // A Mutation or Resolver runs ready?, then authorized?, then resolve.
+    // A hook that returns false, or [false, payload], stops the field,
+    // and the payload comes back in its place.
+    resolverHooks: {
+      methods: ["ready?", "authorized?"],
+      answerIsListHead: true
+    },
     ancestryRootClassNames: [...GRAPHQL_RUBY_ROOT_CLASS_NAMES],
     requiredKeyword: "required",
     // graphql-ruby registers an argument as required unless the call
@@ -124,13 +133,14 @@ var declares = {
   kind: "framework",
   package: "@suss/framework-graphql-ruby",
   dependencies: [{ ecosystem: "rubygems", name: "graphql" }],
-  reads: "graphql-ruby class-based field DSL (Ruby). The pack follows `mutation:` and `resolver:` wiring one hop out to what the referenced class declares. It also records the model a resolver reads through `dataloader`, when a storage pack in the run recognizes that model.",
+  reads: "graphql-ruby class-based field DSL (Ruby). The pack follows `mutation:` and `resolver:` wiring to the referenced class, wherever the run declares it, and reads its arguments, its payload, its `resolve` method and the `ready?` and `authorized?` hooks that run first. It follows `resolver_method:` to the type's own method. It also records the model a resolver reads through `dataloader`, when a storage pack in the run recognizes that model.",
   configuration: {
     file: "suss.graphql-ruby.json",
     example: { root: "app/graphql" },
     required: true,
-    why: "the directory a field's wired class is looked up under, read relative to this file. A Rails app generated by the library keeps its types and mutations under app/graphql.",
-    defaults: { root: "app/graphql" }
+    why: "the directory a field's wired class is looked up under when no file in the run declares it, read relative to this file. A Rails app generated by the library keeps its types and mutations under app/graphql.",
+    defaults: { root: "app/graphql" },
+    paths: ["root"]
   }
 };
 var index_default = graphqlRubyFramework;