schemagraphy 0.1.0

data/lib/schemagraphy/schema_utils.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SchemaGraphy
+  # A utility module for introspecting schema definitions.
+  # Provides methods for retrieving metadata, default values, and type information
+  # from a schema hash using a dot-separated path syntax.
+  module SchemaUtils
+    module_function
+
+    # Retrieve a nested property definition from a schema using a dot-separated path.
+    #
+    # @example Schema Structure
+    #   schema = {
+    #     "$schema": {
+    #       "properties": {
+    #         "property1": {
+    #           "properties": {
+    #             "subproperty1": {
+    #               "default": "value1",
+    #               "type": "String"
+    #             }
+    #           }
+    #         }
+    #       }
+    #     }
+    #   }
+    #   crawl_properties(schema, "property1.subproperty1")
+    #   # => { "default" => "value1", "type" => "String" }
+    #
+    # @param schema [Hash] The schema hash to crawl.
+    # @param path [String] The dot-separated path to the property.
+    # @return [Hash, nil] The property definition hash, or `nil` if not found.
+    def crawl_properties schema, path
+      path_components = path.split('.')
+      current = schema['$schema'] || schema
+
+      path_components.each do |component|
+        return nil unless current.is_a?(Hash)
+        return nil unless current['properties']&.key?(component)
+
+        current = current['properties'][component]
+      end
+
+      current
+    end
+
+    # Get the default value for a property from the schema.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String] The dot-separated path to the property.
+    # @return [Object, nil] The default value, or `nil` if not defined.
+    def default_for schema, path
+      property = crawl_properties(schema, path)
+      return nil unless property.is_a?(Hash)
+
+      property['default'] || property['dflt']
+    end
+
+    # Get the type for a property from the schema.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String] The dot-separated path to the property.
+    # @return [String, nil] The property type, or `nil` if not defined.
+    def type_for schema, path
+      property = crawl_properties(schema, path)
+      return nil unless property.is_a?(Hash)
+
+      property['type']
+    end
+
+    # Get the templating configuration for a property from the schema.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String] The dot-separated path to the property.
+    # @return [Hash] The templating configuration hash.
+    def templating_config_for schema, path
+      property = crawl_properties(schema, path)
+      return {} unless property.is_a?(Hash)
+
+      return property['templating'] if property['templating']
+
+      if property['type'].to_s.downcase == 'liquid'
+        { 'default' => 'liquid', 'delay' => true }
+      elsif property['type'].to_s.downcase == 'erb'
+        { 'default' => 'erb', 'delay' => true }
+      else
+        {}
+      end
+    end
+
+    # Check if a property is a templated field.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String] The dot-separated path to the property.
+    # @return [Boolean] `true` if the field has templating configured, `false` otherwise.
+    def templated_field? schema, path
+      property = crawl_properties(schema, path)
+      return false unless property.is_a?(Hash)
+
+      property.key?('templating') && property['templating'].is_a?(Hash)
+    end
+
+    # Crawl the schema to find the metadata for a given path.
+    #
+    # @param schema [Hash] The schema hash.
+    # @param path [String, nil] The dot-separated path.
+    # @return [Hash] The metadata hash.
+    def self.crawl_meta schema, path = nil
+      parts = path ? path.split('.') : []
+      node = schema['$schema'] || schema
+      meta = {}
+
+      parts.each do |part|
+        node = node['properties'][part] if node['properties']&.key?(part)
+        break unless node.is_a?(Hash)
+
+        # Only update meta if this level has it
+        meta = node if node['templating']
+      end
+
+      meta['$meta'] || meta['sgyml'] || meta['templating'] || {}
+    end
+  end
+end

data/lib/schemagraphy/sgyml.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module SchemaGraphy
+  # Provides SGYML (SchemaGraphy YAML-based Modeling Language) type classification.
+  # This is the canonical source for SGYML data types used across DocOps Lab tooling.
+  #
+  # Type strings are in "Kind:Class" form, e.g. "Scalar:String", "Compound:ArrayList",
+  # "Null:nil". Downstream gems (AsciiSourcerer, ReleaseHx, etc.) that render SGYML
+  # templates should obtain this classification via SchemaGraphy rather than
+  # re-implementing it.
+  module SGYML
+    module_function
+
+    # Classifies a Ruby value by its SGYML type.
+    # @param input [Object] Any Ruby value.
+    # @return [String] A "Kind:Class" type string.
+    def classify input
+      if input.nil?
+        'Null:nil'
+      elsif input.is_a?(Array)
+        classify_array(input)
+      elsif input.is_a?(Hash)
+        classify_hash(input)
+      elsif input.is_a?(String)
+        'Scalar:String'
+      elsif input.is_a?(Integer)
+        'Scalar:Number'
+      elsif input.is_a?(Float)
+        'Scalar:Float'
+      elsif input.is_a?(Time)
+        'Scalar:DateTime'
+      elsif input.is_a?(TrueClass) || input.is_a?(FalseClass)
+        'Scalar:Boolean'
+      else
+        'unknown:unknown'
+      end
+    end
+
+    def classify_array input
+      if input.all? do |i|
+        i.is_a?(Integer) || i.is_a?(Float) || i.is_a?(String) || i.is_a?(TrueClass) || i.is_a?(FalseClass)
+      end
+        'Compound:ArrayList'
+      elsif input.all? { |i| i.is_a?(Hash) && i.keys.length >= 2 }
+        'Compound:ArrayTable'
+      else
+        'Compound:Array'
+      end
+    end
+
+    def classify_hash input
+      if input.values.all? { |v| v.is_a?(Hash) && v.keys.length >= 2 }
+        'Compound:MapTable'
+      else
+        'Compound:Map'
+      end
+    end
+  end
+end

data/lib/schemagraphy/tag_utils.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SchemaGraphy
+  # A utility module for working with the custom tag data structure.
+  # The structure is a hash with 'value' and '__tag__' keys.
+  module TagUtils
+    # Extracts the original value from a tagged data structure.
+    #
+    # @param value [Object] The tagged value (a Hash) or any other value.
+    # @return [Object] The original value, or the value itself if not tagged.
+    def self.detag value
+      value.is_a?(Hash) && value.key?('value') ? value['value'] : value
+    end
+
+    # Retrieves the tag from a tagged data structure.
+    #
+    # @param value [Object] The tagged value (a Hash) or any other value.
+    # @return [String, nil] The tag string, or `nil` if not tagged.
+    def self.tag_of value
+      value.is_a?(Hash) ? value['__tag__'] : nil
+    end
+
+    # Checks if a value has a specific tag.
+    #
+    # @param value [Object] The tagged value to check.
+    # @param tag [String, Symbol] The tag to check for.
+    # @return [Boolean] `true` if the value has the specified tag, `false` otherwise.
+    def self.tag? value, tag
+      tag_of(value)&.to_s == tag.to_s
+    end
+  end
+end

data/lib/schemagraphy/templating.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'tilt'
+require 'sourcerer/templating'
+
+# frozen_string_literal: true
+
+module SchemaGraphy
+  # A module for handling templated fields within a data structure based on a schema or definition.
+  # It provides methods for pre-compiling and rendering fields using various template engines.
+  module Templating
+    extend Sourcerer::Templating
+
+    # Renders a field if it is a template.
+    #
+    # @param field [Object] The field to render.
+    # @param context [Hash] The context to use for rendering.
+    # @return [Object] The rendered field, or the original field if it's not a template.
+    def self.resolve_field field, context = {}
+      render_field_if_template(field, context)
+    end
+
+    # Recursively pre-compiles templated fields in a data structure based on a schema.
+    #
+    # @param data [Hash] The data to process.
+    # @param schema [Hash] The schema defining which fields are templated.
+    # @param base_path [String] The base path for the current data level.
+    # @param scope [Hash] The scope to use for compilation.
+    def self.precompile_from_schema! data, schema, base_path = '', scope: {}
+      return unless data.is_a?(Hash)
+
+      data.each do |key, value|
+        path = [base_path, key].reject(&:empty?).join('.')
+
+        precompile_from_schema!(value, schema, path, scope: scope) if value.is_a?(Hash)
+
+        next unless SchemaGraphy::SchemaUtils.templated_field?(schema, path)
+
+        compile_templated_fields!(
+          data: data,
+          schema: schema,
+          fields: [{ key: key, path: path }],
+          scope: scope)
+      end
+    end
+
+    # An alias for the `Sourcerer::Templating::TemplatedField` class.
+    TemplatedField = Sourcerer::Templating::TemplatedField
+
+    # Compiles templated fields in the data.
+    #
+    # @param data [Hash] The data containing the fields to compile.
+    # @param schema [Hash] The schema definition.
+    # @param fields [Array<Hash>] An array of fields to compile, each with a `:key` and `:path`.
+    # @param scope [Hash] The scope to use for compilation.
+    def self.compile_templated_fields! data:, schema:, fields:, scope: {}
+      fields.each do |entry|
+        key  = entry[:key]
+        path = entry[:path]
+        val  = data[key]
+
+        next unless val.is_a?(String) || (val.is_a?(Hash) && val['__tag__'] && val['value'])
+
+        raw     = val.is_a?(Hash) ? val['value'] : val
+        tagged  = val.is_a?(Hash)
+        config  = SchemaGraphy::SchemaUtils.templating_config_for(schema, path)
+        engine  = tagged ? val['__tag__'] : (config['default'] || 'liquid')
+
+        compiled = Sourcerer::Templating::Engines.compile(raw, engine)
+
+        data[key] = if config['delay']
+                      Sourcerer::Templating::TemplatedField.new(raw, compiled, engine, tagged, inferred: !tagged)
+                    else
+                      Sourcerer::Templating::Engines.render(compiled, engine, scope)
+                    end
+      end
+    end
+
+    # Recursively renders all pre-compiled templated fields in a data structure.
+    #
+    # @param data [Hash, Array] The data structure to process.
+    # @param context [Hash] The context to use for rendering.
+    def self.render_all_templated_fields! data, context = {}
+      return unless data.is_a?(Hash)
+
+      data.each do |key, value|
+        case value
+        when TemplatedField
+          data[key] = value.render(context)
+        when Hash
+          render_all_templated_fields!(value, context)
+        when Array
+          value.each_with_index do |item, idx|
+            if item.is_a?(TemplatedField)
+              value[idx] = item.render(context)
+            elsif item.is_a?(Hash)
+              render_all_templated_fields!(item, context)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/schemagraphy/version.rb

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

data/lib/schemagraphy.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'schemagraphy/version'
+require_relative 'schemagraphy/loader'
+require_relative 'schemagraphy/tag_utils'
+require_relative 'schemagraphy/schema_utils'
+require_relative 'schemagraphy/templating'
+require_relative 'schemagraphy/regexp_utils'
+require_relative 'schemagraphy/safe_expression'
+require_relative 'schemagraphy/cfgyml/doc_builder'
+require_relative 'schemagraphy/data_query/json_pointer'
+require_relative 'schemagraphy/cfgyml/path_reference'
+require_relative 'schemagraphy/sgyml'
+require_relative 'schemagraphy/liquid/filters'
+
+module SchemaGraphy
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: schemagraphy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- DocOpsLab
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciisourcerer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.20'
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+- !ruby/object:Gem::Dependency
+  name: tilt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: to_regexp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: A YAML-based schema system for validating and transforming configuration
+  data
+email:
+- docopslab@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.adoc
+- lib/schemagraphy.rb
+- lib/schemagraphy/attribute_resolver.rb
+- lib/schemagraphy/cfgyml/definition.rb
+- lib/schemagraphy/cfgyml/doc_builder.rb
+- lib/schemagraphy/cfgyml/path_reference.rb
+- lib/schemagraphy/cfgyml/templates/config-property.adoc.liquid
+- lib/schemagraphy/cfgyml/templates/config-reference.adoc.liquid
+- lib/schemagraphy/cfgyml/templates/sample-config.yaml.liquid
+- lib/schemagraphy/cfgyml/templates/sample-property.yaml.liquid
+- lib/schemagraphy/data_query/json_pointer.rb
+- lib/schemagraphy/liquid/filters.rb
+- lib/schemagraphy/loader.rb
+- lib/schemagraphy/regexp_utils.rb
+- lib/schemagraphy/safe_expression.rb
+- lib/schemagraphy/schema_utils.rb
+- lib/schemagraphy/sgyml.rb
+- lib/schemagraphy/tag_utils.rb
+- lib/schemagraphy/templating.rb
+- lib/schemagraphy/version.rb
+homepage: https://github.com/DocOps/schemagraphy
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Schema-driven configuration and data validation library
+test_files: []