lens_core 0.1.0

data/lib/lens_core/node.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module LensCore
+  # Base of the immutable value objects. A node has standard members (named by
+  # MEMBERS, in schema order) plus extensions: additional JSON-safe members a
+  # compatible v1 producer may add. Extensions are kept and re-emitted after
+  # the standard members, sorted lexically.
+  class Node
+    attr_reader :extensions
+
+    def self.members
+      self::MEMBERS
+    end
+
+    # Splits a wire object into [standard members, extensions]. A standard
+    # member is never null: absent optional members are omitted.
+    def self.split(hash, name = nil)
+      Validation.object(hash, name)
+      known, extra = hash.partition { |key, _| members.include?(key) }
+        .map(&:to_h)
+      reject_nulls(known)
+      [known, extra]
+    end
+
+    def self.reject_nulls(known)
+      known.each do |key, value|
+        next unless value.nil?
+
+        Validation.fail_at("must not be null (omit the member instead)", key)
+      end
+    end
+    private_class_method :reject_nulls
+
+    def initialize(extensions: {})
+      @extensions = Validation.extensions(extensions, self.class.members)
+    end
+
+    # Canonical wire form: standard members in schema order (absent optional
+    # members omitted), then extensions.
+    def to_h
+      standard_members.compact.merge(extensions)
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    private
+
+    def standard_members
+      raise NotImplementedError
+    end
+  end
+end

data/lib/lens_core/parsers/json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LensCore
+  module Parsers
+    # JSON text -> Report.
+    module Json
+      module_function
+
+      # @param input [String] a JSON document
+      # @return [LensCore::Report]
+      # @raise [LensCore::Error] see lib/lens_core/errors.rb
+      def parse(input)
+        Report.from_h(decode(Text.decode(input)))
+      end
+
+      def decode(text)
+        ::JSON.parse(text, allow_nan: false)
+      rescue ::JSON::ParserError => e
+        raise ParseError, "malformed JSON: #{e.message.lines.first.to_s.strip}"
+      end
+    end
+  end
+end

data/lib/lens_core/parsers/text.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module LensCore
+  module Parsers
+    # Input decoding shared by the JSON and YAML parsers.
+    module Text
+      BOM = ""
+      READABLE = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::BINARY].freeze
+
+      module_function
+
+      # Returns the input as valid UTF-8 text, or raises. Strings tagged
+      # UTF-8, US-ASCII or binary (the usual result of reading a file in
+      # "rb" mode) are read as UTF-8; any other encoding is rejected rather
+      # than transcoded, so every accepted byte stream has one meaning.
+      def decode(input)
+        unless input.is_a?(String)
+          raise ParseError, "expected a String, got #{input.class}"
+        end
+
+        text = utf8(input)
+        if text.start_with?(BOM)
+          raise ParseError, "a byte order mark is not allowed"
+        end
+
+        text
+      end
+
+      def utf8(input)
+        unless READABLE.include?(input.encoding)
+          raise InvalidEncodingError, "input is #{input.encoding}, not UTF-8"
+        end
+
+        text = input.dup.force_encoding(Encoding::UTF_8)
+        return text if text.valid_encoding?
+
+        raise InvalidEncodingError, "input is not valid UTF-8"
+      end
+    end
+  end
+end

data/lib/lens_core/parsers/yaml.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module LensCore
+  module Parsers
+    # YAML text -> Report. Only plain data is loaded: no object tags, symbols
+    # or aliases. A Time is permitted solely so an unquoted RFC 3339
+    # `timestamp` works; anywhere else it fails as "must be a string".
+    # The document is first read as a Psych AST, so explicit tags other than
+    # the core scalar and collection ones are refused before any object is
+    # built, and the unquoted `timestamp` is checked in its written form.
+    module Yaml
+      CORE_TAG =
+        /\A(?:!!|tag:yaml\.org,2002:)(?:str|int|float|bool|null|map|seq)\z/
+      DATE_LIKE = /\A\d{4}-\d/
+
+      module_function
+
+      # @param input [String] a YAML document
+      # @return [LensCore::Report]
+      # @raise [LensCore::Error] see lib/lens_core/errors.rb
+      def parse(input)
+        Report.from_h(decode(Text.decode(input)))
+      end
+
+      def decode(text)
+        preflight(::YAML.parse(text))
+        ::YAML.safe_load(text, permitted_classes: [Time],
+                               permitted_symbols: [], aliases: false)
+      rescue ::Psych::DisallowedClass, ::Psych::BadAlias => e
+        raise UnsafeYamlError, "unsafe YAML: #{e.message}"
+      rescue ::Psych::SyntaxError => e
+        raise ParseError, "malformed YAML: #{e.message}"
+      end
+
+      def preflight(document)
+        return unless document
+
+        document.root.each do |node|
+          tag = node.tag
+          next if tag.nil? || CORE_TAG.match?(tag)
+
+          raise UnsafeYamlError, "unsafe YAML: tag #{tag} is not allowed"
+        end
+        check_timestamp(document.root)
+      end
+
+      # Psych turns an unquoted date-shaped scalar into a Time and forgets how
+      # it was written, so the written form is validated here.
+      def check_timestamp(root)
+        return unless root.is_a?(::Psych::Nodes::Mapping)
+
+        root.children.each_slice(2) do |key, value|
+          next unless key.respond_to?(:value) && key.value == "timestamp"
+          next unless written_date?(value)
+
+          Validation.timestamp(value.value, "timestamp")
+        end
+      end
+
+      def written_date?(node)
+        node.is_a?(::Psych::Nodes::Scalar) && node.plain &&
+          DATE_LIKE.match?(node.value)
+      end
+    end
+  end
+end

data/lib/lens_core/producer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LensCore
+  # The tool that produced a report.
+  class Producer < Node
+    MEMBERS = %w[name version].freeze
+
+    attr_reader :name, :version
+
+    def self.from_h(hash)
+      known, extra = split(hash)
+      new(name: known["name"], version: known["version"], extensions: extra)
+    end
+
+    def initialize(name:, version:, extensions: {})
+      @name = Validation.string(name, "name")
+      @version = Validation.string(version, "version")
+      super(extensions: extensions)
+      freeze
+    end
+
+    private
+
+    def standard_members
+      { "name" => name, "version" => version }
+    end
+  end
+end

data/lib/lens_core/profile.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module LensCore
+  # The profile (rule set) a document was checked against.
+  class Profile < Node
+    MEMBERS = %w[id citations].freeze
+
+    attr_reader :id, :citations
+
+    def self.from_h(hash)
+      known, extra = split(hash)
+      new(id: known["id"], citations: Citation.list_from_h(known["citations"]),
+          extensions: extra)
+    end
+
+    def initialize(id:, citations: [], extensions: {})
+      @id = Validation.string(id, "id")
+      @citations = Citation.check_list(citations)
+      super(extensions: extensions)
+      freeze
+    end
+
+    private
+
+    def standard_members
+      { "id" => id, "citations" => citations.map(&:to_h) }
+    end
+  end
+end

data/lib/lens_core/renderers/human.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LensCore
+  module Renderers
+    # Report -> plain text for people. No colour, no terminal control codes,
+    # no wrapping: the same report always yields the same text.
+    #
+    #   svg-lens 0.2.4, profile example-profile
+    #   INVALID: 1 error, 1 warning, 1 info
+    #
+    #   error  REQ-001  (unsupported_element)
+    #     at line 3, column 5, /svg/foo
+    #     <message>
+    #     fix: <remediation>
+    #     see: <label> <uri>
+    #     context: {"key":"value"}
+    module Human
+      # How each coordinate reads, in display order.
+      PLACES = {
+        "xml" => [["line", "line "], ["column", "column "], ["path", ""]],
+        "binary" => [
+          ["byte_offset", "byte offset "],
+          ["byte_length", "length "],
+          ["record_index", "record "],
+          ["record_type", ""],
+        ],
+      }.freeze
+
+      module_function
+
+      def render(report)
+        lines = header(report)
+        report.diagnostics.each { |d| lines.push("", *entry(d)) }
+        "#{lines.join("\n")}\n"
+      end
+
+      def header(report)
+        ["#{report.producer.name} #{report.producer.version}, " \
+         "profile #{report.profile.id}",
+         *("Checked at #{report.to_h['timestamp']}" if report.timestamp),
+         verdict(report)]
+      end
+
+      def verdict(report)
+        counts = report.summary.map do |key, count|
+          noun = key.delete_suffix("s")
+          "#{count} #{noun}#{'s' unless count == 1}"
+        end
+        "#{report.valid ? 'VALID' : 'INVALID'}: #{counts.join(', ')}"
+      end
+
+      def entry(diagnostic)
+        [headline(diagnostic),
+         *("  at #{place(diagnostic.location)}" if diagnostic.location),
+         *diagnostic.message.each_line(chomp: true).map { |l| "  #{l}" },
+         *("  fix: #{diagnostic.remediation}" if diagnostic.remediation),
+         *diagnostic.citations.map { |c| citation_line(c) },
+         *context_line(diagnostic.context)]
+      end
+
+      def citation_line(citation)
+        "  see: #{[citation.label, citation.uri].compact.join(' ')}"
+      end
+
+      def headline(diagnostic)
+        "#{diagnostic.severity}  #{diagnostic.requirement_id}  " \
+          "(#{diagnostic.kind})"
+      end
+
+      def context_line(context)
+        context.empty? ? [] : ["  context: #{::JSON.generate(context)}"]
+      end
+
+      def place(location)
+        parts = PLACES.fetch(location.type).filter_map do |key, prefix|
+          value = location.coordinates[key]
+          "#{prefix}#{value}" unless value.nil?
+        end
+        parts.empty? ? "(#{location.type}, no coordinates)" : parts.join(", ")
+      end
+    end
+  end
+end

data/lib/lens_core/renderers/json.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LensCore
+  module Renderers
+    # Report -> canonical JSON: two-space indent, schema key order, one
+    # trailing newline. Parsing canonical JSON and rendering it again
+    # returns the same bytes.
+    module Json
+      module_function
+
+      def render(report)
+        "#{::JSON.pretty_generate(report.to_h)}\n"
+      end
+    end
+  end
+end

data/lib/lens_core/renderers/yaml.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module LensCore
+  module Renderers
+    # Report -> YAML with the same content and key order as the JSON form.
+    module Yaml
+      module_function
+
+      def render(report)
+        ::YAML.dump(report.to_h, line_width: -1)
+      end
+    end
+  end
+end

data/lib/lens_core/report.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module LensCore
+  # A complete diagnostics report (schema version 1).
+  #
+  # `valid` is stated by the producer, not derived: whether warnings fail a
+  # document is the producer's policy. It cannot be true while the report
+  # holds an error. `summary` is always derived from the diagnostics.
+  class Report < Node
+    MEMBERS = %w[schema_version producer profile timestamp valid summary
+                 diagnostics].freeze
+    SUMMARY_KEYS = {
+      "errors" => "error", "warnings" => "warning", "infos" => "info"
+    }.freeze
+
+    attr_reader :producer, :profile, :valid, :diagnostics, :timestamp
+
+    # Builds a Report from a decoded JSON/YAML object. Raises
+    # UnsupportedVersionError, SchemaError or InvalidEncodingError.
+    def self.from_h(hash)
+      unless hash.is_a?(Hash)
+        raise SchemaError, "the document must be an object"
+      end
+
+      check_version(hash["schema_version"])
+      known, extra = split(hash)
+      build(known, extra).tap { |r| r.check_summary(known["summary"]) }
+    end
+
+    def self.check_version(version)
+      Validation.integer(version, "schema_version", min: 0)
+      return if version == SCHEMA_VERSION
+
+      raise UnsupportedVersionError,
+            "schema_version #{version} is not supported " \
+            "(this is LensCore #{VERSION}, schema version #{SCHEMA_VERSION})"
+    end
+
+    def self.build(known, extra)
+      new(
+        producer: within("producer") { Producer.from_h(known["producer"]) },
+        profile: within("profile") { Profile.from_h(known["profile"]) },
+        diagnostics: diagnostics_from(known["diagnostics"]),
+        valid: known["valid"], timestamp: known["timestamp"], extensions: extra
+      )
+    end
+
+    def self.within(name)
+      yield
+    rescue SchemaError => e
+      raise e.within(name)
+    end
+
+    def self.diagnostics_from(list)
+      Validation.array(list, "diagnostics").each_with_index.map do |item, i|
+        within("diagnostics") { within(i) { Diagnostic.from_h(item) } }
+      end
+    end
+    private_class_method :check_version, :build, :within, :diagnostics_from
+
+    # @param timestamp [Time, String, nil] supplied by the caller; never
+    #   defaulted to the current time.
+    def initialize(producer:, profile:, valid:, diagnostics: [],
+                   timestamp: nil, extensions: {})
+      @producer = check_type(producer, Producer, "producer")
+      @profile = check_type(profile, Profile, "profile")
+      @diagnostics = check_diagnostics(diagnostics)
+      @valid = check_valid(valid)
+      @timestamp = Validation.timestamp(timestamp, "timestamp")
+      super(extensions: extensions)
+      freeze
+    end
+
+    def schema_version
+      SCHEMA_VERSION
+    end
+
+    # Counts derived from the diagnostics.
+    def summary
+      SUMMARY_KEYS.transform_values { |severity| count(severity) }
+    end
+
+    # The wire summary is redundant; reject one that disagrees.
+    # @api private
+    def check_summary(wire)
+      Validation.object(wire, "summary")
+      summary.each do |key, expected|
+        actual = Validation.integer(wire[key], ["summary", key], min: 0)
+        next if actual == expected
+
+        Validation.fail_at(
+          "is #{actual} but the diagnostics contain #{expected}",
+          ["summary", key],
+        )
+      end
+    end
+
+    private
+
+    def count(severity)
+      diagnostics.count { |d| d.severity == severity }
+    end
+
+    def check_type(value, type, name)
+      return value if value.is_a?(type)
+
+      Validation.fail_at("must be a #{type}", name)
+    end
+
+    def check_diagnostics(list)
+      Validation.array(list, "diagnostics").each_with_index.map do |item, i|
+        check_type(item, Diagnostic, ["diagnostics", i])
+      end.freeze
+    end
+
+    def check_valid(value)
+      Validation.boolean(value, "valid")
+      return value unless value && diagnostics.any?(&:error?)
+
+      Validation.fail_at("cannot be true when the report has errors", "valid")
+    end
+
+    def standard_members
+      {
+        "schema_version" => schema_version, "producer" => producer.to_h,
+        "profile" => profile.to_h, "timestamp" => format_timestamp,
+        "valid" => valid, "summary" => summary,
+        "diagnostics" => diagnostics.map(&:to_h)
+      }
+    end
+
+    # UTC, with sub-second digits only when there are some.
+    def format_timestamp
+      return nil unless timestamp
+
+      digits = format("%09d", timestamp.nsec).sub(/0+\z/, "")
+      fraction = digits.empty? ? "" : ".#{digits}"
+      "#{timestamp.strftime('%Y-%m-%dT%H:%M:%S')}#{fraction}Z"
+    end
+  end
+end

data/lib/lens_core/schema.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LensCore
+  # The normative JSON Schema shipped with the gem.
+  module Schema
+    PATH = File.expand_path("../../schemas/lens-diagnostics-v1.json", __dir__)
+
+    module_function
+
+    # Schema version, as written in a report's `schema_version` member.
+    def version
+      SCHEMA_VERSION
+    end
+
+    # The schema as a Hash, freshly parsed on every call.
+    def document
+      ::JSON.parse(File.read(PATH, encoding: Encoding::UTF_8))
+    end
+  end
+end