@maroonedog/luq 2.4.4 → 2.6.0

package/dist/json-schema/malformed-schema-error.js

@@ -0,0 +1,103 @@
+"use strict";
+// ===========================================================================
+// L8  src/json-schema/malformed-schema-error.ts
+//
+// UnsupportedKeywordError refuses a keyword NAME Luq cannot honour. This
+// refuses a keyword VALUE the Draft-07 meta-schema does not allow, which until
+// it is refused does not fail — it quietly enforces less than the document
+// says. `{"type":"strig"}` drops the unknown name, so the type check vanishes
+// and the field starts accepting null; `{"pattern":{"source":"^SKU-"}}` reaches
+// the regex constructor as a stringified object and compiles to one matching
+// almost anything; `{"additionalProperties":"false"}` loses the closed-object
+// guarantee; `{"required":"name"}` builds and then throws a raw TypeError
+// inside validate() on the first request. A validator that silently drops a
+// constraint is worse than one that refuses the schema, so the refusal is a
+// typed error carrying the keyword, what the meta-schema requires, and a
+// rendering of what was found instead.
+//
+// The two refusals stay separate classes, neither extending the other, because
+// they answer different questions: "Luq cannot honour this keyword" versus
+// "this document is not valid Draft-07". The first is a limit of the library
+// and the second is a bug in the document; a caller catching one must not
+// silently catch the other.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MalformedSchemaError = exports.SCHEMA_FORMS = void 0;
+exports.renderReceivedValue = renderReceivedValue;
+/**
+ * The two shapes §4.4 lets a schema take, worded once. Several keywords take a
+ * schema as their value — `properties` members, `additionalProperties`, every
+ * position of the tuple form of `items` — and each is read by a different
+ * module; sharing the phrase is what stops the same refusal being explained
+ * three different ways to the same caller.
+ *
+ * It is a fragment, so it composes: "the value ", `the schema under "a" `.
+ */
+exports.SCHEMA_FORMS = "must be an object or a boolean";
+/**
+ * How much of the offending value a message may carry. A schema node is
+ * arbitrarily large, and an error whose message is a megabyte long is unusable
+ * in a log line.
+ */
+const RECEIVED_MAX_LENGTH = 80;
+const TRUNCATION_MARKER = "...";
+/**
+ * Renders an untrusted schema value for a message, in at most
+ * RECEIVED_MAX_LENGTH characters. The value comes from the same document that
+ * is already known to be malformed, so nothing about it can be assumed: it may
+ * be circular, hold a bigint, or be large enough to drown the message.
+ * Rendering must never be the thing that throws.
+ */
+function renderReceivedValue(value) {
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "function")
+        return "[function]";
+    if (typeof value === "symbol")
+        return "[symbol]";
+    return truncate(renderJson(value));
+}
+/**
+ * JSON.stringify throws on a circular reference and on a bigint anywhere in
+ * the value, and returns undefined for a value it has no encoding for at all.
+ * Both outcomes become a description of the shape rather than a failure.
+ */
+function renderJson(value) {
+    try {
+        const rendered = JSON.stringify(value);
+        return rendered === undefined ? describeUnrenderable(value) : rendered;
+    }
+    catch {
+        return describeUnrenderable(value);
+    }
+}
+function describeUnrenderable(value) {
+    return Array.isArray(value)
+        ? "[unrenderable array]"
+        : `[unrenderable ${typeof value}]`;
+}
+function truncate(rendered) {
+    if (rendered.length <= RECEIVED_MAX_LENGTH)
+        return rendered;
+    const kept = RECEIVED_MAX_LENGTH - TRUNCATION_MARKER.length;
+    return `${rendered.slice(0, kept)}${TRUNCATION_MARKER}`;
+}
+/**
+ * Raised when a keyword's value violates the Draft-07 meta-schema. Thrown at
+ * build time, before a validator that would enforce less than the document
+ * states can exist.
+ */
+class MalformedSchemaError extends Error {
+    constructor(keyword, reason, value) {
+        const received = renderReceivedValue(value);
+        super(`JSON Schema keyword "${keyword}" has a value the Draft-07 meta-schema ` +
+            `does not allow: ${reason}. Received: ${received}.`);
+        this.name = "MalformedSchemaError";
+        this.keyword = keyword;
+        this.reason = reason;
+        this.received = received;
+        // Without this, `instanceof` fails when the package is compiled to ES5.
+        Object.setPrototypeOf(this, MalformedSchemaError.prototype);
+    }
+}
+exports.MalformedSchemaError = MalformedSchemaError;

package/dist/json-schema/malformed-schema-error.mjs

@@ -0,0 +1,98 @@
+// ===========================================================================
+// L8  src/json-schema/malformed-schema-error.ts
+//
+// UnsupportedKeywordError refuses a keyword NAME Luq cannot honour. This
+// refuses a keyword VALUE the Draft-07 meta-schema does not allow, which until
+// it is refused does not fail — it quietly enforces less than the document
+// says. `{"type":"strig"}` drops the unknown name, so the type check vanishes
+// and the field starts accepting null; `{"pattern":{"source":"^SKU-"}}` reaches
+// the regex constructor as a stringified object and compiles to one matching
+// almost anything; `{"additionalProperties":"false"}` loses the closed-object
+// guarantee; `{"required":"name"}` builds and then throws a raw TypeError
+// inside validate() on the first request. A validator that silently drops a
+// constraint is worse than one that refuses the schema, so the refusal is a
+// typed error carrying the keyword, what the meta-schema requires, and a
+// rendering of what was found instead.
+//
+// The two refusals stay separate classes, neither extending the other, because
+// they answer different questions: "Luq cannot honour this keyword" versus
+// "this document is not valid Draft-07". The first is a limit of the library
+// and the second is a bug in the document; a caller catching one must not
+// silently catch the other.
+// ===========================================================================
+/**
+ * The two shapes §4.4 lets a schema take, worded once. Several keywords take a
+ * schema as their value — `properties` members, `additionalProperties`, every
+ * position of the tuple form of `items` — and each is read by a different
+ * module; sharing the phrase is what stops the same refusal being explained
+ * three different ways to the same caller.
+ *
+ * It is a fragment, so it composes: "the value ", `the schema under "a" `.
+ */
+export const SCHEMA_FORMS = "must be an object or a boolean";
+/**
+ * How much of the offending value a message may carry. A schema node is
+ * arbitrarily large, and an error whose message is a megabyte long is unusable
+ * in a log line.
+ */
+const RECEIVED_MAX_LENGTH = 80;
+const TRUNCATION_MARKER = "...";
+/**
+ * Renders an untrusted schema value for a message, in at most
+ * RECEIVED_MAX_LENGTH characters. The value comes from the same document that
+ * is already known to be malformed, so nothing about it can be assumed: it may
+ * be circular, hold a bigint, or be large enough to drown the message.
+ * Rendering must never be the thing that throws.
+ */
+export function renderReceivedValue(value) {
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "function")
+        return "[function]";
+    if (typeof value === "symbol")
+        return "[symbol]";
+    return truncate(renderJson(value));
+}
+/**
+ * JSON.stringify throws on a circular reference and on a bigint anywhere in
+ * the value, and returns undefined for a value it has no encoding for at all.
+ * Both outcomes become a description of the shape rather than a failure.
+ */
+function renderJson(value) {
+    try {
+        const rendered = JSON.stringify(value);
+        return rendered === undefined ? describeUnrenderable(value) : rendered;
+    }
+    catch {
+        return describeUnrenderable(value);
+    }
+}
+function describeUnrenderable(value) {
+    return Array.isArray(value)
+        ? "[unrenderable array]"
+        : `[unrenderable ${typeof value}]`;
+}
+function truncate(rendered) {
+    if (rendered.length <= RECEIVED_MAX_LENGTH)
+        return rendered;
+    const kept = RECEIVED_MAX_LENGTH - TRUNCATION_MARKER.length;
+    return `${rendered.slice(0, kept)}${TRUNCATION_MARKER}`;
+}
+/**
+ * Raised when a keyword's value violates the Draft-07 meta-schema. Thrown at
+ * build time, before a validator that would enforce less than the document
+ * states can exist.
+ */
+export class MalformedSchemaError extends Error {
+    constructor(keyword, reason, value) {
+        const received = renderReceivedValue(value);
+        super(`JSON Schema keyword "${keyword}" has a value the Draft-07 meta-schema ` +
+            `does not allow: ${reason}. Received: ${received}.`);
+        this.name = "MalformedSchemaError";
+        this.keyword = keyword;
+        this.reason = reason;
+        this.received = received;
+        // Without this, `instanceof` fails when the package is compiled to ES5.
+        Object.setPrototypeOf(this, MalformedSchemaError.prototype);
+    }
+}

package/dist/json-schema/unsupported-dialect-error.d.ts

@@ -0,0 +1,21 @@
+/** The dialect this library implements, in the spelling the draft publishes. */
+export declare const DRAFT07_DIALECT_URI = "http://json-schema.org/draft-07/schema#";
+/**
+ * Raised when a document's root `$schema` names a dialect Luq does not
+ * implement. Thrown at build time, before a validator that would read the
+ * document under the wrong dialect's rules can exist.
+ *
+ * `reason` follows the convention the other two refusals use: a sentence
+ * fragment with no terminal punctuation, saying what the dialect does that
+ * Draft-07 does not, so that two refusals from two different dialects read as
+ * one library rather than as two unrelated messages.
+ */
+export declare class UnsupportedDialectError extends Error {
+    /** The `$schema` value the document wrote, verbatim. */
+    readonly declared: string;
+    /** The dialect Luq reads every document under. */
+    readonly implemented: string;
+    /** What that dialect does differently, or that it is unrecognised. */
+    readonly reason: string;
+    constructor(declared: string, reason: string);
+}

package/dist/json-schema/unsupported-dialect-error.js

@@ -0,0 +1,58 @@
+"use strict";
+// ===========================================================================
+// L8  src/json-schema/unsupported-dialect-error.ts
+//
+// The third refusal, and the only one with no keyword to hang on.
+// UnsupportedKeywordError refuses a keyword NAME; MalformedSchemaError refuses
+// a keyword VALUE. Both need the document to write something recognisable, and
+// there is one divergence that writes nothing at all:
+//
+//     {"$schema": "https://json-schema.org/draft/2020-12/schema",
+//      "$defs": {"name": {"type": "string"}},
+//      "properties": {"nick": {"$ref": "#/$defs/name", "minLength": 5}}}
+//
+// Every keyword there is a Draft-07 keyword spelled the Draft-07 way, so the
+// keyword table sees nothing to refuse. The meaning is not Draft-07: §8.3 has
+// `$ref` REPLACE the object it appears in, and from 2019-09 on `$ref` is an
+// ordinary applicator whose siblings are applied. Read as Draft-07 the document
+// above builds a validator that accepts `{"nick":"ab"}` — the `minLength` is
+// gone, silently, and nothing in the result says a constraint went missing.
+// `$schema` is the only signal the document offers, so it is the one read.
+//
+// It stays a separate class from the other two, neither extending the other,
+// for the reason written in malformed-schema-error.ts: each answers a different
+// question. "Luq cannot honour this keyword", "this document is not valid
+// Draft-07", and now "this document is not Draft-07 AT ALL" are three distinct
+// facts, and a caller catching one must not silently catch another.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsupportedDialectError = exports.DRAFT07_DIALECT_URI = void 0;
+/** The dialect this library implements, in the spelling the draft publishes. */
+exports.DRAFT07_DIALECT_URI = "http://json-schema.org/draft-07/schema#";
+/**
+ * Raised when a document's root `$schema` names a dialect Luq does not
+ * implement. Thrown at build time, before a validator that would read the
+ * document under the wrong dialect's rules can exist.
+ *
+ * `reason` follows the convention the other two refusals use: a sentence
+ * fragment with no terminal punctuation, saying what the dialect does that
+ * Draft-07 does not, so that two refusals from two different dialects read as
+ * one library rather than as two unrelated messages.
+ */
+class UnsupportedDialectError extends Error {
+    constructor(declared, reason) {
+        super(`JSON Schema dialect "${declared}" is not supported: ${reason}. Luq ` +
+            `implements Draft-07 (${exports.DRAFT07_DIALECT_URI}) and would read this ` +
+            "document under Draft-07 rules, which can enforce less than it " +
+            "states. Convert the document to Draft-07, or pass " +
+            "`{ assumeDraft07: true }` to take the Draft-07 reading deliberately.");
+        /** The dialect Luq reads every document under. */
+        this.implemented = exports.DRAFT07_DIALECT_URI;
+        this.name = "UnsupportedDialectError";
+        this.declared = declared;
+        this.reason = reason;
+        // Without this, `instanceof` fails when the package is compiled to ES5.
+        Object.setPrototypeOf(this, UnsupportedDialectError.prototype);
+    }
+}
+exports.UnsupportedDialectError = UnsupportedDialectError;

package/dist/json-schema/unsupported-dialect-error.mjs

@@ -0,0 +1,54 @@
+// ===========================================================================
+// L8  src/json-schema/unsupported-dialect-error.ts
+//
+// The third refusal, and the only one with no keyword to hang on.
+// UnsupportedKeywordError refuses a keyword NAME; MalformedSchemaError refuses
+// a keyword VALUE. Both need the document to write something recognisable, and
+// there is one divergence that writes nothing at all:
+//
+//     {"$schema": "https://json-schema.org/draft/2020-12/schema",
+//      "$defs": {"name": {"type": "string"}},
+//      "properties": {"nick": {"$ref": "#/$defs/name", "minLength": 5}}}
+//
+// Every keyword there is a Draft-07 keyword spelled the Draft-07 way, so the
+// keyword table sees nothing to refuse. The meaning is not Draft-07: §8.3 has
+// `$ref` REPLACE the object it appears in, and from 2019-09 on `$ref` is an
+// ordinary applicator whose siblings are applied. Read as Draft-07 the document
+// above builds a validator that accepts `{"nick":"ab"}` — the `minLength` is
+// gone, silently, and nothing in the result says a constraint went missing.
+// `$schema` is the only signal the document offers, so it is the one read.
+//
+// It stays a separate class from the other two, neither extending the other,
+// for the reason written in malformed-schema-error.ts: each answers a different
+// question. "Luq cannot honour this keyword", "this document is not valid
+// Draft-07", and now "this document is not Draft-07 AT ALL" are three distinct
+// facts, and a caller catching one must not silently catch another.
+// ===========================================================================
+/** The dialect this library implements, in the spelling the draft publishes. */
+export const DRAFT07_DIALECT_URI = "http://json-schema.org/draft-07/schema#";
+/**
+ * Raised when a document's root `$schema` names a dialect Luq does not
+ * implement. Thrown at build time, before a validator that would read the
+ * document under the wrong dialect's rules can exist.
+ *
+ * `reason` follows the convention the other two refusals use: a sentence
+ * fragment with no terminal punctuation, saying what the dialect does that
+ * Draft-07 does not, so that two refusals from two different dialects read as
+ * one library rather than as two unrelated messages.
+ */
+export class UnsupportedDialectError extends Error {
+    constructor(declared, reason) {
+        super(`JSON Schema dialect "${declared}" is not supported: ${reason}. Luq ` +
+            `implements Draft-07 (${DRAFT07_DIALECT_URI}) and would read this ` +
+            "document under Draft-07 rules, which can enforce less than it " +
+            "states. Convert the document to Draft-07, or pass " +
+            "`{ assumeDraft07: true }` to take the Draft-07 reading deliberately.");
+        /** The dialect Luq reads every document under. */
+        this.implemented = DRAFT07_DIALECT_URI;
+        this.name = "UnsupportedDialectError";
+        this.declared = declared;
+        this.reason = reason;
+        // Without this, `instanceof` fails when the package is compiled to ES5.
+        Object.setPrototypeOf(this, UnsupportedDialectError.prototype);
+    }
+}

package/dist/plugins/one-of/one-of.js

@@ -36,7 +36,10 @@ function describeAllowed(allowed) {
 function areAllMembersPrimitive(allowed) {
     return allowed.every((member) => member === null || typeof member !== "object");
 }
-/** One membership test, decided ONCE at build time and never re-decided. */
+/** One membership test, decided ONCE at build time and never re-decided. The
+ *  list must already be a snapshot: the linear path CLOSES OVER it rather than
+ *  copying it into a Set, so a caller-owned array reaching here would stay
+ *  readable — and mutable — through the returned validator. */
 function createMembershipTest(allowed) {
     if (allowed.length > SET_MEMBERSHIP_THRESHOLD &&
         areAllMembersPrimitive(allowed)) {
@@ -53,13 +56,24 @@ exports.oneOfPlugin = (0, plugin_definition_1.definePlugin)()({
         if (!(0, types_1.isArray)(allowed) || allowed.length === 0) {
             throw new plugin_definition_1.PluginArgumentError(ctx.pluginName, "allowed", allowed);
         }
-        const isMember = createMembershipTest(allowed);
-        const rendered = describeAllowed(allowed);
+        // A built validator is a SNAPSHOT of what it was built from, and this list
+        // arrives BY REFERENCE: reached through the `enum` keyword it is the very
+        // array inside the caller's schema document. Without this copy, appending
+        // to that array in place after build() — a config reload that mutates the
+        // document rather than replacing it — silently widens a validator that is
+        // already serving traffic. It would also do so only SOMETIMES: the Set
+        // path in createMembershipTest copies and the linear path does not, so the
+        // behaviour would flip at a member count the caller has no reason to know
+        // about. Copying here, at the one point where the caller's array enters
+        // the plugin, is what makes both paths and the reported `expected` agree.
+        const members = Object.freeze(allowed.slice());
+        const isMember = createMembershipTest(members);
+        const rendered = describeAllowed(members);
         return (0, create_rule_1.check)({
             code: ctx.code,
             messageFactory: ctx.messageFactory,
             severity: ctx.severity,
-            run: (value) => isMember(value) ? types_1.PASS : (0, types_1.fail)({ expected: allowed, actual: value }),
+            run: (value) => isMember(value) ? types_1.PASS : (0, types_1.fail)({ expected: members, actual: value }),
             describe: () => `Value must be one of: ${rendered}`,
             buildMessageContext: () => ({}),
         });

package/dist/plugins/one-of/one-of.mjs

@@ -33,7 +33,10 @@ function describeAllowed(allowed) {
 function areAllMembersPrimitive(allowed) {
     return allowed.every((member) => member === null || typeof member !== "object");
 }
-/** One membership test, decided ONCE at build time and never re-decided. */
+/** One membership test, decided ONCE at build time and never re-decided. The
+ *  list must already be a snapshot: the linear path CLOSES OVER it rather than
+ *  copying it into a Set, so a caller-owned array reaching here would stay
+ *  readable — and mutable — through the returned validator. */
 function createMembershipTest(allowed) {
     if (allowed.length > SET_MEMBERSHIP_THRESHOLD &&
         areAllMembersPrimitive(allowed)) {
@@ -50,13 +53,24 @@ export const oneOfPlugin = /*#__PURE__*/ definePlugin()({
         if (!isArray(allowed) || allowed.length === 0) {
             throw new PluginArgumentError(ctx.pluginName, "allowed", allowed);
         }
-        const isMember = createMembershipTest(allowed);
-        const rendered = describeAllowed(allowed);
+        // A built validator is a SNAPSHOT of what it was built from, and this list
+        // arrives BY REFERENCE: reached through the `enum` keyword it is the very
+        // array inside the caller's schema document. Without this copy, appending
+        // to that array in place after build() — a config reload that mutates the
+        // document rather than replacing it — silently widens a validator that is
+        // already serving traffic. It would also do so only SOMETIMES: the Set
+        // path in createMembershipTest copies and the linear path does not, so the
+        // behaviour would flip at a member count the caller has no reason to know
+        // about. Copying here, at the one point where the caller's array enters
+        // the plugin, is what makes both paths and the reported `expected` agree.
+        const members = Object.freeze(allowed.slice());
+        const isMember = createMembershipTest(members);
+        const rendered = describeAllowed(members);
         return check({
             code: ctx.code,
             messageFactory: ctx.messageFactory,
             severity: ctx.severity,
-            run: (value) => isMember(value) ? PASS : fail({ expected: allowed, actual: value }),
+            run: (value) => isMember(value) ? PASS : fail({ expected: members, actual: value }),
             describe: () => `Value must be one of: ${rendered}`,
             buildMessageContext: () => ({}),
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maroonedog/luq",
-  "version": "2.4.4",
+  "version": "2.6.0",
   "description": "Universal Model & API Definition Platform - TypeScript validation library evolving into cross-language code generation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -459,18 +459,20 @@
     "typecheck:src": "tsc --noEmit -p tsconfig.json",
     "typecheck:scripts": "tsc --noEmit -p scripts/tsconfig.json",
     "typecheck:bench": "tsc --noEmit -p bench/tsconfig.json",
-    "generate": "npm run generate:sources && npm run generate:exports && npm run generate:lock",
+    "generate": "npm run generate:sources && npm run generate:exports && npm run generate:lock && npm run generate:issue-codes",
     "generate:sources": "npm run generate:manifest && npm run generate:barrel && npm run generate:slot-catalog",
     "generate:slot-catalog": "npx ts-node --project scripts/tsconfig.json scripts/generate-slot-catalog.ts",
     "generate:manifest": "npx ts-node --project scripts/tsconfig.json scripts/generate-plugin-manifest.ts",
     "generate:barrel": "npx ts-node --project scripts/tsconfig.json scripts/generate-plugin-barrel.ts",
     "generate:exports": "npx ts-node --project scripts/tsconfig.json scripts/generate-package-exports.ts",
     "generate:lock": "npx ts-node --project scripts/tsconfig.json scripts/generate-plugin-catalog.ts",
+    "generate:issue-codes": "npx ts-node --project scripts/tsconfig.json scripts/generate-issue-code-catalog.ts",
     "check:exports": "npx ts-node --project scripts/tsconfig.json scripts/check-exports.ts --mode=exact",
     "check:catalog-lock": "npx ts-node --project scripts/tsconfig.json scripts/check-catalog-lock.ts",
+    "check:issue-code-lock": "npx ts-node --project scripts/tsconfig.json scripts/check-issue-code-lock.ts",
     "check:plugin-isolation": "npx ts-node --project scripts/tsconfig.json scripts/check-plugin-isolation.ts",
     "check:plugin-uniqueness": "npx ts-node --project scripts/tsconfig.json scripts/check-plugin-uniqueness.ts",
-    "check:catalog": "npm run check:plugin-uniqueness && npm run check:plugin-isolation && npm run check:exports && npm run check:catalog-lock",
+    "check:catalog": "npm run check:plugin-uniqueness && npm run check:plugin-isolation && npm run check:exports && npm run check:catalog-lock && npm run check:issue-code-lock",
     "check:size": "npx ts-node --project scripts/tsconfig.json scripts/measure-bundle-size.ts",
     "check:barrel-equivalence": "npx ts-node --project scripts/tsconfig.json scripts/check-barrel-equivalence.ts",
     "check:no-dynamic-code": "npx ts-node --project scripts/tsconfig.json scripts/check-no-dynamic-code.ts",
@@ -493,6 +495,7 @@
     "check:conformance-figures": "npx ts-node --project scripts/tsconfig.json scripts/check-conformance-figures.ts",
     "bench:competitors": "npx ts-node --project bench/tsconfig.json bench/competitors/report-competitors.ts",
     "bench:competitors:check": "npx ts-node --project bench/tsconfig.json bench/competitors/check-competitors.ts",
+    "bench:megamorphism": "npx ts-node --project bench/tsconfig.json bench/megamorphism/report-megamorphism.ts",
     "lint:ox": "oxlint -c .oxlintrc.json src bench",
     "lint:naming": "eslint \"src/**/*.ts\" \"bench/**/*.ts\"",
     "generate:perf-figures": "npx ts-node --project scripts/tsconfig.json scripts/check-perf-figures.ts --write",
@@ -538,9 +541,9 @@
     "ts-node": "^10.9.2",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
-    "valibot": "^1.4.2",
+    "valibot": "^1.5.0",
     "yup": "^1.7.1",
-    "zod": "^4.0.14"
+    "zod": "^4.6.2"
   },
   "sideEffects": false
 }