@loomcli/validators 0.5.0 → 0.7.0

package/dist/bounds.d.ts

@@ -1,3 +1,5 @@
+import type { StandardSchemaV1 } from '@loomcli/core';
+import type { BoundCodes } from './codes.js';
 /** Inclusive bounds on a numeric factory, either or both absent. */
 interface Bounds {
     min: number | undefined;
@@ -15,13 +17,13 @@ declare function readBounds(options: unknown, rule: BoundRule): Bounds;
 declare function withinBounds(value: number, { max, min }: Bounds): boolean;
 /** The number a numeric token outputs, with `-0` read as `0`. */
 declare function withoutNegativeZero(value: number): number;
-/** The one sentence for a numeric configuration, each bound printed as JavaScript prints it. */
-declare function boundsSentence(noun: string, { max, min }: Bounds): string;
+/** The one issue for a numeric configuration, under the code for the bounds it declares. */
+declare function boundsIssue(codes: BoundCodes, { max, min }: Bounds): StandardSchemaV1.Issue;
 /** The published schema for a numeric type, with each declared bound. */
 declare function boundsSchema(type: 'integer' | 'number', { max, min }: Bounds): {
     type: "integer" | "number";
     minimum?: number;
     maximum?: number;
 };
-export { boundsSchema, boundsSentence, readBounds, withinBounds, withoutNegativeZero };
+export { boundsIssue, boundsSchema, readBounds, withinBounds, withoutNegativeZero };
 export type { Bounds };

package/dist/bounds.js

@@ -1,21 +1,31 @@
 import { fault, readOptions } from './faults.js';
+import { boundsOrder, boundValue } from './rules.js';
 const zero = 0;
-function boundOf(rule, name, value) {
+/** One bound a numeric factory declares, checked against its rule; a fault marks the bound. */
+function boundOf(bound, name, value) {
+    const { call, rule } = bound;
     if (value === undefined) {
         return undefined;
     }
     if (typeof value !== 'number' || !rule.accepts(value)) {
-        throw fault(`${rule.factory}() ${name} is not ${rule.requirement}. ${rule.correction}`);
+        throw fault(boundValue, { ...call, mark: `0.${name}` }, {
+            correction: rule.correction,
+            sentence: `${rule.factory}() ${name} is not ${rule.requirement}.`,
+        });
     }
     return value;
 }
 /** Reads a numeric factory's `min` and `max`, and faults on a bad bound or `min` above `max`. */
 function readBounds(options, rule) {
     const declared = readOptions(rule.factory, options);
-    const min = boundOf(rule, 'min', declared.min);
-    const max = boundOf(rule, 'max', declared.max);
+    const call = { arguments: [options], factory: rule.factory };
+    const min = boundOf({ call, rule }, 'min', declared.min);
+    const max = boundOf({ call, rule }, 'max', declared.max);
     if (min !== undefined && max !== undefined && min > max) {
-        throw fault(`${rule.factory}() min ${String(min)} is above max ${String(max)}. Supply a min at or below max.`);
+        throw fault(boundsOrder, { ...call, mark: '0.min' }, {
+            correction: 'Supply a min at or below max.',
+            sentence: `${rule.factory}() min ${String(min)} is above max ${String(max)}.`,
+        });
     }
     return { max, min };
 }
@@ -26,18 +36,18 @@ function withinBounds(value, { max, min }) {
 function withoutNegativeZero(value) {
     return value === zero ? zero : value;
 }
-/** The one sentence for a numeric configuration, each bound printed as JavaScript prints it. */
-function boundsSentence(noun, { max, min }) {
+/** The one issue for a numeric configuration, under the code for the bounds it declares. */
+function boundsIssue(codes, { max, min }) {
     if (min !== undefined && max !== undefined) {
-        return `Expected ${noun} from ${String(min)} through ${String(max)}.`;
+        return codes.range.issue({ max, min });
     }
     if (min !== undefined) {
-        return `Expected ${noun} of at least ${String(min)}.`;
+        return codes.min.issue({ min });
     }
     if (max !== undefined) {
-        return `Expected ${noun} of at most ${String(max)}.`;
+        return codes.max.issue({ max });
     }
-    return `Expected ${noun}.`;
+    return codes.unbounded.issue({});
 }
 /** The published schema for a numeric type, with each declared bound. */
 function boundsSchema(type, { max, min }) {
@@ -47,4 +57,4 @@ function boundsSchema(type, { max, min }) {
         ...(max === undefined ? {} : { maximum: max }),
     };
 }
-export { boundsSchema, boundsSentence, readBounds, withinBounds, withoutNegativeZero };
+export { boundsIssue, boundsSchema, readBounds, withinBounds, withoutNegativeZero };

package/dist/codes.d.ts

@@ -0,0 +1,78 @@
+import type { IssueCode } from './issue-code.js';
+import type { NoParams } from './params.js';
+import type { PathKind } from './probe.js';
+declare const textNonemptyIssue: IssueCode<Readonly<Record<string, never>>>;
+declare const textMinLengthIssue: IssueCode<{
+    min: number;
+}>;
+declare const textMaxLengthIssue: IssueCode<{
+    max: number;
+}>;
+declare const textExactLengthIssue: IssueCode<{
+    length: number;
+}>;
+declare const textLengthRangeIssue: IssueCode<{
+    max: number;
+    min: number;
+}>;
+/** The author's own sentence for a `text()` pattern, which is the code's one blank. */
+declare const textPatternIssue: IssueCode<{
+    message: string;
+}>;
+declare const integerIssue: IssueCode<Readonly<Record<string, never>>>;
+declare const integerRangeIssue: IssueCode<{
+    max: number;
+    min: number;
+}>;
+declare const integerMinIssue: IssueCode<{
+    min: number;
+}>;
+declare const integerMaxIssue: IssueCode<{
+    max: number;
+}>;
+declare const numberIssue: IssueCode<Readonly<Record<string, never>>>;
+declare const numberRangeIssue: IssueCode<{
+    max: number;
+    min: number;
+}>;
+declare const numberMinIssue: IssueCode<{
+    min: number;
+}>;
+declare const numberMaxIssue: IssueCode<{
+    max: number;
+}>;
+declare const portIssue: IssueCode<Readonly<Record<string, never>>>;
+declare const oneOfIssue: IssueCode<{
+    values: readonly string[];
+}>;
+declare const urlIssue: IssueCode<Readonly<Record<string, never>>>;
+declare const urlSchemeIssue: IssueCode<{
+    protocols: readonly string[];
+}>;
+declare const uuidIssue: IssueCode<Readonly<Record<string, never>>>;
+declare const dateIssue: IssueCode<Readonly<Record<string, never>>>;
+declare const pathIssue: IssueCode<Readonly<Record<string, never>>>;
+declare const pathReadableIssue: IssueCode<{
+    kind: PathKind;
+}>;
+declare const pathWritableIssue: IssueCode<{
+    kind: PathKind;
+}>;
+/** The four codes a numeric factory rejects with, one for each way its bounds are declared. */
+interface BoundCodes {
+    unbounded: IssueCode<NoParams>;
+    range: IssueCode<{
+        max: number;
+        min: number;
+    }>;
+    min: IssueCode<{
+        min: number;
+    }>;
+    max: IssueCode<{
+        max: number;
+    }>;
+}
+declare const integerCodes: BoundCodes;
+declare const numberCodes: BoundCodes;
+export { dateIssue, integerCodes, integerIssue, integerMaxIssue, integerMinIssue, integerRangeIssue, numberCodes, numberIssue, numberMaxIssue, numberMinIssue, numberRangeIssue, oneOfIssue, pathIssue, pathReadableIssue, pathWritableIssue, portIssue, textExactLengthIssue, textLengthRangeIssue, textMaxLengthIssue, textMinLengthIssue, textNonemptyIssue, textPatternIssue, urlIssue, urlSchemeIssue, uuidIssue, };
+export type { BoundCodes };

package/dist/codes.js

@@ -0,0 +1,134 @@
+import { issueCode } from './issue-code.js';
+import { listing } from './issues.js';
+import { isCount, isFiniteNumber, isSafeInteger, kindParams, lengthParams, maxParams, messageParams, minParams, noParams, protocolsParams, rangeParams, valuesParams, } from './params.js';
+/**
+ * The catalog's issue codes, one for each sentence a catalog validator prints. Each code's
+ * parameters are that sentence's blanks and hold the rule's settings, never the rejected value.
+ */
+const oneCharacter = 1;
+/** A count of characters, reading `character` for a count of 1. */
+function characters(count) {
+    return count === oneCharacter ? '1 character' : `${String(count)} characters`;
+}
+/** The catalog's own code for a rule: the package name, `/`, and the rule name. */
+function catalogCode(rule) {
+    return `@loomcli/validators/${rule}`;
+}
+const textNonemptyIssue = issueCode(catalogCode('text-nonempty'), {
+    message: () => 'Expected a nonempty value.',
+    schema: noParams,
+});
+const textMinLengthIssue = issueCode(catalogCode('text-min-length'), {
+    message: ({ min }) => `Expected at least ${characters(min)}.`,
+    schema: minParams(isCount),
+});
+const textMaxLengthIssue = issueCode(catalogCode('text-max-length'), {
+    message: ({ max }) => `Expected at most ${characters(max)}.`,
+    schema: maxParams(isCount),
+});
+const textExactLengthIssue = issueCode(catalogCode('text-exact-length'), {
+    message: ({ length }) => `Expected exactly ${characters(length)}.`,
+    schema: lengthParams,
+});
+const textLengthRangeIssue = issueCode(catalogCode('text-length-range'), {
+    message: ({ max, min }) => `Expected from ${String(min)} through ${characters(max)}.`,
+    schema: rangeParams(isCount),
+});
+/** The author's own sentence for a `text()` pattern, which is the code's one blank. */
+const textPatternIssue = issueCode(catalogCode('text-pattern'), {
+    message: ({ message }) => message,
+    schema: messageParams,
+});
+const integerIssue = issueCode(catalogCode('integer'), {
+    message: () => 'Expected a whole number.',
+    schema: noParams,
+});
+const integerRangeIssue = issueCode(catalogCode('integer-range'), {
+    message: ({ max, min }) => `Expected a whole number from ${String(min)} through ${String(max)}.`,
+    schema: rangeParams(isSafeInteger),
+});
+const integerMinIssue = issueCode(catalogCode('integer-min'), {
+    message: ({ min }) => `Expected a whole number of at least ${String(min)}.`,
+    schema: minParams(isSafeInteger),
+});
+const integerMaxIssue = issueCode(catalogCode('integer-max'), {
+    message: ({ max }) => `Expected a whole number of at most ${String(max)}.`,
+    schema: maxParams(isSafeInteger),
+});
+const numberIssue = issueCode(catalogCode('number'), {
+    message: () => 'Expected a number.',
+    schema: noParams,
+});
+const numberRangeIssue = issueCode(catalogCode('number-range'), {
+    message: ({ max, min }) => `Expected a number from ${String(min)} through ${String(max)}.`,
+    schema: rangeParams(isFiniteNumber),
+});
+const numberMinIssue = issueCode(catalogCode('number-min'), {
+    message: ({ min }) => `Expected a number of at least ${String(min)}.`,
+    schema: minParams(isFiniteNumber),
+});
+const numberMaxIssue = issueCode(catalogCode('number-max'), {
+    message: ({ max }) => `Expected a number of at most ${String(max)}.`,
+    schema: maxParams(isFiniteNumber),
+});
+const portIssue = issueCode(catalogCode('port'), {
+    message: () => 'Expected a port number from 1 through 65535.',
+    schema: noParams,
+});
+const oneOfIssue = issueCode(catalogCode('one-of'), {
+    message: ({ values }) => `Expected one of: ${values.join(', ')}.`,
+    schema: valuesParams,
+});
+const urlIssue = issueCode(catalogCode('url'), {
+    message: () => 'Expected an absolute URL, such as https://example.com.',
+    schema: noParams,
+});
+const urlSchemeIssue = issueCode(catalogCode('url-scheme'), {
+    message: ({ protocols }) => `Expected an absolute URL with the scheme ${listing(protocols)}.`,
+    schema: protocolsParams,
+});
+const uuidIssue = issueCode(catalogCode('uuid'), {
+    message: () => 'Expected a UUID, such as 123e4567-e89b-12d3-a456-426614174000.',
+    schema: noParams,
+});
+const dateIssue = issueCode(catalogCode('date'), {
+    message: () => 'Expected a date as YYYY-MM-DD, such as 2026-09-25.',
+    schema: noParams,
+});
+const pathIssue = issueCode(catalogCode('path'), {
+    message: () => 'Expected a nonempty path with no NUL character.',
+    schema: noParams,
+});
+/** How each kind reads in a readable-path sentence. */
+const readableKinds = {
+    any: 'file or directory',
+    directory: 'directory',
+    file: 'file',
+};
+/** How each kind reads in a writable-path sentence. */
+const writableKinds = {
+    any: 'path',
+    directory: 'directory',
+    file: 'file',
+};
+const pathReadableIssue = issueCode(catalogCode('path-readable'), {
+    message: ({ kind }) => `Expected a readable ${readableKinds[kind]} that exists.`,
+    schema: kindParams,
+});
+const pathWritableIssue = issueCode(catalogCode('path-writable'), {
+    message: ({ kind }) => `Expected a writable ${writableKinds[kind]}, or a new ${writableKinds[kind]} in a writable directory.`,
+    schema: kindParams,
+});
+const integerCodes = {
+    max: integerMaxIssue,
+    min: integerMinIssue,
+    range: integerRangeIssue,
+    unbounded: integerIssue,
+};
+const numberCodes = {
+    max: numberMaxIssue,
+    min: numberMinIssue,
+    range: numberRangeIssue,
+    unbounded: numberIssue,
+};
+export { dateIssue, integerCodes, integerIssue, integerMaxIssue, integerMinIssue, integerRangeIssue, numberCodes, numberIssue, numberMaxIssue, numberMinIssue, numberRangeIssue, oneOfIssue, pathIssue, pathReadableIssue, pathWritableIssue, portIssue, textExactLengthIssue, textLengthRangeIssue, textMaxLengthIssue, textMinLengthIssue, textNonemptyIssue, textPatternIssue, urlIssue, urlSchemeIssue, uuidIssue, };

package/dist/create.d.ts

@@ -8,6 +8,8 @@ interface ValidatorDefinition<Output> {
     parse: (raw: string, context: ValidationContext) => ParseResult<Output> | Promise<ParseResult<Output>>;
     inputSchema?: Readonly<Record<string, unknown>>;
 }
+/** The vendor every Standard Schema value this package builds reports. */
+declare const vendor = "@loomcli/validators";
 /**
  * Builds a frozen Standard Schema value from the author's parse function.
  * With an input schema it also publishes that schema through Standard JSON Schema.
@@ -16,5 +18,5 @@ declare function createValidator<Output>(definition: ValidatorDefinition<Output>
     inputSchema: Readonly<Record<string, unknown>>;
 }): Validator<Output>;
 declare function createValidator<Output>(definition: ValidatorDefinition<Output>): StandardSchemaV1<string, Output>;
-export { createValidator };
+export { createValidator, vendor };
 export type { ParseResult, Validator, ValidatorDefinition };

package/dist/create.js

@@ -1,11 +1,17 @@
 import { DeclarationError, validationContext } from '@loomcli/core';
 import { copyRecord, isPlainObject } from './data.js';
 import { fault } from './faults.js';
+import { contextOutsideRun, inputSchema, validatorDefinition } from './rules.js';
+/** The vendor every Standard Schema value this package builds reports. */
 const vendor = '@loomcli/validators';
 const target = 'draft-2020-12';
 const dialect = 'https://json-schema.org/draft/2020-12/schema';
+/** A read of the context outside a run, which no declaration call stands for. */
 function unavailable() {
-    throw new DeclarationError('This validator reads the validation context, which only exists during a Loom run.');
+    throw new DeclarationError(contextOutsideRun, {
+        correction: 'Call the validator through an Application run, or leave the context unread.',
+        sentence: 'This validator reads the validation context, which only exists during a Loom run.',
+    });
 }
 /**
  * The context `parse` receives when core did not make the call.
@@ -50,26 +56,42 @@ function converter(schema) {
  * undefined when it declares none.
  */
 function checkDefinition(definition) {
+    const at = (mark) => ({ arguments: [definition], factory: 'createValidator', mark });
     if (!isPlainObject(definition)) {
-        throw fault('createValidator() definition is not a plain object. Supply an object with a parse function.');
+        throw fault(validatorDefinition, at('0'), {
+            correction: 'Supply an object with a parse function.',
+            sentence: 'createValidator() definition is not a plain object.',
+        });
     }
     if (typeof definition.parse !== 'function') {
-        throw fault('createValidator() parse is not a function. Supply a function that validates one raw string.');
+        throw fault(validatorDefinition, at('parse' in definition ? '0.parse' : '0'), {
+            correction: 'Supply a function that validates one raw string.',
+            sentence: 'createValidator() parse is not a function.',
+        });
     }
-    return declaredSchema(definition.inputSchema);
+    return declaredSchema(definition.inputSchema, at);
 }
-/** The declared input schema, checked, copied, and frozen, or undefined when none is declared. */
-function declaredSchema(inputSchema) {
-    if (inputSchema === undefined) {
+/**
+ * The declared input schema, checked, copied, and frozen, or undefined when none is declared. `at`
+ * rebuilds the `createValidator()` call, marking the part at fault.
+ */
+function declaredSchema(declared, at) {
+    if (declared === undefined) {
         return undefined;
     }
-    if (!isPlainObject(inputSchema)) {
-        throw fault('createValidator() inputSchema is not a plain object. Supply the JSON Schema as a plain object.');
+    if (!isPlainObject(declared)) {
+        throw fault(inputSchema, at('0.inputSchema'), {
+            correction: 'Supply the JSON Schema as a plain object.',
+            sentence: 'createValidator() inputSchema is not a plain object.',
+        });
     }
-    if (Object.hasOwn(inputSchema, '$schema')) {
-        throw fault('createValidator() inputSchema declares its own $schema. Leave out $schema, which the validator publishes itself.');
+    if (Object.hasOwn(declared, '$schema')) {
+        throw fault(inputSchema, at('0.inputSchema.$schema'), {
+            correction: 'Leave out $schema, which the validator publishes itself.',
+            sentence: 'createValidator() inputSchema declares its own $schema.',
+        });
     }
-    return copyRecord(inputSchema, true);
+    return copyRecord(declared, true);
 }
 function createValidator(definition) {
     const schema = checkDefinition(definition);
@@ -89,4 +111,4 @@ function createValidator(definition) {
     }
     return Object.freeze({ '~standard': Object.freeze({ ...props, jsonSchema: converter(schema) }) });
 }
-export { createValidator };
+export { createValidator, vendor };

package/dist/date.js

@@ -1,3 +1,4 @@
+import { dateIssue } from './codes.js';
 import { createValidator } from './create.js';
 import { reject } from './issues.js';
 const layout = /^(?<year>[0-9]{4})-(?<month>[0-9]{2})-(?<day>[0-9]{2})$/u;
@@ -17,13 +18,14 @@ function isRealDay(year, month, day) {
 }
 /** A calendar date as `YYYY-MM-DD`, kept as the token because a date has no time or zone. */
 function date() {
+    const issue = dateIssue.issue({});
     return createValidator({
         inputSchema: { type: 'string', format: 'date' },
         parse: (raw) => {
             const parts = layout.exec(raw)?.groups;
             const real = parts !== undefined &&
                 isRealDay(Number(parts.year), Number(parts.month), Number(parts.day));
-            return real ? { value: raw } : reject('Expected a date as YYYY-MM-DD, such as 2026-09-25.');
+            return real ? { value: raw } : reject(issue);
         },
     });
 }

package/dist/faults.d.ts

@@ -1,9 +1,23 @@
 import { DeclarationError } from '@loomcli/core';
+import type { DiagnosticRule } from '@loomcli/core';
+/** One factory call as a finding rebuilds it: the factory's name and the arguments it received. */
+interface FactoryCall {
+    readonly factory: string;
+    readonly arguments: readonly unknown[];
+}
 /**
- * A factory argument that can never work.
- * The message names the factory and the argument, states the problem, then the correction.
+ * A factory argument that can never work, under the rule it breaks. The finding rebuilds the call
+ * and marks the argument or the key at fault, `mark` being its dotted path among the arguments,
+ * with a note when given. The sentence names the factory and the argument and states the problem,
+ * and the correction states the fix.
  */
-declare function fault(message: string): DeclarationError;
+declare function fault(rule: DiagnosticRule, at: FactoryCall & {
+    readonly mark: string;
+    readonly note?: string;
+}, parts: {
+    readonly sentence: string;
+    readonly correction: string;
+}): DeclarationError;
 /** A declared value as a fault message quotes it: a string in quotes, a primitive as printed. */
 declare function quote(value: unknown): string;
 /**
@@ -12,3 +26,4 @@ declare function quote(value: unknown): string;
  */
 declare function readOptions(factory: string, options: unknown): Readonly<Record<string, unknown>>;
 export { fault, quote, readOptions };
+export type { FactoryCall };

package/dist/faults.js

@@ -1,11 +1,20 @@
 import { DeclarationError } from '@loomcli/core';
 import { isPlainObject } from './data.js';
+import { factoryOptions } from './rules.js';
 /**
- * A factory argument that can never work.
- * The message names the factory and the argument, states the problem, then the correction.
+ * A factory argument that can never work, under the rule it breaks. The finding rebuilds the call
+ * and marks the argument or the key at fault, `mark` being its dotted path among the arguments,
+ * with a note when given. The sentence names the factory and the argument and states the problem,
+ * and the correction states the fix.
  */
-function fault(message) {
-    return new DeclarationError(message);
+function fault(rule, at, parts) {
+    const { mark, note } = at;
+    const finding = { arguments: at.arguments, call: at.factory, mark };
+    return new DeclarationError(rule, {
+        correction: parts.correction,
+        findings: [note === undefined ? finding : { ...finding, note }],
+        sentence: parts.sentence,
+    });
 }
 /** A declared value as a fault message quotes it: a string in quotes, a primitive as printed. */
 function quote(value) {
@@ -30,7 +39,10 @@ function readOptions(factory, options) {
         return {};
     }
     if (!isPlainObject(options)) {
-        throw fault(`${factory}() options is not a plain object. Supply an object or leave it out.`);
+        throw fault(factoryOptions, { arguments: [options], factory, mark: '0' }, {
+            correction: 'Supply an object or leave it out.',
+            sentence: `${factory}() options is not a plain object.`,
+        });
     }
     return options;
 }

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+export { dateIssue, integerIssue, integerMaxIssue, integerMinIssue, integerRangeIssue, numberIssue, numberMaxIssue, numberMinIssue, numberRangeIssue, oneOfIssue, pathIssue, pathReadableIssue, pathWritableIssue, portIssue, textExactLengthIssue, textLengthRangeIssue, textMaxLengthIssue, textMinLengthIssue, textNonemptyIssue, textPatternIssue, urlIssue, urlSchemeIssue, uuidIssue, } from './codes.js';
 export { createValidator } from './create.js';
 export { date } from './date.js';
 export { integer } from './integer.js';
+export { issueCode } from './issue-code.js';
 export { number } from './number.js';
 export { oneOf } from './one-of.js';
 export { path } from './path.js';
@@ -9,3 +11,4 @@ export { text } from './text.js';
 export { url } from './url.js';
 export { uuid } from './uuid.js';
 export type { ParseResult, Validator } from './create.js';
+export type { IssueCode } from './issue-code.js';

package/dist/index.js

@@ -1,6 +1,8 @@
+export { dateIssue, integerIssue, integerMaxIssue, integerMinIssue, integerRangeIssue, numberIssue, numberMaxIssue, numberMinIssue, numberRangeIssue, oneOfIssue, pathIssue, pathReadableIssue, pathWritableIssue, portIssue, textExactLengthIssue, textLengthRangeIssue, textMaxLengthIssue, textMinLengthIssue, textNonemptyIssue, textPatternIssue, urlIssue, urlSchemeIssue, uuidIssue, } from './codes.js';
 export { createValidator } from './create.js';
 export { date } from './date.js';
 export { integer } from './integer.js';
+export { issueCode } from './issue-code.js';
 export { number } from './number.js';
 export { oneOf } from './one-of.js';
 export { path } from './path.js';

package/dist/integer.js

@@ -1,4 +1,5 @@
-import { boundsSchema, boundsSentence, readBounds, withinBounds, withoutNegativeZero, } from './bounds.js';
+import { boundsIssue, boundsSchema, readBounds, withinBounds, withoutNegativeZero, } from './bounds.js';
+import { integerCodes } from './codes.js';
 import { createValidator } from './create.js';
 import { reject } from './issues.js';
 const digits = /^-?[0-9]+$/u;
@@ -18,12 +19,12 @@ function integer(options) {
         factory: 'integer',
         requirement: 'a safe integer',
     });
-    const sentence = boundsSentence('a whole number', bounds);
+    const issue = boundsIssue(integerCodes, bounds);
     return createValidator({
         inputSchema: boundsSchema('integer', bounds),
         parse: (raw) => {
             const value = readInteger(raw);
-            return value !== undefined && withinBounds(value, bounds) ? { value } : reject(sentence);
+            return value !== undefined && withinBounds(value, bounds) ? { value } : reject(issue);
         },
     });
 }

package/dist/issue-code.d.ts

@@ -0,0 +1,24 @@
+import type { StandardSchemaV1 } from '@loomcli/core';
+/**
+ * One issue code a validator package declares: the code string, the schema its parameters pass,
+ * a builder for the issue a `parse` function returns, and a typed read of that issue.
+ */
+interface IssueCode<Params> {
+    readonly code: string;
+    readonly schema: StandardSchemaV1<Params>;
+    issue(this: void, params: Params): StandardSchemaV1.Issue;
+    read(this: void, issue: StandardSchemaV1.Issue): Params | undefined;
+}
+/** What `issueCode` declares beside the code: the parameter schema and the one sentence. */
+interface IssueCodeConfig<Params> {
+    schema: StandardSchemaV1<Params>;
+    message: (params: Params) => string;
+}
+/**
+ * Declares one issue code with its parameter schema and its one sentence, and returns a frozen
+ * descriptor. `issue` builds the rejection a `parse` function returns, and `read` recovers the
+ * typed parameters from an issue carrying the code.
+ */
+declare function issueCode<Params>(code: string, config: IssueCodeConfig<Params>): IssueCode<Params>;
+export { issueCode };
+export type { IssueCode, IssueCodeConfig };