@loomcli/core 0.4.0 → 0.6.0

package/dist/theme.js

@@ -1,19 +1,39 @@
-import { DeclarationError } from './errors.js';
-import { isPlainObject } from './facts.js';
+import { DeclarationError, quoted } from './errors.js';
+import { partFinding, slotSite } from './facts.js';
+import { isPlainObject } from './plain.js';
+import { themeMapping, themeNameTaken } from './plugin-rules.js';
 import { chains, reservedStyleNames } from './style.js';
+/**
+ * One plugin's theme, read as the palette core resolves semantic styles through. Each fault marks
+ * the theme, or the one entry at fault, in `plugin(identity, { theme })`.
+ */
 function buildTheme(value, identity) {
+    const subject = `Plugin ${quoted(identity)}`;
+    const site = slotSite({ call: 'plugin', named: identity, subject }, 'theme', value);
     if (!isPlainObject(value)) {
-        throw new DeclarationError(`Plugin "${identity}" must declare theme as a mapping of names to concrete style chains.`);
+        throw new DeclarationError(themeMapping, {
+            correction: 'Supply a mapping of names to concrete style chains.',
+            findings: [partFinding(site, [])],
+            sentence: `${subject} declares a theme that is not a mapping.`,
+        });
     }
     const palette = new Map();
     for (const [name, chain] of Object.entries(value)) {
         if (reservedStyleNames.has(name)) {
-            throw new DeclarationError(`Plugin "${identity}" theme name "${name}" shadows a built-in style member.`);
+            throw new DeclarationError(themeNameTaken, {
+                correction: 'Rename the theme entry.',
+                findings: [partFinding(site, [name])],
+                sentence: `${subject} theme name ${quoted(name)} shadows a built-in style member.`,
+            });
         }
         const operations = typeof chain === 'function' ? chains.get(chain) : undefined;
         if (chain !== undefined &&
             (operations === undefined || operations.some((entry) => entry[0] === 'token'))) {
-            throw new DeclarationError(`Plugin "${identity}" theme mapping "${name}" must be an unapplied concrete style chain without semantic tokens.`);
+            throw new DeclarationError(themeMapping, {
+                correction: 'Map the name to a concrete chain such as style.cyan.bold, without calling it or naming a semantic style.',
+                findings: [partFinding(site, [name])],
+                sentence: `${subject} theme mapping ${quoted(name)} is not an unapplied concrete style chain without semantic tokens.`,
+            });
         }
         palette.set(name, operations ?? []);
     }

package/dist/thenable.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether one value is a promise or another thenable. A thenable object and a promise from another
+ * realm are as unwaitable to a synchronous caller as a native one, so the test is the contract and
+ * not the class, and a function with a callable `then` counts, as Promises/A+ says. A value whose
+ * `then` cannot be read, such as a proxy whose trap throws, is not a thenable, so the test itself
+ * never throws.
+ */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+/**
+ * Attaches a rejection handler to a thenable a synchronous function returned, and otherwise
+ * ignores it. An unobserved rejection would end the process before the run could report anything.
+ * The thenable is adopted inside a fresh promise, so a `then` that throws rejects that promise
+ * instead of throwing here.
+ */
+export declare function ignoreRejection(value: PromiseLike<unknown>): void;

package/dist/thenable.js

@@ -0,0 +1,29 @@
+/**
+ * Whether one value is a promise or another thenable. A thenable object and a promise from another
+ * realm are as unwaitable to a synchronous caller as a native one, so the test is the contract and
+ * not the class, and a function with a callable `then` counts, as Promises/A+ says. A value whose
+ * `then` cannot be read, such as a proxy whose trap throws, is not a thenable, so the test itself
+ * never throws.
+ */
+export function isThenable(value) {
+    try {
+        return ((typeof value === 'object' || typeof value === 'function') &&
+            value !== null &&
+            'then' in value &&
+            typeof value.then === 'function');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Attaches a rejection handler to a thenable a synchronous function returned, and otherwise
+ * ignores it. An unobserved rejection would end the process before the run could report anything.
+ * The thenable is adopted inside a fresh promise, so a `then` that throws rejects that promise
+ * instead of throwing here.
+ */
+export function ignoreRejection(value) {
+    void new Promise((resolve) => {
+        resolve(value);
+    }).catch(() => undefined);
+}

package/dist/translators.d.ts

@@ -0,0 +1,69 @@
+import { LoomError } from './errors.js';
+import type { FactSite } from './facts.js';
+/** Phantom key. It brands a translation and holds no runtime value. */
+declare const translation: unique symbol;
+/**
+ * A class a translation is keyed on, such as `SyntaxError`. Its instance type is the type the
+ * translator receives, so the function needs no narrowing of its own.
+ */
+type ErrorClass<Thrown extends object> = abstract new (...args: never[]) => Thrown;
+/**
+ * A function that turns one foreign throw into one of the author's failures, or answers
+ * `undefined` to pass the throw on to the next translator.
+ */
+type Translator<Thrown extends object> = (error: Thrown) => LoomError | undefined;
+/** One translation as core reads it back: the key's prototype, its name, and the typed call. */
+interface TranslationRecord {
+    /** The object a thrown value's prototype chain holds when the key's class constructed it. */
+    prototype: object;
+    /** The key's name, which a broken translator's diagnostic reports. */
+    name: string;
+    /**
+     * The translator, typed at `translate()` against its key. It answers `undefined` without calling
+     * the translator for a value its key does not claim as an instance.
+     */
+    offer: (thrown: object) => unknown;
+}
+/** The runtime value `translate()` returns. Its record lives in the registry above. */
+declare class TranslationDeclaration {
+    readonly [translation]: true;
+    constructor(record: TranslationRecord);
+}
+/** An opaque translation pairing one error class with the translator that answers it. */
+type Translation = Pick<TranslationDeclaration, typeof translation>;
+/**
+ * Pairs an error class with the translator that turns its instances into a failure. The
+ * translator receives the thrown instance typed from the class, and a `translators` list on the
+ * Application or a plugin registers the pair.
+ */
+declare function translate<Thrown extends object>(key: ErrorClass<Thrown>, translator: Translator<Thrown>): Translation;
+/**
+ * One contributor's translations: how a diagnostic names it, and its records by key prototype,
+ * each list in the order the contributor listed it.
+ */
+interface TranslationContributor {
+    /** The contributor as a diagnostic's subject, such as `the Application` or `plugin "@acme/http"`. */
+    subject: string;
+    byPrototype: ReadonlyMap<object, readonly TranslationRecord[]>;
+}
+/**
+ * Every contributor in resolution order: the application's translations, then each installed
+ * plugin's in installation order.
+ */
+type TranslatorRegistry = readonly TranslationContributor[];
+/**
+ * One contributor's `translators` list. `site` names the contributor at the start of a sentence,
+ * `The Application` or `Plugin "@acme/http"`, and holds the call that declared the list, which a
+ * fault marks. The slot is read defensively, because a JavaScript author reaches it with any value.
+ */
+declare function readTranslations(site: FactSite, declared: unknown): TranslationContributor;
+/**
+ * The failure the translators answer for one foreign throw, or `undefined` when the throw is never
+ * offered or every translator passed. Resolution follows the override walk: each contributor in
+ * order, the thrown value's chain walked in full at each, most derived first, and within one
+ * class the list order. A broken translator ends the walk with its defect, so no later translator
+ * hides it.
+ */
+declare function translateThrow(registry: TranslatorRegistry, thrown: unknown): LoomError | undefined;
+export type { ErrorClass, TranslationContributor, Translation, Translator, TranslatorRegistry };
+export { readTranslations, translate, translateThrow };

package/dist/translators.js

@@ -0,0 +1,253 @@
+import { spelled } from './diagnostic-text.js';
+import { asSentence, DeclarationError, InternalError, LoomError, quoted, reasonOf, } from './errors.js';
+import { partFinding } from './facts.js';
+import { foreignValue, notAFunction, notAList, translationKey } from './plugin-rules.js';
+import { prototypeChain } from './prototypes.js';
+import { brokenTranslator, brokenTranslatorCorrection } from './rules.js';
+import { ignoreRejection, isThenable } from './thenable.js';
+/** Authored translations register here, so the public type publishes nothing to reach. */
+const records = new WeakMap();
+/** The runtime value `translate()` returns. Its record lives in the registry above. */
+class TranslationDeclaration {
+    constructor(record) {
+        records.set(this, record);
+        Object.freeze(this);
+    }
+}
+/**
+ * The prototype a class key carries, or `undefined` for a value that is not a class. A class is a
+ * function whose `prototype` is the object its instances' chains hold, so an arrow function, a
+ * bound function, and every non-function are no key at all. A key whose `prototype` cannot be
+ * read, such as a proxy whose trap throws, is no key either.
+ */
+function keyPrototype(key) {
+    let prototype = undefined;
+    try {
+        if (typeof key !== 'function' || !('prototype' in key)) {
+            return undefined;
+        }
+        prototype = key.prototype;
+    }
+    catch {
+        return undefined;
+    }
+    return typeof prototype === 'object' && prototype !== null ? prototype : undefined;
+}
+/** A key's own name, or `undefined` when it has none that can be read. */
+function nameOf(key) {
+    let name = undefined;
+    try {
+        name = 'name' in key ? key.name : undefined;
+    }
+    catch {
+        name = undefined;
+    }
+    return typeof name === 'string' && name !== '' ? name : undefined;
+}
+/**
+ * How a diagnostic names one key class: its name, quoted and escaped, or what it is when it has no
+ * name that can be read.
+ */
+function keyName(key) {
+    const name = nameOf(key);
+    return name === undefined ? 'an anonymous class' : quoted(name);
+}
+/** A name JavaScript source can spell as an identifier, which a finding prints a class key as. */
+const identifier = /^[A-Za-z_$][\w$]*$/u;
+/**
+ * The finding for one `translate()` call, marking the argument at `mark`. A class key prints as
+ * its name, as its author wrote it, where any other function prints as an ellipsis.
+ */
+function translateFinding(key, translator, mark) {
+    const name = typeof key === 'function' ? nameOf(key) : undefined;
+    const code = name !== undefined && identifier.test(name) ? spelled(name) : key;
+    return { arguments: [code, translator], call: 'translate', mark };
+}
+/**
+ * Whether a key claims a thrown value as its instance. A value whose chain cannot be read is not
+ * claimed, so its translator is never called and is not blamed for the failed read.
+ */
+function claims(thrown, key) {
+    try {
+        return thrown instanceof key;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pairs an error class with the translator that turns its instances into a failure. The
+ * translator receives the thrown instance typed from the class, and a `translators` list on the
+ * Application or a plugin registers the pair.
+ */
+function translate(key, translator) {
+    const prototype = keyPrototype(key);
+    // A key whose prototype's chain cannot be read, such as through a proxy whose trap throws, is no
+    // Key either, so it is reported as a non-class before any failure-class check.
+    const chain = prototype === undefined ? undefined : prototypeChain(prototype);
+    if (prototype === undefined || chain === undefined) {
+        throw new DeclarationError(translationKey, {
+            correction: 'Supply an error class, such as SyntaxError.',
+            findings: [translateFinding(key, translator, '0')],
+            sentence: 'translate() received a key that is not a class.',
+        });
+    }
+    // Core never offers a failure to translators, so a translation keyed on a failure class never runs.
+    if (prototype === LoomError.prototype || chain.includes(LoomError.prototype)) {
+        throw new DeclarationError(translationKey, {
+            correction: 'Key the translation on the foreign class it replaces.',
+            findings: [translateFinding(key, translator, '0')],
+            sentence: 'translate() received a failure class as its key.',
+        });
+    }
+    if (typeof translator !== 'function') {
+        throw new DeclarationError(notAFunction, {
+            correction: 'Supply a function that returns a failure or undefined.',
+            findings: [translateFinding(key, translator, '1')],
+            sentence: 'translate() received a translator that is not a function.',
+        });
+    }
+    return new TranslationDeclaration({
+        name: keyName(key),
+        offer: (thrown) => (claims(thrown, key) ? translator(thrown) : undefined),
+        prototype,
+    });
+}
+/**
+ * One contributor's `translators` list. `site` names the contributor at the start of a sentence,
+ * `The Application` or `Plugin "@acme/http"`, and holds the call that declared the list, which a
+ * fault marks. The slot is read defensively, because a JavaScript author reaches it with any value.
+ */
+function readTranslations(site, declared) {
+    const sentence = site.subject;
+    const byPrototype = new Map();
+    for (const record of translationRecords(site, declared)) {
+        const listed = byPrototype.get(record.prototype) ?? [];
+        listed.push(record);
+        byPrototype.set(record.prototype, listed);
+    }
+    return {
+        byPrototype,
+        subject: `${sentence.slice(0, 1).toLowerCase()}${sentence.slice(1)}`,
+    };
+}
+/** The fix a `translators` slot's list fault and entry fault share. */
+const translationSupply = 'translate(ErrorClass, translator)';
+/** The record behind each entry of one `translators` slot, whose every other value is its fault. */
+function translationRecords(site, declared) {
+    if (declared !== undefined && !Array.isArray(declared)) {
+        throw new DeclarationError(notAList, {
+            correction: `Supply a list of values returned by ${translationSupply}.`,
+            findings: [partFinding(site, [])],
+            sentence: `${site.subject} declares translators that are not an array.`,
+        });
+    }
+    const list = declared ?? [];
+    // Array.from visits a hole as undefined, where map would skip it and leave the hole in place.
+    return Array.from(list, (entry, index) => {
+        const record = typeof entry === 'object' && entry !== null ? records.get(entry) : undefined;
+        if (!record) {
+            throw new DeclarationError(foreignValue, {
+                correction: `Supply the value returned by ${translationSupply}.`,
+                findings: [partFinding(site, [index])],
+                sentence: `${site.subject} holds a translator entry that is not a translation.`,
+            });
+        }
+        return record;
+    });
+}
+/**
+ * Every prototype in one thrown value's chain, most derived first, or `undefined` when the value is
+ * never offered: a value whose chain holds a failure class, and a value whose chain cannot be read,
+ * such as a proxy whose trap throws, or whose chain repeats a link or never ends. A value with a
+ * `null` prototype has an empty chain, which no key matches.
+ */
+function offeredChain(thrown) {
+    const chain = prototypeChain(thrown);
+    return chain?.includes(LoomError.prototype) ? undefined : chain;
+}
+/** How a broken translator's diagnostic names a value that is not a failure. */
+function returnedKind(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (isThenable(value)) {
+        return 'a promise';
+    }
+    const kind = typeof value;
+    return /^[aeiou]/u.test(kind) ? `an ${kind}` : `a ${kind}`;
+}
+/** Whether a translator's answer is a failure, read without letting a hostile value throw. */
+function isFailure(value) {
+    try {
+        return value instanceof LoomError;
+    }
+    catch {
+        return false;
+    }
+}
+/** The defect of a broken translator under its rule, with the sentence and cause each shape gives. */
+function brokenDefect(sentence, cause) {
+    return new InternalError(brokenTranslator, {
+        cause,
+        correction: brokenTranslatorCorrection,
+        sentence,
+    });
+}
+/**
+ * The defect of a translator that threw. Its cause is a new `AggregateError` that holds the
+ * translator's throw and then the original throw, so neither is lost and neither is mutated. The
+ * reason is read through `reasonOf`, which escapes it onto one line.
+ */
+function threwDefect(who, error, thrown) {
+    const reason = reasonOf(error);
+    const cause = new AggregateError([error, thrown], 'The translator threw while translating the original throw.');
+    return brokenDefect(`${who} threw: ${asSentence(reason)}`, cause);
+}
+/** The one translator call, whose throw or non-failure answer is the defect of that translator. */
+function consult(contributor, record, thrown) {
+    const who = `The translator ${contributor.subject} registered for ${record.name}`;
+    let answer = undefined;
+    try {
+        answer = record.offer(thrown);
+    }
+    catch (error) {
+        return threwDefect(who, error, thrown);
+    }
+    if (answer === undefined || isFailure(answer)) {
+        return answer;
+    }
+    // A translator is synchronous, so a returned promise is ignored once its rejection is observed.
+    if (isThenable(answer)) {
+        ignoreRejection(answer);
+    }
+    return brokenDefect(`${who} returned ${returnedKind(answer)} instead of a failure.`, thrown);
+}
+/**
+ * The failure the translators answer for one foreign throw, or `undefined` when the throw is never
+ * offered or every translator passed. Resolution follows the override walk: each contributor in
+ * order, the thrown value's chain walked in full at each, most derived first, and within one
+ * class the list order. A broken translator ends the walk with its defect, so no later translator
+ * hides it.
+ */
+function translateThrow(registry, thrown) {
+    if ((typeof thrown !== 'object' && typeof thrown !== 'function') || thrown === null) {
+        return undefined;
+    }
+    // With no translation registered, the chain is never read.
+    const chain = registry.some((contributor) => contributor.byPrototype.size > 0)
+        ? (offeredChain(thrown) ?? [])
+        : [];
+    for (const contributor of registry) {
+        for (const prototype of chain) {
+            for (const record of contributor.byPrototype.get(prototype) ?? []) {
+                const answer = consult(contributor, record, thrown);
+                if (answer !== undefined) {
+                    return answer;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export { readTranslations, translate, translateThrow };

package/dist/types.d.ts

@@ -1,8 +1,9 @@
 /// <reference types="node" preserve="true" />
 import type { Readable, Writable } from 'node:stream';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { FailureExitCode } from './exit-codes.js';
 import type { ExtensionValue } from './extension.js';
-import type { ResultNode } from './inspect.js';
+import type { CommandGraph, CommandNode, ResultNode } from './inspect.js';
 import type { RenderingPolicy } from './rendering.js';
 import type { ContextualStyle } from './style.js';
 type LowercaseLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
@@ -21,12 +22,23 @@ type Presence = {
     required?: false;
     default?: unknown;
 };
-/** The literal member keeps `multiple: true` exact under contextual typing, as `Presence` does. */
+/**
+ * The literal member keeps `multiple: true` exact under contextual typing, as `Presence` does.
+ * A multiple option takes its list from the configuration source, so it binds no variable.
+ */
 type Multiplicity = {
     multiple: true;
-} | {
+    env?: never;
+} | ({
     multiple?: false;
-};
+} & EnvBinding);
+/**
+ * The environment binding: the variable the input-source stage fills the option from when argv
+ * supplies none. The declaration names it explicitly, and core derives no name.
+ */
+interface EnvBinding {
+    env?: string;
+}
 /**
  * `validateOmitted: true` sends an omitted optional scalar to its own schema. The literal member
  * keeps the flag exact under contextual typing, as `Multiplicity` does.
@@ -62,15 +74,22 @@ interface ArgumentExtensions {
     extensions?: readonly ExtensionValue<'argument'>[];
 }
 /**
- * The tokens one declaration collects before validation: one string, or the whole collection. A
- * multiple option and a variadic argument collect alike, so they share this raw shape.
+ * The tokens one declaration collects before validation: one string, or several. A multiple option
+ * and a variadic argument collect alike, so they share this raw shape.
  */
 type RawValue<Config> = Config extends {
     multiple: true;
 } | {
     variadic: true;
 } ? string[] : string;
-type SchemaOutput<Schema, Raw> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Schema> : Raw;
+/** A multiple option and a variadic argument pass each value through the same validator. */
+type PerValue<Config, Value> = Config extends {
+    multiple: true;
+} | {
+    variadic: true;
+} ? Value[] : Value;
+/** The validated value: the validator's output for each value, or the raw shape without one. */
+type SchemaOutput<Config, Schema, Raw> = Schema extends StandardSchemaV1 ? PerValue<Config, StandardSchemaV1.InferOutput<Schema>> : Raw;
 type SchemaInput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<Schema> : string;
 /** The named key states the rule, so a rejected declaration name reads as its own diagnostic. */
 interface LiteralNameFault {
@@ -83,7 +102,8 @@ export type GlobalNameConstraint<Name extends string, Globals> = Name extends ke
 } : unknown;
 /** A required record key excludes open strings; distribution rejects each union member. */
 export type NameConstraint<Name extends string, Whole extends string = Name> = {} extends Record<Name, unknown> ? LiteralNameFault : Name extends Whole ? [Whole] extends [Name] ? unknown : LiteralNameFault : LiteralNameFault;
-export type ExitCode = 0 | 1 | 2 | 130 | 143;
+/** The status `run()` resolves: success, a failure class's code, or a cancellation code. */
+export type ExitCode = 0 | FailureExitCode | 130 | 143;
 export interface InputTerminal {
     isTTY: boolean;
 }
@@ -104,6 +124,14 @@ export interface Host {
     stdin: Readable;
     stdout: Writable;
     stderr: Writable;
+    /**
+     * Reads one source file for a defect's Developer Diagnostic, or answers `undefined`. Core calls
+     * it only in a development build, only while it reports a defect, and only for a path under the
+     * working directory. Process capture supplies a reader that refuses a file outside `cwd` after
+     * resolving symbolic links, and answers `undefined` for a path that is not a regular file or
+     * that exceeds 1 MiB.
+     */
+    readSource?: (path: string, cwd: string) => string | undefined;
 }
 export interface RunOptions {
     rendering?: RenderingPolicy;
@@ -324,19 +352,24 @@ export type ScalarArgument = Presence & Omission & Described & ArgumentExtension
     validate?: StandardSchemaV1;
 };
 export type ArgumentConfig = VariadicArgument | ScalarArgument;
-export type ValidatedValue<Config, Raw> = Config extends unknown ? 'validate' extends keyof Config ? SchemaOutput<Config['validate'], Raw> : Raw : never;
-/** Keep each conditional declaration paired with its own schema input type. */
+export type ValidatedValue<Config, Raw> = Config extends unknown ? 'validate' extends keyof Config ? SchemaOutput<Config, Config['validate'], Raw> : Raw : never;
+/** Keep each conditional declaration paired with its own validator input type. */
 export type DefaultConstraint<Config> = Config extends unknown ? Config & {
-    default?: 'validate' extends keyof Config ? SchemaInput<Config['validate']> : RawValue<Config>;
+    default?: 'validate' extends keyof Config ? PerValue<Config, SchemaInput<Config['validate']>> : RawValue<Config>;
 } : never;
 /**
- * A multiple option hands its whole collection to one schema, so the declared schema must accept a
- * `string[]` input. The key names the fault, the way the other declaration constraints do.
+ * A multiple option or a variadic argument passes each value to its validator alone, so the
+ * declared validator must accept one `string`. The key names the fault, the way the other
+ * declaration constraints do.
  */
-export type MultipleConstraint<Config> = Config extends {
+export type PerValueConstraint<Config> = Config extends {
     multiple: true;
-} ? 'validate' extends keyof Config ? string[] extends SchemaInput<Config['validate']> ? unknown : {
-    'A multiple option schema must accept a string[] input': Config['validate'];
+} | {
+    variadic: true;
+} ? 'validate' extends keyof Config ? [
+    SchemaInput<Config['validate']>
+] extends [never] ? unknown : string extends SchemaInput<Config['validate']> ? unknown : {
+    'A validator of several values must accept one string input': Config['validate'];
 } : unknown : unknown;
 /**
  * The declaration rules `validateOmitted: true` needs: a schema that accepts `undefined`, an
@@ -362,12 +395,28 @@ export type ValidateOmittedConstraint<Config> = Config extends {
 } | {
     variadic: true;
 } ? {
-    'A collected input validates its omission as an empty array': never;
+    'An input of several values receives no values as an empty array': never;
 } : 'validate' extends keyof Config ? undefined extends SchemaInput<Config['validate']> ? unknown : {
-    'A validateOmitted schema must accept an undefined input': Config['validate'];
+    'A validateOmitted validator must accept an undefined input': Config['validate'];
 } : {
-    'validateOmitted needs a validate schema to receive the omission': never;
+    'validateOmitted needs a validator to receive the omission': never;
 } : unknown;
+/**
+ * A global option declares no presence rule, so its omission is always plain absence. A union
+ * config fails when any member declares the key, and a wide `OptionConfig` passes, because its
+ * members only allow the key.
+ */
+export type GlobalOmissionConstraint<Config> = [Extract<Config, {
+    required: unknown;
+}>] extends [
+    never
+] ? [Extract<Config, {
+    validateOmitted: unknown;
+}>] extends [never] ? unknown : {
+    'A global option declares no validateOmitted; its omission is plain absence': never;
+} : {
+    'A global option declares no required; the Commands that read it check for it': never;
+};
 export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
     variadic: true;
 } ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
@@ -377,7 +426,7 @@ export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
 } | {
     validateOmitted: true;
 } ? never : undefined);
-export type BooleanOption = (OptionSpelling & Described & Listed & OptionExtensions & {
+export type BooleanOption = (OptionSpelling & Described & Listed & EnvBinding & OptionExtensions & {
     type: 'boolean';
     validate?: never;
     default?: never;
@@ -385,7 +434,7 @@ export type BooleanOption = (OptionSpelling & Described & Listed & OptionExtensi
     required?: never;
     validateOmitted?: never;
     polarity?: 'positive' | 'negative';
-}) | (Described & Listed & OptionExtensions & {
+}) | (Described & Listed & EnvBinding & OptionExtensions & {
     type: 'boolean';
     validate?: never;
     default?: never;
@@ -422,10 +471,16 @@ export type OptionValue<Config extends OptionConfig> = Config extends StringOpti
 } | {
     validateOmitted: true;
 } ? never : undefined) : boolean;
+/**
+ * What an action receives. `graph` is the frozen graph `inspect()` returns for this run, and
+ * `command` is the routed node inside it: the same two values the run's middleware receive.
+ */
 export interface ActionContext<Args, Options = {}, Result = unknown> {
     readonly style: ContextualStyle;
     args: Args;
     options: Options;
+    readonly graph: CommandGraph;
+    readonly command: CommandNode;
     passthrough: string[];
     out: Out<Result>;
     host: Host;