facera 0.1.0

data/lib/facera/grape/entity_generator.rb

@@ -0,0 +1,89 @@
+require 'grape-entity'
+
+module Facera
+  module Grape
+    class EntityGenerator
+      def self.for(entity, facet)
+        entity_name = entity.name
+        visibility = facet.field_visibility_for(entity_name)
+
+        # If no visibility rules, expose all fields
+        unless visibility
+          return create_default_entity(entity)
+        end
+
+        create_facet_entity(entity, visibility, facet)
+      end
+
+      def self.for_collection(entity, facet)
+        entity_class = self.for(entity, facet)
+
+        Class.new(::Grape::Entity) do
+          expose :data, using: entity_class, documentation: { is_array: true }
+          expose :meta do |obj, options|
+            {
+              total: obj[:total] || obj.dig(:meta, :total) || 0,
+              limit: obj[:limit] || obj.dig(:meta, :limit) || 20,
+              offset: obj[:offset] || obj.dig(:meta, :offset) || 0
+            }
+          end
+        end
+      end
+
+      private
+
+      def self.create_default_entity(entity)
+        attrs = entity.attributes
+
+        Class.new(::Grape::Entity) do
+          attrs.each do |name, _attr|
+            expose name
+          end
+        end
+      end
+
+      def self.create_facet_entity(entity, visibility, facet)
+        visible_fields = visibility.visible_field_names(entity)
+        aliases = visibility.field_aliases
+        computed = visibility.computed_fields
+        format_type = facet.format
+
+        Class.new(::Grape::Entity) do
+          # Expose visible base fields
+          visible_fields.each do |field_name|
+            aliased_name = aliases[field_name]
+
+            if aliased_name
+              # Field with alias
+              expose field_name, as: aliased_name
+            else
+              # Regular field
+              expose field_name
+            end
+          end
+
+          # Expose computed fields
+          computed.each do |field_name, block|
+            expose field_name do |obj, options|
+              context = build_computation_context(obj, options)
+              context.instance_eval(&block)
+            end
+          end
+
+          # Apply format-specific transformations
+          if format_type == :structured
+            format_with(:iso_timestamp) { |dt| dt&.iso8601 }
+          end
+
+          private
+
+          def self.build_computation_context(obj, options)
+            # Convert to Context to allow easy field access in blocks
+            data = obj.is_a?(Hash) ? obj : {}
+            Facera::Context.new(data.merge(options[:context] || {}))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facera/grape.rb

@@ -0,0 +1,14 @@
+require_relative 'grape/entity_generator'
+require_relative 'grape/endpoint_generator'
+require_relative 'grape/api_generator'
+
+module Facera
+  module Grape
+    class << self
+      # Generate a Grape API for a specific facet
+      def api_for(facet_name)
+        APIGenerator.for_facet(facet_name)
+      end
+    end
+  end
+end

data/lib/facera/introspection.rb

@@ -0,0 +1,111 @@
+module Facera
+  class Introspection
+    class << self
+      def inspect_all
+        {
+          version: Facera::VERSION,
+          cores: inspect_cores,
+          facets: inspect_facets,
+          mounted: inspect_mounted
+        }
+      end
+
+      def inspect_cores
+        Registry.cores.map do |name, core|
+          {
+            name: name,
+            entities: core.entities.map { |entity_name, entity|
+              {
+                name: entity_name,
+                attributes: entity.attributes.map { |attr_name, attr|
+                  {
+                    name: attr_name,
+                    type: attr.type,
+                    required: attr.required?,
+                    immutable: attr.immutable?,
+                    enum_values: attr.enum_values
+                  }.compact
+                },
+                required_attributes: entity.attributes.select { |_, a| a.required? }.keys,
+                immutable_attributes: entity.attributes.select { |_, a| a.immutable? }.keys
+              }
+            },
+            capabilities: core.capabilities.map { |cap_name, cap|
+              {
+                name: cap_name,
+                type: cap.type,
+                entity: cap.entity_name,
+                required_params: cap.required_params,
+                optional_params: cap.optional_params,
+                preconditions: cap.preconditions.count,
+                validations: cap.validations.count,
+                transitions_to: cap.transitions,
+                sets_fields: cap.field_setters
+              }.compact
+            },
+            invariants: core.invariants.map { |inv|
+              {
+                name: inv.name,
+                description: inv.description
+              }
+            }
+          }
+        end
+      end
+
+      def inspect_facets
+        Registry.facets.map do |name, facet|
+          {
+            name: name,
+            core: facet.core_name,
+            description: facet.description,
+            exposures: facet.field_visibilities.map { |entity_name, visibility|
+              {
+                entity: entity_name,
+                visible_fields: visibility.visible_fields,
+                hidden_fields: visibility.hidden_fields,
+                computed_fields: visibility.computed_fields.keys,
+                field_aliases: visibility.field_aliases
+              }
+            },
+            capabilities: {
+              allowed: facet.capability_access.allowed_capabilities,
+              denied: facet.capability_access.denied_capabilities,
+              total: facet.capability_access.allowed_capabilities == :all ? 'all' : facet.capability_access.allowed_capabilities.count
+            },
+            scopes: facet.capability_access.scopes.keys,
+            error_verbosity: facet.error_verbosity,
+            format: facet.format,
+            rate_limit: facet.rate_limit,
+            audit_logging: facet.audit_enabled
+          }
+        end
+      end
+
+      def inspect_mounted
+        return {} unless defined?(Facera::AutoMount)
+
+        # This will be populated after auto_mount! is called
+        {
+          base_path: Facera.configuration.base_path,
+          version: Facera.configuration.version,
+          facets: Facera.configuration.instance_variable_get(:@facet_paths) || {}
+        }
+      end
+
+      def inspect_core(core_name)
+        core = Registry.cores[core_name]
+        return nil unless core
+
+        inspect_cores.find { |c| c[:name] == core_name }
+      end
+
+      def inspect_facet(facet_name)
+        facet = Registry.facets[facet_name]
+        return nil unless facet
+
+        inspect_facets.find { |f| f[:name] == facet_name }
+      end
+    end
+  end
+end

data/lib/facera/introspection_api.rb

@@ -0,0 +1,66 @@
+require 'grape'
+require_relative 'introspection'
+require_relative 'openapi_generator'
+
+module Facera
+  class IntrospectionAPI < ::Grape::API
+    format :json
+
+    desc 'Get complete introspection data'
+    get :introspect do
+      Facera::Introspection.inspect_all
+    end
+
+    desc 'Get all cores'
+    get :cores do
+      Facera::Introspection.inspect_cores
+    end
+
+    desc 'Get specific core'
+    params do
+      requires :name, type: Symbol, desc: 'Core name'
+    end
+    get 'cores/:name' do
+      core = Facera::Introspection.inspect_core(params[:name].to_sym)
+      error!('Core not found', 404) unless core
+      core
+    end
+
+    desc 'Get all facets'
+    get :facets do
+      Facera::Introspection.inspect_facets
+    end
+
+    desc 'Get specific facet'
+    params do
+      requires :name, type: Symbol, desc: 'Facet name'
+    end
+    get 'facets/:name' do
+      facet = Facera::Introspection.inspect_facet(params[:name].to_sym)
+      error!('Facet not found', 404) unless facet
+      facet
+    end
+
+    desc 'Get mounted configuration'
+    get :mounted do
+      Facera::Introspection.inspect_mounted
+    end
+
+    desc 'Get OpenAPI spec for all facets'
+    get :openapi do
+      Facera::OpenAPIGenerator.generate_all
+    end
+
+    desc 'Get OpenAPI spec for specific facet'
+    params do
+      requires :name, type: Symbol, desc: 'Facet name'
+    end
+    get 'openapi/:name' do
+      begin
+        Facera::OpenAPIGenerator.for_facet(params[:name].to_sym)
+      rescue => e
+        error!(e.message, 404)
+      end
+    end
+  end
+end

data/lib/facera/invariant.rb

@@ -0,0 +1,26 @@
+module Facera
+  class Invariant
+    attr_reader :name, :description, :block
+
+    def initialize(name, description: nil, &block)
+      @name = name.to_sym
+      @description = description
+      @block = block
+
+      raise Error, "Invariant '#{name}' must have a block" unless @block
+    end
+
+    def validate(context)
+      context.instance_eval(&block)
+    rescue StandardError => e
+      raise Error, "Invariant '#{name}' validation failed: #{e.message}"
+    end
+
+    def check(context)
+      result = validate(context)
+      return true if result
+
+      false
+    end
+  end
+end

data/lib/facera/loader.rb

@@ -0,0 +1,153 @@
+module Facera
+  class Loader
+    attr_reader :load_paths, :logger
+
+    def initialize(load_paths: nil, logger: nil)
+      @load_paths = load_paths || detect_load_paths
+      @logger = logger || Logger.new($stdout)
+    end
+
+    def load_all!
+      load_cores!
+      load_adapters!
+      load_facets!
+    end
+
+    def load_cores!
+      core_files = discover_files('cores')
+
+      if core_files.any?
+        @logger.info "📦 Loading cores..."
+        core_files.each do |file|
+          require file
+          @logger.info "  ✓ #{File.basename(file, '.rb')}"
+        end
+      end
+
+      core_files.count
+    end
+
+    def load_adapters!
+      adapter_files = discover_files('adapters')
+
+      if adapter_files.any?
+        @logger.info "🔌 Loading adapters..."
+        adapter_files.each do |file|
+          require file
+
+          # Auto-register adapter if it matches a core
+          adapter_name = File.basename(file, '.rb')
+          core_name = adapter_name.gsub(/_adapter$/, '').to_sym
+
+          # Try to find the adapter class
+          adapter_class_name = adapter_name.split('_').map(&:capitalize).join
+
+          if Object.const_defined?(adapter_class_name)
+            adapter_class = Object.const_get(adapter_class_name)
+
+            # Check if matching core exists
+            if Registry.cores[core_name]
+              AdapterRegistry.register(core_name, adapter_class)
+              @logger.info "  ✓ #{File.basename(file, '.rb')} → linked to :#{core_name} core"
+            else
+              @logger.warn "  ⚠ #{File.basename(file, '.rb')} → no matching :#{core_name} core found"
+            end
+          end
+        end
+      end
+
+      adapter_files.count
+    end
+
+    def load_facets!
+      facet_files = discover_files('facets')
+
+      if facet_files.any?
+        @logger.info "🎭 Loading facets..."
+        facet_files.each do |file|
+          require file
+          @logger.info "  ✓ #{File.basename(file, '.rb')}"
+        end
+      end
+
+      facet_files.count
+    end
+
+    private
+
+    def detect_load_paths
+      paths = []
+
+      if defined?(Rails)
+        # Rails application
+        paths << Rails.root.to_s
+      else
+        # Non-Rails: look for conventional directories
+        base_paths = [Dir.pwd, File.expand_path('..', Dir.pwd)]
+
+        base_paths.each do |base|
+          # Check if cores/ or facets/ exist at this level
+          if File.directory?(File.join(base, 'cores')) ||
+             File.directory?(File.join(base, 'facets'))
+            paths << base
+            break
+          end
+
+          # Check in app/ subdirectory
+          app_path = File.join(base, 'app')
+          if File.directory?(File.join(app_path, 'cores')) ||
+             File.directory?(File.join(app_path, 'facets'))
+            paths << app_path
+            break
+          end
+        end
+      end
+
+      paths
+    end
+
+    def discover_files(type)
+      files = []
+
+      @load_paths.each do |base_path|
+        # Try app/cores or app/facets (Rails-style)
+        pattern = File.join(base_path, 'app', type, '**/*.rb')
+        files.concat(Dir.glob(pattern))
+
+        # Try cores/ or facets/ directly (non-Rails)
+        pattern = File.join(base_path, type, '**/*.rb')
+        files.concat(Dir.glob(pattern))
+
+        # Try lib/cores or lib/facets
+        pattern = File.join(base_path, 'lib', type, '**/*.rb')
+        files.concat(Dir.glob(pattern))
+      end
+
+      files.uniq.sort
+    end
+  end
+
+  class << self
+    def load_all!(load_paths: nil)
+      loader = Loader.new(load_paths: load_paths)
+      loader.load_all!
+    end
+
+    def load_cores!(load_paths: nil)
+      loader = Loader.new(load_paths: load_paths)
+      loader.load_cores!
+    end
+
+    def load_adapters!(load_paths: nil)
+      loader = Loader.new(load_paths: load_paths)
+      loader.load_adapters!
+    end
+
+    def load_facets!(load_paths: nil)
+      loader = Loader.new(load_paths: load_paths)
+      loader.load_facets!
+    end
+  end
+end
+
+require 'logger'