@fougere/testing 0.3.0-alpha.0 → 0.4.0-alpha.0

package/src/gql.ts

@@ -0,0 +1,136 @@
+import { Anatomy, Role, Visibility, type Field, type SchemaView } from '@fougere/schema';
+
+/** One field of a root type, in the shape this file reads it. */
+interface RootField {
+  name: string;
+  type: { toString(): string };
+  args: { name: string }[];
+}
+
+/** The minimum of a GraphQL schema this file reads — no `graphql` import, no second copy. */
+interface Introspectable {
+  getQueryType(): { getFields(): Record<string, RootField> } | null | undefined;
+  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.
+ */
+export function selectionOf(entity: SchemaView): string {
+  return Object.entries(Visibility.of(entity.getFields()).output)
+    .filter(([, field]) => !Role.of(field as Field).relation)
+    .map(([name]) => name)
+    .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.
+ */
+export function queryFieldFor(
+  schema: Introspectable,
+  entity: SchemaView,
+  op: 'list' | 'findById',
+): string | undefined {
+  const fields = schema.getQueryType()?.getFields() ?? {};
+  const wanted = op === 'list' ? `${entity.name}List` : entity.name;
+
+  for (const field of Object.values(fields)) {
+    // `String(type)` gives the name with its wrappers (`Product!`, `[Product!]!`), which
+    // is why this compares on inclusion rather than equality.
+    const named = String(field.type).replace(/[![\]]/g, '');
+    if (named !== wanted) continue;
+    const takesId = field.args.some((arg) => arg.name === 'id');
+    if (op === 'findById' ? takesId : !takesId) return field.name;
+  }
+  return undefined;
+}
+
+/** A `list` query, and the path at which its rows sit in the answer. */
+export function listQuery(schema: Introspectable, entity: SchemaView): { query: string; at: string[] } | undefined {
+  const field = queryFieldFor(schema, entity, 'list');
+  if (!field) return undefined;
+  // The list type wraps its rows — `ProductList { items }` — so the reader below has to
+  // be told where to look rather than assume the answer IS the rows.
+  return { query: `{ ${field} { items { ${selectionOf(entity)} } } }`, at: [field, 'items'] };
+}
+
+/** A `findById` query for one row. */
+export function findQuery(schema: Introspectable, entity: SchemaView, id: string): { query: string; at: string[] } | undefined {
+  const field = queryFieldFor(schema, entity, 'findById');
+  if (!field) return undefined;
+  return { query: `{ ${field}(id: ${JSON.stringify(id)}) { ${selectionOf(entity)} } }`, at: [field] };
+}
+
+/** Follow a path into a GraphQL answer, tolerating an absence rather than throwing. */
+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.
+ */
+export function mutationFieldFor(schema: Introspectable, entity: SchemaView, op: string): string | undefined {
+  const fields = schema.getMutationType?.()?.getFields() ?? {};
+  const candidates = [`${op}${entity.name}`, op];
+  return candidates.find((name) => name in fields);
+}
+
+/** A mutation, with the arguments its operation takes and where its answer sits. */
+export function mutationFor(
+  schema: Introspectable,
+  entity: SchemaView,
+  op: string,
+  input: { id?: string; body?: 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))}`);
+  const call = args.length ? `${field}(${args.join(', ')})` : field;
+
+  // `delete` answers a Boolean, which takes no sub-selection — asking for one is a syntax
+  // error, and the schema is what says which case this is.
+  const scalar = String(schema.getMutationType?.()?.getFields()[field]?.type ?? '').replace(/[!]/g, '') === 'Boolean';
+  return { query: `mutation { ${call}${scalar ? '' : ` { ${selectionOf(entity)} }`} }`, at: [field] };
+}
+
+/** 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); })
+    .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.
+ */
+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;
+  if (Array.isArray(value)) return `[${value.map((one) => literalOf(one, enums, key)).join(', ')}]`;
+  if (typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .map(([name, one]) => `${name}: ${literalOf(one, enums, name)}`).join(', ')}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+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 { 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';
+export { scopeOf, scopeOfRun, frondOf, rootOf, type Scope } from './scope.js';
+export { loadScript, reachableOps, type LoadOptions } from './load.js';
+export {
+  checkDoorContract,
+  checkDoors,
+  type DoorContractCase,
+  type DoorInput,
+  type DoorOptions,
+} from './comparison.js';
+export { selectionOf, queryFieldFor, mutationFieldFor, listQuery, findQuery, mutationFor, at } from './gql.js';
+export { driftOf, agrees, explain, type CardDrift } from './remotes.js';
+export { checkAll, servedEntities, type CheckAllOptions } from './all.js';
+export { syncedRemotes, heldShapes, syncDriftOf, inSync, type SyncedRemote, type SyncDrift } from './sync.js';

package/src/load.ts

@@ -0,0 +1,107 @@
+import { frameCall } from '@fougere/transport-http';
+import type { App } from '@fougere/core';
+import type { SchemaView } from '@fougere/schema';
+import { sampleInput } from './sample.js';
+
+export interface LoadOptions {
+  /** Where the calls go. The RPC door of a running app. */
+  door?: string;
+  /** Values the generator cannot invent, by entity name — the id a `ref()` points at. */
+  given?: Record<string, Record<string, unknown>>;
+}
+
+interface Reachable {
+  method: string;
+  body: 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.
+ */
+export function reachableOps(app: App, given: LoadOptions['given'] = {}): Reachable[] {
+  const found: Reachable[] = [];
+  for (const frond of app.fronds) {
+    for (const handler of frond.handlers) {
+      // A named surface is a restricted door; the load of an app is what its default
+      // door answers, so a surface would count the same operation twice.
+      if (handler.surface) continue;
+      for (const [op, contract] of handler.operations ?? []) {
+        const schema = contract.input as SchemaView | undefined;
+        found.push({
+          method: `${handler.address}.${op}`,
+          body: schema ? sampleInput(schema, given[handler.address] ?? {}) : undefined,
+        });
+      }
+    }
+  }
+  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.
+ */
+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);
+  // 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']);
+  const keys = Object.keys(envelope).filter((key) => !perCall.has(key));
+
+  return `// Generated by \`fougere load\` — edit the weights, the stages and the thresholds.
+// Everything else is read from what the app answers: regenerate rather than patch.
+import http from 'k6/http';
+import { check } from 'k6';
+
+const DOOR = ${JSON.stringify(door)};
+
+// Every operation the app serves. A weight of 0 takes one out, visibly.
+const OPS = ${JSON.stringify(ops.map((op) => ({ ...op, weight: 1 })), null, 2)};
+
+export const options = {
+  // Yours: a flat rate draws flat lines and there is nothing to read in them.
+  stages: [
+    { duration: '30s', target: 5 },
+    { duration: '45s', target: 5 },
+    { duration: '30s', target: 0 },
+  ],
+  // Yours: what counts as too slow is a fact about your users.
+  thresholds: { http_req_failed: ['rate<0.01'], http_req_duration: ['p(95)<500'] },
+};
+
+const TOTAL = OPS.reduce((sum, op) => sum + op.weight, 0);
+let id = 0;
+
+function pick() {
+  let roll = Math.random() * TOTAL;
+  for (const op of OPS) if ((roll -= op.weight) < 0) return op;
+  return OPS[OPS.length - 1];
+}
+
+export default function () {
+  const op = pick();
+  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: {} } }),
+    { headers: { 'content-type': 'application/json' }, tags: { op: op.method } },
+  );
+  check(response, { 'answered': (r) => r.status === 200 });
+}
+`;
+}

package/src/remotes.ts

@@ -0,0 +1,125 @@
+import { Card, type Change, type SchemaDescriptor } from '@fougere/schema';
+import type { IdentityCard } from '@fougere/core';
+
+/** What separates the copy a consumer holds from what the producer actually serves. */
+export interface CardDrift {
+  frond: string;
+  /** A door the consumer calls that the producer no longer serves. */
+  missingDoors: string[];
+  /** An operation the consumer calls that the door no longer has. */
+  missingOps: { door: string; ops: string[] }[];
+  /** A shape that moved under a door the consumer still calls. */
+  shapes: { door: string; changes: Change[] }[];
+  /** A fact the consumer subscribes to whose shape moved, or that is gone. */
+  facts: { fact: string; changes: Change[] | 'gone' }[];
+}
+
+/** Every door of a card, by name. */
+function doorsOf(card: IdentityCard, frond: string): Map<string, { ops: Set<string>; schema?: SchemaDescriptor }> {
+  const found = new Map<string, { ops: Set<string>; schema?: SchemaDescriptor }>();
+  for (const one of card.fronds) {
+    if (one.name !== frond) continue;
+    for (const door of one.doors) {
+      found.set(door.name, { ops: new Set(door.ops.map((op) => op.name)), schema: door.schema });
+    }
+  }
+  return found;
+}
+
+function factsOf(card: IdentityCard, frond: string): Map<string, SchemaDescriptor | undefined> {
+  const found = new Map<string, SchemaDescriptor | undefined>();
+  for (const one of card.fronds) {
+    if (one.name !== frond) continue;
+    for (const fact of one.facts ?? []) found.set(fact.name, fact.schema as SchemaDescriptor | undefined);
+  }
+  return found;
+}
+
+/**
+ * What a consumer's synced copy no longer matches in what the producer serves.
+ *
+ * The gap TypeScript cannot see, and the only place the gradient genuinely lies: the code
+ * is identical in-process and split, but one side may have aged. `fougere sync` wrote the
+ * consumer's copy three weeks ago, the producer moved on, and it still compiles —
+ * production is where that is found today. This is what Pact sells; the material was
+ * already here, in `rpc.discover` and in `Card.diff`.
+ *
+ * Read in ONE direction on purpose: what the consumer holds, checked against what is
+ * served. A producer serving MORE than the consumer knows is not drift — it is a producer
+ * that moved forward without breaking anyone, which is the whole point of the order the
+ * repo already states (re-sync the readers, then deploy the sender).
+ */
+export function driftOf(mine: IdentityCard, theirs: IdentityCard, frond: string): CardDrift {
+  const held = doorsOf(mine, frond);
+  const served = doorsOf(theirs, frond);
+  const drift: CardDrift = { frond, missingDoors: [], missingOps: [], shapes: [], facts: [] };
+
+  for (const [name, door] of held) {
+    const there = served.get(name);
+    if (!there) { drift.missingDoors.push(name); continue; }
+
+    const missing = [...door.ops].filter((op) => !there.ops.has(op));
+    if (missing.length > 0) drift.missingOps.push({ door: name, ops: missing.sort() });
+
+    if (door.schema && there.schema) {
+      // `Card.diff` never guesses a rename — a field gone plus a field appeared lands in
+      // `ambiguous`, and only a declaration settles it. Here nobody can declare one, so
+      // the pair is reported as it is and a human reads it.
+      const moved = Card.fromDescriptor(door.schema).diff(Card.fromDescriptor(there.schema));
+      if (moved.changes.length > 0) drift.shapes.push({ door: name, changes: moved.changes });
+    }
+  }
+
+  const heldFacts = factsOf(mine, frond);
+  const servedFacts = factsOf(theirs, frond);
+  for (const [name, shape] of heldFacts) {
+    if (!servedFacts.has(name)) { drift.facts.push({ fact: name, changes: 'gone' }); continue; }
+    const there = servedFacts.get(name);
+    if (!shape || !there) continue;
+    const moved = Card.fromDescriptor(shape).diff(Card.fromDescriptor(there));
+    if (moved.changes.length > 0) drift.facts.push({ fact: name, changes: moved.changes });
+  }
+
+  return drift;
+}
+
+/** Whether anything at all separates the two cards. */
+export function agrees(drift: CardDrift): boolean {
+  return drift.missingDoors.length === 0
+    && drift.missingOps.length === 0
+    && drift.shapes.length === 0
+    && drift.facts.length === 0;
+}
+
+/**
+ * The drift, in the words a deploy needs.
+ *
+ * A fact says the order out loud, because the repo already states it as a rule and
+ * nothing enforced it: a fact is judged strictly, so a reader that has not been re-synced
+ * refuses what the sender now announces.
+ */
+export function explain(drift: CardDrift): string[] {
+  const lines: string[] = [];
+  for (const door of drift.missingDoors) lines.push(`${drift.frond}.${door} — you call it, it is not served`);
+  for (const { door, ops } of drift.missingOps) lines.push(`${drift.frond}.${door} — gone: ${ops.join(', ')}`);
+  for (const { door, changes } of drift.shapes) {
+    for (const change of changes) lines.push(`${drift.frond}.${door} — ${describe(change)}`);
+  }
+  for (const { fact, changes } of drift.facts) {
+    if (changes === 'gone') { lines.push(`${fact} — you subscribe to it, it is no longer announced`); continue; }
+    for (const change of changes) lines.push(`${fact} — ${describe(change)} → re-sync and deploy the readers, THEN the sender`);
+  }
+  return lines;
+}
+
+function describe(change: Change): string {
+  switch (change.kind) {
+    case 'added': return `+ ${change.field}${change.required ? ' (required)' : ''}`;
+    case 'removed': return `- ${change.field}`;
+    case 'renamed': return `${change.from} → ${change.to}`;
+    case 'retyped': return `${change.field}: ${[...change.from].join('|')} → ${[...change.to].join('|')}`;
+    case 'reshaped': return `${change.field}: its bounds moved`;
+    case 'required': return `${change.field}: ${change.from ? 'no longer' : 'now'} required`;
+    case 'restated': return `${change.field}: its ${change.axis} moved`;
+  }
+}

package/src/sample.ts

@@ -0,0 +1,86 @@
+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.
+ */
+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.
+   */
+  seed?: number;
+}
+
+/** Stable across runs and across machines: the entity name is the only input. */
+function seedOf(name: string): number {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) hash = (hash * 31 + name.charCodeAt(i)) | 0;
+  return Math.abs(hash) || 1;
+}
+
+/**
+ * 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.
+ */
+function referencesIn(fields: Fields): string[] {
+  return Object.entries(fields)
+    .filter(([, field]) => Role.of(field as Field).isReference)
+    .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.
+ */
+let lastSeed: { entity: string; seed: number } | undefined;
+
+/** How to reproduce the last generated body, in the words that reproduce it. */
+export function replaySeed(): string {
+  return lastSeed
+    ? `sampleInput(${lastSeed.entity}, {}, { seed: ${lastSeed.seed} })`
+    : 'nothing has been sampled yet';
+}
+
+export function sampleInput(
+  entity: SchemaView,
+  given: Record<string, unknown> = {},
+  options: SampleOptions = {},
+): Record<string, unknown> {
+  const fields = Visibility.of(entity.getFields()).input;
+  const missing = referencesIn(fields).filter((name) => !(name in given));
+  if (missing.length > 0) {
+    throw new Error(
+      `[sampleInput] ${missing.join(', ')} ${missing.length > 1 ? 'are references' : 'is a reference'} — `
+      + 'a generated id points at no row. Pass the ids: '
+      + `sampleInput(Entity, { ${missing.map((n) => `${n}: '…'`).join(', ')} }).`,
+    );
+  }
+
+  const seed = options.seed ?? seedOf(entity.name ?? 'anonymous');
+  lastSeed = { entity: entity.name ?? 'Entity', seed };
+  const body: Record<string, unknown> = {};
+  let nth = 0;
+  for (const [name, field] of Object.entries(fields)) {
+    if (name in given) { body[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`.
+    // 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++ });
+  }
+  return body;
+}

package/src/scope.ts

@@ -0,0 +1,81 @@
+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.
+ */
+export interface Scope {
+  /** The project the app boots from — where `fronds/` and `fougere.config.ts` live. */
+  root: string;
+  /** The frond under test. Absent means every frond is real: several of them, together. */
+  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.
+ */
+export function frondOf(path: string, frondsDir: string = DEFAULT_CONVENTIONS.fronds): string | undefined {
+  const parts = path.split(sep);
+  const at = parts.lastIndexOf(frondsDir);
+  if (at === -1 || at + 1 >= parts.length) return undefined;
+  const name = parts[at + 1];
+  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.
+ */
+export function rootOf(path: string): string | undefined {
+  let at = dirname(path);
+  let previous = '';
+  while (at !== previous) {
+    if (existsSync(join(at, 'fougere.config.ts')) || existsSync(join(at, DEFAULT_CONVENTIONS.fronds))) return at;
+    previous = at;
+    at = dirname(at);
+  }
+  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.
+ */
+export async function scopeOf(path: string): Promise<Scope | undefined> {
+  const root = rootOf(path);
+  if (!root) return undefined;
+  // The root is known, so its config can say what the fronds directory is called before
+  // the position is read against it.
+  const { fronds } = resolveConventions((await loadConfig(root)).conventions);
+  const frond = frondOf(path, fronds);
+  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.
+ */
+export async function scopeOfRun(testPath: string | undefined): Promise<Scope | undefined> {
+  return testPath ? scopeOf(testPath) : undefined;
+}

package/src/stub.ts

@@ -0,0 +1,80 @@
+import { vi, type Mock } from 'vitest';
+import type { Container } from '@fougere/container';
+import type { App } from '@fougere/core';
+
+/** Anything a provider can be declared as: a class the container knows how to build. */
+export type Port = abstract new (...args: never[]) => unknown;
+
+/** The double handed in place of a port — one spy per method the port declares. */
+export type Stub<T> = { [K in keyof T]: T[K] extends (...args: never[]) => unknown ? Mock : T[K] };
+
+/**
+ * The methods a port declares, read from the prototype chain at runtime.
+ *
+ * Not written by hand and not read from the AST: `ProviderEntry` keeps `ctor`, `deps` and
+ * `filePath` and never the methods, while the prototype has them all along. So a double
+ * carries exactly what the port carries and gains a method the day the port does — which
+ * is the failure `ports.test.ts` records, a `charge is not a function` from a stand-in
+ * that did not carry what its type promised.
+ *
+ * Walks the chain because a port may itself extend one; stops at `Object.prototype`,
+ * whose members belong to no port.
+ */
+export function methodsOf(port: Port): string[] {
+  const found = new Set<string>();
+  let proto: object | null = port.prototype as object;
+  while (proto && proto !== Object.prototype) {
+    for (const name of Object.getOwnPropertyNames(proto)) {
+      if (name === 'constructor') continue;
+      const declared = Object.getOwnPropertyDescriptor(proto, name);
+      if (typeof declared?.value === 'function') found.add(name);
+    }
+    proto = Object.getPrototypeOf(proto) as object | null;
+  }
+  return [...found];
+}
+
+/**
+ * A double for a port: every method present, every call recorded, nothing returned.
+ *
+ * What it RETURNS is not derivable and the value is the caller's to state — a service's
+ * return type is a bare TypeScript type, erased at runtime, with no declared fields for
+ * anything to build from. The same line the whole package sits on: what Fougere's
+ * vocabulary declares can be derived, arbitrary code cannot.
+ */
+export function stubOf<T>(port: Port): Stub<T> {
+  const double: Record<string, Mock> = {};
+  for (const method of methodsOf(port)) double[method] = vi.fn();
+  return double as Stub<T>;
+}
+
+/**
+ * Put doubles in front of ports, in every frond scope that answers under their name.
+ *
+ * After the boot rather than through `ports:`, because the container resolves lazily: a
+ * provider is built on first `resolve`, so a value registered before any call is the one
+ * a handler receives. `registerValue` also marks it as not the container's to dispose,
+ * which is right — the test made it.
+ *
+ * A port nobody answers under is REFUSED by name, for the reason `ports:` refuses a key
+ * that matched nothing: a double that silently stands in front of no one reads as a test
+ * that covered a case it never reached.
+ */
+export function installStubs(app: App, ports: Port[]): Map<Port, Stub<unknown>> {
+  const doubles = new Map<Port, Stub<unknown>>();
+  const scopes = app.fronds.map((frond) => app.resolve<Container>(`frond:${frond.name}`));
+
+  for (const port of ports) {
+    const answering = scopes.filter((scope) => scope.has(port.name));
+    if (answering.length === 0) {
+      throw new Error(
+        `[stub] ${port.name} — nothing answers under that name in any frond. `
+        + 'A port is a class a provider extends; a class nobody extends is an ordinary service.',
+      );
+    }
+    const double = stubOf(port);
+    for (const scope of answering) scope.registerValue(port.name, double);
+    doubles.set(port, double);
+  }
+  return doubles;
+}