@fougere/testing 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/comparison.ts

@@ -6,13 +6,7 @@ import { lowerFirst, type SchemaView } from '@fougere/schema';
 import { listQuery, findQuery, mutationFor, at } from './gql.js';
 import { sampleInput, type SampleOptions } from './sample.js';
 
-/**
- * The rows a door hands back, with its own envelope taken off.
- *
- * Each door wraps differently by construction — REST answers a page, GraphQL nests under
- * its field, RPC returns the value — and comparing the wrappers would compare the
- * protocols. What must agree is what is inside.
- */
+/** The rows a door hands back, with its own envelope taken off. */
 function rowsOf(value: unknown): unknown {
   if (Array.isArray(value)) return [...value];
   const page = value as { items?: unknown } | null;
@@ -22,13 +16,7 @@ function rowsOf(value: unknown): unknown {
 /** Through the wire and back, so a `Date` and its ISO string are not read as a divergence. */
 const wire = (value: unknown): unknown => JSON.parse(JSON.stringify(value ?? null));
 
-/**
- * What is the SAME row seen twice, and what is merely a second row.
- *
- * A write creates a different row at each door — different id, different `createdAt` —
- * so comparing values would compare clocks. The generated fields are dropped and what the
- * caller sent is what remains, which is the part the doors must agree on.
- */
+/** What is the SAME row seen twice, and what is merely a second row. */
 function written(value: unknown, sent: Record<string, unknown>): unknown {
   const row = value as Record<string, unknown> | null;
   if (!row || typeof row !== 'object') return wire(row);
@@ -42,13 +30,13 @@ export interface DoorOptions extends SampleOptions {
 }
 
 interface Doors {
-  local: (op: string, input?: DoorInput) => Promise<unknown>;
-  rpc: (op: string, input?: DoorInput) => Promise<unknown>;
-  rest: (op: string, input?: DoorInput) => Promise<unknown>;
-  graphql: (op: string, input?: DoorInput) => Promise<unknown>;
+  local: (op: string, call?: DoorInput) => Promise<unknown>;
+  rpc: (op: string, call?: DoorInput) => Promise<unknown>;
+  rest: (op: string, call?: DoorInput) => Promise<unknown>;
+  graphql: (op: string, call?: DoorInput) => Promise<unknown>;
 }
 
-export interface DoorInput { id?: string; body?: Record<string, unknown> }
+export interface DoorInput { id?: string; input?: Record<string, unknown> }
 
 export interface DoorContractCase {
   /** What this case proves — becomes the test name. */
@@ -60,28 +48,17 @@ export interface DoorContractCase {
   expected: unknown;
 }
 
-/**
- * One entity, four doors, the same answers.
- *
- * The claim runs through the whole repo — a frond runs in-process or behind JSON-RPC with
- * identical user code, and REST, GraphQL and RPC are three projections of one contract —
- * and nothing compared REST to GraphQL until now. `transport-swap.test.ts` compares three
- * TRANSPORTS, which is a different sentence.
- *
- * The five CRUD operations, reads and writes. A CUSTOM op is not compared: REST addresses
- * it by a path the table states, GraphQL by a mutation whose input type is its own, and
- * matching the two means guessing which is which — a guess this file exists to avoid.
- */
+/** One entity, four doors, the same answers. */
 export function checkDoors(app: App, entity: SchemaView, options: DoorOptions = {}): void {
   const name = lowerFirst(entity.name ?? '');
   const doors = doorsOf(app, entity, name, options.surface);
-  const bodyOf = () => sampleInput(entity, options.given ?? {}, options);
+  const inputOf = () => sampleInput(entity, options.given ?? {}, options);
 
   describe(`${entity.name} — the doors agree`, () => {
     it('on create, over what the caller sent', async () => {
-      const sent = bodyOf();
+      const sent = inputOf();
       const answers = await Promise.all(
-        (['local', 'rpc', 'rest', 'graphql'] as const).map((door) => doors[door]('create', { body: sent })),
+        (['local', 'rpc', 'rest', 'graphql'] as const).map((door) => doors[door]('create', { input: sent })),
       );
 
       const [local, ...others] = answers.map((answer) => written(answer, sent));
@@ -91,7 +68,7 @@ export function checkDoors(app: App, entity: SchemaView, options: DoorOptions =
     });
 
     it('on list', async () => {
-      await doors.local('create', { body: bodyOf() });
+      await doors.local('create', { input: inputOf() });
 
       const local = wire(rowsOf(await doors.local('list')));
       expect(Array.isArray(local) && local.length > 0, 'nothing to compare').toBe(true);
@@ -102,7 +79,7 @@ export function checkDoors(app: App, entity: SchemaView, options: DoorOptions =
     });
 
     it('on findById', async () => {
-      const row = await doors.local('create', { body: bodyOf() }) as { id: string };
+      const row = await doors.local('create', { input: inputOf() }) as { id: string };
 
       const local = wire(await doors.local('findById', { id: row.id }));
 
@@ -112,12 +89,12 @@ export function checkDoors(app: App, entity: SchemaView, options: DoorOptions =
     });
 
     it('on update, over what the caller sent', async () => {
-      const rows = await Promise.all([1, 2, 3, 4].map(() => doors.local('create', { body: bodyOf() }))) as { id: string }[];
-      const patch = bodyOf();
+      const rows = await Promise.all([1, 2, 3, 4].map(() => doors.local('create', { input: inputOf() }))) as { id: string }[];
+      const patch = inputOf();
 
       const answers = await Promise.all(
         (['local', 'rpc', 'rest', 'graphql'] as const)
-          .map((door, index) => doors[door]('update', { id: rows[index].id, body: patch })),
+          .map((door, index) => doors[door]('update', { id: rows[index].id, input: patch })),
       );
 
       const [local, ...others] = answers.map((answer) => written(answer, patch));
@@ -127,23 +104,23 @@ export function checkDoors(app: App, entity: SchemaView, options: DoorOptions =
     });
 
     it('on delete', async () => {
-      const rows = await Promise.all([1, 2, 3, 4].map(() => doors.local('create', { body: bodyOf() }))) as { id: string }[];
+      const rows = await Promise.all([1, 2, 3, 4].map(() => doors.local('create', { input: inputOf() }))) as { id: string }[];
 
       const answers = await Promise.all(
         (['local', 'rpc', 'rest', 'graphql'] as const).map((door, index) => doors[door]('delete', { id: rows[index].id })),
       );
 
       // REST answers a deletion with no content at all, which is the protocol saying yes.
-      const said = answers.map((answer) => (answer === undefined || answer === null ? true : wire(answer)));
-      expect(new Set(said).size, `the doors disagree: ${JSON.stringify(said)}`).toBe(1);
+      const onTheWire = answers.map((answer) => (answer === undefined || answer === null ? true : wire(answer)));
+      expect(new Set(onTheWire).size, `the doors disagree: ${JSON.stringify(onTheWire)}`).toBe(1);
     });
 
     it('on a refusal', async () => {
       // A refusal is where the doors diverge most, and where each is most tempted to
       // answer in its own words. What must match is that it WAS refused.
-      const bad = { ...bodyOf(), __unknown__: 'x' };
+      const bad = { ...inputOf(), __unknown__: 'x' };
       const refusals = await Promise.all(
-        (['local', 'rpc', 'rest', 'graphql'] as const).map((door) => refused(() => doors[door]('create', { body: bad }))),
+        (['local', 'rpc', 'rest', 'graphql'] as const).map((door) => refused(() => doors[door]('create', { input: bad }))),
       );
 
       expect(refusals[0], 'local accepted a body outside the contract').toBe(true);
@@ -152,13 +129,7 @@ export function checkDoors(app: App, entity: SchemaView, options: DoorOptions =
   });
 }
 
-/**
- * Run one hand-written invocation contract through every door.
- *
- * `checkDoors` derives the generic CRUD gradient. This is its small explicit companion
- * for semantics only the handler can observe — notably omitted versus null input. A new
- * adapter joins the same harness instead of inventing its own interpretation.
- */
+/** Run one hand-written invocation contract through every door. */
 export function checkDoorContract(
   app: App,
   entity: SchemaView,
@@ -190,43 +161,43 @@ function doorsOf(app: App, entity: SchemaView, name: string, surface?: string):
   const run = createLocalRunner(app, surface);
   const state: Record<string, unknown> = {};
 
-  const invocation = (input: DoorInput = {}) => ({
+  const invocation = (call: DoorInput = {}) => ({
     ...EMPTY_INVOCATION,
-    ...(input.id !== undefined ? { params: { id: input.id } } : {}),
-    ...(input.body !== undefined ? { body: input.body } : {}),
+    ...(call.id !== undefined ? { params: { id: call.id } } : {}),
+    ...(call.input !== undefined ? { input: call.input } : {}),
   });
 
   return {
-    local: (op, input) => run({ entity: name, op }, invocation(input)),
+    local: (op, call) => run({ entity: name, op }, invocation(call)),
 
-    rpc: async (op, input) => {
+    rpc: async (op, call) => {
       const answer = await serveRpc(app, {
         path: '',
-        body: { jsonrpc: '2.0', id: 1, method: `${name}.${op}`, params: invocation(input) },
+        body: { jsonrpc: '2.0', id: 1, method: `${name}.${op}`, params: invocation(call) },
         state,
       }) as { result?: unknown; error?: { message: string } };
       if (answer.error) throw new Error(answer.error.message);
       return answer.result;
     },
 
-    rest: async (op, input) => {
+    rest: async (op, call) => {
       // The route the REST door itself would match, read from its own table — rebuilding
       // the path here would be a second opinion on where an entity lives.
       const route = tableOf(app).find((one) => one.entityName === name && one.operationName === op);
       if (!route) throw new Error(`[checkDoors] REST serves no ${name}.${op}`);
-      const path = route.segments.map((segment) => (segment.startsWith(':') ? input?.id ?? '' : segment)).join('/');
+      const path = route.segments.map((segment) => (segment.startsWith(':') ? call?.id ?? '' : segment)).join('/');
 
-      const answer = await serveRest(app, { method: route.method, path, query: {}, body: input?.body, state });
+      const answer = await serveRest(app, { method: route.method, path, query: {}, body: call?.input, state });
       if (answer.kind !== 'ok') throw new Error(`[checkDoors] REST answered ${answer.kind} on ${name}.${op}`);
       return answer.body;
     },
 
-    graphql: async (op, input) => {
+    graphql: async (op, call) => {
       const { executeOn, schemaOf } = await import('@fougere/adapter-graphql');
       const schema = schemaOf(app as never) as never;
       const built = op === 'list' ? listQuery(schema, entity)
-        : op === 'findById' ? findQuery(schema, entity, input?.id ?? '')
-        : mutationFor(schema, entity, op, { id: input?.id, body: input?.body });
+        : op === 'findById' ? findQuery(schema, entity, call?.id ?? '')
+        : mutationFor(schema, entity, op, { id: call?.id, input: call?.input });
       if (!built) throw new Error(`[checkDoors] GraphQL serves no ${entity.name} ${op}`);
 
       const answer = await executeOn(app as never, { query: built.query, state });

package/src/derive.ts

@@ -1,18 +1,12 @@
-import { Cases, type Case } from '@fougere/schema';
+import { Cases, type ValidationCase } from '@fougere/schema';
 import type { SchemaView } from '@fougere/schema';
 import { sampleInput, type SampleOptions } from './sample.js';
 
-/**
- * The cases, with the valid body generated rather than handed in.
- *
- * `Cases` lives in `@fougere/schema` because deriving them reads the four axes and
- * nothing else. This is the half that needs a generator, which is why it is here: a
- * 426 KB faker has no business in the package a browser loads.
- */
+/** The cases, with the valid body generated rather than handed in. */
 export function derivedCases(
   entity: SchemaView,
   given: Record<string, unknown> = {},
   options: SampleOptions = {},
-): readonly Case[] {
+): readonly ValidationCase[] {
   return Cases.of(entity, sampleInput(entity, given, options)).all;
 }

package/src/doors.ts

@@ -6,19 +6,13 @@ import { Cases } from '@fougere/schema';
 import { derivedCases } from './derive.js';
 import { sampleInput, replaySeed, type SampleOptions } from './sample.js';
 
-/** The one shape both the local judge and a door already speak. */
+/** The one shape both the local validator and a door already speak. */
 export interface Verdict {
   success: boolean;
   errors?: ValidationError[];
 }
 
-/**
- * What a door answers, in the shape a verdict is compared in.
- *
- * A refusal reaches a caller as a thrown `FougereError` carrying `details`, not as a
- * returned value — so the translation happens once, here, and every reader below compares
- * the same thing.
- */
+/** What a door answers, in the shape a verdict is compared in. */
 export async function verdictOf(call: () => Promise<unknown>): Promise<Verdict> {
   try {
     await call();
@@ -40,13 +34,7 @@ export interface CheckOptions extends SampleOptions {
   given?: Record<string, unknown>;
 }
 
-/**
- * The declared contract, posed to the façade that will receive it.
- *
- * Declares one `it` per case rather than looping inside a single one: a failure names the
- * case, and a suite that lists what it checked is the point — the list comes from the
- * entity, not from what the author remembered.
- */
+/** The declared contract, posed to the façade that will receive it. */
 export function checkContract(app: App, entity: SchemaView, options: CheckOptions = {}): void {
   const { name, create, update } = opsFor(entity);
   const run = createLocalRunner(app);
@@ -57,7 +45,7 @@ export function checkContract(app: App, entity: SchemaView, options: CheckOption
       it(one.why, async () => {
         const verdict = await verdictOf(() => run(
           { entity: name, op: one.patch ? update : create },
-          { ...EMPTY_INVOCATION, params: one.patch ? { id: '__absent__' } : {}, body: one.body },
+          { ...EMPTY_INVOCATION, params: one.patch ? { id: '__absent__' } : {}, input: one.input },
         ));
 
         expect(Cases.holds(one.expect, verdict), `${JSON.stringify(verdict)} — replay: ${replaySeed()}`).toBe(true);
@@ -66,13 +54,7 @@ export function checkContract(app: App, entity: SchemaView, options: CheckOption
   });
 }
 
-/**
- * What may leave, checked against what the entity says may leave.
- *
- * Costs nothing to state: `Visibility.output` already answers it, and a field the boundary
- * closes has no business in any response. A `password: text({ boundary: 'writeOnly' })`
- * that reaches a caller is the one leak no reviewer catches by reading a handler.
- */
+/** What may leave, checked against what the entity says may leave. */
 export function checkOutput(app: App, entity: SchemaView, options: CheckOptions = {}): void {
   const { name, create } = opsFor(entity);
   const run = createLocalRunner(app);
@@ -83,7 +65,7 @@ export function checkOutput(app: App, entity: SchemaView, options: CheckOptions
     it(closed.length > 0 ? `keeps ${closed.join(', ')} in` : 'closes no field, and says so', async () => {
       const row = await run(
         { entity: name, op: create },
-        { ...EMPTY_INVOCATION, body: sampleInput(entity, options.given ?? {}, options) },
+        { ...EMPTY_INVOCATION, input: sampleInput(entity, options.given ?? {}, options) },
       ) as Record<string, unknown>;
 
       expect(Object.keys(row).filter((field) => closed.includes(field))).toEqual([]);
@@ -92,7 +74,7 @@ export function checkOutput(app: App, entity: SchemaView, options: CheckOptions
     it('answers with fields the entity declares, and no others', async () => {
       const row = await run(
         { entity: name, op: create },
-        { ...EMPTY_INVOCATION, body: sampleInput(entity, options.given ?? {}, options) },
+        { ...EMPTY_INVOCATION, input: sampleInput(entity, options.given ?? {}, options) },
       ) as Record<string, unknown>;
 
       // A computed field from a presenter is declared by the presenter, not the entity,

package/src/gql.ts

@@ -1,4 +1,4 @@
-import { Anatomy, Role, Visibility, type Field, type SchemaView } from '@fougere/schema';
+import { Shapes, Role, Visibility, type Field, type SchemaView } from '@fougere/schema';
 
 /** One field of a root type, in the shape this file reads it. */
 interface RootField {
@@ -13,12 +13,7 @@ interface Introspectable {
   getMutationType?(): { getFields(): Record<string, RootField> } | null | undefined;
 }
 
-/**
- * The scalar fields of an entity, as a GraphQL selection.
- *
- * Relations are left out: they resolve to an object, so naming one without a sub-selection
- * is a syntax error, and following it would compare a neighbour's rows rather than these.
- */
+/** The scalar fields of an entity, as a GraphQL selection. */
 export function selectionOf(entity: SchemaView): string {
   return Object.entries(Visibility.of(entity.getFields()).output)
     .filter(([, field]) => !Role.of(field as Field).relation)
@@ -26,14 +21,7 @@ export function selectionOf(entity: SchemaView): string {
     .join(' ');
 }
 
-/**
- * The Query field that answers an operation, asked of the schema rather than recomputed.
- *
- * `pluralize` is written privately in `adapter/rest/src/routes.ts` AND in
- * `adapter/graphql/src/pothos.ts`; a third copy here would be the one that drifts. The
- * schema already states the answer, so it is read: a list is the field whose type is the
- * entity's list type, and a find is the field of the entity's own type that takes an id.
- */
+/** The Query field that answers an operation, asked of the schema rather than recomputed. */
 export function queryFieldFor(
   schema: Introspectable,
   entity: SchemaView,
@@ -74,14 +62,7 @@ export function at(data: unknown, path: string[]): unknown {
   return path.reduce<unknown>((value, key) => (value as Record<string, unknown>)?.[key], data);
 }
 
-/**
- * The Mutation field that answers an operation.
- *
- * By NAME here, unlike the Query side: `createProduct` and `quote` both take a single
- * `input` argument and both return `Product!`, so their shapes do not separate them. Two
- * candidates are tried against the real fields — `<op><Entity>` for a CRUD write, and the
- * bare op for a custom one — which needs no pluralization and invents nothing.
- */
+/** The Mutation field that answers an operation. */
 export function mutationFieldFor(schema: Introspectable, entity: SchemaView, op: string): string | undefined {
   const fields = schema.getMutationType?.()?.getFields() ?? {};
   const candidates = [`${op}${entity.name}`, op];
@@ -93,14 +74,14 @@ export function mutationFor(
   schema: Introspectable,
   entity: SchemaView,
   op: string,
-  input: { id?: string; body?: Record<string, unknown> },
+  sent: { id?: string; input?: Record<string, unknown> },
 ): { query: string; at: string[] } | undefined {
   const field = mutationFieldFor(schema, entity, op);
   if (!field) return undefined;
 
   const args: string[] = [];
-  if (input.id !== undefined) args.push(`id: ${JSON.stringify(input.id)}`);
-  if (input.body !== undefined) args.push(`input: ${literalOf(input.body, enumsOf(entity))}`);
+  if (sent.id !== undefined) args.push(`id: ${JSON.stringify(sent.id)}`);
+  if (sent.input !== undefined) args.push(`input: ${literalOf(sent.input, enumsOf(entity))}`);
   const call = args.length ? `${field}(${args.join(', ')})` : field;
 
   // `delete` answers a Boolean, which takes no sub-selection — asking for one is a syntax
@@ -112,18 +93,11 @@ export function mutationFor(
 /** The fields the entity declares as a bounded set — GraphQL turns each into an enum. */
 function enumsOf(entity: SchemaView): Set<string> {
   return new Set(Object.entries(entity.getFields())
-    .filter(([, field]) => { const base = Anatomy.of(field.shape).base; return base?.type === 'string' && Array.isArray(base.enum); })
+    .filter(([, field]) => { const base = Shapes.of(field.shape).base; return base?.type === 'string' && Array.isArray(base.enum); })
     .map(([name]) => name));
 }
 
-/**
- * A JS value as a GraphQL literal.
- *
- * `JSON.stringify` is not it, twice over: an input object's keys are NAMES, so
- * `{"sku": "x"}` is a syntax error where `{sku: "x"}` is the value — and an ENUM value is
- * a name too, so `status: "draft"` is refused where `status: draft` is taken. Which
- * fields are enums is read from the entity (`shape.enum`), not guessed from the string.
- */
+/** A JS value as a GraphQL literal. */
 function literalOf(value: unknown, enums: Set<string> = new Set(), key?: string): string {
   if (value === null) return 'null';
   if (key !== undefined && enums.has(key) && typeof value === 'string') return value;

package/src/index.ts

@@ -1,7 +1,7 @@
 export { sampleInput, replaySeed, type SampleOptions } from './sample.js';
 export { derivedCases } from './derive.js';
 // The derivation itself lives with the axes it reads.
-export { Cases, type Case } from '@fougere/schema';
+export { Cases, type ValidationCase } from '@fougere/schema';
 export { testApp, type TestAppOptions, type TestApp } from './app.js';
 export { checkContract, checkOutput, verdictOf, type Verdict, type CheckOptions } from './doors.js';
 export { stubOf, methodsOf, installStubs, type Port, type Stub } from './stub.js';

package/src/load.ts

@@ -12,17 +12,10 @@ export interface LoadOptions {
 
 interface Reachable {
   method: string;
-  body: unknown;
+  input: unknown;
 }
 
-/**
- * Every operation the app answers, with a body for those that take one.
- *
- * Enumerated rather than chosen, and that is the whole point: a scenario written by hand
- * holds the operations its author thought of — `demos/observability/load.js` exercises
- * three — while this one holds all of them, and an operation given `weight: 0` becomes a
- * decision visible in the file instead of an omission nobody can see.
- */
+/** Every operation the app answers, with a body for those that take one. */
 export function reachableOps(app: App, given: LoadOptions['given'] = {}): Reachable[] {
   const found: Reachable[] = [];
   for (const frond of app.fronds) {
@@ -34,7 +27,7 @@ export function reachableOps(app: App, given: LoadOptions['given'] = {}): Reacha
         const schema = contract.input as SchemaView | undefined;
         found.push({
           method: `${handler.address}.${op}`,
-          body: schema ? sampleInput(schema, given[handler.address] ?? {}) : undefined,
+          input: schema ? sampleInput(schema, given[handler.address] ?? {}) : undefined,
         });
       }
     }
@@ -42,22 +35,12 @@ export function reachableOps(app: App, given: LoadOptions['given'] = {}): Reacha
   return found;
 }
 
-/**
- * A k6 scenario, written from what the app answers.
- *
- * k6 runs on its own runtime and cannot import from here, so the file is GENERATED rather
- * than made to import `frameCall` — but the envelope in it comes from `frameCall` itself,
- * called once at generation time. `demos/observability/load.js` spells that envelope by
- * hand, so it will go on claiming to be JSON-RPC the day the format moves.
- *
- * What stays the author's: the weights, the stages and the thresholds. The scan knows
- * which operations exist; it knows nothing about the traffic they receive.
- */
+/** A k6 scenario, written from what the app answers. */
 export function loadScript(app: App, options: LoadOptions = {}): string {
   const door = options.door ?? 'http://127.0.0.1:3000/_fougere/call';
   const ops = reachableOps(app, options.given);
   // The shape, from the one function that states it. `body` is replaced per iteration.
-  const envelope = frameCall({ entity: 'ENTITY', op: 'OP' }, { params: {}, query: {}, body: undefined, state: {} } as never, 0);
+  const envelope = frameCall({ entity: 'ENTITY', op: 'OP' }, { params: {}, query: {}, input: undefined, state: {} } as never, 0);
   // What the envelope carries that an iteration does not fill in itself. Keeping
   // `params` here too put it in the object AND in the spread that overwrites it.
   const perCall = new Set(['method', 'id', 'params']);
@@ -98,10 +81,10 @@ export default function () {
   const payload = ${JSON.stringify(Object.fromEntries(keys.map((key) => [key, envelope[key as keyof typeof envelope]])))};
   const response = http.post(
     DOOR,
-    JSON.stringify({ ...payload, id: ++id, method: op.method, params: { params: {}, query: {}, body: op.body, state: {} } }),
+    JSON.stringify({ ...payload, id: ++id, method: op.method, params: { params: {}, query: {}, input: op.input, state: {} } }),
     { headers: { 'content-type': 'application/json' }, tags: { op: op.method } },
   );
-  check(response, { 'answered': (r) => r.status === 200 });
+  validate(response, { 'answered': (r) => r.status === 200 });
 }
 `;
 }

package/src/remotes.ts

@@ -1,7 +1,2 @@
-/**
- * Contract drift moved to `@fougere/core`, beside the card it compares.
- *
- * Republished here because a test states its subject by where it sits, and `agrees(driftOf(…))`
- * is a testing gesture — the function is core's, the assertion is this package's.
- */
+/** Contract drift moved to `@fougere/core`, beside the card it compares. */
 export { driftOf, agrees, explain, type CardDrift } from '@fougere/core';

package/src/sample.ts

@@ -1,21 +1,9 @@
 import { Role, Visibility, type Field, type Fields, type SchemaView } from '@fougere/schema';
 import { generateSync, type JsonSchema } from 'json-schema-faker';
 
-/**
- * A body a client could legitimately send, built from what the entity declares.
- *
- * The shape IS JSON Schema, so the value itself is not ours to invent — `json-schema-faker`
- * honours `minLength`, `enum`, `format`, `pattern`, `items` and `required`. What is ours is
- * WHICH fields belong in a body, and that is `Visibility.input`: the one reader of the boundary
- * and lifecycle axes the façade and the form already stand on. Re-deriving "not primary,
- * not stamped, not read-only" here would make this a second opinion on the axes.
- */
+/** A body a client could legitimately send, built from what the entity declares. */
 export interface SampleOptions {
-  /**
-   * Fixes what is generated. Defaults to a value derived from the entity name, so two
-   * runs agree and a failure is replayable — a body drawn afresh every time produces the
-   * test that fails once in twenty and cannot be reproduced.
-   */
+  /** Fixes what is generated. */
   seed?: number;
 }
 
@@ -27,10 +15,8 @@ function seedOf(name: string): number {
 }
 
 /**
- * A relation has no value of its own to invent — `ref(Author)` names a row that must
- * exist, and a made-up id points at nothing. So it is REFUSED by name rather than
- * omitted: a body silently missing a required reference is a body the judge rejects for
- * a reason that has nothing to do with the test.
+ * A relation has no value of its own to invent — `ref(Author)` names a row that must exist, and a
+ * made-up id points at nothing.
  */
 function referencesIn(fields: Fields): string[] {
   return Object.entries(fields)
@@ -38,13 +24,7 @@ function referencesIn(fields: Fields): string[] {
     .map(([name]) => name);
 }
 
-/**
- * The seed the last sample used, so a failure can say how to replay it.
- *
- * A stable seed nobody can read is a stable seed for nothing: the value has to reach the
- * person looking at the red line. Held here rather than returned, so the signature stays
- * the body a caller wanted.
- */
+/** The seed the last sample used, so a failure can say how to replay it. */
 let lastSeed: { entity: string; seed: number } | undefined;
 
 /** How to reproduce the last generated body, in the words that reproduce it. */
@@ -71,16 +51,16 @@ export function sampleInput(
 
   const seed = options.seed ?? seedOf(entity.name ?? 'anonymous');
   lastSeed = { entity: entity.name ?? 'Entity', seed };
-  const body: Record<string, unknown> = {};
+  const input: Record<string, unknown> = {};
   let nth = 0;
   for (const [name, field] of Object.entries(fields)) {
-    if (name in given) { body[name] = given[name]; continue; }
+    if (name in given) { input[name] = given[name]; continue; }
     // One seed per field, derived from one seed per entity: two fields of the same shape
     // would otherwise carry the same value, and a test asserting on `title` would pass
-    // while reading `body`.
+    // while reading `title`.
     // A `Shape` IS a JSON Schema; the two packages declare the same concept and only
     // disagree on `readonly`, which no value crosses.
-    body[name] = generateSync((field as Field).shape as JsonSchema, { seed: seed + nth++ });
+    input[name] = generateSync((field as Field).shape as JsonSchema, { seed: seed + nth++ });
   }
-  return body;
+  return input;
 }

package/src/scope.ts

@@ -2,18 +2,7 @@ import { existsSync } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { DEFAULT_CONVENTIONS, loadConfig, resolveConventions } from '@fougere/core/node';
 
-/**
- * What a test file's position states about its subject.
- *
- * The same reading the scan already performs on `entities/` and `handlers/`: a directory
- * is a declaration. A file under `fronds/blog/tests/` says its subject is `blog`, so that
- * frond is real and its neighbours are not — which is a TOPOLOGY, the very thing
- * `remotes:` states in production, and not a mode of testing.
- *
- * The sub-directory below `tests/` carries nothing. A name like `it('refuses a payment')`
- * is prose, and prose deciding how an app is wired is the hidden runtime the doctrine
- * refuses; a path is a position, which a reader sees by looking at where the file sits.
- */
+/** What a test file's position states about its subject. */
 export interface Scope {
   /** The project the app boots from — where `fronds/` and `fougere.config.ts` live. */
   root: string;
@@ -21,12 +10,7 @@ export interface Scope {
   frond?: string;
 }
 
-/**
- * The frond a path sits in, or nothing.
- *
- * The LAST `fronds/` segment wins: a frond may hold a synced copy of a neighbour under
- * `.fougere/remotes/`, and a test that ever lands beside one is about the inner frond.
- */
+/** The frond a path sits in, or nothing. */
 export function frondOf(path: string, frondsDir: string = DEFAULT_CONVENTIONS.fronds): string | undefined {
   const parts = path.split(sep);
   const at = parts.lastIndexOf(frondsDir);
@@ -35,13 +19,7 @@ export function frondOf(path: string, frondsDir: string = DEFAULT_CONVENTIONS.fr
   return name && !name.endsWith('.ts') ? name : undefined;
 }
 
-/**
- * Where the project starts: the first ancestor holding a config or a `fronds/`.
- *
- * The config is probed FIRST, which is what lets the rest of this file ask it where fronds
- * live: a project that renamed the directory still declares one, and only a project with
- * no config at all is found by the convention.
- */
+/** Where the project starts. */
 export function rootOf(path: string): string | undefined {
   let at = dirname(path);
   let previous = '';
@@ -53,12 +31,7 @@ export function rootOf(path: string): string | undefined {
   return undefined;
 }
 
-/**
- * The scope a test file declares by where it sits.
- *
- * Returns nothing when the file sits outside any project — a caller then states `root`
- * itself, which is what this package's own tests do against their fixtures.
- */
+/** The scope a test file declares by where it sits. */
 export async function scopeOf(path: string): Promise<Scope | undefined> {
   const root = rootOf(path);
   if (!root) return undefined;
@@ -69,13 +42,7 @@ export async function scopeOf(path: string): Promise<Scope | undefined> {
   return { root, ...(frond ? { frond } : {}) };
 }
 
-/**
- * The path of the running test file, from vitest.
- *
- * Read rather than guessed: `expect.getState()` is vitest's own API. Handed in by the
- * caller because this module is ESM and cannot `require`, and because a package that
- * imports vitest at the top level stops being loadable outside a test run.
- */
+/** The path of the running test file, from vitest. */
 export async function scopeOfRun(testPath: string | undefined): Promise<Scope | undefined> {
   return testPath ? scopeOf(testPath) : undefined;
 }