lens_core 0.1.0

data/lib/lens_core/validation.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module LensCore
+  # Shared checks and canonicalization used by every value object, so a
+  # report built in Ruby and a report parsed from text obey the same rules.
+  # `name` is a member name or a path (Array) to one; errors carry it.
+  module Validation
+    ABSOLUTE_URI = /\A[A-Za-z][A-Za-z0-9+.-]*:\S+\z/
+    TIMESTAMP = /\A(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})T
+                 (?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?:\.\d+)?
+                 (?:Z|[+-](?<off_hour>\d{2}):(?<off_minute>\d{2}))\z/x
+    CLOCK_LIMITS = { "hour" => 23, "minute" => 59, "second" => 59,
+                     "off_hour" => 23, "off_minute" => 59 }.freeze
+    TEXT_ENCODINGS = [Encoding::UTF_8, Encoding::US_ASCII].freeze
+
+    module_function
+
+    def fail_at(detail, name)
+      raise SchemaError.new(detail, Array(name))
+    end
+
+    def required(value, name)
+      fail_at("is required", name) if value.nil?
+      value
+    end
+
+    def object(value, name = nil)
+      return value if required(value, name).is_a?(Hash)
+
+      fail_at("must be an object", name)
+    end
+
+    def array(value, name)
+      return value if required(value, name).is_a?(Array)
+
+      fail_at("must be an array", name)
+    end
+
+    def string(value, name, allow_empty: false)
+      required(value, name)
+      fail_at("must be a string", name) unless value.is_a?(String)
+
+      text(value, name)
+      fail_at("must not be empty", name) if value.empty? && !allow_empty
+
+      value.frozen? ? value : value.dup.freeze
+    end
+
+    # An optional string member: nil stays nil.
+    def optional_string(value, name)
+      value.nil? ? nil : string(value, name)
+    end
+
+    def integer(value, name, min:)
+      required(value, name)
+      fail_at("must be an integer", name) unless value.is_a?(Integer)
+      fail_at("must be >= #{min}", name) if value < min
+
+      value
+    end
+
+    def boolean(value, name)
+      return value if [true, false].include?(required(value, name))
+
+      fail_at("must be true or false", name)
+    end
+
+    def one_of(value, allowed, name)
+      value = value.to_s if value.is_a?(Symbol)
+      return value if allowed.include?(string(value, name))
+
+      fail_at("must be one of #{allowed.join(', ')}", name)
+    end
+
+    def absolute_uri(value, name)
+      return value if ABSOLUTE_URI.match?(string(value, name))
+
+      fail_at("must be an absolute URI", name)
+    end
+
+    # Accepts a Time or an RFC 3339 string with an explicit offset; returns a
+    # frozen UTC Time, or nil when the member is absent.
+    def timestamp(value, name)
+      return nil if value.nil?
+      return value.dup.utc.freeze if value.is_a?(Time)
+
+      string(value, name)
+      return Time.iso8601(value).utc.freeze if rfc3339?(value)
+
+      fail_at("must be an RFC 3339 timestamp", name)
+    rescue ArgumentError
+      fail_at("must be an RFC 3339 timestamp", name)
+    end
+
+    # The lexical form plus real calendar and clock values, so Time never
+    # rolls an impossible date or hour 24 over into the next day.
+    def rfc3339?(value)
+      match = TIMESTAMP.match(value) or return false
+      part = match.named_captures.transform_values(&:to_i)
+
+      Date.valid_date?(part["year"], part["month"], part["day"]) &&
+        CLOCK_LIMITS.all? { |key, max| part[key] <= max }
+    end
+
+    def text(value, name)
+      return if TEXT_ENCODINGS.include?(value.encoding) && value.valid_encoding?
+
+      raise InvalidEncodingError, "#{Array(name).join('.')}: not valid UTF-8"
+    end
+
+    # Deep copy of a JSON-safe value, frozen, with object keys sorted
+    # lexically (by bytes). Raises SchemaError for anything JSON cannot carry.
+    def json_value(value, name)
+      case value
+      when nil, true, false, Integer, Float, String
+        json_scalar(value, name)
+      when Array then json_array(value, name)
+      when Hash then json_object(value, name)
+      else fail_at("must be JSON-safe (got #{value.class})", name)
+      end
+    end
+
+    def json_scalar(value, name)
+      if value.is_a?(Float) && !value.finite?
+        fail_at("must be a finite number", name)
+      end
+
+      value.is_a?(String) ? string(value, name, allow_empty: true) : value
+    end
+
+    def json_array(list, name)
+      list.each_with_index.map { |v, i| json_value(v, [*name, i]) }.freeze
+    end
+
+    def json_object(hash, name)
+      hash.each_key do |key|
+        fail_at("object keys must be strings", name) unless key.is_a?(String)
+
+        text(key, name)
+      end
+      hash.sort_by { |key, _| key.b }
+        .to_h { |key, v| [key.dup.freeze, json_value(v, [*name, key])] }
+        .freeze
+    end
+
+    # A diagnostic's `context`: a JSON-safe object.
+    def context(value)
+      json_object(object(value, "context"), "context")
+    end
+
+    # Extension members: JSON-safe values under keys that are not standard.
+    def extensions(hash, standard, name = [])
+      json_object(object(hash, name), name).tap do |ext|
+        clash = ext.keys & standard
+        next if clash.empty?
+
+        fail_at("#{clash.first} is a standard member, not an extension", name)
+      end
+    end
+  end
+end

data/lib/lens_core/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module LensCore
+  # Gem version.
+  VERSION = "0.1.0"
+
+  # Major version of the wire format this gem reads and writes. It is the
+  # value of the `schema_version` member and is independent of VERSION.
+  SCHEMA_VERSION = 1
+end

data/lib/lens_core.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lens_core/version"
+require_relative "lens_core/errors"
+require_relative "lens_core/schema"
+require_relative "lens_core/validation"
+require_relative "lens_core/node"
+require_relative "lens_core/citation"
+require_relative "lens_core/location"
+require_relative "lens_core/producer"
+require_relative "lens_core/profile"
+require_relative "lens_core/diagnostic"
+require_relative "lens_core/report"
+require_relative "lens_core/parsers/text"
+require_relative "lens_core/parsers/json"
+require_relative "lens_core/parsers/yaml"
+require_relative "lens_core/renderers/json"
+require_relative "lens_core/renderers/yaml"
+require_relative "lens_core/renderers/human"
+
+# Format-neutral conformance diagnostics: a report model (schema version
+# LensCore::SCHEMA_VERSION), JSON and YAML parsers, and JSON, YAML and
+# human-readable renderers. It has no runtime dependencies.
+module LensCore
+end

data/schemas/lens-diagnostics-v1.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/claricle/lens_core/main/schemas/lens-diagnostics-v1.json",
+  "title": "LensCore diagnostics report, schema version 1",
+  "description": "Normative wire format. Unknown object members are permitted everywhere (additive evolution) except inside `summary`, where they are ignored. See docs/diagnostics-v1.adoc for the rules JSON Schema cannot express.",
+  "type": "object",
+  "required": ["schema_version", "producer", "profile", "valid", "summary", "diagnostics"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "producer": { "$ref": "#/$defs/producer" },
+    "profile": { "$ref": "#/$defs/profile" },
+    "timestamp": { "$ref": "#/$defs/timestamp" },
+    "valid": { "type": "boolean" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "diagnostics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/diagnostic" }
+    }
+  },
+  "if": { "properties": { "valid": { "const": true } }, "required": ["valid"] },
+  "then": { "properties": { "summary": { "properties": { "errors": { "const": 0 } } } } },
+  "$defs": {
+    "text": { "type": "string", "minLength": 1 },
+    "count": { "type": "integer", "minimum": 0 },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
+    },
+    "producer": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "$ref": "#/$defs/text" },
+        "version": { "$ref": "#/$defs/text" }
+      }
+    },
+    "profile": {
+      "type": "object",
+      "required": ["id", "citations"],
+      "properties": {
+        "id": { "$ref": "#/$defs/text" },
+        "citations": { "$ref": "#/$defs/citations" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["errors", "warnings", "infos"],
+      "properties": {
+        "errors": { "$ref": "#/$defs/count" },
+        "warnings": { "$ref": "#/$defs/count" },
+        "infos": { "$ref": "#/$defs/count" }
+      }
+    },
+    "citations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/citation" }
+    },
+    "citation": {
+      "type": "object",
+      "required": ["uri"],
+      "properties": {
+        "uri": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:\\S+$" },
+        "label": { "$ref": "#/$defs/text" }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": ["severity", "kind", "requirement_id", "message"],
+      "properties": {
+        "severity": { "enum": ["error", "warning", "info"] },
+        "kind": { "$ref": "#/$defs/text" },
+        "requirement_id": { "$ref": "#/$defs/text" },
+        "message": { "$ref": "#/$defs/text" },
+        "citations": { "$ref": "#/$defs/citations" },
+        "remediation": { "$ref": "#/$defs/text" },
+        "context": { "type": "object" },
+        "location": { "$ref": "#/$defs/location" }
+      }
+    },
+    "location": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": { "enum": ["xml", "binary"] }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "xml" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "line": { "type": "integer", "minimum": 1 },
+              "column": { "type": "integer", "minimum": 1 },
+              "path": { "$ref": "#/$defs/text" },
+              "byte_offset": false,
+              "byte_length": false,
+              "record_index": false,
+              "record_type": false
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "binary" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "byte_offset": { "type": "integer", "minimum": 0 },
+              "byte_length": { "type": "integer", "minimum": 0 },
+              "record_index": { "type": "integer", "minimum": 0 },
+              "record_type": { "$ref": "#/$defs/text" },
+              "line": false,
+              "column": false,
+              "path": false
+            }
+          }
+        }
+      ]
+    }
+  }
+}

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: lens_core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: One diagnostics report shape (schema version 1) that any format checker
+  can emit, with JSON and YAML parsers and JSON, YAML and human-readable renderers.
+  No runtime dependencies.
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.adoc
+- Rakefile
+- docs/diagnostics-v1.adoc
+- lens_core.gemspec
+- lib/lens_core.rb
+- lib/lens_core/citation.rb
+- lib/lens_core/diagnostic.rb
+- lib/lens_core/errors.rb
+- lib/lens_core/location.rb
+- lib/lens_core/node.rb
+- lib/lens_core/parsers/json.rb
+- lib/lens_core/parsers/text.rb
+- lib/lens_core/parsers/yaml.rb
+- lib/lens_core/producer.rb
+- lib/lens_core/profile.rb
+- lib/lens_core/renderers/human.rb
+- lib/lens_core/renderers/json.rb
+- lib/lens_core/renderers/yaml.rb
+- lib/lens_core/report.rb
+- lib/lens_core/schema.rb
+- lib/lens_core/validation.rb
+- lib/lens_core/version.rb
+- schemas/lens-diagnostics-v1.json
+homepage: https://github.com/claricle/lens_core
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://github.com/claricle/lens_core
+  source_code_uri: https://github.com/claricle/lens_core
+  bug_tracker_uri: https://github.com/claricle/lens_core/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Format-neutral conformance diagnostics model and renderers.
+test_files: []