@loomcli/core 0.5.0 → 0.7.0

package/dist/validation.d.ts

@@ -1,4 +1,8 @@
 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';
 /**
@@ -73,12 +77,62 @@ 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;
+}
+/**
+ * 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 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.
+ */
+export declare function declarationSubject(input: InputDeclaration): string;
+/** Where the call that declared one input sits: the call's name and the Command it is on. */
+export type InputPlace = Pick<Finding, 'call' | 'path'>;
+/**
+ * Where one input was declared: a global option at its `globalOption()` call, and every other input
+ * at its own `argument()` or `option()` call on the Command at `path`.
+ */
+export declare function inputPlace(input: InputDeclaration, scope: {
+    readonly global: boolean;
+    readonly path: readonly string[];
+}): InputPlace;
+/**
+ * The site of the call that declared one input at `place`, rebuilt as `call(name, config)`. Every
+ * finding for an input's own call starts from it, so each marks the call the same way. `subject`
+ * 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.
@@ -90,6 +144,11 @@ export declare function validatesOmission(input: InputDeclaration): boolean;
  * helper, so a rejected item reads alike wherever its diagnostic is written.
  */
 export declare function issuePath(issue: StandardSchemaV1.Issue): string | undefined;
+/** One declaration and where it was declared, which its faults' findings rebuild. */
+export interface SitedInput {
+    readonly input: InputDeclaration;
+    readonly site: InputSite;
+}
 /**
  * Every declaration rule that reads the declaration alone. It is synchronous, so the call that
  * declares an input applies it, and build applies it to an input a lifecycle hook declared; only
@@ -97,10 +156,13 @@ export declare function issuePath(issue: StandardSchemaV1.Issue): string | undef
  * contributor that declares under its own name, such as a plugin, supplies the subject its
  * diagnostics read with; every other caller is named by the declaration itself.
  */
-export declare function checkDeclarations(inputs: readonly InputDeclaration[], named?: string): void;
+export declare function checkDeclarations(inputs: readonly SitedInput[], named?: string): void;
+/** The call that declared one input and the Command it sits on, which a default's fault rebuilds. */
+export type InputPlaces = ReadonlyMap<InputDeclaration, InputPlace>;
 /**
  * Every declared default, validated before any token is read. The host is captured by then, so a
- * default's validator reads the same Host its action will, under the `default` phase.
+ * default's validator reads the same Host its action will, under the `default` phase. `places`
+ * says where each declaration sits, which a rejected default's finding rebuilds.
  */
-export declare function prepareInputs(inputs: ScopedInputs, host: Host): Promise<DefaultValues>;
+export declare function prepareInputs(inputs: ScopedInputs, host: Host, places: InputPlaces): Promise<DefaultValues>;
 export declare function validateValues(invocation: Invocation): Promise<ValidatedInputs>;

package/dist/validation.js

@@ -1,6 +1,14 @@
+import { captureDeclaration, elidedRead, unreadableFault } from './capture.js';
 import { schemaOptions } from './context.js';
-import { DeclarationError, InputError } from './errors.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, defaultDepth, defaultLevels, defaultShape, invalidDefault, notAValidator, omissionAlreadyDecided, omissionWithoutValidator, requiredWithDefault, } from './input-rules.js';
 import { booleanValue } from './options.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. */
 function scoped(inputs) {
     return [
@@ -47,20 +55,98 @@ class ValidatedInputs {
     }
 }
 /**
- * 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.
+ * 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 captureConfig(config) {
-    const value = config.default;
-    return Array.isArray(value) ? { ...config, default: [...value] } : { ...config };
+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),
+    });
+}
+/** 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.`,
+    });
+}
+/**
+ * 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 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.
  * An argument declares and reads under one name, so the two namings differ for options alone.
  */
-function declaredName(input) {
-    return input.kind === 'argument' ? `Argument "${input.name}"` : `Option "${input.name}"`;
+export function declarationSubject(input) {
+    return input.kind === 'argument'
+        ? `Argument ${quoted(input.name)}`
+        : `Option ${quoted(input.name)}`;
+}
+/**
+ * Where one input was declared: a global option at its `globalOption()` call, and every other input
+ * at its own `argument()` or `option()` call on the Command at `path`.
+ */
+export function inputPlace(input, scope) {
+    return scope.global ? { call: 'globalOption', path: [] } : { call: input.kind, path: scope.path };
+}
+/**
+ * The site of the call that declared one input at `place`, rebuilt as `call(name, config)`. Every
+ * finding for an input's own call starts from it, so each marks the call the same way. `subject`
+ * is the sentence's name for the input.
+ */
+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
@@ -143,61 +229,88 @@ function holdsRawDefault(input) {
  * rule that already decides absence rejects it, and the flag needs a validator to receive the
  * omission.
  */
-function checkOmissionValidation(input, subject) {
+function checkOmissionValidation(input, site, subject) {
     const { config } = input;
+    const decided = (sentence, correction) => factFault(omissionAlreadyDecided, site, { correction, fact: 'validateOmitted', sentence });
     if (config.required) {
-        throw new DeclarationError(`${subject} is required and declares validateOmitted. Remove validateOmitted or make the input optional.`);
+        throw decided(`${subject} is required and declares validateOmitted.`, 'Remove validateOmitted or make the input optional.');
     }
     if (hasDefault(input)) {
-        throw new DeclarationError(`${subject} declares a default and validateOmitted. Remove one; the default already fills an omitted value.`);
+        throw decided(`${subject} declares a default and validateOmitted.`, 'Remove one; the default already fills an omitted value.');
     }
     if (collects(input)) {
-        throw new DeclarationError(`${subject} takes several values and declares validateOmitted. Remove validateOmitted; with no values the action receives an empty array and no validator runs.`);
+        throw decided(`${subject} takes several values and declares validateOmitted.`, 'Remove validateOmitted; with no values the action receives an empty array and no validator runs.');
     }
     if (config.validate === undefined) {
-        throw new DeclarationError(`${subject} declares validateOmitted without a validator. Add validate or remove validateOmitted.`);
+        throw factFault(omissionWithoutValidator, site, {
+            correction: 'Add validate or remove validateOmitted.',
+            fact: 'validateOmitted',
+            sentence: `${subject} declares validateOmitted without a validator.`,
+        });
     }
 }
-function checkDeclaration(input, subject) {
+/** The value rules a Boolean option may not declare, in the order its diagnostic names them. */
+const valueRules = ['validate', 'default', 'required', 'validateOmitted'];
+/** Whether a `validate` value is a Standard Schema v1 object that core can call. */
+function isStandardSchema(validator) {
+    if (validator === null || (typeof validator !== 'object' && typeof validator !== 'function')) {
+        return false;
+    }
+    const props = Reflect.get(validator, '~standard');
+    return (typeof props === 'object' &&
+        props !== null &&
+        Reflect.get(props, 'version') === 1 &&
+        typeof Reflect.get(props, 'vendor') === 'string' &&
+        typeof Reflect.get(props, 'validate') === 'function');
+}
+function checkDeclaration(input, site, subject) {
     const { config } = input;
     if (input.kind === 'option' && input.config.type === 'boolean') {
-        if ('validate' in config ||
-            'default' in config ||
-            'required' in config ||
-            'validateOmitted' in config) {
-            throw new DeclarationError(`${subject} is Boolean. Remove validate, default, required, and validateOmitted; use polarity to control its absent value.`);
+        const declared = valueRules.find((key) => key in config);
+        if (declared !== undefined) {
+            throw factFault(booleanOptionValueRule, site, {
+                correction: `Remove ${declared}; use polarity to control its absent value.`,
+                fact: declared,
+                sentence: `${subject} is Boolean and declares ${declared}.`,
+            });
         }
         return;
     }
     if (config.required !== undefined && typeof config.required !== 'boolean') {
-        throw new DeclarationError(`${subject} required must be Boolean. Use true or false.`);
+        throw flagFault(site, 'required');
     }
     if (input.kind === 'argument' &&
         input.config.variadic !== undefined &&
         typeof input.config.variadic !== 'boolean') {
-        throw new DeclarationError(`${subject} variadic must be Boolean. Use true or false.`);
+        throw flagFault(site, 'variadic');
     }
     // The test reads presence, not truth, so a declared `undefined` is a declaration to reject.
     if ('validateOmitted' in config && typeof config.validateOmitted !== 'boolean') {
-        throw new DeclarationError(`${subject} validateOmitted must be Boolean. Use true or false.`);
+        throw flagFault(site, 'validateOmitted');
     }
     if (config.required && Object.hasOwn(config, 'default')) {
-        throw new DeclarationError(`${subject} is required and declares a default. Remove the default or make the input optional.`);
+        throw factFault(requiredWithDefault, site, {
+            correction: 'Remove the default or make the input optional.',
+            fact: 'default',
+            sentence: `${subject} is required and declares a default.`,
+        });
     }
     if (validatesOmission(input)) {
-        checkOmissionValidation(input, subject);
+        checkOmissionValidation(input, site, subject);
     }
-    const validator = config.validate;
-    if (validator !== undefined &&
-        (validator === null ||
-            (typeof validator !== 'object' && typeof validator !== 'function') ||
-            !validator['~standard'] ||
-            validator['~standard'].version !== 1 ||
-            typeof validator['~standard'].vendor !== 'string' ||
-            typeof validator['~standard'].validate !== 'function')) {
-        throw new DeclarationError(`${subject} validate must be a Standard Schema v1 object. Supply a compatible validator.`);
+    if (config.validate !== undefined && !isStandardSchema(config.validate)) {
+        throw factFault(notAValidator, site, {
+            correction: 'Supply a compatible validator.',
+            fact: 'validate',
+            sentence: `${subject} validate must be a Standard Schema v1 object.`,
+        });
     }
 }
+/**
+ * One issue a validator returned, checked where it enters. Core keeps every own enumerable field
+ * the issue carries and rewrites only `path`, reducing each segment to its key, so a field core
+ * never reads, such as a validator's issue code, reaches a failure view unchanged.
+ */
 function readIssue(issue) {
     if (issue === null || typeof issue !== 'object' || !('message' in issue)) {
         throw new Error('The validator returned an invalid Standard Schema issue.');
@@ -208,7 +321,7 @@ function readIssue(issue) {
     }
     const suppliedPath = 'path' in issue ? issue.path : undefined;
     if (suppliedPath === undefined) {
-        return { message };
+        return { ...issue, message };
     }
     if (!Array.isArray(suppliedPath)) {
         throw new Error('The validator returned an invalid Standard Schema issue path.');
@@ -220,13 +333,15 @@ function readIssue(issue) {
         }
         return key;
     });
-    return { message, path };
+    return { ...issue, message, path };
 }
 /**
  * A broken validator is a fault in the declaration, whichever value reached it, so its diagnostic
- * names the declaration. Returned issues belong to the value, so the caller names those.
+ * names the declaration and its finding marks the validator on the call at `place`. Returned issues
+ * belong to the value, so the caller names those.
  */
-async function validate(input, raw, context) {
+async function validate(input, raw, call) {
+    const { context, place } = call;
     const validator = input.config.validate;
     if (validator === undefined) {
         return { value: raw };
@@ -246,8 +361,13 @@ async function validate(input, raw, context) {
         return { issues: Array.from(issues, readIssue) };
     }
     catch (error) {
-        const reason = error instanceof Error ? error.message : 'Unknown validator failure.';
-        throw new DeclarationError(`${declaredName(input)} validator failed unexpectedly: ${reason} Fix the validator.`);
+        // The reason is the author's detail: a distributed build shows the generic defect message.
+        const site = place === undefined ? undefined : declaringSite(input, place);
+        throw new DeclarationError(validatorFailed, {
+            correction: 'Fix the validator.',
+            findings: site === undefined ? [] : [siteFinding(site, partOf(site, 'validate'))],
+            sentence: `${declarationSubject(input)} validator failed unexpectedly: ${asSentence(reasonOf(error))}`,
+        }, { cause: error });
     }
 }
 /**
@@ -258,13 +378,13 @@ async function validate(input, raw, context) {
  * next call. The host is the one captured object that every call and the action share.
  */
 async function validateDeclared(input, raw, call) {
-    const { context, signal } = call;
+    const { context, place, signal } = call;
     if (!collects(input) || input.config.validate === undefined) {
-        return validate(input, raw, context());
+        return validate(input, raw, { context: context(), place });
     }
     if (!Array.isArray(raw)) {
         // The parser, the input sources, and the declaration rules only ever supply an array here.
-        throw new TypeError(`${declaredName(input)} reached validation without an array of values.`);
+        throw new TypeError(`${declarationSubject(input)} reached validation without an array of values.`);
     }
     const outputs = [];
     const issues = [];
@@ -273,15 +393,15 @@ async function validateDeclared(input, raw, call) {
             // A cancelled run starts no further call; the run resolves its cancellation code instead.
             break;
         }
-        const result = await validate(input, value, context());
+        const result = await validate(input, value, { context: context(), place });
         if (result.issues === undefined) {
             outputs.push(result.value);
         }
         else {
-            issues.push(...reported(result.issues).map((issue) => ({
-                message: issue.message,
-                path: [position, ...(issue.path ?? [])],
-            })));
+            // The issue keeps its own fields, and only its path gains the value's position.
+            for (const issue of reported(result.issues)) {
+                issues.push({ ...issue, path: [position, ...(issue.path ?? [])] });
+            }
         }
     }
     return issues.length === 0 ? { value: outputs } : { issues };
@@ -304,23 +424,33 @@ export function issuePath(issue) {
  */
 function reported(issues) {
     return issues.length === 0
-        ? [{ message: 'The validator rejected this value without an explanation.' }]
+        ? [
+            {
+                message: 'The validator rejected this value without an explanation. Supply a different value.',
+            },
+        ]
         : issues;
 }
+/**
+ * One line per issue under the input's subject. A path segment can hold text the operator typed,
+ * such as a key of a record, so the line escapes the path; `issuePath` keeps it raw for a view.
+ */
 function messages(subject, issues) {
     return issues.map((issue) => {
         const path = issuePath(issue);
-        return `${subject}${path === undefined ? '' : ` at ${path}`}: ${issue.message}`;
+        const position = path === undefined ? '' : ` at ${escapeControlCharacters(path)}`;
+        return `${subject}${position}: ${issue.message}`;
     });
 }
 /** The fault a default of the wrong raw shape reports, by the shape its declaration expects. */
-function defaultShapeFault(input, subject) {
+function defaultShapeFault(input, site, subject) {
+    const fault = (sentence, correction) => factFault(defaultShape, site, { correction, fact: 'default', sentence });
     if (!collects(input)) {
-        return `${subject} default must be a string without a validator. Supply a string default.`;
+        return fault(`${subject} default must be a string without a validator.`, 'Supply a string default.');
     }
     return input.config.validate === undefined
-        ? `${subject} default must be an array of strings without a validator. Supply a string array default.`
-        : `${subject} default must be an array. Supply an array of values.`;
+        ? fault(`${subject} default must be an array of strings without a validator.`, 'Supply a string array default.')
+        : fault(`${subject} default must be an array.`, 'Supply an array of values.');
 }
 /** A declared `default: undefined` is a default, so presence is the key, never the value. */
 function hasDefault(input) {
@@ -334,44 +464,57 @@ function hasDefault(input) {
  * diagnostics read with; every other caller is named by the declaration itself.
  */
 export function checkDeclarations(inputs, named) {
-    for (const input of inputs) {
-        checkDeclaration(input, named ?? declaredName(input));
+    for (const { input, site } of inputs) {
+        checkDeclaration(input, site, named ?? declarationSubject(input));
     }
-    for (const input of inputs.filter((entry) => hasDefault(entry))) {
+    for (const { input, site } of inputs.filter((entry) => hasDefault(entry.input))) {
         if (!holdsRawDefault(input)) {
-            const subject = named ?? declaredName(input);
-            throw new DeclarationError(defaultShapeFault(input, subject));
+            throw defaultShapeFault(input, site, named ?? declarationSubject(input));
         }
     }
 }
 /**
  * Every declared default, validated before any token is read. The host is captured by then, so a
- * default's validator reads the same Host its action will, under the `default` phase.
+ * default's validator reads the same Host its action will, under the `default` phase. `places`
+ * says where each declaration sits, which a rejected default's finding rebuilds.
  */
-export async function prepareInputs(inputs, host) {
+export async function prepareInputs(inputs, host, places) {
     const declarations = scoped(inputs);
     const defaults = new Map();
     for (const entry of declarations.filter(({ input }) => hasDefault(input))) {
         const { input } = entry;
-        const subject = declaredName(input);
+        const subject = declarationSubject(input);
+        const place = places.get(input);
         const result = await validateDeclared(input, input.config.default, {
             context: () => ({ host, input: identityOf(entry), phase: 'default' }),
+            place,
         });
         if (result.issues !== undefined) {
-            throw new DeclarationError(`${subject} has an invalid default. Fix the default or its validator.\n${messages(subject, reported(result.issues)).join('\n')}`);
+            const site = place === undefined ? undefined : declaringSite(input, place);
+            throw new DeclarationError(invalidDefault, {
+                correction: 'Fix the default or its validator.',
+                findings: site === undefined ? [] : [siteFinding(site, partOf(site, 'default'))],
+                sentence: [
+                    `${subject} has an invalid default.`,
+                    ...messages(subject, reported(result.issues)),
+                ].join('\n'),
+            });
         }
         defaults.set(input, result.value);
     }
     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
@@ -461,6 +604,7 @@ export async function validateValues(invocation) {
     const accept = async (entry, raw, spelling) => {
         const result = await validateDeclared(entry.input, raw, {
             context: () => contextOf(entry),
+            place: inputPlace(entry.input, { global: entry.global, path: invocation.command }),
             signal: invocation.signal,
         });
         if (result.issues === undefined) {