@fougere/core 0.3.0-alpha.0 → 0.5.0-alpha.0

package/src/boot/seed.ts

@@ -0,0 +1,158 @@
+import { Role } from '@fougere/schema';
+import { facadeKeyOf } from '../wire/call.js';
+import type { FrondDescriptor, SeedEntry, SeedFactory } from '../scan/frond.js';
+import type { App } from './types.js';
+import type { Extension } from './AppLifecycle.js';
+
+/**
+ * Seeds in dependency order — a `ref()` target is planted before its referrer.
+ *
+ * The order is a fact about the entity graph, not about the surface running the seeds,
+ * so it is stated once here. The Nuxt module read it off a pairwise comparator (which
+ * `Array.sort` cannot make transitive: `a` before `b` and `b` before `c` never implies
+ * `a` before `c`), and `boot()` had no order at all — the same fact, told twice and
+ * wrong both times. A list seeded before its owner failed on the foreign key, and the
+ * driver's error named neither the entity nor the file.
+ *
+ * Kahn, like `orderTables` in `@fougere/adapter-sql` — the same shape one level up: there
+ * the nodes are tables and the edges FK columns, here they are seeds and the edges the
+ * `one` relations of the entities they target. A cycle cannot be satisfied by ordering,
+ * so its remaining seeds keep their scan order and land last: the driver refuses what is
+ * genuinely impossible, and everything acyclic around it still gets planted.
+ */
+export function orderSeeds(fronds: FrondDescriptor[]): SeedEntry[] {
+  const refs = new Map<string, Set<string>>();
+  for (const frond of fronds) {
+    for (const entity of frond.entities) {
+      const targets = new Set<string>();
+      for (const field of Object.values(entity.entityClass.getFields())) {
+        if (!Role.of(field).isReference) continue;
+        const target = (Role.of(field).target as { name?: string }).name?.toLowerCase();
+        if (target && target !== entity.name.toLowerCase()) targets.add(target);
+      }
+      refs.set(entity.name.toLowerCase(), targets);
+    }
+  }
+
+  const seeds = fronds.flatMap((frond) => frond.seeds);
+  const seeded = new Set(seeds.map((seed) => seed.entityName.toLowerCase()));
+
+  // Only what is actually seeded can be waited for: a relation to an entity with no seed
+  // is already satisfied by whatever put its rows there.
+  const waiting = new Map(
+    seeds.map((seed) => {
+      const own = seed.entityName.toLowerCase();
+      const targets = [...(refs.get(own) ?? [])].filter((target) => seeded.has(target) && target !== own);
+
+      return [seed, new Set(targets)] as const;
+    }),
+  );
+
+  const ordered: SeedEntry[] = [];
+  const planted = new Set<string>();
+
+  while (waiting.size > 0) {
+    const ready = [...waiting.keys()].find((seed) => [...waiting.get(seed)!].every((dep) => planted.has(dep)));
+    if (!ready) break;
+
+    ordered.push(ready);
+    planted.add(ready.entityName.toLowerCase());
+    waiting.delete(ready);
+  }
+
+  return [...ordered, ...waiting.keys()];
+}
+
+/** Where a seed writes, and what it may skip — resolved per entity. */
+interface SeedDoor {
+  list(): Promise<unknown[]>;
+  write(item: unknown): Promise<unknown>;
+}
+
+/**
+ * Plant a set of seeds, in the order given. Reports what it did, one line per entity.
+ *
+ * The one seeding loop. `boot()` had one and the Nuxt module generated a second into its
+ * Nitro plugin, which had drifted: no ORM fallback, so an entity with no façade was
+ * skipped there and planted here. Two answers to "how does a row get in at boot" is one
+ * too many, and the second was the one running in the browser.
+ */
+export async function runSeeds(
+  app: App,
+  seeds: SeedEntry[],
+  report: (message: string) => void = () => {},
+): Promise<void> {
+  for (const seed of seeds) {
+    const resolve = <T>(name: string) => app.resolve<T>(name + 'Handler');
+    const data = typeof seed.data === 'function' ? await (seed.data as SeedFactory)(resolve) : seed.data;
+
+    const door = doorFor(app, seed.entityName);
+    if (!door) {
+      report(`  ${seed.entityName}: no handler façade nor ORM — skipping seed`);
+      continue;
+    }
+
+    const existing = await door.list();
+    if (existing.length > 0) {
+      report(`  ${seed.entityName}: skipped (${existing.length} exist)`);
+      continue;
+    }
+
+    // The driver's error alone names neither the entity nor the row — and a foreign
+    // key is exactly what a seed gets wrong.
+    for (const item of data) {
+      try {
+        await door.write(item);
+      } catch (cause) {
+        throw new Error(
+          `Seed '${seed.entityName}' failed on ${JSON.stringify(item)}: ${(cause as Error)?.message ?? cause}`,
+          { cause },
+        );
+      }
+    }
+    report(`  ${seed.entityName}: ${data.length} records`);
+  }
+}
+
+/**
+ * A seed is not a client: it writes at boot, from inside. The façade is used when the
+ * entity declares one (its judge catches a bad seed early), the storage when it does
+ * not — an entity that exposes nothing is still an entity whose reference rows must land.
+ */
+function doorFor(app: App, entityName: string): SeedDoor | undefined {
+  let handler: Record<string, Function> | undefined;
+  try { handler = app.resolve<Record<string, Function>>(facadeKeyOf(entityName)); } catch {}
+
+  if (typeof handler?.list === 'function' && typeof handler.create === 'function') {
+    return {
+      list: () => handler!.list() as Promise<unknown[]>,
+      write: (item) => handler!.create({ params: {}, query: {}, body: item, state: {} }),
+    };
+  }
+
+  const orm = app.ormFor(entityName) as
+    | { list: () => Promise<unknown[]>; create: (input: unknown) => Promise<unknown> }
+    | undefined;
+  if (!orm) return undefined;
+
+  return { list: () => orm.list(), write: (item) => orm.create(item) };
+}
+
+/**
+ * The framework's own ascent for rows, named — so a host can REPLACE it rather than take
+ * over the whole post-boot to get its own.
+ *
+ * That is what Nuxt's Nitro plugin had to do: a bundler needs its seed modules spelled out
+ * as static imports, so the plugin claimed everything after the boot and its copy of the
+ * loop drifted. It now declares an extension under this same name instead, and the delta
+ * is one member of a list.
+ */
+export function seeding(report?: (message: string) => void): Extension {
+  return {
+    name: 'seeds',
+    up: async (app: App) => {
+      const seeds = orderSeeds(app.fronds);
+      if (seeds.length > 0) await runSeeds(app, seeds, report);
+    },
+  };
+}

package/src/boot/statement-drift.ts

@@ -0,0 +1,60 @@
+/**
+ * Where a STATED contract and the signature it is about have stopped agreeing.
+ *
+ * `frond.config.ts` states an operation's contract and wins over the scan — that order is
+ * deliberate, and it is the only answer for a method inherited from an installed base class
+ * the workspace scan cannot see. But winning silently is how a statement made about
+ * `publish(id: string)` keeps applying after the parameter was renamed to `postId`: the
+ * façade binds what the config said, the method receives `undefined`, and nothing anywhere
+ * says the two disagree.
+ *
+ * So this compares, and only where BOTH exist — a statement about a signature the scan
+ * never read is not drift, it is the case config was built for. It is a `warning` and not
+ * a refusal: the statement is still the author's word, and a boot that ran yesterday must
+ * not stop running because a parameter moved. What it must not do is stay quiet.
+ */
+import type { FrondDescriptor, HandlerEntry, ScanDiagnostic } from '../scan/frond.js';
+import type { BindingPlan } from './binding.js';
+import type { ParsedMethod } from '../scan/handler-parser.js';
+
+/** The parameters a stated binding names, against the ones the method declares. */
+function namesDisagreeing(stated: BindingPlan, signature: ParsedMethod): string[] {
+  const declared = new Set(signature.params.map((p: { name: string }) => p.name));
+
+  return stated.map((b) => b.name).filter((name) => !declared.has(name));
+}
+
+/**
+ * What a frond's stated contracts no longer match.
+ *
+ * Read by `resolveEffectiveOperations`, so the same answer reaches `fougere check` and a
+ * boot — one comparison, two readers, no second opinion to drift on its own.
+ */
+export function statementDrift(frond: FrondDescriptor, handler: HandlerEntry): ScanDiagnostic[] {
+  const found: ScanDiagnostic[] = [];
+
+  for (const [name, override] of Object.entries(frond.operationsOverrides ?? {})) {
+    if (!override.binding) continue;
+
+    // The scan's own reading of this method. Absent means config is stating what nothing
+    // read — an installed base class, a handler outside the workspace — which is legal.
+    const signature = handler.operations.get(name)?.signature;
+    if (!signature) continue;
+
+    const orphans = namesDisagreeing(override.binding, signature);
+    if (orphans.length === 0) continue;
+
+    found.push({
+      severity: 'warning',
+      code: 'stated-binding-drifted',
+      filePath: handler.filePath,
+      frond: frond.name,
+      subject: `${handler.ctor.name}.${name}`,
+      message: `frond.config.ts binds ${orphans.map((o) => `\`${o}\``).join(', ')} on `
+        + `${handler.ctor.name}.${name}, which declares (${signature.params.map((p: { name: string }) => p.name).join(', ')}). `
+        + `The statement wins, so those parameters receive nothing.`,
+    });
+  }
+
+  return found;
+}

package/src/boot/together.ts

@@ -0,0 +1,215 @@
+/**
+ * Building a frame — what a handler asking for `Together<[…]>` receives.
+ *
+ * The declaration names its members and nothing else; where they live, and therefore
+ * which of the two realizations they get, is read HERE and stated at boot. A frame whose
+ * members share an engine is a transaction; one whose members are split replays its own
+ * inverses (`frame.ts`). Same user code, two guarantees, and the boot says which — the
+ * one thing a gradient must never leave to assumption.
+ */
+import { ambient } from '#ambient';
+import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
+import type { Container } from '@fougere/container';
+import { membersOfTogetherKey, ormKeyOf, type EntityOrm, type OrmFactory } from '../orm.js';
+import type { Logger } from '../builtins/logger.js';
+import type { ProviderEntry } from '../scan/frond.js';
+import { StorageGuard } from '../dispatch/StorageGuard.js';
+import { recording, unwind, type Undo } from './frame.js';
+
+/** Everything the boot knows that a frame needs, gathered once for every frond. */
+export interface FrameWorld {
+  /** Every entity of every frond, by registration key. A frame crosses fronds by design. */
+  entityByName: Map<string, SchemaView>;
+  /** Which frond holds an entity — the question `remotes:` turns into a refusal. */
+  frondOf: Map<string, string>;
+  hostedHere: (frond: string) => boolean;
+  ormFactory?: OrmFactory;
+  sourceOf?: (entityName: string) => string;
+  transacted?: <R>(source: string, fn: (ormFactory: OrmFactory) => Promise<R>) => Promise<R>;
+  log: Logger;
+}
+
+/** An entity the block writes through, and a provider rebuilt so that its writes count too. */
+interface Members {
+  entities: { name: string; schema: SchemaView }[];
+  providers: ProviderEntry[];
+}
+
+/**
+ * Each declared name, resolved to what it designates.
+ *
+ * A name that resolves to nothing is refused rather than skipped: `Together<[Account,
+ * Ledgre]>` is a typo whose only other symptom is a frame quietly one member short. The
+ * two lists are checked against different registries, which is exactly why the declaration
+ * separates them — nothing here has to guess what kind a name is.
+ */
+function resolve(names: { entities: string[]; providers: string[] }, declared: readonly ProviderEntry[], world: FrameWorld): Members {
+  const entities = names.entities.map((member) => {
+    const name = lowerFirst(member);
+    const schema = world.entityByName.get(name);
+    if (!schema) {
+      throw new Error(
+        `Together<[…${member}…]>: no entity named '${member}' is scanned in this app. ` +
+        `The first list names entities; a class of this frond goes in the second.`,
+      );
+    }
+    return { name, schema };
+  });
+
+  const providers = names.providers.map((member) => {
+    const entry = declared.find((provider) => provider.ctor.name === member);
+    if (!entry) {
+      throw new Error(
+        `Together<[…], [… ${member} …]>: this frond declares no class named '${member}'. ` +
+        `The second list names providers to rebuild inside the frame — a service, a mirror, ` +
+        `a repository — so that what they write is covered by the unwind.`,
+      );
+    }
+    return entry;
+  });
+
+  return { entities, providers };
+}
+
+/**
+ * A member that cannot write here at all — its frond is hosted elsewhere.
+ *
+ * Refused rather than compensated: a compensated frame still writes through a local ORM,
+ * and a remote frond registers none. There is nothing to record and nothing to undo.
+ */
+function refuseRemote(members: Members, world: FrameWorld, key: string): void {
+  for (const member of members.entities) {
+    const frond = world.frondOf.get(member.name);
+    if (frond && !world.hostedHere(frond)) {
+      throw new Error(
+        `Together<[…]> (${key}): '${member.name}' belongs to frond '${frond}', which this ` +
+        `process declares in remotes: — it registers no storage here, so its writes cannot be ` +
+        `part of a frame. Host the frond here, or split the work and join the halves with a fact.`,
+      );
+    }
+  }
+}
+
+/**
+ * A provider member writing an entity the frame does not name.
+ *
+ * The frame does not widen itself to cover it: doing so would pull an entity from another
+ * source into the group without anyone writing it down. Named instead, with the one-word fix.
+ */
+function refuseUncoveredWrites(members: Members, key: string): void {
+  const covered = new Set(members.entities.map((member) => member.name));
+  for (const provider of members.providers) {
+    for (const dep of provider.deps) {
+      if (!dep.endsWith('Orm')) continue;
+      const entity = lowerFirst(dep.slice(0, -'Orm'.length));
+      if (covered.has(entity)) continue;
+      throw new Error(
+        `Together<[…]> (${key}): ${provider.ctor.name} writes ${entity}, which is not in the ` +
+        `frame's entity list — its writes would escape the unwind. Add it: ` +
+        `Together<[…, ${upperFirst(entity)}], [… ${provider.ctor.name} …]>.`,
+      );
+    }
+  }
+}
+
+/**
+ * Open the block: build every member over `factory`, in a scope of their own.
+ *
+ * The scope is what makes a provider member work without a locator — its ORM keys are
+ * registered here, so the container hands it the framed ones through the ordinary
+ * constructor. It is disposed when the block ends, whichever way it ended.
+ */
+async function inScope<R>(
+  parent: Container,
+  members: Members,
+  factory: OrmFactory,
+  wrap: (orm: EntityOrm, name: string, schema: SchemaView) => EntityOrm,
+  fn: (entities: unknown[], providers: unknown[]) => Promise<R>,
+): Promise<R> {
+  const scope = parent.createScope();
+  try {
+    const orms = members.entities.map((member) => {
+      const orm = wrap(factory(member.schema, member.name), member.name, member.schema);
+      scope.registerValue(ormKeyOf(member.name), orm);
+      return orm;
+    });
+    // Providers after every ORM is in place: one may depend on another member's.
+    const built = members.providers.map((provider) => {
+      scope.register(provider.ctor.name, provider.ctor, { deps: provider.deps });
+      return scope.resolve(provider.ctor.name);
+    });
+    return await fn(orms, built);
+  } finally {
+    await scope.dispose();
+  }
+}
+
+/**
+ * Register one frame per key a handler or provider of this frond asked for.
+ *
+ * Called with the frond's scope, because that is where the asking constructor resolves —
+ * while the MEMBERS are looked up app-wide, a frame crossing fronds being the ordinary case
+ * rather than the exception (the frond is not the storage boundary; `sources:` is).
+ */
+export function registerFrames(
+  scope: Container,
+  keys: Iterable<string>,
+  providers: readonly ProviderEntry[],
+  world: FrameWorld,
+): void {
+  let registered = 0;
+  for (const key of new Set(keys)) {
+    const names = membersOfTogetherKey(key);
+    if (!names) continue;
+    registered += 1;
+    if (!world.ormFactory) {
+      throw new Error(`Together<[${names.entities.join(', ')}]> needs storage, and this boot declares none.`);
+    }
+
+    const members = resolve(names, providers, world);
+    refuseRemote(members, world, key);
+    refuseUncoveredWrites(members, key);
+
+    const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
+    const judge = (orm: EntityOrm, name: string, schema: SchemaView) =>
+      new StorageGuard(schema.getFields(), name).guard(orm);
+
+    // One engine and a way into it: the engine gives the unwind AND the isolation.
+    if (world.transacted && sources.size === 1) {
+      const source = [...sources][0];
+      world.log.info(`${key} — transaction, source '${source}'`);
+      scope.registerValue(key, {
+        run: <R>(fn: (entities: never, providers: never) => Promise<R>) =>
+          ambient.enterFrame(key, () =>
+            world.transacted!(source, (factory) => inScope(scope, members, factory, judge, fn as never))),
+      });
+      continue;
+    }
+
+    // Split, or an engine that hands out no transaction: the frame keeps the before-image
+    // of every write and replays the inverses itself. `judge` stays OUTSIDE `recording`, so
+    // a write the entity refuses never enters the journal.
+    const why = sources.size > 1
+      ? members.entities.map((m) => `${m.name} in '${world.sourceOf?.(m.name) ?? 'db'}'`).join(', ')
+      : 'this storage hands out no transaction';
+    world.log.info(`${key} — compensated: ${why} — no isolation`);
+    scope.registerValue(key, {
+      run: <R>(fn: (entities: never, providers: never) => Promise<R>): Promise<R> => ambient.enterFrame(key, async () => {
+        const journal: Undo[] = [];
+        const record = (orm: EntityOrm, name: string, schema: SchemaView) =>
+          judge(recording(orm, name, schema.getFields(), journal), name, schema);
+        try {
+          return await inScope(scope, members, world.ormFactory!, record, fn as never);
+        } catch (cause) {
+          return unwind(journal, cause, world.log);
+        }
+      }),
+    });
+  }
+  if (registered > 0 && ambient.degraded) {
+    world.log.warn(
+      'no async context on this runtime — frames run one at a time, and a frame opened '
+      + 'inside another times out instead of being refused',
+    );
+  }
+}