@loomcli/core 0.2.0 → 0.4.0

package/dist/extension.js

@@ -19,16 +19,15 @@ class ExtensionCarrier {
         Object.freeze(this);
     }
 }
-/**
- * One typed fact a plugin defines for one target. The descriptor is compared by reference wherever
- * it appears, so one identity means one descriptor and a duplicated package copy is visible.
- */
 function extension(identity, config) {
     // `Object.assign` returns the same function object, so the value carries the descriptor itself.
     function create(input) {
         return new ExtensionCarrier({ descriptor, input });
     }
+    // An omitted or undefined `collect` publishes as false, and any other value as given.
+    // Build then rejects a JavaScript author's value that is neither Boolean.
     const descriptor = Object.assign(create, {
+        collect: config.collect === undefined ? false : config.collect,
         identity,
         schema: config.schema,
         target: config.target,
@@ -36,26 +35,31 @@ function extension(identity, config) {
     Object.freeze(descriptor);
     return descriptor;
 }
+/** The read of a collecting extension a declaration carries no value of, shared and frozen. */
+const noValues = Object.freeze([]);
 /**
  * The typed read of one extension value. It takes the node kind the descriptor targets, returns the
  * stored output or `undefined`, compares the descriptor by reference with the one that produced the
- * value, and runs no schema.
+ * value, and runs no schema. Through a collecting descriptor it returns every collected output in
+ * collection order, and an empty list where the node carries none.
  */
 function readExtension(node, descriptor) {
     const record = node.extensions;
     const owner = owners.get(record)?.get(descriptor.identity);
-    if (owner === undefined) {
-        return undefined;
-    }
-    if (owner !== descriptor) {
+    if (owner !== undefined && owner !== descriptor) {
         throw new DeclarationError(`Extension "${descriptor.identity}" was read through a descriptor that did not define the stored value. Install one copy of the package that defines it.`);
     }
-    // Last resort: no typed path exists. The graph stores every output under a string identity, so
-    // The record reads back as `unknown` and no key relates one entry to a descriptor's schema.
-    // It holds because the reference test above proves this descriptor produced this output, and
-    // Build stored exactly what that descriptor's own schema returned.
+    // A collecting extension a declaration carries no value of reads as an empty list.
+    const absent = descriptor.collect ? noValues : undefined;
+    const stored = owner === undefined ? absent : record[descriptor.identity];
+    // Last resort: no typed path exists.
+    // The graph stores every output under a string identity, so the record reads back as `unknown`.
+    // No key relates one entry to a descriptor's schema or to its runtime `collect` flag.
+    // It holds because the reference test above proves this descriptor produced this entry.
+    // Build stored exactly what its schema returned, a list when the descriptor collects.
+    // `Collect` is the literal `extension()` published as `collect`, which registration enforces.
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-    return record[descriptor.identity];
+    return stored;
 }
 /** How a diagnostic names the declarations one target covers. */
 const applies = {
@@ -172,7 +176,10 @@ function plainData(value) {
         }
     }
 }
-/** Whether a value is a descriptor: a callable object carrying an identity and a declared target. */
+/**
+ * Whether a value has a descriptor's shape: a callable object carrying an identity and a declared
+ * target. Its `collect` flag is checked where a build registers it.
+ */
 function isDescriptor(value) {
     return (value !== null &&
         (typeof value === 'object' || typeof value === 'function') &&
@@ -181,16 +188,37 @@ function isDescriptor(value) {
         'target' in value &&
         (value.target === 'argument' || value.target === 'command' || value.target === 'option'));
 }
-/** One identity means one descriptor, wherever on the graph that descriptor appears. */
-function registerDescriptor(descriptors, descriptor) {
+/** Whether a descriptor carries the `collect` flag every descriptor publishes, as a Boolean. */
+function hasCollectFlag(descriptor) {
+    return 'collect' in descriptor && typeof descriptor.collect === 'boolean';
+}
+/** Whether one registered descriptor collects, so its values accumulate instead of replacing. */
+function collects(descriptor) {
+    return descriptor.collect;
+}
+/**
+ * The descriptor a registry holds for one identity once this one is admitted. One identity means
+ * one descriptor, wherever on the graph that descriptor appears, and a descriptor is checked when
+ * a build first meets it: its `collect` flag is `true` or `false`, which the factory always
+ * publishes and a hand-built descriptor may not. It reads the registry and changes nothing.
+ */
+function admitDescriptor(descriptors, descriptor) {
     const known = descriptors.get(descriptor.identity);
     if (known === undefined) {
-        descriptors.set(descriptor.identity, descriptor);
-        return;
+        if (!hasCollectFlag(descriptor)) {
+            throw new DeclarationError(`Extension "${descriptor.identity}" declares collect that is not a Boolean. Supply true or false, or build the descriptor with extension(identity, config).`);
+        }
+        return descriptor;
     }
     if (known !== descriptor) {
         throw new DeclarationError(`Extension "${descriptor.identity}" is defined twice. Install one copy of the package that defines it.`);
     }
+    return known;
+}
+/** Admits one descriptor and records it, so a later descriptor of its identity is compared to it. */
+function registerDescriptor(descriptors, descriptor) {
+    const admitted = admitDescriptor(descriptors, descriptor);
+    descriptors.set(admitted.identity, admitted);
 }
 /** Whether a value answers the Standard Schema v1 contract this build calls synchronously. */
 function isSchema(value) {
@@ -286,28 +314,85 @@ function carriedValue(subject, target, entry) {
     return carried;
 }
 /**
- * The frozen record one declaration publishes: each carried value validated once, synchronously,
- * and stored under its extension's identity. The descriptors that produced them are recorded beside
- * the record, so a typed read compares by reference without the graph carrying a reference.
+ * One layer's values, each validated once, synchronously, in authoring order. A layer holds at
+ * most one value of an extension, collecting or not, so a second one is a declaration fault.
  */
-function buildExtensions(slot) {
+function validateLayer(slot) {
     const { subject } = slot;
-    const stored = [];
-    const defined = new Map();
+    const layer = [];
+    const seen = new Set();
+    // The layer's descriptors register together once every value is valid.
+    // A rejected layer, such as a hook's `extend()` call the hook catches, leaves the registry as it was.
+    const staged = new Map(slot.descriptors);
     for (const entry of readList(subject, slot.declared)) {
         const carried = carriedValue(subject, slot.target, entry);
         const { descriptor } = carried;
-        registerDescriptor(slot.descriptors, descriptor);
-        if (defined.has(descriptor.identity)) {
+        registerDescriptor(staged, descriptor);
+        if (seen.has(descriptor.identity)) {
             throw new DeclarationError(`${subject.sentence} holds extension "${descriptor.identity}" twice. Supply one value.`);
         }
-        defined.set(descriptor.identity, descriptor);
-        stored.push([descriptor.identity, validateValue(subject, carried)]);
+        seen.add(descriptor.identity);
+        layer.push({ descriptor, output: validateValue(subject, carried) });
+    }
+    for (const [identity, descriptor] of staged) {
+        slot.descriptors.set(identity, descriptor);
+    }
+    return layer;
+}
+/**
+ * The record each store published, so a store a hook left unchanged publishes the same record on
+ * every read and build does no second walk of it.
+ */
+const published = new WeakMap();
+/** The store of a declaration that carries no value yet. */
+const emptyStore = { entries: new Map() };
+/**
+ * The store with one more validated layer. An ordinary value replaces the earlier one in place, so
+ * a key keeps its first position, and a collecting value joins the values before it.
+ */
+function extendStore(store, layer) {
+    const entries = new Map(store.entries);
+    for (const { descriptor, output } of layer) {
+        const earlier = entries.get(descriptor.identity)?.outputs ?? [];
+        const outputs = collects(descriptor) ? [...earlier, output] : [output];
+        entries.set(descriptor.identity, { descriptor, outputs });
+    }
+    return { entries };
+}
+/**
+ * The frozen record a store publishes: each ordinary extension's output, and each collecting
+ * extension's frozen list of outputs, under its identity. The descriptors that produced them are
+ * recorded beside the record, so a typed read compares by reference without the graph carrying a
+ * reference.
+ */
+function publishStore(store) {
+    const cached = published.get(store);
+    if (cached) {
+        return cached;
+    }
+    const stored = [];
+    const defined = new Map();
+    for (const [identity, { descriptor, outputs }] of store.entries) {
+        stored.push([identity, collects(descriptor) ? Object.freeze([...outputs]) : outputs[0]]);
+        defined.set(identity, descriptor);
     }
     // `Object.fromEntries` defines each identity as an own data property, so an identity of
     // `__proto__` is a key of the record and the record keeps `Object.prototype`.
     const frozen = Object.freeze(Object.fromEntries(stored));
     owners.set(frozen, defined);
+    published.set(store, frozen);
     return frozen;
 }
-export { buildExtensions, extension, isDescriptor, readExtension, registerDescriptor };
+/** The frozen record of one `extensions` slot, which is one layer. */
+function buildExtensions(slot) {
+    return publishStore(extendStore(emptyStore, validateLayer(slot)));
+}
+/** A Command's author layers, validated in authoring order into the store its hooks extend. */
+function storeCommandLayers(slot) {
+    let store = emptyStore;
+    for (const declared of slot.layers) {
+        store = extendStore(store, validateLayer({ ...slot, declared, target: 'command' }));
+    }
+    return store;
+}
+export { buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/globals.d.ts

@@ -1,10 +1,8 @@
 import { DeclarationError } from './errors.js';
 import { compileOptions } from './options.js';
 import type { BuiltPlugin, PluginBuild } from './plugin.js';
-import type { DefaultConstraint, MultipleConstraint, NameConstraint, OptionConfig, OptionValue, ValidateOmittedConstraint } from './types.js';
+import type { OptionConfig, OptionValue } from './types.js';
 import type { InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
-/** Phantom key. It keeps the declared option types exact and holds no runtime value. */
-declare const declaredTypes: unique symbol;
 /**
  * Who declared one option that shares the globals table, or the Command that declares a local
  * option colliding with it. Every collision sentence is derived from a pair of these, so the
@@ -36,33 +34,24 @@ declare function spellingCollision(spelling: string, first: OptionSite, second:
  * validated and never reaches an action.
  */
 interface BuiltGlobals {
+    bind: (values: ValidatedInputs) => unknown;
     inputs: readonly InputDeclaration[];
     names: ReadonlyMap<string, OptionOwner>;
     options: ReturnType<typeof compileOptions>;
     plugins: readonly BuiltPlugin[];
-    source: unknown;
 }
-declare class GlobalOptionsBuilder<Options> {
-    #private;
-    readonly [declaredTypes]: Options;
-    constructor(inputs: readonly OptionInput[], bind: (values: ValidatedInputs) => Options);
-    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): GlobalOptions<Options & Record<Name, OptionValue<Config>>>;
+/** The Application's private global declarations and their schema-derived value binder. */
+interface GlobalsState<Globals = unknown> {
+    bind: (values: ValidatedInputs) => Globals;
+    inputs: readonly OptionInput[];
 }
+declare function emptyGlobals(): GlobalsState<{}>;
+declare function declareGlobalOption<Globals, Name extends string, Config extends OptionConfig>(state: GlobalsState<Globals>, input: OptionInput<Name, Config>): GlobalsState<Globals & Record<Name, OptionValue<Config>>>;
 /**
- * Application-wide options. `option()` is the whole authoring surface: it returns a new value and
- * leaves its receiver unchanged. The value the declarations share is the application's globals.
- * The declarations themselves stay private, so no consumer can read or replace them.
+ * The one table the pre-scan reads: the application's global options in authoring order, then each
+ * installed plugin's options in installation order. Every collision between the two scopes, by key
+ * or by spelling, is reported here, so the pre-scan meets a table with one owner per name.
  */
-type GlobalOptions<Options = {}> = Pick<GlobalOptionsBuilder<Options>, typeof declaredTypes | 'option'>;
-/**
- * Whether a value is an authored GlobalOptions declaration, whichever call produced it. The
- * registry is the test, because `option()` returns a new declaration of its own and the exported
- * constructor is only the first of them.
- */
-declare function isGlobalOptions(value: unknown): boolean;
-/** Absent globals compile to an empty table whose source is `undefined`, like the declarations. */
-declare function buildGlobals(globals: object | undefined, plugins: readonly BuiltPlugin[], build: PluginBuild): BuiltGlobals;
-declare function bindGlobals<Options>(globals: GlobalOptions<Options> | undefined, values: ValidatedInputs): Options;
-declare const GlobalOptions: new () => GlobalOptions;
-export type { BuiltGlobals, OptionOwner, OptionSite };
-export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions, keyCollision, spellingCollision, };
+declare function buildGlobals(node: GlobalsState, plugins: readonly BuiltPlugin[], build: PluginBuild): BuiltGlobals;
+export type { BuiltGlobals, GlobalsState, OptionOwner, OptionSite };
+export { buildGlobals, declareGlobalOption, emptyGlobals, keyCollision, spellingCollision };

package/dist/globals.js

@@ -2,7 +2,6 @@ import { DeclarationError } from './errors.js';
 import { buildExtensions } from './extension.js';
 import { checkDeprecated, checkDescription, checkHidden } from './facts.js';
 import { compileOptions } from './options.js';
-import { captureConfig } from './validation.js';
 const globalSubject = 'the global options';
 /** A collision sentence names a plugin first, then the application's globals, then a local. */
 const ranks = {
@@ -57,51 +56,21 @@ function spellingCollision(spelling, first, second) {
     const [leading, trailing] = ordered(first, second);
     return new DeclarationError(`Option spelling "${spelling}" is used by ${usedBy(leading)} and ${usedBy(trailing)}. Change one declaration.`);
 }
-/** Authored values register here, so the public type publishes no state to reach or replace. */
-const nodes = new WeakMap();
-class GlobalOptionsBuilder {
-    #bind;
-    #inputs;
-    constructor(inputs, bind) {
-        this.#bind = bind;
-        this.#inputs = inputs;
-        nodes.set(this, { bind, inputs, source: this });
-    }
-    option(name, config) {
-        const input = {
-            config: captureConfig(config),
-            kind: 'option',
-            name,
-        };
-        const previous = this.#bind;
-        return new GlobalOptionsBuilder([...this.#inputs, input], (values) => ({
-            ...previous(values),
-            ...values.option(input),
-        }));
-    }
+function emptyGlobals() {
+    return { bind: () => ({}), inputs: [] };
 }
-/** Reads the declarations behind an authored value; anything else is a declaration error. */
-function nodeOf(globals) {
-    const node = nodes.get(globals);
-    if (!node) {
-        throw new DeclarationError('The Application holds a value that is not a GlobalOptions declaration. Supply the value returned by new GlobalOptions().');
-    }
-    return node;
-}
-/**
- * Whether a value is an authored GlobalOptions declaration, whichever call produced it. The
- * registry is the test, because `option()` returns a new declaration of its own and the exported
- * constructor is only the first of them.
- */
-function isGlobalOptions(value) {
-    return typeof value === 'object' && value !== null && nodes.has(value);
+function declareGlobalOption(state, input) {
+    return {
+        bind: (values) => ({ ...state.bind(values), ...values.option(input) }),
+        inputs: [...state.inputs, input],
+    };
 }
 /**
  * The one table the pre-scan reads: the application's global options in authoring order, then each
  * installed plugin's options in installation order. Every collision between the two scopes, by key
  * or by spelling, is reported here, so the pre-scan meets a table with one owner per name.
  */
-function compileTable(node, plugins, build) {
+function buildGlobals(node, plugins, build) {
     const names = new Map();
     const application = { kind: 'application' };
     // A global option belongs to the application, not to one Command, so its facts read that way.
@@ -125,7 +94,7 @@ function compileTable(node, plugins, build) {
             options,
         });
     });
-    return { inputs: node.inputs, names, options, plugins, source: node.source };
+    return { bind: node.bind, inputs: node.inputs, names, options, plugins };
 }
 /** One plugin's options joining the table the application's globals already hold. */
 function join(owner, inputs, table) {
@@ -145,24 +114,4 @@ function join(owner, inputs, table) {
         options.set(spelling, option);
     }
 }
-/** Absent globals compile to an empty table whose source is `undefined`, like the declarations. */
-function buildGlobals(globals, plugins, build) {
-    const node = globals === undefined ? { bind: () => ({}), inputs: [], source: undefined } : nodeOf(globals);
-    return compileTable(node, plugins, build);
-}
-function bindGlobals(globals, values) {
-    const bound = globals === undefined ? {} : nodeOf(globals).bind(values);
-    // Last resort: no typed path exists. The public GlobalOptions type hides its declarations.
-    // The registry is the only bridge from a value to its binder, and a WeakMap cannot carry the
-    // Options type of its key. It holds because the registered binder belongs to this value alone.
-    // Its record composes exactly the declarations that its Options type records.
-    // A declaration without globals publishes `Options = {}`, and the empty record is exactly that.
-    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-    return bound;
-}
-const GlobalOptions = class extends GlobalOptionsBuilder {
-    constructor() {
-        super([], () => ({}));
-    }
-};
-export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions, keyCollision, spellingCollision, };
+export { buildGlobals, declareGlobalOption, emptyGlobals, keyCollision, spellingCollision };