@suluk/testgen 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,141 @@
+# @suluk/testgen
+
+**Generate a deterministic conformance test suite from a v4 "Suluk" contract — the contract's claims, made executable.**
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```bash
+bun add @suluk/testgen @cfworker/json-schema
+```
+
+`@cfworker/json-schema` is a peer dependency — the *generated* suite imports it to validate response
+bodies against their declared schemas. `generateMoneyTests` additionally targets `@suluk/stripe` (the
+emitted suite imports the pricing primitives from there).
+
+## What it does
+
+`generateTests(doc)` walks a v4 document and emits a **self-contained test file** (a string) that runs
+against a live deployment. It turns the `x-suluk-*` facets from decoration into load-bearing claims:
+
+- **Access enforcement, on the real wire.** A non-public op must DENY anon a success; a public op must be
+  reachable by anon. `x-suluk-access` is only the *expectation* — the test passes iff the wire agrees. It
+  never asserts over a projection and never treats the facet as if it were the enforcement (C022 inv.3).
+- **Status smoke + schema conformance.** A public, parameter-free GET returns a *declared* status, and its
+  2xx body validates against the declared response schema (same generic JSON-Schema engine the SDK uses).
+- **Error-conformance.** A denied request returns a well-formed RFC-9457 Problem Details body (the shared
+  `@suluk/hono` envelope: `title` string + `status` matching the HTTP status).
+- **Cost declared.** Every op that prices itself declares a well-formed `x-suluk-cost` — checked statically,
+  never as a literal µ$ amount (which would couple tests to billing internals and go flaky).
+
+A **pure function of the document**: same contract in, same suite out, no network at generate-time. Each op's
+tests are labelled with its provenance (`x-suluk-source`) so a failure points at the authoring source.
+
+`generateMoneyTests()` is a separate emitter for the money path — an in-process suite over the `@suluk/stripe`
+pricing primitives (anti-tampering, integer-cents, never-over-discount, exact proration, deterministic
+idempotency). It takes no document; the invariants live in the shared primitives, not in any one contract.
+
+## When to reach for it
+
+Reach for it whenever you want the contract's facets to *mean something* — this is what makes `x-suluk-*`
+enforced rather than aspirational. The common pattern is to expose the generated suite as a download endpoint
+so any consumer can verify your deployment honours its own contract (see Usage). Add `generateMoneyTests` when
+your app touches checkout/billing through `@suluk/stripe`.
+
+This is a **generator**, not a runner: it produces a `bun:test` (or `vitest`) file you run yourself. It is the
+testing facet of the projection model — siblings like `@suluk/scalar` / `@suluk/swagger` *render* the contract;
+`@suluk/sdk` *generates a client*; this generates the *conformance proof*.
+
+## Usage
+
+### Generate a conformance suite from a v4 document
+
+```ts
+import { generateTests } from "@suluk/testgen";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+const suite = generateTests(document, { baseURL: "https://api.example.com" });
+// → a self-contained test-file string. Write it next to your tests and run it:
+await Bun.write("api.conformance.test.ts", suite);
+```
+
+Run the emitted suite against a deployment — `SULUK_BASE_URL` wins over the baked-in `baseURL`:
+
+```bash
+SULUK_BASE_URL=https://api.example.com bun test api.conformance.test.ts
+```
+
+Optional positive-side checks (a non-public op also asserting a *valid* principal IS allowed through) are
+skipped unless you provide **synthetic** principal tokens — never a production credential:
+
+```bash
+SULUK_ADMIN_TOKEN=… SULUK_USER_TOKEN=… bun test api.conformance.test.ts
+```
+
+### Serve it as a download endpoint (real saasuluk usage)
+
+```ts
+import { generateTests } from "@suluk/testgen";
+
+app.get("/conformance.test.ts", (c) =>
+  new Response(generateTests(document, { baseURL: new URL(c.req.url).origin }), {
+    headers: {
+      "content-type": "application/typescript; charset=utf-8",
+      "content-disposition": 'attachment; filename="api.conformance.test.ts"',
+    },
+  }),
+);
+```
+
+### Options
+
+```ts
+generateTests(document, {
+  baseURL: "https://api.example.com", // baked default; SULUK_BASE_URL overrides at run-time
+  framework: "vitest",                // "bun" (default) | "vitest" — toggles the emitted imports
+});
+```
+
+### Money-correctness suite
+
+```ts
+import { generateMoneyTests } from "@suluk/testgen";
+
+const money = generateMoneyTests();                 // imports primitives from "@suluk/stripe"
+await Bun.write("money.conformance.test.ts", money);
+// then: bun test money.conformance.test.ts (no network, in-process)
+
+// configurable runner + import specifier:
+generateMoneyTests({ framework: "vitest", stripeModule: "../pricing" });
+```
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `generateTests(doc, opts?)` | Emit a wire-conformance suite (access / status / schema / cost) from a v4 document, as a test-file string. |
+| `generateMoneyTests(opts?)` | Emit an in-process money-correctness suite over the `@suluk/stripe` pricing primitives. |
+| `TestgenOptions` | `{ baseURL?: string; framework?: "bun" \| "vitest" }`. |
+| `MoneyTestsOptions` | `{ framework?: "bun" \| "vitest"; stripeModule?: string }`. |
+
+## Boundary
+
+This package **generates, never hosts** (L3). It is a pure string-emitter: no network at generate-time, no
+deployment of its own. The seams it leaves to the app:
+
+- **The deployment under test** is injected via `SULUK_BASE_URL` (or the baked `baseURL`) at *run*-time — the
+  generated suite reads it from the environment.
+- **Authorization is the server's job.** The access tests assert the *wire* enforces `x-suluk-access`; this
+  never re-implements authz, and never asserts over a projection (C022 inv.3 — the server is the only boundary).
+- **Synthetic principals** for the optional positive-side checks come from you (`SULUK_*_TOKEN`), out of band.
+- **Running** the emitted file is the app's responsibility (`bun test`); you decide where to write it and when
+  to run it in CI.
+
+Contributing: a new facet means a new asserted claim here — that is what keeps `x-suluk-*` load-bearing.
+
+## License
+
+Apache-2.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/testgen",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Generate a DETERMINISTIC conformance test suite from a v4 'Suluk' contract — the executable form of the contract's claims. Asserts the SERVER ENFORCES x-suluk-access on the real wire (anon rejected on non-public ops; public ops reachable), smoke-tests declared statuses, validates 2xx bodies against their declared schemas, and checks every declared cost is well-formed. A pure function of the document — same contract in, same suite out, no network at generate-time. CANDIDATE tooling.",
   "publishConfig": {
     "access": "public"
@@ -19,7 +19,7 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@suluk/core": "^0.1.7"
+    "@suluk/core": "^0.1.11"
   },
   "peerDependencies": {
     "@cfworker/json-schema": "^4.1.1"
@@ -31,7 +31,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@suluk/stripe": "^0.1.2"
+    "@suluk/stripe": "^0.1.7"
   },
   "scripts": {
     "test": "bun test",

package/src/generate.ts

@@ -22,10 +22,13 @@ interface RawReq {
   parameterSchema?: { path?: unknown; query?: unknown; body?: unknown };
   responses?: Record<string, { status: string | number; contentSchema?: unknown }>;
   ["x-suluk-cost"]?: CostModel; ["x-suluk-access"]?: AccessFacet; ["x-suluk-source"]?: SulukSource;
+  ["x-suluk-approval"]?: { required?: unknown; reason?: unknown };
 }
 interface OpInfo {
   name: string; method: string; uri: string; filledPath: string; requires: string;
   declaredStatuses: number[]; okSchema?: unknown; cost: number | null; source?: SulukSource;
+  /** the raw x-suluk-approval.required when the HITL facet is present (else null) — checked WELL-FORMED, statically. */
+  approvalRequired: unknown; hasApproval: boolean;
   hasBody: boolean; paramFree: boolean;
 }
 
@@ -52,6 +55,7 @@ function walkOps(doc: OpenAPIv4Document): OpInfo[] {
         requires: req["x-suluk-access"]?.requires ?? "anyone",
         declaredStatuses: [...new Set(statuses)].sort((a, b) => a - b),
         okSchema: ok?.contentSchema, cost: costOf(req), source: req["x-suluk-source"],
+        approvalRequired: req["x-suluk-approval"]?.required, hasApproval: req["x-suluk-approval"] != null,
         hasBody: req.contentSchema != null || ps.body != null,
         paramFree: method === "GET" && !hasPathParam && reqQuery.length === 0,
       });
@@ -132,6 +136,13 @@ function emitOp(doc: OpenAPIv4Document, op: OpInfo): string {
     expect(Number.isFinite(${op.cost}) && ${op.cost} >= 0, "x-suluk-cost is malformed").toBe(true);
   });`);
 
+  // ── L2 (static): a declared HITL gate is well-formed. x-suluk-approval is an AGENT-RUNTIME facet (it projects to the
+  //    Agents SDK `needsApproval`), NOT wire-enforced like x-suluk-access — so, like cost, the conformance claim is the
+  //    static well-formedness (`required` is a boolean), which keeps the facet load-bearing (it can't silently malform).
+  if (op.hasApproval) tests.push(`  test("approval — declares a well-formed x-suluk-approval HITL gate (static; enforced by the agent runtime, not the wire)", () => {
+    expect(typeof ${JSON.stringify(op.approvalRequired)} === "boolean", "x-suluk-approval.required must be a boolean").toBe(true);
+  });`);
+
   return `describe("${lbl(head)}", () => {\n${tests.join("\n")}\n});`;
 }
 

package/test/testgen.test.ts

@@ -10,7 +10,7 @@ const doc = {
     product: {
       requests: {
         listProduct: { method: "get", responses: { ok: { status: 200, contentSchema: { type: "array", items: { type: "object", properties: { id: { type: "integer" } }, required: ["id"], additionalProperties: false } } } }, "x-suluk-access": { requires: "anyone" }, "x-suluk-cost": { estimateMicroUsd: 10 }, "x-suluk-source": { file: "src/schema.ts", symbol: "product", kind: "drizzle-table" } },
-        createProduct: { method: "post", contentSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] }, responses: { created: { status: 201 } }, "x-suluk-access": { requires: "admin" }, "x-suluk-cost": { estimateMicroUsd: 145 }, "x-suluk-source": { file: "src/schema.ts", symbol: "product", kind: "drizzle-table" } },
+        createProduct: { method: "post", contentSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] }, responses: { created: { status: 201 } }, "x-suluk-access": { requires: "admin" }, "x-suluk-cost": { estimateMicroUsd: 145 }, "x-suluk-approval": { required: true, reason: "creates a billable product" }, "x-suluk-source": { file: "src/schema.ts", symbol: "product", kind: "drizzle-table" } },
       },
     },
     "cart/{id}": { requests: { getCart: { method: "get", responses: { ok: { status: 200 } }, "x-suluk-access": { requires: "authenticated", scope: "owner" }, "x-suluk-source": { file: "src/ops.ts", symbol: "getCart", kind: "operation" } } } },
@@ -59,6 +59,14 @@ describe("@suluk/testgen — generate a conformance suite from a v4 contract", (
     expect(suite).not.toMatch(/toBe\(145\)/);                    // never asserts the literal amount
   });
 
+  test("x-suluk-approval (HITL) is checked as a DECLARED well-formed gate — static, NOT wire-enforced (it's an agent-runtime facet)", () => {
+    expect(suite).toContain("declares a well-formed x-suluk-approval HITL gate");
+    expect(suite).toContain("enforced by the agent runtime, not the wire"); // honest scope — unlike x-suluk-access
+    expect(suite).toContain('typeof true === "boolean"');                    // the static well-formedness assertion on `required`
+    // only the op that declares it gets the claim; a non-gated op (listProduct) does not
+    expect(suite.match(/well-formed x-suluk-approval/g)?.length).toBe(1);
+  });
+
   test("each op group is LABELLED with its provenance (x-suluk-source) — a failure points at the source", () => {
     expect(suite).toContain("createProduct  [POST product]  · admin  ←  src/schema.ts#product");
     expect(suite).toContain("getCart  [GET cart/{id}]  · authenticated  ←  src/ops.ts#getCart");