@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/prefab/presenter.ts

@@ -0,0 +1,63 @@
+/**
+ * Presenter(Entity) — enriches an entity's output with computed fields.
+ *
+ * Each method on the presenter is a computed field resolver:
+ * - Receives the entity record as first argument
+ * - Can be sync or async
+ * - Injected via DI (constructor params resolved by the container)
+ *
+ * Usage:
+ * ```ts
+ * export default class PostPresenter extends Presenter(Post) {
+ *   constructor(private commentOrm: CommentOrm) { super(); }
+ *
+ *   excerpt(post: Post) {
+ *     return post.body.slice(0, 200);
+ *   }
+ *
+ *   async commentCount(post: Post) {
+ *     return this.commentOrm.countFor(post.id);
+ *   }
+ * }
+ * ```
+ */
+
+import { upperFirst, type EntityConstructor } from '@fougere/schema';
+
+/**
+ * The view a computed field emits — `OrderItemView` for one, `[OrderItemView]` for many.
+ * A view is a schema, so it derives: `Order.pick('id', 'status')`, never a hand-written type.
+ */
+export type PresenterViews = Record<string, EntityConstructor | [EntityConstructor]>;
+
+/**
+ * `Presenter(Order, { items: [OrderItemView], user: UserCard })` — the second argument names
+ * the view each computed field emits, exactly as `Crud(Post, { list: PostCard })` names an
+ * op's. What fabricates a field declares its contract, and it declares it **once**: the
+ * façade applies the presenter (see `PresenterExecutor`), and every surface reads the same statement
+ * instead of guessing.
+ *
+ * Guessing was the cost of not stating it. The scan can read a scalar off a return type and
+ * nothing more, so a field returning an object had no derivable shape: the GraphQL projection
+ * fell back to a serialized `String`, and a client asking `items { quantity }` got a schema
+ * error on a field REST served whole. Declaring is optional — a scalar field needs nothing,
+ * and an undeclared object keeps the old behaviour.
+ */
+export function Presenter<E extends EntityConstructor>(entity: E, views?: PresenterViews) {
+  class PresenterBase {
+    static readonly __entity = entity;
+    static readonly __views = views;
+  }
+  return PresenterBase;
+}
+
+/** List computed field names from a presenter class (own methods minus constructor). */
+export function getPresenterFields(ctor: Function): string[] {
+  return Object.getOwnPropertyNames(ctor.prototype)
+    .filter((name) => name !== 'constructor' && typeof ctor.prototype[name] === 'function');
+}
+
+/** Container key of an entity's presenter — 'post' → 'PostPresenter'. */
+export function presenterKeyOf(entity: string): string {
+  return `${upperFirst(entity)}Presenter`;
+}

package/src/prefab/repository.ts

@@ -0,0 +1,170 @@
+import { upperFirst, type EntityConstructor } from '@fougere/schema';
+import type { EntityOrm, ListOptions, ListResult, SelectOption } from '../orm.js';
+import type { SchemaView } from '@fougere/schema';
+
+/**
+ * Repository(…entities) — who owns an entity's storage, and where its questions are named.
+ *
+ * **The arity decides**, which is the second reading of what `orm.ts` already states for
+ * `EntityOrm` against `Together`: the arity of the unit is the whole distinction.
+ *
+ * ONE entity — the repository IS that entity's storage, with your methods added. The port's
+ * thirteen gestures are forwarded, so a handler reads `this.posts.list()` whether or not
+ * anyone wrote the file, and a named question sits beside them:
+ *
+ * ```ts
+ * // repositories/PostRepository.ts
+ * export default class PostRepository extends Repository(Post) {
+ *   published() {
+ *     return this.list({ where: { status: 'published' }, orderBy: 'publishedAt', order: 'desc' });
+ *   }
+ * }
+ * ```
+ *
+ * TWO OR MORE — an aggregate. It owns them: nothing else in the app is handed their
+ * storage, and no gesture is forwarded (which entity would `create` write to?), so the only
+ * way in is a method this class names. That is what lets a rule spanning two tables exist:
+ * it is ordinary TypeScript inside the method that does the writing.
+ *
+ * ```ts
+ * // repositories/CommandeRepository.ts
+ * export default class CommandeRepository extends Repository(Commande, Stock) {
+ *   avecLignes(id: string) {
+ *     const [commandes, stock] = this.orms;
+ *     …
+ *   }
+ * }
+ * ```
+ *
+ * `this.orms` is protected, because the whole point is that the storage stops at this file.
+ * `protected` is erased at runtime, like `abstract` on a port: a compile-time guarantee, not
+ * a barrier. The same bargain, already accepted.
+ *
+ * **The boundary is not the unit of work.** An aggregate says the rules of these entities
+ * hold together; a frame says these writes land together, and the two lists coincide only
+ * often. Deriving the frame from the membership would make a read-only aggregate carry one
+ * — refusals included, and `registerFrames` refuses without storage or over `remotes:` —
+ * and would put `Together<[Commande, Stock], [StockMirror]>` out of reach forever. So a
+ * frame is ASKED FOR here as anywhere else, which is what makes it declared:
+ *
+ * ```ts
+ * constructor(commandes: CommandeOrm, stock: StockOrm, private frame: Together<[Commande, Stock]>) {
+ *   super(commandes, stock);
+ * }
+ * ```
+ *
+ * The ORM words come back in that line, and only there: this class IS the holder, which is
+ * the one case `boot/ownership.ts` lets name the storage it was built on.
+ *
+ * A repository is NOT a door: it has no façade, so nothing here is reachable from the wire.
+ */
+
+/**
+ * The shape a repository of ONE entity has — the port itself, plus whatever the subclass
+ * names on top. Written by an author who has not written the file: `RepositoryOf<Post>` is
+ * to `PostRepository` what `EntityOrm<Post>` is to `PostOrm`, one spelling of one key, and
+ * `depKeyOf` reads both.
+ */
+export type RepositoryOf<T> = EntityOrm<T>;
+
+/** The single-entity form: the port, plus whatever the subclass names. */
+export interface RepositoryConstructor<T> {
+  new (orm: EntityOrm<T>): EntityOrm<T>;
+  readonly __entity: unknown;
+}
+
+/**
+ * What an aggregate's subclass sees: the storage of the members it owns, in declared order,
+ * and `protected` — the storage stops at that file, which is the whole mechanism.
+ *
+ * A class and not an interface, because `protected` cannot be spelled in one. Ambient: the
+ * value it describes is fabricated by `many()` for an arity only known at the call.
+ */
+declare abstract class AggregateShape<E extends readonly EntityConstructor[]> {
+  protected orms: { [K in keyof E]: EntityOrm<InstanceType<E[K]>> };
+}
+
+/** The tuple an aggregate holds — the readable form of {@link AggregateShape}'s member. */
+export type AggregateOf<E extends readonly EntityConstructor[]> =
+  { [K in keyof E]: EntityOrm<InstanceType<E[K]>> };
+
+export type AggregateConstructor<E extends readonly EntityConstructor[]> =
+  (new (...orms: unknown[]) => AggregateShape<E>) & {
+    readonly __entity: unknown;
+    /** The entities this class owns. Present from two on — an owner of one owns nothing. */
+    readonly __owns: E;
+  };
+
+export function Repository<E extends EntityConstructor>(entity: E): RepositoryConstructor<InstanceType<E>>;
+export function Repository<E extends readonly [EntityConstructor, EntityConstructor, ...EntityConstructor[]]>(
+  ...entities: E
+): AggregateConstructor<E>;
+export function Repository(...entities: EntityConstructor[]): unknown {
+  return entities.length === 1 ? one(entities[0]) : many(entities);
+}
+
+/**
+ * The port forwarded, member by member. Written out rather than proxied: a Proxy would
+ * answer every name including the ones the port does not have, and this file would then
+ * state the surface nowhere. Thirteen lines against one declaration that can be read.
+ */
+function one<E extends EntityConstructor>(entity: E): RepositoryConstructor<InstanceType<E>> {
+  type T = InstanceType<E>;
+
+  class RepositoryBase implements EntityOrm<T> {
+    static readonly __entity = entity;
+
+    constructor(protected orm: EntityOrm<T>) {}
+
+    list(options?: ListOptions & SelectOption): Promise<ListResult<T>> { return this.orm.list(options); }
+    findById(id: string, options?: SelectOption) { return this.orm.findById(id, options); }
+    findBy(criteria: Partial<T> | Record<string, unknown>, options?: SelectOption) { return this.orm.findBy(criteria, options); }
+    findAllBy(criteria: Partial<T> | Record<string, unknown>, options?: SelectOption) { return this.orm.findAllBy(criteria, options); }
+    findByKeys(ids: readonly string[], options?: SelectOption) { return this.orm.findByKeys(ids, options); }
+    findAllByKeys(field: string, keys: readonly string[], options?: SelectOption) { return this.orm.findAllByKeys(field, keys, options); }
+    create(input: Partial<T>, options?: SelectOption) { return this.orm.create(input, options); }
+    upsert(input: Partial<T>, options?: SelectOption) { return this.orm.upsert(input, options); }
+    upsertAll(inputs: readonly Partial<T>[], options?: SelectOption) { return this.orm.upsertAll(inputs, options); }
+    update(id: string, input: Partial<T>, options?: SelectOption) { return this.orm.update(id, input, options); }
+    delete(id: string) { return this.orm.delete(id); }
+    output(schema: SchemaView) { return this.orm.output(schema); }
+    get client(): unknown { return this.orm.client; }
+  }
+
+  return RepositoryBase as unknown as RepositoryConstructor<T>;
+}
+
+/**
+ * The aggregate. Its constructor takes the members' storage in the DECLARED order — the
+ * order `toProvider` fills its `deps` with, and the order a subclass hands back to `super()`
+ * when it declares a constructor of its own.
+ */
+function many<E extends readonly EntityConstructor[]>(entities: E): AggregateConstructor<E> {
+  class AggregateBase {
+    static readonly __entity = entities[0];
+    static readonly __owns = entities;
+
+    protected orms: AggregateOf<E>;
+
+    constructor(...orms: unknown[]) {
+      this.orms = orms.slice(0, entities.length) as AggregateOf<E>;
+    }
+  }
+
+  return AggregateBase as unknown as AggregateConstructor<E>;
+}
+
+/** Container key of an entity's repository — 'reading' → 'ReadingRepository'. */
+export function repositoryKeyOf(entity: string): string {
+  return `${upperFirst(entity)}Repository`;
+}
+
+/**
+ * The entities a class owns — empty for anything that is not an aggregate.
+ *
+ * Read from the mark rather than from the constructor, for the reason `Crud.__ops` exists:
+ * the AST scan is workspace-only, so an installed prefab resolves to nothing.
+ */
+export function ownedBy(ctor: unknown): readonly EntityConstructor[] {
+  return (ctor as { __owns?: readonly EntityConstructor[] } | undefined)?.__owns ?? [];
+}

package/src/scan/Fronds.ts

@@ -0,0 +1,73 @@
+import type { SchemaView } from '@fougere/schema';
+import type { EntityEntry, FrondDescriptor } from './frond.js';
+
+/**
+ * What this app hosts — the scan's answer, with the questions everyone was asking it
+ * by hand.
+ *
+ * The list was a bare array, so every reader re-walked it: "which frond owns this
+ * entity" was spelled four times, "every entity by name" three times as three literal
+ * copies of the same `Map`, and the two inside the boot even carried comments saying so.
+ * A concept nobody can question is a concept everyone rebuilds.
+ *
+ * It IS an array — the same reason `ListResult` is one: twenty call sites iterate,
+ * filter and spread it, and none of them is wrong to. `Symbol.species` is `Array` so a
+ * `.map()` over it answers a plain array rather than something that claims to be a
+ * hosting table and holds strings.
+ */
+export class Fronds extends Array<FrondDescriptor> {
+  static override get [Symbol.species](): ArrayConstructor {
+    return Array;
+  }
+
+  /** What one scan run found. The only gate in — `Array.of` is taken, and named. */
+  static scanned(fronds: readonly FrondDescriptor[]): Fronds {
+    const held = new Fronds();
+    held.push(...fronds);
+    return held;
+  }
+
+  /** The frond that hosts an entity — `undefined` when no loaded frond does. */
+  owner(entity: string): FrondDescriptor | undefined {
+    return this.find((frond) => frond.entities.some((e) => e.name === entity));
+  }
+
+  /** The entity of that name, wherever it was scanned. */
+  entity(name: string): EntityEntry | undefined {
+    for (const frond of this) {
+      const found = frond.entities.find((e) => e.name === name);
+      if (found) return found;
+    }
+    return undefined;
+  }
+
+  /**
+   * Every scanned entity class, by name — across all fronds and never per-frond.
+   *
+   * A fact is announced in one frond and heard in another, so the subscriber's own
+   * frond does not hold the shape it must judge; a `reads:` clause names entities
+   * that belong to neighbours by definition.
+   */
+  schemas(): Map<string, SchemaView> {
+    return new Map(this.flatMap((frond) => frond.entities.map((e) => [e.name, e.entityClass] as const)));
+  }
+
+  /** Every scanned entity, sorted. What was FOUND, not what answers. */
+  entityNames(): string[] {
+    return this.flatMap((frond) => frond.entities.map((e) => e.name)).sort();
+  }
+
+  /**
+   * The names a call may address, sorted — what a NOT_FOUND must print.
+   *
+   * Not `entityNames()`, which is what the scan found: an entity with no handler is
+   * scanned and serves nothing, so the refusal read *"Entity 'indexed' is not hosted
+   * here. Hosted here: indexed."* — naming the very thing it had just refused. A façade
+   * is keyed on a HANDLER's address, and that is what this lists.
+   */
+  servedNames(surface?: string): string[] {
+    return this.flatMap((frond) => frond.handlers
+      .filter((handler) => (handler.surface ?? undefined) === surface)
+      .map((handler) => handler.address)).sort();
+  }
+}

package/src/scan/conventions.ts

@@ -0,0 +1,122 @@
+/**
+ * The names the scan READS instead of deriving them.
+ *
+ * Everything else a frond states, it states by its shape; these seven directories and the
+ * import prefix are the one place where a name is the declaration. They were spelled as
+ * literals in five packages, so a project could not move any of them and `frondsDir` was
+ * a declared key with no reader.
+ */
+import { join } from 'node:path';
+
+export interface Conventions {
+  /**
+   * The scope a frond's package name carries — `@fronds/blog`.
+   *
+   * A real package name, not only an alias: the CLI writes it as `name` in a scaffolded
+   * frond and as a `workspace:*` dependency in the app that consumes it.
+   */
+  scope: string;
+  /** The directory holding fronds, below the project root. */
+  fronds: string;
+  /** Directory per role. The role is the key; the name on disk is the value. */
+  dirs: {
+    entities: string;
+    handlers: string;
+    services: string;
+    repositories: string;
+    presenters: string;
+    collectors: string;
+    seeds: string;
+    /** What its shapes used to be — written by `fougere freeze`, replayed by `migrate`. */
+    versions: string;
+  };
+}
+
+/**
+ * What a project means when it declares nothing — the convention itself.
+ *
+ * `@fronds` and not `@frond`: the npm org for the singular belongs to someone else, and a
+ * scope is a name that must be ownable.
+ */
+export const DEFAULT_CONVENTIONS: Conventions = {
+  scope: '@fronds',
+  fronds: 'fronds',
+  dirs: {
+    entities: 'entities',
+    handlers: 'handlers',
+    services: 'services',
+    repositories: 'repositories',
+    presenters: 'presenters',
+    collectors: 'collectors',
+    seeds: 'seeds',
+    versions: 'versions',
+  },
+};
+
+/** What a `fougere.config.ts` may state: only the names that differ. */
+export type ConventionsInput = {
+  scope?: string;
+  fronds?: string;
+  dirs?: Partial<Conventions['dirs']>;
+};
+
+/**
+ * The convention, with a project's exceptions folded in.
+ *
+ * Merged one level into `dirs` so renaming one directory does not require restating the
+ * other six — the same reading `sources:` and `ports:` get, where only the exception is
+ * declared.
+ */
+export function resolveConventions(input?: ConventionsInput): Conventions {
+  return {
+    scope: input?.scope ?? DEFAULT_CONVENTIONS.scope,
+    fronds: input?.fronds ?? DEFAULT_CONVENTIONS.fronds,
+    dirs: { ...DEFAULT_CONVENTIONS.dirs, ...input?.dirs },
+  };
+}
+
+/** The package name a frond answers to. */
+export function frondPackage(name: string, conventions: Conventions): string {
+  return `${conventions.scope}/${name}`;
+}
+
+/**
+ * Directories whose classes register as providers — two spellings, one behaviour.
+ *
+ * A project may point both roles at one directory; the scan must then read it once, or
+ * every provider would be registered twice.
+ */
+export function providerDirsOf(conventions: Conventions): string[] {
+  return [...new Set([conventions.dirs.services, conventions.dirs.repositories])];
+}
+
+/**
+ * The frond vocabulary — every directory the scan reads.
+ *
+ * What a reader needs to bound a frond: the Nuxt module watches these for the root frond
+ * (watching the root itself would match every write), and a flat app's tsconfig lists
+ * them instead of `["."]`, which would swallow `app/` and `nuxt.config.ts`.
+ */
+export function frondDirsOf(conventions: Conventions): string[] {
+  const { entities, handlers, presenters, collectors, seeds, versions } = conventions.dirs;
+  return [...new Set([
+    entities, handlers, presenters, collectors, seeds, versions, ...providerDirsOf(conventions),
+  ])];
+}
+
+/**
+ * What changes when a frond's domain changes — the paths a dev loop watches.
+ *
+ * The root frond IS the scan root, so watching its path would match every write in the
+ * project: `.nuxt/`, `node_modules/`, the build output. Its convention directories are
+ * the frond, and they are what a scan re-reads.
+ */
+export function watchPathsOf(
+  frond: { source: { path: string } },
+  scanRoot: string,
+  conventions: Conventions,
+): string[] {
+  return frond.source.path === scanRoot
+    ? frondDirsOf(conventions).map((dir) => join(scanRoot, dir))
+    : [frond.source.path];
+}

package/src/scan/emit.ts

@@ -0,0 +1,231 @@
+/**
+ * The scan, written down as a module — what `createApp` is handed where there is no disk.
+ *
+ * It RE-RESOLVES NOTHING. By the time this runs the scan has already decided what every
+ * slot holds, and `resolveSchema` put the entity's own class in `contract.output` — the
+ * very object `EntityEntry.entityClass` holds. So the emitter keeps a table from object
+ * to import alias and writes the alias. Identity is preserved because it is the same
+ * object that becomes the same import, which is what three call sites depend on
+ * (`adapter/graphql`'s `view === entity.entityClass` and its WeakMap, and `bootstrap`'s
+ * `outputSchema !== entity.entityClass`). An emitter that re-resolved instead would build
+ * a second class for `Post` and those three would silently take the other branch.
+ *
+ * Measured on three real projects: every live reference is either a class the descriptor
+ * already names by `filePath`, a named export of the file that declared the signature, or
+ * `Partial<X>` — the one derivation `resolveSchema` fabricates.
+ */
+import { dirname, relative } from 'node:path';
+import { ANONYMOUS_SCHEMA_NAME, Card, type SchemaView } from '@fougere/schema';
+import type {
+  ScanResult, FrondDescriptor, EntityEntry, HandlerEntry,
+  PresenterEntry, CollectorEntry, ProviderEntry, SeedEntry,
+} from './frond.js';
+import type { OperationContract } from '../wire/operation.js';
+
+export interface EmitOptions {
+  /** Where the generated module will sit. Imports are written relative to it. */
+  outFile: string;
+  /** How `@fougere/core` is reached from there. Default: the package name. */
+  core?: string;
+}
+
+type Live = object;
+
+/** Is a TypeScript compiler going to read this module? Its name is the only thing that says. */
+const isTypeScript = (outFile: string): boolean => /\.tsx?$/.test(outFile);
+
+/**
+ * A source file becomes a specifier its reader can follow — and the two readers differ.
+ *
+ * A `.ts` destination is compiled by tsc under Node16 resolution, which spells a
+ * TypeScript source with `.js`. A `.mjs` destination is read by a bundler, which resolves
+ * the path AS IT IS ON DISK — measured, Nitro's rollup refused `Post.seed.js` because no
+ * such file exists. One rule, read off the destination, exactly like the type annotation.
+ */
+function specifierOf(filePath: string, outFile: string): string {
+  const path = relative(dirname(outFile), filePath);
+  const rel = isTypeScript(outFile) ? path.replace(/\.tsx?$/, '.js') : path;
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+const lit = (v: unknown): string => JSON.stringify(v ?? null);
+
+class Imports {
+  private readonly byValue = new Map<Live, string>();
+  private readonly lines: string[] = [];
+  /** Entity classes by their class name — what a `Partial<X>` names as its source. */
+  readonly byClassName = new Map<string, Live>();
+
+  constructor(private readonly outFile: string) {}
+
+  /** Register `value` as the default export of `filePath`, and answer its alias. */
+  default(value: Live, filePath: string): string {
+    const known = this.byValue.get(value);
+    if (known) return known;
+    const alias = `_${this.lines.length}`;
+    this.lines.push(`import ${alias} from '${specifierOf(filePath, this.outFile)}';`);
+    this.byValue.set(value, alias);
+    return alias;
+  }
+
+  /** Register `value` as a NAMED export of `filePath` — its class name is the export. */
+  named(value: Live, filePath: string, name: string): string {
+    const known = this.byValue.get(value);
+    if (known) return known;
+    const alias = `_${this.lines.length}`;
+    this.lines.push(`import { ${name} as ${alias} } from '${specifierOf(filePath, this.outFile)}';`);
+    this.byValue.set(value, alias);
+    return alias;
+  }
+
+  has(value: Live): boolean { return this.byValue.has(value); }
+  aliasOf(value: Live): string | undefined { return this.byValue.get(value); }
+  render(): string { return this.lines.join('\n'); }
+}
+
+/**
+ * What a schema slot becomes in the generated module.
+ *
+ * Three answers, and the third is the only rule: a class already imported is its alias; a
+ * named export of the file that declared the signature is imported by its own name — it
+ * IS exported there, because that is where `resolveSchema` found it; and an anonymous
+ * schema is `Partial<X>`, the one derivation `resolveSchema` builds, so it is written as
+ * the derivation rather than as a value.
+ */
+function schemaRef(schema: SchemaView | undefined, declaredIn: string, imports: Imports): string | undefined {
+  if (!schema) return undefined;
+  const known = imports.aliasOf(schema as Live);
+  if (known) return known;
+
+  const name = (schema as { name?: string }).name;
+  if (name && name !== ANONYMOUS_SCHEMA_NAME) return imports.named(schema as Live, declaredIn, name);
+
+  const card = Card.fromSchema(schema);
+  const source = card.origin?.from ?? card.descriptor.title;
+  const from = source ? imports.byClassName.get(source) : undefined;
+  if (from) return `${imports.aliasOf(from)}.partial()`;
+
+  throw new Error(
+    `A scan cannot be written down: an anonymous schema in ${declaredIn} names no source. `
+    + 'Only `Partial<X>` is derivable here, and it says which X it came from.',
+  );
+}
+
+function contractOf(op: string, c: OperationContract, declaredIn: string, imports: Imports): string {
+  const parts: string[] = [];
+  const input = schemaRef(c.input, declaredIn, imports);
+  const output = schemaRef(c.output, declaredIn, imports);
+  if (input) parts.push(`input: ${input}`);
+  if (output) parts.push(`output: ${output}`);
+  if (c.binding !== undefined) parts.push(`binding: ${lit(c.binding)}`);
+  if (c.description !== undefined) parts.push(`description: ${lit(c.description)}`);
+  if (c.cardinality !== undefined) parts.push(`cardinality: ${lit(c.cardinality)}`);
+  if (c.signature !== undefined) parts.push(`signature: ${lit(c.signature)}`);
+  return `[${lit(op)}, { ${parts.join(', ')} }]`;
+}
+
+function entityOf(e: EntityEntry, imports: Imports): string {
+  return `{ name: ${lit(e.name)}, entityClass: ${imports.aliasOf(e.entityClass as Live)}, `
+    + `filePath: ${lit(e.filePath)}, exposed: ${lit(e.exposed)} }`;
+}
+
+function handlerOf(h: HandlerEntry, imports: Imports): string {
+  const ops = [...h.operations].map(([op, c]) => contractOf(op, c, h.filePath, imports));
+  const override = schemaRef(h.outputOverride, h.filePath, imports);
+  return `{ name: ${lit(h.name)}, address: ${lit(h.address)}, ctor: ${imports.aliasOf(h.ctor as Live)}, `
+    + `deps: ${lit(h.deps)}, filePath: ${lit(h.filePath)}, exposed: ${lit(h.exposed)}, `
+    + (h.surface ? `surface: ${lit(h.surface)}, ` : '')
+    + (override ? `outputOverride: ${override}, ` : '')
+    + `operations: new Map([\n      ${ops.join(',\n      ')}\n    ]) }`;
+}
+
+function presenterOf(p: PresenterEntry, imports: Imports): string {
+  // `views` is not written: it is read back off the constructor (`__views`), so emitting
+  // it would be a second copy of a statement the imported class already carries.
+  return `{ entityName: ${lit(p.entityName)}, ctor: ${imports.aliasOf(p.ctor as Live)}, `
+    + `fields: ${lit(p.fields)}, fieldMeta: ${lit(p.fieldMeta)}, deps: ${lit(p.deps)}, `
+    + `filePath: ${lit(p.filePath)} }`;
+}
+
+function collectorOf(c: CollectorEntry, imports: Imports): string {
+  return `{ typeName: ${lit(c.typeName)}, ctor: ${imports.aliasOf(c.ctor as Live)}, `
+    + `deps: ${lit(c.deps)}, filePath: ${lit(c.filePath)} }`;
+}
+
+function providerOf(p: ProviderEntry, imports: Imports): string {
+  return `{ ctor: ${imports.aliasOf(p.ctor as Live)}, deps: ${lit(p.deps)}, filePath: ${lit(p.filePath)} }`;
+}
+
+function seedOf(s: SeedEntry, imports: Imports): string {
+  const data = typeof s.data === 'function' ? imports.aliasOf(s.data as Live) : lit(s.data);
+  return `{ entityName: ${lit(s.entityName)}, data: ${data}, filePath: ${lit(s.filePath)} }`;
+}
+
+function frondOf(f: FrondDescriptor, imports: Imports): string {
+  const list = (label: string, items: string[]) =>
+    `    ${label}: [${items.length ? `\n      ${items.join(',\n      ')},\n    ` : ''}],`;
+  return [
+    '  {',
+    `    name: ${lit(f.name)},`,
+    `    source: ${lit(f.source)},`,
+    list('providers', f.providers.map((p) => providerOf(p, imports))),
+    list('entities', f.entities.map((e) => entityOf(e, imports))),
+    list('handlers', f.handlers.map((h) => handlerOf(h, imports))),
+    list('presenters', f.presenters.map((p) => presenterOf(p, imports))),
+    list('collectors', f.collectors.map((c) => collectorOf(c, imports))),
+    list('seeds', f.seeds.map((s) => seedOf(s, imports))),
+    f.surfaces ? `    surfaces: ${lit(f.surfaces)},` : '',
+    f.reads ? `    reads: ${lit(f.reads)},` : '',
+    '  }',
+  ].filter(Boolean).join('\n');
+}
+
+/**
+ * Write a scan down. The result is a TypeScript module whose only imports are the classes
+ * the scan found — static, so a bundler traces them — and whose only value is the
+ * descriptor `createApp` asks for.
+ */
+export function emitScan(result: ScanResult, options: EmitOptions): string {
+  const imports = new Imports(options.outFile);
+  const core = options.core ?? '@fougere/core';
+
+  // Every class the descriptor names by a file comes first: a schema slot holding one of
+  // them then finds it in the table instead of being imported a second time.
+  for (const f of result.fronds) {
+    for (const e of f.entities) {
+      imports.default(e.entityClass as Live, e.filePath);
+      const name = (e.entityClass as { name?: string }).name;
+      if (name) imports.byClassName.set(name, e.entityClass as Live);
+    }
+    for (const p of f.providers) imports.default(p.ctor as Live, p.filePath);
+    for (const h of f.handlers) imports.default(h.ctor as Live, h.filePath);
+    for (const p of f.presenters) imports.default(p.ctor as Live, p.filePath);
+    for (const c of f.collectors) imports.default(c.ctor as Live, c.filePath);
+    for (const s of f.seeds) if (typeof s.data === 'function') imports.default(s.data as Live, s.filePath);
+  }
+
+  const fronds = result.fronds.map((f) => frondOf(f, imports)).join(',\n');
+  // `cause` is dropped: it is an Error, and the build that produced this already reported
+  // it. What a boot logs is the message, and that travels.
+  const diagnostics = result.diagnostics.map(({ cause: _cause, ...rest }) => lit(rest));
+
+  // The annotation is a convenience for a file a human's tsc will read; it is never what
+  // makes the value correct. A bundler parses a `.mjs` as JavaScript and `import type`
+  // stops it dead — measured, Nitro's rollup refused the Nuxt template at that line.
+  const typed = isTypeScript(options.outFile);
+
+  return `// Generated by \`fougere build\` — the scan, written down. Do not edit.
+//
+// \`createApp\` reads this instead of a disk. Everything here was decided by the scan that
+// produced it; nothing is resolved a second time.
+import { Fronds } from '${core}';
+${typed ? `import type { ScanResult } from '${core}';\n` : ''}${imports.render()}
+
+export const scan${typed ? ': ScanResult' : ''} = {
+  fronds: Fronds.scanned([
+${fronds}
+  ]),
+  diagnostics: [${diagnostics.join(', ')}],
+};
+`;
+}