corvus_json_schema 0.1.0

data/ext/corvus_json_schema/vendor/corvus-json-schema/src/results.rs

@@ -0,0 +1,316 @@
+//! Results collection: a port of Corvus.Text.Json's `JsonSchemaResultsCollector` and `JsonSchemaAnnotationProducer`.
+//!
+//! The evaluator opens a context per subschema application and writes keyword rows into the open context. Closing a
+//! context either commits it (a summary row, then its own rows newest first, after its committed descendants) or
+//! pops it (everything it and its descendants wrote is discarded). Levels decide which rows exist and which carry
+//! message text: Basic has failures without text, Detailed adds text to failures, Verbose keeps every row with text,
+//! annotations included.
+
+use std::collections::BTreeMap;
+
+use serde_json::Value;
+
+/// How much a results collector records.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub enum ResultsLevel {
+    /// Failures only, without message text (the lowest overhead).
+    Basic,
+    /// Failures only, with message text.
+    Detailed,
+    /// Every evaluation, passing and failing, with message text, including annotations.
+    Verbose,
+}
+
+/// One result row.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SchemaResult {
+    pub is_match: bool,
+    /// The message, or `""` when the level records none or the keyword has none. Annotation rows carry raw JSON.
+    pub message: String,
+    /// The path of keywords from the root schema (e.g. `/properties/name/type`).
+    pub evaluation_location: String,
+    /// The JSON pointer of the evaluated schema (or keyword) within its document (e.g. `/properties/name/type`).
+    pub schema_evaluation_location: String,
+    /// The JSON pointer of the instance location (e.g. `/name`).
+    pub document_evaluation_location: String,
+}
+
+/// A message for a result row, produced only when the level records message text.
+pub(crate) enum Message<'a> {
+    None,
+    Static(&'static str),
+    Lazy(&'a dyn Fn() -> String),
+}
+
+struct Frame {
+    eval_len: usize,
+    schema_path: String,
+    doc_len: usize,
+    commit_index: usize,
+    rows_start: usize,
+}
+
+/// Collects the results of an evaluation (`JsonSchemaResultsCollector`).
+pub struct JsonSchemaResultsCollector {
+    level: ResultsLevel,
+    committed: Vec<SchemaResult>,
+    frames: Vec<Frame>,
+    /// The rows written into open frames (each frame owns the tail from its `rows_start`).
+    pending: Vec<SchemaResult>,
+    eval_path: String,
+    schema_path: String,
+    doc_path: String,
+}
+
+/// Encodes a JSON pointer segment (`~` as `~0`, `/` as `~1`).
+pub fn encode_pointer_segment(segment: &str) -> std::borrow::Cow<'_, str> {
+    crate::uri::escape_pointer_token(segment)
+}
+
+impl JsonSchemaResultsCollector {
+    /// Creates a collector at the given level.
+    pub fn new(level: ResultsLevel) -> Self {
+        JsonSchemaResultsCollector {
+            level,
+            committed: Vec::new(),
+            frames: Vec::new(),
+            pending: Vec::new(),
+            eval_path: String::new(),
+            schema_path: String::new(),
+            doc_path: String::new(),
+        }
+    }
+
+    pub fn level(&self) -> ResultsLevel {
+        self.level
+    }
+
+    /// The results, in commit order.
+    pub fn results(&self) -> &[SchemaResult] {
+        &self.committed
+    }
+
+    /// Removes and returns the results.
+    pub fn take_results(&mut self) -> Vec<SchemaResult> {
+        std::mem::take(&mut self.committed)
+    }
+
+    // ------------------------------------------------------------------------------------------------------------
+    // The evaluator's side
+
+    /// Opens a child context. The evaluation path is extended by `eval_segment` (verbatim), the schema path is
+    /// replaced by `schema_location`, and the document path is extended by `doc_segment` (already pointer-encoded).
+    pub(crate) fn begin_child_context(
+        &mut self,
+        eval_segment: Option<&str>,
+        schema_location: Option<&str>,
+        doc_segment: Option<&str>,
+    ) {
+        self.frames.push(Frame {
+            eval_len: self.eval_path.len(),
+            schema_path: self.schema_path.clone(),
+            doc_len: self.doc_path.len(),
+            commit_index: self.committed.len(),
+            rows_start: self.pending.len(),
+        });
+        if let Some(s) = eval_segment {
+            self.eval_path.push('/');
+            self.eval_path.push_str(s);
+        }
+        if let Some(s) = schema_location {
+            self.schema_path.clear();
+            self.schema_path.push_str(s);
+        }
+        if let Some(s) = doc_segment {
+            self.doc_path.push('/');
+            self.doc_path.push_str(s);
+        }
+    }
+
+    /// Closes a child context. When the parent does not need the child's results (`parent_is_match`) they are
+    /// discarded below Verbose; otherwise the context's summary row is written and its rows are committed.
+    pub(crate) fn commit_child_context(&mut self, parent_is_match: bool, child_is_match: bool, message: Message<'_>) {
+        if parent_is_match && self.level != ResultsLevel::Verbose {
+            self.pop_child_context();
+            return;
+        }
+        let row =
+            self.row(child_is_match, message, self.eval_path.clone(), self.schema_path.clone(), self.doc_path.clone());
+        self.pending.push(row);
+        let frame = self.frames.pop().unwrap();
+        let rows = self.pending.split_off(frame.rows_start);
+        self.committed.extend(rows.into_iter().rev());
+        self.restore(frame);
+    }
+
+    /// Closes a child context and discards everything it and its descendants wrote.
+    pub(crate) fn pop_child_context(&mut self) {
+        let frame = self.frames.pop().unwrap();
+        self.committed.truncate(frame.commit_index);
+        self.pending.truncate(frame.rows_start);
+        self.restore(frame);
+    }
+
+    pub(crate) fn evaluated_keyword(&mut self, is_match: bool, message: Message<'_>, keyword: &str) {
+        if !is_match || self.level == ResultsLevel::Verbose {
+            let k = encode_pointer_segment(keyword);
+            let row = self.row(
+                is_match,
+                message,
+                format!("{}/{k}", self.eval_path),
+                format!("{}/{k}", self.schema_path),
+                self.doc_path.clone(),
+            );
+            self.pending.push(row);
+        }
+    }
+
+    pub(crate) fn evaluated_keyword_for_property(
+        &mut self,
+        is_match: bool,
+        message: Message<'_>,
+        property_name: &str,
+        keyword: &str,
+    ) {
+        if !is_match || self.level == ResultsLevel::Verbose {
+            let k = encode_pointer_segment(keyword);
+            let row = self.row(
+                is_match,
+                message,
+                format!("{}/{k}", self.eval_path),
+                format!("{}/{k}", self.schema_path),
+                format!("{}/{}", self.doc_path, encode_pointer_segment(property_name)),
+            );
+            self.pending.push(row);
+        }
+    }
+
+    /// An annotation: Verbose only; the keyword extends the evaluation path but not the schema path.
+    pub(crate) fn ignored_keyword(&mut self, message: Message<'_>, keyword: &str) {
+        if self.level == ResultsLevel::Verbose {
+            let row = self.row(
+                true,
+                message,
+                format!("{}/{}", self.eval_path, encode_pointer_segment(keyword)),
+                self.schema_path.clone(),
+                self.doc_path.clone(),
+            );
+            self.pending.push(row);
+        }
+    }
+
+    pub(crate) fn evaluated_boolean_schema(&mut self, is_match: bool) {
+        if !is_match || self.level == ResultsLevel::Verbose {
+            let row = self.row(
+                is_match,
+                Message::None,
+                self.eval_path.clone(),
+                self.schema_path.clone(),
+                self.doc_path.clone(),
+            );
+            self.pending.push(row);
+        }
+    }
+
+    fn row(
+        &self,
+        is_match: bool,
+        message: Message<'_>,
+        evaluation_location: String,
+        schema_evaluation_location: String,
+        document_evaluation_location: String,
+    ) -> SchemaResult {
+        let with_text = self.level == ResultsLevel::Verbose || (!is_match && self.level >= ResultsLevel::Detailed);
+        let message = if with_text {
+            match message {
+                Message::None => String::new(),
+                Message::Static(s) => s.to_string(),
+                Message::Lazy(f) => f(),
+            }
+        } else {
+            String::new()
+        };
+        SchemaResult {
+            is_match,
+            message,
+            evaluation_location,
+            schema_evaluation_location,
+            document_evaluation_location,
+        }
+    }
+
+    fn restore(&mut self, frame: Frame) {
+        self.eval_path.truncate(frame.eval_len);
+        self.schema_path = frame.schema_path;
+        self.doc_path.truncate(frame.doc_len);
+    }
+}
+
+/// An annotation extracted from verbose results.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Annotation {
+    /// The instance location (JSON pointer).
+    pub instance_location: String,
+    pub keyword: String,
+    /// The JSON pointer of the schema object that holds the keyword.
+    pub schema_location: String,
+    /// The annotation value as JSON text.
+    pub value: String,
+}
+
+/// The annotations in a verbose collector's results (`JsonSchemaAnnotationProducer.EnumerateAnnotations`).
+pub fn enumerate_annotations(collector: &JsonSchemaResultsCollector) -> impl Iterator<Item = Annotation> + '_ {
+    collector.results().iter().filter_map(|r| {
+        if !r.is_match || r.message.is_empty() {
+            return None;
+        }
+        let slash = r.evaluation_location.rfind('/')?;
+        if r.evaluation_location == r.schema_evaluation_location {
+            return None;
+        }
+        let keyword = &r.evaluation_location[slash + 1..];
+        let first = r.message.as_bytes()[0];
+        if keyword.is_empty()
+            || !(matches!(first, b'"' | b'{' | b'[' | b't' | b'f' | b'n' | b'-') || first.is_ascii_digit())
+        {
+            return None;
+        }
+        Some(Annotation {
+            instance_location: r.document_evaluation_location.clone(),
+            keyword: keyword.to_string(),
+            schema_location: r.schema_evaluation_location.clone(),
+            value: r.message.clone(),
+        })
+    })
+}
+
+/// `#` followed by the schema location, percent-encoded as a URI fragment (upper-case hex, UTF-8).
+pub fn schema_location_fragment(schema_location: &str) -> String {
+    let mut out = String::from("#");
+    for &byte in schema_location.as_bytes() {
+        let c = byte as char;
+        if byte < 128 && (c.is_ascii_alphanumeric() || "-._~!$&'()*+,;=:@/?".contains(c)) {
+            out.push(c);
+        } else {
+            out.push_str(&format!("%{byte:02X}"));
+        }
+    }
+    out
+}
+
+/// Annotations grouped by instance location, then keyword, then schema location fragment, with parsed values
+/// (`JsonSchemaAnnotationProducer.WriteAnnotationsTo`): `{ "/name": { "title": { "#/properties/name": "Name" } } }`.
+pub fn collect_annotations(
+    collector: &JsonSchemaResultsCollector,
+) -> BTreeMap<String, BTreeMap<String, BTreeMap<String, Value>>> {
+    let mut out: BTreeMap<String, BTreeMap<String, BTreeMap<String, Value>>> = BTreeMap::new();
+    for a in enumerate_annotations(collector) {
+        let value = serde_json::from_str(&a.value).unwrap_or(Value::String(a.value.clone()));
+        out.entry(a.instance_location)
+            .or_default()
+            .entry(a.keyword)
+            .or_default()
+            .insert(schema_location_fragment(&a.schema_location), value);
+    }
+    out
+}

data/ext/corvus_json_schema/vendor/corvus-json-schema/src/uri.rs

@@ -0,0 +1,274 @@
+//! URI handling for schema identification and reference resolution (RFC 3986 section 5).
+//!
+//! Mirrors the TypeScript port's `uri.ts`: reference resolution is implemented directly so that opaque bases
+//! (`urn:`, `tag:`) resolve the same way everywhere.
+
+use serde_json::Value;
+
+struct UriParts<'a> {
+    scheme: Option<&'a str>,
+    authority: Option<&'a str>,
+    path: &'a str,
+    query: Option<&'a str>,
+}
+
+/// Splits a URI into scheme, authority, path and query (the fragment must already be removed).
+fn parse(uri: &str) -> UriParts<'_> {
+    let mut rest = uri;
+    let mut scheme = None;
+    if let Some(colon) = scheme_end(rest) {
+        scheme = Some(&rest[..colon]);
+        rest = &rest[colon + 1..];
+    }
+    let mut authority = None;
+    if let Some(after) = rest.strip_prefix("//") {
+        let end = after.find(['/', '?']).unwrap_or(after.len());
+        authority = Some(&after[..end]);
+        rest = &after[end..];
+    }
+    let (path, query) = match rest.find('?') {
+        Some(q) => (&rest[..q], Some(&rest[q + 1..])),
+        None => (rest, None),
+    };
+    UriParts { scheme, authority, path, query }
+}
+
+/// The index of the ':' ending a URI scheme, if the text starts with one.
+fn scheme_end(s: &str) -> Option<usize> {
+    let bytes = s.as_bytes();
+    if bytes.is_empty() || !bytes[0].is_ascii_alphabetic() {
+        return None;
+    }
+    for (i, &b) in bytes.iter().enumerate().skip(1) {
+        if b == b':' {
+            return Some(i);
+        }
+        if !(b.is_ascii_alphanumeric() || b == b'+' || b == b'-' || b == b'.') {
+            return None;
+        }
+    }
+    None
+}
+
+/// True when the reference starts with a URI scheme.
+pub(crate) fn has_scheme(reference: &str) -> bool {
+    scheme_end(reference).is_some()
+}
+
+/// Splits a reference at its first '#'.
+pub(crate) fn split(reference: &str) -> (&str, &str) {
+    match reference.find('#') {
+        Some(i) => (&reference[..i], &reference[i + 1..]),
+        None => (reference, ""),
+    }
+}
+
+fn format(scheme: Option<&str>, authority: Option<&str>, path: &str, query: Option<&str>) -> String {
+    let mut s = String::with_capacity(path.len() + 32);
+    if let Some(sc) = scheme {
+        s.push_str(sc);
+        s.push(':');
+    }
+    if let Some(a) = authority {
+        s.push_str("//");
+        s.push_str(a);
+    }
+    s.push_str(path);
+    if let Some(q) = query {
+        s.push('?');
+        s.push_str(q);
+    }
+    s
+}
+
+fn remove_dot_segments(path: &str) -> String {
+    if !path.contains('.') {
+        return path.to_string();
+    }
+    let input: Vec<&str> = path.split('/').collect();
+    let mut out: Vec<&str> = Vec::with_capacity(input.len());
+    let last = input.len() - 1;
+    for (i, seg) in input.iter().enumerate() {
+        match *seg {
+            "." => {
+                if i == last {
+                    out.push("");
+                }
+            }
+            ".." => {
+                if out.len() > 1 || (out.len() == 1 && !out[0].is_empty()) {
+                    out.pop();
+                }
+                if i == last {
+                    out.push("");
+                }
+            }
+            s => out.push(s),
+        }
+    }
+    out.join("/")
+}
+
+fn merge(base: &UriParts<'_>, ref_path: &str) -> String {
+    if base.authority.is_some() && base.path.is_empty() {
+        return format!("/{ref_path}");
+    }
+    match base.path.rfind('/') {
+        Some(i) => format!("{}{}", &base.path[..=i], ref_path),
+        None => ref_path.to_string(),
+    }
+}
+
+fn normalize_parts(scheme: Option<&str>, authority: Option<&str>, path: &str, query: Option<&str>) -> String {
+    let scheme = scheme.map(|s| s.to_ascii_lowercase());
+    let mut path = remove_dot_segments(path);
+    let authority = authority.map(|a| {
+        let mut a = a.to_ascii_lowercase();
+        let default_port = match scheme.as_deref() {
+            Some("http") => Some(":80"),
+            Some("https") => Some(":443"),
+            _ => None,
+        };
+        if let Some(port) = default_port {
+            if a.ends_with(port) {
+                a.truncate(a.len() - port.len());
+            }
+        }
+        if path.is_empty() {
+            path = "/".to_string();
+        }
+        a
+    });
+    format(scheme.as_deref(), authority.as_deref(), &path, query)
+}
+
+/// Normalises an absolute URI (dropping its fragment) so that equivalent spellings compare equal.
+pub(crate) fn normalize(uri: &str) -> String {
+    let (uri_part, _) = split(uri);
+    if !has_scheme(uri_part) {
+        return uri_part.to_string();
+    }
+    let p = parse(uri_part);
+    normalize_parts(p.scheme, p.authority, p.path, p.query)
+}
+
+/// Resolves a reference (without fragment) against a base URI, returning the normalised absolute URI.
+pub(crate) fn resolve(base_uri: &str, reference: &str) -> String {
+    if reference.is_empty() {
+        return base_uri.to_string();
+    }
+    let r = parse(reference);
+    if r.scheme.is_some() {
+        return normalize_parts(r.scheme, r.authority, r.path, r.query);
+    }
+    if base_uri.is_empty() {
+        return reference.to_string();
+    }
+    let b = parse(base_uri);
+    let (authority, path, query);
+    if r.authority.is_some() {
+        authority = r.authority;
+        path = remove_dot_segments(r.path);
+        query = r.query;
+    } else {
+        if r.path.is_empty() {
+            path = b.path.to_string();
+            query = if r.query.is_some() { r.query } else { b.query };
+        } else {
+            path = if r.path.starts_with('/') {
+                remove_dot_segments(r.path)
+            } else {
+                remove_dot_segments(&merge(&b, r.path))
+            };
+            query = r.query;
+        }
+        authority = b.authority;
+    }
+    if b.scheme.is_some() {
+        normalize_parts(b.scheme, authority, &path, query)
+    } else {
+        format(None, authority, &path, query)
+    }
+}
+
+/// Percent-decodes a fragment (invalid escapes leave the text unchanged).
+pub(crate) fn decode_fragment(fragment: &str) -> String {
+    if !fragment.contains('%') {
+        return fragment.to_string();
+    }
+    let bytes = fragment.as_bytes();
+    let mut out = Vec::with_capacity(bytes.len());
+    let mut i = 0;
+    while i < bytes.len() {
+        if bytes[i] == b'%' {
+            let hex = |c: u8| (c as char).to_digit(16);
+            match (bytes.get(i + 1).and_then(|&c| hex(c)), bytes.get(i + 2).and_then(|&c| hex(c))) {
+                (Some(h), Some(l)) => {
+                    out.push((h * 16 + l) as u8);
+                    i += 3;
+                    continue;
+                }
+                _ => return fragment.to_string(),
+            }
+        }
+        out.push(bytes[i]);
+        i += 1;
+    }
+    String::from_utf8(out).unwrap_or_else(|_| fragment.to_string())
+}
+
+/// Escapes a JSON pointer token (`~` as `~0`, `/` as `~1`).
+pub(crate) fn escape_pointer_token(token: &str) -> std::borrow::Cow<'_, str> {
+    if !token.contains(['~', '/']) {
+        return std::borrow::Cow::Borrowed(token);
+    }
+    std::borrow::Cow::Owned(token.replace('~', "~0").replace('/', "~1"))
+}
+
+/// Resolves an RFC 6901 JSON pointer against a JSON value, returning the value and its normalised pointer.
+pub(crate) fn resolve_pointer<'a>(root: &'a Value, pointer: &str) -> Option<(&'a Value, String)> {
+    if pointer.is_empty() {
+        return Some((root, String::new()));
+    }
+    let rest = pointer.strip_prefix('/')?;
+    let mut current = root;
+    let mut path = String::with_capacity(pointer.len());
+    for raw in rest.split('/') {
+        let token = raw.replace("~1", "/").replace("~0", "~");
+        match current {
+            Value::Array(items) => {
+                let valid = token == "0"
+                    || (!token.is_empty() && !token.starts_with('0') && token.bytes().all(|b| b.is_ascii_digit()));
+                if !valid {
+                    return None;
+                }
+                let i: usize = token.parse().ok()?;
+                current = items.get(i)?;
+                path.push('/');
+                path.push_str(&token);
+            }
+            Value::Object(map) => {
+                current = map.get(&token)?;
+                path.push('/');
+                path.push_str(&escape_pointer_token(&token));
+            }
+            _ => return None,
+        }
+    }
+    Some((current, path))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn resolves_relative_references() {
+        assert_eq!(resolve("http://example.com/a/b.json", "c.json"), "http://example.com/a/c.json");
+        assert_eq!(resolve("http://example.com/a/b.json", "../c.json"), "http://example.com/c.json");
+        assert_eq!(resolve("http://Example.com:80", ""), "http://Example.com:80");
+        assert_eq!(normalize("HTTP://Example.COM:80#frag"), "http://example.com/");
+        assert_eq!(resolve("urn:uuid:deadbeef-1234", ""), "urn:uuid:deadbeef-1234");
+        assert_eq!(resolve("tag:example.com,2021:a", "b"), "tag:b");
+    }
+}

data/lib/corvus_json_schema/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CorvusJsonSchema
+  VERSION = "0.1.0"
+end

data/lib/corvus_json_schema.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# A high-performance JSON Schema evaluator (draft 4, 6, 7, 2019-09 and 2020-12) for Ruby, backed by the
+# corvus-json-schema Rust crate, with results collection and annotations.
+#
+#   validator = CorvusJsonSchema.compile({ "type" => "object", "required" => ["id"] })
+#   validator.valid?({ "id" => 3 })        # => true
+#   validator.valid_json?('{"id": 3}')     # => true, parsed in Rust
+#
+# Values are read in place: Hash (String or Symbol keys), Array, String, Symbol (as its name), Integer, Float, true,
+# false and nil. Integers beyond 64 bits become the nearest double. A value the schema examines that is none of these
+# raises (TypeError; ArgumentError for NaN and infinities; EncodingError for a String that is not valid UTF-8); values
+# are read only as the schema examines them.
+require_relative "corvus_json_schema/version"
+
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "corvus_json_schema/#{Regexp.last_match(1)}/corvus_json_schema"
+rescue LoadError
+  require_relative "corvus_json_schema/corvus_json_schema"
+end
+
+module CorvusJsonSchema
+  DIALECTS = {
+    draft4: 4, draft6: 6, draft7: 7, draft201909: 2019, draft202012: 2020
+  }.freeze
+
+  RESULTS_LEVELS = { basic: 0, detailed: 1, verbose: 2 }.freeze
+
+  # Compiles a schema (a Hash or Array, true or false, or JSON text) into a Validator.
+  #
+  # Options: default_dialect (:draft4, :draft6, :draft7, :draft201909, :draft202012; the dialect of schemas without
+  # $schema), assert_format (nil follows the vocabularies), assert_format_in_legacy_drafts, assert_content, formats (a
+  # Hash of format name to a callable returning whether a string is valid), resolver (a callable from an absolute URI
+  # to the document, as a Hash or JSON text, or nil when unknown), base_uri, entry_point (a reference such as
+  # "#/$defs/item") and max_depth (of in-place recursion, default 128).
+  def self.compile(schema, default_dialect: :draft202012, assert_format: nil, assert_format_in_legacy_drafts: false,
+                   assert_content: true, formats: nil, resolver: nil, base_uri: nil, entry_point: nil, max_depth: 128)
+    dialect = DIALECTS.fetch(default_dialect) { raise ArgumentError, "unknown dialect #{default_dialect.inspect}" }
+    Native.compile(schema, dialect, assert_format, assert_format_in_legacy_drafts, assert_content, formats, resolver,
+                   base_uri, entry_point, Integer(max_depth))
+  end
+
+  # The version of the corvus-json-schema crate the extension was built from.
+  def self.crate_version
+    Native.crate_version
+  end
+
+  # A compiled schema: valid?(value), valid_json?(text) and evaluate(value, collector).
+  class Validator
+    # Evaluates the value, replacing the collector's results with this evaluation's (every keyword is evaluated and
+    # reported at the collector's level). Returns whether the value is valid.
+    def evaluate(value, collector)
+      native_evaluate(value, collector)
+    end
+  end
+
+  # The results of the latest evaluation into it: results (rows as Hashes) and annotations (from a :verbose
+  # evaluation, grouped by instance location, keyword and schema location).
+  class Collector
+    def self.new(level = :basic)
+      native_new(RESULTS_LEVELS.fetch(level) { raise ArgumentError, "unknown results level #{level.inspect}" })
+    end
+  end
+end