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

package/src/FrondsStated.ts

@@ -0,0 +1,72 @@
+import type { NameOf } from './NameOf.js';
+
+/**
+ * What the config says about the fronds this app is made of — where each one comes from, and
+ * which one it inherits code from.
+ *
+ * `fronds:` on an entry says ONE thing: those fronds resolve what this one declared. It says
+ * nothing about placement, and nothing about the right to call — two fronds reach each other
+ * through a façade or an announced fact, whatever their place here.
+ *
+ * The key SUGGESTS what the scan found and refuses nothing: `NameOf<'frond'>` alone would
+ * close the record, and a module specifier is a legal key no scan can have seen. `string & {}`
+ * is what keeps the union open while an editor still lists the names.
+ *
+ * Documented: [fronds](https://fougere.dev/docs/infra/fronds).
+ */
+export type FrondsStated = {
+  readonly [frond in NameOf<'frond'> | (string & {})]?: FrondStated;
+};
+
+/**
+ * Everything an entry says, or the one string that is the whole of it — an address for a frond
+ * that answers elsewhere, the argument for a module key.
+ */
+export type FrondStated = string | FrondAttributes;
+
+export interface FrondAttributes {
+  /**
+   * The frond this one inherits code from — its scope hangs off that one's.
+   *
+   * Said by the INHERITOR, and scalar: a name then lives in one place, so moving a frond from
+   * one family to another is one edit and removing it leaves nothing dangling. It is the form
+   * `tsconfig`, Maven and Kubernetes all chose for inheritance, and the one that makes
+   * "one parent" a fact of the shape rather than a refusal at boot.
+   *
+   * ONE level: the frond it names may not inherit itself (`frond-extends-chain`). Nothing in
+   * this repo has ever wanted a chain, and refusing it is also what keeps a cycle out.
+   */
+  extends?: NameOf<'frond'> | (string & {});
+  /** Where it answers — the same thing the shorthand says. */
+  remote?: string;
+  /** What the host hands a module key when it imports it. */
+  options?: string;
+}
+
+/**
+ * A key that names a module rather than a frond. A frond's name is a directory name or the
+ * `fougere.frond` field of a package, and neither can hold a separator — so the two never
+ * collide, and no allow-list of short names has to be kept anywhere.
+ */
+export function statesModule(key: string): boolean {
+  return key.includes('/') || key.startsWith('.');
+}
+
+/**
+ * Two levels of the cascade, folded. An entry merges by attribute, so an app naming a frond's
+ * address keeps the `extends` the workspace gave it — and an app naming a different `extends`
+ * replaces it, silently, the way every scalar key of this config replaces.
+ */
+export function mergeStated(base: FrondsStated, override: FrondsStated): FrondsStated {
+  const merged: Record<string, FrondStated> = { ...base } as Record<string, FrondStated>;
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+
+    const mine = merged[key];
+    merged[key] = typeof value === 'string' || typeof mine === 'string' || mine === undefined
+      ? value
+      : { ...mine, ...value };
+  }
+
+  return merged;
+}

package/src/StatedFrond.ts

@@ -0,0 +1,51 @@
+import { statesModule, type FrondAttributes, type FrondStated, type FrondsStated } from './FrondsStated.js';
+
+/** One entry of the config, read whole. */
+export interface StatedFrond {
+  /** The key as written — a frond name, or a module specifier. */
+  key: string;
+  /** The frond it inherits code from, absent when it names none. */
+  extends?: string;
+  /** The entry that named it, for a refusal that says where to look. */
+  path: string;
+  /** An address for a frond that is elsewhere, an argument for a module. */
+  value?: string;
+}
+
+/** What an entry says, whichever of its two forms it was written in. */
+function attributesOf(stated: FrondStated, key: string): FrondAttributes {
+  if (typeof stated !== 'string') return stated;
+
+  return statesModule(key) ? { options: stated } : { remote: stated };
+}
+
+/**
+ * Every frond the config states, those inheriting from nothing first — which is also the order
+ * a boot installs them in, since a scope hangs off the one above it.
+ *
+ * A partition and not a sort: with one level, a frond that inherits has nothing under it, so
+ * two passes put every parent before every child without knowing the tree.
+ */
+export function statedFronds(stated: FrondsStated | undefined): StatedFrond[] {
+  const entries = Object.entries(stated ?? {}) as [string, FrondStated | undefined][];
+
+  const read = ([key, value]: [string, FrondStated | undefined]): StatedFrond | undefined => {
+    if (value === undefined) return undefined;
+
+    const attributes = attributesOf(value, key);
+    const above = attributes.extends;
+    const carries = statesModule(key) ? attributes.options : attributes.remote;
+
+    return {
+      key,
+      path: above !== undefined ? `${above}.${key}` : key,
+      ...(above !== undefined ? { extends: above } : {}),
+      ...(carries !== undefined ? { value: carries } : {}),
+    };
+  };
+
+  const stands = (one: StatedFrond | undefined): one is StatedFrond => one !== undefined;
+  const all = entries.map(read).filter(stands);
+
+  return [...all.filter((one) => one.extends === undefined), ...all.filter((one) => one.extends !== undefined)];
+}

package/src/StatedModules.ts

@@ -0,0 +1,58 @@
+/**
+ * The fronds a config names by MODULE rather than by directory — `@fougere/log`, or a package
+ * of your own. Reading one means importing it, which is why this lives on the node entry and
+ * never on the one a Worker runs.
+ *
+ * What a module hands back decides where it goes: a shape stating `up` or `down` is an
+ * extension and rises with the app, anything else is a frond and is installed like the rest.
+ * The author of a config does not have to know which one their package exports — the same
+ * reading `extensions/` already does off a module's form.
+ */
+import type { Extension } from './boot/Extension.js';
+import type { FrondDescriptor } from './descriptor/FrondDescriptor.js';
+import { statesModule, type FrondsStated } from './FrondsStated.js';
+import { statedFronds } from './StatedFrond.js';
+import { getModuleLoader } from './loader.js';
+
+/** The export a specifier reaches: its last segment, `default` failing that. */
+function exportedBy(specifier: string): string {
+  const last = specifier.split('/').at(-1) ?? specifier;
+
+  return last.replace(/\.[cm]?[jt]s$/, '');
+}
+
+function rises(built: unknown): built is Extension {
+  const shape = built as { up?: unknown; down?: unknown } | null;
+
+  return typeof shape?.up === 'function' || typeof shape?.down === 'function';
+}
+
+/** What a config's module keys hand over, sorted by what each one turned out to be. */
+export async function statedModules(
+  stated: FrondsStated | undefined,
+): Promise<{ fronds: FrondDescriptor[]; extensions: Extension[] }> {
+  const fronds: FrondDescriptor[] = [];
+  const extensions: Extension[] = [];
+  const loader = getModuleLoader();
+
+  for (const entry of statedFronds(stated)) {
+    if (!statesModule(entry.key)) continue;
+
+    const module = await loader(entry.key) as Record<string, unknown>;
+    const name = exportedBy(entry.key);
+    const factory = module[name] ?? module.default;
+    if (typeof factory !== 'function') {
+      throw new Error(
+        `Fougere config: '${entry.key}' exports no '${name}'. A module a config names hands its `
+        + `frond back from the export its last segment spells — \`export const ${name} = …\` — or `
+        + 'from its default.',
+      );
+    }
+
+    const built = (factory as (argument?: unknown) => unknown)(entry.value);
+    if (rises(built)) extensions.push(built);
+    else fronds.push(built as FrondDescriptor);
+  }
+
+  return { fronds, extensions };
+}

package/src/boot/CreateAppOptions.ts

@@ -1,5 +1,6 @@
 import type { Container } from '@fougere/container';
 import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+import type { FrondsStated } from '../FrondsStated.js';
 import type { ScanResult } from '../scan.js';
 import type { StorageFactory } from '../storage/StorageFactory.js';
 import type { Constraint } from '../Constraint.js';
@@ -11,8 +12,13 @@ import type { App } from './App.js';
 
 /** Options for createApp(). */
 export interface CreateAppOptions {
-  /** Factory function to create the container. Required. */
-  createContainer: () => Container;
+  /**
+   * The container this app resolves through. Absent, core builds its own — the only
+   * realization there is. A host states one to fill the root BEFORE the boot runs: the CLI
+   * registers its terminal that way, and a seed resolving a handler during the ascent would
+   * never see a value registered after `createApp` returned.
+   */
+  createContainer?: () => Container;
   /** Factory to auto-generate Storage for each scanned entity. */
   storageFactory?: StorageFactory;
   /**
@@ -41,6 +47,17 @@ export interface CreateAppOptions {
   scan?: ScanResult | (() => Promise<ScanResult> | ScanResult);
   /** What this app STATES it hosts — `frond('blog', { entities: [Post] })`. */
   fronds?: readonly FrondDescriptor[];
+  /**
+   * Who inherits code from whom — `FougereConfig.fronds`, handed over whole rather than
+   * flattened, because a refusal names where an entry sits in it (`shop.cart`). The host has
+   * already turned its addresses and its modules into `remotes` and `fronds`.
+   */
+  under?: FrondsStated;
+  /**
+   * This process carries a subset of what the project declares — `only:` at the host. A name
+   * the tree states and this process left out is then expected, not a typo.
+   */
+  narrowed?: boolean;
   /**
    * Remote fronds — label → address. What each remote hosts is discovered
    * at the first miss (rpc.discover), never declared here.

package/src/boot/Emissions.ts

@@ -223,17 +223,30 @@ export class Emissions {
       return [];
     }
 
+    return this.answersOf(fact, handed);
+  }
+
+  /**
+   * A subscriber that did not answer REFUSES the announcement, it does not shrink it: an
+   * announcer handed the survivors cannot tell three answers from two, and its own law then
+   * reads silence as consent — the room one would have refused gets booked.
+   *
+   * What answers NOTHING contributes nothing: a subscriber is free to have no opinion, and
+   * `Promise<void>` is how it says so.
+   */
+  private async answersOf(
+    fact: string,
+    handed: (Listener & { done: Promise<unknown> })[],
+  ): Promise<unknown[]> {
     const settled = await Promise.allSettled(handed.map((one) => one.done));
 
-    // A subscriber that did not answer REFUSES the announcement, it does not shrink it: an
-    // announcer handed the survivors cannot tell three answers from two, and its own law
-    // then reads silence as consent — the room one would have refused gets booked.
     const missing = settled.flatMap((result, at) =>
       (result.status === 'rejected' ? [{ ...handed[at]!, reason: result.reason as unknown }] : []));
     if (missing.length > 0) {
       for (const { facade, op, reason } of missing) {
         this.log.error(`${fact} → ${facade}.${op}`, this.describeRefusal(fact, reason) ?? reason);
       }
+
       throw new AggregateError(
         missing.map((one) => one.reason),
         `${fact} — ${missing.length} of ${handed.length} subscriber(s) did not answer`
@@ -243,8 +256,6 @@ export class Emissions {
       );
     }
 
-    // What answers NOTHING contributes nothing — a subscriber is free to have no opinion,
-    // and `Promise<void>` is how it says so.
     return settled.flatMap((result) =>
       (result.status === 'fulfilled' && result.value != null ? [result.value] : []));
   }