@suss/packs 0.33.0 → 0.34.0

package/dist/react-router.js

@@ -45,12 +45,12 @@ var JSX_ROUTES = {
 };
 var optionsSchema = z.object({
   /**
-   * Helpers this project throws HTTP errors through, as
-   * `throw myHelper(new HttpError.NotFound(), body)`. React Router
-   * declares no such helper, so nothing is assumed by default and a
-   * project that installs this pack never matches a call on a name some
-   * other codebase happened to use. The thrown argument's class name
-   * gives the status, read against the `http-errors` constructors.
+   * Helpers this project throws HTTP errors through, as in
+   * `throw myHelper(new HttpError.NotFound(), body)`. React Router has
+   * no such helper, so the list is empty by default, and the pack never
+   * matches a call on a name another codebase happened to use. The
+   * status comes from the class name of the thrown argument, looked up
+   * in the `http-errors` constructors.
    */
   errorHelpers: z.array(z.string()).optional()
 }).strict();
@@ -62,32 +62,16 @@ function reactRouterFramework(options = {}) {
     discovery: [
       {
         kind: "loader",
+        // The README explains why no route comes from the file name.
         match: { type: "namedExport", names: ["loader"] },
-        // No route derived from the filename. React Router only
-        // reads routes that way when the project opted in by
-        // importing @react-router/fs-routes, and the pack language
-        // has no way to say "only when that import is there". A
-        // loader whose route came out of a guess pairs with whatever
-        // consumer matches the guess, which is worse than pairing
-        // with nothing.
-        // Empty gate: route files often re-export `loader` /
-        // `action` from non-router-importing modules
-        // (server-side data functions, shared util re-exports).
-        // A heuristic gate would miss those. The dispatch only
-        // looks at named exports, so paying for the walk on
-        // every file is fine.
+        // Route files often re-export `loader` and `action` from modules
+        // that never import the router. The match reads only named
+        // exports, so running it on every file costs little.
         requiresImport: []
       },
       {
         kind: "action",
         match: { type: "namedExport", names: ["action"] },
-        // No route derived from the filename. React Router only
-        // reads routes that way when the project opted in by
-        // importing @react-router/fs-routes, and the pack language
-        // has no way to say "only when that import is there". A
-        // loader whose route came out of a guess pairs with whatever
-        // consumer matches the guess, which is worse than pairing
-        // with nothing.
         requiresImport: []
       },
       {
@@ -96,10 +80,9 @@ function reactRouterFramework(options = {}) {
         requiresImport: []
       },
       {
-        // The route tree the app declares in its own JSX, which is how
-        // most React Router apps say what serves which URL. Gated on
-        // the router import, since the whole pattern is written with
-        // names that come out of it.
+        // Most React Router apps declare their routes in JSX. Every name
+        // this pattern matches comes from the router, so it needs the
+        // router import.
         kind: "component",
         match: JSX_ROUTES,
         requiresImport: ROUTER_MODULES
@@ -112,9 +95,8 @@ function reactRouterFramework(options = {}) {
         match: {
           type: "functionCall",
           functionName: "json",
-          // These names come from the router, so a same-named helper
-          // the project wrote is a different function, with its own
-          // argument order, and must not match.
+          // A project helper with the same name may order its arguments
+          // differently, so only the router's own helpers match.
           requiresImport: RESPONSE_MODULES
         },
         extraction: {
@@ -128,9 +110,6 @@ function reactRouterFramework(options = {}) {
         match: {
           type: "functionCall",
           functionName: "data",
-          // These names come from the router, so a same-named helper
-          // the project wrote is a different function, with its own
-          // argument order, and must not match.
           requiresImport: RESPONSE_MODULES
         },
         extraction: {
@@ -144,9 +123,6 @@ function reactRouterFramework(options = {}) {
         match: {
           type: "functionCall",
           functionName: "redirect",
-          // These names come from the router, so a same-named helper
-          // the project wrote is a different function, with its own
-          // argument order, and must not match.
           requiresImport: RESPONSE_MODULES
         },
         extraction: {
@@ -155,25 +131,22 @@ function reactRouterFramework(options = {}) {
         }
       },
       {
-        // What a routed component renders. The route says which
-        // URL reaches this component, and the JSX it returns is what
-        // that URL renders, so the pack reads both rather than
-        // reporting the route and nothing behind it.
+        // The route gives the URL and the returned JSX gives what that
+        // URL renders, so a routed component records both.
         kind: "render",
         match: { type: "jsxReturn" },
         extraction: {}
       },
       {
-        // Loaders return data directly
+        // A loader can return plain data without a helper.
         kind: "return",
         match: { type: "returnShape" },
         extraction: {
           body: { from: "argument", position: 0 }
         }
       },
-      // A project's error helper puts the status in the class name of its
-      // argument, so resolve through `argumentConstructor` rather
-      // than taking the argument's raw source text as a status value.
+      // The status is in the class name of the helper's argument, so it is
+      // read through `argumentConstructor`.
       ...(options.errorHelpers ?? []).map((helper) => ({
         kind: "throw",
         match: {
@@ -209,7 +182,7 @@ var declares = {
     { ecosystem: "npm", name: "react-router" },
     { ecosystem: "npm", name: "react-router-dom" }
   ],
-  reads: "React Router loaders / actions / routes."
+  reads: "React Router loaders, actions and routes."
 };
 var index_default = reactRouterFramework;
 export {

package/dist/react.js

@@ -182,8 +182,8 @@ function disambiguateHandlers(raw, componentName) {
       kind: "handler",
       name,
       inputMapping: EVENT_HANDLER_INPUT,
-      // The element and prop a handler hangs off already shape the
-      // summary name; no reader consumes them as metadata (#462).
+      // The element and prop are already in the summary name, and nothing
+      // reads them from metadata (#462).
       metadata: {
         react: {
           kind: "handler",
@@ -226,8 +226,8 @@ function synthesizeUseEffects(componentName, parentFunc, ctx) {
           kind: "effect",
           component: componentName,
           index,
-          // `null` deps means the second argument was absent
-          // (re-runs every render); `[]` means mount-only.
+          // `null` means no deps argument, so the effect runs after every
+          // render. `[]` means it runs on mount only.
           deps
         }
       }
@@ -236,6 +236,7 @@ function synthesizeUseEffects(componentName, parentFunc, ctx) {
   }
   return out;
 }
+var PASS_THROUGH = ["useCallback", "memo", "forwardRef"];
 function reactFramework() {
   return {
     name: "react",
@@ -297,6 +298,14 @@ function reactFramework() {
       type: "componentProps",
       paramPosition: 0
     },
+    // Each hands back the function it was given, so a call through the
+    // result runs that function. `useMemo` and `lazy` are left out: one
+    // returns what its argument returns, the other a module's export.
+    transparentWrappers: PASS_THROUGH.map((name) => ({
+      module: "react",
+      name,
+      argument: 0
+    })),
     subUnits: reactSubUnits,
     discoverUnits: (sourceFile, ctx) => [
       ...reactComponentExports(sourceFile, ctx),
@@ -308,7 +317,7 @@ var declares = {
   kind: "framework",
   package: "@suss/framework-react",
   dependencies: [{ ecosystem: "npm", name: "react" }],
-  reads: "React function components, event handlers, `useEffect` bodies."
+  reads: "React function components, event handlers and `useEffect` bodies."
 };
 var index_default = reactFramework;
 export {

package/dist/redis.js

@@ -95,7 +95,7 @@ var declares = {
     { ecosystem: "npm", name: "iovalkey" },
     { ecosystem: "npm", name: "redis" }
   ],
-  reads: "Redis, Valkey and node-redis commands, emits storage-access interactions."
+  reads: "Redis, Valkey and node-redis commands. Each one becomes a storage-access interaction."
 };
 var index_default = redisFramework;
 export {

package/dist/requests.js

@@ -18,9 +18,8 @@ function requestsClient() {
         type: "clientCall",
         importModule: ["requests"],
         verbAttributeNames: VERB_FUNCTIONS,
-        // Every one of them takes the URL first, and `url=` is the
-        // keyword for all of them but `request`, which takes `url`
-        // second and still calls it that.
+        // The verb functions take the URL first and `request` takes it
+        // second. All of them accept it as `url=`.
         url: { position: 0, keyword: "url" },
         methodCall: {
           attribute: "request",
@@ -29,8 +28,8 @@ function requestsClient() {
           urlPosition: 1
         },
         receiverConstructors: ["Session"],
-        // What a caller reads off the response it got back. A test on
-        // one of these says which statuses the caller handles.
+        // A caller's condition on one of these members shows which
+        // statuses it handles.
         response: {
           statusCode: ["status_code"],
           success: ["ok"],

package/dist/rspec.d.ts

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

package/dist/rspec.js

@@ -0,0 +1,135 @@
+// ../framework/rspec/dist/index.js
+import { z } from "zod";
+var optionsSchema = z.object({
+  /**
+   * The spec 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
+   * `*_spec.rb` file is read.
+   */
+  files: z.array(z.string().min(1)).optional()
+}).strict();
+var RUNNER_METHODS = [
+  "expect",
+  "is_expected",
+  "allow",
+  "allow_any_instance_of",
+  "expect_any_instance_of",
+  "receive",
+  "receive_messages",
+  "have_received",
+  "double",
+  "instance_double",
+  "class_double",
+  "object_double",
+  "spy",
+  "instance_spy",
+  "stub_const",
+  "eq",
+  "eql",
+  "equal",
+  "be",
+  "be_a",
+  "be_an",
+  "be_nil",
+  "be_truthy",
+  "be_falsey",
+  "be_within",
+  "include",
+  "match",
+  "match_array",
+  "contain_exactly",
+  "raise_error",
+  "change",
+  "have_attributes",
+  "an_instance_of",
+  "a_kind_of",
+  "anything",
+  "hash_including",
+  "satisfy",
+  "output",
+  "all"
+];
+function rspecFramework(options = {}) {
+  return {
+    name: "rspec",
+    protocol: "in-process",
+    discovery: [],
+    tests: [
+      {
+        filePatterns: ["*_spec.rb"],
+        receiver: "RSpec",
+        groupNames: ["describe", "context", "feature", "example_group"],
+        skippedGroupNames: ["xdescribe", "xcontext", "xfeature"],
+        sharedGroupNames: [
+          "shared_examples",
+          "shared_examples_for",
+          "shared_context"
+        ],
+        sharedIncludes: [
+          { method: "it_behaves_like", nestedTitle: "behaves like" },
+          {
+            method: "it_should_behave_like",
+            nestedTitle: "it should behave like"
+          },
+          { method: "include_examples" },
+          { method: "include_context" }
+        ],
+        exampleNames: ["it", "specify", "example", "scenario", "its"],
+        skippedExampleNames: [
+          "xit",
+          "xspecify",
+          "xexample",
+          "xscenario",
+          "skip",
+          "pending"
+        ],
+        skipStatements: ["skip", "pending"],
+        skipMetadata: ["skip"],
+        beforeHooks: ["before", "prepend_before", "append_before"],
+        lazyValues: ["let"],
+        eagerValues: ["let!"],
+        subjectNames: { lazy: ["subject"], eager: ["subject!"] },
+        subjectReads: ["subject", "is_expected"],
+        subjectValue: "subject",
+        describedClass: "described_class",
+        runnerMethods: RUNNER_METHODS,
+        predicateMatchers: [
+          { prefix: "be_", methodPrefix: "", methodSuffix: "?" },
+          { prefix: "have_", methodPrefix: "has_", methodSuffix: "?" }
+        ],
+        expectations: {
+          starts: ["expect"],
+          onSubject: "is_expected",
+          runs: ["to", "not_to", "to_not"]
+        },
+        mocks: {
+          targets: [
+            "allow",
+            "expect",
+            "allow_any_instance_of",
+            "expect_any_instance_of"
+          ],
+          expectations: ["to", "not_to", "to_not"],
+          messages: ["receive", "receive_messages"],
+          constantStubs: ["stub_const"],
+          doubles: ["instance_double", "class_double"],
+          constantDoubleMethod: "as_stubbed_const"
+        },
+        ...options.files !== void 0 ? { files: options.files } : {}
+      }
+    ]
+  };
+}
+var declares = {
+  kind: "framework",
+  package: "@suss/framework-rspec",
+  dependencies: [],
+  reads: "RSpec examples, named by their group titles, so a PRD scenario can say which test covers it."
+};
+var index_default = rspecFramework;
+export {
+  declares,
+  index_default as default,
+  optionsSchema
+};

package/dist/sqlalchemy.js

@@ -2,7 +2,7 @@ import {
   declares,
   index_default,
   optionsSchema
-} from "./chunk-NYWZHQBJ.js";
+} from "./chunk-GK4BILHB.js";
 export {
   declares,
   index_default as default,

package/dist/sqlmodel.js

@@ -2,16 +2,15 @@ import {
   sqlalchemyModels,
   sqlalchemyRawSql,
   sqlalchemyStorage
-} from "./chunk-NYWZHQBJ.js";
+} from "./chunk-GK4BILHB.js";
 
 // ../framework/sqlmodel/dist/index.js
 import { z } from "zod";
 import { storageSystemOption } from "@suss/extractor";
 var optionsSchema = z.object({
   /**
-   * Which database is behind the engine. SQLModel talks to all of them
-   * and the URL says which, so this is the project's own choice rather
-   * than something the library settles.
+   * Which database is behind the engine. SQLModel works with several,
+   * and the connection URL picks one, so the project has to set this.
    */
   storageSystem: storageSystemOption
 }).strict();
@@ -60,9 +59,9 @@ function sqlmodelStorage(options) {
       module: "sqlmodel",
       queryTypes: ["Select", "SelectOfScalar", "Update", "Delete", "Insert"],
       writes: ["update", "delete", "insert", "commit"],
-      // `select(Item).where(...)` imports the constructor from the package
-      // root, so there is no project method in between whose return says
-      // what it is.
+      // `select(Item).where(...)` calls a constructor imported from the
+      // package root, so there is no project method in the chain whose
+      // return type the adapter could read.
       queryFunctions: ["select", "insert", "update", "delete"],
       valueMethods: ["values"],
       storageSystem: options.storageSystem
@@ -114,7 +113,7 @@ var declares = {
   kind: "effects",
   package: "@suss/framework-sqlmodel",
   dependencies: [{ ecosystem: "pypi", name: "sqlmodel" }],
-  reads: "SQLModel calls (Python): says which types a query comes back as and which methods write, under the modules SQLModel exports them from, and includes the SQLAlchemy patterns a SQLModel project also reaches.",
+  reads: "SQLModel calls (Python). The pack declares which types a query returns and which methods write, under the modules SQLModel exports them from. It also includes the SQLAlchemy patterns, since a SQLModel project reaches those too.",
   configuration: {
     file: "suss.sqlmodel.json",
     example: { storageSystem: "postgresql" },

package/dist/ts-rest.js

@@ -17,10 +17,8 @@ function tsRestFramework() {
           method: { type: "fromContract" },
           path: { type: "fromContract" }
         },
-        // Pre-filter to ts-rest server callers. The `@ts-rest/`
-        // prefix sweeps any of the framework's adapters in one
-        // go (`@ts-rest/express` / `@ts-rest/fastify` /
-        // `@ts-rest/nest` / etc.).
+        // The `@ts-rest` prefix matches every server adapter, such as
+        // `@ts-rest/express` and `@ts-rest/fastify`.
         requiresImport: ["@ts-rest"]
       },
       {
@@ -50,9 +48,9 @@ function tsRestFramework() {
           body: { from: "property", name: "body" }
         }
       },
-      // A consumer of a ts-rest client finishes the way any function
-      // does, by returning or throwing. Without these two it matches
-      // no terminal at all and its summary says nothing.
+      // A function that uses a ts-rest client ends by returning or
+      // throwing. Without these two it would not match any terminal, and
+      // its summary would have no transitions.
       { kind: "return", match: { type: "returnStatement" }, extraction: {} },
       { kind: "throw", match: { type: "throwExpression" }, extraction: {} }
     ],
@@ -87,7 +85,7 @@ var declares = {
   kind: "framework",
   package: "@suss/framework-ts-rest",
   dependencies: [{ ecosystem: "npm", name: "@ts-rest/core" }],
-  reads: "ts-rest providers + clients (contract-backed)."
+  reads: "ts-rest handlers and clients, and the contract both sides are built from."
 };
 var index_default = tsRestFramework;
 export {

package/dist/typeorm.d.ts

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