@loomcli/core 0.6.0 → 0.7.0

package/dist/globals.js

@@ -4,7 +4,7 @@ import { buildExtensions } from './extension.js';
 import { callSite, checkDeprecated, checkDescription, checkHidden, factFault, pluginOptionSite, siteFinding, } from './facts.js';
 import { globalPresenceRule, optionDeclaredTwice, spellingTaken } from './input-rules.js';
 import { checkOptionName, compileOptions, spellingMark } from './options.js';
-import { captureConfig, checkInputConfig } from './validation.js';
+import { captureInputConfig, configUnread } from './validation.js';
 const globalSubject = 'the global options';
 /**
  * The presence keys a global option may not declare, in the order its diagnostic names them. A
@@ -99,7 +99,7 @@ function globalSite(input) {
  */
 function pluginSites(identity, inputs) {
     const options = Object.fromEntries(inputs.map(({ config, name }) => [name, config]));
-    return (input) => pluginOptionSite({ identity, options }, input.name, `Plugin ${quoted(identity)} option "${input.name}"`);
+    return (input) => pluginOptionSite({ identity, options }, input.name, `Plugin ${quoted(identity)} option ${quoted(input.name)}`);
 }
 /**
  * One global option's own facts, binding, and extension values, checked at its `globalOption()`
@@ -108,9 +108,11 @@ function pluginSites(identity, inputs) {
  */
 function declareGlobalOption(state, declared, descriptors) {
     // The name is judged before the config, as every other declaration judges its own name first.
-    checkOptionName(declared.name, globalSite(declared));
-    checkInputConfig(declared, { call: 'globalOption', path: [] });
-    const input = { ...declared, config: captureConfig(declared.config) };
+    checkOptionName(declared.name, configUnread(globalSite(declared)));
+    const input = {
+        ...declared,
+        config: captureInputConfig(declared, { call: 'globalOption', path: [] }),
+    };
     const site = globalSite(input);
     const sentence = site.subject;
     const rejected = omissionRules.find((key) => key in input.config);
@@ -168,7 +170,7 @@ function globalTable(inputs, plugins) {
         ...plugins.flatMap((installed) => {
             const siteOf = pluginSites(installed.identity, installed.inputs);
             return boundOptions(installed.inputs, (input) => ({
-                phrase: `plugin ${quoted(installed.identity)} option "${input.name}"`,
+                phrase: `plugin ${quoted(installed.identity)} option ${quoted(input.name)}`,
                 site: siteOf(input),
             }));
         }),
@@ -206,7 +208,7 @@ function checkLocalOptions(declarations, table, scope) {
         }
     }
     claimVariables(boundOptions(declarations, (input) => ({
-        phrase: `${subject} option "${input.name}"`,
+        phrase: `${subject} option ${quoted(input.name)}`,
         site: siteOf(input),
     })), table.variables);
     return options;

package/dist/glyphs.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/check-glyph-catalog.py from Inquirer a446ea9e273864a3653a26943f59b4fbe8003796.
-/*
+/*!
 Copyright (c) 2025 Simon Boudrias
 
 Permission is hereby granted, free of charge, to any person

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { locate } from './locate.js';
 export { incompleteResult, lanes } from './lanes.js';
 export { override, view } from './view.js';
 export { plugin } from './plugin.js';
+export { checkShortSetting } from './plugin-settings.js';
 export { translate } from './translators.js';
 export { glyph } from './glyphs.generated.js';
 export type { RenderingPolicy } from './rendering.js';
@@ -30,7 +31,7 @@ export type { CancellationReason } from './signals.js';
 export type { ErrorClass, Translation, Translator } from './translators.js';
 export type { IncompleteResult } from './lanes.js';
 export type { WordPosition } from './locate.js';
-export type { AnyDeclaredView, DeclaredRowView, DeclaredView, DeclaredViewBrand, FailureClass, FailureView, FailureViewContext, ViewContribution, ViewOverride, } from './view.js';
+export type { AnyDeclaredView, AnyOverrideKey, DeclaredRowView, DeclaredView, DeclaredViewBrand, FailureClass, FailureView, FailureViewContext, ReplacementView, ViewContribution, ViewOverride, } from './view.js';
 export type { ArgumentNode, CommandGraph, CommandNode, OptionNode, ResultNode } from './inspect.js';
 export type { Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionSpellings, PluginOptionValues, SourceAnswer, SourceContext, SourceResolver, } from './plugin.js';
 export type { Action, ActionArgs, ActionContext, ActionHandler, ActionOptions, ArgumentConfig, AttachedCommand, BooleanOption, CommandAttachHook, ExitCode, Host, InputIdentity, InputTerminal, Out, OptionConfig, OutputTerminal, Request, ResultInput, ResultView, ResultViews, RunOptions, ScalarArgument, StringOption, SuppliedInputs, RowView, RowViews, ValidationContext, VariadicArgument, View, } from './types.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { locate } from './locate.js';
 export { incompleteResult, lanes } from './lanes.js';
 export { override, view } from './view.js';
 export { plugin } from './plugin.js';
+export { checkShortSetting } from './plugin-settings.js';
 export { translate } from './translators.js';
 export { glyph } from './glyphs.generated.js';
 export { pad, style } from './style.js';

package/dist/input-rules.d.ts

@@ -57,8 +57,12 @@ declare const requiredWithDefault: import("./diagnostic-text.js").DiagnosticRule
 declare const notAValidator: import("./diagnostic-text.js").DiagnosticRule;
 /** A default of the wrong raw shape for its declaration. */
 declare const defaultShape: import("./diagnostic-text.js").DiagnosticRule;
+/** The most arrays and plain objects any path through a declared default may hold. */
+declare const defaultLevels = 10;
+/** A declared default nested deeper than `defaultLevels`. */
+declare const defaultDepth: import("./diagnostic-text.js").DiagnosticRule;
 /** A declared default its validator rejected. */
 declare const invalidDefault: import("./diagnostic-text.js").DiagnosticRule;
 /** A validator's JSON Schema converter that threw or returned a value that is not a plain object. */
 declare const schemaConverterFailed: import("./diagnostic-text.js").DiagnosticRule;
-export { booleanOptionMultiple, booleanOptionValueRule, defaultShape, envName, envOnArgument, envOnMultiple, flagNotBoolean, globalOptionAfterCommand, globalPresenceRule, invalidDefault, notAValidator, omissionAlreadyDecided, nameSharedAcrossKinds, omissionWithoutValidator, optionDeclaredTwice, optionPolarity, optionType, polarityOnString, requiredWithDefault, schemaConverterFailed, shortAlias, shortOnlyBothPolarities, shortOnlyWithoutShort, spellingTaken, variableBoundTwice, };
+export { booleanOptionMultiple, booleanOptionValueRule, defaultDepth, defaultLevels, defaultShape, envName, envOnArgument, envOnMultiple, flagNotBoolean, globalOptionAfterCommand, globalPresenceRule, invalidDefault, notAValidator, omissionAlreadyDecided, nameSharedAcrossKinds, omissionWithoutValidator, optionDeclaredTwice, optionPolarity, optionType, polarityOnString, requiredWithDefault, schemaConverterFailed, shortAlias, shortOnlyBothPolarities, shortOnlyWithoutShort, spellingTaken, variableBoundTwice, };

package/dist/input-rules.js

@@ -132,6 +132,13 @@ const defaultShape = registerRule('@loomcli/core/default-shape', {
     explanation: "A default stands in for the value an operator would supply. Without a validator it is that raw value, a string or, for an input that takes several values, an array of strings; with one, it is the validator's input, and an input that takes several values still takes an array of them.",
     headline: 'Default of the wrong shape',
 });
+/** The most arrays and plain objects any path through a declared default may hold. */
+const defaultLevels = 10;
+/** A declared default nested deeper than `defaultLevels`. */
+const defaultDepth = registerRule('@loomcli/core/default-depth', {
+    explanation: `A default stands in for the value an operator would supply, and every reader of the graph, help and the manifest included, walks it. Core keeps every path through a default within ${String(defaultLevels)} levels of arrays and plain objects, and a default that holds itself nests without end, so every reader stays far inside the call stack on every runtime.`,
+    headline: 'Default nested too deep',
+});
 /** A declared default its validator rejected. */
 const invalidDefault = registerRule('@loomcli/core/invalid-default', {
     explanation: 'Each run passes every declared default through its validator before it reads a token, because a default reaches the action as a validated value. A default the validator rejects would reach no action, whatever the operator supplies.',
@@ -142,4 +149,4 @@ const schemaConverterFailed = registerRule('@loomcli/core/schema-converter-faile
     explanation: "Help, the manifest, and completion read what an input accepts from the JSON Schema its validator publishes. A converter that throws or returns anything but a plain object publishes no shape, so a distributed build reads the input's schema as null.",
     headline: 'Schema converter failed',
 });
-export { booleanOptionMultiple, booleanOptionValueRule, defaultShape, envName, envOnArgument, envOnMultiple, flagNotBoolean, globalOptionAfterCommand, globalPresenceRule, invalidDefault, notAValidator, omissionAlreadyDecided, nameSharedAcrossKinds, omissionWithoutValidator, optionDeclaredTwice, optionPolarity, optionType, polarityOnString, requiredWithDefault, schemaConverterFailed, shortAlias, shortOnlyBothPolarities, shortOnlyWithoutShort, spellingTaken, variableBoundTwice, };
+export { booleanOptionMultiple, booleanOptionValueRule, defaultDepth, defaultLevels, defaultShape, envName, envOnArgument, envOnMultiple, flagNotBoolean, globalOptionAfterCommand, globalPresenceRule, invalidDefault, notAValidator, omissionAlreadyDecided, nameSharedAcrossKinds, omissionWithoutValidator, optionDeclaredTwice, optionPolarity, optionType, polarityOnString, requiredWithDefault, schemaConverterFailed, shortAlias, shortOnlyBothPolarities, shortOnlyWithoutShort, spellingTaken, variableBoundTwice, };

package/dist/inspect.d.ts

@@ -110,14 +110,6 @@ interface CommandGraph {
     readonly globals: readonly OptionNode[];
     readonly root: CommandNode;
 }
-/**
- * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
- * consumer cannot reach the source through the copy, and a later call reports the value again.
- * Primitives and library objects, such as a class instance or a `Date` a schema produced, are
- * reported as they are, because core cannot copy them meaningfully. The graph reads it for a
- * declared value and the chain reads it for the request one middleware holds.
- */
-export declare function snapshot(value: unknown): unknown;
 /** The declared result as plain data, or `null` on a Command that declares none. */
 declare function resultNode(result: DeclaredResult | undefined): ResultNode | null;
 /**

package/dist/inspect.js

@@ -1,7 +1,7 @@
 import { asSentence, DeclarationError, InternalError, reasonOf } from './errors.js';
 import { partOf, siteFinding } from './facts.js';
 import { schemaConverterFailed } from './input-rules.js';
-import { isPlainObject } from './plain.js';
+import { isPlainObject, snapshotRecord } from './plain.js';
 import { foreignGraph, foreignGraphCorrection } from './rules.js';
 import { declaringSite, inputPlace, validatesOmission } from './validation.js';
 /** A declaration that carries no extension value publishes one shared, empty frozen record. */
@@ -21,28 +21,12 @@ function spellingsOf(table, name) {
     return spellings;
 }
 /**
- * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
- * consumer cannot reach the source through the copy, and a later call reports the value again.
- * Primitives and library objects, such as a class instance or a `Date` a schema produced, are
- * reported as they are, because core cannot copy them meaningfully. The graph reads it for a
- * declared value and the chain reads it for the request one middleware holds.
+ * A declared default is wrapped, so `default: undefined` reads apart from no default at all. The
+ * value is the frozen snapshot the declaring call took, the one a run validates, so inspection
+ * copies nothing and every reader sees one value.
  */
-export function snapshot(value) {
-    if (Array.isArray(value)) {
-        return Object.freeze(value.map((entry) => snapshot(entry)));
-    }
-    if (isPlainObject(value)) {
-        return snapshotRecord(value);
-    }
-    return value;
-}
-/** The snapshot of one plain object, under the record type the caller already established. */
-function snapshotRecord(value) {
-    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
-}
-/** A declared default is wrapped, so `default: undefined` reads apart from no default at all. */
 function declaredDefault(config) {
-    return 'default' in config ? Object.freeze({ value: snapshot(config.default) }) : undefined;
+    return 'default' in config ? Object.freeze({ value: config.default }) : undefined;
 }
 /**
  * The JSON Schema draft build asks every converter for, with no library options. Every converter

package/dist/options.d.ts

@@ -35,6 +35,13 @@ type OptionSpelling = OptionForm & {
 export declare function spellingMark(site: InputSite, role: SpellingRole): string;
 /** The declared name answers the declared-name rule an argument's name answers. */
 export declare function checkOptionName(name: unknown, site: InputSite): void;
+/** Whether a declared short alias is one ASCII letter, the rule every short spelling answers. */
+export declare function isShortAlias(short: unknown): boolean;
+/** The sentence and correction of the short-alias fault for the option `subject` names. */
+export declare function shortAliasText(subject: string): {
+    sentence: string;
+    correction: string;
+};
 /**
  * The scope one table compiles: the phrase a repeated name names it by, and where each of its
  * options was declared, which every fault's findings rebuild.

package/dist/options.js

@@ -36,15 +36,21 @@ export function checkOptionName(name, site) {
         });
     }
 }
+/** Whether a declared short alias is one ASCII letter, the rule every short spelling answers. */
+export function isShortAlias(short) {
+    return typeof short === 'string' && /^[A-Za-z]$/u.test(short);
+}
+/** The sentence and correction of the short-alias fault for the option `subject` names. */
+export function shortAliasText(subject) {
+    return {
+        correction: 'Supply one ASCII letter.',
+        sentence: `${subject} declares a short alias that is not one ASCII letter.`,
+    };
+}
 /** The short alias, and `shortOnly`, which leaves the option that alias alone. */
 function checkShortForms(config, site, subject) {
-    if (config.short !== undefined &&
-        (typeof config.short !== 'string' || !/^[A-Za-z]$/u.test(config.short))) {
-        throw factFault(shortAlias, site, {
-            correction: 'Supply one ASCII letter.',
-            fact: 'short',
-            sentence: `${subject} declares a short alias that is not one ASCII letter.`,
-        });
+    if (config.short !== undefined && !isShortAlias(config.short)) {
+        throw factFault(shortAlias, site, { ...shortAliasText(subject), fact: 'short' });
     }
     if (config.shortOnly !== undefined && typeof config.shortOnly !== 'boolean') {
         throw flagFault(site, 'shortOnly');

package/dist/plain.d.ts

@@ -1,6 +1,56 @@
+/**
+ * Runs one declaring call with verdicts of its own, dropped when it returns or throws. A call made
+ * inside another, such as a `plugin()` a getter makes, is part of the outer read and shares them.
+ */
+declare function declaring<Result>(call: () => Result): Result;
 /**
  * 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.
+ * object, and `snapshot` reads it to copy a declared value faithfully. A value a declaring call
+ * already judged answers with that verdict.
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Whether a declaring call reads one part of a declaration as plain data, decided once: the first
+ * verdict is recorded, and `isPlainObject` answers with it for the same value from then on.
+ */
+declare function decidePlain(value: unknown): value is Record<string, unknown>;
+/**
+ * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
+ * consumer cannot reach the source through the copy. A value that holds itself is copied with the
+ * same cycle, because each source object is judged and copied once and every path to it reaches
+ * that copy. Primitives and library objects, such as a class instance or a `Date` a schema
+ * produced, are reported as they are, because core cannot copy them meaningfully. Build reads it
+ * for a converter's schema, and the chain for the request one middleware holds.
+ */
+declare function snapshot(value: unknown): unknown;
+/** The snapshot of one plain object, under the record type the caller already established. */
+declare function snapshotRecord(value: Record<string, unknown>): Readonly<Record<string, unknown>>;
+/**
+ * The snapshot `snapshot` takes, of a value whose paths may hold at most `levels` arrays and plain
+ * objects, the value itself included. Every path through a container the value holds twice counts
+ * it, and a value that holds itself has a path without end. Either kind of path past `levels`
+ * throws `NestedTooDeepError` before the walk goes deeper than `levels`, so neither the walk nor
+ * any later reader of the copy goes deeper either. A declaring call reads it for a declared default.
+ */
+declare function boundedSnapshot(value: unknown, levels: number): unknown;
+/** What `boundedSnapshot` throws for a value with a path longer than its limit. */
+declare class NestedTooDeepError extends Error {
+    name: string;
+}
+/**
+ * A copy of every own string key of one object, enumerable or not, each described once and read
+ * once, in the order the object lists its keys. `entering` hears each key before it is read, so a
+ * read that throws can name it. A symbol key is not copied, because no declaration declares one.
+ */
+declare function copyOwnKeys(declared: object, entering?: (key: string) => void): Record<string, unknown>;
+/**
+ * The copy of one part of a declaration that `decidePlain` judges plain, by `copyOwnKeys`. Any other
+ * value is answered as it is, so the rule for its slot reports it.
  */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function shallowRecord(value: unknown): unknown;
+/** A copy of one list's entries by `fillList`. Each entry is what its factory built, so it is kept. */
+declare function copyList<Entry>(list: readonly Entry[]): Entry[];
+/** The copy of a value that is a list, by `copyList`. Any other value is answered as it is. */
+declare function shallowList(value: unknown): unknown;
+export { boundedSnapshot, copyList, copyOwnKeys, decidePlain, declaring, isPlainObject, NestedTooDeepError, shallowList, shallowRecord, snapshot, snapshotRecord, };

package/dist/plain.js

@@ -1,12 +1,238 @@
+/**
+ * The verdict the declaring call under way reached on each part of a declaration it captured, so
+ * every later rule of that call reads that one verdict and never asks the part's prototype again.
+ * No call is under way outside `declaring`, so a run and every later call judge afresh.
+ */
+let verdicts = undefined;
+/**
+ * Runs one declaring call with verdicts of its own, dropped when it returns or throws. A call made
+ * inside another, such as a `plugin()` a getter makes, is part of the outer read and shares them.
+ */
+function declaring(call) {
+    if (verdicts !== undefined) {
+        return call();
+    }
+    verdicts = new WeakMap();
+    try {
+        return call();
+    }
+    finally {
+        verdicts = undefined;
+    }
+}
 /**
  * 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.
+ * object, and `snapshot` reads it to copy a declared value faithfully. A value a declaring call
+ * already judged answers with that verdict.
  */
-export function isPlainObject(value) {
+function isPlainObject(value) {
     if (value === null || typeof value !== 'object') {
         return false;
     }
+    return verdicts?.get(value) ?? hasPlainPrototype(value);
+}
+/** Whether one object's prototype, read once, is `Object.prototype` or `null`. */
+function hasPlainPrototype(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
+/**
+ * Whether a declaring call reads one part of a declaration as plain data, decided once: the first
+ * verdict is recorded, and `isPlainObject` answers with it for the same value from then on.
+ */
+function decidePlain(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const known = verdicts?.get(value);
+    if (known !== undefined) {
+        return known;
+    }
+    const verdict = hasPlainPrototype(value);
+    verdicts?.set(value, verdict);
+    return verdict;
+}
+/**
+ * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
+ * consumer cannot reach the source through the copy. A value that holds itself is copied with the
+ * same cycle, because each source object is judged and copied once and every path to it reaches
+ * that copy. Primitives and library objects, such as a class instance or a `Date` a schema
+ * produced, are reported as they are, because core cannot copy them meaningfully. Build reads it
+ * for a converter's schema, and the chain for the request one middleware holds.
+ */
+function snapshot(value) {
+    return copied(value, copying(Number.POSITIVE_INFINITY), 1);
+}
+/** The snapshot of one plain object, under the record type the caller already established. */
+function snapshotRecord(value) {
+    return copiedRecord(value, copying(Number.POSITIVE_INFINITY), 1);
+}
+/**
+ * The snapshot `snapshot` takes, of a value whose paths may hold at most `levels` arrays and plain
+ * objects, the value itself included. Every path through a container the value holds twice counts
+ * it, and a value that holds itself has a path without end. Either kind of path past `levels`
+ * throws `NestedTooDeepError` before the walk goes deeper than `levels`, so neither the walk nor
+ * any later reader of the copy goes deeper either. A declaring call reads it for a declared default.
+ */
+function boundedSnapshot(value, levels) {
+    return copied(value, copying(levels), 1);
+}
+/** What `boundedSnapshot` throws for a value with a path longer than its limit. */
+class NestedTooDeepError extends Error {
+    name = 'NestedTooDeepError';
+}
+/** A snapshot about to start, whose paths may hold at most `levels` containers. */
+function copying(levels) {
+    return { copies: new Map(), heights: new Map(), levels };
+}
+/**
+ * One value of a snapshot in progress, reached at `level`, where the value itself is level 1. An
+ * object the walk reached already answers as it did then, so its prototype is read once.
+ */
+function copied(value, walk, level) {
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    if (walk.copies.has(value)) {
+        return walk.copies.get(value);
+    }
+    if (Array.isArray(value)) {
+        return copiedList(value, walk, level);
+    }
+    if (isPlainObject(value)) {
+        return copiedRecord(value, walk, level);
+    }
+    return kept(value, walk);
+}
+/** An object core cannot copy, kept as it is, which every later reach answers with unread. */
+function kept(value, walk) {
+    walk.copies.set(value, value);
+    walk.heights.set(value, 0);
+    return value;
+}
+/**
+ * How many containers the longest path from one entry holds, once the walk has copied the entry of
+ * a container reached at `level`. A container the walk filled counts every container below it,
+ * even one it reached first by a shorter path. A container still being filled is one this entry
+ * leads back into, so the path through it has no end, and any other value holds none.
+ */
+function checkedHeight(entry, walk, level) {
+    const height = typeof entry === 'object' && entry !== null
+        ? (walk.heights.get(entry) ?? Number.POSITIVE_INFINITY)
+        : 0;
+    if (level + height > walk.levels) {
+        throw new NestedTooDeepError();
+    }
+    return height;
+}
+/**
+ * The copier of each entry of one container reached at `level`, which counts how many containers
+ * the longest path from that container holds, itself included.
+ */
+function entryCopier(walk, level) {
+    let height = 1;
+    return {
+        copy: (entry) => {
+            const copy = copied(entry, walk, level + 1);
+            height = Math.max(height, checkedHeight(entry, walk, level) + 1);
+            return copy;
+        },
+        height: () => height,
+    };
+}
+/** Throws `NestedTooDeepError` for a container the walk first reaches past its limit. */
+function checkLevel(walk, level) {
+    if (level > walk.levels) {
+        throw new NestedTooDeepError();
+    }
+}
+/**
+ * One array's copy. It joins `copies` before its entries are read, so an entry that leads back to
+ * it reaches the copy, and it is frozen once it is filled. A hole stays a hole.
+ */
+function copiedList(list, walk, level) {
+    checkLevel(walk, level);
+    const copy = [];
+    walk.copies.set(list, copy);
+    const entries = entryCopier(walk, level);
+    fillList(copy, list, entries.copy);
+    walk.heights.set(list, entries.height());
+    return Object.freeze(copy);
+}
+/**
+ * One plain object's copy on `Object.prototype`, filled and frozen as an array's copy is. Each key
+ * is defined as an own data property, so a key of `__proto__` is stored under that name.
+ */
+function copiedRecord(record, walk, level) {
+    checkLevel(walk, level);
+    const copy = {};
+    walk.copies.set(record, copy);
+    const entries = entryCopier(walk, level);
+    for (const [key, entry] of Object.entries(record)) {
+        defineEntry(copy, key, entries.copy(entry));
+    }
+    walk.heights.set(record, entries.height());
+    return Object.freeze(copy);
+}
+/** Defines one key as an own data property, so a key of `__proto__` is stored under that name. */
+function defineEntry(target, key, value) {
+    Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true,
+    });
+}
+/**
+ * A copy of every own string key of one object, enumerable or not, each described once and read
+ * once, in the order the object lists its keys. `entering` hears each key before it is read, so a
+ * read that throws can name it. A symbol key is not copied, because no declaration declares one.
+ */
+function copyOwnKeys(declared, entering = () => undefined) {
+    const copy = {};
+    for (const key of Reflect.ownKeys(declared)) {
+        if (typeof key === 'string') {
+            entering(key);
+            if (Reflect.getOwnPropertyDescriptor(declared, key) !== undefined) {
+                defineEntry(copy, key, Reflect.get(declared, key));
+            }
+        }
+    }
+    return copy;
+}
+/**
+ * The copy of one part of a declaration that `decidePlain` judges plain, by `copyOwnKeys`. Any other
+ * value is answered as it is, so the rule for its slot reports it.
+ */
+function shallowRecord(value) {
+    return decidePlain(value) ? copyOwnKeys(value) : value;
+}
+/**
+ * Fills `copy` with what `convert` makes of each entry of `list`, read by its length once and then
+ * index by index, so none of the list's own methods runs. A hole stays a hole.
+ */
+function fillList(copy, list, convert) {
+    const { length } = list;
+    for (let index = 0; index < length; index += 1) {
+        if (Object.hasOwn(list, index)) {
+            defineEntry(copy, index, convert(list[index]));
+        }
+    }
+    copy.length = length;
+}
+/** A copy of one list's entries by `fillList`. Each entry is what its factory built, so it is kept. */
+function copyList(list) {
+    const copy = [];
+    fillList(copy, list, (entry) => entry);
+    return copy;
+}
+/** The copy of a value that is a list, by `copyList`. Any other value is answered as it is. */
+function shallowList(value) {
+    if (!Array.isArray(value)) {
+        return value;
+    }
+    const list = value;
+    return copyList(list);
+}
+export { boundedSnapshot, copyList, copyOwnKeys, decidePlain, declaring, isPlainObject, NestedTooDeepError, shallowList, shallowRecord, snapshot, snapshotRecord, };

package/dist/plugin-rules.d.ts

@@ -5,6 +5,12 @@ declare const notAList: import("./diagnostic-text.js").DiagnosticRule;
  * that is not an object.
  */
 declare const notAnObject: import("./diagnostic-text.js").DiagnosticRule;
+/**
+ * A declaration whose read throws while core takes its one copy, such as a getter that throws or a
+ * proxy whose trap throws: the config of an argument or option, a plugin's definition and each of
+ * its option declarations, and the options of a Command or of the Application.
+ */
+declare const unreadableDeclaration: import("./diagnostic-text.js").DiagnosticRule;
 /** A list entry that its factory did not build, such as a hand-made plugin or translation. */
 declare const foreignValue: import("./diagnostic-text.js").DiagnosticRule;
 /** One plugin identity installed twice. */
@@ -59,4 +65,4 @@ declare const renderingPolicyRule: import("./diagnostic-text.js").DiagnosticRule
 declare const themeMapping: import("./diagnostic-text.js").DiagnosticRule;
 /** A theme name that a built-in style member already holds. */
 declare const themeNameTaken: import("./diagnostic-text.js").DiagnosticRule;
-export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, pluginOptionRule, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, };
+export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, pluginOptionRule, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, unreadableDeclaration, };

package/dist/plugin-rules.js

@@ -14,9 +14,18 @@ const notAList = registerRule('@loomcli/core/not-a-list', {
  * that is not an object.
  */
 const notAnObject = registerRule('@loomcli/core/not-an-object', {
-    explanation: "Core reads the options of a Command and of the Application, a plugin's definition, its options record, each of its option declarations, its middleware, its source, and the config of an argument or option by their keys. A value of any other kind has no keys to read.",
+    explanation: "Core reads the options of a Command and of the Application, a plugin's definition, its options record, each of its option declarations, its middleware, its source, the config of an argument or option, and the settings a plugin factory takes by their keys. A value of any other kind has no keys to read.",
     headline: 'Not an object',
 });
+/**
+ * A declaration whose read throws while core takes its one copy, such as a getter that throws or a
+ * proxy whose trap throws: the config of an argument or option, a plugin's definition and each of
+ * its option declarations, and the options of a Command or of the Application.
+ */
+const unreadableDeclaration = registerRule('@loomcli/core/unreadable-declaration', {
+    explanation: 'Core reads a declaration by its keys, and each list in it by index, once, at the call that declares it, and checks and records the copy it takes. A read that throws, such as a throwing getter or proxy trap, leaves core nothing to check or record.',
+    headline: 'Declaration could not be read',
+});
 /** A list entry that its factory did not build, such as a hand-made plugin or translation. */
 const foreignValue = registerRule('@loomcli/core/foreign-value', {
     explanation: 'Core reads a plugin, an extension, an extension value, a declared view, a view override, and a translation through facts its factory recorded when it built the value. Any other value carries none, even one of the same shape.',
@@ -152,4 +161,4 @@ const themeNameTaken = registerRule('@loomcli/core/theme-name-taken', {
     explanation: 'Each theme name becomes a member of the style object beside the built-in members, so a name a built-in already holds would hide it.',
     headline: 'Theme name taken',
 });
-export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, pluginOptionRule, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, };
+export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, pluginOptionRule, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, unreadableDeclaration, };

package/dist/plugin-settings.d.ts

@@ -0,0 +1,18 @@
+/** The plugin factory whose settings `checkShortSetting` judges, and the option `short` spells. */
+interface ShortSettingDeclarer {
+    /** The plugin's identity, which the sentence and each finding's note name. */
+    readonly plugin: string;
+    /** The factory's name, the call each finding quotes, such as `'format'`. */
+    readonly call: string;
+    /** The name of the option the setting gives a short spelling, such as `'format'`. */
+    readonly option: string;
+}
+/**
+ * Judges a plugin factory's settings at its call, under core's own rules: settings that are neither
+ * undefined nor a plain object are the not-an-object fault, and a `short` that is not one ASCII
+ * letter is the short-alias fault every option's short spelling answers, in the same sentence. Each
+ * finding quotes the factory's call and names the plugin, so a first-party plugin that takes a short
+ * spelling as `{ short }` reports it where the author wrote it.
+ */
+export declare function checkShortSetting(settings: unknown, declarer: ShortSettingDeclarer): void;
+export {};

package/dist/plugin-settings.js

@@ -0,0 +1,38 @@
+import { DeclarationError, quoted } from './errors.js';
+import { declarerNote } from './facts.js';
+import { shortAlias } from './input-rules.js';
+import { shortAliasText, isShortAlias } from './options.js';
+import { isPlainObject } from './plain.js';
+import { notAnObject } from './plugin-rules.js';
+/**
+ * Judges a plugin factory's settings at its call, under core's own rules: settings that are neither
+ * undefined nor a plain object are the not-an-object fault, and a `short` that is not one ASCII
+ * letter is the short-alias fault every option's short spelling answers, in the same sentence. Each
+ * finding quotes the factory's call and names the plugin, so a first-party plugin that takes a short
+ * spelling as `{ short }` reports it where the author wrote it.
+ */
+export function checkShortSetting(settings, declarer) {
+    if (settings === undefined) {
+        return;
+    }
+    const { call, option, plugin } = declarer;
+    const finding = (mark) => ({
+        arguments: [settings],
+        call,
+        mark,
+        note: declarerNote(plugin),
+    });
+    if (!isPlainObject(settings)) {
+        throw new DeclarationError(notAnObject, {
+            correction: 'Supply a settings object, or omit the settings.',
+            findings: [finding('0')],
+            sentence: `Plugin ${quoted(plugin)} declares settings that are not an object.`,
+        });
+    }
+    if (settings.short !== undefined && !isShortAlias(settings.short)) {
+        throw new DeclarationError(shortAlias, {
+            ...shortAliasText(`Option ${quoted(option)}`),
+            findings: [finding('0.short')],
+        });
+    }
+}