@maroonedog/luq 0.1.2-alpha → 2.0.0

package/dist/plugin-kit/index.mjs

@@ -0,0 +1,23 @@
+// ===========================================================================
+// src/plugin-kit/index.ts — THE ./plugin-kit SUBPATH.
+//
+// Everything a plugin author may import, and nothing else. A plugin under
+// src/plugins/** imports these modules by relative path; a plugin published
+// OUTSIDE this repository imports this subpath. The two must name the same
+// set, so this barrel re-exports exactly the modules the isolation gate
+// permits an isolated-tier plugin to reach: plugin-kit itself, the L0
+// vocabulary, and the L1 path vocabulary.
+//
+// Re-exports only; nothing is defined here.
+// ===========================================================================
+export * from "./compiled-rule.mjs";
+export * from "./create-conditional-presence.mjs";
+export * from "./create-rule.mjs";
+export * from "./external-context.mjs";
+export * from "./is-json-value-equal.mjs";
+export * from "./marker.types.mjs";
+export * from "./plugin-definition.mjs";
+export * from "./rule-build-context.mjs";
+export * from "./runtime-args.types.mjs";
+// ---- the vocabulary a rule reads its value and its context with -----------
+export * from "../types/index.mjs";

package/dist/plugin-kit/is-json-value-equal.d.ts

@@ -0,0 +1,10 @@
+/** NaN equals NaN; +0 equals -0. `a !== a` is the NaN test that needs no cast. */
+export declare function isSameValueZero(left: unknown, right: unknown): boolean;
+/**
+ * Structural comparison for arrays and PLAIN objects only. A Date, a RegExp, a
+ * Map or a class instance compares by identity, because reading their own
+ * enumerable keys would call every one of them equal to every other — a RegExp
+ * has none at all. JSON has none of those shapes, so nothing that came out of
+ * JSON.parse is affected.
+ */
+export declare function isJsonValueEqual(left: unknown, right: unknown): boolean;

package/dist/plugin-kit/is-json-value-equal.js

@@ -0,0 +1,81 @@
+"use strict";
+// ===========================================================================
+// L2  src/plugin-kit/is-json-value-equal.ts
+// THE single definition of "these two values are the same JSON value".
+//
+// It lives in plugin-kit because FOUR callers need the same answer and a plugin
+// may not import a sibling plugin: `unique` (array-unique), `oneOf`, `literal`,
+// and through the last two the Draft-07 `enum` and `const` keywords. Every one
+// of those keywords is defined by JSON Schema §4.2.3 in terms of the JSON data
+// model, where equality is STRUCTURAL — `{"a":1}` equals `{"a":1}` however many
+// times it was parsed — so three separate `===` tests were three ways of being
+// wrong at once. Measured on the official suite: reference equality cost 17 of
+// the 929 draft7 cases before this module existed.
+//
+// docs/legacy-spec/plugin-catalog-structural.md records two defects this closes
+// for `unique`, and they are the reason the implementation looks the way it does:
+//   * 1.x switched from a `===` double loop to a Set at length 11, so [NaN, NaN]
+//     was a duplicate in a long array and not in a short one. One definition is
+//     used here at every length.
+//   * the rewrite's first draft keyed on JSON.stringify, which is ORDER
+//     dependent: {a:1,b:2} and {b:2,a:1} are the same value and were reported as
+//     distinct. Keys are compared as a set, so order cannot matter.
+//
+// Leaves compare with SameValueZero (NaN equals NaN, +0 equals -0), which is the
+// definition `Set` and `Array.prototype.includes` already use, so `unique`,
+// `includes`, `oneOf` and `literal` all agree about what "the same value" means.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSameValueZero = isSameValueZero;
+exports.isJsonValueEqual = isJsonValueEqual;
+/** NaN equals NaN; +0 equals -0. `a !== a` is the NaN test that needs no cast. */
+function isSameValueZero(left, right) {
+    return left === right || (left !== left && right !== right);
+}
+/**
+ * Structural comparison for arrays and PLAIN objects only. A Date, a RegExp, a
+ * Map or a class instance compares by identity, because reading their own
+ * enumerable keys would call every one of them equal to every other — a RegExp
+ * has none at all. JSON has none of those shapes, so nothing that came out of
+ * JSON.parse is affected.
+ */
+function isJsonValueEqual(left, right) {
+    if (isSameValueZero(left, right))
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            areElementsEqual(left, right));
+    }
+    if (!isPlainRecord(left) || !isPlainRecord(right))
+        return false;
+    return areEntriesEqual(left, right);
+}
+function areElementsEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        if (!isJsonValueEqual(left[index], right[index]))
+            return false;
+    }
+    return true;
+}
+function areEntriesEqual(left, right) {
+    const leftKeys = Object.keys(left);
+    if (leftKeys.length !== Object.keys(right).length)
+        return false;
+    for (const key of leftKeys) {
+        if (!Object.prototype.hasOwnProperty.call(right, key))
+            return false;
+        if (!isJsonValueEqual(left[key], right[key]))
+            return false;
+    }
+    return true;
+}
+/** Object.prototype or a null prototype: anything else keeps its identity. */
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/plugin-kit/is-json-value-equal.mjs

@@ -0,0 +1,77 @@
+// ===========================================================================
+// L2  src/plugin-kit/is-json-value-equal.ts
+// THE single definition of "these two values are the same JSON value".
+//
+// It lives in plugin-kit because FOUR callers need the same answer and a plugin
+// may not import a sibling plugin: `unique` (array-unique), `oneOf`, `literal`,
+// and through the last two the Draft-07 `enum` and `const` keywords. Every one
+// of those keywords is defined by JSON Schema §4.2.3 in terms of the JSON data
+// model, where equality is STRUCTURAL — `{"a":1}` equals `{"a":1}` however many
+// times it was parsed — so three separate `===` tests were three ways of being
+// wrong at once. Measured on the official suite: reference equality cost 17 of
+// the 929 draft7 cases before this module existed.
+//
+// docs/legacy-spec/plugin-catalog-structural.md records two defects this closes
+// for `unique`, and they are the reason the implementation looks the way it does:
+//   * 1.x switched from a `===` double loop to a Set at length 11, so [NaN, NaN]
+//     was a duplicate in a long array and not in a short one. One definition is
+//     used here at every length.
+//   * the rewrite's first draft keyed on JSON.stringify, which is ORDER
+//     dependent: {a:1,b:2} and {b:2,a:1} are the same value and were reported as
+//     distinct. Keys are compared as a set, so order cannot matter.
+//
+// Leaves compare with SameValueZero (NaN equals NaN, +0 equals -0), which is the
+// definition `Set` and `Array.prototype.includes` already use, so `unique`,
+// `includes`, `oneOf` and `literal` all agree about what "the same value" means.
+// ===========================================================================
+/** NaN equals NaN; +0 equals -0. `a !== a` is the NaN test that needs no cast. */
+export function isSameValueZero(left, right) {
+    return left === right || (left !== left && right !== right);
+}
+/**
+ * Structural comparison for arrays and PLAIN objects only. A Date, a RegExp, a
+ * Map or a class instance compares by identity, because reading their own
+ * enumerable keys would call every one of them equal to every other — a RegExp
+ * has none at all. JSON has none of those shapes, so nothing that came out of
+ * JSON.parse is affected.
+ */
+export function isJsonValueEqual(left, right) {
+    if (isSameValueZero(left, right))
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            areElementsEqual(left, right));
+    }
+    if (!isPlainRecord(left) || !isPlainRecord(right))
+        return false;
+    return areEntriesEqual(left, right);
+}
+function areElementsEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        if (!isJsonValueEqual(left[index], right[index]))
+            return false;
+    }
+    return true;
+}
+function areEntriesEqual(left, right) {
+    const leftKeys = Object.keys(left);
+    if (leftKeys.length !== Object.keys(right).length)
+        return false;
+    for (const key of leftKeys) {
+        if (!Object.prototype.hasOwnProperty.call(right, key))
+            return false;
+        if (!isJsonValueEqual(left[key], right[key]))
+            return false;
+    }
+    return true;
+}
+/** Object.prototype or a null prototype: anything else keeps its identity. */
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/plugin-kit/marker.types.d.ts

@@ -0,0 +1,114 @@
+declare const MARKER: unique symbol;
+export interface FieldRef {
+    readonly [MARKER]: "fieldRef";
+}
+export interface FieldRefs {
+    readonly [MARKER]: "fieldRefs";
+}
+export interface RootPredicate {
+    readonly [MARKER]: "rootPredicate";
+}
+export interface RootReader<R> {
+    readonly [MARKER]: "rootReader";
+    readonly read: R;
+}
+export interface SelfReader<R> {
+    readonly [MARKER]: "selfReader";
+    readonly read: R;
+}
+export interface SelfValue {
+    readonly [MARKER]: "selfValue";
+}
+export interface ElementChain {
+    readonly [MARKER]: "elementChain";
+}
+export interface SelfGuard {
+    readonly [MARKER]: "selfGuard";
+}
+export interface NarrowedChain {
+    readonly [MARKER]: "narrowedChain";
+}
+/** A sub-chain over the VALUE behind any property key of the subject object. */
+export interface PropertyValueChain {
+    readonly [MARKER]: "propertyValueChain";
+}
+/** A sub-chain over the property KEY itself, which is always a string. */
+export interface PropertyKeyChain {
+    readonly [MARKER]: "propertyKeyChain";
+}
+export interface Unchanged {
+    readonly [MARKER]: "unchanged";
+}
+export interface TransformOut {
+    readonly [MARKER]: "transformOut";
+}
+export interface GuardOut {
+    readonly [MARKER]: "guardOut";
+}
+export type PresenceShiftKind = "excludeMissing" | "excludeUndefined" | "excludeNull" | "allowNull";
+export interface PresenceShift<K extends PresenceShiftKind> {
+    readonly [MARKER]: "presence";
+    readonly shift: K;
+}
+declare const PROBE: unique symbol;
+/** A type no resolver can produce by accident, used to spot an unresolved marker. */
+export interface MarkerProbe {
+    readonly [PROBE]: true;
+}
+/** THE registry of argument markers. Both resolvers are proved exhaustive
+ *  against it by src/chain/marker-coverage.types.ts. */
+export interface ArgumentMarkerRegistry {
+    readonly fieldRef: FieldRef;
+    readonly fieldRefs: FieldRefs;
+    readonly rootPredicate: RootPredicate;
+    readonly rootReader: RootReader<MarkerProbe>;
+    readonly selfReader: SelfReader<MarkerProbe>;
+    readonly selfValue: SelfValue;
+    readonly elementChain: ElementChain;
+    readonly selfGuard: SelfGuard;
+    readonly narrowedChain: NarrowedChain;
+    readonly propertyValueChain: PropertyValueChain;
+    readonly propertyKeyChain: PropertyKeyChain;
+}
+export type ArgumentMarkerKind = keyof ArgumentMarkerRegistry;
+export interface OutputMarkerRegistry {
+    readonly unchanged: Unchanged;
+    readonly transformOut: TransformOut;
+    readonly guardOut: GuardOut;
+    readonly excludeMissing: PresenceShift<"excludeMissing">;
+    readonly excludeUndefined: PresenceShift<"excludeUndefined">;
+    readonly excludeNull: PresenceShift<"excludeNull">;
+    readonly allowNull: PresenceShift<"allowNull">;
+}
+export type OutputMarkerKind = keyof OutputMarkerRegistry;
+export type ArgumentMarker = ArgumentMarkerRegistry[ArgumentMarkerKind];
+export type AnyMarker = ArgumentMarker | OutputMarkerRegistry[OutputMarkerKind];
+/**
+ * A record whose every value is an argument marker. `patternProperties` and
+ * `dependentSchemas` take one sub-chain PER KEY, and a key set is not a tuple,
+ * so neither resolver's array recursion reached them. Both resolvers now
+ * recurse into exactly this shape and leave every other object argument (e.g.
+ * `{ maxDepth?: number }`) untouched, so the recursion cannot silently rewrite
+ * an ordinary options bag.
+ */
+export type MarkerRecord = Readonly<Record<string, ArgumentMarker>>;
+export type AssertNever<T extends never> = T;
+export type BrandOf<M> = M extends {
+    readonly [MARKER]: infer K extends string;
+} ? K : never;
+type UnbrandedArgumentEntry = {
+    [K in ArgumentMarkerKind]: [BrandOf<ArgumentMarkerRegistry[K]>] extends [
+        never
+    ] ? K : never;
+}[ArgumentMarkerKind];
+type UnbrandedOutputEntry = {
+    [K in OutputMarkerKind]: [BrandOf<OutputMarkerRegistry[K]>] extends [never] ? K : never;
+}[OutputMarkerKind];
+export type MarkerRegistryProof = [
+    AssertNever<UnbrandedArgumentEntry>,
+    AssertNever<UnbrandedOutputEntry>
+];
+type MarkerInOne<A> = [Extract<A, ArgumentMarker>] extends [never] ? [A] extends [readonly unknown[]] ? MarkerInUnion<A[number]> : [A] extends [MarkerRecord] ? true : false : true;
+type MarkerInUnion<A> = A extends unknown ? MarkerInOne<A> : never;
+export type IsMarkerFree<A extends readonly unknown[]> = true extends MarkerInUnion<A[number]> ? false : true;
+export {};

package/dist/plugin-kit/marker.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/plugin-kit/marker.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/plugin-kit/plugin-definition.d.ts

@@ -0,0 +1,40 @@
+import type { MessageContextExtra, TypeName } from "../types";
+import type { RuleForOut, RuntimeArgs } from "./runtime-args.types";
+import type { RuleBuildContext } from "./rule-build-context";
+/** TOut defaults to `unknown`, NOT to `Unchanged`. */
+export interface PluginSignature<TArgs extends readonly unknown[] = readonly unknown[], TOut = unknown, TContext extends MessageContextExtra = MessageContextExtra> {
+    readonly args: TArgs;
+    readonly out: TOut;
+    readonly context: TContext;
+}
+export type PluginBuild<TSig extends PluginSignature> = (ctx: RuleBuildContext<TSig["context"]>, ...args: RuntimeArgs<TSig["args"]>) => RuleForOut<TSig["out"]>;
+export interface PluginDefinition<TName extends string, TMethod extends string, TSlots extends readonly TypeName[], TSig extends PluginSignature> {
+    readonly name: TName;
+    readonly method: TMethod;
+    readonly slots: TSlots;
+    build(ctx: RuleBuildContext<TSig["context"]>, ...args: RuntimeArgs<TSig["args"]>): RuleForOut<TSig["out"]>;
+    /**
+     * Which argument POSITIONS carry a sub-chain. Absent on a plugin that takes
+     * none. It cannot be recovered from the signature at run time — a
+     * NarrowedChain and a RootPredicate are both plain functions once the types
+     * are erased — so a composite declares it, and src/chain/collect-branch-rules
+     * resolves exactly those positions to `readonly Rule[]` before build() runs.
+     */
+    readonly subChainArguments?: readonly number[];
+    readonly signature?: TSig;
+}
+export type AnyPlugin = PluginDefinition<string, string, readonly TypeName[], PluginSignature>;
+export interface PluginSpec<TName extends string, TMethod extends string, TSlots extends readonly TypeName[], TSig extends PluginSignature> {
+    readonly name: TName;
+    readonly method: TMethod;
+    readonly slots: TSlots;
+    readonly build: PluginBuild<TSig>;
+    readonly subChainArguments?: readonly number[];
+}
+/** Curried: the signature is explicit, the identity literals are inferred. */
+export declare function definePlugin<TSig extends PluginSignature>(): <TName extends string, TMethod extends string, TSlots extends readonly TypeName[]>(spec: PluginSpec<TName, TMethod, TSlots, TSig>) => PluginDefinition<TName, TMethod, TSlots, TSig>;
+export type PluginArgs<P> = P extends PluginDefinition<string, string, readonly TypeName[], infer Sig> ? Sig["args"] : never;
+export type PluginOut<P> = P extends PluginDefinition<string, string, readonly TypeName[], infer Sig> ? Sig["out"] : never;
+export declare class PluginArgumentError extends Error {
+    constructor(pluginName: string, argumentName: string, received: unknown);
+}

package/dist/plugin-kit/plugin-definition.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginArgumentError = void 0;
+exports.definePlugin = definePlugin;
+/** Curried: the signature is explicit, the identity literals are inferred. */
+function definePlugin() {
+    return (spec) => ({
+        name: spec.name,
+        method: spec.method,
+        slots: spec.slots,
+        build: spec.build,
+        // Only present when the plugin declared one, so a plugin that takes no
+        // sub-chain keeps exactly the four members it always had.
+        ...(spec.subChainArguments === undefined
+            ? {}
+            : { subChainArguments: spec.subChainArguments }),
+    });
+}
+class PluginArgumentError extends Error {
+    constructor(pluginName, argumentName, received) {
+        super(`${pluginName}: invalid argument "${argumentName}": ${String(received)}`);
+        this.name = "PluginArgumentError";
+    }
+}
+exports.PluginArgumentError = PluginArgumentError;

package/dist/plugin-kit/plugin-definition.mjs

@@ -0,0 +1,20 @@
+/** Curried: the signature is explicit, the identity literals are inferred. */
+export function definePlugin() {
+    return (spec) => ({
+        name: spec.name,
+        method: spec.method,
+        slots: spec.slots,
+        build: spec.build,
+        // Only present when the plugin declared one, so a plugin that takes no
+        // sub-chain keeps exactly the four members it always had.
+        ...(spec.subChainArguments === undefined
+            ? {}
+            : { subChainArguments: spec.subChainArguments }),
+    });
+}
+export class PluginArgumentError extends Error {
+    constructor(pluginName, argumentName, received) {
+        super(`${pluginName}: invalid argument "${argumentName}": ${String(received)}`);
+        this.name = "PluginArgumentError";
+    }
+}

package/dist/plugin-kit/rule-build-context.d.ts

@@ -0,0 +1,27 @@
+import type { IssueSeverity, MessageContext, MessageContextExtra, MessageFactory } from "../types";
+import type { ResolvedGlobalConfig } from "../types/global-config";
+export interface RuleBuildContext<C extends MessageContextExtra = MessageContextExtra> {
+    /** Identity of the plugin whose build() is running. */
+    readonly pluginName: string;
+    /** Error code already resolved from options.code, falling back to pluginName. */
+    readonly code: string;
+    /** Message factory already resolved from options.messageFactory. */
+    readonly messageFactory?: MessageFactory<C>;
+    /**
+     * Already resolved from options.severity, falling back to
+     * config.defaultSeverity. Resolved ONCE, here, for the same reason
+     * options.code is: two resolution sites is how an override stops working.
+     */
+    readonly severity: IssueSeverity;
+    /**
+     * The effective GlobalConfig for the builder that is building this rule.
+     * This is the ONLY way a plugin sees it; nothing reads a process-wide
+     * singleton at validation time.
+     */
+    readonly config: ResolvedGlobalConfig;
+    /** The field this rule is attached to, in L1 grammar. */
+    readonly fieldPath: string;
+    /** Immediate child object keys declared underneath fieldPath, frozen by L4. */
+    readonly declaredSiblingKeys: readonly string[];
+}
+export declare function renderMessage<C extends MessageContextExtra>(factory: MessageFactory<C> | undefined, ctx: MessageContext, extra: C, fallback: string): string;

package/dist/plugin-kit/rule-build-context.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMessage = renderMessage;
+function renderMessage(factory, ctx, extra, fallback) {
+    return factory === undefined
+        ? fallback
+        : factory(Object.assign({}, ctx, extra));
+}

package/dist/plugin-kit/rule-build-context.mjs

@@ -0,0 +1,5 @@
+export function renderMessage(factory, ctx, extra, fallback) {
+    return factory === undefined
+        ? fallback
+        : factory(Object.assign({}, ctx, extra));
+}

package/dist/plugin-kit/runtime-args.types.d.ts

@@ -0,0 +1,27 @@
+import type { ElementChain, FieldRef, FieldRefs, MarkerRecord, NarrowedChain, PresenceShift, PresenceShiftKind, PropertyKeyChain, PropertyValueChain, RootPredicate, RootReader, SelfGuard, SelfReader, SelfValue, TransformOut } from "./marker.types";
+import type { ArrayItemContext } from "../types";
+import type { PresenceRule, Rule, TransformRule } from "./compiled-rule";
+export type RootPredicateFn = (root: unknown, item?: ArrayItemContext) => boolean;
+export type RootReaderFn<R> = (root: unknown) => R;
+export type SelfReaderFn<R> = (value: unknown) => R;
+export type SelfGuardFn = (value: unknown) => boolean;
+/**
+ * An OPTIONAL tuple element makes `A[I]` be `M | undefined`, which matches no
+ * marker branch. Undefined is stripped before matching and re-added afterwards.
+ */
+export type RuntimeArg<A> = [undefined] extends [A] ? ResolveRuntimeArg<Exclude<A, undefined>> | undefined : ResolveRuntimeArg<A>;
+type ResolveRuntimeArg<A> = [A] extends [FieldRef] ? string : [A] extends [FieldRefs] ? readonly string[] : [A] extends [RootPredicate] ? RootPredicateFn : [A] extends [RootReader<infer R>] ? RootReaderFn<R> : [A] extends [SelfReader<infer R>] ? SelfReaderFn<R> : [A] extends [SelfGuard] ? SelfGuardFn : [A] extends [SelfValue] ? unknown : [A] extends [ElementChain] ? readonly Rule[] : [A] extends [NarrowedChain] ? readonly Rule[] : [A] extends [PropertyValueChain] ? readonly Rule[] : [A] extends [PropertyKeyChain] ? readonly Rule[] : [
+    A
+] extends [readonly unknown[]] ? {
+    [I in keyof A]: RuntimeArg<A[I]>;
+} : [
+    A
+] extends [MarkerRecord] ? {
+    readonly [K in keyof A]: RuntimeArg<A[K]>;
+} : A;
+export type RuntimeArgs<A extends readonly unknown[]> = {
+    [I in keyof A]: RuntimeArg<A[I]>;
+};
+/** The runtime counterpart of the OUTPUT markers. */
+export type RuleForOut<O> = [O] extends [TransformOut] ? TransformRule : [O] extends [PresenceShift<PresenceShiftKind>] ? PresenceRule : Rule;
+export {};

package/dist/plugin-kit/runtime-args.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/plugin-kit/runtime-args.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/plugin-kit.d.ts

@@ -0,0 +1 @@
+export * from "./plugin-kit/index";

package/dist/plugin-kit.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./plugin-kit/index");

package/dist/plugin-kit.mjs

@@ -0,0 +1 @@
+export * from "./plugin-kit/index.mjs";

package/dist/plugins/array-contains/array-contains.d.ts

@@ -0,0 +1,22 @@
+import type { ElementChain, Unchanged } from "../../plugin-kit/marker.types";
+export interface ArrayContainsBounds {
+    readonly min?: number;
+    readonly max?: number;
+}
+export interface ArrayContainsContext {
+    readonly matched: number;
+    readonly min: number;
+    readonly max: 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 arrayContainsPlugin: import("../../plugin-kit/plugin-definition").PluginDefinition<"arrayContains", "contains", readonly ["array", "tuple"], {
+    args: readonly [element: ElementChain, bounds?: ArrayContainsBounds];
+    out: Unchanged;
+    context: ArrayContainsContext;
+}>;

package/dist/plugins/array-contains/array-contains.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arrayContainsPlugin = void 0;
+// ===========================================================================
+// L7  src/plugins/array-contains/array-contains.ts
+// Draft-07 `contains` / `minContains` / `maxContains`.
+//
+// A COMPOSITE, not a check: the element schema arrives as an ElementChain that
+// the chain has already collected into rules, becomes ONE branch, and the
+// engine turns that branch into a runner. The plugin never touches a Rule, so
+// there is no second execution path here — only counting.
+//
+// Legacy replaced (docs/legacy-spec/plugin-catalog-structural.md#arrayContainsPlugin):
+//   * three argument shapes (a value, a {validator}, a JSONSchema7) and a
+//     private mini schema evaluator: all three collapse into the sub-chain,
+//     which is the same engine every other rule runs on;
+//   * a non-array returned FALSE, alone among the array plugins. It passes
+//     here, because the array type guard owns type errors;
+//   * the code was the only SCREAMING_SNAKE in the catalog and no options bag
+//     was accepted. Both now follow the one rule: code defaults to the plugin
+//     name and options.code / options.messageFactory work.
+// ===========================================================================
+const types_1 = require("../../types");
+const create_rule_1 = require("../../plugin-kit/create-rule");
+const plugin_definition_1 = require("../../plugin-kit/plugin-definition");
+/**
+ * Counting stops as soon as the count passes `max`: a further match cannot
+ * change the answer, and the array may be long.
+ */
+function countMatchingElements(runners, min, max) {
+    const matcher = runners[0];
+    return (value, ctx) => {
+        if (matcher === undefined || !(0, types_1.isArray)(value))
+            return types_1.PASS;
+        let matched = 0;
+        for (const element of value) {
+            if (matcher.run(element, ctx).ok)
+                matched += 1;
+            if (matched > max)
+                break;
+        }
+        return matched < min || matched > max
+            ? (0, types_1.fail)({ expected: min, actual: matched, branch: matcher.label })
+            : types_1.PASS;
+    };
+}
+/**
+ * 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.arrayContainsPlugin = (0, plugin_definition_1.definePlugin)()({
+    name: "arrayContains",
+    method: "contains",
+    slots: ["array", "tuple"],
+    build: (ctx, element, bounds) => {
+        const min = bounds?.min ?? 1;
+        const max = bounds?.max ?? Number.POSITIVE_INFINITY;
+        if (!(0, types_1.isNumber)(min) || Number.isNaN(min) || min < 0) {
+            throw new plugin_definition_1.PluginArgumentError(ctx.pluginName, "bounds.min", min);
+        }
+        if (!(0, types_1.isNumber)(max) || Number.isNaN(max) || max < min) {
+            throw new plugin_definition_1.PluginArgumentError(ctx.pluginName, "bounds.max", max);
+        }
+        return (0, create_rule_1.composite)({
+            code: ctx.code,
+            messageFactory: ctx.messageFactory,
+            severity: ctx.severity,
+            branches: [(0, create_rule_1.branch)("contains", element)],
+            combine: (runners) => countMatchingElements(runners, min, max),
+            describe: (detail) => `Array must contain at least ${String(min)} matching element(s), but got ${String(detail.actual)}`,
+            buildMessageContext: (detail) => ({
+                matched: (0, types_1.isNumber)(detail.actual) ? detail.actual : 0,
+                min,
+                max,
+            }),
+        });
+    },
+    subChainArguments: [0],
+});