facera 0.1.0

data/lib/facera/core.rb

@@ -0,0 +1,65 @@
+module Facera
+  class Core
+    attr_reader :name, :entities, :capabilities, :invariants
+
+    def initialize(name)
+      @name = name.to_sym
+      @entities = {}
+      @capabilities = {}
+      @invariants = {}
+      @current_entity = nil
+    end
+
+    def entity(name, &block)
+      entity_obj = Entity.new(name)
+      @entities[name.to_sym] = entity_obj
+      @current_entity = entity_obj
+
+      entity_obj.instance_eval(&block) if block_given?
+
+      @current_entity = nil
+      entity_obj
+    end
+
+    def capability(name, type:, &block)
+      capability_obj = Capability.new(name, type: type)
+      @capabilities[name.to_sym] = capability_obj
+
+      capability_obj.instance_eval(&block) if block_given?
+
+      capability_obj
+    end
+
+    def invariant(name, description: nil, &block)
+      invariant_obj = Invariant.new(name, description: description, &block)
+      @invariants[name.to_sym] = invariant_obj
+    end
+
+    def find_entity(name)
+      @entities[name.to_sym] or raise Error, "Entity '#{name}' not found in core '#{@name}'"
+    end
+
+    def find_capability(name)
+      @capabilities[name.to_sym] or raise Error, "Capability '#{name}' not found in core '#{@name}'"
+    end
+
+    def find_invariant(name)
+      @invariants[name.to_sym]
+    end
+
+    def validate_invariants(context)
+      errors = []
+
+      @invariants.each do |name, invariant|
+        begin
+          result = invariant.check(context)
+          errors << "Invariant '#{name}' failed" unless result
+        rescue Error => e
+          errors << e.message
+        end
+      end
+
+      errors
+    end
+  end
+end

data/lib/facera/dsl.rb

@@ -0,0 +1,41 @@
+module Facera
+  module DSL
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def define_core(name, &block)
+        core = Core.new(name)
+        core.instance_eval(&block) if block_given?
+        Registry.register_core(name, core)
+        core
+      end
+
+      def define_facet(name, core:, &block)
+        facet = Facet.new(name, core: core)
+        facet.instance_eval(&block) if block_given?
+        Registry.register_facet(name, facet)
+        facet
+      end
+
+      def cores
+        Registry.cores
+      end
+
+      def facets
+        Registry.facets
+      end
+
+      def find_core(name)
+        Registry.find_core(name)
+      end
+
+      def find_facet(name)
+        Registry.find_facet(name)
+      end
+    end
+  end
+
+  extend DSL::ClassMethods
+end

data/lib/facera/entity.rb

@@ -0,0 +1,50 @@
+module Facera
+  class Entity
+    attr_reader :name, :attributes
+
+    def initialize(name)
+      @name = name.to_sym
+      @attributes = {}
+    end
+
+    def attribute(name, type, **options)
+      attr = Attribute.new(name, type, **options)
+      @attributes[attr.name] = attr
+    end
+
+    def find_attribute(name)
+      @attributes[name.to_sym]
+    end
+
+    def required_attributes
+      @attributes.values.select(&:required?)
+    end
+
+    def immutable_attributes
+      @attributes.values.select(&:immutable?)
+    end
+
+    def validate_data(data)
+      errors = []
+
+      # Check required attributes
+      required_attributes.each do |attr|
+        if data[attr.name].nil? && data[attr.name.to_s].nil?
+          errors << "#{attr.name} is required"
+        end
+      end
+
+      # Validate each provided attribute
+      data.each do |key, value|
+        attr = find_attribute(key)
+        next unless attr
+
+        unless attr.validate_value(value)
+          errors << "#{key} has invalid value for type #{attr.type}"
+        end
+      end
+
+      errors
+    end
+  end
+end

data/lib/facera/error_formatter.rb

@@ -0,0 +1,100 @@
+module Facera
+  class ErrorFormatter
+    VERBOSITY_LEVELS = [:minimal, :detailed, :structured].freeze
+
+    def initialize(verbosity = :minimal)
+      @verbosity = verbosity.to_sym
+      validate_verbosity!
+    end
+
+    def format(error)
+      case @verbosity
+      when :minimal
+        format_minimal(error)
+      when :detailed
+        format_detailed(error)
+      when :structured
+        format_structured(error)
+      end
+    end
+
+    private
+
+    def validate_verbosity!
+      unless VERBOSITY_LEVELS.include?(@verbosity)
+        raise Error, "Invalid verbosity level '#{@verbosity}'. Valid levels: #{VERBOSITY_LEVELS.join(', ')}"
+      end
+    end
+
+    def format_minimal(error)
+      {
+        error: error.class.name.split('::').last.gsub('Error', '').downcase,
+        message: error.message
+      }
+    end
+
+    def format_detailed(error)
+      result = {
+        error: error.class.name,
+        message: error.message,
+        timestamp: Time.now.iso8601
+      }
+
+      case error
+      when ValidationError
+        result[:validation_errors] = error.errors
+      when InvariantError
+        result[:invariant_errors] = error.invariant_errors
+      end
+
+      result[:backtrace] = error.backtrace.first(10) if error.backtrace
+
+      result
+    end
+
+    def format_structured(error)
+      result = {
+        type: error.class.name.split('::').last,
+        message: error.message,
+        timestamp: Time.now.iso8601,
+        severity: severity_for(error)
+      }
+
+      case error
+      when ValidationError
+        result[:details] = {
+          validation_errors: error.errors.map { |e| { field: extract_field(e), message: e } }
+        }
+      when InvariantError
+        result[:details] = {
+          invariant_violations: error.invariant_errors
+        }
+      when NotFoundError
+        result[:details] = { resource: extract_resource(error.message) }
+      end
+
+      result
+    end
+
+    def severity_for(error)
+      case error
+      when ValidationError, PreconditionError
+        'warning'
+      when UnauthorizedError
+        'error'
+      when NotFoundError
+        'info'
+      else
+        'error'
+      end
+    end
+
+    def extract_field(error_message)
+      error_message.split(' ').first
+    end
+
+    def extract_resource(message)
+      message.split(' ').first
+    end
+  end
+end

data/lib/facera/errors.rb

@@ -0,0 +1,40 @@
+module Facera
+  class FaceraError < StandardError; end
+
+  class ValidationError < FaceraError
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors.is_a?(Array) ? errors : [errors]
+      super(@errors.join(", "))
+    end
+  end
+
+  class UnauthorizedError < FaceraError
+    def initialize(message = "Unauthorized access")
+      super(message)
+    end
+  end
+
+  class NotFoundError < FaceraError
+    def initialize(resource, id = nil)
+      message = id ? "#{resource} with id '#{id}' not found" : "#{resource} not found"
+      super(message)
+    end
+  end
+
+  class PreconditionError < FaceraError
+    def initialize(message = "Precondition failed")
+      super(message)
+    end
+  end
+
+  class InvariantError < FaceraError
+    attr_reader :invariant_errors
+
+    def initialize(invariant_errors)
+      @invariant_errors = invariant_errors
+      super("Invariant violations: #{invariant_errors.join(', ')}")
+    end
+  end
+end

data/lib/facera/executor.rb

@@ -0,0 +1,265 @@
+module Facera
+  class Executor
+    attr_reader :facet, :capability, :params, :context
+
+    def self.run(facet:, capability:, params: {}, context: {})
+      new(facet: facet, capability: capability, params: params, context: context).execute
+    end
+
+    def initialize(facet:, capability:, params: {}, context: {})
+      @facet = facet.is_a?(Symbol) ? Registry.find_facet(facet) : facet
+      @capability = capability.is_a?(Symbol) ? @facet.core.find_capability(capability) : capability
+      @params = normalize_params(params)
+      @context = context
+    end
+
+    def execute
+      # Check if capability is allowed in this facet
+      unless facet.capability_allowed?(capability.name)
+        raise UnauthorizedError, "Capability '#{capability.name}' is not allowed in facet '#{facet.name}'"
+      end
+
+      # Validate parameters
+      validate_params!
+
+      # Apply facet scoping if present
+      apply_scoping!
+
+      # Check preconditions
+      check_preconditions!
+
+      # Execute the capability logic
+      result = execute_capability
+
+      # Validate invariants if result is an entity (not a collection or metadata structure)
+      validate_invariants!(result) if should_validate_result?(result)
+
+      result
+    end
+
+    private
+
+    def normalize_params(params)
+      # Convert string keys to symbols
+      params.transform_keys(&:to_sym)
+    end
+
+    def validate_params!
+      errors = capability.validate_params(params)
+
+      raise ValidationError.new(errors) if errors.any?
+    end
+
+    def apply_scoping!
+      return unless facet.has_scope_for?(capability.name)
+
+      scope_block = facet.capability_scope(capability.name)
+      scope_params = context_eval(&scope_block)
+
+      # Merge scope params into params
+      @params.merge!(scope_params) if scope_params.is_a?(Hash)
+    end
+
+    def check_preconditions!
+      return if capability.preconditions.empty?
+
+      unless capability.check_preconditions(build_context)
+        raise PreconditionError, "Precondition failed for capability '#{capability.name}'"
+      end
+    end
+
+    def execute_capability
+      # Priority 1: Execute block defined inline
+      if capability.has_execute_block?
+        return execute_inline_block
+      end
+
+      # Priority 2: Call adapter if registered
+      adapter = AdapterRegistry.get(facet.core.name)
+      if adapter
+        return execute_adapter(adapter)
+      end
+
+      # Fallback: Mock implementation
+      execute_mock_implementation
+    end
+
+    def execute_inline_block
+      # Execute the block defined in the capability
+      context = build_context
+      result = context.instance_exec(params, &capability.execute_block)
+
+      # Apply field setters if result is a hash
+      if result.is_a?(Hash) && capability.field_setters.any?
+        capability.field_setters.each do |field, value|
+          result[field] = value.is_a?(Proc) ? value.call : value
+        end
+      end
+
+      result
+    end
+
+    def execute_adapter(adapter_class)
+      adapter_instance = adapter_class.new
+
+      # Call the appropriate adapter method
+      case capability.type
+      when :create
+        adapter_instance.send("create_#{capability.entity_name}", params)
+      when :get
+        adapter_instance.send("get_#{capability.entity_name}", params)
+      when :list
+        adapter_instance.send("list_#{capability.entity_name}s", params)
+      when :action
+        # For actions, call the method by capability name
+        adapter_instance.send(capability.name, params)
+      when :update
+        adapter_instance.send("update_#{capability.entity_name}", params)
+      when :delete
+        adapter_instance.send("delete_#{capability.entity_name}", params)
+      end
+    end
+
+    def execute_mock_implementation
+      # Fallback mock implementation (for testing/prototyping)
+      case capability.type
+      when :create
+        create_result
+      when :get
+        get_result
+      when :list
+        list_result
+      when :action
+        action_result
+      when :update
+        update_result
+      when :delete
+        delete_result
+      else
+        {}
+      end
+    end
+
+    def create_result
+      # Mock created entity
+      entity_attrs = params.dup
+      entity_attrs[:id] = generate_id
+      entity_attrs[:created_at] = Time.now
+      entity_attrs
+    end
+
+    def get_result
+      # Mock fetched entity
+      base_data = mock_entity_data
+      base_data[:id] = params[:id]  # Use the requested ID
+      base_data
+    end
+
+    def list_result
+      # Mock collection
+      {
+        data: [mock_entity_data],
+        meta: {
+          total: 1,
+          limit: params[:limit] || 20,
+          offset: params[:offset] || 0
+        }
+      }
+    end
+
+    def action_result
+      # Mock entity after action
+      result = get_result
+
+      # Apply transitions
+      if capability.transitions.any?
+        result[:status] = capability.transitions.first
+      end
+
+      # Apply field setters
+      capability.field_setters.each do |field, value|
+        result[field] = value.is_a?(Proc) ? value.call : value
+      end
+
+      result
+    end
+
+    def update_result
+      get_result.merge(params.except(:id))
+    end
+
+    def delete_result
+      { success: true, id: params[:id] }
+    end
+
+    def should_validate_result?(result)
+      return false unless result.is_a?(Hash)
+      return false if capability.type == :list # List returns collection structure
+      return false if capability.type == :delete # Delete returns success message
+      return false unless capability.entity_name
+
+      true
+    end
+
+    def validate_invariants!(result)
+      return unless capability.entity_name
+
+      entity = facet.core.find_entity(capability.entity_name)
+      errors = entity.validate_data(result)
+
+      # Also check core invariants
+      invariant_errors = facet.core.validate_invariants(build_context(result))
+      errors.concat(invariant_errors)
+
+      raise InvariantError.new(invariant_errors) if invariant_errors.any?
+      raise ValidationError.new(errors) if errors.any?
+    end
+
+    def build_context(data = {})
+      # Create a context object with data that can be used in blocks
+      Context.new(data.merge(params).merge(context))
+    end
+
+    def context_eval(&block)
+      build_context.instance_eval(&block)
+    end
+
+    def generate_id
+      require 'securerandom'
+      SecureRandom.uuid
+    end
+
+    def mock_entity_data
+      # Generate mock data based on entity definition
+      return {} unless capability.entity_name
+
+      entity = facet.core.find_entity(capability.entity_name)
+      data = {
+        id: generate_id,
+        created_at: Time.now
+      }
+
+      entity.attributes.each do |name, attr|
+        next if [:id, :created_at, :updated_at].include?(name)
+        data[name] = mock_value_for_type(attr.type)
+      end
+
+      data
+    end
+
+    def mock_value_for_type(type)
+      case type
+      when :string then "sample"
+      when :integer then 42
+      when :money then 100.0
+      when :uuid then generate_id
+      when :enum then :pending
+      when :boolean then true
+      when :hash then {}
+      when :array then []
+      when :timestamp, :datetime then Time.now
+      else nil
+      end
+    end
+  end
+end

data/lib/facera/facet.rb

@@ -0,0 +1,103 @@
+module Facera
+  class Facet
+    attr_reader :name, :core_name, :description, :field_visibilities, :capability_access,
+                :error_verbosity, :format, :rate_limit, :audit_enabled
+
+    def initialize(name, core:)
+      @name = name.to_sym
+      @core_name = core.to_sym
+      @description = nil
+      @field_visibilities = {}
+      @capability_access = CapabilityAccess.new
+      @error_verbosity = :minimal
+      @format = :json
+      @rate_limit = nil
+      @audit_enabled = false
+      @audit_options = {}
+    end
+
+    def core
+      @core ||= Registry.find_core(@core_name)
+    end
+
+    def description(text = nil)
+      return @description if text.nil?
+      @description = text
+    end
+
+    def expose(entity_name, &block)
+      visibility = FieldVisibility.new(entity_name)
+      @field_visibilities[entity_name.to_sym] = visibility
+      visibility.instance_eval(&block) if block_given?
+      visibility
+    end
+
+    def allow_capabilities(*capability_names)
+      @capability_access.allow(*capability_names)
+    end
+
+    def deny_capabilities(*capability_names)
+      @capability_access.deny(*capability_names)
+    end
+
+    def scope(capability_name, &block)
+      @capability_access.scope(capability_name, &block)
+    end
+
+    def error_verbosity(level = nil)
+      return @error_verbosity if level.nil?
+      @error_verbosity = level.to_sym
+    end
+
+    def format(format_type = nil)
+      return @format if format_type.nil?
+      @format = format_type.to_sym
+    end
+
+    def rate_limit(requests: nil, per: nil)
+      return @rate_limit if requests.nil?
+      @rate_limit = { requests: requests, per: per.to_sym }
+    end
+
+    def audit_all_operations(**options)
+      @audit_enabled = true
+      @audit_options = options
+    end
+
+    def field_visibility_for(entity_name)
+      @field_visibilities[entity_name.to_sym]
+    end
+
+    def visible_fields_for(entity_name)
+      visibility = field_visibility_for(entity_name)
+      return [] unless visibility
+
+      entity = core.find_entity(entity_name)
+      visibility.all_visible_fields(entity)
+    end
+
+    def capability_allowed?(capability_name)
+      @capability_access.allowed?(capability_name)
+    end
+
+    def capability_scope(capability_name)
+      @capability_access.scope_for(capability_name)
+    end
+
+    def has_scope_for?(capability_name)
+      @capability_access.has_scope?(capability_name)
+    end
+
+    def allowed_capabilities
+      @capability_access.allowed_capability_names(core)
+    end
+
+    def error_formatter
+      @error_formatter ||= ErrorFormatter.new(@error_verbosity)
+    end
+
+    def format_error(error)
+      error_formatter.format(error)
+    end
+  end
+end