@loomcli/core 0.6.0 → 0.7.0

package/dist/validation.d.ts

@@ -1,5 +1,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { CaptureFaults } from './capture.js';
 import type { Finding } from './diagnostic-text.js';
+import { DeclarationError } from './errors.js';
 import type { InputSite } from './facts.js';
 import type { OptionValues } from './options.js';
 import type { ArgumentConfig, ArgumentValue, Host, OptionConfig, OptionValue } from './types.js';
@@ -75,22 +77,36 @@ declare class ValidatedInputs {
     read(input: InputDeclaration): unknown;
 }
 export type { ValidatedInputs };
+/** The faults a config's capture raises: those of every capture, and a default nested too deep. */
+export interface ConfigFaults extends CaptureFaults {
+    /** The default holds a path deeper than `defaultLevels`; the finding prints it elided. */
+    readonly tooDeep: () => DeclarationError;
+}
 /**
- * The one check every `argument()`, `option()`, and `globalOption()` call makes before it reads its
- * config, so a call in JavaScript that supplies none, or a value of another kind, reports a
- * declaration fault and not a TypeError. `place` is where the call sits.
+ * Authoring's one read of a config, through `captureDeclaration`: the prototype verdict, the copy of
+ * every own string key, the copy of its `extensions` list, and the snapshot of its default, inside
+ * one try. Every later check, the registry entry, and every sentence read the copy and never the
+ * author's object again, so a getter runs once and the caller's later changes reach nothing. The
+ * default is copied and frozen to `defaultLevels` levels, cycles included, and that copy is the
+ * value the graph publishes and a run validates; every other property is captured as declared,
+ * because core clones no library object. A read that throws, from a getter or a proxy trap, is the
+ * unreadable fault, named by the key it threw in, a default nested deeper is the too-deep fault,
+ * and a value that is not a plain object is the not-an-object fault.
  */
-export declare function checkInputConfig(declared: {
-    readonly config: unknown;
-    readonly kind: InputDeclaration['kind'];
-    readonly name: string;
-}, place: InputPlace): void;
+export declare function captureConfig<Config extends ArgumentConfig | OptionConfig>(config: Config, faults: ConfigFaults): Config;
+/** The fault of a default nested deeper than `defaultLevels`, declared by `subject`. */
+export declare function defaultDepthFault(subject: string, findings: readonly Finding[]): DeclarationError;
 /**
- * Authoring's snapshot of one config. An array default is the one declared value core hands to an
- * action as its own value, so the declaration keeps a copy and the caller keeps its array. Every
- * other property is captured as declared, because core clones no library object.
+ * The config every `argument()`, `option()`, and `globalOption()` call, and every input a lifecycle
+ * hook declares, reads through `captureConfig`. A call in JavaScript that supplies none, or a value
+ * of another kind, reports a declaration fault and not a TypeError, and so does a config whose read
+ * throws. Each fault marks the config on the call at `place`.
  */
-export declare function captureConfig<Config extends ArgumentConfig | OptionConfig>(config: Config): Config;
+export declare function captureInputConfig<Config extends ArgumentConfig | OptionConfig>(declared: {
+    readonly config: Config;
+    readonly kind: InputDeclaration['kind'];
+    readonly name: string;
+}, place: InputPlace): Config;
 /**
  * A declaration error names the declaration, because the author reads the declaration to fix it.
  * An argument declares and reads under one name, so the two namings differ for options alone.
@@ -112,6 +128,11 @@ export declare function inputPlace(input: InputDeclaration, scope: {
  * is the sentence's name for the input.
  */
 export declare function declaringSite(input: InputDeclaration, place: InputPlace, subject?: string): InputSite;
+/**
+ * One input's site with its config printed elided, for a fault judged before the config is read,
+ * such as an invalid name, so the fault reads none of the config.
+ */
+export declare function configUnread(site: InputSite): InputSite;
 /**
  * The declaration flag that sends an omitted value to its own validator. Every declaration reads it
  * here, and the declaration rules below reject it wherever another rule already decides absence.

package/dist/validation.js

@@ -1,10 +1,12 @@
+import { captureDeclaration, elidedRead, unreadableFault } from './capture.js';
 import { schemaOptions } from './context.js';
 import { escapeControlCharacters } from './controls.js';
+import { elided, spelled } from './diagnostic-text.js';
 import { asSentence, DeclarationError, InputError, quoted, reasonOf } from './errors.js';
 import { callSite, factFault, flagFault, partOf, siteFinding } from './facts.js';
-import { booleanOptionValueRule, defaultShape, invalidDefault, notAValidator, omissionAlreadyDecided, omissionWithoutValidator, requiredWithDefault, } from './input-rules.js';
+import { booleanOptionValueRule, defaultDepth, defaultLevels, defaultShape, invalidDefault, notAValidator, omissionAlreadyDecided, omissionWithoutValidator, requiredWithDefault, } from './input-rules.js';
 import { booleanValue } from './options.js';
-import { isPlainObject } from './plain.js';
+import { boundedSnapshot, NestedTooDeepError, shallowList } from './plain.js';
 import { notAnObject } from './plugin-rules.js';
 import { validatorFailed } from './rules.js';
 /** Every declaration in validation order: the globals first, then the reading Command's own. */
@@ -53,34 +55,65 @@ class ValidatedInputs {
     }
 }
 /**
- * The one check every `argument()`, `option()`, and `globalOption()` call makes before it reads its
- * config, so a call in JavaScript that supplies none, or a value of another kind, reports a
- * declaration fault and not a TypeError. `place` is where the call sits.
+ * Authoring's one read of a config, through `captureDeclaration`: the prototype verdict, the copy of
+ * every own string key, the copy of its `extensions` list, and the snapshot of its default, inside
+ * one try. Every later check, the registry entry, and every sentence read the copy and never the
+ * author's object again, so a getter runs once and the caller's later changes reach nothing. The
+ * default is copied and frozen to `defaultLevels` levels, cycles included, and that copy is the
+ * value the graph publishes and a run validates; every other property is captured as declared,
+ * because core clones no library object. A read that throws, from a getter or a proxy trap, is the
+ * unreadable fault, named by the key it threw in, a default nested deeper is the too-deep fault,
+ * and a value that is not a plain object is the not-an-object fault.
  */
-export function checkInputConfig(declared, place) {
-    const { config, kind, name } = declared;
-    if (isPlainObject(config)) {
-        return;
-    }
-    const subject = kind === 'argument' ? 'Argument' : 'Option';
-    const site = callSite(`${subject} ${quoted(name)}`, {
-        arguments: [name, config],
-        ...place,
+export function captureConfig(config, faults) {
+    const { notAnObject: notAnObjectFault, tooDeep, unreadable } = faults;
+    return captureDeclaration(config, (copy, read) => {
+        // Presence is the key, so a declared `default: undefined` stays a default.
+        read.nested(copy, 'default', (value) => boundedSnapshot(value, defaultLevels));
+        read.nested(copy, 'extensions', shallowList);
+    }, {
+        notAnObject: notAnObjectFault,
+        unreadable: (thrown, slot) => thrown instanceof NestedTooDeepError ? tooDeep() : unreadable(thrown, slot),
     });
-    throw new DeclarationError(notAnObject, {
-        correction: `Supply ${kind === 'argument' ? 'an argument' : 'an option'} config object, such as ${kind === 'argument' ? '{}' : "{ type: 'string' }"}.`,
-        findings: [siteFinding(site, '1')],
-        sentence: `${site.subject} declares a config that is not an object.`,
+}
+/** The fault of a default nested deeper than `defaultLevels`, declared by `subject`. */
+export function defaultDepthFault(subject, findings) {
+    return new DeclarationError(defaultDepth, {
+        correction: `Nest a default at most ${String(defaultLevels)} levels deep.`,
+        findings,
+        sentence: `${subject} default nests deeper than ${String(defaultLevels)} levels.`,
     });
 }
 /**
- * Authoring's snapshot of one config. An array default is the one declared value core hands to an
- * action as its own value, so the declaration keeps a copy and the caller keeps its array. Every
- * other property is captured as declared, because core clones no library object.
+ * The config every `argument()`, `option()`, and `globalOption()` call, and every input a lifecycle
+ * hook declares, reads through `captureConfig`. A call in JavaScript that supplies none, or a value
+ * of another kind, reports a declaration fault and not a TypeError, and so does a config whose read
+ * throws. Each fault marks the config on the call at `place`.
  */
-export function captureConfig(config) {
-    const value = config.default;
-    return Array.isArray(value) ? { ...config, default: [...value] } : { ...config };
+export function captureInputConfig(declared, place) {
+    const { config, kind, name } = declared;
+    const subject = `${kind === 'argument' ? 'Argument' : 'Option'} ${quoted(name)}`;
+    // The finding marks the config, or one key inside it, which `shown` stands for when the call prints.
+    const findings = (shown, keys = []) => [
+        siteFinding(callSite(subject, { arguments: [name, shown], ...place }), ['1', ...keys].join('.')),
+    ];
+    return captureConfig(config, {
+        notAnObject: () => new DeclarationError(notAnObject, {
+            correction: `Supply ${kind === 'argument' ? 'an argument' : 'an option'} config object, such as ${kind === 'argument' ? '{}' : "{ type: 'string' }"}.`,
+            findings: findings(config),
+            sentence: `${subject} declares a config that is not an object.`,
+        }),
+        // The default's walk stopped at the limit, so the finding prints it elided.
+        tooDeep: () => {
+            const { keys, shown } = elidedRead('default');
+            return defaultDepthFault(subject, findings(shown, keys));
+        },
+        // A part whose read threw is never read again, so the finding prints it elided.
+        unreadable: (thrown, slot) => {
+            const { keys, shown } = elidedRead(slot);
+            return unreadableFault({ declared: 'config', findings: findings(shown, keys), subject }, thrown);
+        },
+    });
 }
 /**
  * A declaration error names the declaration, because the author reads the declaration to fix it.
@@ -106,6 +139,15 @@ export function inputPlace(input, scope) {
 export function declaringSite(input, place, subject = declarationSubject(input)) {
     return callSite(subject, { arguments: [input.name, input.config], ...place });
 }
+/**
+ * One input's site with its config printed elided, for a fault judged before the config is read,
+ * such as an invalid name, so the fault reads none of the config.
+ */
+export function configUnread(site) {
+    const [name, config] = site.declaration.arguments;
+    const shown = config === undefined ? [name] : [name, spelled(elided)];
+    return { ...site, declaration: { ...site.declaration, arguments: shown } };
+}
 /**
  * The token an operator would type for one declaration: `--file` for an option, `-F` when the
  * option declares `shortOnly`, and the declared name for an argument. Every input diagnostic and
@@ -463,13 +505,16 @@ export async function prepareInputs(inputs, host, places) {
     return defaults;
 }
 /**
- * An array default reaches the action as its own copy, so an action that mutates its array
+ * An array default reaches the action as its own mutable copy, so an action that mutates its array
  * rewrites neither the declaration nor the next invocation. One prepared default serves every
- * invocation of a run, and an unvalidated default is the declared array itself, so each read
- * copies it. Every other output passes through unchanged.
+ * invocation of a run, and an unvalidated default is the frozen snapshot the declaring call took,
+ * so each read copies it. The copy keeps a hole where the default has one, as the graph's does.
+ * Every other output passes through unchanged.
  */
 function freshDefault(value) {
-    return Array.isArray(value) ? [...value] : value;
+    // A spread reads a hole as `undefined`, and `slice` keeps it.
+    // oxlint-disable-next-line unicorn/prefer-spread
+    return Array.isArray(value) ? value.slice() : value;
 }
 /**
  * The raw tokens of one invocation, keyed by declared name. Every declared input of the routed

package/dist/view.d.ts

@@ -56,7 +56,7 @@ interface FailureViewContext extends ViewContext {
 interface FailureView<Failure extends LoomError> {
     render: (failure: Readonly<Failure>, context: FailureViewContext) => string;
     /** A failure view has one shape, as a view does. */
-    row?: never;
+    row?: undefined;
 }
 /**
  * One stored view function, with the data type and the context erased. A registry holds one entry
@@ -125,17 +125,22 @@ declare class OverrideDeclaration {
 type ViewOverride = Pick<OverrideDeclaration, typeof viewOverride>;
 /** What a plugin's own list holds: the views it declares and the overrides it makes. */
 type ViewContribution = AnyDeclaredView | ViewOverride;
+/** Every value an override can key on: a declared view of either shape or a failure class. */
+type AnyOverrideKey = AnyDeclaredView | FailureClass<LoomError>;
 /**
- * One override pairing a key with a replacement view. Under a declared view the replacement is
- * typed from the view's data; under a failure class it is typed from the class's instances, which
- * is the typed path for a class-keyed list, because an array literal cannot carry a different type
- * parameter per element.
+ * The replacement view one key takes, derived from the key alone. The declared-view branches come
+ * first, so a declared view is never read as a failure class. Each check is wrapped in a tuple so a
+ * union key is not split into a union of replacements that each answer only one of its members.
  */
-declare function override<Data>(key: DeclaredView<Data>, replacement: NoInfer<View<Data>>): ViewOverride;
-declare function override<Row>(key: DeclaredRowView<Row>, replacement: NoInfer<RowView<Row>>): ViewOverride;
-declare function override<Failure extends LoomError>(key: FailureClass<Failure> & {
-    readonly [declaredView]?: never;
-}, replacement: NoInfer<FailureView<Failure>>): ViewOverride;
+type ReplacementView<Key> = [Key] extends [DeclaredView<infer Data>] ? View<Data> : [Key] extends [DeclaredRowView<infer Row>] ? RowView<Row> : [Key] extends [FailureClass<infer Failure>] ? FailureView<Failure> : never;
+/**
+ * One override pairing a key with a replacement view. The replacement's type is derived from the
+ * key: under a declared view it is typed from the view's data, and under a failure class from the
+ * class's instances, which is the typed path for a class-keyed list, because an array literal cannot
+ * carry a different type parameter per element. One signature serves every key, so a mismatch
+ * names the replacement's type against the one the key expects.
+ */
+declare function override<Key extends AnyOverrideKey>(key: Key, replacement: NoInfer<ReplacementView<Key>>): ViewOverride;
 /** One contributor's overrides, read once per build and consulted in contributor order. */
 interface ViewContributions {
     failures: Map<unknown, StoredView>;
@@ -210,5 +215,5 @@ type FailureReport = {
  * carries the same default text without hints, which the plain fallback path writes.
  */
 declare function describeFailure(registry: ViewRegistry, failure: LoomError, context: FailureViewContext): FailureReport;
-export type { AnyDeclaredView, DeclaredRowView, DeclaredView, DeclaredViewBrand, FailureClass, FailureReport, FailureView, FailureViewContext, ResolvedRowView, ViewContribution, ViewContributions, ViewSubject, ViewIdentities, ViewOverride, ViewRegistry, ViewShape, };
+export type { AnyDeclaredView, AnyOverrideKey, DeclaredRowView, DeclaredView, DeclaredViewBrand, FailureClass, FailureReport, FailureView, FailureViewContext, ReplacementView, ResolvedRowView, ViewContribution, ViewContributions, ViewSubject, ViewIdentities, ViewOverride, ViewRegistry, ViewShape, };
 export { buildViews, describeFailure, override, resolveRowView, resolveView, shapeOf, view, viewIdentities, };

package/dist/view.js

@@ -84,12 +84,21 @@ class OverrideDeclaration {
         Object.freeze(this);
     }
 }
+/**
+ * One override pairing a key with a replacement view. The replacement's type is derived from the
+ * key: under a declared view it is typed from the view's data, and under a failure class from the
+ * class's instances, which is the typed path for a class-keyed list, because an array literal cannot
+ * carry a different type parameter per element. One signature serves every key, so a mismatch
+ * names the replacement's type against the one the key expects.
+ */
 function override(key, replacement) {
+    // Every replacement a key derives is a stored view, so it widens here with no check.
+    const supplied = replacement;
     const stored = {
-        head: replacement.head,
-        render: replacement.render,
-        row: replacement.row,
-        tail: replacement.tail,
+        head: supplied.head,
+        render: supplied.render,
+        row: supplied.row,
+        tail: supplied.tail,
     };
     const declared = declarations.get(key);
     if (declared) {

package/licenses/unicode-LICENSE.txt

@@ -0,0 +1,41 @@
+https://www.unicode.org/license.txt
+
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 1991-2025 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.

package/licenses/uucode-LICENSE.md

@@ -0,0 +1,35 @@
+# uucode license
+
+MIT License
+
+Copyright (c) 2026 Tim Culverhouse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Attribution
+
+This TypeScript implementation is based on the design and table strategy of
+Jacob Sandlund's `uucode`:
+
+- https://github.com/jacobsandlund/uucode
+
+The bundled Unicode Character Database files are provided by Unicode, Inc. and
+are subject to the Unicode terms of use:
+
+- https://www.unicode.org/terms_of_use.html

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@loomcli/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The Loom CLI core package. Provides the scaffolding for creating new Loom CLI applications.",
-  "license": "MIT",
+  "license": "MIT AND Unicode-3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dbtlr/loomcli.git"
   },
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    "licenses",
+    "NOTICE"
   ],
   "type": "module",
   "exports": {
@@ -19,9 +21,11 @@
     }
   },
   "dependencies": {
-    "@rockorager/uucode": "2.2.1",
     "@standard-schema/spec": "^1.1.0",
-    "@types/node": "22.20.1"
+    "@types/node": "22.20.5"
+  },
+  "devDependencies": {
+    "@rockorager/uucode": "2.2.1"
   },
   "engines": {
     "bun": ">=1.4.0",