@fougere/core 0.6.0-alpha.0 → 0.8.0-alpha.0

package/src/prefab/repository.ts

@@ -2,68 +2,11 @@ import { upperFirst, type EntityConstructor } from '@fougere/schema';
 import type { Storage, ListOptions, ListResult, SelectOption } from '../storage.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 `storage.ts` already states for
- * `Storage` 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.storages;
- *     …
- *   }
- * }
- * ```
- *
- * `this.storages` 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: CommandeStorage, stock: StockStorage, private frame: Together<[Commande, Stock]>) {
- *   super(commandes, stock);
- * }
- * ```
- *
- * The storage 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.
- */
+/** Repository(…entities) — who owns an entity's storage, and where its questions are named. */
 
 /**
- * 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 `Storage<Post>` is to `PostStorage`, one spelling of one key, and
- * `depKeyOf` reads both.
+ * The shape a repository of ONE entity has — the port itself, plus whatever the subclass names on
+ * top.
  */
 export type RepositoryOf<T> = Storage<T>;
 
@@ -73,13 +16,7 @@ export interface RepositoryConstructor<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.
- */
+/** What an aggregate's subclass sees. */
 declare abstract class AggregateShape<E extends readonly EntityConstructor[]> {
   protected storages: { [K in keyof E]: Storage<InstanceType<E[K]>> };
 }
@@ -103,11 +40,7 @@ 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.
- */
+/** The port forwarded, member by member. */
 function one<E extends EntityConstructor>(entity: E): RepositoryConstructor<InstanceType<E>> {
   type T = InstanceType<E>;
 
@@ -134,11 +67,7 @@ function one<E extends EntityConstructor>(entity: E): RepositoryConstructor<Inst
   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.
- */
+/** The aggregate. */
 function many<E extends readonly EntityConstructor[]>(entities: E): AggregateConstructor<E> {
   class AggregateBase {
     static readonly __entity = entities[0];
@@ -159,12 +88,7 @@ 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.
- */
+/** The entities a class owns — empty for anything that is not an aggregate. */
 export function ownedBy(ctor: unknown): readonly EntityConstructor[] {
   return (ctor as { __owns?: readonly EntityConstructor[] } | undefined)?.__owns ?? [];
 }

package/src/scan/adapters.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** Which adapters a PROJECT could load, read off its dependencies. */
+const ADAPTER_PACKAGE = /^@fougere\/adapter-(.+)$/;
+
+/** The adapter names this project depends on — empty when it has no package.json to read. */
+export async function adaptersOf(root: string): Promise<string[]> {
+  const manifest = await read(join(root, 'package.json'));
+  if (!manifest) return [];
+
+  const declared = { ...manifest.dependencies, ...manifest.devDependencies };
+
+  return Object.keys(declared)
+    .map((name) => ADAPTER_PACKAGE.exec(name)?.[1])
+    .filter((name): name is string => name !== undefined);
+}
+
+async function read(path: string): Promise<Manifest | undefined> {
+  try {
+    return JSON.parse(await readFile(path, 'utf8')) as Manifest;
+  } catch {
+    // No manifest, or one that is not JSON. Either way this cannot validate a name, and
+    // reporting every `adapters:` key as unknown would be worse than saying nothing.
+    return undefined;
+  }
+}
+
+interface Manifest {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}

package/src/scan/bundling.ts

@@ -1,15 +1,4 @@
-/**
- * What a Fougere boot loads at RUNTIME, so a bundler must leave it alone.
- *
- * Stated once because it was stated twice and the two had already drifted: the Vite plugin
- * listed `@fougere/schema`, `@fougere/adapter-graphql` and `@fougere/auth-better`, the Next
- * one did not, and BOTH omitted the two packages `@fougere/app`'s boot actually imports
- * dynamically — `@fougere/defaults` and `@fougere/transport-http`. A list a bundler reads
- * has no way to notice it is wrong: nothing fails at build time, the app fails at boot.
- *
- * It sits here rather than beside the dynamic imports because both readers are BUILD-TIME
- * plugins that already depend on core, and neither may pull the boot into a bundler config.
- */
+/** What a Fougere boot loads at RUNTIME, so a bundler must leave it alone. */
 export const RUNTIME_PACKAGES: readonly string[] = [
   '@fougere/app',
   '@fougere/core',

package/src/scan/contract.ts

@@ -0,0 +1,80 @@
+/** An operation contract, written down — the half two emitters say the same way. */
+import { ANONYMOUS_SCHEMA_NAME, Card, type SchemaView } from '@fougere/schema';
+
+import type { OperationContract } from '../wire/operation.js';
+
+/** A value that ends up as an import in the module being written. */
+export type Live = object;
+
+/**
+ * What the writer needs of an emitter's imports, and nothing more.
+ *
+ * The two emitters index theirs differently — one by value against a relative path, one
+ * by file against the package specifier a project already uses — and neither is wrong for
+ * the module it writes. What they agree on is this: a value already imported has an
+ * alias, a class can be imported by name, and an entity can be found by its class name.
+ */
+export interface Aliases {
+  aliasOf(value: Live): string | undefined;
+  named(value: Live, filePath: string, name: string): string;
+  /** The entity class this name belongs to — what a `Partial<X>` names as its source. */
+  classNamed(name: string): Live | undefined;
+}
+
+export const lit = (value: unknown): string => JSON.stringify(value ?? null);
+
+/** What a schema slot becomes in the generated module. */
+export function schemaRef(
+  schema: SchemaView | undefined,
+  declaredIn: string,
+  imports: Aliases,
+): 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.classNamed(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.',
+  );
+}
+
+/** One entry of an operations Map, as its module spells it. */
+export function contractOf(
+  op: string,
+  contract: OperationContract,
+  declaredIn: string,
+  imports: Aliases,
+): string {
+  const parts: string[] = [];
+  const input = schemaRef(contract.input, declaredIn, imports);
+  const output = schemaRef(contract.output, declaredIn, imports);
+  if (input) parts.push(`input: ${input}`);
+  if (output) parts.push(`output: ${output}`);
+  if (contract.binding !== undefined) parts.push(`binding: ${lit(contract.binding)}`);
+  if (contract.description !== undefined) parts.push(`description: ${lit(contract.description)}`);
+  if (contract.cardinality !== undefined) parts.push(`cardinality: ${lit(contract.cardinality)}`);
+  if (contract.signature !== undefined) parts.push(`signature: ${lit(contract.signature)}`);
+
+  return `[${lit(op)}, { ${parts.join(', ')} }]`;
+}
+
+/** The operations of one handler, as the Map its reader builds. */
+export function operationsOf(
+  operations: ReadonlyMap<string, OperationContract>,
+  declaredIn: string,
+  imports: Aliases,
+  indent: string,
+): string {
+  const ops = [...operations].map((entry) => contractOf(entry[0], entry[1], declaredIn, imports));
+
+  return `new Map([\n${indent}  ${ops.join(`,\n${indent}  `)}\n${indent}])`;
+}

package/src/scan/conventions.ts

@@ -1,19 +1,7 @@
-/**
- * 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.
- */
+/** The names the scan READS instead of deriving them. */
 
 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.
-   */
+  /** The scope a frond's package name carries — `@fronds/blog`. */
   scope: string;
   /** The directory holding fronds, below the project root. */
   fronds: string;
@@ -31,12 +19,7 @@ export interface Conventions {
   };
 }
 
-/**
- * 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.
- */
+/** What a project means when it declares nothing — the convention itself. */
 export const DEFAULT_CONVENTIONS: Conventions = {
   scope: '@fronds',
   fronds: 'fronds',
@@ -59,13 +42,7 @@ export type ConventionsInput = {
   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.
- */
+/** The convention, with a project's exceptions folded in. */
 export function resolveConventions(input?: ConventionsInput): Conventions {
   return {
     scope: input?.scope ?? DEFAULT_CONVENTIONS.scope,
@@ -79,23 +56,12 @@ 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.
- */
+/** Directories whose classes register as providers — two spellings, one behaviour. */
 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`.
- */
+/** The frond vocabulary — every directory the scan reads. */
 export function frondDirsOf(conventions: Conventions): string[] {
   const { entities, handlers, presenters, collectors, seeds, versions } = conventions.dirs;
   return [...new Set([

package/src/scan/emit.ts

@@ -1,24 +1,9 @@
-/**
- * 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.
- */
+/** The scan, written down as a module — what `createApp` is handed where there is no disk. */
 import { dirname, relative } from 'node:path';
-import { ANONYMOUS_SCHEMA_NAME, Card, type SchemaView } from '@fougere/schema';
+import { nameOf } from '../descriptor/frond.js';
 import type { FrondDescriptor, EntityEntry, HandlerEntry, PresenterEntry, CollectorEntry, ProviderEntry, SeedEntry } from '../descriptor/frond.js';
 import type { ScanResult } from './result.js';
-import type { OperationContract } from '../wire/operation.js';
+import { type Aliases, type Live, lit, operationsOf, schemaRef } from './contract.js';
 
 export interface EmitOptions {
   /** Where the generated module will sit. Imports are written relative to it. */
@@ -27,28 +12,17 @@ export interface EmitOptions {
   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.
- */
+/** A source file becomes a specifier its reader can follow — and the two readers differ. */
 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 {
+class Imports implements Aliases {
   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. */
@@ -78,63 +52,23 @@ class Imports {
 
   has(value: Live): boolean { return this.byValue.has(value); }
   aliasOf(value: Live): string | undefined { return this.byValue.get(value); }
+  classNamed(name: string): Live | undefined { return this.byClassName.get(name); }
   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 ops = operationsOf(h.operations, 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    ]) }`;
+    + `operations: ${ops} }`;
 }
 
 function presenterOf(p: PresenterEntry, imports: Imports): string {
@@ -151,7 +85,8 @@ function collectorOf(c: CollectorEntry, imports: Imports): string {
 }
 
 function providerOf(p: ProviderEntry, imports: Imports): string {
-  return `{ ctor: ${imports.aliasOf(p.ctor as Live)}, deps: ${lit(p.deps)}, filePath: ${lit(p.filePath)} }`;
+  return `{ name: ${lit(nameOf(p))}, ctor: ${imports.aliasOf(p.ctor as Live)}, `
+    + `deps: ${lit(p.deps)}, filePath: ${lit(p.filePath)} }`;
 }
 
 function seedOf(s: SeedEntry, imports: Imports): string {
@@ -178,11 +113,7 @@ function frondOf(f: FrondDescriptor, imports: Imports): string {
   ].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.
- */
+/** Write a scan down. */
 export function emitScan(result: ScanResult, options: EmitOptions): string {
   const imports = new Imports(options.outFile);
   const core = options.core ?? '@fougere/core';