@suluk/testgen 0.1.0 → 0.1.2

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.2",
   "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.13"
   },
   "peerDependencies": {
     "@cfworker/json-schema": "^4.1.1"
@@ -31,7 +31,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@suluk/stripe": "^0.1.2"
+    "@suluk/payments": "^0.1.0"
   },
   "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/src/index.ts

@@ -4,5 +4,5 @@
  * conform to their schemas, declared costs are well-formed. A pure function of the document. CANDIDATE tooling.
  */
 export { generateTests, type TestgenOptions } from "./generate";
-// money-correctness conformance (PARITY §2 checkout-resilience over the @suluk/stripe pricing primitives).
+// money-correctness conformance (PARITY §2 checkout-resilience over the @suluk/payments pricing primitives).
 export { generateMoneyTests, type MoneyTestsOptions } from "./money";

package/src/money.ts

@@ -1,6 +1,6 @@
 /**
  * generateMoneyTests — PARITY §2 "Checkout & E-commerce Resilience" made an EXECUTABLE, in-process conformance
- * suite over the @suluk/stripe pricing primitives (saastarter-parity Phase 0). Unlike the wire conformance suite,
+ * suite over the @suluk/payments pricing primitives (saastarter-parity Phase 0). Unlike the wire conformance suite,
  * the money invariants are properties of the SHARED, app-independent primitives (there is nothing in a v4 document
  * to walk for verifyAmount) — so this is a separate emitter that produces a self-contained `bun test` file an app
  * commits + runs. No network, no app coupling, no document input.
@@ -8,14 +8,14 @@
  * Provenance note (honesty, adopt-by-receipt): the anti-tampering + integer-cents + never-over-discount invariants
  * are faithful encodings of saastarter's checkout intent. The exact-sum proration + deterministic-idempotency
  * invariants are STRONGER than saastarter's actual code (PARITY records a real cart/order proration drift bug and
- * an ad-hoc retry path) — they assert what @suluk/stripe was authored to GUARANTEE, an origination inspired by the
+ * an ad-hoc retry path) — they assert what @suluk/payments was authored to GUARANTEE, an origination inspired by the
  * parity goal, not a behavioral port. The generated header says so.
  */
 
 export interface MoneyTestsOptions {
   /** which runner's imports to emit (both share test/expect/describe). Default "bun". */
   framework?: "bun" | "vitest";
-  /** the import specifier for the pricing primitives. Default "@suluk/stripe". */
+  /** the import specifier for the pricing primitives. Default "@suluk/payments". */
   stripeModule?: string;
 }
 
@@ -24,16 +24,16 @@ export function generateMoneyTests(opts: MoneyTestsOptions = {}): string {
   const importLine = opts.framework === "vitest"
     ? `import { test, expect, describe } from "vitest";`
     : `import { test, expect, describe } from "bun:test";`;
-  const mod = opts.stripeModule ?? "@suluk/stripe";
+  const mod = opts.stripeModule ?? "@suluk/payments";
 
   return `/**
  * Checkout money-correctness — CONFORMANCE suite. AUTO-GENERATED by @suluk/testgen. Do not edit.
  *
- * PARITY §2 "Checkout & E-commerce Resilience" made executable over the @suluk/stripe pricing primitives — the
+ * PARITY §2 "Checkout & E-commerce Resilience" made executable over the @suluk/payments pricing primitives — the
  * arithmetic that separates a toy cart from one you'd trust with money. In-process, no network: it asserts the
  * SHARED primitives uphold the invariants, so the cart-drawer total and the order-summary total can never drift.
  *
- * Honesty: the exact-sum proration + deterministic-idempotency checks assert what @suluk/stripe GUARANTEES — they
+ * Honesty: the exact-sum proration + deterministic-idempotency checks assert what @suluk/payments GUARANTEES — they
  * are stronger than saastarter's actual impl (which has a known proration-drift bug), an origination inspired by
  * the parity goal rather than a behavioral port.
  *

package/test/testgen.test.ts

@@ -1,6 +1,6 @@
 import { test, expect, describe } from "bun:test";
 import { generateTests, generateMoneyTests } from "../src/index";
-import { orderTotal, verifyAmount, prorateDiscount, idempotencyKey } from "@suluk/stripe";
+import { orderTotal, verifyAmount, prorateDiscount, idempotencyKey } from "@suluk/payments";
 import type { OpenAPIv4Document } from "@suluk/core";
 
 const doc = {
@@ -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");
@@ -79,9 +87,9 @@ describe("@suluk/testgen — generate a conformance suite from a v4 contract", (
 describe("@suluk/testgen — generateMoneyTests (PARITY §2 checkout-resilience, in-process)", () => {
   const money = generateMoneyTests();
 
-  test("emits a self-contained bun:test suite importing the @suluk/stripe primitives", () => {
+  test("emits a self-contained bun:test suite importing the @suluk/payments primitives", () => {
     expect(money).toContain('import { test, expect, describe } from "bun:test"');
-    expect(money).toContain('} from "@suluk/stripe"');
+    expect(money).toContain('} from "@suluk/payments"');
     expect(money).toContain("verifyAmount");
     expect(money).toContain("prorateDiscount");
     expect(money).toContain("idempotencyKey");
@@ -106,8 +114,8 @@ describe("@suluk/testgen — generateMoneyTests (PARITY §2 checkout-resilience,
   });
 });
 
-// Smoke (closes the loop): the invariants the emitter ENCODES actually hold for the real @suluk/stripe build.
-describe("@suluk/testgen — money smoke against the real @suluk/stripe primitives", () => {
+// Smoke (closes the loop): the invariants the emitter ENCODES actually hold for the real @suluk/payments build.
+describe("@suluk/testgen — money smoke against the real @suluk/payments primitives", () => {
   test("verifyAmount rejects tampering; proration sums exactly; idempotency is deterministic", () => {
     const lines = [{ unitCents: 1999, qty: 2, id: "a" }, { unitCents: 500, qty: 1, id: "b" }, { unitCents: 333, qty: 3 }];
     const exact = orderTotal(lines, null).totalCents;