@sdxc/spec 0.0.0-pre.1

package/dist/plugins/sample.js

@@ -0,0 +1,400 @@
+/**
+ * The built-in `sample` capability: generated input for a spec that needs a
+ * name, an address, or fifty of something, without a literal typed into the
+ * suite. Every tool draws from the test's own stream, so the same test sees
+ * the same values on every run whatever else the suite is doing.
+ *
+ * A call target carries at most one dot, so a module reaches a spec as one
+ * zero-argument tool returning every field that module generates —
+ * `let who = sample.person` then `who.job_title`. Generators that need an
+ * argument keep a tool of their own. Fields are named the way a spec names
+ * things, in snake case.
+ *
+ * The tools are actions rather than observations: a draw advances the stream,
+ * and polling `eventually` until a random value matches is never what an
+ * author meant. None needs a permission — generation is computation, reaching
+ * nothing outside the process.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { createSample } from "@sdxc/sample";
+import { ToolError } from "../errors.js";
+/** One module, as the record a spec binds and reads fields off. */
+const MODULE_TOOLS = [
+    "person",
+    "internet",
+    "location",
+    "company",
+    "lorem",
+    "date",
+    "string",
+    "number",
+    "color",
+    "datatype",
+    "git",
+    "hacker",
+    "phone",
+    "system",
+];
+/** The generators that need an argument, plus the two shortest shortcuts. */
+const CALL_TOOLS = ["email", "uuid", "int", "float", "words", "pick"];
+/** One line of documentation per module tool, shown in diagnostics. */
+const MODULE_SUMMARIES = {
+    person: "A person: names, titles, sex, job, contact details.",
+    internet: "Addresses, handles, links, and protocol values.",
+    location: "A place: country, city, street, postcode, coordinates.",
+    company: "A company name and the phrases around it.",
+    lorem: "Placeholder prose in every shape.",
+    date: "Instants around the test's own start time, as ISO timestamps.",
+    string: "Identifiers and character runs.",
+    number: "Numbers, in every base.",
+    color: "A color, as a name and in each notation.",
+    datatype: "A boolean.",
+    git: "A branch, a hash, a message, a whole log entry.",
+    hacker: "Technical-sounding filler.",
+    phone: "A phone number in each format, and an IMEI.",
+    system: "File names, paths, types, and machine identifiers.",
+};
+const DESCRIPTORS = [
+    ...MODULE_TOOLS.map((name) => ({
+        name,
+        summary: MODULE_SUMMARIES[name],
+        kind: "action",
+        params: [],
+    })),
+    {
+        name: "email",
+        summary: "An email address on a domain reserved for documentation.",
+        kind: "action",
+        params: [],
+    },
+    {
+        name: "uuid",
+        summary: "A version 4 UUID, drawn from the test's stream.",
+        kind: "action",
+        params: [],
+    },
+    {
+        name: "int",
+        summary: "An integer between two bounds, both included.",
+        kind: "action",
+        params: [
+            { name: "min", kind: "value", required: true, summary: "Lowest value, included." },
+            { name: "max", kind: "value", required: true, summary: "Highest value, included." },
+        ],
+    },
+    {
+        name: "float",
+        summary: "A number between two bounds, with two decimals.",
+        kind: "action",
+        params: [
+            { name: "min", kind: "value", required: true, summary: "Lowest value, included." },
+            { name: "max", kind: "value", required: true, summary: "Highest value, excluded." },
+        ],
+    },
+    {
+        name: "words",
+        summary: "Placeholder prose of a given number of words.",
+        kind: "action",
+        params: [
+            { name: "count", kind: "value", required: true, summary: "How many words to return." },
+        ],
+    },
+    {
+        name: "pick",
+        summary: "One element of a list.",
+        kind: "action",
+        params: [{ name: "list", kind: "value", required: true, summary: "The list to pick from." }],
+    },
+];
+/**
+ * Create the built-in `sample` plugin (namespace `"sample"`). Values come from
+ * the stream on the call's context, so two runs of one test generate the same
+ * data and two tests never draw from each other's stream.
+ */
+export function createSamplePlugin() {
+    return {
+        namespace: "sample",
+        describe() {
+            return DESCRIPTORS;
+        },
+        async call(tool, args, context) {
+            if (!isSampleTool(tool)) {
+                let available = [...MODULE_TOOLS, ...CALL_TOOLS].join(", ");
+                return failure(new ToolError(`sample has no tool "${tool}"; available tools: ${available}`));
+            }
+            return generate(tool, args, context);
+        },
+    };
+}
+function isSampleTool(tool) {
+    return (MODULE_TOOLS.includes(tool) ||
+        CALL_TOOLS.includes(tool));
+}
+function isModuleTool(tool) {
+    return MODULE_TOOLS.includes(tool);
+}
+/**
+ * Run one tool against the test's stream. The generator throws a `RangeError`
+ * on a bound it cannot honor; every throw becomes a `ToolError` naming the
+ * tool, since a plugin reports failure as a result rather than an exception.
+ */
+function generate(tool, args, context) {
+    let sample = createSample({ seed: context.random, now: context.now });
+    try {
+        if (isModuleTool(tool))
+            return success(record(tool, sample));
+        if (tool === "email")
+            return success(sample.internet.email());
+        if (tool === "uuid")
+            return success(sample.string.uuid());
+        if (tool === "int") {
+            let min = readNumber(args, 0);
+            if (min === undefined)
+                return numberError(tool, "min");
+            let max = readNumber(args, 1);
+            if (max === undefined)
+                return numberError(tool, "max");
+            return success(sample.number.int({ min, max }));
+        }
+        if (tool === "float") {
+            let min = readNumber(args, 0);
+            if (min === undefined)
+                return numberError(tool, "min");
+            let max = readNumber(args, 1);
+            if (max === undefined)
+                return numberError(tool, "max");
+            return success(sample.number.float({ min, max }));
+        }
+        if (tool === "words") {
+            let count = readNumber(args, 0);
+            if (count === undefined)
+                return numberError(tool, "count");
+            return success(sample.lorem.words(count));
+        }
+        let list = args[0];
+        if (list === undefined || list.kind !== "value" || !Array.isArray(list.value)) {
+            return failure(new ToolError("sample.pick needs a list to pick from."));
+        }
+        if (list.value.length === 0) {
+            return failure(new ToolError("sample.pick needs a list with at least one item."));
+        }
+        return success(sample.helpers.pick(list.value));
+    }
+    catch (error) {
+        let reason = error instanceof Error ? error.message : String(error);
+        return failure(new ToolError(`sample.${tool} could not generate a value: ${reason}`));
+    }
+}
+/** Build one module's record, every field named as a spec names things. */
+function record(tool, sample) {
+    if (tool === "person") {
+        let person = sample.person.record();
+        return {
+            first_name: person.firstName,
+            last_name: person.lastName,
+            middle_name: sample.person.middleName(),
+            full_name: person.fullName,
+            prefix: sample.person.prefix(),
+            suffix: sample.person.suffix(),
+            sex: person.sex,
+            gender: sample.person.gender(),
+            zodiac_sign: sample.person.zodiacSign(),
+            job_area: sample.person.jobArea(),
+            job_descriptor: sample.person.jobDescriptor(),
+            job_type: sample.person.jobType(),
+            job_title: person.jobTitle,
+            bio: sample.person.bio(),
+            email: person.email,
+            username: person.username,
+            phone: person.phone,
+        };
+    }
+    if (tool === "internet") {
+        return {
+            email: sample.internet.email(),
+            username: sample.internet.username(),
+            display_name: sample.internet.displayName(),
+            domain_name: sample.internet.domainName(),
+            domain_suffix: sample.internet.domainSuffix(),
+            domain_word: sample.internet.domainWord(),
+            url: sample.internet.url(),
+            password: sample.internet.password(),
+            emoji: sample.internet.emoji(),
+            http_method: sample.internet.httpMethod(),
+            http_status_code: sample.internet.httpStatusCode(),
+            ip: sample.internet.ip(),
+            ipv4: sample.internet.ipv4(),
+            ipv6: sample.internet.ipv6(),
+            mac: sample.internet.mac(),
+            port: sample.internet.port(),
+            protocol: sample.internet.protocol(),
+            jwt: sample.internet.jwt(),
+            jwt_algorithm: sample.internet.jwtAlgorithm(),
+            user_agent: sample.internet.userAgent(),
+        };
+    }
+    if (tool === "location") {
+        /**
+         * Built from one set of parts rather than field by field, so a spec that
+         * reads the country and the postal address off the same record sees one
+         * place rather than two.
+         */
+        let country = sample.location.country();
+        let city = sample.location.city({ country });
+        let streetAddress = sample.location.streetAddress();
+        let zipCode = sample.location.zipCode();
+        return {
+            country,
+            city,
+            country_code: sample.location.countryCode(),
+            continent: sample.location.continent(),
+            state: sample.location.state(),
+            state_abbreviation: sample.location.state({ abbreviated: true }),
+            county: sample.location.county(),
+            street: sample.location.street(),
+            building_number: sample.location.buildingNumber(),
+            street_address: streetAddress,
+            secondary_address: sample.location.secondaryAddress(),
+            zip_code: zipCode,
+            postal_address: `${streetAddress}, ${city} ${zipCode}, ${country}`,
+            direction: sample.location.direction(),
+            cardinal_direction: sample.location.cardinalDirection(),
+            ordinal_direction: sample.location.ordinalDirection(),
+            language: sample.location.language(),
+            time_zone: sample.location.timeZone(),
+            latitude: sample.location.latitude(),
+            longitude: sample.location.longitude(),
+        };
+    }
+    if (tool === "company") {
+        return {
+            name: sample.company.name(),
+            catch_phrase: sample.company.catchPhrase(),
+            catch_phrase_adjective: sample.company.catchPhraseAdjective(),
+            catch_phrase_descriptor: sample.company.catchPhraseDescriptor(),
+            catch_phrase_noun: sample.company.catchPhraseNoun(),
+            buzz_phrase: sample.company.buzzPhrase(),
+            buzz_adjective: sample.company.buzzAdjective(),
+            buzz_noun: sample.company.buzzNoun(),
+            buzz_verb: sample.company.buzzVerb(),
+        };
+    }
+    if (tool === "lorem") {
+        return {
+            word: sample.lorem.word(),
+            words: sample.lorem.words(5),
+            sentence: sample.lorem.sentence(),
+            paragraph: sample.lorem.paragraph(),
+            lines: sample.lorem.lines(3),
+            slug: sample.lorem.slug(),
+            text: sample.lorem.text(),
+        };
+    }
+    if (tool === "date") {
+        return {
+            past: sample.date.past().toISOString(),
+            future: sample.date.future().toISOString(),
+            recent: sample.date.recent().toISOString(),
+            soon: sample.date.soon().toISOString(),
+            anytime: sample.date.anytime().toISOString(),
+            birthdate: sample.date.birthdate().toISOString(),
+            month: sample.date.month(),
+            weekday: sample.date.weekday(),
+            time_zone: sample.date.timeZone(),
+        };
+    }
+    if (tool === "string") {
+        return {
+            uuid: sample.string.uuid(),
+            ulid: sample.string.ulid(),
+            nanoid: sample.string.nanoid(),
+            alpha: sample.string.alpha(10),
+            alphanumeric: sample.string.alphanumeric(10),
+            numeric: sample.string.numeric(10),
+            hexadecimal: sample.string.hexadecimal(16),
+            binary: sample.string.binary(8),
+            octal: sample.string.octal(8),
+            symbol: sample.string.symbol(4),
+            sample: sample.string.sample(10),
+        };
+    }
+    if (tool === "number") {
+        return {
+            int: sample.number.int(),
+            float: sample.number.float(),
+            hex: sample.number.hex(),
+            binary: sample.number.binary(),
+            octal: sample.number.octal(),
+            roman_numeral: sample.number.romanNumeral(),
+            big_int: String(sample.number.bigInt()),
+        };
+    }
+    if (tool === "color") {
+        return {
+            human: sample.color.human(),
+            hex: String(sample.color.rgb()),
+            rgb: String(sample.color.rgb({ format: "css" })),
+            hsl: String(sample.color.hsl({ format: "css" })),
+            space: sample.color.space(),
+            css_function: sample.color.cssSupportedFunction(),
+        };
+    }
+    if (tool === "datatype") {
+        return { boolean: sample.datatype.boolean() };
+    }
+    if (tool === "git") {
+        return {
+            branch: sample.git.branch(),
+            commit_sha: sample.git.commitSha(),
+            short_sha: sample.git.commitSha({ length: 7 }),
+            commit_message: sample.git.commitMessage(),
+            commit_date: sample.git.commitDate(),
+            commit_entry: sample.git.commitEntry(),
+        };
+    }
+    if (tool === "hacker") {
+        return {
+            abbreviation: sample.hacker.abbreviation(),
+            adjective: sample.hacker.adjective(),
+            noun: sample.hacker.noun(),
+            verb: sample.hacker.verb(),
+            ingverb: sample.hacker.ingverb(),
+            phrase: sample.hacker.phrase(),
+        };
+    }
+    if (tool === "phone") {
+        return {
+            number: sample.phone.number(),
+            national: sample.phone.number({ style: "national" }),
+            international: sample.phone.number({ style: "international" }),
+            imei: sample.phone.imei(),
+        };
+    }
+    return {
+        file_name: sample.system.fileName(),
+        file_ext: sample.system.fileExt(),
+        file_type: sample.system.fileType(),
+        common_file_name: sample.system.commonFileName(),
+        common_file_ext: sample.system.commonFileExt(),
+        common_file_type: sample.system.commonFileType(),
+        mime_type: sample.system.mimeType(),
+        directory_path: sample.system.directoryPath(),
+        file_path: sample.system.filePath(),
+        network_interface: sample.system.networkInterface(),
+        semver: sample.system.semver(),
+        cron: sample.system.cron(),
+    };
+}
+/** Read a positional argument as a number, or `undefined` when it is not one. */
+function readNumber(args, index) {
+    let argument = args[index];
+    if (argument === undefined || argument.kind !== "value")
+        return undefined;
+    return typeof argument.value === "number" ? argument.value : undefined;
+}
+function numberError(tool, name) {
+    return failure(new ToolError(`sample.${tool} needs a number for "${name}".`));
+}

package/dist/plugins/url.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The built-in `url` capability: pure, permissionless parsing of an absolute
+ * URL string into a query-string parameter, a fragment parameter, the path, or
+ * the host. It lets a spec read a value out of a URL it already holds — most
+ * often the authorization `code` in the redirect URL a `browser.url`
+ * observation returned after an OAuth authorize step. Every tool is a pure
+ * computation, so all are `observable` and need no permission grant.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Plugin } from "../plugin.js";
+/**
+ * Create the built-in `url` plugin (namespace `"url"`). Every tool parses its
+ * first argument as an absolute URL; a non-string argument, an unparseable
+ * URL, or a missing `query`/`fragment` parameter is a {@link ToolError}.
+ */
+export declare function createUrlPlugin(): Plugin;

package/dist/plugins/url.js

@@ -0,0 +1,126 @@
+/**
+ * The built-in `url` capability: pure, permissionless parsing of an absolute
+ * URL string into a query-string parameter, a fragment parameter, the path, or
+ * the host. It lets a spec read a value out of a URL it already holds — most
+ * often the authorization `code` in the redirect URL a `browser.url`
+ * observation returned after an OAuth authorize step. Every tool is a pure
+ * computation, so all are `observable` and need no permission grant.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { ToolError } from "../errors.js";
+const URL_TOOLS = ["query", "fragment", "path", "host"];
+const DESCRIPTORS = [
+    {
+        name: "query",
+        summary: "Read the value of a query-string parameter from an absolute URL.",
+        kind: "observable",
+        params: [
+            { name: "url", kind: "value", required: true, summary: "The absolute URL to read." },
+            { name: "name", kind: "value", required: true, summary: "The query parameter to return." },
+        ],
+    },
+    {
+        name: "fragment",
+        summary: "Read the value of a parameter from a URL's fragment (after the #).",
+        kind: "observable",
+        params: [
+            { name: "url", kind: "value", required: true, summary: "The absolute URL to read." },
+            { name: "name", kind: "value", required: true, summary: "The fragment parameter to return." },
+        ],
+    },
+    {
+        name: "path",
+        summary: "Read an absolute URL's pathname.",
+        kind: "observable",
+        params: [{ name: "url", kind: "value", required: true, summary: "The absolute URL to read." }],
+    },
+    {
+        name: "host",
+        summary: "Read an absolute URL's host, including the port when present.",
+        kind: "observable",
+        params: [{ name: "url", kind: "value", required: true, summary: "The absolute URL to read." }],
+    },
+];
+/**
+ * Create the built-in `url` plugin (namespace `"url"`). Every tool parses its
+ * first argument as an absolute URL; a non-string argument, an unparseable
+ * URL, or a missing `query`/`fragment` parameter is a {@link ToolError}.
+ */
+export function createUrlPlugin() {
+    return {
+        namespace: "url",
+        describe() {
+            return DESCRIPTORS;
+        },
+        async call(tool, args) {
+            if (!isUrlTool(tool)) {
+                return failure(new ToolError(`url has no tool "${tool}"; available tools: ${URL_TOOLS.join(", ")}`));
+            }
+            if (tool === "query" || tool === "fragment")
+                return param(tool, args);
+            return part(tool, args);
+        },
+    };
+}
+function isUrlTool(tool) {
+    return URL_TOOLS.includes(tool);
+}
+/**
+ * A fragment parses as a query string, the shape an implicit/hybrid OAuth flow
+ * returns its tokens in. An absent parameter is a tool error naming both the
+ * parameter and the URL, so a spec fails loud at the point of the lookup.
+ */
+function param(tool, args) {
+    let url = readUrl(tool, args);
+    if (isFailure(url))
+        return url;
+    let name = readName(tool, args);
+    if (isFailure(name))
+        return name;
+    let params = tool === "query" ? url.data.searchParams : new URLSearchParams(url.data.hash.replace(/^#/, ""));
+    let found = params.get(name.data);
+    if (found === null) {
+        let where = tool === "query" ? "query string" : "fragment";
+        return failure(new ToolError(`url.${tool} found no ${where} parameter "${name.data}" in the URL ${args0Raw(args)}`));
+    }
+    return success(found);
+}
+function part(tool, args) {
+    let url = readUrl(tool, args);
+    if (isFailure(url))
+        return url;
+    return success(tool === "path" ? url.data.pathname : url.data.host);
+}
+/**
+ * Validate and parse the first argument as an absolute URL. A missing
+ * argument, a non-string argument, or an unparseable URL is a tool error.
+ */
+function readUrl(tool, args) {
+    let first = args[0];
+    if (first === undefined || first.kind !== "value" || typeof first.value !== "string") {
+        return failure(new ToolError(`url.${tool} requires its first argument to be a URL string`));
+    }
+    try {
+        return success(new URL(first.value));
+    }
+    catch {
+        return failure(new ToolError(`url.${tool} could not parse the URL "${first.value}"`));
+    }
+}
+function readName(tool, args) {
+    let second = args[1];
+    if (second === undefined || second.kind !== "value" || typeof second.value !== "string") {
+        return failure(new ToolError(`url.${tool} requires its second argument to be a parameter name`));
+    }
+    return success(second.value);
+}
+function args0Raw(args) {
+    let first = args[0];
+    if (first !== undefined && first.kind === "value" && typeof first.value === "string") {
+        return first.value;
+    }
+    return "the URL";
+}