@fougere/core 0.9.3-alpha.0 → 0.11.0-alpha.0

package/src/descriptor/FrondDescriptor.ts

@@ -0,0 +1,58 @@
+import type { OperationContract } from '../wire/OperationContract.js';
+import type { ProviderEntry } from './ProviderEntry.js';
+import type { EntityEntry } from './EntityEntry.js';
+import type { HandlerEntry } from './HandlerEntry.js';
+import type { PresenterEntry } from './PresenterEntry.js';
+import type { CollectorEntry } from './CollectorEntry.js';
+import type { MiddlewareEntry } from './MiddlewareEntry.js';
+import type { SeedEntry } from './SeedEntry.js';
+import type { FrondSource } from './FrondSource.js';
+import type { ExtensionEntry } from './ExtensionEntry.js';
+
+/**
+ * The key a provider answers under. What the source said, and the class's own name only
+ * where nobody wrote it down — a statement is read as code, and code can say it.
+ */
+export const nameOf = (provider: ProviderEntry): string => provider.name ?? provider.ctor.name;
+
+export interface FrondDescriptor {
+  name: string;
+  source: FrondSource;
+  providers: ProviderEntry[];
+  entities: EntityEntry[];
+  handlers: HandlerEntry[];
+  presenters: PresenterEntry[];
+  collectors: CollectorEntry[];
+  seeds: SeedEntry[];
+  middlewares: MiddlewareEntry[];
+  /** What this frond mounts on the process that serves it. Absent when it declares none. */
+  extensions?: ExtensionEntry[];
+  /**
+   * Brought by an EXTENSION rather than by the app — `@fougere/calls` keeping its lines,
+   * `@fougere/observability` sending them on. It is installed like any other, and it is not
+   * what the app SERVES: a report that lists it describes the instrumentation, not the
+   * domain. Set by the boot, never by a declaration.
+   */
+  brought?: true;
+  /** The ops that finish a fact, in order — see `FrondConfig.pipes`. */
+  pipes?: Record<string, string[]>;
+  /**
+   * Per-surface entity lists from frond.config.ts (e.g. { graphql: ['Post'], rest: ['Post',
+   * 'Author'] }).
+   */
+  surfaces?: Record<string, string[]>;
+  /** Entities this frond may read across sources — see `FrondConfig.reads`. */
+  reads?: string[];
+  /** Per-operation overrides from frond.config.ts. */
+  operationsOverrides?: Record<string, OperationContract & {
+    kind?: 'query' | 'command';
+    /** Class name to resolve from DI (overrides default `{Entity}Handler` lookup). */
+    handlerName?: string;
+    /** Method name on the resolved handler (defaults to op name). */
+    method?: string;
+    /** The GraphQL root field this op answers to — read by `adapter/graphql`. */
+    graphql?: string;
+    /** Where it answers over REST — read by `adapter/rest`, the dual of `graphql`. */
+    rest?: { method?: string; path?: string; status?: number };
+  }>;
+}

package/src/descriptor/FrondSource.ts

@@ -0,0 +1,7 @@
+/** Where a frond lives on disk. */
+export interface FrondSource {
+  /** Absolute path to the frond directory. */
+  path: string;
+  /** The @fronds/{name} package name. Always present. */
+  package: string;
+}

package/src/descriptor/Fronds.ts

@@ -1,5 +1,6 @@
 import type { SchemaView } from '@fougere/schema';
-import type { EntityEntry, FrondDescriptor } from './frond.js';
+import type { EntityEntry } from './EntityEntry.js';
+import type { FrondDescriptor } from './FrondDescriptor.js';
 
 /** What this app hosts, with the questions everyone was asking it by hand. */
 export class Fronds extends Array<FrondDescriptor> {

package/src/descriptor/HandlerEntry.ts

@@ -0,0 +1,27 @@
+import type { SchemaView } from '@fougere/schema';
+import type { OperationsMap } from '../wire/OperationsMap.js';
+
+/** A discovered handler (controls what a service exposes). */
+export interface HandlerEntry {
+  /** Registration key (e.g. 'postHandler'). */
+  name: string;
+  /**
+   * The name this handler answers to — its class name minus `Handler`, lowercased (`PostHandler` →
+   * `post`).
+   */
+  address: string;
+  /** The handler class. */
+  ctor: new (...args: never[]) => unknown;
+  /** All operations with full signatures for binding. */
+  operations: OperationsMap;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+  /** Whether this handler is part of the frond's public contract. */
+  exposed?: boolean;
+  /** Output schema override — when Crud(Entity, Output), restricts storage output. */
+  outputOverride?: SchemaView;
+  /** Surface name — subdirectory in handlers/ (e.g. 'admin', 'public'). */
+  surface?: string;
+}

package/src/descriptor/MiddlewareEntry.ts

@@ -0,0 +1,16 @@
+/**
+ * A discovered middleware — a class declaring `around(ctx, next)`, which runs before and
+ * after every operation in its scope.
+ */
+export interface MiddlewareEntry {
+  /** Class name — what `frond.config.ts` addresses to widen the scope. */
+  name: string;
+  /** The middleware class. */
+  ctor: new (...args: never[]) => unknown;
+  /** How far it reaches: its own frond's entities, or every operation in the process. */
+  scope: 'frond' | 'app';
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}

package/src/descriptor/PresenterEntry.ts

@@ -0,0 +1,23 @@
+import type { PresenterViews } from '../prefab/presenter.js';
+import type { PresenterFieldMeta } from './PresenterFieldMeta.js';
+
+/** A discovered presenter (computed fields for an entity's output). */
+export interface PresenterEntry {
+  /** Entity name this presenter enriches (e.g. 'post' from PostPresenter). */
+  entityName: string;
+  /** The presenter class. */
+  ctor: new (...args: never[]) => unknown;
+  /** Computed field names (method names on prototype). */
+  fields: string[];
+  /** Per-field type metadata (inferred from source via parser). */
+  fieldMeta: PresenterFieldMeta[];
+  /**
+   * The view each computed field emits, when the presenter declares one (`Presenter(Order, {
+   * items: [OrderItemView] })`).
+   */
+  views?: PresenterViews;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}

package/src/descriptor/PresenterFieldMeta.ts

@@ -0,0 +1,14 @@
+import type { Param } from '../wire/Param.js';
+
+/** Return type metadata for a presenter computed field. */
+export interface PresenterFieldMeta {
+  name: string;
+  /** Inferred return type name: 'string', 'number', 'boolean', or a class name. */
+  returnType?: string;
+  /** The field emits a LIST per row — `tags(posts: Post[]): string[][]`. */
+  list?: boolean;
+  /** Whether the return is nullable. */
+  nullable?: boolean;
+  /** The declared parameters AFTER the rows. */
+  params?: Param[];
+}

package/src/descriptor/ProviderEntry.ts

@@ -0,0 +1,18 @@
+/** A discovered provider — a class under `services/` or `repositories/`, injected by type. */
+export interface ProviderEntry {
+  /**
+   * The container key — the class name as the SOURCE spells it.
+   *
+   * Read at boot off `ctor.name` for a decade of no consequence, until a bundler lowered
+   * a `static readonly` field and renamed the declaration doing it: the provider
+   * registered as `_Communes` and the handler asking for `Communes` got a container miss.
+   * A name a tool may rewrite is written down, for the same reason `deps` is.
+   */
+  name?: string;
+  /** The class constructor (default export of the file). */
+  ctor: new (...args: never[]) => unknown;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}

package/src/descriptor/SeedEntry.ts

@@ -0,0 +1,11 @@
+import type { SeedFactory } from './SeedFactory.js';
+
+/** A discovered seed file (array of records or async factory). */
+export interface SeedEntry {
+  /** Entity name this seed targets (from filename: Author.seed.ts → 'author'). */
+  entityName: string;
+  /** Raw default export — array or function. Resolved at runtime. */
+  data: Record<string, unknown>[] | SeedFactory;
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}

package/src/descriptor/SeedFactory.ts

@@ -0,0 +1,2 @@
+/** Seed factory — receives a resolver to access handlers cross-frond. */
+export type SeedFactory = (resolve: <T>(name: string) => T) => Promise<Record<string, unknown>[]>;

package/src/descriptor/bases.ts

@@ -0,0 +1,30 @@
+import { type ProviderEntry } from './ProviderEntry.js';
+
+/**
+ * Port class name → the classes that extend it, in scan order.
+ *
+ * ONE condition, and the caller owns it: something already answers under that name. The boot
+ * asks its container, where the providers sit in the frond's scope and the builtins in its
+ * parent — so a neighbour service and `Logger` both count, a framework class being a port like
+ * any other, which is what makes a default overridable.
+ *
+ * It is also what excludes a prefab: a repository extends the class `Repository(Post)`
+ * returned (`RepositoryBase`), and no key is ever that name.
+ *
+ * Read twice, which is why it is stated once: the boot binds against it, and the scan emits
+ * the same relation as types so a config cannot name a class that does not answer the port.
+ */
+export function basesOf(
+  providers: ProviderEntry[],
+  answers: (name: string) => boolean,
+): Map<string, ProviderEntry[]> {
+  const bases = new Map<string, ProviderEntry[]>();
+  for (const provider of providers) {
+    const base = Object.getPrototypeOf(provider.ctor) as { name?: string } | null;
+    const port = base?.name;
+    if (!port || !answers(port)) continue;
+    bases.set(port, [...(bases.get(port) ?? []), provider]);
+  }
+
+  return bases;
+}

package/src/descriptor/index.ts

@@ -2,14 +2,32 @@
  * What it takes to PRODUCE a descriptor — the surface a scan reads, whoever wrote it.
  * The main entry serves what an app RUNS; this one serves what fills it in.
  */
-export * from './frond.js';
+export * from './ProviderEntry.js';
+export * from './EntityEntry.js';
+export * from './HandlerEntry.js';
+export * from './PresenterFieldMeta.js';
+export * from './PresenterEntry.js';
+export * from './CollectorEntry.js';
+export * from './MiddlewareEntry.js';
+export * from './SeedEntry.js';
+export * from './SeedFactory.js';
+export * from './FrondSource.js';
+export * from './ExtensionEntry.js';
+export * from './FrondDescriptor.js';
 export { Fronds } from './Fronds.js';
 
-export { cardinalityOf, type OperationContract, type OperationsMap, type Param, type TypeRef } from '../wire/operation.js';
+export { cardinalityOf, type OperationContract } from '../wire/OperationContract.js';
+export { type OperationsMap } from '../wire/OperationsMap.js';
+export { type Param } from '../wire/Param.js';
+export { type TypeRef } from '../wire/TypeRef.js';
 export { computeBindingPlan, type BindingPlan } from '../wire/binding.js';
-export type { Signature } from '../wire/signature.js';
-export { emitKeyOf, awaitKeyOf } from '../wire/emit.js';
-export { storageKeyOf } from '../storage/port.js';
+export type { Signature } from '../wire/Signature.js';
+export { awaitKeyOf, emitKeyOf } from '../wire/Emit.js';
+export { storageKeyOf } from '../storage/Storage.js';
 export { getPresenterFields } from '../prefab/presenter.js';
 export { targetOf, viewsOf, outputOf } from '../prefab/prefab.js';
-export { ownedBy, repositoryKeyOf } from '../prefab/repository.js';
+export { ownedBy, repositoryKeyOf } from '../prefab/RepositoryConstructor.js';
+
+// The surfaces a handler answers on — a directory names one, and so does `frond.config.ts`.
+export { servedSurfaces } from './surface.js';
+export { basesOf } from './bases.js';

package/src/descriptor/surface.ts

@@ -1,8 +1,9 @@
-import type { FrondDescriptor, HandlerEntry } from './frond.js';
+import type { FrondDescriptor } from './FrondDescriptor.js';
+import type { HandlerEntry } from './HandlerEntry.js';
 
 /**
  * The surfaces a handler answers on — its own when it has one, otherwise the default
- * and every surface that names its address without opening a door of its own.
+ * and every surface that names its address without opening a facade of its own.
  * `undefined` is the default surface, as `facadeKeyOf` and `RouteAddress` spell it.
  */
 export function servedSurfaces(

package/src/diagnostic.ts

@@ -0,0 +1,41 @@
+/**
+ * One thing that does not hold, in the terms of whoever has to fix it — raised by the scan,
+ * by a boot rule, or by `fougere check`, which is why it belongs to no phase.
+ */
+export interface Diagnostic {
+  /**
+   * `blocking` — the app now serves less than its source declares, and no caller can know it: a
+   * handler that failed to parse contributes zero operations.
+   */
+  severity: 'blocking' | 'warning';
+  /** Stable rule name — `handler-parse-failed`, `directory-unreadable`. */
+  code: string;
+  /** Where to go and look. */
+  filePath: string;
+  /** The frond it belongs to, when whoever raised it got far enough to know. */
+  frond?: string;
+  /**
+   * What the diagnostic is ABOUT — `PostHandler.publish` — when the rule holds it as a fact
+   * rather than inside its sentence. Two ops of one handler breaking the same rule read as
+   * one repeated line without it.
+   */
+  subject?: string;
+  /** What does not hold, and what it costs. One sentence, for a human. */
+  message: string;
+  /** The underlying failure, kept whole. */
+  cause?: unknown;
+}
+
+/**
+ * Every blocking diagnostic in ONE refusal, so a boot names all of them rather than the
+ * first — the shape `fougere check` renders, read back by whoever has to fix it.
+ */
+export function refusalOf(diagnostics: readonly Diagnostic[], what: string): Error | undefined {
+  const blocking = diagnostics.filter((one) => one.severity === 'blocking');
+  if (blocking.length === 0) return undefined;
+
+  const lines = blocking.map((one) =>
+    `  [${one.code}]${one.subject ? ` ${one.subject}` : ''}\n    ${one.message}\n    ${one.filePath}`);
+
+  return new Error(`Fougere boot refused: ${blocking.length} ${what}:\n${lines.join('\n')}`);
+}

package/src/dispatch/ArgumentResolver.ts

@@ -1,11 +1,6 @@
-import type { InvocationContext } from '../wire/Invocation.js';
+import type { InvocationContext } from '../wire/InvocationContext.js';
 import type { BindingPlan } from '../wire/binding.js';
-
-export interface CollectorResolver {
-  collect(ctx: InvocationContext): Promise<unknown>;
-}
-
-export type CollectorLookup = (typeName: string) => CollectorResolver | undefined;
+import type { CollectorLookup } from './CollectorLookup.js';
 
 /** Resolves an operation's declared binding plan against one invocation. */
 export class ArgumentResolver {

package/src/dispatch/CollectorLookup.ts

@@ -0,0 +1,3 @@
+import type { CollectorResolver } from './CollectorResolver.js';
+
+export type CollectorLookup = (typeName: string) => CollectorResolver | undefined;

package/src/dispatch/CollectorResolver.ts

@@ -0,0 +1,5 @@
+import type { InvocationContext } from '../wire/InvocationContext.js';
+
+export interface CollectorResolver {
+  collect(ctx: InvocationContext): Promise<unknown>;
+}

package/src/dispatch/Dependent.ts

@@ -0,0 +1,19 @@
+import type { OnDelete } from '@fougere/schema';
+
+/**
+ * A `ref()` read from the TARGET's side: rows that name it, and what becomes of them.
+ *
+ * The dual of `RelationCheck`, which reads the same declaration from the child's side to judge
+ * a write. Only what no foreign key holds reaches here — a key answers at the rows, inside the
+ * delete's own transaction, and nothing in this process would see it happen.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export interface Dependent {
+  /** The entity whose rows name the target — `post`. */
+  entity: string;
+  /** The field carrying the key — `authorId`. */
+  field: string;
+  /** Unstated is `restrict`: what a foreign key does when nothing is said. */
+  onDelete: OnDelete;
+}

package/src/dispatch/DispatchEvent.ts

@@ -1,7 +1,6 @@
-import type { Call } from '../wire/call.js';
-import type { RouteKind } from '../wire/RouteAddress.js';
-
-export type DispatchStage = 'received' | 'resolved' | 'completed' | 'failed' | 'settled';
+import type { Call } from '../wire/Call.js';
+import type { RouteKind } from '../wire/RouteKind.js';
+import type { DispatchStage } from './DispatchStage.js';
 
 /** Immutable transition observed across one dispatch lifecycle. */
 export class DispatchEvent {
@@ -34,5 +33,3 @@ export class DispatchEvent {
     return new DispatchEvent('settled', call, routeKind);
   }
 }
-
-export type DispatchObserver = (event: DispatchEvent) => void;

package/src/dispatch/DispatchLifecycle.ts

@@ -1,4 +1,5 @@
-import type { DispatchEvent, DispatchObserver } from './DispatchEvent.js';
+import type { DispatchEvent } from './DispatchEvent.js';
+import type { DispatchObserver } from './DispatchObserver.js';
 
 /** Publishes dispatch transitions without participating in dispatch decisions. */
 export class DispatchLifecycle {

package/src/dispatch/DispatchObserver.ts

@@ -0,0 +1,3 @@
+import type { DispatchEvent } from './DispatchEvent.js';
+
+export type DispatchObserver = (event: DispatchEvent) => void;

package/src/dispatch/DispatchPort.ts

@@ -1,4 +1,4 @@
-import type { Call } from '../wire/call.js';
+import type { Call } from '../wire/Call.js';
 
 /** The only capability an entry needs. */
 export interface DispatchPort {

package/src/dispatch/DispatchStage.ts

@@ -0,0 +1 @@
+export type DispatchStage = 'received' | 'resolved' | 'completed' | 'failed' | 'settled';

package/src/dispatch/Dispatcher.ts

@@ -1,4 +1,4 @@
-import type { Call } from '../wire/call.js';
+import type { Call } from '../wire/Call.js';
 import { DispatchEvent } from './DispatchEvent.js';
 import { DispatchLifecycle } from './DispatchLifecycle.js';
 import type { DispatchPort } from './DispatchPort.js';
@@ -7,6 +7,7 @@ import type { RoutePolicy } from './RoutePolicy.js';
 import { RouteRegistry } from './RouteRegistry.js';
 import { routeNotFound, servedOperations } from './routeNotFound.js';
 import type { InFlight } from './InFlight.js';
+import type { Journal } from './Journal.js';
 
 /** Resolves and executes every call through the same transverse lifecycle. */
 export class Dispatcher implements DispatchPort {
@@ -15,22 +16,57 @@ export class Dispatcher implements DispatchPort {
     private readonly inFlight: InFlight,
     private readonly lifecycle = new DispatchLifecycle(),
     private readonly policy?: RoutePolicy,
+    private readonly journalOf?: () => Journal | undefined,
   ) {}
 
+  /** The route that answers this address, or the refusal naming what is served instead. */
+  private async routeFor(call: Call): Promise<Route> {
+    const known = this.routes.find(call.address);
+    const resolved = known ?? await this.routes.resolve(call.address);
+    const route = resolved && (!this.policy || this.policy.accepts(resolved)) ? resolved : undefined;
+    if (!route) {
+      throw this.policy?.notFound?.(call, this.routes.routes())
+        ?? routeNotFound(call, servedOperations(call, this.routes.routes(), this.policy));
+    }
+
+    return route;
+  }
+
+  /**
+   * A kept call publishes no dispatch event and enters no flight: it has not been answered,
+   * and counting it here would report one call spanning the days until its hour.
+   *
+   * Its address is resolved all the same. What is kept is made hours later, by then against
+   * whatever the app still serves — so an address nothing answers is refused to the caller who
+   * can still fix it, rather than to a beat nobody is watching.
+   */
+  private async keep(call: Call, runAt: number): Promise<undefined> {
+    await this.routeFor(call);
+
+    const journal = this.journalOf?.();
+    if (!journal) {
+      throw new Error(
+        `${call.address.toString()} asks to run at ${new Date(runAt).toISOString()}, and nothing keeps it.`
+        + ' Install a package answering Journal — @fougere/workflow.',
+      );
+    }
+
+    await journal.keep(call, runAt);
+
+    return undefined;
+  }
+
   async dispatch(call: Call): Promise<unknown> {
+    const { runAt } = call.invocation;
+    if (runAt !== undefined) return this.keep(call, runAt);
+
     let route: Route | undefined;
     let release: (() => void) | undefined;
     this.lifecycle.publish(DispatchEvent.received(call));
 
     try {
       release = this.inFlight.enter(call.address.entity, call.address.operation);
-      const known = this.routes.find(call.address);
-      const resolved = known ?? await this.routes.resolve(call.address);
-      route = resolved && (!this.policy || this.policy.accepts(resolved)) ? resolved : undefined;
-      if (!route) {
-        throw this.policy?.notFound?.(call, this.routes.routes())
-          ?? routeNotFound(call, servedOperations(call, this.routes.routes(), this.policy));
-      }
+      route = await this.routeFor(call);
 
       this.lifecycle.publish(DispatchEvent.resolved(call, route.kind));
       const result = await route.execute(call);

package/src/dispatch/Facade.ts

@@ -0,0 +1,25 @@
+import type { Container } from '@fougere/container';
+import { type AppMiddleware } from '../wire/AppMiddleware.js';
+import type { EffectiveOperationsMap } from '../EffectiveOperationsMap.js';
+import type { HandlerEntry } from '../descriptor/HandlerEntry.js';
+import type { PresenterEntry } from '../descriptor/PresenterEntry.js';
+
+/** What boot resolved around one handler, beyond the handler and the scope it resolves in. */
+export interface Facade {
+  /** The container key this facade answers under. */
+  key: string;
+  /** The frond this facade belongs to — travels on every OperationContext. */
+  frond: string;
+  /** Handlers in the owning frond, used to realize a resolved implementation override. */
+  handlers: readonly HandlerEntry[];
+  /** The canonical operation table resolved before boot performs any side effect. */
+  operations: EffectiveOperationsMap;
+  /** Entity names this frond has a collector for. */
+  collectors: Set<string>;
+  /** The presenter over this handler's entity, when the frond declares one. */
+  presenter: PresenterEntry | undefined;
+  /** Presenters live in the frond's own scope, whatever sub-scope this facade resolves in. */
+  presenterScope: Container;
+  /** The middlewares that apply to this address, read at call time and never at boot. */
+  middlewares: () => AppMiddleware[];
+}

package/src/dispatch/GuardReport.ts

@@ -0,0 +1,9 @@
+import { type Fields } from '@fougere/schema';
+
+/** What a guard says about a filter it let through. The boot owns the voice. */
+export interface GuardReport {
+  /** The fields this facade hands back, when it hands back fewer than the entity has. */
+  view?: Fields;
+  /** Said once per field — a filter is not a write, and a warning per call is noise. */
+  outOfView?: (message: string) => void;
+}