@maroonedog/luq 2.5.0 → 2.7.0

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/runtime/create-issue.d.ts

@@ -13,6 +13,15 @@ export interface IssueRequest {
      * sees one call shape and needs no rule kind to dispatch on.
      */
     render(context: MessageContext): string;
+    /**
+     * The branch failures behind a composite, when the rule that failed is one.
+     *
+     * Passed rather than read off the detail because this layer never sees a
+     * rule kind: a presence policy closes over nothing and a check closes over
+     * its own IssueDetail, and keeping that asymmetry out of here is what lets
+     * one call shape serve both.
+     */
+    readonly causes?: readonly ValidationIssue[] | undefined;
 }
 /**
  * A plugin whose message factory throws must not take the validation down

package/dist/runtime/create-issue.js

@@ -17,12 +17,19 @@ function createIssue(request) {
         value: request.value,
         code: request.code,
     };
-    return Object.freeze({
+    const issue = {
         path: request.path,
         code: request.code,
         message: renderMessageOrFallback(request, context),
         severity: request.severity,
-    });
+    };
+    // Spread CONDITIONALLY. Writing `causes: request.causes` unconditionally
+    // would put the key on every issue the library reports, with the value
+    // undefined — and `"causes" in issue` would then answer true for a plain
+    // stringMin failure, which is exactly the question a caller asks it.
+    return Object.freeze(request.causes === undefined || request.causes.length === 0
+        ? issue
+        : { ...issue, causes: request.causes });
 }
 function renderMessageOrFallback(request, context) {
     try {

package/dist/runtime/create-issue.mjs

@@ -13,12 +13,19 @@ export function createIssue(request) {
         value: request.value,
         code: request.code,
     };
-    return Object.freeze({
+    const issue = {
         path: request.path,
         code: request.code,
         message: renderMessageOrFallback(request, context),
         severity: request.severity,
-    });
+    };
+    // Spread CONDITIONALLY. Writing `causes: request.causes` unconditionally
+    // would put the key on every issue the library reports, with the value
+    // undefined — and `"causes" in issue` would then answer true for a plain
+    // stringMin failure, which is exactly the question a caller asks it.
+    return Object.freeze(request.causes === undefined || request.causes.length === 0
+        ? issue
+        : { ...issue, causes: request.causes });
 }
 function renderMessageOrFallback(request, context) {
     try {

package/dist/runtime/run-field.js

@@ -78,6 +78,7 @@ function reportCheckFailure(check, detail, value, ruleContext, context) {
         severity: check.severity,
         value,
         render: (ctx) => check.describe(detail, ctx),
+        causes: detail.causes,
     }));
 }
 function runChecks(field, value, ruleContext, context, mark) {

package/dist/runtime/run-field.mjs

@@ -74,6 +74,7 @@ function reportCheckFailure(check, detail, value, ruleContext, context) {
         severity: check.severity,
         value,
         render: (ctx) => check.describe(detail, ctx),
+        causes: detail.causes,
     }));
 }
 function runChecks(field, value, ruleContext, context, mark) {

package/dist/types/index.d.ts

@@ -26,6 +26,18 @@ export interface ValidationIssue {
     /** Never optional: the chain resolves it once at build time, so a reader
      *  never has to re-implement the "absent means error" fallback. */
     readonly severity: IssueSeverity;
+    /**
+     * Why a composite failed, when the failing rule is one.
+     *
+     * `allOf`, `anyOf` and `oneOf` report their own code, which says WHICH
+     * applicator failed and never why. The branch failures behind it land here,
+     * so a caller can reach "minLength" without re-running the sub-schemas.
+     *
+     * ABSENT, not undefined, on an ordinary issue. A key present everywhere
+     * would make `"causes" in issue` answer true for every issue the library
+     * reports, which is the opposite of what it is for.
+     */
+    readonly causes?: readonly ValidationIssue[];
 }
 /** branch / index / causes let a composite failure explain itself. */
 export interface IssueDetail {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maroonedog/luq",
-  "version": "2.5.0",
-  "description": "Universal Model & API Definition Platform - TypeScript validation library evolving into cross-language code generation",
+  "version": "2.7.0",
+  "description": "Validate the TypeScript types you already have. Rules are declared against your own type's field paths, so a rule that does not apply to its field is a compile error.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -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",
@@ -507,13 +510,22 @@
     "url": "https://github.com/maroonedog/luq/issues"
   },
   "keywords": [
-    "form",
-    "validation",
     "typescript",
+    "validation",
     "validator",
-    "library"
+    "schema",
+    "json-schema",
+    "draft-07",
+    "openapi",
+    "standard-schema",
+    "standardschema",
+    "type-safe",
+    "form-validation",
+    "runtime-validation",
+    "content-security-policy",
+    "zero-dependencies"
   ],
-  "author": "",
+  "author": "maroonedog (https://github.com/maroonedog)",
   "license": "MIT",
   "files": [
     "dist"