@suss/packs 0.33.0 → 0.34.0

package/dist/fastify.js

@@ -17,8 +17,8 @@ function fastifyFramework(_options = {}) {
     name: "fastify",
     protocol: "http",
     languages: ["typescript", "javascript"],
-    // Fastify exposes the routable via either default `Fastify` or
-    // named `fastify()`. Both drive handler registration the same way.
+    // Projects import the app factory as the default `Fastify` or the
+    // named `fastify`, and both register routes the same way.
     discovery: [
       ...httpRouteDiscovery({
         importModule: "fastify",
@@ -48,7 +48,7 @@ function fastifyFramework(_options = {}) {
         }
       },
       {
-        // reply.status(N).send(body), `.status` is the Express-style alias
+        // reply.status(N).send(body), the alias for `code`
         kind: "response",
         match: {
           type: "parameterMethodCall",
@@ -74,9 +74,8 @@ function fastifyFramework(_options = {}) {
         }
       },
       {
-        // reply.redirect(url) or reply.redirect(N, url)
-        // Arg 0 is a status code only in the 2-arg form; minArgs prevents
-        // extracting the URL string as a status code in the 1-arg form.
+        // reply.redirect(url) or reply.redirect(N, url). `minArgs` keeps
+        // the URL in the one-argument form from being read as a status.
         kind: "response",
         match: {
           type: "parameterMethodCall",
@@ -89,19 +88,16 @@ function fastifyFramework(_options = {}) {
         }
       },
       {
-        // throw new Error(...) / throw httpErrors.notFound() / etc.
-        // Status code is left for the consumer to infer from exception type;
-        // Fastify error libraries vary too widely to map here.
+        // throw httpErrors.notFound(). Fastify error libraries differ too
+        // much to map a status here, so the throw does not record one.
         kind: "throw",
         match: { type: "throwExpression" },
         extraction: {}
       },
       {
-        // `return user`, `return { id, name }`, `return await db.find(id)`,
-        // Fastify serialises the returned value as a 200 response body.
-        // `excludeCallReturns: true` keeps `return reply.send(...)` out
-        // of this branch: that call already lands as a parameterMethodCall
-        // terminal above, and matching it here would double-fire.
+        // `return user`: Fastify sends the value as a 200 body. Without
+        // `excludeCallReturns`, `return reply.send(...)` would match here
+        // and again as the `send` terminal above.
         kind: "response",
         match: {
           type: "returnStatement",

package/dist/fetch.js

@@ -21,10 +21,9 @@ function webFetchPack() {
           },
           path: { type: "fromArgument", position: 0 }
         },
-        // No import gate: `fetch` is a global. Walk every file,
-        // the discovery dispatch is itself cheap (just looks for
-        // call expressions named `fetch`), so the lack of pre-
-        // filter doesn't blow up perf.
+        // `fetch` is a global, so there is no import to gate on. Walking
+        // every file stays cheap because discovery only looks for calls
+        // named `fetch`.
         requiresImport: []
       }
     ],

package/dist/flask-restx.js

@@ -2,10 +2,9 @@
 import { z } from "zod";
 var optionsSchema = z.object({
   /**
-   * Modules a project's own wrapper re-exports flask-restx's route
-   * decorator from. flask-restx's own module is always accepted. The
-   * wrapper's name is the project's own choice, so it is supplied by
-   * whoever configures the pack rather than hardcoded here.
+   * Modules that re-export flask-restx's route decorator, on top of
+   * `flask_restx` itself. A dependency stub fills this in; a project's
+   * config file may not set it.
    */
   wrapperModules: z.array(z.string()).optional()
 }).strict();
@@ -30,8 +29,8 @@ function flaskRestxFramework(options = {}) {
         decoratorName: "route",
         verbMethodNames: VERB_METHOD_NAMES,
         pathParamSyntax: "flaskConverters",
-        // What each of these settings means for a written prefix is the
-        // grid in the Python adapter's README.
+        // The Python adapter's README has a table of what each of these
+        // settings does to a written prefix.
         pathRepeatedSlashes: "merged",
         routerComposition: {
           routerConstructorName: "Namespace",
@@ -53,11 +52,9 @@ function flaskRestxFramework(options = {}) {
             }
           }
         },
-        // Flask returns 200 from a resource method that returns a value
-        // and sets no status of its own.
         defaultStatusCode: 200,
         // Flask reads a status out of `return body, 201`, so the 200
-        // above only applies where the body writes no status of its own.
+        // above applies only when the return writes no status.
         statusFromReturnedTuple: true,
         // flask-restx re-exports Flask's function, which re-exports
         // Werkzeug's, and a project may import it from any of the three.
@@ -70,8 +67,8 @@ function flaskRestxFramework(options = {}) {
           {
             type: "decoratedWrapper",
             attribute: "before_request",
-            // A blueprint's own hook is not read: a route is decorated on
-            // a namespace, and the blueprint it is served under is a mount.
+            // A blueprint's own hook is skipped, because a route is decorated
+            // on a namespace and the blueprint only mounts it.
             registrars: [
               {
                 constructorName: "Flask",
@@ -100,7 +97,17 @@ function flaskRestxFramework(options = {}) {
           }
         ]
       }
-    ]
+    ],
+    // A resource method reads the request off Flask's module-level object.
+    requestObjects: [{ module: "flask", name: "request" }],
+    // A path parameter is handed to the method, and the rest is read off
+    // Flask's `request`: `request.args` for the query string.
+    requestSpelling: {
+      headers: { path: ["request", "headers"], saysWhichField: true },
+      query: { path: ["request", "args"], saysWhichField: true },
+      params: { path: ["pathParams"], saysWhichField: true },
+      body: { path: ["request", "json"], saysWhichField: true }
+    }
   };
 }
 var declares = {

package/dist/gcs.js

@@ -53,7 +53,7 @@ var declares = {
   kind: "effects",
   package: "@suss/framework-gcs",
   dependencies: [{ ecosystem: "npm", name: "@google-cloud/storage" }],
-  reads: "Google Cloud Storage calls, emits storage-access interactions."
+  reads: "Google Cloud Storage calls. Each one becomes a storage-access interaction."
 };
 var index_default = gcsFramework;
 export {

package/dist/graphql-ruby.js

@@ -4,20 +4,24 @@ import { z } from "zod";
 import { SCALAR_SHAPES } from "@suss/contract-graphql";
 var optionsSchema = z.object({
   /**
-   * Directory a `mutation:` / `resolver:` field's referenced class is
-   * looked up under, e.g. `path.join(repoRoot, "app/graphql")`.
-   * Written relative, it is read relative to `configDirectory`, and
-   * relative to the working directory when there is none.
+   * 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.
    */
   root: z.string(),
   /**
-   * The directory a relative `root` is read against: the config file's
-   * own directory, or the directory the run reads when the options came
-   * without one. The CLI supplies this; it is not written in the file
-   * itself.
+   * The CLI fills this in with the config file's directory, or with the
+   * directory the run reads when there is no file. A config file does
+   * not set it.
    */
   configDirectory: z.string().optional(),
-  /** Base classes beyond `Types::BaseObject` that also mark a class as declaring GraphQL fields. */
+  /**
+   * Base classes beyond the generated `Types::Base*` ones whose
+   * subclasses declare GraphQL fields. A config file may not set this; a
+   * dependency stub fills it.
+   */
   baseClassNames: z.array(z.string()).optional(),
   /** The schema-wide camelCase default. A `field` or `argument` call's own `camelize:` keyword overrides it for that one name. */
   camelize: z.boolean().optional()
@@ -72,10 +76,9 @@ function graphqlRubyFramework(options) {
     requiredDefault: true,
     camelizeKeyword: "camelize",
     camelizeDefault: options.camelize ?? true,
-    // The standard scalars come from the shared SDL table, so a
-    // contract read from Ruby compares against one read from SDL
-    // without a vocabulary mismatch. graphql-ruby accepts Ruby's own
-    // `Integer` class as a synonym for its `Int` scalar.
+    // The standard scalars come from the shared SDL table, so a contract
+    // read from Ruby uses the same shapes as one read from SDL.
+    // graphql-ruby also accepts Ruby's `Integer` class for `Int`.
     scalars: {
       ...SCALAR_SHAPES,
       Integer: { type: "number" }
@@ -98,7 +101,7 @@ function graphqlRubyFramework(options) {
     discovery: [pattern],
     // A resolver that reads a model through the dataloader passes the model
     // as an argument, so the read is recorded against that model when a
-    // storage pack in the same run says it is one.
+    // storage pack in the same run recognizes it as one.
     loaders: [
       {
         loader: "dataloader",
@@ -121,12 +124,13 @@ var declares = {
   kind: "framework",
   package: "@suss/framework-graphql-ruby",
   dependencies: [{ ecosystem: "rubygems", name: "graphql" }],
-  reads: "graphql-ruby class-based field DSL (Ruby), including `mutation:` / `resolver:` wiring one hop out to what the referenced class itself declares, and the model a resolver reads through `dataloader` when a storage pack in the run recognizes it.",
+  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.",
   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."
+    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" }
   }
 };
 var index_default = graphqlRubyFramework;

package/dist/hono.js

@@ -37,21 +37,15 @@ function honoFramework(_options = {}) {
     name: "hono",
     protocol: "http",
     languages: ["typescript", "javascript"],
-    // createRoute wraps its config without changing it; the call IS the
-    // route object. Declared here because the wrapper's body lives in
-    // the library, where nobody can read it.
+    // `createRoute` returns its config unchanged, so the call is the route
+    // object. The pack has to declare this because the function's body is
+    // in the library, where suss cannot read it.
     transparentWrappers: [
-      { callee: "createRoute", argument: 0, module: "@hono/zod-openapi" }
+      { module: "@hono/zod-openapi", name: "createRoute", argument: 0 }
     ],
-    // `new Hono()` and `new OpenAPIHono()` both register the same way.
-    // Sub-apps mounted with `app.route(prefix, sub)` compose the
-    // prefix into a route declared on the sub-app, following the sub-app
-    // through an import when it's declared in another file. A mount
-    // nested more than one level deep composes too, since the same
-    // index a mount resolves to is asked again for its own mount; a
-    // mount the resolution store can't follow to a concrete sub-app,
-    // or whose prefix isn't a string literal, leaves the route's path
-    // as written.
+    // A route on a sub-app mounted with `app.route(prefix, sub)` gets the
+    // prefix in front of its path, at any depth of nesting. The README
+    // covers the mounts that leave a path as written.
     discovery: [
       ...httpRouteDiscovery({
         importModule: "hono",
@@ -66,11 +60,9 @@ function honoFramework(_options = {}) {
         mount: { method: "route", prefixPosition: 0, targetPosition: 1 }
       }),
       {
-        // app.openapi(route, handler), where the route is a
-        // createRoute({ method, path, ... }) object that usually lives
-        // on a shared contract in another file. The fact layer follows
-        // the reference, and the route object has its own method and path on
-        // it.
+        // `app.openapi(route, handler)`, where the route is often a
+        // `createRoute({ method, path })` object in another file. The
+        // method and path come off that object.
         kind: "handler",
         match: {
           type: "registrationCall",
@@ -109,9 +101,9 @@ function honoFramework(_options = {}) {
       importNames: ["Hono", "OpenAPIHono"],
       methods: METHODS
     }),
-    // The createRoute object registered alongside the handler declares
-    // the endpoint's responses, so a handler returning a status the
-    // route never declares is a contract finding, not a style choice.
+    // The `createRoute` object lists the endpoint's responses, so a
+    // handler that returns a status missing from that list gets a
+    // contract finding.
     contractReading: {
       discovery: {
         importModule: "@hono/zod-openapi",
@@ -190,8 +182,8 @@ function honoFramework(_options = {}) {
         extraction: { defaultStatusCode: 404 }
       },
       {
-        // throw new HTTPException(status, { message }); hono sends the
-        // exception's status as the wire response.
+        // throw new HTTPException(status, { message }): Hono sends the
+        // exception's status as the response.
         kind: "throw",
         match: { type: "throwExpression" },
         extraction: {
@@ -203,14 +195,12 @@ function honoFramework(_options = {}) {
         producesResponse: true
       }
     ],
-    // One parameter, the context, carrying the request and the response
-    // methods together.
     inputMapping: {
       type: "positionalParams",
       params: [{ position: 0, role: "context" }]
     },
-    // `c.req.header("x-tenant-id")` puts the field in the argument, and
-    // a read records the method without it, so no read says which field.
+    // In `c.req.header("x-tenant-id")` the field is an argument, and the
+    // recorded read keeps only the method, so it loses which field it was.
     requestSpelling: {
       headers: { path: ["context", "req", "header"], saysWhichField: false },
       query: { path: ["context", "req", "query"], saysWhichField: false },

package/dist/httpx.js

@@ -25,11 +25,9 @@ function httpxClient() {
           methodKeyword: "method",
           urlPosition: 1
         },
-        // Both are written as a context manager as often as they are
-        // assigned, and the adapter reads a `with ... as` the same way.
         receiverConstructors: ["Client", "AsyncClient"],
-        // httpx spells the response the way requests does, which is
-        // deliberate on its part.
+        // httpx copies the requests response API, with `is_success` in
+        // place of `ok`.
         response: {
           statusCode: ["status_code"],
           success: ["is_success"],
@@ -38,7 +36,7 @@ function httpxClient() {
         }
       }
     ],
-    // Both classes document `__enter__` as giving back the client, so
+    // Both classes document `__enter__` as returning the client, so
     // `with httpx.Client() as c` puts the constructed client in c.
     contextManagers: [
       { module: "httpx", returnsSelf: ["Client", "AsyncClient"] }

package/dist/minitest.d.ts

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

package/dist/minitest.js

@@ -0,0 +1,59 @@
+// ../framework/minitest/dist/index.js
+import { z } from "zod";
+var optionsSchema = z.object({
+  /**
+   * The test files to read, matched on whole path segments from the
+   * end. `suss extract --intent` fills it in from the tests the PRDs
+   * list, so a run reads those files and no others. Left out, every
+   * `*_test.rb` file is read.
+   */
+  files: z.array(z.string().min(1)).optional()
+}).strict();
+var TEST_CASE_CLASSES = [
+  "Minitest::Test",
+  "ActiveSupport::TestCase",
+  "ActionDispatch::IntegrationTest",
+  "ActionDispatch::SystemTestCase",
+  "ActionController::TestCase",
+  "ActionMailer::TestCase",
+  "ActionView::TestCase",
+  "ActiveJob::TestCase",
+  "ActionCable::TestCase",
+  "ActionCable::Channel::TestCase",
+  "ActionCable::Connection::TestCase",
+  "Rails::Generators::TestCase"
+];
+function minitestFramework(options = {}) {
+  return {
+    name: "minitest",
+    protocol: "in-process",
+    discovery: [],
+    testClasses: [
+      {
+        filePatterns: ["*_test.rb"],
+        baseClassNames: TEST_CASE_CLASSES,
+        testMethodPrefix: "test_",
+        testBlockMethods: ["test"],
+        blockTestName: { prefix: "test_", spacesAs: "_" },
+        setupBlockMethods: ["setup"],
+        setupMethodNames: ["setup", "before_setup"],
+        skipStatements: ["skip"],
+        assertionPrefixes: ["assert", "refute", "must_", "wont_", "flunk"],
+        stubMethods: ["stub", "stubs", "expects"],
+        ...options.files !== void 0 ? { files: options.files } : {}
+      }
+    ]
+  };
+}
+var declares = {
+  kind: "framework",
+  package: "@suss/framework-minitest",
+  dependencies: [],
+  reads: "Minitest and Rails test cases (Ruby), named by class and test method, so a PRD scenario can say which test covers it."
+};
+var index_default = minitestFramework;
+export {
+  declares,
+  index_default as default,
+  optionsSchema
+};

package/dist/mongoose.js

@@ -97,9 +97,9 @@ var METHODS = {
   },
   findByIdAndDelete: { kind: "write", selector: BY_ID, fields: WHOLE_DOCUMENT },
   findOneAndReplace: { kind: "write", selector: filter(0), fields: payload(1) },
-  // A document can be changed after it was built, which this does not
-  // track, so a save is not reported as touching the fields the
-  // constructor happened to state.
+  // The pack does not track changes to a document after it is built, so
+  // the constructor's fields may be stale by the save. A save touches
+  // every field.
   save: { kind: "write", fields: WHOLE_DOCUMENT }
 };
 var MODEL_FACTORY = "model";
@@ -131,9 +131,9 @@ function pluralized(modelName) {
 }
 var optionsSchema = z.object({
   /**
-   * Scope label for the storage binding. Defaults to `"default"`. Set
-   * this when a project keeps more than one MongoDB connection and
-   * wants their accesses paired separately.
+   * Scope for the storage binding, `"default"` when unset. Set it when a
+   * project has more than one MongoDB connection and their accesses
+   * should pair separately.
    */
   scope: scopeOption.optional()
 }).strict();
@@ -156,7 +156,7 @@ var declares = {
   kind: "effects",
   package: "@suss/framework-mongoose",
   dependencies: [{ ecosystem: "npm", name: "mongoose" }],
-  reads: `Mongoose model calls, emits storage-access interactions against the collection a model's \`.model(...)\` call declares.`
+  reads: `Mongoose model calls. Each one becomes a storage-access interaction on the collection that the model's \`.model(...)\` call declares.`
 };
 var index_default = mongooseFramework;
 export {

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 },