@suss/packs 0.33.1 → 0.34.1

package/dist/nestjs-graphql.js

@@ -2,14 +2,10 @@
 import { z } from "zod";
 var optionsSchema = z.object({
   /**
-   * Class decorators this project composes `@Resolver()` 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 `Resolver` from
-   * `@nestjs/graphql`. 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 `@Resolver()` 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 `Resolver` from `@nestjs/graphql`.
    */
   classDecorators: z.array(z.string()).optional()
 }).strict();
@@ -17,10 +13,8 @@ function nestjsGraphqlFramework(options = {}) {
   return {
     name: "nestjs-graphql",
     languages: ["typescript"],
-    // Apollo Server runs underneath via `GraphQLModule.forRoot({...
-    // ApolloDriver })`; the wire transport stays HTTP regardless of
-    // whether the resolver was discovered via decorator or via an
-    // object-literal resolver map.
+    // Apollo Server runs underneath `GraphQLModule.forRoot`, so the
+    // transport is HTTP here as it is for the apollo pack.
     protocol: "http",
     discovery: [
       {
@@ -28,8 +22,8 @@ function nestjsGraphqlFramework(options = {}) {
         match: {
           type: "decoratedMethod",
           importModule: "@nestjs/graphql",
-          // 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: ["Resolver", ...options.classDecorators ?? []],
           methodDecorators: [
             "Query",
@@ -37,9 +31,8 @@ function nestjsGraphqlFramework(options = {}) {
             "ResolveField",
             "Subscription"
           ],
-          // The three that settle their own type, each named after the
-          // type it puts its field on. `ResolveField` is deliberately
-          // absent: it is the one that needs the class decorator.
+          // `ResolveField` is left out because its type comes from the
+          // class decorator.
           methodDecoratorTypeMap: {
             Query: "Query",
             Mutation: "Mutation",
@@ -50,10 +43,8 @@ function nestjsGraphqlFramework(options = {}) {
       }
     ],
     terminals: [
-      // Resolvers return a value; errors propagate as thrown
-      // exceptions (NestJS / Apollo map them to `errors[]` on the
-      // outgoing response). No framework-specific response-call
-      // shape: return + throw cover the observable behaviour.
+      // A resolver has no response call. It returns a value or throws,
+      // and NestJS turns a thrown exception into `errors[]`.
       {
         kind: "return",
         match: { type: "returnStatement" },
@@ -65,10 +56,8 @@ function nestjsGraphqlFramework(options = {}) {
         extraction: {}
       },
       {
-        // Resolver methods can fall through and return `undefined` when the
-        // field is optional and the parent object already has the value. Keep a
-        // default transition so the unit does not come out with no transitions
-        // at all.
+        // A resolver for an optional field can fall off the end. Without
+        // this terminal that unit would come out with no transitions.
         kind: "return",
         match: { type: "functionFallthrough" },
         extraction: {}

package/dist/nestjs-microservices.js

@@ -7,14 +7,13 @@ var TRANSPORTS = [
 ];
 var optionsSchema = z.object({
   /**
-   * The broker bootstrap connects, which the handler's own file never
-   * states. Defaults to NATS.
+   * The broker the project connects at bootstrap. The handler's file
+   * never mentions it. Defaults to NATS.
    */
   transport: z.enum(TRANSPORTS).optional(),
   /**
-   * Class decorators this project composes `@Controller()` into, the
-   * same escape the REST pack takes for wrappers whose body is not in
-   * the project.
+   * Class decorators that wrap `@Controller()` in a package outside the
+   * project, as in the REST pack. A dependency stub fills this.
    */
   classDecorators: z.array(z.string()).optional()
 }).strict();
@@ -35,8 +34,8 @@ function nestjsMicroservicesFramework(options = {}) {
           type: "decoratedRoute",
           importModule: ["@nestjs/microservices", "@nestjs/common"],
           classDecorators: ["Controller", ...options.classDecorators ?? []],
-          // The values label the handler for a reader; the boundary
-          // comes from the declared binding below.
+          // These values only label the handler. The boundary comes from
+          // the declared binding.
           methodDecoratorRouteMap: {
             EventPattern: "event",
             MessagePattern: "message"
@@ -47,9 +46,9 @@ function nestjsMicroservicesFramework(options = {}) {
       }
     ],
     terminals: [
-      // An @MessagePattern handler's return is the reply; an
-      // @EventPattern handler's return is dropped by the framework.
-      // Both are recorded as returns, and reply pairing is deferred.
+      // An `@MessagePattern` handler's return value is the reply, and
+      // NestJS drops an `@EventPattern` handler's. Both are recorded as
+      // returns, and nothing pairs the reply yet.
       {
         kind: "return",
         match: { type: "returnStatement", excludeCallReturns: false },

package/dist/nestjs-rest.js

@@ -1,18 +1,143 @@
 // ../framework/nestjs-rest/dist/index.js
 import { z } from "zod";
+var HTTP_STATUS = {
+  CONTINUE: 100,
+  SWITCHING_PROTOCOLS: 101,
+  PROCESSING: 102,
+  EARLYHINTS: 103,
+  OK: 200,
+  CREATED: 201,
+  ACCEPTED: 202,
+  NON_AUTHORITATIVE_INFORMATION: 203,
+  NO_CONTENT: 204,
+  RESET_CONTENT: 205,
+  PARTIAL_CONTENT: 206,
+  MULTI_STATUS: 207,
+  ALREADY_REPORTED: 208,
+  CONTENT_DIFFERENT: 210,
+  AMBIGUOUS: 300,
+  MOVED_PERMANENTLY: 301,
+  FOUND: 302,
+  SEE_OTHER: 303,
+  NOT_MODIFIED: 304,
+  TEMPORARY_REDIRECT: 307,
+  PERMANENT_REDIRECT: 308,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  PAYMENT_REQUIRED: 402,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  NOT_ACCEPTABLE: 406,
+  PROXY_AUTHENTICATION_REQUIRED: 407,
+  REQUEST_TIMEOUT: 408,
+  CONFLICT: 409,
+  GONE: 410,
+  LENGTH_REQUIRED: 411,
+  PRECONDITION_FAILED: 412,
+  PAYLOAD_TOO_LARGE: 413,
+  URI_TOO_LONG: 414,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  REQUESTED_RANGE_NOT_SATISFIABLE: 416,
+  EXPECTATION_FAILED: 417,
+  I_AM_A_TEAPOT: 418,
+  MISDIRECTED: 421,
+  UNPROCESSABLE_ENTITY: 422,
+  LOCKED: 423,
+  FAILED_DEPENDENCY: 424,
+  PRECONDITION_REQUIRED: 428,
+  TOO_MANY_REQUESTS: 429,
+  UNRECOVERABLE_ERROR: 456,
+  INTERNAL_SERVER_ERROR: 500,
+  NOT_IMPLEMENTED: 501,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504,
+  HTTP_VERSION_NOT_SUPPORTED: 505,
+  INSUFFICIENT_STORAGE: 507,
+  LOOP_DETECTED: 508
+};
+var HTTP_STATUS_CONSTANTS = Object.fromEntries(
+  Object.entries(HTTP_STATUS).map(([member, status]) => [
+    `HttpStatus.${member}`,
+    status
+  ])
+);
 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 NEST_APPLICATION = {
+  importModule: "@nestjs/core",
+  importName: "NestFactory",
+  factory: "create"
+};
+var REQUEST_METHODS = {
+  0: "GET",
+  1: "POST",
+  2: "PUT",
+  3: "DELETE",
+  4: "PATCH",
+  5: "*",
+  6: "OPTIONS",
+  7: "HEAD"
+};
+var NEST_EXCEPTION_STATUSES = {
+  BadRequestException: 400,
+  UnauthorizedException: 401,
+  ForbiddenException: 403,
+  NotFoundException: 404,
+  MethodNotAllowedException: 405,
+  NotAcceptableException: 406,
+  RequestTimeoutException: 408,
+  ConflictException: 409,
+  GoneException: 410,
+  PreconditionFailedException: 412,
+  PayloadTooLargeException: 413,
+  UnsupportedMediaTypeException: 415,
+  ImATeapotException: 418,
+  MisdirectedException: 421,
+  UnprocessableEntityException: 422,
+  InternalServerErrorException: 500,
+  NotImplementedException: 501,
+  BadGatewayException: 502,
+  ServiceUnavailableException: 503,
+  GatewayTimeoutException: 504,
+  HttpVersionNotSupportedException: 505
+};
+var SWAGGER_RESPONSE_DECORATORS = {
+  ApiResponse: null,
+  ApiOkResponse: 200,
+  ApiCreatedResponse: 201,
+  ApiAcceptedResponse: 202,
+  ApiNoContentResponse: 204,
+  ApiMovedPermanentlyResponse: 301,
+  ApiFoundResponse: 302,
+  ApiBadRequestResponse: 400,
+  ApiUnauthorizedResponse: 401,
+  ApiForbiddenResponse: 403,
+  ApiNotFoundResponse: 404,
+  ApiMethodNotAllowedResponse: 405,
+  ApiNotAcceptableResponse: 406,
+  ApiRequestTimeoutResponse: 408,
+  ApiConflictResponse: 409,
+  ApiGoneResponse: 410,
+  ApiPreconditionFailedResponse: 412,
+  ApiPayloadTooLargeResponse: 413,
+  ApiUnsupportedMediaTypeResponse: 415,
+  ApiUnprocessableEntityResponse: 422,
+  ApiTooManyRequestsResponse: 429,
+  ApiInternalServerErrorResponse: 500,
+  ApiNotImplementedResponse: 501,
+  ApiBadGatewayResponse: 502,
+  ApiServiceUnavailableResponse: 503,
+  ApiGatewayTimeoutResponse: 504
+};
 function nestjsRestFramework(options = {}) {
   return {
     name: "nestjs-rest",
@@ -24,8 +149,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 +161,62 @@ 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",
+          statusCodeConstants: HTTP_STATUS_CONSTANTS,
+          globalPrefix: {
+            method: "setGlobalPrefix",
+            application: NEST_APPLICATION,
+            // 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
+            }
+          },
+          // A spec `@nestjs/swagger` generates declares these statuses
+          // because of the decorators, whether or not a path sends them.
+          declaredStatuses: {
+            importModule: "@nestjs/swagger",
+            decorators: SWAGGER_RESPONSE_DECORATORS,
+            statusKey: "status"
+          },
+          // `app.enableVersioning()` with no options is URI versioning,
+          // which serves version 1 of a route at `/v1/...`.
+          versioning: {
+            option: "version",
+            decorator: "Version",
+            neutral: "VERSION_NEUTRAL",
+            call: { method: "enableVersioning", application: NEST_APPLICATION },
+            typeKey: "type",
+            types: {
+              "VersioningType.URI": "path",
+              "VersioningType.HEADER": "outsidePath",
+              "VersioningType.MEDIA_TYPE": "outsidePath",
+              "VersioningType.CUSTOM": "outsidePath"
+            },
+            typeNumbers: {
+              0: "path",
+              1: "outsidePath",
+              2: "outsidePath",
+              3: "outsidePath"
+            },
+            defaultType: "path",
+            pathPrefix: { key: "prefix", default: "v" },
+            defaultVersionKey: "defaultVersion"
           }
         },
         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 +225,19 @@ 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's exception filter
+        // sends the status that class is for. Any other throw keeps no
+        // status and stays a throw.
         kind: "throw",
         match: { type: "throwExpression" },
-        extraction: {}
+        extraction: {
+          statusCode: { from: "constructor", codes: NEST_EXCEPTION_STATUSES }
+        },
+        producesResponse: true
       },
       {
         // 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,13 +38,14 @@ 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"],
-          failureDelivery: "response"
+          failureDelivery: "response",
+          // Net::HTTP never follows a redirect.
+          redirectDelivery: "response"
         }
       }
     ]
@@ -55,6 +56,7 @@ var declares = {
   package: "@suss/client-net-http",
   dependencies: [],
   shippedWith: "ruby",
+  sourcePattern: /\bNet::HTTP\b/,
   reads: "Net::HTTP call sites (Ruby): the module methods that send on their own, and a request object built with `Net::HTTP::Get` and its siblings, with the URL read through `URI`."
 };
 var index_default = netHttpClient;

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 {