@maroonedog/luq 0.1.1-alpha → 2.0.0

package/dist/plugins/stringUrl.d.ts

@@ -1,97 +1 @@
-import { ValidationOptions } from "../core/plugin/types";
-/**
- * @luq-plugin
- * @name stringUrl
- * @category standard
- * @description Validates that a string is a valid URL format
- * @allowedTypes ["string"]
- * @see https://developer.mozilla.org/en-US/docs/Web/API/URL - MDN URL API Reference
- * @see https://tools.ietf.org/html/rfc3986 - RFC 3986: Uniform Resource Identifier (URI) Generic Syntax
- * @example
- * ```typescript
- * // Basic usage - validates all URL formats (RFC 3986 compliant)
- * const validator = Builder()
- *   .use(stringUrlPlugin)
- *   .for<UserProfile>()
- *   .v("website", (b) => b.string.url())
- *   .v("profileUrl", (b) => b.string.required().url())
- *   .build();
- *
- * // Custom protocols (e.g., allow ftp://)
- * builder.v("ftpServer", b => b.string.url({
- *   protocols: ['ftp:', 'ftps:']
- * }))
- *
- * // Allow URLs without protocol (assumes https://)
- * builder.v("domain", b => b.string.url({
- *   allowWithoutProtocol: true
- * }))
- *
- * // ✅ VALID URL formats (RFC 3986)
- * validator.parse({ website: "https://example.com" });                    // Standard HTTPS
- * validator.parse({ website: "http://www.test.co.uk/path?q=value#frag" }); // Full URL with query and fragment
- * validator.parse({ website: "ftp://files.domain.com/file.txt" });        // FTP protocol
- * validator.parse({ website: "ws://localhost:3000" });                    // WebSocket protocol
- * validator.parse({ website: "https://subdomain.example.com:8080/api" }); // With port and path
- * validator.parse({ website: "https://127.0.0.1:3000" });                // IP address
- * validator.parse({ website: "https://[::1]:8080" });                    // IPv6 address
- * validator.parse({ website: "mailto:user@example.com" });                // mailto protocol
- * validator.parse({ website: "tel:+1-555-123-4567" });                   // tel protocol
- * validator.parse({ website: "https://user:pass@example.com" });          // With credentials
- *
- * // With allowWithoutProtocol: true
- * const flexValidator = builder.v("site", b => b.string.url({ allowWithoutProtocol: true }));
- * flexValidator.parse({ site: "example.com" });                          // Assumes https://
- * flexValidator.parse({ site: "www.domain.co.uk/path" });                // Assumes https://
- *
- * // ❌ INVALID URL formats
- * validator.parse({ website: "not-a-url" });              // Plain text
- * validator.parse({ website: "http://" });                // Missing host
- * validator.parse({ website: "://missing-protocol" });    // Missing protocol
- * validator.parse({ website: "https://" });               // Missing host after protocol
- * validator.parse({ website: "http://.com" });            // Invalid host
- * validator.parse({ website: "https://example." });       // Incomplete domain
- * validator.parse({ website: "just text with spaces" });  // Contains spaces
- * validator.parse({ website: "ftp://[invalid-ipv6]" });   // Invalid IPv6
- * validator.parse({ website: "https://exam ple.com" });   // Space in domain
- * validator.parse({ website: "" });                       // Empty string
- * ```
- * @params
- * - options?: StringUrlOptions - URL validation configuration
- *   - protocols?: string[] - Allowed protocols (default: all protocols allowed)
- *   - allowWithoutProtocol?: boolean - Allow URLs without protocol (default: false)
- *   - messageFactory?: (context: MessageContext) => string - Custom error message factory
- * @returns Validation function that returns true if string is a valid URL
- * @customError
- * ```typescript
- * .url({
- *   messageFactory: ({ path, value }) =>
- *     `${path} must be a valid URL (received: ${value})`
- * })
- *
- * // Restrict to specific protocols
- * .url({
- *   protocols: ['https:'],
- *   messageFactory: ({ path }) => `${path} must be a secure HTTPS URL`
- * })
- * ```
- * @since 0.1.0-alpha
- */
-export interface StringUrlOptions extends ValidationOptions {
-    /**
-     * Array of allowed protocols. Default: null (allow all protocols)
-     * @example ['http:', 'https:', 'ftp:', 'ws:', 'wss:']
-     */
-    protocols?: string[];
-    /**
-     * Whether to allow URLs without protocol (will default to https://)
-     * @default false
-     */
-    allowWithoutProtocol?: boolean;
-}
-export declare const stringUrlPlugin: import("../index").TypedPlugin<"stringUrl", "url", (options?: StringUrlOptions) => {
-    check: (value: any) => boolean;
-    code: string;
-    getErrorMessage: (value: any, path: string) => string;
-    params: StringUrlOptions[];
-}, readonly ["string"], "validator", "standard">;
+export * from "./string-url/index";

package/dist/plugins/stringUrl.js

@@ -1 +1,2 @@
-"use strict";var m=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var g=(e,t)=>{for(var r in t)m(e,r,{get:t[r],enumerable:!0})},c=(e,t,r,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of p(t))!d.call(e,o)&&o!==r&&m(e,o,{get:()=>t[o],enumerable:!(s=T(t,o))||s.enumerable});return e};var y=e=>c(m({},"__esModule",{value:!0}),e);var P={};g(P,{stringUrlPlugin:()=>h});module.exports=y(P);var f=(e,t,r,s)=>{let n=(a=>(...i)=>{let l=a(...i);return l&&typeof l=="object"&&"check"in l?{...l,pluginName:s}:l})(r);switch(e){case"conditional":return(a,...i)=>n(a,...i);case"fieldReference":return(a,...i)=>n(a,...i);case"multiFieldReference":return n;case"transform":return a=>n(a);case"arrayElement":return(a,...i)=>n(a,...i);case"context":return a=>n(a);default:return n}};function u(e){let{name:t,methodName:r,allowedTypes:s,category:o,impl:n}=e;return{name:t,methodName:r,allowedTypes:s,category:o,create:()=>f(o,r,n,t)}}var N="stringUrl",x=["string"],h=u({name:"stringUrl",methodName:"url",allowedTypes:x,category:"standard",impl:e=>{let t=e?.code||N,r=e?.protocols||null,s=e?.allowWithoutProtocol||!1,o=e?.messageFactory||(n=>"Invalid URL format");return{check:n=>{if(typeof n!="string")return!0;try{let a=n;s&&!n.includes("://")&&(a=`https://${n}`);let i=new URL(a);return!(r&&!r.includes(i.protocol))}catch{return!1}},code:t,getErrorMessage:(n,a)=>o({path:a,value:n,code:t}),params:e?[e]:[]}}});0&&(module.exports={stringUrlPlugin});
+"use strict";
+module.exports = require("./string-url/index");

package/dist/plugins/stringUrl.mjs

@@ -1 +1 @@
-var u=(t,o,r,i)=>{let e=(n=>(...a)=>{let l=n(...a);return l&&typeof l=="object"&&"check"in l?{...l,pluginName:i}:l})(r);switch(t){case"conditional":return(n,...a)=>e(n,...a);case"fieldReference":return(n,...a)=>e(n,...a);case"multiFieldReference":return e;case"transform":return n=>e(n);case"arrayElement":return(n,...a)=>e(n,...a);case"context":return n=>e(n);default:return e}};function m(t){let{name:o,methodName:r,allowedTypes:i,category:s,impl:e}=t;return{name:o,methodName:r,allowedTypes:i,category:s,create:()=>u(s,r,e,o)}}var T="stringUrl",p=["string"],c=m({name:"stringUrl",methodName:"url",allowedTypes:p,category:"standard",impl:t=>{let o=t?.code||T,r=t?.protocols||null,i=t?.allowWithoutProtocol||!1,s=t?.messageFactory||(e=>"Invalid URL format");return{check:e=>{if(typeof e!="string")return!0;try{let n=e;i&&!e.includes("://")&&(n=`https://${e}`);let a=new URL(n);return!(r&&!r.includes(a.protocol))}catch{return!1}},code:o,getErrorMessage:(e,n)=>s({path:n,value:e,code:o}),params:t?[t]:[]}}});export{c as stringUrlPlugin};
+export * from "./string-url/index.mjs";

package/dist/plugins/transform/index.d.ts

@@ -0,0 +1 @@
+export { transformPlugin } from "./transform";

package/dist/plugins/transform/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformPlugin = void 0;
+var transform_1 = require("./transform");
+Object.defineProperty(exports, "transformPlugin", { enumerable: true, get: function () { return transform_1.transformPlugin; } });

package/dist/plugins/transform/index.mjs

@@ -0,0 +1 @@
+export { transformPlugin } from "./transform.mjs";

package/dist/plugins/transform/transform.d.ts

@@ -0,0 +1,7 @@
+import type { MessageContextExtra } from "../../types";
+import type { SelfReader, TransformOut } from "../../plugin-kit/marker.types";
+export declare const transformPlugin: import("../../plugin-kit/plugin-definition").PluginDefinition<"transform", "transform", readonly ["string", "number", "boolean", "date", "array", "object", "union"], {
+    args: readonly [map: SelfReader<unknown>];
+    out: TransformOut;
+    context: MessageContextExtra;
+}>;

package/dist/plugins/transform/transform.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformPlugin = void 0;
+// ===========================================================================
+// L7  src/plugins/transform/transform.ts
+// `out: TransformOut` is the whole declaration: RuleForOut then DEMANDS that
+// build return a TransformRule, and the chain gives this method its own
+// signature `<R>(map: (value: Present<TValue, TState>) => R) => ...`, so the
+// output type becomes the chain's current type without a cast anywhere.
+//
+// Order is the engine's, not this plugin's (src/runtime/run-field.ts):
+// default -> presence -> gates -> checks -> transforms, and transforms run in
+// parse() only, and only when the field's checks all passed. That is 1.x's
+// mainline order (docs/legacy-spec/plugin-catalog-relational.md), now the ONLY
+// order — the plugin-registry fallback that ran transforms FIRST is gone.
+// A throwing map propagates, exactly as 1.x's mainline did.
+// ===========================================================================
+const create_rule_1 = require("../../plugin-kit/create-rule");
+const plugin_definition_1 = require("../../plugin-kit/plugin-definition");
+/** 1.x's allowedTypes for .transform(): tuple and any are not among them. */
+const TRANSFORM_SLOTS = [
+    "string",
+    "number",
+    "boolean",
+    "date",
+    "array",
+    "object",
+    "union",
+];
+exports.transformPlugin = (0, plugin_definition_1.definePlugin)()({
+    name: "transform",
+    method: "transform",
+    slots: TRANSFORM_SLOTS,
+    build: (_ctx, map) => (0, create_rule_1.transform)((value) => map(value)),
+});

package/dist/plugins/transform/transform.mjs

@@ -0,0 +1,32 @@
+// ===========================================================================
+// L7  src/plugins/transform/transform.ts
+// `out: TransformOut` is the whole declaration: RuleForOut then DEMANDS that
+// build return a TransformRule, and the chain gives this method its own
+// signature `<R>(map: (value: Present<TValue, TState>) => R) => ...`, so the
+// output type becomes the chain's current type without a cast anywhere.
+//
+// Order is the engine's, not this plugin's (src/runtime/run-field.ts):
+// default -> presence -> gates -> checks -> transforms, and transforms run in
+// parse() only, and only when the field's checks all passed. That is 1.x's
+// mainline order (docs/legacy-spec/plugin-catalog-relational.md), now the ONLY
+// order — the plugin-registry fallback that ran transforms FIRST is gone.
+// A throwing map propagates, exactly as 1.x's mainline did.
+// ===========================================================================
+import { transform } from "../../plugin-kit/create-rule.mjs";
+import { definePlugin } from "../../plugin-kit/plugin-definition.mjs";
+/** 1.x's allowedTypes for .transform(): tuple and any are not among them. */
+const TRANSFORM_SLOTS = [
+    "string",
+    "number",
+    "boolean",
+    "date",
+    "array",
+    "object",
+    "union",
+];
+export const transformPlugin = /*#__PURE__*/ definePlugin()({
+    name: "transform",
+    method: "transform",
+    slots: TRANSFORM_SLOTS,
+    build: (_ctx, map) => transform((value) => map(value)),
+});

package/dist/plugins/transform.d.ts

@@ -1,35 +1 @@
-/**
- * @luq-plugin
- * @name transform
- * @category transform
- * @description Transforms values after successful validation (type conversion, normalization, computed values)
- * @allowedTypes ["string", "number", "boolean", "array", "object", "date", "union"]
- * @example
- * ```typescript
- * // String transformation (lowercase)
- * const validator = Builder()
- *   .use(transformPlugin)
- *   .for<UserData>()
- *   .v("email", (b) =>
- *     b.string.required().email().transform(v => v.toLowerCase())
- *   )
- *   .build();
- *
- * // Number to string conversion
- * builder.v("age", b =>
- *   b.number.required().min(0).transform(v => String(v))
- * )
- *
- * // Array element transformation
- * builder.v("tags", b =>
- *   b.array.transform(tags => tags.map(t => t.trim().toLowerCase()))
- * )
- * ```
- * @params
- * - transformFn: (value: T) => U - Transform function that takes input value and returns transformed value
- * @returns Validation function with transformation
- * @customError
- * Transform plugin does not generate errors. Errors in transform function are treated as exceptions.
- * @since 0.1.0-alpha
- */
-export declare const transformPlugin: import("../index").TypedPlugin<"transform", "transform", import("../builder/plugins/plugin-interfaces").TransformPluginImplementation<any, any>, readonly ["string", "number", "boolean", "array", "object", "date", "union"], "validator", "transform">;
+export * from "./transform/index";

package/dist/plugins/transform.js

@@ -1 +1,2 @@
-"use strict";var l=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var T=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var g=(n,e)=>{for(var t in e)l(n,t,{get:e[t],enumerable:!0})},y=(n,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of T(e))!d.call(n,a)&&a!==t&&l(n,a,{get:()=>e[a],enumerable:!(i=p(e,a))||i.enumerable});return n};var c=n=>y(l({},"__esModule",{value:!0}),n);var x={};g(x,{transformPlugin:()=>h});module.exports=c(x);var f=(n,e,t,i)=>{let o=(r=>(...m)=>{let s=r(...m);return s&&typeof s=="object"&&"check"in s?{...s,pluginName:i}:s})(t);switch(n){case"conditional":return(r,...m)=>o(r,...m);case"fieldReference":return(r,...m)=>o(r,...m);case"multiFieldReference":return o;case"transform":return r=>o(r);case"arrayElement":return(r,...m)=>o(r,...m);case"context":return r=>o(r);default:return o}};function u(n){let{name:e,methodName:t,allowedTypes:i,category:a,impl:o}=n;return{name:e,methodName:t,allowedTypes:i,category:a,create:()=>f(a,t,o,e)}}var N=["string","number","boolean","array","object","date","union"],h=u({name:"transform",methodName:"transform",allowedTypes:N,category:"transform",impl:(n,e)=>{let t=e?.code||"transform";return{check:a=>!0,code:t,getErrorMessage:(a,o)=>"Transform operation failed",params:[n,e],__isTransform:!0,__transformFn:n}}});0&&(module.exports={transformPlugin});
+"use strict";
+module.exports = require("./transform/index");

package/dist/plugins/transform.mjs

@@ -1 +1 @@
-var u=(a,r,o,s)=>{let n=(e=>(...t)=>{let m=e(...t);return m&&typeof m=="object"&&"check"in m?{...m,pluginName:s}:m})(o);switch(a){case"conditional":return(e,...t)=>n(e,...t);case"fieldReference":return(e,...t)=>n(e,...t);case"multiFieldReference":return n;case"transform":return e=>n(e);case"arrayElement":return(e,...t)=>n(e,...t);case"context":return e=>n(e);default:return n}};function l(a){let{name:r,methodName:o,allowedTypes:s,category:i,impl:n}=a;return{name:r,methodName:o,allowedTypes:s,category:i,create:()=>u(i,o,n,r)}}var p=["string","number","boolean","array","object","date","union"],g=l({name:"transform",methodName:"transform",allowedTypes:p,category:"transform",impl:(a,r)=>{let o=r?.code||"transform";return{check:i=>!0,code:o,getErrorMessage:(i,n)=>"Transform operation failed",params:[a,r],__isTransform:!0,__transformFn:a}}});export{g as transformPlugin};
+export * from "./transform/index.mjs";

package/dist/plugins/tuple-builder/index.d.ts

@@ -0,0 +1,2 @@
+export { tupleBuilderPlugin } from "./tuple-builder";
+export type { TupleBuilderContext, TupleFailure } from "./tuple-builder";

package/dist/plugins/tuple-builder/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tupleBuilderPlugin = void 0;
+var tuple_builder_1 = require("./tuple-builder");
+Object.defineProperty(exports, "tupleBuilderPlugin", { enumerable: true, get: function () { return tuple_builder_1.tupleBuilderPlugin; } });

package/dist/plugins/tuple-builder/index.mjs

@@ -0,0 +1 @@
+export { tupleBuilderPlugin } from "./tuple-builder.mjs";

package/dist/plugins/tuple-builder/tuple-builder.d.ts

@@ -0,0 +1,21 @@
+import type { ElementChain, Unchanged } from "../../plugin-kit/marker.types";
+/** Which of the four failures happened. Legacy spelled these as four codes. */
+export type TupleFailure = "notArray" | "lengthMismatch" | "tooShort" | "element";
+export interface TupleBuilderContext {
+    readonly failure: TupleFailure;
+    readonly positionCount: number;
+    readonly index: number;
+    readonly actualLength: number;
+}
+/**
+ * WHICH argument positions carry a sub-chain cannot be recovered from a
+ * plugin's type at run time — a NarrowedChain and a RootPredicate are both
+ * plain functions once erased — so src/chain/collect-branch-rules.ts reads it
+ * from this declared field. definePlugin's spec does not carry it yet (see
+ * needsFromOthers), which is why it is spread on rather than passed in.
+ */
+export declare const tupleBuilderPlugin: import("../../plugin-kit/plugin-definition").PluginDefinition<"tupleBuilder", "builder", readonly ["tuple"], {
+    args: readonly [positions: readonly ElementChain[], rest?: ElementChain];
+    out: Unchanged;
+    context: TupleBuilderContext;
+}>;

package/dist/plugins/tuple-builder/tuple-builder.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tupleBuilderPlugin = void 0;
+// ===========================================================================
+// L7  src/plugins/tuple-builder/tuple-builder.ts
+// `b.tuple.builder([position0, position1, ...], rest?)`.
+//
+// Legacy semantics (docs/legacy-spec/plugin-catalog-structural.md#tupleBuilderPlugin):
+// positional element schemas, an optional rest schema reused for every surplus
+// element, exact length without a rest, at-least length with one, and per
+// element the failure carries that element's index.
+//
+// LEGACY BUG FIXED, and it is the whole plugin: legacy's tupleBuilder threw
+// `TypeError: Cannot read properties of undefined (reading 'addValidator')`
+// during build(), through the composable-directly mechanism that reached for a
+// `builder._executionPlan` nobody set. Tuple validation therefore never ran a
+// single line. It needs no separate mechanism here: positions are BRANCHES of
+// an ordinary composite, and the engine compiles them like any other branch.
+//
+// CONTRADICTION A-15: `positions` is an ARRAY of ElementChain markers, so both
+// marker resolvers must descend into the array and resolve each element.
+//
+// `b.tuple` gets no injected type guard (docs/legacy-spec/plugin-contract.md),
+// which is why this plugin — alone among the collection plugins — rejects a
+// non-array instead of passing it through.
+// ===========================================================================
+const plugin_definition_1 = require("../../plugin-kit/plugin-definition");
+const create_rule_1 = require("../../plugin-kit/create-rule");
+const types_1 = require("../../types");
+function checkLength(value, positionCount, hasRest) {
+    if (!hasRest && value.length !== positionCount) {
+        return (0, types_1.fail)({
+            branch: "lengthMismatch",
+            expected: positionCount,
+            actual: value.length,
+        });
+    }
+    if (hasRest && value.length < positionCount) {
+        return (0, types_1.fail)({
+            branch: "tooShort",
+            expected: positionCount,
+            actual: value.length,
+        });
+    }
+    return types_1.PASS;
+}
+/**
+ * Branch i is position i; the branch after the last position, when there is
+ * one, is the rest schema and every surplus element runs through it.
+ */
+function applyPositionally(runners, positionCount, hasRest) {
+    return (value, ctx) => {
+        if (!(0, types_1.isArray)(value)) {
+            return (0, types_1.fail)({ branch: "notArray", expected: "array", actual: value });
+        }
+        const lengthOutcome = checkLength(value, positionCount, hasRest);
+        if (!lengthOutcome.ok)
+            return lengthOutcome;
+        for (let index = 0; index < value.length; index += 1) {
+            const runner = index < positionCount ? runners[index] : runners[positionCount];
+            if (runner === undefined)
+                continue;
+            const outcome = runner.run(value[index], ctx);
+            if (!outcome.ok) {
+                return (0, types_1.fail)({
+                    ...outcome.detail,
+                    index,
+                    branch: "element",
+                    actual: value.length,
+                });
+            }
+        }
+        return types_1.PASS;
+    };
+}
+function readFailure(branchLabel) {
+    if (branchLabel === "notArray")
+        return "notArray";
+    if (branchLabel === "lengthMismatch")
+        return "lengthMismatch";
+    if (branchLabel === "tooShort")
+        return "tooShort";
+    return "element";
+}
+function describeFailure(failure, positionCount, actualLength, index) {
+    if (failure === "notArray")
+        return "Value must be an array";
+    if (failure === "lengthMismatch") {
+        return `Tuple must have exactly ${String(positionCount)} elements, got ${String(actualLength)}`;
+    }
+    if (failure === "tooShort") {
+        return `Tuple must have at least ${String(positionCount)} elements, got ${String(actualLength)}`;
+    }
+    return `Validation failed for element ${String(index)}`;
+}
+/**
+ * WHICH argument positions carry a sub-chain cannot be recovered from a
+ * plugin's type at run time — a NarrowedChain and a RootPredicate are both
+ * plain functions once erased — so src/chain/collect-branch-rules.ts reads it
+ * from this declared field. definePlugin's spec does not carry it yet (see
+ * needsFromOthers), which is why it is spread on rather than passed in.
+ */
+exports.tupleBuilderPlugin = (0, plugin_definition_1.definePlugin)()({
+    name: "tupleBuilder",
+    method: "builder",
+    slots: ["tuple"],
+    build: (ctx, positions, rest) => {
+        const branches = positions.map((rules, index) => (0, create_rule_1.branch)(`position:${String(index)}`, rules));
+        if (rest !== undefined)
+            branches.push((0, create_rule_1.branch)("rest", rest));
+        const positionCount = positions.length;
+        return (0, create_rule_1.composite)({
+            code: ctx.code,
+            messageFactory: ctx.messageFactory,
+            severity: ctx.severity,
+            branches,
+            combine: (runners) => applyPositionally(runners, positionCount, rest !== undefined),
+            describe: (detail) => describeFailure(readFailure(detail.branch), positionCount, (0, types_1.isNumber)(detail.actual) ? detail.actual : -1, detail.index ?? -1),
+            buildMessageContext: (detail) => ({
+                failure: readFailure(detail.branch),
+                positionCount,
+                index: detail.index ?? -1,
+                actualLength: (0, types_1.isNumber)(detail.actual) ? detail.actual : -1,
+            }),
+        });
+    },
+    subChainArguments: [0, 1],
+});

package/dist/plugins/tuple-builder/tuple-builder.mjs

@@ -0,0 +1,125 @@
+// ===========================================================================
+// L7  src/plugins/tuple-builder/tuple-builder.ts
+// `b.tuple.builder([position0, position1, ...], rest?)`.
+//
+// Legacy semantics (docs/legacy-spec/plugin-catalog-structural.md#tupleBuilderPlugin):
+// positional element schemas, an optional rest schema reused for every surplus
+// element, exact length without a rest, at-least length with one, and per
+// element the failure carries that element's index.
+//
+// LEGACY BUG FIXED, and it is the whole plugin: legacy's tupleBuilder threw
+// `TypeError: Cannot read properties of undefined (reading 'addValidator')`
+// during build(), through the composable-directly mechanism that reached for a
+// `builder._executionPlan` nobody set. Tuple validation therefore never ran a
+// single line. It needs no separate mechanism here: positions are BRANCHES of
+// an ordinary composite, and the engine compiles them like any other branch.
+//
+// CONTRADICTION A-15: `positions` is an ARRAY of ElementChain markers, so both
+// marker resolvers must descend into the array and resolve each element.
+//
+// `b.tuple` gets no injected type guard (docs/legacy-spec/plugin-contract.md),
+// which is why this plugin — alone among the collection plugins — rejects a
+// non-array instead of passing it through.
+// ===========================================================================
+import { definePlugin } from "../../plugin-kit/plugin-definition.mjs";
+import { branch, composite } from "../../plugin-kit/create-rule.mjs";
+import { fail, isArray, isNumber, PASS } from "../../types/index.mjs";
+function checkLength(value, positionCount, hasRest) {
+    if (!hasRest && value.length !== positionCount) {
+        return fail({
+            branch: "lengthMismatch",
+            expected: positionCount,
+            actual: value.length,
+        });
+    }
+    if (hasRest && value.length < positionCount) {
+        return fail({
+            branch: "tooShort",
+            expected: positionCount,
+            actual: value.length,
+        });
+    }
+    return PASS;
+}
+/**
+ * Branch i is position i; the branch after the last position, when there is
+ * one, is the rest schema and every surplus element runs through it.
+ */
+function applyPositionally(runners, positionCount, hasRest) {
+    return (value, ctx) => {
+        if (!isArray(value)) {
+            return fail({ branch: "notArray", expected: "array", actual: value });
+        }
+        const lengthOutcome = checkLength(value, positionCount, hasRest);
+        if (!lengthOutcome.ok)
+            return lengthOutcome;
+        for (let index = 0; index < value.length; index += 1) {
+            const runner = index < positionCount ? runners[index] : runners[positionCount];
+            if (runner === undefined)
+                continue;
+            const outcome = runner.run(value[index], ctx);
+            if (!outcome.ok) {
+                return fail({
+                    ...outcome.detail,
+                    index,
+                    branch: "element",
+                    actual: value.length,
+                });
+            }
+        }
+        return PASS;
+    };
+}
+function readFailure(branchLabel) {
+    if (branchLabel === "notArray")
+        return "notArray";
+    if (branchLabel === "lengthMismatch")
+        return "lengthMismatch";
+    if (branchLabel === "tooShort")
+        return "tooShort";
+    return "element";
+}
+function describeFailure(failure, positionCount, actualLength, index) {
+    if (failure === "notArray")
+        return "Value must be an array";
+    if (failure === "lengthMismatch") {
+        return `Tuple must have exactly ${String(positionCount)} elements, got ${String(actualLength)}`;
+    }
+    if (failure === "tooShort") {
+        return `Tuple must have at least ${String(positionCount)} elements, got ${String(actualLength)}`;
+    }
+    return `Validation failed for element ${String(index)}`;
+}
+/**
+ * WHICH argument positions carry a sub-chain cannot be recovered from a
+ * plugin's type at run time — a NarrowedChain and a RootPredicate are both
+ * plain functions once erased — so src/chain/collect-branch-rules.ts reads it
+ * from this declared field. definePlugin's spec does not carry it yet (see
+ * needsFromOthers), which is why it is spread on rather than passed in.
+ */
+export const tupleBuilderPlugin = /*#__PURE__*/ definePlugin()({
+    name: "tupleBuilder",
+    method: "builder",
+    slots: ["tuple"],
+    build: (ctx, positions, rest) => {
+        const branches = positions.map((rules, index) => branch(`position:${String(index)}`, rules));
+        if (rest !== undefined)
+            branches.push(branch("rest", rest));
+        const positionCount = positions.length;
+        return composite({
+            code: ctx.code,
+            messageFactory: ctx.messageFactory,
+            severity: ctx.severity,
+            branches,
+            combine: (runners) => applyPositionally(runners, positionCount, rest !== undefined),
+            describe: (detail) => describeFailure(readFailure(detail.branch), positionCount, isNumber(detail.actual) ? detail.actual : -1, detail.index ?? -1),
+            buildMessageContext: (detail) => ({
+                failure: readFailure(detail.branch),
+                positionCount,
+                index: detail.index ?? -1,
+                actualLength: isNumber(detail.actual) ? detail.actual : -1,
+            }),
+        });
+    },
+    subChainArguments: [0, 1],
+});

package/dist/plugins/tupleBuilder.d.ts

@@ -1,66 +1 @@
-/**
- * @luq-plugin
- * @name tupleBuilder
- * @category composable-directly
- * @description Validates tuple types (fixed-length arrays with different types for each element)
- * @allowedTypes ["tuple"]
- * @example
- * ```typescript
- * // Fixed-length tuple - no options needed
- * type Coordinates = [number, number];
- *
- * const validator = Builder()
- *   .use(tupleBuilderPlugin)
- *   .for<{ location: Coordinates }>()
- *   .v("location", (b) => b.tuple
- *     .required()
- *     .builder(
- *       (a) => a.number.required().min(0),
- *       (b) => b.number.required().min(0)
- *     )
- *   )
- *   .build();
- *
- * // Variable-length tuple with rest elements
- * type UserData = [string, number, boolean, ...string[]];
- *
- * const userValidator = Builder()
- *   .use(tupleBuilderPlugin)
- *   .for<{ data: UserData }>()
- *   .v("data", (b) => b.tuple
- *     .required()
- *     .builder(
- *       (a) => a.string.required().min(3),     // name
- *       (b) => b.number.required().min(0),     // age
- *       (c) => c.boolean.required(),           // isActive
- *       { rest: (r) => r.string.optional() }   // rest elements
- *     )
- *   )
- *   .build();
- * ```
- * @params
- * - ...builderFns: Array<(context: FieldBuilderContext) => any> - Builder functions for each tuple element
- * - options?: { rest?: (context: FieldBuilderContext) => any } - Optional configuration (automatically defaults to {} when omitted)
- * @returns Composable validation function
- * @customError
- * - Returns false if value is not an array
- * - Returns false if array length doesn't match tuple definition (without rest)
- * - Returns false if any element validation fails
- * @since 0.1.0-alpha
- */
-import type { FieldBuilderContext } from "../core/builder/plugins/plugin-types";
-export interface TupleBuilderFunction<TObject extends object, TPlugins> {
-    (context: FieldBuilderContext<TObject, TPlugins, any>): any;
-}
-export interface RestBuilderFunction<TObject extends object, TPlugins> {
-    (context: FieldBuilderContext<TObject, TPlugins, any>): any;
-}
-export interface TupleBuilderOptions<TObject extends object, TPlugins> {
-    rest?: RestBuilderFunction<TObject, TPlugins>;
-    messageFactory?: {
-        notArray?: (value: unknown) => string;
-        lengthMismatch?: (expected: number, actual: number) => string;
-        tooShort?: (minimum: number, actual: number) => string;
-    };
-}
-export declare const tupleBuilderPlugin: import("../builder/plugins/composable-directly-plugin").ComposableDirectlyPlugin<"tupleBuilder", "builder", readonly ["tuple"]>;
+export * from "./tuple-builder/index";

package/dist/plugins/tupleBuilder.js

@@ -1 +1,2 @@
-"use strict";var j=Object.defineProperty;var W=Object.getOwnPropertyDescriptor;var U=Object.getOwnPropertyNames;var I=Object.prototype.hasOwnProperty;var z=(n,e)=>{for(var o in e)j(n,o,{get:e[o],enumerable:!0})},H=(n,e,o,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of U(e))!I.call(n,t)&&t!==o&&j(n,t,{get:()=>e[t],enumerable:!(r=W(e,t))||r.enumerable});return n};var G=n=>H(j({},"__esModule",{value:!0}),n);var Z={};z(Z,{tupleBuilderPlugin:()=>X});module.exports=G(Z);var V=Object.freeze({valid:!0}),x=Object.freeze({valid:!1});function O(n,e=[],o){return{_validators:n,_transforms:e,validate:o||(r=>{for(let t=0;t<e.length;t++)if(!n[t].check(r,r))return x;return V})}}function P(n,e,o){return{check:e,name:n,inputType:o?.inputType,outputType:o?.outputType,metadata:o?{severity:o.severity||"error",async:o.async||!1}:void 0}}function R(n,e,o,r){return{name:n,methodName:e,allowedTypes:o,category:"composable",createComposer(t,a){let i=[],d={add(s){return i.push(s),d},build(){return r(i,t,a)}},y=d;return y[e]=function(...s){return y.add(s)},y}}}function E(n,e,o,r){let t=e.methodName,a=null,i=null;n[t]=function(...d){if(a||(a=e.createComposer(o,r)),a.add(d),n[t]=a[t],a){i=a.build();let y=n._executionPlan;if(!(y&&i&&typeof i.validate=="function")){if(i&&i._validators)for(let s of i._validators)y.addValidator(s.name,(l,g)=>{let f=s.check(l,l);return{valid:f,message:f?void 0:`Validation failed for ${s.name}`}})}}return n}}function L(n,e,o,r){return{...R(n,e,o,r),category:"composable-directly"}}function Y(n){switch(n){case"string":return{check:e=>e==null?!0:typeof e=="string",name:"stringType",messageFactory:()=>"Expected string",inputType:"string",outputType:"string",metadata:{severity:"error",async:!1}};case"number":return{check:e=>e==null?!0:typeof e=="number"&&!isNaN(e),name:"numberType",messageFactory:()=>"Expected number",inputType:"number",outputType:"number",metadata:{severity:"error",async:!1}};case"boolean":return{check:e=>e==null?!0:typeof e=="boolean",name:"booleanType",messageFactory:()=>"Expected boolean",inputType:"boolean",outputType:"boolean",metadata:{severity:"error",async:!1}};case"array":return{check:e=>e==null?!0:Array.isArray(e),name:"arrayType",messageFactory:()=>"Expected array",inputType:"array",outputType:"array",metadata:{severity:"error",async:!1}};case"object":return{check:e=>e==null?!0:typeof e=="object"&&e!==null&&!Array.isArray(e),name:"objectType",messageFactory:()=>"Expected object",inputType:"object",outputType:"object",metadata:{severity:"error",async:!1}};case"date":return{check:e=>e==null?!0:e instanceof Date,name:"dateType",messageFactory:()=>"Expected Date",inputType:"date",outputType:"date",metadata:{severity:"error",async:!1}};case"null":return{check:e=>e===null,name:"nullType",messageFactory:()=>"Expected null",inputType:"null",outputType:"null",metadata:{severity:"error",async:!1}};case"any":return{check:()=>!0,name:"anyType",messageFactory:()=>"",inputType:"any",outputType:"any",metadata:{severity:"error",async:!1}};default:return null}}function m(n,e,o,r){let t=r?.validators?[...r.validators]:[];if(!r&&n!=="union"){let d=Y(n);d&&t.push(d)}let a=r?.transforms?[...r.transforms]:[],i={_type:n,_fieldPath:e,_validators:t,_transforms:a,build(){return n==="union"&&t.length===0&&t.push({check:()=>!1,name:"unionGuard",messageFactory:()=>"No union type guards defined",inputType:"union",outputType:"union",metadata:{severity:"error",async:!1}}),{_validators:t,_transforms:a}}};return K(i,n,e,o,t,a),i.refineString=()=>m("string",e,o,{validators:t,transforms:a}),i.refineNumber=()=>m("number",e,o,{validators:t,transforms:a}),i.refineBoolean=()=>m("boolean",e,o,{validators:t,transforms:a}),i.refineArray=()=>m("array",e,o,{validators:t,transforms:a}),i.refineObject=()=>m("object",e,o,{validators:t,transforms:a}),i.refineTuple=()=>m("tuple",e,o,{validators:t,transforms:a}),i.refineUnion=()=>m("union",e,o,{validators:t,transforms:a}),i.refineDate=()=>m("date",e,o,{validators:t,transforms:a}),i.refineAny=()=>m("any",e,o,{validators:t,transforms:a}),i}function K(n,e,o,r,t,a){let i=Object.entries(r),d=i.length;for(let y=0;y<d;y++){let[,s]=i[y];if(!s||typeof s!="object")continue;if(s.category?.startsWith("composable")){if(s.allowedTypes&&!s.allowedTypes.includes(e))continue;E(n,s,o,r);continue}if(typeof s.create!="function"||s.allowedTypes&&!s.allowedTypes.includes(e))continue;let{methodName:l,category:g="standard",name:f}=s,b=s.create();n[l]=function(...w){try{let h=b(...w);if(g==="transform"){let N=q(h,w[0]);a.push(N)}else{let N=J(h,o),M=Q(N,f||l,e,w,h);t.push(M)}}catch{}return n}}}function q(n,e){return typeof n=="function"?e:n?.__isTransform?n.__transformFn:n?.__isCoerce?o=>n.coerce.coerceFn(o):n?.__isDefault?(o,r)=>n.default.applyDefault(o,r):n?.__isPreprocess?(o,r)=>n.preprocess.applyPreprocess(o,r):e||(o=>o)}function J(n,e){return typeof n=="function"?(o,r)=>n(o,{path:e,allValues:r}).valid:n?.check?(o,r)=>n.check(o,r):()=>!1}function Q(n,e,o,r,t){let a={check:n,name:e,code:t?.code||e,pluginName:t?.pluginName||e,getErrorMessage:t?.getErrorMessage,messageFactory:r[r.length-1]?.messageFactory||t?.messageFactory||(()=>"Validation failed"),inputType:o,outputType:o,metadata:t?.metadata||{severity:"error",async:!1}};return t&&(t.shouldSkipAllValidation&&(a.shouldSkipAllValidation=t.shouldSkipAllValidation),t.shouldSkipValidation&&(a.shouldSkipValidation=t.shouldSkipValidation),t.shouldSkipFurtherValidation&&(a.shouldSkipFurtherValidation=t.shouldSkipFurtherValidation),t.skipForNull!==void 0&&(a.skipForNull=t.skipForNull),t.skipForUndefined!==void 0&&(a.skipForUndefined=t.skipForUndefined),t.__isRecursive&&(a.__isRecursive=t.__isRecursive),t.recursive&&(a.recursive=t.recursive)),a}function v(n,e){let o=m("string",n,e),r=m("number",n,e),t=m("boolean",n,e),a=m("array",n,e),i=m("object",n,e),d=m("union",n,e),y=m("tuple",n,e),s=m("date",n,e),l=m("any",n,e);return{string:o,number:r,boolean:t,date:s,array:a,tuple:y,union:d,object:i,any:l}}var D=Array.isArray,S=Object.freeze({code:"TUPLE_NOT_ARRAY",message:"Value must be an array"}),_=Object.freeze({code:"TUPLE_LENGTH_MISMATCH",prefix:"Tuple must have exactly",suffix:"elements, got"}),B=Object.freeze({code:"TUPLE_TOO_SHORT",prefix:"Tuple must have at least",suffix:"elements, got"}),X=L("tupleBuilder","builder",["tuple"],(n,e,o)=>{let r=n[0]||[];if(r.length===0)return O([P("tupleBuilder",()=>!1,{inputType:"tuple",outputType:"tuple"})]);let t=[],a,i=r.length,d=r[i-1],y=d&&typeof d=="object"&&typeof d!="function"&&(Object.prototype.hasOwnProperty.call(d,"rest")||Object.keys(d).length===0),s={};y?(t=r.slice(0,-1),s=d,a=s.rest):t=r;let l=t.length,g=!!a,f=new Array(l);for(let u=0;u<l;u++){let c=v(`${e}[${u}]`,o),p=t[u](c);p&&typeof p.build=="function"?f[u]=p.build():f[u]=null}let b=null;if(a){let u=v(`${e}[rest]`,o),c=a(u);c&&typeof c.build=="function"&&(b=c.build())}let w=u=>{if(u.length!==l)return!1;for(let c=0;c<l;c++){let p=f[c];if(p&&!p.validate(u[c]).valid)return!1}return!0},h=u=>{let c=u.length;if(c<l)return!1;for(let p=0;p<l;p++){let T=f[p];if(T&&!T.validate(u[p]).valid)return!1}if(b&&c>l){for(let p=l;p<c;p++)if(!b.validate(u[p]).valid)return!1}return!0},N=P("tupleBuilder",u=>D(u)?g?h(u):w(u):!1,{inputType:"tuple",outputType:"tuple",severity:"error",async:!1});return O([N],[],u=>{if(!D(u))return{...x,errors:[{path:e,message:s.messageFactory?.notArray?s.messageFactory.notArray(u):S.message,code:S.code}]};let c=u.length;if(!g&&c!==l)return{...x,errors:[{path:e,message:s.messageFactory?.lengthMismatch?s.messageFactory.lengthMismatch(l,c):`${_.prefix} ${l} ${_.suffix} ${c}`,code:_.code}]};if(g&&c<l)return{...x,errors:[{path:e,message:s.messageFactory?.tooShort?s.messageFactory.tooShort(l,c):`${B.prefix} ${l} ${B.suffix} ${c}`,code:B.code}]};let p=[];for(let T=0;T<l;T++){let C=f[T];if(C){let F=u[T],k=C.validate(F,u);if(!k.isValid()){let A=`${e}[${T}]`;if(k.errors&&k.errors.length>0)for(let $ of k.errors)p.push({...$,path:A});else p.push({path:A,message:`Validation failed for element ${T}`,code:"ELEMENT_INVALID"})}}}if(b&&c>l)for(let T=l;T<c;T++){let C=b.validate(u[T]);if(!C.valid&&C.errors){let F=`${e}[${T}]`;for(let k of C.errors)p.push({...k,path:F})}}return p.length>0?{...x,errors:p}:V})});0&&(module.exports={tupleBuilderPlugin});
+"use strict";
+module.exports = require("./tuple-builder/index");