@json-schema-engine/core 0.0.1

package/src/result.ts

@@ -0,0 +1,252 @@
+// Result assembly (ADR 0003): the option checks that admit or reject a
+// combination of controls before any evaluation, and the assembly of a
+// Result from the flat surface and the located tree. Both tiers use it —
+// the interpreter after rendering its records, a compiled evaluator after
+// recording its tree — so presence rules and key order have one owner.
+
+import {
+  type AnnotationSelection,
+  type AnnotationUnit,
+  type BasicOutputDocument,
+  type DetailedOutputUnit,
+  type ErrorUnit,
+  type IrrelevantRendering,
+  type ListOutputDocument,
+  type OutputUnit,
+  type RenderInput,
+  type RenderNode,
+  type TraceUnit,
+  renderBasic,
+  renderDetailed,
+  renderHierarchical,
+  renderList,
+  renderTrace,
+  renderVerbose,
+} from "./output.js";
+
+/**
+ * Output format names (ADR 0003), each fixing a document structure and field
+ * vocabulary: `flag`, `basic`, `detailed`, `verbose` from IETF draft-03 §13;
+ * `list`, `hierarchical` from the machines-oriented output proposal.
+ */
+export type OutputFormat =
+  "flag" | "basic" | "detailed" | "verbose" | "list" | "hierarchical";
+
+const OUTPUT_FORMATS: ReadonlySet<string> = new Set<OutputFormat>([
+  "flag",
+  "basic",
+  "detailed",
+  "verbose",
+  "list",
+  "hierarchical",
+]);
+
+/** Thrown by `evaluate` for an unsupported combination of output options (ADR 0003: no silent no-ops). */
+export class OutputOptionsError extends Error {}
+
+/** Options for `Engine.evaluate`. */
+export interface EvaluateOptions {
+  /**
+   * Output format, by name; default `"flag"` (the minimal level: `valid`
+   * only). Every other name populates the flat `Result.errors`/
+   * `Result.annotations` surface and renders `Result.outputDocument` in the
+   * format's own structure ({@link OutputDocuments}).
+   */
+  output?: OutputFormat;
+  /**
+   * Request the verbose level for `list` or `hierarchical`: every unit is
+   * kept and irrelevant records (draft-03 §12.2) render marked, as
+   * `droppedErrors`/`droppedAnnotations` in the document and as
+   * `Result.droppedErrors`/`Result.droppedAnnotations`. `basic` and
+   * `detailed` are relevant-level by definition and reject it; `verbose` is
+   * the verbose level by definition.
+   */
+  verbose?: boolean;
+  /**
+   * Which annotations reach output: `false` (default) none, `true` all, or
+   * an {@link AnnotationSelection}. Independent of format and level; never
+   * affects dependency data or validation.
+   */
+  annotations?: boolean | AnnotationSelection;
+  /** Include `keyword`, `vocabulary`, and structured `params` on each flat error unit (D13). */
+  errorParams?: boolean;
+  /** Decorate flat units with schema-side source positions when available (D17). */
+  positions?: boolean;
+  /** Render the evaluation trace into `Result.trace`. */
+  trace?: boolean;
+}
+
+/** The document type each non-minimal {@link OutputFormat} renders. */
+export interface OutputDocuments {
+  basic: BasicOutputDocument;
+  detailed: DetailedOutputUnit;
+  verbose: DetailedOutputUnit;
+  list: ListOutputDocument;
+  hierarchical: OutputUnit;
+}
+
+/** The result of an evaluation. */
+export interface Result {
+  valid: boolean;
+  /** relevant errors, native field names; present on an invalid result of any non-flag format */
+  errors?: ErrorUnit[];
+  /** relevant annotations per the selection; present on a valid result when annotations are selected */
+  annotations?: AnnotationUnit[];
+  /** irrelevant errors (draft-03 §12.2); present at the verbose level */
+  droppedErrors?: ErrorUnit[];
+  /** irrelevant annotations per the selection; present at the verbose level when annotations are selected */
+  droppedAnnotations?: AnnotationUnit[];
+  /** the output document, in the requested format's structure ({@link OutputDocuments}) */
+  outputDocument?: OutputDocuments[keyof OutputDocuments];
+  /** the evaluation trace, present with `trace: true`; `errorIndexes` reference `errors` on this result */
+  trace?: TraceUnit;
+}
+
+/**
+ * {@link Result} narrowed by literal options: `outputDocument` takes the
+ * requested format's document type and `trace` is present when requested.
+ * A widened {@link EvaluateOptions} yields the plain `Result`.
+ */
+export type ResultFor<O extends EvaluateOptions> = Result &
+  ([O["output"]] extends [infer F extends keyof OutputDocuments]
+    ? { outputDocument: OutputDocuments[F] }
+    : unknown) &
+  ([O["trace"]] extends [true] ? { trace: TraceUnit } : unknown);
+
+/** What an evaluation must produce for a resolved set of output options. */
+export interface OutputDemand {
+  format: OutputFormat;
+  /** the verbose level: irrelevant records are rendered, marked */
+  verbose: boolean;
+  /** the located tree is built: every format but flag and basic, or `trace: true` */
+  tracing: boolean;
+  annotations: boolean | AnnotationSelection;
+}
+
+/**
+ * Every combination of controls is supported or rejected here, before any
+ * evaluation (ADR 0003).
+ */
+export function resolveOutputDemand(options: EvaluateOptions): OutputDemand {
+  const format = options.output ?? "flag";
+  if (!OUTPUT_FORMATS.has(format)) {
+    throw new OutputOptionsError(`unknown output format '${format}'`);
+  }
+  const annotations = options.annotations ?? false;
+  if (format === "flag") {
+    const requested: [string, boolean][] = [
+      ["verbose", options.verbose === true],
+      ["annotations", annotations !== false],
+      ["errorParams", options.errorParams === true],
+      ["positions", options.positions === true],
+      ["trace", options.trace === true],
+    ];
+    for (const [name, on] of requested) {
+      if (on) {
+        throw new OutputOptionsError(
+          `'${name}' has no effect with output "flag", which carries no ` +
+            `records (the minimal level); choose "basic" or another format`,
+        );
+      }
+    }
+  }
+  if (
+    options.verbose === true &&
+    (format === "basic" || format === "detailed")
+  ) {
+    throw new OutputOptionsError(
+      `'verbose' does not apply to output "${format}", a relevant-level ` +
+        `format by definition (IETF draft-03 §13.4); use "verbose", or ` +
+        `"list"/"hierarchical" with verbose: true`,
+    );
+  }
+  if (options.verbose === false && format === "verbose") {
+    throw new OutputOptionsError(
+      `output "verbose" is the verbose level by definition; ` +
+        `'verbose: false' contradicts it`,
+    );
+  }
+  return {
+    format,
+    verbose: format === "verbose" || options.verbose === true,
+    tracing:
+      format !== "flag" && (format !== "basic" || options.trace === true),
+    annotations,
+  };
+}
+
+/**
+ * The flat surface as one evaluation produced it. The arrays are placed on
+ * the {@link Result} as they are; `annotations` is empty on an invalid run
+ * or when none are selected, and the dropped pair is empty unless
+ * irrelevant records were retained (verbose demand).
+ */
+export interface ResultUnits {
+  errors: ErrorUnit[];
+  droppedErrors: ErrorUnit[];
+  annotations: AnnotationUnit[];
+  droppedAnnotations: AnnotationUnit[];
+}
+
+/**
+ * Assembles a {@link Result} from the flat surface and, when the demand
+ * built one, the located tree. `root` is required whenever
+ * `demand.tracing`; `rootLocation` is the root schema's canonical location
+ * (the `basic` document's own).
+ */
+export function assembleResult(
+  demand: OutputDemand,
+  valid: boolean,
+  units: ResultUnits,
+  root: RenderNode | null,
+  rootLocation: string,
+  trace: boolean,
+): Result {
+  const result: Result = { valid };
+  if (demand.format === "flag") return result;
+  if (!valid) result.errors = units.errors;
+  if (valid && demand.annotations !== false) {
+    result.annotations = units.annotations;
+  }
+  if (demand.verbose) {
+    result.droppedErrors = units.droppedErrors;
+    if (demand.annotations !== false) {
+      result.droppedAnnotations = units.droppedAnnotations;
+    }
+  }
+  const input: RenderInput | null = demand.tracing
+    ? {
+        errors: units.errors,
+        droppedErrors: units.droppedErrors,
+        annotations: units.annotations,
+        droppedAnnotations: units.droppedAnnotations,
+        root: root!,
+      }
+    : null;
+  if (trace) result.trace = renderTrace(input!.root);
+
+  const irrelevant: IrrelevantRendering = demand.verbose ? "mark" : "omit";
+  switch (demand.format) {
+    case "basic":
+      result.outputDocument = renderBasic(
+        valid,
+        rootLocation,
+        units.errors,
+        units.annotations,
+      );
+      break;
+    case "list":
+      result.outputDocument = renderList(input!, irrelevant);
+      break;
+    case "hierarchical":
+      result.outputDocument = renderHierarchical(input!, irrelevant);
+      break;
+    case "detailed":
+      result.outputDocument = renderDetailed(input!);
+      break;
+    case "verbose":
+      result.outputDocument = renderVerbose(input!);
+      break;
+  }
+  return result;
+}

package/src/uri.ts

@@ -0,0 +1,35 @@
+// URI handling for schema identification and reference resolution.
+
+/** Thrown when a reference cannot be resolved to an absolute URI. */
+export class UnresolvableRefError extends Error {}
+
+/**
+ * Resolves a reference URI against a base URI to an absolute URI.
+ * @throws UnresolvableRefError if the pair does not form a valid URI.
+ */
+export function resolveUri(ref: string, base: string): string {
+  try {
+    return new URL(ref, base).href;
+  } catch {
+    throw new UnresolvableRefError(`cannot resolve '${ref}' against '${base}'`);
+  }
+}
+
+/** A URI split into its resource part and decoded fragment. */
+export interface SplitUri {
+  /** URI without fragment. */
+  resource: string;
+  /** Decoded fragment, `null` if absent. */
+  fragment: string | null;
+}
+
+/** Splits a URI into its resource and decoded fragment parts. */
+export function splitFragment(uri: string): SplitUri {
+  const i = uri.indexOf("#");
+  return i === -1
+    ? { resource: uri, fragment: null }
+    : {
+        resource: uri.slice(0, i),
+        fragment: decodeURIComponent(uri.slice(i + 1)),
+      };
+}

package/src/walk.ts

@@ -0,0 +1,88 @@
+// Public schema-position walk (M8.6): the descent knowledge lives in each
+// keyword's analyze() facts, so adapters and tools stop hardcoding their own
+// applicator tables. Unlike the registry's registration walk (which owns
+// base-URI rebasing, anchor indexing, and reference collection), this walk
+// is deliberately tolerant: it runs on unvalidated input — e.g. a strict-
+// mode check before registration — where a malformed keyword value must be
+// skipped, not thrown. Registration keeps its InvalidSchemaError job.
+
+import { JsonValue, isObject, escapeSegment } from "./json.js";
+import { Dialect } from "./dialect.js";
+import { DEFAULT_MAX_DEPTH, MaxDepthExceededError } from "./registry.js";
+
+/**
+ * One schema position visited by {@link walkSchema}.
+ */
+export interface SchemaWalkVisit {
+  /** The value in schema position: an object or a boolean. */
+  readonly node: JsonValue;
+  /** JSON Pointer from the walk root. */
+  readonly pointer: string;
+  /** Applying keyword in the parent schema object; `null` at the root. */
+  readonly keyword: string | null;
+}
+
+/**
+ * Walks every schema position of `schema` reachable through the dialect's
+ * keyword facts (`analyze().subschemas`), visiting parents before children.
+ *
+ * Tolerant by design: values in schema position that are neither objects
+ * nor booleans are skipped, as are positions under keyword values whose
+ * `analyze()` rejects them — unknown keywords' values are never descended.
+ * Nesting beyond `maxDepth` still throws {@link MaxDepthExceededError}: the
+ * depth bound is a security posture, not a validity judgment.
+ */
+export function walkSchema(
+  schema: JsonValue,
+  dialect: Pick<Dialect, "keywords">,
+  visit: (v: SchemaWalkVisit) => void,
+  maxDepth: number = DEFAULT_MAX_DEPTH,
+): void {
+  const step = (
+    node: JsonValue,
+    pointer: string,
+    keyword: string | null,
+    depth: number,
+  ): void => {
+    if (depth > maxDepth) {
+      throw new MaxDepthExceededError(
+        `schema nesting exceeds maxDepth (${maxDepth}) at '#${pointer}'`,
+      );
+    }
+    if (typeof node === "boolean") {
+      visit({ node, pointer, keyword });
+      return;
+    }
+    if (!isObject(node)) return;
+    visit({ node, pointer, keyword });
+
+    for (const [name, value] of Object.entries(node)) {
+      const behavior = dialect.keywords.get(name)?.behavior;
+      if (!behavior?.analyze) continue;
+      let positions;
+      try {
+        positions = behavior.analyze(value, { schema: node }).subschemas;
+      } catch {
+        continue;
+      }
+      if (!positions) continue;
+      for (const relPath of positions) {
+        let child: JsonValue | undefined = value;
+        let suffix = "/" + escapeSegment(name);
+        for (const seg of relPath) {
+          child =
+            child === null || typeof child !== "object"
+              ? undefined
+              : Array.isArray(child)
+                ? child[seg as number]
+                : (child as Record<string, JsonValue>)[seg as string];
+          suffix += "/" + escapeSegment(String(seg));
+        }
+        if (child !== undefined) {
+          step(child, pointer + suffix, name, depth + 1);
+        }
+      }
+    }
+  };
+  step(schema, "", null, 0);
+}