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

package/src/boot/nesting.ts

@@ -0,0 +1,196 @@
+/**
+ * Who inherits code from whom, read off `FougereConfig.fronds` and judged before anything is
+ * built. It reads no disk and holds no container: the scopes it decides are built later, in
+ * `install.ts`, and everything here is a fact about names.
+ *
+ * Documented: [fronds](https://fougere.dev/docs/infra/fronds).
+ */
+import type { Diagnostic } from '../diagnostic.js';
+import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+import { Fronds } from '../descriptor/Fronds.js';
+import { statesModule, type FrondsStated } from '../FrondsStated.js';
+import { statedFronds } from '../StatedFrond.js';
+
+/** A frond that holds what a family shares serves nothing — which is what keeps it here. */
+function refuseServingParent(
+  parent: FrondDescriptor,
+  children: string[],
+  refused: Diagnostic[],
+): boolean {
+  if (parent.handlers.length === 0) return false;
+
+  const served = [...new Set(parent.handlers.map((handler) => handler.address))];
+  refused.push({
+    severity: 'blocking',
+    code: 'frond-parent-serves',
+    filePath: parent.handlers[0]!.filePath,
+    frond: parent.name,
+    subject: parent.name,
+    message: `'${parent.name}' has children (${children.join(', ')}) and answers at `
+      + `${served.join(', ')}. A frond its family inherits from holds the code they share and `
+      + 'nothing else — with no façade, nothing can call it and nothing can place it elsewhere. '
+      + 'Move its handlers into a child, or take the children out.',
+  });
+
+  return true;
+}
+
+/** Rows belong to a frond something can call — the family case is not traced, so it is refused. */
+function refuseParentEntities(
+  parent: FrondDescriptor,
+  children: string[],
+  refused: Diagnostic[],
+): void {
+  if (parent.entities.length === 0) return;
+
+  refused.push({
+    severity: 'blocking',
+    code: 'frond-parent-entities',
+    filePath: parent.entities[0]!.filePath,
+    frond: parent.name,
+    subject: parent.name,
+    message: `'${parent.name}' has children (${children.join(', ')}) and declares `
+      + `${parent.entities.map((entity) => entity.name).join(', ')}. A frond they inherit from `
+      + 'holds code, not rows. Declare the entity in a child and import it from there — '
+      + `\`import X from '@fronds/<child>/entities/X.js'\` reaches it from anywhere.`,
+  });
+}
+
+/** What the tree says, against what this process actually holds. */
+export function nestingOf(
+  stated: FrondsStated | undefined,
+  fronds: Fronds,
+  remotes: Record<string, string> | undefined,
+  /** This process carries a subset of the project — `only:`, so an absent name is expected. */
+  narrowed = false,
+): { under: Map<string, string>; refused: Diagnostic[] } {
+  const refused: Diagnostic[] = [];
+  const under = new Map<string, string>();
+  if (stated === undefined) return { under, refused };
+
+  const statements = statedFronds(stated);
+  const here = new Map(fronds.map((frond) => [frond.name, frond]));
+  const childrenOf = new Map<string, string[]>();
+  const inherits = new Set<string>();
+  for (const statement of statements) {
+    if (statement.extends === undefined) continue;
+
+    inherits.add(statement.key);
+    childrenOf.set(statement.extends, [...(childrenOf.get(statement.extends) ?? []), statement.key]);
+  }
+
+  for (const statement of statements) {
+    if (statement.extends === undefined || !inherits.has(statement.extends)) continue;
+
+    refused.push({
+      severity: 'blocking',
+      code: 'frond-extends-chain',
+      filePath: 'fougere.config.ts',
+      subject: statement.path,
+      message: `'${statement.key}' inherits from '${statement.extends}', which inherits from `
+        + `'${statedFronds(stated).find((one) => one.key === statement.extends)?.extends}'. `
+        + 'Inheriting goes one level: a scope hangs off the one above it, and a chain would make '
+        + 'a frond depend on code its own family never named. Move what they share into one '
+        + 'frond they both inherit from.',
+    });
+  }
+
+  // A frond a family inherits from needs no entry of its own — `extends` is said by the
+  // inheritor — so what it may not be is asked of the NAMES, not of the entries.
+  for (const [parent, children] of childrenOf) {
+    const frond = here.get(parent);
+    if (frond === undefined) continue;
+
+    const placed = stated[parent];
+    const address = typeof placed === 'string' ? placed : placed?.remote;
+    if (address !== undefined || (remotes && parent in remotes)) {
+      refused.push({
+        severity: 'blocking',
+        code: 'frond-parent-remote',
+        filePath: frond.source.path,
+        frond: frond.name,
+        subject: parent,
+        message: `'${parent}' is inherited from by ${children.join(', ')} and is placed at `
+          + `${address ?? remotes?.[parent]}. A frond they inherit from stands in every process `
+          + 'that holds one of them, so it has no address of its own. Give the address to one of '
+          + 'them, or have them inherit from somewhere else.',
+      });
+    }
+
+    if (!refuseServingParent(frond, children, refused)) refuseParentEntities(frond, children, refused);
+  }
+
+  for (const statement of statements) {
+    const frond = here.get(statement.key);
+
+    if (frond === undefined) {
+      // Three ways a stated name is absent from this process and says nothing wrong: a module
+      // key, which the host imports; an address, whose frond answers elsewhere by definition;
+      // and a frond `only:` left out, since the config describes the PROJECT and the flag one
+      // process. What is left is a name nothing carries — a typo, and the config is where it
+      // was made, so that is where the message points.
+      const elsewhere = statement.value !== undefined || (remotes && statement.key in remotes);
+      if (!statesModule(statement.key) && !elsewhere && here.size > 0 && !narrowed) {
+        refused.push({
+          severity: 'blocking',
+          code: 'frond-unknown',
+          filePath: 'fougere.config.ts',
+          subject: statement.path,
+          message: `'${statement.path}' names no frond this project holds. It has `
+            + `${[...here.keys()].join(', ') || 'none'}. Check the spelling, or drop the entry.`,
+        });
+      }
+      continue;
+    }
+
+    if (statement.extends !== undefined && !here.has(statement.extends)) {
+      refused.push({
+        severity: 'blocking',
+        code: 'frond-family-split',
+        filePath: frond.source.path,
+        frond: frond.name,
+        subject: statement.path,
+        message: `'${statement.key}' inherits from '${statement.extends}', which this process does `
+          + 'not carry. A frond cannot leave the code it resolves behind — carry the two '
+          + `together, or take '${statement.key}' out from under '${statement.extends}'.`,
+      });
+      continue;
+    }
+
+    if (statement.extends !== undefined) under.set(statement.key, statement.extends);
+  }
+
+  return { under, refused };
+}
+
+/**
+ * The same fronds, each parent before the ones inheriting from it — the order the boot installs
+ * them in, since a scope hangs off the one above it.
+ *
+ * A partition and not a sort: inheriting goes one level, so a frond that inherits has nothing
+ * under it and two passes are enough. Stable, and the same array when nothing inherits — which
+ * is what `orderSeeds` reads.
+ */
+export function parentsFirst(fronds: Fronds, under: Map<string, string>): Fronds {
+  if (under.size === 0) return fronds;
+
+  return Fronds.hosting([
+    ...fronds.filter((frond) => !under.has(frond.name)),
+    ...fronds.filter((frond) => under.has(frond.name)),
+  ]);
+}
+
+/**
+ * The same `under` a boot stamps, for a reader that does not boot — `fougere check` and
+ * `fougere explain` resolve the model off a scan, and a scan knows nothing of the tree.
+ * Without it they report every inherited dependency as a crossing.
+ */
+export function nested(fronds: Fronds, stated: FrondsStated | undefined): Fronds {
+  const { under } = nestingOf(stated, fronds, undefined, true);
+  for (const frond of fronds) {
+    const parent = under.get(frond.name);
+    if (parent !== undefined) frond.extends = parent;
+  }
+
+  return parentsFirst(fronds, under);
+}

package/src/boot/ownership.ts

@@ -84,6 +84,83 @@ function builtOn(ctor: unknown): string[] {
 }
 
 /** `Storage<E>` is not a word of the user's vocabulary — `<E>Repository` is the one way in. */
+/**
+ * A provider named `<Entity>Storage` takes the key of that entity's own storage — and the storage
+ * is registered second, so the provider is never resolved. The name is already wrong by two other
+ * rules, which is why nothing hits it; it is said rather than left silent.
+ */
+function refuseStorageKeyAsProvider(
+  provider: ProviderEntry,
+  frond: string,
+  known: (entity: string) => boolean,
+  refused: Diagnostic[],
+): void {
+  // The key the boot registers it under, which a bundler may have renamed — the same reading
+  // `ProviderEntry.name` exists for.
+  const registered = nameOf(provider);
+  const held = entityOfStorageKey(registered, known);
+  if (!held) return;
+
+  refused.push({
+    severity: 'blocking',
+    code: 'storage-key-is-provider',
+    filePath: provider.filePath,
+    frond,
+    subject: registered,
+    message: `${registered} is a provider, and it is the container key of ${held}'s own storage `
+      + '— the storage is registered second, so the provider is never resolved. Name it for '
+      + 'what it holds; `<Entity>Storage` belongs to the entity.',
+  });
+}
+
+/**
+ * Storage is reached through a repository, and an OWNED entity's not even that way: an aggregate's
+ * members are reached through it and nowhere else. The ownership question is asked first, so a
+ * member says who owns it rather than being told to write a repository it may not have.
+ */
+function refuseStorageReached(
+  decl: { ctor: { name: string }; deps: string[]; filePath: string; kind: string },
+  frond: string,
+  owners: Map<string, string>,
+  known: (entity: string) => boolean,
+  refused: Diagnostic[],
+): void {
+  const allowed = decl.kind === 'provider' ? builtOn(decl.ctor) : [];
+
+  for (const dep of decl.deps) {
+    const entity = entityOfStorageKey(dep, known);
+    if (!entity) continue;
+
+    const owner = owners.get(entity);
+    if (owner && owner !== decl.ctor.name) {
+      refused.push({
+        severity: 'blocking',
+        code: 'aggregate-storage-reached',
+        filePath: decl.filePath,
+        frond,
+        subject: `${decl.ctor.name}(${dep})`,
+        message: `${decl.ctor.name} asks for ${dep}, and ${owner} owns ${entity}. Nothing else `
+          + `reaches an owned entity's storage — name the operation on ${owner} and ask for it: `
+          + `constructor(private ${entity}: ${owner}) {}`,
+      });
+      continue;
+    }
+    if (allowed.includes(entity)) continue;
+
+    refused.push({
+      severity: 'blocking',
+      code: 'storage-outside-repository',
+      filePath: decl.filePath,
+      frond,
+      subject: `${decl.ctor.name}(${dep})`,
+      message: `${decl.ctor.name} asks for ${dep}. Storage is reached through a repository, never `
+        + `through the port: constructor(private ${entity}: ${repositoryKeyOf(entity)}) {}. It `
+        + `answers every gesture ${dep} does, whether or not anyone wrote the file — and the day `
+        + `${entity} belongs to an aggregate, this line does not move.`,
+    });
+  }
+}
+
 export function storageInUserCode(
   frond: FrondDescriptor,
   owners: Map<string, string>,
@@ -97,59 +174,10 @@ export function storageInUserCode(
   ];
   const holders = frond.providers.map((p) => ({ ...p, kind: 'provider' as const }));
 
-  for (const provider of holders) {
-    // The key the boot registers it under, which a bundler may have renamed — the same
-    // reading `ProviderEntry.name` exists for.
-    const registered = nameOf(provider);
-    const held = entityOfStorageKey(registered, known);
-    if (!held) continue;
-
-    refused.push({
-      severity: 'blocking',
-      code: 'storage-key-is-provider',
-      filePath: provider.filePath,
-      frond: frond.name,
-      subject: registered,
-      message: `${registered} is a provider, and it is the container key of ${held}'s own storage `
-        + '— the storage is registered second, so the provider is never resolved. Name it for '
-        + 'what it holds; `<Entity>Storage` belongs to the entity.',
-    });
-  }
+  for (const provider of holders) refuseStorageKeyAsProvider(provider, frond.name, known, refused);
 
   for (const decl of [...facades, ...holders]) {
-    const allowed = decl.kind === 'provider' ? builtOn(decl.ctor) : [];
-    for (const dep of decl.deps) {
-      const entity = entityOfStorageKey(dep, known);
-      if (!entity) continue;
-
-      const owner = owners.get(entity);
-      if (owner && owner !== decl.ctor.name) {
-        refused.push({
-          severity: 'blocking',
-          code: 'aggregate-storage-reached',
-          filePath: decl.filePath,
-          frond: frond.name,
-          subject: `${decl.ctor.name}(${dep})`,
-          message: `${decl.ctor.name} asks for ${dep}, and ${owner} owns ${entity}. Nothing else `
-            + `reaches an owned entity's storage — name the operation on ${owner} and ask for it: `
-            + `constructor(private ${entity}: ${owner}) {}`,
-        });
-        continue;
-      }
-      if (allowed.includes(entity)) continue;
-
-      refused.push({
-        severity: 'blocking',
-        code: 'storage-outside-repository',
-        filePath: decl.filePath,
-        frond: frond.name,
-        subject: `${decl.ctor.name}(${dep})`,
-        message: `${decl.ctor.name} asks for ${dep}. Storage is reached through a repository, never `
-          + `through the port: constructor(private ${entity}: ${repositoryKeyOf(entity)}) {}. It `
-          + `answers every gesture ${dep} does, whether or not anyone wrote the file — and the day `
-          + `${entity} belongs to an aggregate, this line does not move.`,
-      });
-    }
+    refuseStorageReached(decl, frond.name, owners, known, refused);
   }
 }
 

package/src/boot/ports.ts

@@ -111,35 +111,54 @@ function chain(
   stated: string | readonly string[] | undefined,
   refused: Diagnostic[],
 ): ProviderEntry[] {
-  // The whole chain, outside in — a string is a chain of one, and the last name is what
-  // actually answers. What a deployment wraps its realization with is the same kind of
-  // decision as which realization it uses, so it is the same key.
-  if (stated !== undefined) {
-    const order = typeof stated === 'string' ? [stated] : stated;
-    const all = [...wrappers, ...impls];
-
-    return order.flatMap((name) => {
-      const pick = all.find((one) => nameOf(one) === name);
-      if (!pick) {
-        refused.push({
-          severity: 'blocking',
-          code: 'port-not-extended',
-          filePath: all[0]?.filePath ?? 'fougere.config.ts',
-          subject: `ports: { ${port}: '${name}' }`,
-          message: `${port}: '${name}' does not extend it. What does: ${all.map(nameOf).join(', ')}.`,
-        });
-
-        return [];
-      }
-
-      return [pick];
+  if (stated !== undefined) return statedChain(port, [...wrappers, ...impls], stated, refused);
+
+  refuseUndecided(port, impls, wrappers, refused);
+
+  return [...wrappers, ...impls];
+}
+
+/**
+ * The whole chain, outside in — a string is a chain of one, and the last name is what actually
+ * answers. What a deployment wraps its realization with is the same kind of decision as which
+ * realization it uses, so it is the same key.
+ */
+function statedChain(
+  port: string,
+  all: ProviderEntry[],
+  stated: string | readonly string[],
+  refused: Diagnostic[],
+): ProviderEntry[] {
+  const order = typeof stated === 'string' ? [stated] : stated;
+
+  return order.flatMap((name) => {
+    const pick = all.find((one) => nameOf(one) === name);
+    if (pick) return [pick];
+
+    refused.push({
+      severity: 'blocking',
+      code: 'port-not-extended',
+      filePath: all[0]?.filePath ?? 'fougere.config.ts',
+      subject: `ports: { ${port}: '${name}' }`,
+      message: `${port}: '${name}' does not extend it. What does: ${all.map(nameOf).join(', ')}.`,
     });
-  }
 
+    return [];
+  });
+}
+
+/**
+ * Two realizations, or two wrappers, and nothing saying which — refused rather than settled by
+ * scan order, the same reason `remotes` refuses two owners of one entity: whichever won would
+ * depend on the order files were read, and the handler would charge the wrong provider silently.
+ */
+function refuseUndecided(
+  port: string,
+  impls: ProviderEntry[],
+  wrappers: ProviderEntry[],
+  refused: Diagnostic[],
+): void {
   if (impls.length > 1) {
-    // Refusing rather than keeping one, for the reason `remotes` refuses two owners
-    // of an entity: whichever won would depend on scan order, and the handler would
-    // charge the wrong provider without a word.
     refused.push({
       severity: 'blocking',
       code: 'port-implemented-twice',
@@ -149,12 +168,9 @@ function chain(
         + 'answers it. Which realization a deployment uses is not a fact about the code — state it: '
         + `ports: { ${port}: '${nameOf(impls[0]!)}' } in fougere.config.ts.`,
     });
-
-    return [...wrappers, ...impls];
   }
 
   if (wrappers.length > 1) {
-    // Same refusal one layer out: two wrappers are an ORDER, and scan order is not one.
     refused.push({
       severity: 'blocking',
       code: 'port-wrapped-twice',
@@ -166,6 +182,4 @@ function chain(
         + 'in fougere.config.ts.',
     });
   }
-
-  return [...wrappers, ...impls];
 }

package/src/boot/remote.ts

@@ -65,36 +65,9 @@ export function createRemoteRouter(
 
     for (const answered of cards) {
       if (!answered) continue;
-      const { label, url, transport, answer } = answered;
-      pending.delete(label);
-      const card = assertIdentityCard(answer, `Remote '${label}' (${url})`);
 
-      for (const frond of card.fronds) {
-        // Facades only. A fact is not routable — nobody calls it, it arrives — so
-        // adding one here would answer a call with a transport to a facade that
-        // does not exist.
-        for (const facade of frond.facades) {
-          const first = claimedBy.get(facade.name);
-          /** Two remotes claiming one name is refused, not silently arbitrated. */
-          if (first !== undefined && first !== label) {
-            throw new FougereError({
-              code: ErrorCode.INTERNAL_ERROR,
-              message:
-                `[claim] Two remotes serve '${facade.name}': '${first}' and '${label}'.\n`
-                + `  A call names an entity, not a frond, so nothing could choose between them.\n`
-                + `  - Keep one of the two out of \`remotes:\`, or\n`
-                + `  - expose one of them under a different entity name.`,
-              entity: facade.name,
-            });
-          }
-          claimedBy.set(facade.name, label);
-          byEntity.set(facade.name, {
-            frond: frond.name,
-            transport,
-            ...(facade.schema ? { schema: Card.fromDescriptor(facade.schema as SchemaDescriptor).toSchema() } : {}),
-          });
-        }
-      }
+      pending.delete(answered.label);
+      claimFacades(answered, byEntity, claimedBy);
     }
   };
 
@@ -141,3 +114,48 @@ export function createRemoteFacade(
 
   return dynamicOperations(opFn) as Facade;
 }
+
+/** What one remote answered `discover` with, once it has been reached. */
+interface Answered {
+  label: string;
+  url: string;
+  transport: Transport;
+  answer: unknown;
+}
+
+/**
+ * Which remote serves which facade. Facades only: a fact is not routable — nobody calls it, it
+ * arrives — so adding one here would answer a call with a transport to a facade that does not
+ * exist. Two remotes claiming one name is refused, never silently arbitrated.
+ */
+function claimFacades(
+  { label, url, transport, answer }: Answered,
+  byEntity: Map<string, Route>,
+  claimedBy: Map<string, string>,
+): void {
+  const card = assertIdentityCard(answer, `Remote '${label}' (${url})`);
+
+  for (const frond of card.fronds) {
+    for (const facade of frond.facades) {
+      const first = claimedBy.get(facade.name);
+      if (first !== undefined && first !== label) {
+        throw new FougereError({
+          code: ErrorCode.INTERNAL_ERROR,
+          message:
+            `[claim] Two remotes serve '${facade.name}': '${first}' and '${label}'.\n`
+            + `  A call names an entity, not a frond, so nothing could choose between them.\n`
+            + `  - Keep one of the two out of \`remotes:\`, or\n`
+            + `  - expose one of them under a different entity name.`,
+          entity: facade.name,
+        });
+      }
+
+      claimedBy.set(facade.name, label);
+      byEntity.set(facade.name, {
+        frond: frond.name,
+        transport,
+        ...(facade.schema ? { schema: Card.fromDescriptor(facade.schema as SchemaDescriptor).toSchema() } : {}),
+      });
+    }
+  }
+}

package/src/boot/seed.ts

@@ -15,6 +15,33 @@ export interface SeedOrder {
 
 /** Seeds in dependency order — a `ref()` target is planted before its referrer. */
 export function orderSeeds(fronds: FrondDescriptor[]): SeedOrder {
+  const seeds = fronds.flatMap((frond) => frond.seeds);
+  const waiting = whatEachWaitsFor(fronds, seeds);
+
+  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, cycle: [...waiting.keys()] };
+}
+
+/**
+ * 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, and an entity naming itself waits for
+ * nobody.
+ */
+function whatEachWaitsFor(
+  fronds: FrondDescriptor[],
+  seeds: SeedEntry[],
+): Map<SeedEntry, Set<string>> {
   const refs = new Map<string, Set<string>>();
   for (const frond of fronds) {
     for (const entity of frond.entities) {
@@ -28,33 +55,13 @@ export function orderSeeds(fronds: FrondDescriptor[]): SeedOrder {
     }
   }
 
-  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 new Map(seeds.map((seed) => {
+    const own = seed.entityName.toLowerCase();
 
-      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, cycle: [...waiting.keys()] };
+    return [seed, new Set([...(refs.get(own) ?? [])].filter((target) => seeded.has(target) && target !== own))] as const;
+  }));
 }
 
 /** Where a seed writes, and what it may skip — resolved per entity. */
@@ -110,10 +117,12 @@ function facadeFor(app: App, entityName: string): SeedFacade | 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') {
+  const list = handler?.list;
+  const create = handler?.create;
+  if (typeof list === 'function' && typeof create === 'function') {
     return {
-      list: () => handler!.list() as Promise<unknown[]>,
-      write: (item) => handler!.create({ params: {}, query: {}, input: item, state: {} }),
+      list: () => list.call(handler) as Promise<unknown[]>,
+      write: (item) => create.call(handler, { params: {}, query: {}, input: item, state: {} }),
     };
   }