@suss/packs 0.33.0 → 0.34.0

package/dist/nestjs-rest.js

@@ -2,17 +2,23 @@
 import { z } from "zod";
 var optionsSchema = z.object({
   /**
-   * Class decorators this project composes `@Controller()` into, for
-   * the cases the adapter cannot follow on its own.
-   *
-   * A wrapper written in the project needs no entry here: the adapter
-   * resolves a class decorator to the function behind it and accepts it
-   * when calling that function calls `Controller` from
-   * `@nestjs/common`. What is left for this option is a wrapper whose
-   * body is not in the project, so there is nothing to read.
+   * Class decorators that wrap `@Controller()` in a package outside the
+   * project. A dependency stub fills this. A wrapper written in the
+   * project needs no entry, because the adapter reads its body and
+   * sees it call `Controller` from `@nestjs/common`.
    */
   classDecorators: z.array(z.string()).optional()
 }).strict();
+var REQUEST_METHODS = {
+  0: "GET",
+  1: "POST",
+  2: "PUT",
+  3: "DELETE",
+  4: "PATCH",
+  5: "*",
+  6: "OPTIONS",
+  7: "HEAD"
+};
 function nestjsRestFramework(options = {}) {
   return {
     name: "nestjs-rest",
@@ -24,8 +30,8 @@ function nestjsRestFramework(options = {}) {
         match: {
           type: "decoratedRoute",
           importModule: "@nestjs/common",
-          // First match wins, so the framework's own decorator is
-          // tried before any wrapper a project names.
+          // The first match wins, so the framework's own decorator is
+          // tried before any wrapper.
           classDecorators: ["Controller", ...options.classDecorators ?? []],
           methodDecoratorRouteMap: {
             Get: "GET",
@@ -36,17 +42,34 @@ function nestjsRestFramework(options = {}) {
             Options: "OPTIONS",
             Head: "HEAD",
             All: "*"
+          },
+          // Nest sends 201 for a POST and 200 for every other verb, and
+          // `@HttpCode(n)` sets the status for one handler.
+          defaultStatusCodes: { Post: 201 },
+          statusCodeDecorator: "HttpCode",
+          globalPrefix: {
+            method: "setGlobalPrefix",
+            application: {
+              importModule: "@nestjs/core",
+              importName: "NestFactory",
+              factory: "create"
+            },
+            // An exclusion is a path, or a `RouteInfo` whose method is a
+            // member of Nest's `RequestMethod` enum.
+            exclude: {
+              option: "exclude",
+              pathKey: "path",
+              methodKey: "method",
+              methods: REQUEST_METHODS
+            }
           }
         },
         requiresImport: ["@nestjs/common"]
       }
     ],
     terminals: [
-      // NestJS controllers serialise the returned value as the
-      // response body and pick a 200 default unless the method
-      // declares `@HttpCode(N)` (deferred: that decorator is
-      // metadata-only). Match bare returns and treat object literals
-      // / identifiers / awaited calls as 200 responses.
+      // NestJS sends the returned value as the body. The route's own
+      // status, from its verb or `@HttpCode`, replaces this 200.
       {
         kind: "response",
         match: { type: "returnStatement", excludeCallReturns: false },
@@ -55,19 +78,16 @@ function nestjsRestFramework(options = {}) {
         }
       },
       {
-        // `throw new HttpException(msg, status)` / `throw new
-        // BadRequestException()` etc. NestJS maps these to HTTP
-        // responses; v0 records the exception type so downstream
-        // contract-checking can pair it with the wire status that
-        // the framework would emit.
+        // `throw new BadRequestException()`: NestJS turns the exception
+        // into a response. The throw records the exception type, and the
+        // contract check pairs it with the status NestJS would send.
         kind: "throw",
         match: { type: "throwExpression" },
         extraction: {}
       },
       {
         // A method that runs off the end returns undefined, and Nest
-        // sends the same 200 with an empty body it sends for a bare
-        // `return;`. Only `@HttpCode(N)` changes that.
+        // sends the same empty response it sends for a bare `return;`.
         kind: "response",
         match: { type: "functionFallthrough" },
         extraction: {

package/dist/net-http.js

@@ -28,9 +28,9 @@ function netHttpClient() {
       {
         constantName: "Net::HTTP",
         verbMethodNames: VERB_METHODS,
-        // Every one of these takes a URI object rather than a string.
-        // `URI(...)` and `URI.parse(...)` belong to Ruby itself, so the
-        // adapter's value tables read them and the pack says nothing.
+        // These methods take a URI object. `URI(...)` and `URI.parse(...)`
+        // are part of Ruby, so the adapter already evaluates them and the
+        // pack adds nothing for them.
         url: { position: 0 },
         receiverBuilders: ["new"],
         requestObject: {
@@ -38,9 +38,8 @@ function netHttpClient() {
           constructors: REQUEST_CLASSES,
           urlPosition: 0
         },
-        // The status comes back as a string, which is why a caller
-        // writes `response.code.to_i == 404`, read the same as any
-        // other member.
+        // `code` is a string, so callers write `response.code.to_i == 404`.
+        // That comparison is read the same way as one on any other member.
         response: {
           statusCode: ["code"],
           body: ["body"],

package/dist/nextjs.js

@@ -36,9 +36,9 @@ function actionUnit(func, name, module) {
     name,
     terminals: ACTION_TERMINALS,
     inputMapping: { type: "allPositional" },
-    // The identity intent and the keyed pairing pass refer to the
-    // action by. The path is absolute here and the CLI makes it
-    // project-relative with every other path on the summary.
+    // Intent files and keyed pairing find the action by module and export
+    // name. The path is absolute here, and the CLI makes it relative to
+    // the project along with every other path on the summary.
     functionCallInfo: { module, exportName: name }
   };
 }
@@ -152,8 +152,8 @@ function nextjsFramework() {
           exportNames: ["default"]
         },
         bindingExtraction: {
-          // One export serves every method, which is what the wildcard says.
-          // Pairing matches it against whichever method a consumer used.
+          // One default export serves every method, so pairing matches it
+          // against whichever method a caller uses.
           method: { type: "literal", value: "*" },
           path: PAGES_ROUTES
         }
@@ -177,7 +177,7 @@ function nextjsFramework() {
       },
       {
         // Response.json(body, { status }), the platform's own, which a
-        // handler can return without importing anything.
+        // handler can call without an import.
         kind: "response",
         match: { type: "functionCall", functionName: "Response.json" },
         extraction: {
@@ -187,8 +187,8 @@ function nextjsFramework() {
         }
       },
       {
-        // new Response(body, { status }), which a handler returns for
-        // anything that is not JSON: a redirect, a stream, plain text.
+        // new Response(body, { status }), which a handler returns for a
+        // body that is not JSON, such as a stream or plain text.
         kind: "response",
         match: { type: "functionCall", functionName: "Response" },
         extraction: {
@@ -198,9 +198,8 @@ function nextjsFramework() {
         }
       },
       {
-        // NextResponse.redirect(url) sends a 307 unless the caller says
-        // otherwise, and the alternative is written as an init object
-        // this pack does not read yet.
+        // NextResponse.redirect(url) sends a 307 by default. Another status
+        // goes in an init object, which this pack does not read yet.
         kind: "response",
         match: {
           type: "functionCall",
@@ -210,8 +209,8 @@ function nextjsFramework() {
         extraction: { defaultStatusCode: 307 }
       },
       {
-        // A pages handler writes to the response it was handed, the
-        // same shape Express uses.
+        // A pages handler writes to the response object passed to it, as
+        // an Express handler does.
         kind: "response",
         match: {
           type: "parameterMethodCall",
@@ -241,9 +240,9 @@ function nextjsFramework() {
         extraction: {}
       }
     ],
-    // A route handler takes the request first. The app directory hands
-    // it a context object holding the route parameters; a pages handler
-    // takes the response object there instead.
+    // Both kinds of handler take the request first. An app handler gets a
+    // context object with the route parameters second, and a pages handler
+    // gets the response object in that position.
     inputMapping: {
       type: "positionalParams",
       params: [
@@ -257,7 +256,7 @@ var declares = {
   kind: "framework",
   package: "@suss/framework-nextjs",
   dependencies: [{ ecosystem: "npm", name: "next" }],
-  reads: `Next.js route handlers, pages, and server actions; the route comes from where the file is on disk, and a \`"use server"\` function becomes an action unit.`
+  reads: `Next.js route handlers, pages and server actions. The route comes from where the file is on disk, and a \`"use server"\` function becomes an action unit.`
 };
 var index_default = nextjsFramework;
 export {

package/dist/node.js

@@ -25,12 +25,17 @@ import {
 } from "@suss/adapter-typescript";
 import { Node } from "ts-morph";
 import {
-  Node as Node2
+  Node as Node2,
+  SyntaxKind as SyntaxKind3
 } from "ts-morph";
+import { numberValueOf } from "@suss/adapter-typescript";
 import {
   Node as Node3
 } from "ts-morph";
 import { functionCallBinding } from "@suss/behavioral-ir";
+import { Node as Node4 } from "ts-morph";
+import { writtenPayloadOf } from "@suss/adapter-typescript";
+import { ioBinding } from "@suss/behavioral-ir";
 var RECOGNITION = "@suss/runtime-node";
 function configBinding(where) {
   return runtimeConfigBinding({ recognition: RECOGNITION, ...where });
@@ -127,12 +132,12 @@ function schemaEnvReads(call, resolution) {
     if (!readerCouldFire(call, reader, written) || !callMatches(call, reader, resolution)) {
       continue;
     }
-    const environment = environmentArgument(call, reader, resolution);
-    if (environment === null || !resolution.isEnvironmentValue(environment)) {
+    const reads = readsFromSchema(call, reader, resolution);
+    if (reads.length === 0) {
       continue;
     }
-    const reads = readsFromSchema(call, reader, resolution);
-    if (reads.length > 0) {
+    const environment = environmentArgument(call, reader, resolution);
+    if (environment !== null && resolution.isEnvironmentValue(environment)) {
       return reads;
     }
   }
@@ -396,9 +401,9 @@ function bindingRead(element) {
   return [
     {
       name,
-      // A binding default supplies the value the variable is missing,
-      // which is what `??` does for the other two spellings.
-      defaulted: element.getInitializer() !== void 0,
+      // A binding default covers a missing variable the same way `??`
+      // does after a dotted read.
+      defaulted: element.getInitializer() !== void 0 || isDefaultedAt(element),
       node: element
     }
   ];
@@ -464,8 +469,8 @@ function readsThroughHelperCall(call, resolution) {
       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.
+    // A config module often parses its schema inside a function that
+    // every handler calls, so each call reports the keys that parse reads.
     ...anchoredAt(schemaEnvReadsInside(callee, resolution), call)
   ];
 }
@@ -508,7 +513,7 @@ function namesReadAtSites(fn, resolution) {
   if (resolution === void 0) {
     return () => null;
   }
-  const namers = resolution.envNamers(fn.getSourceFile());
+  const namers = resolution.envNamers(fn.getProject());
   return (parameter) => namers.sitesNaming(parameter);
 }
 function directEnvReads(fn, parameter) {
@@ -612,10 +617,14 @@ var OPAQUE_PROPERTY_NAMES = /* @__PURE__ */ new Set([
   "execArgv"
 ]);
 function makeProcessSurfaceRecognizer(where) {
-  return (access, _ctx) => {
+  return (access, ctx) => {
     const node = access;
     if (Node2.isPropertyAccessExpression(node)) {
-      return recognizeProperty(node, where);
+      return recognizeProperty(
+        node,
+        where,
+        ctx?.resolution
+      );
     }
     if (Node2.isElementAccessExpression(node)) {
       return recognizeElementAccess(node, where);
@@ -623,7 +632,7 @@ function makeProcessSurfaceRecognizer(where) {
     return null;
   };
 }
-function recognizeProperty(node, where) {
+function recognizeProperty(node, where, resolution) {
   if (isProcessEnvVarRead(node)) {
     return null;
   }
@@ -635,8 +644,25 @@ function recognizeProperty(node, where) {
   if (isProcessIdentifier(subject) && OPAQUE_PROPERTY_NAMES.has(name)) {
     return [opaqueRuntimeRead(node.getText())];
   }
+  if (isProcessIdentifier(subject) && name === "exitCode") {
+    return exitCodeSet(node, resolution);
+  }
   return null;
 }
+function exitCodeSet(node, resolution) {
+  const assignment = node.getParent();
+  if (!Node2.isBinaryExpression(assignment) || assignment.getLeft() !== node || assignment.getOperatorToken().getKind() !== SyntaxKind3.EqualsToken) {
+    return null;
+  }
+  const written = assignment.getRight();
+  return [
+    {
+      type: "stateChange",
+      variable: node.getText(),
+      newValue: numberValueOf(written, resolution) ?? written.getText()
+    }
+  ];
+}
 function recognizeElementAccess(node, where) {
   const subject = node.getExpression();
   if (!Node2.isPropertyAccessExpression(subject)) {
@@ -767,9 +793,8 @@ var schedulingRecognizer = (call, _ctx) => {
 };
 var SCHEDULED_CALLBACK_INPUT = {
   type: "positionalParams",
-  // Timer callbacks receive whatever `...args` were passed at the
-  // schedule site. v0 doesn't track these positions individually,
-  // packs that need argument-shape modeling can layer it on top.
+  // A timer callback receives the extra arguments passed to the
+  // scheduling call. Those are not mapped to its parameters yet.
   params: []
 };
 function nodeSchedulingSubUnits(parent, _ctx) {
@@ -797,8 +822,8 @@ function nodeSchedulingSubUnits(parent, _ctx) {
     out.push({
       func: arg,
       kind: "scheduled-callback",
-      // Naming convention: `<parent>.<via>#<index>`. Multiple
-      // setImmediate calls in the same parent get distinct indices.
+      // The index keeps two calls to the same primitive in one parent
+      // apart.
       name: `${parent.name}.${primitive.via}#${idx}`,
       inputMapping: SCHEDULED_CALLBACK_INPUT,
       metadata: {
@@ -810,11 +835,84 @@ function nodeSchedulingSubUnits(parent, _ctx) {
   });
   return out;
 }
-var PACK_VERSION = "0.2.0";
+var RECOGNITION2 = "@suss/runtime-node";
+var PROCESS_STREAMS = ["process.stdout", "process.stderr"];
+var CONSOLE_STREAMS = {
+  log: "stdout",
+  info: "stdout",
+  debug: "stdout",
+  table: "stdout",
+  dir: "stdout",
+  warn: "stderr",
+  error: "stderr",
+  trace: "stderr"
+};
+var CONSOLE_TYPES = ["Console"];
+var STREAM_TYPES = ["NodeJS.WriteStream", "NodeJS.WritableStream"];
+var streamWriteRecognizer = (call, ctx) => {
+  const written = call;
+  if (!Node4.isCallExpression(written)) {
+    return null;
+  }
+  const callee = written.getExpression();
+  if (!Node4.isPropertyAccessExpression(callee)) {
+    return null;
+  }
+  const resolution = ctx?.resolution;
+  const target = targetOf(callee.getExpression(), callee.getName(), resolution);
+  if (target === void 0) {
+    return null;
+  }
+  const payload = writtenPayloadOf(written.getArguments());
+  const effect = {
+    type: "interaction",
+    binding: ioBinding({ recognition: RECOGNITION2, target }),
+    callee: callee.getText(),
+    groupId: callSiteId(written),
+    interaction: {
+      class: "stream-write",
+      payload: payload.shape,
+      serialized: payload.serialized
+    }
+  };
+  return [effect];
+};
+function targetOf(receiver, method, resolution) {
+  const consoleStream = Object.hasOwn(CONSOLE_STREAMS, method) ? CONSOLE_STREAMS[method] : void 0;
+  if (consoleStream !== void 0) {
+    if (Node4.isIdentifier(receiver) && receiver.getText() === "console") {
+      return consoleStream;
+    }
+    return viaParameter(receiver, CONSOLE_TYPES, resolution);
+  }
+  if (method !== "write") {
+    return void 0;
+  }
+  if (Node4.isPropertyAccessExpression(receiver)) {
+    const spelled = receiver.getText();
+    return PROCESS_STREAMS.includes(spelled) ? streamName(spelled) : void 0;
+  }
+  const path = viaParameter(receiver, STREAM_TYPES, resolution);
+  return path === null || path === void 0 ? path : streamName(path);
+}
+function viaParameter(receiver, annotations, resolution) {
+  if (resolution === void 0 || !Node4.isIdentifier(receiver)) {
+    return void 0;
+  }
+  return resolution.streamPathOf(receiver, annotations);
+}
+function streamName(path) {
+  return path.slice(path.lastIndexOf(".") + 1);
+}
+function callSiteId(call) {
+  const { line, column } = call.getSourceFile().getLineAndColumnAtPos(call.getStart());
+  return `${line}:${column}`;
+}
+var PACK_VERSION = "0.3.0";
 var optionsSchema = z.object({
   /**
-   * Deployment context for runtime-config reads (process.env.X,
-   * process.argv). Left off the binding unless a run sets it.
+   * The kind of deployment that runtime-config reads such as
+   * `process.env.X` belong to. Left off the binding unless a run sets it.
    */
   deploymentTarget: z.enum(["lambda", "ecs-task", "container", "k8s-deployment"]).optional(),
   /**
@@ -823,6 +921,22 @@ var optionsSchema = z.object({
    */
   instanceName: z.string().optional()
 }).strict();
+var PROCESS_EXIT = {
+  kind: "exit",
+  inEveryUnit: true,
+  match: { type: "functionCall", functionName: "process.exit" },
+  extraction: {
+    statusCode: { from: "argument", position: 0 },
+    defaultStatusCode: 0
+  }
+};
+var PARSE_ARGS = ["node:util", "util"].map((module) => ({
+  module,
+  name: "parseArgs",
+  argument: 0,
+  argsKey: "args",
+  optionsKey: "options"
+}));
 function nodeRuntimePack(options = {}) {
   const configOptions = {
     ...options.deploymentTarget !== void 0 ? { deploymentTarget: options.deploymentTarget } : {},
@@ -836,14 +950,16 @@ function nodeRuntimePack(options = {}) {
     protocol: "in-process",
     languages: ["typescript", "javascript"],
     discovery: [],
-    terminals: [],
+    terminals: [PROCESS_EXIT],
+    exitCodeWrites: ["process.exitCode"],
+    argumentParsers: PARSE_ARGS,
     inputMapping: { type: "positionalParams", params: [] },
-    invocationRecognizers: [schedulingRecognizer],
+    invocationRecognizers: [schedulingRecognizer, streamWriteRecognizer],
     environmentObjects: ["process.env"],
+    streamObjects: PROCESS_STREAMS,
     accessRecognizers: [
-      // `envRecognizer` owns `process.env.X`; `processRecognizer`
-      // owns the rest of the process surface and skips env reads,
-      // together they partition `process.*` without duplication.
+      // envRecognizer handles `process.env.X` and processRecognizer skips
+      // it, so each `process.*` read produces one effect.
       envRecognizer,
       processRecognizer,
       importMetaRecognizer,
@@ -857,7 +973,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 and the keys of a schema parsed against `process.env`), module-loading globals as metadata-read interactions, emitted as interaction effects."
+  reads: "Node.js runtime primitives, scheduling and the `process` surface, each recorded as an interaction effect. A `process.env.X` read, or a key of a schema parsed against `process.env`, becomes a config-read interaction. A module-loading global becomes a metadata-read interaction. A `console` call or a write to `process.stdout` or `process.stderr` becomes a stream-write interaction on the stream it goes to."
 };
 var index_default = nodeRuntimePack;
 export {

package/dist/package-exports.js

@@ -33,7 +33,7 @@ var declares = {
   kind: "framework",
   package: "@suss/framework-package-exports",
   dependencies: [],
-  reads: "The boundary between packages in one workspace: public exports on the provider side, imports of them on the consumer side. Reads the workspace manifest, so it needs no per-project package list."
+  reads: "The boundary between packages in one workspace: public exports on the provider side, and imports of them on the consumer side. The pack reads the workspace manifest, so nobody has to list the packages for each project."
 };
 var index_default = packageExportsFramework;
 export {

package/dist/pg.js

@@ -2,7 +2,8 @@
 import { declaredBy, pack, sqlStatements } from "@suss/recognize";
 var CLIENT_MODULES = ["pg", "@types/pg"];
 var STATEMENT = {
-  statement: [{ at: 0 }, { at: 0, property: ["text"] }]
+  statement: [{ at: 0 }, { at: 0, property: ["text"] }],
+  parameters: [{ at: 1 }, { at: 0, property: ["values"] }]
 };
 var QUERIES = sqlStatements({
   system: "postgresql",
@@ -19,7 +20,7 @@ var declares = {
   kind: "effects",
   package: "@suss/framework-pg",
   dependencies: [{ ecosystem: "npm", name: "pg" }],
-  reads: "node-postgres queries, emits storage-access interactions with the tables each statement touches."
+  reads: "node-postgres queries. Each one becomes a storage-access interaction on the tables its statement touches."
 };
 var index_default = pgFramework;
 export {