@suss/packs 0.32.0 → 0.33.0

package/dist/node.js

@@ -1,34 +1,302 @@
 // ../runtime/node/dist/index.js
 import { z } from "zod";
 import {
-  Node as N,
-  SyntaxKind
+  Node as N2,
+  SyntaxKind as SyntaxKind2
 } from "ts-morph";
 import {
+  declarationsBehind,
   findEnclosingFunction,
   functionTargetOf,
   isDefaultedAt,
   stringValueOf,
-  symbolBehind
+  symbolBehind,
+  toFunctionRoot
 } from "@suss/adapter-typescript";
 import { runtimeConfigBinding } from "@suss/behavioral-ir";
+import { Node as N, SyntaxKind } from "ts-morph";
+import {
+  objectLiteralOf,
+  propertiesOf,
+  propertyNameOf,
+  propertyOf,
+  propertyValueOf,
+  writtenNodeOf
+} from "@suss/adapter-typescript";
 import { Node } from "ts-morph";
-import { runtimeConfigBinding as runtimeConfigBinding2 } from "@suss/behavioral-ir";
 import {
   Node as Node2
 } from "ts-morph";
-import { runtimeConfigBinding as runtimeConfigBinding3 } from "@suss/behavioral-ir";
 import {
   Node as Node3
 } from "ts-morph";
 import { functionCallBinding } from "@suss/behavioral-ir";
+var RECOGNITION = "@suss/runtime-node";
+function configBinding(where) {
+  return runtimeConfigBinding({ recognition: RECOGNITION, ...where });
+}
+function opaqueRuntimeRead(callee) {
+  return {
+    type: "interaction",
+    binding: configBinding({}),
+    callee,
+    interaction: { class: "metadata-read", name: callee }
+  };
+}
+var SCHEMA_READERS = [
+  // cleanEnv(process.env, { PORT: port({ default: 8080 }), DB_NAME: str() })
+  {
+    modules: ["envalid"],
+    calls: ["cleanEnv"],
+    environment: { in: "argument", at: 0 },
+    schema: { in: "argument", at: 1 }
+  },
+  // parseEnv(process.env, { PORT: z.number().default(8080) })
+  {
+    modules: ["znv"],
+    calls: ["parseEnv"],
+    environment: { in: "argument", at: 0 },
+    schema: { in: "argument", at: 1 }
+  },
+  // createEnv({ server: { DB_NAME: z.string() }, runtimeEnv: process.env })
+  {
+    modules: ["@t3-oss/env-core", "@t3-oss/env-nextjs"],
+    calls: ["createEnv"],
+    environment: { in: "property", at: 0, named: "runtimeEnv" },
+    schema: { in: "properties", at: 0, named: ["server", "client", "shared"] }
+  },
+  // v.parse(v.object({ DB_NAME: v.string() }), process.env)
+  {
+    modules: ["valibot"],
+    calls: ["parse", "safeParse", "parseAsync", "safeParseAsync"],
+    environment: { in: "argument", at: 1 },
+    schema: { in: "builtAt", at: 0, builders: ["object"] }
+  },
+  // Env.parse(process.env), where Env came from z.object({ ... })
+  {
+    modules: ["zod"],
+    calls: ["parse", "safeParse", "parseAsync", "safeParseAsync"],
+    onSchema: true,
+    environment: { in: "argument", at: 0 },
+    schema: { in: "builtAtReceiver", builders: ["object"] }
+  }
+];
+var PARSE_CALL_NAMES = new Set(
+  SCHEMA_READERS.flatMap((reader) => [...reader.calls])
+);
+var MODULES_MENTIONED = /* @__PURE__ */ new WeakMap();
+function writtenCalleeName(callee) {
+  if (N.isIdentifier(callee)) {
+    return callee.getText();
+  }
+  return N.isPropertyAccessExpression(callee) ? callee.getName() : null;
+}
+function modulesMentionedIn(sourceFile) {
+  const remembered = MODULES_MENTIONED.get(sourceFile);
+  if (remembered !== void 0) {
+    return remembered;
+  }
+  const text = sourceFile.getFullText();
+  const found = new Set(
+    SCHEMA_READERS.flatMap((reader) => [...reader.modules]).filter(
+      (module) => text.includes(module)
+    )
+  );
+  MODULES_MENTIONED.set(sourceFile, found);
+  return found;
+}
+function readerCouldFire(call, reader, written) {
+  if (!reader.calls.includes(written)) {
+    return false;
+  }
+  if (reader.onSchema === true) {
+    return true;
+  }
+  const mentioned = modulesMentionedIn(call.getSourceFile());
+  return reader.modules.some((module) => mentioned.has(module));
+}
+function schemaEnvReads(call, resolution) {
+  if (resolution === void 0) {
+    return [];
+  }
+  const written = writtenCalleeName(call.getExpression());
+  if (written === null || !PARSE_CALL_NAMES.has(written)) {
+    return [];
+  }
+  for (const reader of SCHEMA_READERS) {
+    if (!readerCouldFire(call, reader, written) || !callMatches(call, reader, resolution)) {
+      continue;
+    }
+    const environment = environmentArgument(call, reader, resolution);
+    if (environment === null || !resolution.isEnvironmentValue(environment)) {
+      continue;
+    }
+    const reads = readsFromSchema(call, reader, resolution);
+    if (reads.length > 0) {
+      return reads;
+    }
+  }
+  return [];
+}
+function callMatches(call, reader, resolution) {
+  const callee = call.getExpression();
+  if (reader.onSchema === true) {
+    return N.isPropertyAccessExpression(callee) && reader.calls.includes(callee.getName());
+  }
+  const name = moduleCallName(callee, reader.modules, resolution);
+  return name !== null && reader.calls.includes(name);
+}
+function moduleCallName(callee, modules, resolution) {
+  if (N.isIdentifier(callee)) {
+    return resolution.importedNamesOf(callee, [...modules])[0] ?? null;
+  }
+  if (!N.isPropertyAccessExpression(callee)) {
+    return null;
+  }
+  const fromPackage = resolution.importedNamesOf(callee.getExpression(), [
+    ...modules
+  ]);
+  return fromPackage.length > 0 ? callee.getName() : null;
+}
+function environmentArgument(call, reader, resolution) {
+  const at = call.getArguments()[reader.environment.at];
+  if (at === void 0) {
+    return null;
+  }
+  if (reader.environment.in === "argument") {
+    return at;
+  }
+  return namedValue(at, reader.environment.named, resolution);
+}
+function readsFromSchema(call, reader, resolution) {
+  return schemaLiterals(call, reader, resolution).flatMap(
+    (literal) => keysOf(literal, resolution)
+  );
+}
+function schemaLiterals(call, reader, resolution) {
+  const { schema } = reader;
+  if (schema.in === "builtAtReceiver") {
+    const callee = call.getExpression();
+    if (!N.isPropertyAccessExpression(callee)) {
+      return [];
+    }
+    return builtSchema(
+      callee.getExpression(),
+      reader.modules,
+      schema.builders,
+      resolution
+    );
+  }
+  const at = call.getArguments()[schema.at];
+  if (at === void 0) {
+    return [];
+  }
+  if (schema.in === "argument") {
+    return [at];
+  }
+  if (schema.in === "builtAt") {
+    return builtSchema(at, reader.modules, schema.builders, resolution);
+  }
+  return schema.named.map((name) => namedValue(at, name, resolution)).filter((found) => found !== null);
+}
+function namedValue(value, named, resolution) {
+  const object = objectLiteralOf(value, resolution);
+  return object === null ? null : propertyOf(object, named, resolution);
+}
+function builtSchema(value, modules, builders, resolution) {
+  const built = chainRoot(writtenCallOf(value, resolution));
+  if (built === null) {
+    return [];
+  }
+  const name = moduleCallName(built.getExpression(), modules, resolution);
+  if (name === null || !builders.includes(name)) {
+    return [];
+  }
+  const literal = built.getArguments()[0];
+  return literal === void 0 ? [] : [literal];
+}
+function writtenCallOf(value, resolution) {
+  const written = writtenNodeOf(value, resolution);
+  return written !== null && N.isCallExpression(written) ? written : null;
+}
+function chainRoot(call) {
+  let at = call;
+  while (at !== null) {
+    const callee = at.getExpression();
+    if (!N.isPropertyAccessExpression(callee)) {
+      return at;
+    }
+    const receiver = callee.getExpression();
+    if (!N.isCallExpression(receiver)) {
+      return at;
+    }
+    at = receiver;
+  }
+  return null;
+}
+function keysOf(literal, resolution) {
+  const object = objectLiteralOf(literal, resolution);
+  if (object === null) {
+    return [];
+  }
+  const reads = [];
+  for (const property of propertiesOf(object, resolution)) {
+    const name = propertyNameOf(property);
+    if (name === null || name.length === 0) {
+      continue;
+    }
+    const value = propertyValueOf(property);
+    reads.push({ name, defaulted: value !== null && suppliesValue(value) });
+  }
+  return reads;
+}
+var DEFAULTING_CALLS = /* @__PURE__ */ new Set([
+  "default",
+  "optional",
+  "nullish",
+  "catch",
+  "or"
+]);
+var DEFAULTING_OPTIONS = /* @__PURE__ */ new Set(["default", "devDefault"]);
+function suppliesValue(value) {
+  let found = defaults(value);
+  value.forEachDescendant((node, traversal) => {
+    if (!defaults(node)) {
+      return;
+    }
+    found = true;
+    traversal.stop();
+  });
+  return found;
+}
+function defaults(node) {
+  if (N.isCallExpression(node)) {
+    const written = writtenCalleeName(node.getExpression());
+    return written !== null && DEFAULTING_CALLS.has(written);
+  }
+  if (!N.isPropertyAssignment(node)) {
+    return false;
+  }
+  const option = propertyNameOf(node);
+  return option !== null && DEFAULTING_OPTIONS.has(option);
+}
+var SCHEMA_READS_INSIDE = /* @__PURE__ */ new WeakMap();
+function schemaEnvReadsInside(callee, resolution) {
+  const remembered = SCHEMA_READS_INSIDE.get(callee);
+  if (remembered !== void 0) {
+    return remembered;
+  }
+  const found = callee.getDescendantsOfKind(SyntaxKind.CallExpression).flatMap((inner) => schemaEnvReads(inner, resolution));
+  SCHEMA_READS_INSIDE.set(callee, found);
+  return found;
+}
 var readName = (name) => `process.env.${name}`;
 function isProcessEnv(node) {
-  if (!N.isPropertyAccessExpression(node) || node.getName() !== "env") {
+  if (!N2.isPropertyAccessExpression(node) || node.getName() !== "env") {
     return false;
   }
   const root = node.getExpression();
-  return N.isIdentifier(root) && root.getText() === "process";
+  return N2.isIdentifier(root) && root.getText() === "process";
 }
 function dottedRead(node) {
   if (!isProcessEnv(node.getExpression())) {
@@ -41,14 +309,14 @@ function bracketRead(access, resolution) {
   if (argument === void 0) {
     return [];
   }
-  if (N.isStringLiteral(argument) || N.isNoSubstitutionTemplateLiteral(argument)) {
+  if (N2.isStringLiteral(argument) || N2.isNoSubstitutionTemplateLiteral(argument)) {
     const name = argument.getLiteralValue();
     if (name.length === 0) {
       return [];
     }
     return [{ name, defaulted: isDefaultedAt(access), node: access }];
   }
-  if (N.isIdentifier(argument)) {
+  if (N2.isIdentifier(argument)) {
     return readsThroughParameter(access, argument, resolution);
   }
   return [];
@@ -100,7 +368,7 @@ function callerLiteralReads(access, index, resolution) {
   return reads;
 }
 function forwardedParameter(passed, call) {
-  if (!N.isIdentifier(passed)) {
+  if (!N2.isIdentifier(passed)) {
     return null;
   }
   const caller = findEnclosingFunction(call);
@@ -108,7 +376,7 @@ function forwardedParameter(passed, call) {
     return null;
   }
   const behind = symbolBehind(passed)?.getValueDeclaration();
-  if (behind === void 0 || !N.isParameterDeclaration(behind)) {
+  if (behind === void 0 || !N2.isParameterDeclaration(behind)) {
     return null;
   }
   return behind.getParent() === caller ? behind : null;
@@ -118,10 +386,10 @@ function bindingRead(element) {
     return [];
   }
   const named = element.getPropertyNameNode() ?? element.getNameNode();
-  if (!(N.isIdentifier(named) || N.isStringLiteral(named))) {
+  if (!(N2.isIdentifier(named) || N2.isStringLiteral(named))) {
     return [];
   }
-  const name = N.isIdentifier(named) ? named.getText() : named.getLiteralValue();
+  const name = N2.isIdentifier(named) ? named.getText() : named.getLiteralValue();
   if (name.length === 0) {
     return [];
   }
@@ -137,32 +405,33 @@ function bindingRead(element) {
 }
 function destructuredReads(declaration) {
   const pattern = declaration.getNameNode();
-  if (!N.isObjectBindingPattern(pattern)) {
+  if (!N2.isObjectBindingPattern(pattern)) {
     return [];
   }
   return pattern.getElements().flatMap(bindingRead);
 }
 function readsThroughEnvObject(envNode, resolution) {
   const parent = envNode.getParent();
-  if (N.isElementAccessExpression(parent)) {
+  if (N2.isElementAccessExpression(parent)) {
     return bracketRead(parent, resolution);
   }
-  if (N.isVariableDeclaration(parent)) {
+  if (N2.isVariableDeclaration(parent)) {
     return destructuredReads(parent);
   }
   return [];
 }
 function envReadsAt(node, resolution) {
-  if (N.isCallExpression(node)) {
-    return readsThroughHelperCall(node, resolution);
+  if (N2.isCallExpression(node)) {
+    const parsed = anchoredAt(schemaEnvReads(node, resolution), node);
+    return parsed.length > 0 ? parsed : readsThroughHelperCall(node, resolution);
   }
-  if (!N.isPropertyAccessExpression(node)) {
+  if (!N2.isPropertyAccessExpression(node)) {
     return [];
   }
   return isProcessEnv(node) ? readsThroughEnvObject(node, resolution) : dottedRead(node);
 }
 function readsThroughHelperCall(call, resolution) {
-  const callee = functionBehindCallee(call.getExpression());
+  const callee = functionBehindCallee(call.getExpression(), resolution);
   if (callee === null) {
     return [];
   }
@@ -189,18 +458,48 @@ function readsThroughHelperCall(call, resolution) {
     );
   });
   const wrapped = isDefaultedAt(call);
-  return [...defaultedByName].map(([name, atSites]) => ({
-    name,
-    defaulted: atSites || wrapped,
-    node: call
-  }));
-}
-function functionBehindCallee(callee) {
-  const nameNode = N.isPropertyAccessExpression(callee) ? callee.getNameNode() : callee;
-  if (!N.isIdentifier(nameNode)) {
+  return [
+    ...[...defaultedByName].map(([name, atSites]) => ({
+      name,
+      defaulted: atSites || wrapped,
+      node: call
+    })),
+    // A config module parses its schema once and every handler calls
+    // the function around it, so the call reports what the parse reads.
+    ...anchoredAt(schemaEnvReadsInside(callee, resolution), call)
+  ];
+}
+function anchoredAt(reads, node) {
+  return reads.map((read) => ({ ...read, node }));
+}
+function functionBehindCallee(callee, resolution) {
+  const nameNode = N2.isPropertyAccessExpression(callee) ? callee.getNameNode() : callee;
+  if (!N2.isIdentifier(nameNode)) {
     return null;
   }
-  return functionTargetOf(nameNode)?.func ?? null;
+  const declared = functionTargetOf(nameNode)?.func;
+  if (declared !== void 0 || resolution === void 0) {
+    return declared ?? null;
+  }
+  return factoryReturnedCallee(nameNode, callee, resolution);
+}
+function factoryReturnedCallee(nameNode, callee, resolution) {
+  if (!isDeclaredAsCall(nameNode)) {
+    return null;
+  }
+  const returned = resolution.resolveReturnedCallable(callee);
+  return returned === null ? null : toFunctionRoot(returned);
+}
+function isDeclaredAsCall(nameNode) {
+  const declarations = declarationsBehind(symbolBehind(nameNode));
+  return declarations.length > 0 && declarations.every(isVariableSetToCall);
+}
+function isVariableSetToCall(declaration) {
+  if (!N2.isVariableDeclaration(declaration)) {
+    return false;
+  }
+  const initializer = declaration.getInitializer();
+  return initializer !== void 0 && N2.isCallExpression(initializer);
 }
 function namesSomething(value) {
   return value !== null && value.length > 0;
@@ -218,26 +517,22 @@ function directEnvReads(fn, parameter) {
 }
 function directEnvRead(fn, parameter) {
   for (const access of fn.getDescendantsOfKind(
-    SyntaxKind.ElementAccessExpression
+    SyntaxKind2.ElementAccessExpression
   )) {
     if (!isProcessEnv(access.getExpression())) {
       continue;
     }
     const argument = access.getArgumentExpression();
-    if (argument !== void 0 && N.isIdentifier(argument) && symbolBehind(argument)?.getValueDeclaration() === parameter) {
+    if (argument !== void 0 && N2.isIdentifier(argument) && symbolBehind(argument)?.getValueDeclaration() === parameter) {
       return access;
     }
   }
   return null;
 }
-function configReadEffect(read, deploymentTarget, instanceName) {
+function configReadEffect(read, where) {
   return {
     type: "interaction",
-    binding: runtimeConfigBinding({
-      recognition: "@suss/runtime-node",
-      deploymentTarget,
-      instanceName
-    }),
+    binding: configBinding(where),
     callee: readName(read.name),
     interaction: {
       class: "config-read",
@@ -246,42 +541,21 @@ function configReadEffect(read, deploymentTarget, instanceName) {
     }
   };
 }
-function recognizeProcessEnvRead(access, deploymentTarget, instanceName, resolution) {
+function recognizeProcessEnvRead(access, where, resolution) {
   const reads = envReadsAt(access, resolution);
   if (reads.length === 0) {
     return null;
   }
-  return reads.map(
-    (read) => configReadEffect(read, deploymentTarget, instanceName)
-  );
+  return reads.map((read) => configReadEffect(read, where));
 }
 function envVarRecognizer(opts = {}) {
-  const deploymentTarget = opts.deploymentTarget ?? "lambda";
-  const instanceName = opts.instanceName ?? "<unknown>";
   return (access, ctx) => recognizeProcessEnvRead(
     access,
-    deploymentTarget,
-    instanceName,
+    opts,
     ctx.resolution
   );
 }
 var FILE_LOCATION_GLOBALS = /* @__PURE__ */ new Set(["__dirname", "__filename"]);
-function moduleMetaRead(callee) {
-  return {
-    type: "interaction",
-    binding: runtimeConfigBinding2({
-      recognition: "@suss/runtime-node",
-      deploymentTarget: "lambda",
-      instanceName: "<runtime>"
-    }),
-    callee,
-    interaction: {
-      class: "config-read",
-      name: callee,
-      defaulted: false
-    }
-  };
-}
 var importMetaRecognizer = (access, _ctx) => {
   const node = access;
   if (!Node.isPropertyAccessExpression(node)) {
@@ -295,7 +569,7 @@ var importMetaRecognizer = (access, _ctx) => {
   if (keyword === void 0 || inner.getNameNode().getText() !== "meta") {
     return null;
   }
-  return [moduleMetaRead(node.getText())];
+  return [opaqueRuntimeRead(node.getText())];
 };
 var fileLocationRecognizer = (access, _ctx) => {
   const node = access;
@@ -310,7 +584,7 @@ var fileLocationRecognizer = (access, _ctx) => {
   if (!FILE_LOCATION_GLOBALS.has(text)) {
     return null;
   }
-  return [moduleMetaRead(text)];
+  return [opaqueRuntimeRead(text)];
 };
 function isProcessEnvVarRead(node) {
   const inner = node.getExpression();
@@ -337,35 +611,33 @@ var OPAQUE_PROPERTY_NAMES = /* @__PURE__ */ new Set([
   "execPath",
   "execArgv"
 ]);
-function makeProcessSurfaceRecognizer(opts) {
-  const deploymentTarget = opts.deploymentTarget ?? "lambda";
-  const instanceName = opts.instanceName ?? "<unknown>";
+function makeProcessSurfaceRecognizer(where) {
   return (access, _ctx) => {
     const node = access;
     if (Node2.isPropertyAccessExpression(node)) {
-      return recognizeProperty(node, deploymentTarget, instanceName);
+      return recognizeProperty(node, where);
     }
     if (Node2.isElementAccessExpression(node)) {
-      return recognizeElementAccess(node, deploymentTarget, instanceName);
+      return recognizeElementAccess(node, where);
     }
     return null;
   };
 }
-function recognizeProperty(node, deploymentTarget, instanceName) {
+function recognizeProperty(node, where) {
   if (isProcessEnvVarRead(node)) {
     return null;
   }
   const subject = node.getExpression();
   const name = node.getName();
   if (isProcessIdentifier(subject) && name === "argv") {
-    return [argvRead(deploymentTarget, instanceName, node.getText(), null)];
+    return [argvRead(where, node.getText(), null)];
   }
   if (isProcessIdentifier(subject) && OPAQUE_PROPERTY_NAMES.has(name)) {
-    return [opaqueProcessRead(node.getText(), `process.${name}`)];
+    return [opaqueRuntimeRead(node.getText())];
   }
   return null;
 }
-function recognizeElementAccess(node, deploymentTarget, instanceName) {
+function recognizeElementAccess(node, where) {
   const subject = node.getExpression();
   if (!Node2.isPropertyAccessExpression(subject)) {
     return null;
@@ -382,17 +654,13 @@ function recognizeElementAccess(node, deploymentTarget, instanceName) {
   if (arg !== void 0 && Node2.isNumericLiteral(arg)) {
     indexLabel = String(arg.getLiteralValue());
   }
-  return [argvRead(deploymentTarget, instanceName, node.getText(), indexLabel)];
+  return [argvRead(where, node.getText(), indexLabel)];
 }
-function argvRead(deploymentTarget, instanceName, callee, indexLabel) {
+function argvRead(where, callee, indexLabel) {
   const name = indexLabel !== null ? `argv[${indexLabel}]` : "argv";
   return {
     type: "interaction",
-    binding: runtimeConfigBinding3({
-      recognition: "@suss/runtime-node",
-      deploymentTarget,
-      instanceName
-    }),
+    binding: configBinding(where),
     callee,
     interaction: {
       class: "config-read",
@@ -401,22 +669,6 @@ function argvRead(deploymentTarget, instanceName, callee, indexLabel) {
     }
   };
 }
-function opaqueProcessRead(callee, _label) {
-  return {
-    type: "interaction",
-    binding: runtimeConfigBinding3({
-      recognition: "@suss/runtime-node",
-      deploymentTarget: "lambda",
-      instanceName: "<runtime>"
-    }),
-    callee,
-    interaction: {
-      class: "config-read",
-      name: callee,
-      defaulted: false
-    }
-  };
-}
 function processSurfaceRecognizer(opts = {}) {
   return makeProcessSurfaceRecognizer(opts);
 }
@@ -558,16 +810,16 @@ function nodeSchedulingSubUnits(parent, _ctx) {
   });
   return out;
 }
-var PACK_VERSION = "0.1.0";
+var PACK_VERSION = "0.2.0";
 var optionsSchema = z.object({
   /**
    * Deployment context for runtime-config reads (process.env.X,
-   * process.argv). Defaults to `"lambda"`.
+   * process.argv). Left off the binding unless a run sets it.
    */
   deploymentTarget: z.enum(["lambda", "ecs-task", "container", "k8s-deployment"]).optional(),
   /**
-   * Instance name placeholder for runtime-config bindings the pack
-   * emits. Defaults to `"<unknown>"`.
+   * The deployed instance the reads belong to. Left off the binding
+   * unless a run sets it.
    */
   instanceName: z.string().optional()
 }).strict();
@@ -605,7 +857,7 @@ var declares = {
   package: "@suss/runtime-node",
   dependencies: [],
   shippedWith: "typescript",
-  reads: "Node.js runtime primitives, scheduling, the `process` surface (incl. `process.env.X` config-read interactions), module-loading globals, emitted as interaction effects."
+  reads: "Node.js runtime primitives, scheduling, the `process` surface (incl. `process.env.X` config-read interactions and the keys of a schema parsed against `process.env`), module-loading globals as metadata-read interactions, emitted as interaction effects."
 };
 var index_default = nodeRuntimePack;
 export {

package/dist/pg-ruby.d.ts

@@ -0,0 +1 @@
+export { declares, default } from '@suss/framework-pg-ruby';