@loomcli/core 0.1.1 → 0.3.0

package/dist/extension.js

@@ -0,0 +1,330 @@
+import { DeclarationError, reasonOf } from './errors.js';
+import { isPlainObject } from './facts.js';
+/** Authored values register here, so the public brand publishes no state to reach or replace. */
+const values = new WeakMap();
+/**
+ * The descriptor that produced each stored output, keyed by the frozen record a node publishes. It
+ * lives beside the graph rather than on it, so a projection reads plain data while a typed read
+ * still compares descriptors by reference.
+ */
+const owners = new WeakMap();
+/**
+ * The value one extension produces, branded with its target so a value on the wrong declaration is
+ * a compile error. It publishes the brand alone, so a value is never mistaken for the descriptor
+ * that produced it, and the input it carries stays private to this package.
+ */
+class ExtensionCarrier {
+    constructor(record) {
+        values.set(this, record);
+        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 });
+    }
+    const descriptor = Object.assign(create, {
+        identity,
+        schema: config.schema,
+        target: config.target,
+    });
+    Object.freeze(descriptor);
+    return descriptor;
+}
+/**
+ * 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.
+ */
+function readExtension(node, descriptor) {
+    const record = node.extensions;
+    const owner = owners.get(record)?.get(descriptor.identity);
+    if (owner === undefined) {
+        return undefined;
+    }
+    if (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.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return record[descriptor.identity];
+}
+/** How a diagnostic names the declarations one target covers. */
+const applies = {
+    argument: 'arguments',
+    command: 'Commands',
+    option: 'options',
+};
+/**
+ * The children one container contributes, or nothing when its own shape is not plain data. An
+ * accessor, a symbol key, and a non-enumerable own property are not plain data, and an `undefined`
+ * property value is absence, so it is dropped rather than stored. An array contributes its items,
+ * the way it reads back.
+ */
+function childrenOf(source) {
+    if (Array.isArray(source)) {
+        // `Array.from` reads a hole as the `undefined` it is, which the walk rejects like any other
+        // Value that is not plain data.
+        return Array.from(source, (value, index) => ({ key: String(index), value }));
+    }
+    if (!isPlainObject(source) || Object.getOwnPropertySymbols(source).length > 0) {
+        return undefined;
+    }
+    const children = [];
+    for (const key of Object.getOwnPropertyNames(source)) {
+        const property = Object.getOwnPropertyDescriptor(source, key);
+        if (!property || !('value' in property) || !property.enumerable) {
+            return undefined;
+        }
+        if (property.value !== undefined) {
+            children.push({ key, value: property.value });
+        }
+    }
+    return children;
+}
+/**
+ * One value the walk reached. A primitive is copied where it is read, and a container answers with
+ * the frame the walk fills. `ancestors` holds the containers on the path to this value, so a value
+ * that is one of them is a cycle.
+ */
+function openValue(value, key, ancestors) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return { data: value, kind: 'leaf' };
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? { data: value, kind: 'leaf' } : undefined;
+    }
+    if (typeof value !== 'object' || ancestors.has(value)) {
+        return undefined;
+    }
+    const children = childrenOf(value);
+    if (!children) {
+        return undefined;
+    }
+    const isArray = Array.isArray(value);
+    return { frame: { children, entries: [], index: 0, isArray, key, source: value }, kind: 'frame' };
+}
+/**
+ * The frozen copy one finished container contributes. `Object.fromEntries` defines every key as an
+ * own data property, so an output key of `__proto__` is stored under that name and the copy keeps
+ * `Object.prototype`.
+ */
+function closeFrame(frame) {
+    return Object.freeze(frame.isArray ? frame.entries.map(([, value]) => value) : Object.fromEntries(frame.entries));
+}
+/**
+ * Whether a produced output is the plain data a node can freeze and every projection can read:
+ * strings, finite numbers, Booleans, null, arrays, and objects whose prototype is `Object.prototype`
+ * or null, to any depth and without cycles. It answers with the frozen copy, because the walk that
+ * proves the shape is the walk that builds it. The walk holds its own stack, so a deep output is
+ * bounded by the heap and never by the call stack. A declared default's snapshot answers a different
+ * question: it keeps a library object as it is, where an extension output holding one is rejected.
+ */
+function plainData(value) {
+    const ancestors = new Set();
+    const opened = openValue(value, '', ancestors);
+    if (!opened) {
+        return undefined;
+    }
+    if (opened.kind === 'leaf') {
+        return { data: opened.data };
+    }
+    const stack = [opened.frame];
+    ancestors.add(opened.frame.source);
+    for (;;) {
+        const frame = stack.at(-1);
+        if (!frame) {
+            return undefined;
+        }
+        const child = frame.children[frame.index];
+        if (child) {
+            const next = openValue(child.value, child.key, ancestors);
+            if (!next) {
+                return undefined;
+            }
+            if (next.kind === 'leaf') {
+                frame.entries.push([child.key, next.data]);
+                frame.index += 1;
+            }
+            else {
+                stack.push(next.frame);
+                ancestors.add(next.frame.source);
+            }
+        }
+        else {
+            stack.pop();
+            ancestors.delete(frame.source);
+            const data = closeFrame(frame);
+            const parent = stack.at(-1);
+            if (!parent) {
+                return { data };
+            }
+            parent.entries.push([frame.key, data]);
+            parent.index += 1;
+        }
+    }
+}
+/** Whether a value is a descriptor: a callable object carrying an identity and a declared target. */
+function isDescriptor(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        'identity' in value &&
+        typeof value.identity === 'string' &&
+        '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) {
+    const known = descriptors.get(descriptor.identity);
+    if (known === undefined) {
+        descriptors.set(descriptor.identity, descriptor);
+        return;
+    }
+    if (known !== descriptor) {
+        throw new DeclarationError(`Extension "${descriptor.identity}" is defined twice. Install one copy of the package that defines it.`);
+    }
+}
+/** Whether a value answers the Standard Schema v1 contract this build calls synchronously. */
+function isSchema(value) {
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
+        return false;
+    }
+    const standard = '~standard' in value ? value['~standard'] : undefined;
+    return (standard !== null &&
+        typeof standard === 'object' &&
+        'validate' in standard &&
+        typeof standard.validate === 'function');
+}
+/**
+ * One schema message as a sentence of its own. A schema author writes the message with or without a
+ * full stop, so the diagnostic supplies one only where the message carries none.
+ */
+function sentence(text) {
+    return text.endsWith('.') ? text : `${text}.`;
+}
+/** The message one rejected value reports, with the placeholder a silent schema earns. */
+function issueText(issues) {
+    const first = Array.isArray(issues) ? issues[0] : undefined;
+    if (first !== null && typeof first === 'object' && 'message' in first) {
+        const { message } = first;
+        if (typeof message === 'string') {
+            return message;
+        }
+    }
+    // The sentence the caller composes ends the diagnostic, so this text carries no full stop.
+    return 'The schema rejected this value without an explanation';
+}
+/**
+ * Whether one schema answered with a promise. A thenable object and a promise from another realm
+ * are as unwaitable here as a native one, so the test is the contract and not the class.
+ */
+function isThenable(value) {
+    return 'then' in value && typeof value.then === 'function';
+}
+/** The schema one descriptor answers with, which a JavaScript author can leave out. */
+function schemaOf(subject, descriptor) {
+    const schema = 'schema' in descriptor ? descriptor.schema : undefined;
+    if (!isSchema(schema)) {
+        throw new DeclarationError(`${subject.sentence} holds extension "${descriptor.identity}", which declares no schema. Supply a Standard Schema v1 object that answers synchronously.`);
+    }
+    return schema;
+}
+/** The result one schema answered with, or the rejection its own throw is. */
+function validated(subject, carried, schema) {
+    try {
+        return schema['~standard'].validate(carried.input);
+    }
+    catch (error) {
+        // A schema that throws rejected the value the only way it could, so it reads as a rejection.
+        throw new DeclarationError(`${subject.sentence} holds an invalid "${carried.descriptor.identity}" value: ${sentence(reasonOf(error))} Correct the value.`);
+    }
+}
+/** Validates one carried value and answers the plain-data output the node stores under it. */
+function validateValue(subject, carried) {
+    const { identity } = carried.descriptor;
+    const result = validated(subject, carried, schemaOf(subject, carried.descriptor));
+    if (result === null || typeof result !== 'object' || isThenable(result)) {
+        throw new DeclarationError(`Extension "${identity}" validates asynchronously. Supply a schema that answers synchronously.`);
+    }
+    const issues = 'issues' in result ? result.issues : undefined;
+    if (issues !== undefined) {
+        throw new DeclarationError(`${subject.sentence} holds an invalid "${identity}" value: ${sentence(issueText(issues))} Correct the value.`);
+    }
+    const output = plainData('value' in result ? result.value : undefined);
+    if (!output) {
+        throw new DeclarationError(`Extension "${identity}" produced a value that is not plain data ${subject.phrase}. Return strings, numbers, booleans, null, arrays, and plain objects.`);
+    }
+    return output.data;
+}
+/** An `extensions` slot holds a list of values, so anything else is the same declaration fault. */
+function readList(subject, declared) {
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        throw new DeclarationError(`${subject.sentence} holds a value that is not an extension value. Supply the value returned by calling an extension.`);
+    }
+    return declared;
+}
+/** The value one entry carries, under the rules its own slot's target sets. */
+function carriedValue(subject, target, entry) {
+    const carried = typeof entry === 'object' && entry !== null ? values.get(entry) : undefined;
+    if (!carried) {
+        throw new DeclarationError(`${subject.sentence} holds a value that is not an extension value. Supply the value returned by calling an extension.`);
+    }
+    if (carried.descriptor.target !== target) {
+        throw new DeclarationError(`${subject.sentence} holds extension "${carried.descriptor.identity}", which applies to ${applies[carried.descriptor.target]}. Supply an extension that applies to ${applies[target]}.`);
+    }
+    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.
+ */
+function buildExtensions(slot) {
+    const { subject } = slot;
+    const stored = [];
+    const defined = new Map();
+    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)) {
+            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)]);
+    }
+    // `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);
+    return frozen;
+}
+/** Layers validate in authoring order; replacement updates existing keys without reinsertion. */
+function buildCommandExtensions(slot) {
+    const stored = new Map();
+    const defined = new Map();
+    for (const declared of slot.layers) {
+        const layer = buildExtensions({ ...slot, declared, target: 'command' });
+        for (const [identity, value] of Object.entries(layer)) {
+            stored.set(identity, value);
+        }
+        for (const [identity, descriptor] of owners.get(layer) ?? []) {
+            defined.set(identity, descriptor);
+        }
+    }
+    const frozen = Object.freeze(Object.fromEntries(stored));
+    owners.set(frozen, defined);
+    return frozen;
+}
+export { buildCommandExtensions, buildExtensions, extension, isDescriptor, readExtension, registerDescriptor, };

package/dist/facts.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The `description` core fact: one line of prose every projection reads. A value that is not a
+ * string fails the same way a blank one does, because the author reads one rule for one fact.
+ * An omitted description is absent, not a fault, so it passes through as `undefined`.
+ */
+export declare function checkDescription(subject: string, value: unknown): string | undefined;
+/**
+ * The `hidden` core fact: whether a listing omits this member. It is a Boolean, because a listing
+ * asks one question of it, and an omitted declaration reads `false`. Routing selects and parsing
+ * binds without reading it, so a hidden member behaves as any other.
+ */
+export declare function checkHidden(subject: string, value: unknown): boolean;
+/**
+ * The `deprecated` core fact: the one-line migration message a listing shows beside the member.
+ * It answers the rule a description answers, because both are one line of prose a projection
+ * prints. A bare `true` is rejected with every other value that is not prose: a deprecation with
+ * no migration path leaves an operator or an agent with nothing to do.
+ */
+export declare function checkDeprecated(subject: string, value: unknown): string | undefined;
+/**
+ * The declarations that carry neither listing fact: an argument, which cannot leave the grammar it
+ * sits in, and the root, which is every page's entry point. The types remove both keys there, and
+ * a JavaScript author, or a TypeScript author whose argument config is inferred from a value,
+ * reaches this rule instead.
+ */
+export declare function checkNoListingFacts(subject: string, declared: object): void;
+/**
+ * The `version` core fact, which the Application alone carries. Core reads it as an opaque string,
+ * because the convention is the package manifest's own field and no scheme is imposed on it. An
+ * omitted version is `0.0.0`, which means unversioned, and core keeps no record of which one the
+ * author wrote.
+ */
+export declare function checkVersion(value: unknown): string;
+/**
+ * A structural value core reads as plain data: an object literal, and never a declaration that
+ * carries state of its own. The options slots read it to reject a value that is not an options
+ * object, and inspection reads it to copy a declared value faithfully.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/facts.js

@@ -0,0 +1,95 @@
+import { DeclarationError } from './errors.js';
+/**
+ * One character outside Unicode `White_Space`, so a fact holds prose and not only spacing.
+ * The class covers the tab, the space, the line terminators, the no-break space, and every other
+ * space separator. A format character such as the zero-width space is outside it, so it is prose.
+ */
+const prose = /\P{White_Space}/u;
+/**
+ * Every character that ends a line, so a fact a projection prints on one line holds none.
+ * The seven are LF, VT, FF, CR, NEL, LS, and PS, each of them `White_Space` too.
+ */
+const lineTerminator = /[\n\v\f\r\u0085\u2028\u2029]/u;
+/**
+ * The `description` core fact: one line of prose every projection reads. A value that is not a
+ * string fails the same way a blank one does, because the author reads one rule for one fact.
+ * An omitted description is absent, not a fault, so it passes through as `undefined`.
+ */
+export function checkDescription(subject, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+        throw new DeclarationError(`${subject} description must hold a character other than whitespace and no line terminator. Supply a one-line summary.`);
+    }
+    return value;
+}
+/**
+ * The `hidden` core fact: whether a listing omits this member. It is a Boolean, because a listing
+ * asks one question of it, and an omitted declaration reads `false`. Routing selects and parsing
+ * binds without reading it, so a hidden member behaves as any other.
+ */
+export function checkHidden(subject, value) {
+    if (value === undefined) {
+        return false;
+    }
+    if (typeof value !== 'boolean') {
+        throw new DeclarationError(`${subject} hidden must be a Boolean. Supply true or false, or omit it.`);
+    }
+    return value;
+}
+/**
+ * The `deprecated` core fact: the one-line migration message a listing shows beside the member.
+ * It answers the rule a description answers, because both are one line of prose a projection
+ * prints. A bare `true` is rejected with every other value that is not prose: a deprecation with
+ * no migration path leaves an operator or an agent with nothing to do.
+ */
+export function checkDeprecated(subject, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+        throw new DeclarationError(`${subject} deprecated message must hold a character other than whitespace and no line terminator. Supply a one-line migration path, such as "Use get instead.".`);
+    }
+    return value;
+}
+/**
+ * The declarations that carry neither listing fact: an argument, which cannot leave the grammar it
+ * sits in, and the root, which is every page's entry point. The types remove both keys there, and
+ * a JavaScript author, or a TypeScript author whose argument config is inferred from a value,
+ * reaches this rule instead.
+ */
+export function checkNoListingFacts(subject, declared) {
+    for (const fact of ['hidden', 'deprecated']) {
+        if (fact in declared) {
+            throw new DeclarationError(`${subject} declares ${fact}, which applies to named Commands and options alone. Remove it.`);
+        }
+    }
+}
+/**
+ * The `version` core fact, which the Application alone carries. Core reads it as an opaque string,
+ * because the convention is the package manifest's own field and no scheme is imposed on it. An
+ * omitted version is `0.0.0`, which means unversioned, and core keeps no record of which one the
+ * author wrote.
+ */
+export function checkVersion(value) {
+    if (value === undefined) {
+        return '0.0.0';
+    }
+    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+        throw new DeclarationError('The Application version must be a string that holds a character other than whitespace and no line terminator. Supply a string such as "1.2.0".');
+    }
+    return value;
+}
+/**
+ * A structural value core reads as plain data: an object literal, and never a declaration that
+ * carries state of its own. The options slots read it to reject a value that is not an options
+ * object, and inspection reads it to copy a declared value faithfully.
+ */
+export function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/globals.d.ts

@@ -1,36 +1,57 @@
+import { DeclarationError } from './errors.js';
 import { compileOptions } from './options.js';
-import type { DefaultConstraint, MultipleConstraint, NameConstraint, OptionConfig, OptionValue, ValidateOmittedConstraint } from './types.js';
-import type { InputDeclaration, ValidatedInputs } from './validation.js';
-/** Phantom key. It keeps the declared option types exact and holds no runtime value. */
-declare const declaredTypes: unique symbol;
-/** The compiled global table: one spelling map shared by every Command in the graph. */
+import type { BuiltPlugin, PluginBuild } from './plugin.js';
+import type { OptionConfig, OptionValue } from './types.js';
+import type { InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
+/**
+ * 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
+ * existing global-versus-local wording and the plugin wording read from one place.
+ */
+type OptionOwner = {
+    kind: 'application';
+} | {
+    kind: 'local';
+    subject: string;
+} | {
+    kind: 'plugin';
+    identity: string;
+    order: number;
+};
+/** One side of a collision: the option's declared name under the scope that declared it. */
+interface OptionSite {
+    name: string;
+    owner: OptionOwner;
+}
+/** One key claimed twice, whichever two scopes claimed it. */
+declare function keyCollision(name: string, first: OptionOwner, second: OptionOwner): DeclarationError;
+/** One spelling claimed twice, whichever two scopes claimed it. */
+declare function spellingCollision(spelling: string, first: OptionSite, second: OptionSite): DeclarationError;
+/**
+ * The compiled global table: one spelling map shared by every Command in the graph. It holds the
+ * application's global options and every installed plugin's options, because the pre-scan reads one
+ * table. `inputs` holds the application's declarations alone, because a plugin option is never
+ * validated and never reaches an action.
+ */
 interface BuiltGlobals {
+    bind: (values: ValidatedInputs) => unknown;
     inputs: readonly InputDeclaration[];
-    names: ReadonlySet<string>;
+    names: ReadonlyMap<string, OptionOwner>;
     options: ReturnType<typeof compileOptions>;
-    source: unknown;
+    plugins: readonly BuiltPlugin[];
 }
-declare class GlobalOptionsBuilder<Options> {
-    #private;
-    readonly [declaredTypes]: Options;
-    constructor(inputs: readonly InputDeclaration[], 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.
- */
-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.
+ * 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.
  */
-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): BuiltGlobals;
-declare function bindGlobals<Options>(globals: GlobalOptions<Options> | undefined, values: ValidatedInputs): Options;
-declare const GlobalOptions: new () => GlobalOptions;
-export type { BuiltGlobals };
-export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions };
+declare function buildGlobals(node: GlobalsState, plugins: readonly BuiltPlugin[], build: PluginBuild): BuiltGlobals;
+export type { BuiltGlobals, GlobalsState, OptionOwner, OptionSite };
+export { buildGlobals, declareGlobalOption, emptyGlobals, keyCollision, spellingCollision };