@loomcli/core 0.1.1 → 0.2.0

package/dist/extension.js

@@ -0,0 +1,313 @@
+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;
+}
+export { 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,19 +1,51 @@
+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 { InputDeclaration, ValidatedInputs } from './validation.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;
-/** The compiled global table: one spelling map shared by every Command in the graph. */
+/**
+ * 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 {
     inputs: readonly InputDeclaration[];
-    names: ReadonlySet<string>;
+    names: ReadonlyMap<string, OptionOwner>;
     options: ReturnType<typeof compileOptions>;
+    plugins: readonly BuiltPlugin[];
     source: unknown;
 }
 declare class GlobalOptionsBuilder<Options> {
     #private;
     readonly [declaredTypes]: Options;
-    constructor(inputs: readonly InputDeclaration[], bind: (values: ValidatedInputs) => 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>>>;
 }
 /**
@@ -29,8 +61,8 @@ type GlobalOptions<Options = {}> = Pick<GlobalOptionsBuilder<Options>, typeof de
  */
 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 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 };
-export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions };
+export type { BuiltGlobals, OptionOwner, OptionSite };
+export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions, keyCollision, spellingCollision, };

package/dist/globals.js

@@ -1,24 +1,71 @@
 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 = {
+    application: 1,
+    local: 2,
+    plugin: 0,
+};
+function ordered(first, second) {
+    const difference = ranks[first.owner.kind] - ranks[second.owner.kind];
+    if (difference !== 0) {
+        return difference < 0 ? [first, second] : [second, first];
+    }
+    if (first.owner.kind === 'plugin' && second.owner.kind === 'plugin') {
+        return first.owner.order <= second.owner.order ? [first, second] : [second, first];
+    }
+    return [first, second];
+}
+/** How one owner reads in a key collision. A repeated preposition is dropped after the first. */
+function declaredBy(owner, leading) {
+    if (owner.kind === 'plugin') {
+        return `${leading ? 'by ' : ''}plugin "${owner.identity}"`;
+    }
+    return owner.kind === 'application'
+        ? 'as a global option'
+        : `as a local option on ${owner.subject}`;
+}
+/** How one owner reads in a spelling collision, where each side names its own option. */
+function usedBy({ name, owner }) {
+    if (owner.kind === 'plugin') {
+        return `plugin "${owner.identity}" option "${name}"`;
+    }
+    return owner.kind === 'application'
+        ? `the global option "${name}"`
+        : `the local option "${name}" on ${owner.subject}`;
+}
+/** The correction each pair earns: a local is renamed, and two plugins are chosen between. */
+function correction(first, second) {
+    if (first.kind === 'local' || second.kind === 'local') {
+        return 'Rename the local option.';
+    }
+    return first.kind === 'plugin' && second.kind === 'plugin'
+        ? 'Install one of them or rename the option.'
+        : 'Rename one declaration.';
+}
+/** One key claimed twice, whichever two scopes claimed it. */
+function keyCollision(name, first, second) {
+    const [leading, trailing] = ordered({ name, owner: first }, { name, owner: second });
+    return new DeclarationError(`Option "${name}" is declared ${declaredBy(leading.owner, true)} and ${declaredBy(trailing.owner, false)}. ${correction(leading.owner, trailing.owner)}`);
+}
+/** One spelling claimed twice, whichever two scopes claimed it. */
+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();
-function compileTable(inputs, source) {
-    return {
-        inputs,
-        names: new Set(inputs.map((input) => input.name)),
-        options: compileOptions(inputs.filter((input) => input.kind === 'option'), globalSubject),
-        source,
-    };
-}
 class GlobalOptionsBuilder {
     #bind;
     #inputs;
     constructor(inputs, bind) {
         this.#bind = bind;
         this.#inputs = inputs;
-        nodes.set(this, { bind, build: () => compileTable(inputs, this) });
+        nodes.set(this, { bind, inputs, source: this });
     }
     option(name, config) {
         const input = {
@@ -49,9 +96,59 @@ function nodeOf(globals) {
 function isGlobalOptions(value) {
     return typeof value === 'object' && value !== null && nodes.has(value);
 }
+/**
+ * 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) {
+    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.
+    for (const input of node.inputs) {
+        const sentence = `Global option "${input.name}"`;
+        checkDescription(sentence, input.config.description);
+        checkHidden(sentence, input.config.hidden);
+        checkDeprecated(sentence, input.config.deprecated);
+        build.extensions.set(input, buildExtensions({
+            declared: input.config.extensions,
+            descriptors: build.descriptors,
+            subject: { phrase: `on the global option "${input.name}"`, sentence },
+            target: 'option',
+        }));
+        names.set(input.name, application);
+    }
+    const options = compileOptions(node.inputs, globalSubject);
+    plugins.forEach((installed, order) => {
+        join({ identity: installed.identity, kind: 'plugin', order }, installed.inputs, {
+            names,
+            options,
+        });
+    });
+    return { inputs: node.inputs, names, options, plugins, source: node.source };
+}
+/** One plugin's options joining the table the application's globals already hold. */
+function join(owner, inputs, table) {
+    const { names, options } = table;
+    for (const input of inputs) {
+        const claimed = names.get(input.name);
+        if (claimed) {
+            throw keyCollision(input.name, owner, claimed);
+        }
+        names.set(input.name, owner);
+    }
+    for (const [spelling, option] of compileOptions(inputs, `plugin "${owner.identity}"`)) {
+        const claimed = options.get(spelling);
+        if (claimed) {
+            throw spellingCollision(spelling, { name: option.name, owner }, { name: claimed.name, owner: names.get(claimed.name) ?? { kind: 'application' } });
+        }
+        options.set(spelling, option);
+    }
+}
 /** Absent globals compile to an empty table whose source is `undefined`, like the declarations. */
-function buildGlobals(globals) {
-    return globals === undefined ? compileTable([], undefined) : nodeOf(globals).build();
+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);
@@ -68,4 +165,4 @@ const GlobalOptions = class extends GlobalOptionsBuilder {
         super([], () => ({}));
     }
 };
-export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions };
+export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions, keyCollision, spellingCollision, };