@json-schema-engine/core 0.0.1

package/src/keywords/core.ts

@@ -0,0 +1,168 @@
+// Core vocabulary behaviors, plus shared behavior factories.
+
+import { JsonValue } from "../json.js";
+import { KeywordBehavior, StaticFacts } from "../dialect.js";
+
+/** 2020-12 core vocabulary URI. */
+export const VOCAB_CORE = "https://json-schema.org/draft/2020-12/vocab/core";
+
+/** Static facts for a keyword whose value is itself a subschema (e.g. `if`, `not`). */
+const SELF: StaticFacts = { subschemas: [[]] };
+/** Static facts for a keyword whose value is a name-keyed map of subschemas. */
+const mapPositions = (value: JsonValue): StaticFacts =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? { subschemas: Object.keys(value).map((k) => [k]) }
+    : {};
+
+/** Identifier/reserved keywords: no evaluation behavior, no annotation. */
+export const structural = (id: string): KeywordBehavior => ({
+  id,
+  structural: true,
+  analyze: () => ({ produces: [] }),
+  evaluate: () => true,
+  lower: () => {
+    /* inert in compiled code too */
+  },
+});
+
+/**
+ * A keyword whose subschemas exist (for identification) but whose
+ * evaluation is driven by a sibling (`then`/`else` via `if`).
+ */
+export const inertSubschema = (id: string): KeywordBehavior => ({
+  id,
+  analyze: () => SELF,
+  evaluate: () => true,
+  lower: () => {
+    /* the driving sibling owns the application */
+  },
+});
+
+/** EXEMPLAR (annotation-only class): the keyword's value is its annotation. */
+export const annotationOnly = (id: string): KeywordBehavior => ({
+  id,
+  evaluate: (_value, _cursor, ctx) => {
+    ctx.annotate();
+    return true;
+  },
+  lower: (_value, lctx) => {
+    lctx.emit({ kind: "annotate" });
+  },
+});
+
+/**
+ * Placeholder for keywords owed by a later milestone: loud failure beats
+ * silently treating a known assertion/applicator as an annotation.
+ */
+export const notImplemented = (
+  id: string,
+  milestone: string,
+): KeywordBehavior => ({
+  id,
+  evaluate: () => {
+    throw new Error(`keyword '${id}' is not implemented until ${milestone}`);
+  },
+});
+
+const referenceFacts = (value: JsonValue): StaticFacts =>
+  typeof value === "string"
+    ? {
+        references: [value],
+        // The resolved target applies in place, unconditionally.
+        applications: [
+          {
+            path: [],
+            ref: value,
+            mode: "inPlace",
+            conditional: false,
+            asserts: true,
+          },
+        ],
+      }
+    : {};
+
+/**
+ * EXEMPLAR (reference class): resolve against the lexical base, apply the
+ * target at the same cursor. The engine owns the evaluation-path extension
+ * and the frame, so a reference behavior is one line.
+ */
+export const $ref: KeywordBehavior = {
+  id: `${VOCAB_CORE}#$ref`,
+  analyze: referenceFacts,
+  evaluate: (value, _cursor, ctx) =>
+    ctx.applyResolved(ctx.resolveRef(value as string)),
+  lower: (value, lctx) => {
+    lctx.emit({
+      kind: "apply",
+      apply: {
+        path: [],
+        ref: value as string,
+        cursor: { kind: "here" },
+        fold: "allMustPass",
+      },
+    });
+  },
+};
+
+/** `$dynamicRef` (D8): resolves with dynamic-scope rebinding. */
+export const $dynamicRef: KeywordBehavior = {
+  id: `${VOCAB_CORE}#$dynamicRef`,
+  analyze: (value) => ({
+    ...referenceFacts(value),
+    dynamicScopeSensitive: true,
+  }),
+  evaluate: (value, _cursor, ctx) =>
+    ctx.applyResolved(ctx.resolveDynamic(value as string)),
+};
+
+// 2019-09 core vocabulary: $recursiveRef/$recursiveAnchor are D8's degenerate
+// case — resolution lives in the engine, anchor indexing in the registry's
+// identifier extractor, so both behaviors are one-liners.
+
+/** 2019-09 core vocabulary URI. */
+export const VOCAB_CORE_2019 =
+  "https://json-schema.org/draft/2019-09/vocab/core";
+
+/** `$recursiveRef`, 2019-09's degenerate case of `$dynamicRef` (D8). */
+export const $recursiveRef: KeywordBehavior = {
+  id: `${VOCAB_CORE_2019}#$recursiveRef`,
+  analyze: (value) => ({
+    ...referenceFacts(value),
+    dynamicScopeSensitive: true,
+  }),
+  evaluate: (value, _cursor, ctx) =>
+    ctx.applyResolved(ctx.resolveRecursive(value as string)),
+};
+
+/** `$recursiveAnchor`: structural only, indexed by the registration walk. */
+export const $recursiveAnchor: KeywordBehavior = structural(
+  `${VOCAB_CORE_2019}#$recursiveAnchor`,
+);
+
+/** `$defs`: a map of named subschemas, reachable only by reference. */
+export const $defs: KeywordBehavior = {
+  id: `${VOCAB_CORE}#$defs`,
+  structural: true,
+  analyze: mapPositions,
+  evaluate: () => true,
+  lower: () => {
+    /* contents are reachable only by reference */
+  },
+};
+
+/** The 2020-12 core vocabulary's keyword behaviors, by name. */
+export const coreVocabulary: Record<string, KeywordBehavior> = {
+  $ref,
+  $dynamicRef,
+  $defs,
+  $id: structural(`${VOCAB_CORE}#$id`),
+  $schema: structural(`${VOCAB_CORE}#$schema`),
+  $anchor: structural(`${VOCAB_CORE}#$anchor`),
+  // Dynamic-anchor indexing happens in the registration walk (D8).
+  $dynamicAnchor: structural(`${VOCAB_CORE}#$dynamicAnchor`),
+  $vocabulary: structural(`${VOCAB_CORE}#$vocabulary`),
+  // $comment's value MUST NOT be collected as an annotation.
+  $comment: structural(`${VOCAB_CORE}#$comment`),
+};
+
+export { mapPositions, SELF };

package/src/keywords/format.ts

@@ -0,0 +1,143 @@
+// The `format` keyword's asserting behavior (M7). Annotation-only `format`
+// is the annotationOnly factory in each dialect module; this file supplies
+// the assertion side: the format-table contract, the format-assertion
+// vocabulary, and the best-effort configuration switch.
+//
+// Two assertion mechanisms with deliberately different unknown-format
+// behavior:
+//  - format-assertion VOCABULARY: promises assertion, so a format the
+//    table cannot assert is refused at registration (UnknownFormatError).
+//  - format-annotation + the `assertFormats` configuration: best effort —
+//    recognized formats assert, unrecognized formats fall back to
+//    annotation-only.
+
+import { JsonValue, JsonType, jsonTypeOf } from "../json.js";
+import { KeywordBehavior } from "../dialect.js";
+import { lowerIR } from "../lowering.js";
+
+/** 2020-12 format-assertion vocabulary URI. */
+export const VOCAB_FORMAT_ASSERTION =
+  "https://json-schema.org/draft/2020-12/vocab/format-assertion";
+
+/**
+ * One format's definition. `types` scopes the assertion: instances of
+ * other types are vacuously valid (every standard JSON Schema format is
+ * string-scoped, but the shape admits non-string formats — the
+ * OpenAPI-registered int32/int64/double family applies to numbers).
+ */
+export interface FormatDefinition {
+  /** instance types the format constrains; default ["string"] */
+  readonly types?: readonly (JsonType | "integer")[];
+  /** true when the (type-scoped) instance conforms */
+  test(value: JsonValue): boolean;
+}
+
+/** Format name → definition. */
+export type FormatTable = Readonly<Record<string, FormatDefinition>>;
+
+/**
+ * A schema uses a format the engine cannot assert while the
+ * format-assertion vocabulary is in effect. Thrown at registration:
+ * that vocabulary promises assertion, so unsupported formats are refused,
+ * never silently annotated.
+ */
+export class UnknownFormatError extends Error {}
+
+const appliesTo = (
+  types: readonly (JsonType | "integer")[],
+  value: JsonValue,
+): boolean =>
+  types.some((t) =>
+    t === "integer"
+      ? typeof value === "number" && Number.isInteger(value)
+      : jsonTypeOf(value) === t,
+  );
+
+/**
+ * Builds an asserting `format` behavior over a table. `refuseUnknown`
+ * selects the vocabulary posture (refuse at registration) versus the
+ * best-effort configuration posture (annotate unknowns).
+ *
+ * Single-table contract: `lower()` resolves the format definition against
+ * the closed-over `table` at compile time, so it is correct only when that
+ * table is the compiling engine's `formats` — true by construction for the
+ * Engine-constructed instances, the only production call sites (both the
+ * `assertFormats` configuration and the format-assertion vocabulary close over
+ * `options.formats`, which the compiler reads back through `engine.formats`).
+ * A custom dialect that wires `assertingFormat` with a foreign table must drop
+ * `lower` (accepting the interpreter fallback) rather than compile against a
+ * table the artifact's runtime would not carry.
+ */
+export function assertingFormat(
+  id: string,
+  table: FormatTable,
+  refuseUnknown: boolean,
+): KeywordBehavior {
+  return {
+    id,
+    analyze: (value) => {
+      if (
+        refuseUnknown &&
+        typeof value === "string" &&
+        !Object.hasOwn(table, value)
+      ) {
+        throw new UnknownFormatError(
+          `format '${value}' is not supported; the format-assertion ` +
+            "vocabulary requires refusing formats it cannot assert",
+        );
+      }
+      // Report only formats the table can assert — the exact set lower()
+      // emits a formatTest for (an unknown format under the best-effort
+      // posture falls back to annotation-only and needs no table entry). This
+      // keeps plan.formats == the artifact's used-format set, so the runtime's
+      // missing-definition guard stays unreachable via public paths.
+      return typeof value === "string" && Object.hasOwn(table, value)
+        ? { formats: [value] }
+        : {};
+    },
+    lower: (value, lctx) => {
+      // Annotate first, unconditionally — evaluate()'s annotate-before-
+      // assertion order (format's annotation value is the name).
+      lctx.emit({ kind: "annotate" });
+      if (typeof value !== "string") return; // metaschema's concern
+      // Resolve against the closed-over table (the compiling engine's, per the
+      // single-table contract above); the name is a schema constant. A
+      // refuseUnknown instance never reaches here undefined — analyze() threw
+      // at registration — so an undefined definition is the best-effort
+      // posture's unrecognized format: fall back to annotation-only, emitting
+      // nothing further (evaluate() parity).
+      const definition = Object.hasOwn(table, value) ? table[value] : undefined;
+      if (definition === undefined) return;
+      const { and, not, typeIs, when, failWith, constant, formatTest } =
+        lowerIR;
+      lctx.emit(
+        when(
+          and(
+            typeIs(lctx.instance, ...(definition.types ?? ["string"])),
+            not(formatTest(value, lctx.instance)),
+          ),
+          [
+            failWith(
+              { format: constant(value) },
+              "must match format '" + value + "'",
+            ),
+          ],
+        ),
+      );
+    },
+    evaluate: (value, cursor, ctx) => {
+      // The annotation is recorded regardless of assertion outcome
+      // (format's annotation value is the format name).
+      ctx.annotate();
+      if (typeof value !== "string") return true; // metaschema's concern
+      const definition = Object.hasOwn(table, value) ? table[value] : undefined;
+      if (definition === undefined) return true; // best-effort fallback
+      if (!appliesTo(definition.types ?? ["string"], cursor.value)) {
+        return true;
+      }
+      if (definition.test(cursor.value)) return true;
+      ctx.error(`must match format '${value}'`, { format: value });
+      return false;
+    },
+  };
+}