@loomcli/validators 0.5.0 → 0.6.0

package/dist/rules.js

@@ -0,0 +1,86 @@
+import { diagnosticRule } from '@loomcli/core';
+/*
+ * The catalog's rules for the declaration faults its factories raise. Each is declared once here
+ * through the public diagnosticRule(), under the package's own name, as any third-party validator
+ * package declares its rules, and shared by every site that raises it.
+ */
+/** One rule of this package, named under the package as its issue codes are. */
+function catalogRule(name, definition) {
+    return diagnosticRule(`@loomcli/validators/${name}`, definition);
+}
+/** A factory's options that are not a plain object. */
+const factoryOptions = catalogRule('factory-options', {
+    explanation: 'A catalog factory reads its settings from one options object, so a value of any other kind leaves it no settings to read.',
+    headline: 'Options not an object',
+});
+/** A `oneOf()` list that is not a list of distinct nonempty strings. */
+const oneOfValues = catalogRule('one-of-values', {
+    explanation: 'oneOf() accepts a token equal to one of its values, and help, completion, and the published schema offer each value as a choice, so the list holds at least one value, each a distinct nonempty string.',
+    headline: 'Invalid oneOf values',
+});
+/** A bound that is not a number of the kind its validator reads. */
+const boundValue = catalogRule('bound-value', {
+    explanation: "A bound limits the values or the length a validator accepts, and the published schema carries it, so it is a number of the kind the validator reads: a safe integer for integer(), a finite number for number(), and a non-negative safe integer for text()'s lengths.",
+    headline: 'Invalid bound',
+});
+/** A lower bound above its upper bound. */
+const boundsOrder = catalogRule('bounds-order', {
+    explanation: 'A validator accepts what lies between its lower and its upper bound, both inclusive, so a lower bound above the upper one would reject every token.',
+    headline: 'Bounds out of order',
+});
+/** A `url()` protocols list that is not a list of scheme names. */
+const urlProtocols = catalogRule('url-protocols', {
+    explanation: 'url() accepts a URL whose scheme the list names and publishes the list as a pattern, so it holds at least one scheme name: a letter followed by letters, digits, +, -, or ., with no trailing colon.',
+    headline: 'Invalid url protocols',
+});
+/** A `path()` access or kind outside its set, or a kind with no access to narrow. */
+const pathCheck = catalogRule('path-check', {
+    explanation: 'path() reads the file system only to check an access, read or write, and kind narrows that check to a file, a directory, or any entry, so kind has no meaning without access.',
+    headline: 'Invalid path check',
+});
+/** A `text()` pattern that JSON Schema cannot read as it is. */
+const textPattern = catalogRule('invalid-pattern', {
+    explanation: 'text() publishes its pattern in the JSON Schema it serves, which reads a pattern under the u flag alone, so the pattern is a regular expression that compiles under u and carries no other flag.',
+    headline: 'Invalid pattern',
+});
+/** A `text()` pattern without its sentence, or a sentence without a pattern. */
+const patternMessage = catalogRule('pattern-message', {
+    explanation: 'Only the author can say what a pattern accepts, so text() takes a pattern together with one sentence that states it, and prints that sentence when a token does not match.',
+    headline: 'Pattern and message apart',
+});
+/** An issue code outside the `<package>[/<subpath>...]/<kebab-case-rule>` grammar. */
+const issueCodeName = catalogRule('issue-code-name', {
+    explanation: 'An issue code names the package that declares it and the one sentence it prints, so a view rewords that sentence by its code. It is a package name, any kebab-case subpath segments, and a kebab-case rule name, joined by /.',
+    headline: 'Invalid issue code',
+});
+/** An `issueCode()` config without a Standard Schema and a message function. */
+const issueCodeConfig = catalogRule('issue-code-config', {
+    explanation: "An issue code checks each issue's parameters with its schema and builds the issue's sentence from them with its message function, so its config holds both.",
+    headline: 'Invalid issue code config',
+});
+/** An issue code schema that answers with a promise, throws, or answers with no result. */
+const issueCodeSchema = catalogRule('issue-code-schema', {
+    explanation: "issue() and read() check an issue's parameters with the code's schema synchronously, while a validator builds the issue or a view reads it, so the schema returns its value or its issues, and neither throws nor answers with a promise.",
+    headline: 'Broken issue code schema',
+});
+/** Parameters an issue code's schema rejects. */
+const issueParameters = catalogRule('issue-parameters', {
+    explanation: "An issue carries parameters its code's schema accepts, so every view that reads them through read() gets the shape the code declares.",
+    headline: 'Issue parameters rejected',
+});
+/** A `createValidator()` definition without a parse function. */
+const validatorDefinition = catalogRule('validator-definition', {
+    explanation: 'createValidator() builds a Standard Schema value around one parse function that validates a raw string, so its definition is an object that holds that function.',
+    headline: 'Invalid validator definition',
+});
+/** A `createValidator()` input schema that is not a plain object, or declares its own dialect. */
+const inputSchema = catalogRule('input-schema', {
+    explanation: 'createValidator() publishes its input schema as draft 2020-12 JSON Schema and adds the $schema dialect itself, so inputSchema is a plain object with no $schema of its own.',
+    headline: 'Invalid input schema',
+});
+/** A validator that read the validation context outside a Loom run. */
+const contextOutsideRun = catalogRule('context-outside-run', {
+    explanation: 'Core attaches the validation context to each call it makes to a validator. A call from anywhere else, such as a unit test, carries none, so a validator that reads it runs inside an Application run.',
+    headline: 'Context outside a run',
+});
+export { boundsOrder, boundValue, contextOutsideRun, factoryOptions, inputSchema, issueCodeConfig, issueCodeName, issueCodeSchema, issueParameters, oneOfValues, pathCheck, patternMessage, textPattern, urlProtocols, validatorDefinition, };

package/dist/text.d.ts

@@ -1,10 +1,18 @@
 import type { Validator } from './create.js';
-interface TextOptions {
+/**
+ * The bounds on a token's length, and a pattern with the author's sentence for what it accepts.
+ * Only the author can say what a pattern accepts, so `message` comes with `pattern` or not at all.
+ */
+type TextOptions = {
     minLength?: number;
     maxLength?: number;
-    pattern?: RegExp;
-    message?: string;
-}
+} & ({
+    pattern?: undefined;
+    message?: undefined;
+} | {
+    pattern: RegExp;
+    message: string;
+});
 /** A string whose code-point length is within bounds and which the pattern matches, if any. */
 declare function text(options?: TextOptions): Validator<string>;
 export { text };

package/dist/text.js

@@ -1,77 +1,111 @@
+import { textExactLengthIssue, textLengthRangeIssue, textMaxLengthIssue, textMinLengthIssue, textNonemptyIssue, textPatternIssue, } from './codes.js';
 import { createValidator } from './create.js';
 import { fault, readOptions } from './faults.js';
 import { reject } from './issues.js';
+import { boundsOrder, boundValue, patternMessage, textPattern } from './rules.js';
 const noLength = 0;
 const oneCharacter = 1;
 const defaultMinLength = 1;
-function lengthOf(name, value) {
+/** The `text()` call a fault marks one key of. */
+function textAt(call, key) {
+    return { ...call, mark: `0.${key}` };
+}
+function lengthOf(call, name, value) {
     if (value === undefined) {
         return undefined;
     }
     if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < noLength) {
-        throw fault(`text() ${name} is not a non-negative safe integer. Supply a whole number of 0 or more.`);
+        throw fault(boundValue, textAt(call, name), {
+            correction: 'Supply a whole number of 0 or more.',
+            sentence: `text() ${name} is not a non-negative safe integer.`,
+        });
     }
     return value;
 }
 /** Faults on a pattern flag other than `u`, which JSON Schema has no way to state. */
-function checkFlags(pattern) {
+function checkFlags(call, pattern) {
     const others = pattern.flags.replace('u', '');
     if (others !== '') {
         const noun = others.length === oneCharacter ? 'flag' : 'flags';
-        throw fault(`text() pattern carries the ${noun} ${others}. Supply a pattern with no flag other than u.`);
+        throw fault(textPattern, textAt(call, 'pattern'), {
+            correction: 'Supply a pattern with no flag other than u.',
+            sentence: `text() pattern carries the ${noun} ${others}.`,
+        });
     }
 }
 /** The author's pattern recompiled under the `u` flag, as JSON Schema reads a `pattern`. */
-function patternOf(value) {
+function patternOf(call, value) {
     if (value === undefined) {
         return undefined;
     }
     if (!(value instanceof RegExp)) {
-        throw fault('text() pattern is not a RegExp. Supply a regular expression literal.');
+        throw fault(textPattern, textAt(call, 'pattern'), {
+            correction: 'Supply a regular expression literal.',
+            sentence: 'text() pattern is not a RegExp.',
+        });
     }
-    checkFlags(value);
+    checkFlags(call, value);
     try {
         return new RegExp(value.source, 'u');
     }
     catch {
-        throw fault('text() pattern does not compile under the u flag. Supply a pattern that is valid with the u flag.');
+        throw fault(textPattern, textAt(call, 'pattern'), {
+            correction: 'Supply a pattern that is valid with the u flag.',
+            sentence: 'text() pattern does not compile under the u flag.',
+        });
     }
 }
-function messageOf(value, pattern) {
+function messageOf(call, value) {
     if (value === undefined) {
         return undefined;
     }
     if (typeof value !== 'string' || value === '') {
-        throw fault('text() message is not a nonempty string. Supply one sentence that states the expectation.');
-    }
-    if (pattern === undefined) {
-        throw fault('text() message has no pattern to describe. Supply a pattern or leave out message.');
+        throw fault(patternMessage, textAt(call, 'message'), {
+            correction: 'Supply one sentence that states the expectation.',
+            sentence: 'text() message is not a nonempty string.',
+        });
     }
     return value;
 }
-function characters(count) {
-    return count === oneCharacter ? '1 character' : `${count} characters`;
+/** The pattern rule, or undefined without a pattern; a pattern and a message each need the other. */
+function patternRule(call, pattern, message) {
+    if (pattern === undefined) {
+        if (message !== undefined) {
+            throw fault(patternMessage, textAt(call, 'message'), {
+                correction: 'Supply a pattern or leave out message.',
+                sentence: 'text() message has no pattern to describe.',
+            });
+        }
+        return undefined;
+    }
+    if (message === undefined) {
+        throw fault(patternMessage, textAt(call, 'pattern'), {
+            correction: 'Supply a message that states what the pattern accepts.',
+            sentence: 'text() pattern has no message to describe it.',
+        });
+    }
+    return { issue: textPatternIssue.issue({ message }), pattern };
 }
-/** The sentence for bounds with a `maxLength`, where `min` is `minLength` after its default. */
-function boundedSentence(min, max) {
+/** The issue for bounds with a `maxLength`, where `min` is `minLength` after its default. */
+function boundedIssue(min, max) {
     if (min === max) {
-        return `Expected exactly ${characters(min)}.`;
+        return textExactLengthIssue.issue({ length: min });
     }
     if (min === noLength) {
-        return `Expected at most ${characters(max)}.`;
+        return textMaxLengthIssue.issue({ max });
     }
-    return `Expected from ${min} through ${max} characters.`;
+    return textLengthRangeIssue.issue({ max, min });
 }
 /** The length rule for the effective bounds, or undefined when every length passes. */
 function lengthRule(min, max) {
     if (max !== undefined) {
-        return { fits: (count) => count >= min && count <= max, sentence: boundedSentence(min, max) };
+        return { fits: (count) => count >= min && count <= max, issue: boundedIssue(min, max) };
     }
     if (min === noLength) {
         return undefined;
     }
-    const sentence = min === oneCharacter ? 'Expected a nonempty value.' : `Expected at least ${characters(min)}.`;
-    return { fits: (count) => count >= min, sentence };
+    const issue = min === oneCharacter ? textNonemptyIssue.issue({}) : textMinLengthIssue.issue({ min });
+    return { fits: (count) => count >= min, issue };
 }
 /**
  * The token's length in Unicode code points, as JSON Schema counts it.
@@ -84,27 +118,32 @@ function codePoints(raw) {
 /** A string whose code-point length is within bounds and which the pattern matches, if any. */
 function text(options) {
     const declared = readOptions('text', options);
-    const minLength = lengthOf('minLength', declared.minLength) ?? defaultMinLength;
-    const maxLength = lengthOf('maxLength', declared.maxLength);
+    const call = { arguments: [options], factory: 'text' };
+    const minLength = lengthOf(call, 'minLength', declared.minLength) ?? defaultMinLength;
+    const maxLength = lengthOf(call, 'maxLength', declared.maxLength);
     if (maxLength !== undefined && minLength > maxLength) {
-        throw fault(`text() minLength ${minLength} is above maxLength ${maxLength}. Supply a minLength at or below maxLength.`);
+        // A minLength left to its default has no key to mark, so the maxLength below it is marked.
+        const key = declared.minLength === undefined ? 'maxLength' : 'minLength';
+        throw fault(boundsOrder, textAt(call, key), {
+            correction: 'Supply a minLength at or below maxLength.',
+            sentence: `text() minLength ${minLength} is above maxLength ${maxLength}.`,
+        });
     }
-    const pattern = patternOf(declared.pattern);
-    const patternSentence = messageOf(declared.message, pattern) ?? 'Expected a value that matches the required pattern.';
+    const matching = patternRule(call, patternOf(call, declared.pattern), messageOf(call, declared.message));
     const length = lengthRule(minLength, maxLength);
     return createValidator({
         inputSchema: {
             type: 'string',
             minLength,
             ...(maxLength === undefined ? {} : { maxLength }),
-            ...(pattern === undefined ? {} : { pattern: pattern.source }),
+            ...(matching === undefined ? {} : { pattern: matching.pattern.source }),
         },
         parse: (raw) => {
             if (length !== undefined && !length.fits(codePoints(raw))) {
-                return reject(length.sentence);
+                return reject(length.issue);
             }
-            if (pattern !== undefined && !pattern.test(raw)) {
-                return reject(patternSentence);
+            if (matching !== undefined && !matching.pattern.test(raw)) {
+                return reject(matching.issue);
             }
             return { value: raw };
         },

package/dist/url.js

@@ -1,23 +1,36 @@
+import { urlIssue, urlSchemeIssue } from './codes.js';
 import { createValidator } from './create.js';
 import { fault, quote, readOptions } from './faults.js';
-import { listing, reject } from './issues.js';
+import { reject } from './issues.js';
+import { urlProtocols } from './rules.js';
 import { schemePattern, uriPattern } from './uri-grammar.js';
 const empty = 0;
-function protocolsOf(value) {
+/** The `protocols` a `url()` call declares, checked, and each fault marks it or one entry. */
+function protocolsOf(options, value) {
     if (value === undefined) {
         return undefined;
     }
+    const at = (mark) => ({ arguments: [options], factory: 'url', mark });
     if (!Array.isArray(value)) {
-        throw fault('url() protocols is not an array. Supply an array of scheme names.');
+        throw fault(urlProtocols, at('0.protocols'), {
+            correction: 'Supply an array of scheme names.',
+            sentence: 'url() protocols is not an array.',
+        });
     }
     const items = value;
     if (items.length === empty) {
-        throw fault('url() protocols is empty. List at least one scheme.');
+        throw fault(urlProtocols, at('0.protocols'), {
+            correction: 'List at least one scheme.',
+            sentence: 'url() protocols is empty.',
+        });
     }
     // `Array.from` reads a hole as `undefined`, so a sparse list faults instead of skipping it.
-    return Array.from(items, (item) => {
+    return Array.from(items, (item, index) => {
         if (typeof item !== 'string' || !schemePattern.test(item)) {
-            throw fault(`url() protocols lists ${quote(item)}, which is not a scheme name. List a letter followed by letters, digits, +, -, or ., with no trailing colon.`);
+            throw fault(urlProtocols, at(`0.protocols.${String(index)}`), {
+                correction: 'List a letter followed by letters, digits, +, -, or ., with no trailing colon.',
+                sentence: `url() protocols lists ${quote(item)}, which is not a scheme name.`,
+            });
         }
         return item;
     });
@@ -37,12 +50,10 @@ function schemesPattern(protocols) {
 }
 /** An absolute RFC 3986 URI that the WHATWG parser also reads, optionally with a listed scheme. */
 function url(options) {
-    const protocols = protocolsOf(readOptions('url', options).protocols);
+    const protocols = protocolsOf(options, readOptions('url', options).protocols);
     // The WHATWG parser lowercases the scheme and ends `protocol` with a colon.
     const listed = new Set(protocols?.map((protocol) => `${protocol.toLowerCase()}:`));
-    const sentence = protocols === undefined
-        ? 'Expected an absolute URL, such as https://example.com.'
-        : `Expected an absolute URL with the scheme ${listing(protocols)}.`;
+    const issue = protocols === undefined ? urlIssue.issue({}) : urlSchemeIssue.issue({ protocols });
     return createValidator({
         inputSchema: {
             type: 'string',
@@ -51,12 +62,12 @@ function url(options) {
         },
         parse: (raw) => {
             if (!uriPattern.test(raw) || !URL.canParse(raw)) {
-                return reject(sentence);
+                return reject(issue);
             }
             const parsed = new URL(raw);
             return protocols === undefined || listed.has(parsed.protocol)
                 ? { value: parsed }
-                : reject(sentence);
+                : reject(issue);
         },
     });
 }

package/dist/uuid.js

@@ -1,13 +1,13 @@
+import { uuidIssue } from './codes.js';
 import { createValidator } from './create.js';
 import { reject } from './issues.js';
 const grouped = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/u;
 /** A UUID of any version in any letter case, read as lowercase so two spellings compare equal. */
 function uuid() {
+    const issue = uuidIssue.issue({});
     return createValidator({
         inputSchema: { type: 'string', format: 'uuid' },
-        parse: (raw) => grouped.test(raw)
-            ? { value: raw.toLowerCase() }
-            : reject('Expected a UUID, such as 123e4567-e89b-12d3-a456-426614174000.'),
+        parse: (raw) => grouped.test(raw) ? { value: raw.toLowerCase() } : reject(issue),
     });
 }
 export { uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcli/validators",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The Loom CLI validator catalog. Ships Standard Schema values for common command-line input shapes.",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
     "ajv-formats": "^3.0.1"
   },
   "peerDependencies": {
-    "@loomcli/core": "0.5.0"
+    "@loomcli/core": "0.6.0"
   },
   "engines": {
     "bun": ">=1.4.0",