trevl 0.1.0

data/lib/trevl/schema/component.json

@@ -0,0 +1,337 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trevl.trendence.com/schema/component.json",
+  "title": "TREVL Component",
+  "description": "Schema for a single TREVL visualization component",
+
+  "type": "object",
+  "required": ["id", "type"],
+
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique component identifier"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["chart", "score", "table", "text", "filter"],
+      "description": "Component type"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable component name"
+    },
+    "api": {
+      "type": "string",
+      "description": "Registered data source name"
+    },
+    "api-parameters": {
+      "$ref": "#/$defs/apiParameters"
+    },
+    "template": {
+      "type": "string",
+      "description": "Name of a registered template to inherit from"
+    },
+    "computed": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/computedField" },
+      "description": "Per-row JavaScript transformations"
+    },
+    "postprocess": {
+      "type": "string",
+      "description": "JavaScript code to transform the full dataset. Must reassign $result to an Array."
+    },
+    "queries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/query" },
+      "description": "Query definitions (for Cube/X-Middle data sources)"
+    },
+    "highchartsData": {
+      "$ref": "#/$defs/highchartsData"
+    },
+    "display": {
+      "$ref": "#/$defs/display"
+    },
+    "tableData": {
+      "$ref": "#/$defs/tableData"
+    },
+    "filters": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/filterDefinition" },
+      "description": "Filter definitions (for filter components)"
+    },
+    "text": {
+      "type": "string",
+      "description": "HTML content (for text components)"
+    },
+    "subheader": {
+      "type": "string"
+    },
+    "body": {
+      "type": "string"
+    }
+  },
+
+  "allOf": [
+    {
+      "if": { "properties": { "type": { "const": "chart" } } },
+      "then": {
+        "required": ["api", "highchartsData"],
+        "properties": {
+          "highchartsData": {
+            "required": ["series"]
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "score" } } },
+      "then": {
+        "required": ["api", "display"]
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "table" } } },
+      "then": {
+        "required": ["api", "tableData"]
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "filter" } } },
+      "then": {
+        "required": ["api", "filters"]
+      }
+    }
+  ],
+
+  "$defs": {
+    "computedField": {
+      "type": "object",
+      "required": ["name", "code"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Field name added to each row"
+        },
+        "code": {
+          "type": "string",
+          "description": "JavaScript expression. Return value is assigned to the field."
+        },
+        "arguments": {
+          "type": "object",
+          "additionalProperties": {
+            "type": ["string", "number", "boolean"]
+          },
+          "description": "Named arguments. Use $endpoint.data.field references as values."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "query": {
+      "type": "object",
+      "properties": {
+        "context": {
+          "type": "string",
+          "description": "Query context (e.g. target_group, compare_group)"
+        },
+        "dimensions": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "measures": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "filters": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/queryFilter" }
+        },
+        "computed": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/computedField" }
+        }
+      }
+    },
+
+    "queryFilter": {
+      "type": "object",
+      "required": ["member", "operator"],
+      "properties": {
+        "member": {
+          "type": "string",
+          "description": "Cube dimension/measure to filter on"
+        },
+        "operator": {
+          "type": "string",
+          "enum": ["equals", "notEquals", "gt", "gte", "lt", "lte", "afterDate", "beforeDate", "set", "notSet", "contains", "notContains"],
+          "description": "Filter operator"
+        },
+        "values": {
+          "type": "array",
+          "items": { "type": ["string", "number"] },
+          "description": "Static filter values"
+        },
+        "parameter": {
+          "type": "string",
+          "description": "Runtime parameter reference ($param_name)"
+        }
+      }
+    },
+
+    "apiParameters": {
+      "type": "object",
+      "description": "Parameters passed to the data source",
+      "additionalProperties": true
+    },
+
+    "highchartsData": {
+      "type": "object",
+      "description": "Highcharts configuration object",
+      "properties": {
+        "chart": {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["bar", "column", "line", "area", "pie", "scatter", "spline", "areaspline", "heatmap", "bubble", "waterfall", "funnel", "gauge", "solidgauge", "bullet"],
+              "description": "Highcharts chart type"
+            },
+            "height": { "type": ["number", "string"] },
+            "backgroundColor": { "type": "string" }
+          },
+          "additionalProperties": true
+        },
+        "title": {
+          "type": "object",
+          "properties": {
+            "text": { "type": "string" }
+          },
+          "additionalProperties": true
+        },
+        "series": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/seriesDefinition" },
+          "description": "Data series definitions"
+        },
+        "xAxis": { "additionalProperties": true },
+        "yAxis": { "additionalProperties": true },
+        "colors": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "plotOptions": { "type": "object", "additionalProperties": true },
+        "legend": { "type": "object", "additionalProperties": true },
+        "tooltip": { "type": "object", "additionalProperties": true },
+        "credits": { "type": "object", "additionalProperties": true }
+      },
+      "additionalProperties": true
+    },
+
+    "seriesDefinition": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Series name. Can be a $reference."
+        },
+        "type": {
+          "type": "string",
+          "description": "Override chart type for this series"
+        },
+        "color": {
+          "type": "string"
+        },
+        "data": {
+          "type": "object",
+          "description": "Data point mapping. Keys (x, y, color, etc.) map to $references.",
+          "additionalProperties": {
+            "type": ["string", "number", "object"]
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "display": {
+      "type": "object",
+      "description": "Display configuration (primarily for score components)",
+      "properties": {
+        "value": {
+          "type": ["string", "number"],
+          "description": "Value to display. Can be a $reference."
+        },
+        "unit": {
+          "type": "string",
+          "description": "Unit suffix (e.g. '%', ' EUR')"
+        },
+        "header": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string" },
+            "icon": { "type": "string" }
+          },
+          "additionalProperties": true
+        },
+        "format": {
+          "type": "object",
+          "properties": {
+            "minimumFractionDigits": { "type": "integer" },
+            "maximumFractionDigits": { "type": "integer" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "tableData": {
+      "type": "object",
+      "required": ["columns"],
+      "properties": {
+        "headers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Column header labels"
+        },
+        "columns": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["identifier", "value"],
+            "properties": {
+              "identifier": { "type": "string" },
+              "value": { "type": "string", "description": "Value or $reference" }
+            },
+            "additionalProperties": true
+          }
+        },
+        "index": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+
+    "filterDefinition": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "type": {
+          "type": "string",
+          "enum": ["select", "multiselect", "range", "date"],
+          "description": "Filter input type"
+        },
+        "label": { "type": "string" },
+        "options": {
+          "type": "object",
+          "description": "Option mapping with $references for value/label",
+          "additionalProperties": { "type": "string" }
+        },
+        "queries": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/query" }
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

data/lib/trevl/schema/document.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trevl.trendence.com/schema/document.json",
+  "title": "TREVL Document",
+  "description": "Schema for a TREVL YAML document — either a hash with 'components' key or a bare array of components",
+
+  "oneOf": [
+    {
+      "type": "object",
+      "required": ["components"],
+      "properties": {
+        "components": {
+          "type": "array",
+          "items": { "$ref": "component.json" },
+          "minItems": 1,
+          "description": "Array of TREVL components"
+        },
+        "parameters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id"],
+            "properties": {
+              "id": { "type": "string" },
+              "type": { "type": "string", "enum": ["single", "multi"] },
+              "sources": { "type": "array" }
+            }
+          },
+          "description": "Runtime parameter definitions"
+        }
+      },
+      "additionalProperties": true
+    },
+    {
+      "type": "array",
+      "items": { "$ref": "component.json" },
+      "minItems": 1,
+      "description": "Bare array of components (shorthand)"
+    }
+  ]
+}

data/lib/trevl/template_store.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Trevl
+  class TemplateStore
+    def initialize
+      @templates = {}
+    end
+
+    def register(name, template_hash)
+      @templates[name.to_s.downcase] = template_hash
+    end
+
+    def find(name)
+      @templates[name.to_s.downcase]
+    end
+
+    def load_yaml(yaml_string)
+      data = YAML.safe_load(yaml_string, permitted_classes: [Hash], aliases: true)
+      return unless data.is_a?(Hash)
+
+      data.each do |name, template_hash|
+        register(name, template_hash) if template_hash.is_a?(Hash)
+      end
+    end
+
+    def load_file(path)
+      load_yaml(File.read(path))
+    end
+
+    def names
+      @templates.keys
+    end
+
+    def clear
+      @templates.clear
+    end
+  end
+end

data/lib/trevl/validator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+
+module Trevl
+  class Validator
+    SCHEMA_DIR = File.expand_path("schema", __dir__)
+    COMPONENT_SCHEMA_PATH = File.join(SCHEMA_DIR, "component.json")
+    DOCUMENT_SCHEMA_PATH = File.join(SCHEMA_DIR, "document.json")
+
+    Result = Struct.new(:valid?, :errors, keyword_init: true) do
+      def to_s
+        return "Valid" if valid?
+        errors.map { |e| "- #{e}" }.join("\n")
+      end
+    end
+
+    def self.validate(yaml_string)
+      new.validate(yaml_string)
+    end
+
+    def self.validate_component(component_hash)
+      new.validate_component(component_hash)
+    end
+
+    def validate(yaml_string)
+      parsed = YAML.safe_load(yaml_string, permitted_classes: [Hash, Symbol], aliases: true)
+      validate_document(parsed)
+    rescue Psych::SyntaxError => e
+      Result.new(valid?: false, errors: ["YAML syntax error: #{e.message}"])
+    end
+
+    def validate_component(component_hash)
+      schema_errors = component_schemer.validate(component_hash).map { |e| format_error(e) }
+      Result.new(valid?: schema_errors.empty?, errors: schema_errors)
+    end
+
+    def validate_document(parsed)
+      if parsed.is_a?(Array)
+        validate_component_array(parsed)
+      elsif parsed.is_a?(Hash) && parsed["components"].is_a?(Array)
+        validate_component_array(parsed["components"])
+      elsif parsed.is_a?(Hash)
+        Result.new(valid?: false, errors: ["Document must have a 'components' array"])
+      else
+        Result.new(valid?: false, errors: ["Document must be a Hash or Array, got #{parsed.class}"])
+      end
+    end
+
+    private
+
+    def validate_component_array(components)
+      all_errors = []
+      components.each_with_index do |comp, idx|
+        schema_errors = component_schemer.validate(comp).map { |e| format_error(e, component_index: idx, component_id: comp["id"]) }
+        all_errors.concat(schema_errors)
+      end
+      Result.new(valid?: all_errors.empty?, errors: all_errors)
+    end
+
+    def component_schemer
+      @component_schemer ||= JSONSchemer.schema(
+        JSON.parse(File.read(COMPONENT_SCHEMA_PATH))
+      )
+    end
+
+    def format_error(error, component_index: nil, component_id: nil)
+      path = error["data_pointer"]
+      msg = error["type"]
+      details = error["details"] || {}
+
+      prefix = if component_id
+        "[#{component_id}]"
+      elsif component_index
+        "[component ##{component_index}]"
+      else
+        ""
+      end
+
+      case msg
+      when "required"
+        missing = details["missing_keys"]&.join(", ") || "unknown"
+        "#{prefix} Missing required field(s): #{missing} (at #{path})"
+      when "enum"
+        "#{prefix} Invalid value at #{path}: must be one of #{error["schema"]["enum"].join(", ")}"
+      when "type"
+        "#{prefix} Wrong type at #{path}: expected #{error["schema"]["type"]}"
+      when "object"
+        "#{prefix} Schema error at #{path}: #{error["error"]}"
+      else
+        detail = error["error"] || error.fetch("message", msg)
+        "#{prefix} #{detail} (at #{path})"
+      end
+    end
+  end
+end

data/lib/trevl/version.rb

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

data/lib/trevl.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+require "logger"
+require "securerandom"
+
+require_relative "trevl/version"
+require_relative "trevl/errors"
+require_relative "trevl/configuration"
+require_relative "trevl/highcharts_asset"
+require_relative "trevl/core_ext/hash"
+require_relative "trevl/template_store"
+require_relative "trevl/data_source"
+require_relative "trevl/data_source/base"
+require_relative "trevl/data_source/static"
+require_relative "trevl/data_source/api"
+require_relative "trevl/data_source/cube"
+require_relative "trevl/auth/bearer_token"
+require_relative "trevl/processor"
+require_relative "trevl/renderer"
+require_relative "trevl/validator"
+require_relative "trevl/html_renderer"
+
+module Trevl
+  GEM_ROOT = File.expand_path("..", __dir__)
+
+  class << self
+    # --- Configuration ---
+
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def logger = configuration.logger
+    def template_store = configuration.template_store
+
+    # --- Core API ---
+
+    def parse(yaml_string)
+      Processor.new(yaml_string)
+    end
+
+    def validate(yaml_string)
+      Validator.validate(yaml_string)
+    end
+
+    # data: inline rows for this render call ({endpoint => rows}), wrapped in
+    # a Static source internally; answers any api name and components without
+    # one. data_sources: per-render sources ({name => instance}). Both take
+    # precedence over the global DataSource registry.
+    def render(yaml_string, params: {}, data: nil, data_sources: {})
+      components = parse(yaml_string).components || []
+      components.filter_map { |c| Renderer.new(c, params, data: data, data_sources: data_sources).render }
+    end
+
+    def render_to_html(yaml_string, params: {}, data: nil, data_sources: {}, width: 800, height: 400)
+      HtmlRenderer.new(width: width, height: height)
+        .render(yaml_string, params: params, data: data, data_sources: data_sources)
+    end
+
+    # --- AI tooling ---
+
+    def schema_reference
+      @schema_reference ||= File.read(File.join(GEM_ROOT, "llms.txt"))
+    end
+
+    def examples
+      @examples ||= load_examples
+    end
+
+    # --- Lifecycle ---
+
+    def reset!
+      @configuration = Configuration.new
+      @schema_reference = nil
+      @examples = nil
+    end
+
+    private
+
+    def load_examples
+      dir = File.join(GEM_ROOT, "examples")
+      return [] unless File.directory?(dir)
+
+      Dir.glob(File.join(dir, "*.yml")).sort.map do |path|
+        name = File.basename(path, ".yml")
+        content = File.read(path)
+        comment_lines = content.lines.take_while { |l| l.start_with?("#") }
+        description = comment_lines.map { |l| l.sub(/^#\s?/, "").chomp }.join(" ").strip
+        {name: name, description: description, yaml: content.sub(/\A(#[^\n]*\n)+/, "")}
+      end
+    end
+  end
+end