funicular 0.0.1 → 0.2.0

data/lib/funicular/middleware.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Funicular
+  class Middleware
+    class << self
+      attr_accessor :last_mtime, :compiling, :mutex
+
+      def reset!
+        @last_mtime = nil
+        @compiling = false
+        @mutex = Mutex.new
+      end
+    end
+
+    # Initialize class state
+    reset!
+
+    def initialize(app)
+      @app = app
+      @source_dir = Rails.root.join("app", "funicular")
+      @output_file = Rails.root.join("app", "assets", "builds", "app.mrb")
+    end
+
+    def call(env)
+      recompile_if_needed if should_check_recompile?
+      @app.call(env)
+    end
+
+    private
+
+    def should_check_recompile?
+      Rails.env.development? && Dir.exist?(@source_dir)
+    end
+
+    def recompile_if_needed
+      current_mtime = latest_source_mtime
+
+      # Skip if already compiling or if no changes detected
+      return if self.class.compiling
+      return if self.class.last_mtime && current_mtime <= self.class.last_mtime
+
+      self.class.mutex.synchronize do
+        # Double-check inside the lock
+        return if self.class.compiling
+        return if self.class.last_mtime && current_mtime <= self.class.last_mtime
+
+        self.class.compiling = true
+      end
+
+      begin
+        Rails.logger.info "Funicular: Source files changed, recompiling..."
+        plugin_registry = build_plugins
+        if Dir.exist?(@source_dir)
+          compiler = Compiler.new(
+            source_dir: @source_dir,
+            output_file: @output_file,
+            debug_mode: true,
+            logger: Rails.logger,
+            prepend_source_files: plugin_registry.local_source_files
+          )
+          compiler.compile
+        end
+        self.class.last_mtime = current_mtime
+        invalidate_asset_pipeline_cache
+      rescue => e
+        Rails.logger.error "Funicular compilation failed: #{e.message}"
+      ensure
+        self.class.compiling = false
+      end
+    end
+
+    # Force the asset pipeline to drop its cached fingerprint for app.mrb.
+    #
+    # Propshaft caches Asset instances (and memoizes #digest / #compiled_content)
+    # in LoadPath, and only refreshes them when its file watcher detects a change
+    # in a file whose extension is registered in Mime::EXTENSION_LOOKUP. The .mrb
+    # extension is not registered there, so when funicular rewrites app.mrb the
+    # Propshaft cache is never invalidated and asset_path('app.mrb') keeps
+    # returning the stale fingerprinted URL until the Rails process is restarted.
+    #
+    # We side-step that by invoking the cache sweeper directly after every
+    # successful recompile. This is a no-op if Propshaft is not in use.
+    def invalidate_asset_pipeline_cache
+      return unless Rails.application.respond_to?(:assets)
+
+      assets = Rails.application.assets
+      return unless assets.respond_to?(:load_path)
+
+      load_path = assets.load_path
+      return unless load_path.respond_to?(:cache_sweeper)
+
+      load_path.cache_sweeper.execute
+    end
+
+    def latest_source_mtime
+      source_files = Dir.glob(File.join(@source_dir, "**", "*.rb"))
+      plugin_files = plugin_source_files
+      all_files = source_files + plugin_files
+      return Time.at(0) if all_files.empty?
+
+      all_files.map { |f| File.mtime(f) }.max
+    end
+
+    def build_plugins
+      registry = Plugin::Registry.new(Rails.root)
+      return registry if registry.specs.empty?
+
+      registry.validate!
+      registry.sync_assets
+      registry
+    rescue Plugin::Error => e
+      Rails.logger.error "Funicular plugin compilation failed: #{e.message}"
+      Plugin::Registry.new(Rails.root)
+    end
+
+    def plugin_source_files
+      registry = Plugin::Registry.new(Rails.root)
+      registry.local_source_files + registry.specs.flat_map { |spec| spec.css_paths.map(&:to_s) }
+    rescue Plugin::Error
+      []
+    end
+  end
+end

data/lib/funicular/plugin.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Funicular
+  module Plugin
+    BUILD_DIR = "app/assets/builds/funicular/plugins"
+    GROUP = :funicular
+
+    class Error < StandardError; end
+
+    class Project
+      attr_reader :root
+
+      def initialize(root)
+        @root = Pathname(root).expand_path
+      end
+
+      def assets_dir
+        root.join("assets")
+      end
+
+      def source_dir
+        root.join("lib")
+      end
+
+      def source_files
+        nested = Dir.glob(source_dir.join("*", "**", "*.rb").to_s).sort
+        top_level = Dir.glob(source_dir.join("*.rb").to_s).sort
+        nested + top_level
+      end
+
+      def css_paths
+        Dir.glob(assets_dir.join("*.css").to_s).sort.map { |path| Pathname(path) }
+      end
+    end
+
+    class Spec
+      attr_reader :bundler_spec
+
+      def initialize(bundler_spec)
+        @bundler_spec = bundler_spec
+      end
+
+      def root
+        @root ||= Pathname(bundler_spec.full_gem_path).expand_path
+      end
+
+      def project
+        @project ||= Project.new(root)
+      end
+
+      def name
+        bundler_spec.name
+      end
+
+      def css_paths
+        project.css_paths
+      end
+
+      def validate!
+        raise Error, "Missing Funicular plugin gem: #{root}" unless root.exist?
+        raise Error, "No Ruby source files found in #{project.source_dir}" if project.source_files.empty?
+
+        self
+      end
+    end
+
+    class Registry
+      attr_reader :rails_root
+
+      def initialize(rails_root)
+        @rails_root = Pathname(rails_root).expand_path
+      end
+
+      def specs
+        @specs ||= funicular_specs.map { |spec| Spec.new(spec) }
+      end
+
+      def sync_assets
+        build_root = rails_root.join(BUILD_DIR)
+        FileUtils.mkdir_p(build_root)
+
+        validated_specs.each do |spec|
+          target_dir = build_root.join(Plugin.safe_name(spec.name))
+          FileUtils.rm_rf(target_dir)
+          FileUtils.mkdir_p(target_dir)
+          spec.css_paths.each do |path|
+            FileUtils.cp(path, target_dir.join(File.basename(path))) if path.exist?
+          end
+        end
+      end
+
+      def local_source_files
+        validated_specs.flat_map { |spec| spec.project.source_files }
+      end
+
+      def asset_entries
+        validated_specs.flat_map do |spec|
+          safe_name = Plugin.safe_name(spec.name)
+          css = spec.css_paths.map { |path| File.basename(path) }
+          css.map { |file| { "type" => "css", "logical_path" => "funicular/plugins/#{safe_name}/#{file}" } }
+        end
+      end
+
+      def validate!
+        specs.each(&:validate!)
+      end
+
+      private
+
+      def funicular_specs
+        names = bundler_dependencies
+                .select { |dependency| dependency.groups.include?(GROUP) }
+                .map(&:name)
+        return [] if names.empty?
+
+        bundler_specs.select { |spec| names.include?(spec.name) }
+      end
+
+      def bundler_dependencies
+        require "bundler"
+
+        Bundler.definition.dependencies
+      rescue LoadError
+        raise Error, "Bundler is required to resolve Funicular plugin gems"
+      end
+
+      def bundler_specs
+        require "bundler"
+
+        Bundler.load.specs
+      rescue LoadError
+        raise Error, "Bundler is required to resolve Funicular plugin gems"
+      end
+
+      def validated_specs
+        specs.map(&:validate!)
+      end
+    end
+
+    def self.safe_name(name)
+      name.to_s.split("/").last.gsub(/[^a-zA-Z0-9]+/, "_").gsub(/\A_+|_+\z/, "").downcase
+    end
+  end
+end

data/lib/funicular/railtie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Funicular
+  class Railtie < Rails::Railtie
+    railtie_name :funicular
+
+    initializer "funicular.middleware" do |app|
+      if Rails.env.development?
+        app.middleware.use Funicular::Middleware
+      end
+    end
+
+    initializer "funicular.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        require "funicular/helpers/picoruby_helper"
+        include Funicular::Helpers::PicorubyHelper
+      end
+    end
+
+    rake_tasks do
+      load "tasks/funicular.rake"
+    end
+  end
+end

data/lib/funicular/route_parser.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Funicular
+  class RouteParser
+    attr_reader :routes
+
+    def initialize(source_file)
+      @source_file = source_file
+      @routes = []
+    end
+
+    def parse
+      return [] unless File.exist?(@source_file)
+
+      content = File.read(@source_file)
+      lines = content.split("\n")
+
+      lines.each do |line|
+        # Skip comments and empty lines
+        trimmed = line.strip
+        next if trimmed.empty? || trimmed.start_with?('#')
+
+        # Parse router.get/post/put/patch/delete lines
+        if trimmed.include?('router.')
+          parse_route_line(trimmed)
+        end
+      end
+
+      @routes
+    end
+
+    private
+
+    def parse_route_line(line)
+      # Extract HTTP method
+      method = nil
+      ['get', 'post', 'put', 'patch', 'delete', 'add_route'].each do |m|
+        if line.include?("router.#{m}")
+          method = m
+          break
+        end
+      end
+
+      return unless method
+
+      # Extract path (between first pair of quotes)
+      path = extract_quoted_string(line)
+      return unless path
+
+      # Extract component name (after 'to:' or as second argument)
+      component = nil
+      if line.include?('to:')
+        to_idx = line.index('to:')
+        if to_idx
+          # Component name is after 'to:'
+          after_to = line[to_idx + 3..-1].strip
+          # Find where component name ends (comma or paren)
+          end_idx = find_first_of(after_to, [',', ')'])
+          if end_idx
+            component = after_to[0...end_idx].strip
+          else
+            component = after_to.strip
+          end
+        end
+      elsif method == 'add_route'
+        # Old style: router.add_route('/path', ComponentName)
+        # Find second comma-separated value
+        first_comma = line.index(',')
+        if first_comma
+          after_comma = line[first_comma + 1..-1].strip
+          # Component name ends at comma or paren
+          end_idx = find_first_of(after_comma, [',', ')'])
+          if end_idx
+            component = after_comma[0...end_idx].strip
+          else
+            component = after_comma.strip
+          end
+        end
+      end
+
+      return unless component
+
+      # Extract helper name (after 'as:')
+      helper_name = nil
+      if line.include?('as:')
+        as_idx = line.index('as:')
+        if as_idx
+          after_as = line[as_idx + 3..-1]
+          helper_str = extract_quoted_string(after_as)
+          helper_name = helper_str ? "#{helper_str}_path" : nil
+        end
+      end
+
+      # Add route
+      @routes << {
+        method: method == 'add_route' ? 'GET' : method.upcase,
+        path: path,
+        component: component,
+        helper: helper_name
+      }
+    end
+
+    def extract_quoted_string(text)
+      # Find first quoted string (single or double quotes)
+      start_idx = nil
+      quote_char = nil
+
+      text.each_char.with_index do |char, idx|
+        if char == '"' || char == "'"
+          if start_idx.nil?
+            start_idx = idx
+            quote_char = char
+          elsif char == quote_char
+            # Found closing quote
+            return text[(start_idx + 1)...idx]
+          end
+        end
+      end
+
+      nil
+    end
+
+    def find_first_of(text, chars)
+      # Find index of first occurrence of any char in chars array
+      min_idx = nil
+
+      chars.each do |char|
+        idx = text.index(char)
+        if idx
+          min_idx = idx if min_idx.nil? || idx < min_idx
+        end
+      end
+
+      min_idx
+    end
+  end
+end

data/lib/funicular/schema.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Funicular
+  # Derives client-side validation rules from an ActiveModel/ActiveRecord
+  # class so they can be embedded in the JSON returned by a schema controller
+  # and reused by Funicular::Model on the client.
+  #
+  # Security model: validations are derived ONLY for the attribute names the
+  # caller passes (the schema's existing attribute allowlist), so nothing
+  # outside the already-public schema is ever introspected. A per-attribute
+  # `except` denylist suppresses specific validator kinds.
+  module Schema
+    # Validator kinds that have a client-side counterpart in
+    # Funicular::Model::Validations. Others (notably :uniqueness, which needs
+    # the database, and any custom validator) are skipped.
+    SUPPORTED_KINDS = %i[
+      presence absence length format numericality
+      inclusion exclusion acceptance confirmation
+    ].freeze
+
+    # Build a full schema hash, merging derived validations inline into each
+    # attribute entry (the shape Funicular::Model.load_schema consumes):
+    #
+    #   Funicular::Schema.build(User,
+    #     attributes: { "display_name" => { type: "string", readonly: false } },
+    #     endpoints:  { "update" => { method: "PATCH", path: "/users/:id" } },
+    #     except:     { username: [:format] })
+    #   # => { attributes: { "display_name" => { type:, readonly:,
+    #   #        validations: { "presence" => true, "length" => {...} } } },
+    #   #      endpoints: {...} }
+    #
+    # Only the attributes you declare are introspected (allowlist); `except`
+    # drops specific kinds per attribute (denylist).
+    def self.build(model_class, attributes:, endpoints: {}, except: {})
+      merged = {}
+      attributes.each do |name, definition|
+        rules = rules_for(model_class, name, except_kinds(except, name))
+        merged[name] = rules.empty? ? definition : definition.merge(validations: rules)
+      end
+      { attributes: merged, endpoints: endpoints }
+    end
+
+    # Returns { "attr" => { "presence" => true, "length" => { "maximum" => 30 } } }
+    # for the given attribute names only. Useful when emitting validations as a
+    # separate block rather than inline (see #build for the inline form).
+    def self.validations_for(model_class, attribute_names, except: {})
+      result = {}
+      attribute_names.each do |name|
+        rules = rules_for(model_class, name, except_kinds(except, name))
+        result[name.to_s] = rules unless rules.empty?
+      end
+      result
+    end
+
+    # Derive the { kind => options } rules for a single attribute.
+    def self.rules_for(model_class, name, skip_kinds)
+      attr = name.to_sym
+      rules = {}
+      model_class.validators_on(attr).each do |validator|
+        kind = validator.kind
+        next unless SUPPORTED_KINDS.include?(kind)
+        next if skip_kinds.include?(kind)
+        # Conditional/context validators can't be evaluated on the client.
+        next if conditional?(validator.options)
+
+        serialized = serialize(kind, validator.options)
+        next if serialized.nil?
+        rules[kind.to_s] = serialized
+      end
+      rules
+    end
+
+    def self.except_kinds(except, name)
+      Array(except[name.to_sym] || except[name.to_s]).map(&:to_sym)
+    end
+
+    def self.conditional?(options)
+      options.key?(:if) || options.key?(:unless) || options.key?(:on)
+    end
+
+    def self.serialize(kind, options)
+      case kind
+      when :presence, :absence, :acceptance, :confirmation
+        true
+      when :length
+        serialize_length(options)
+      when :numericality
+        serialize_numericality(options)
+      when :inclusion, :exclusion
+        serialize_set(options)
+      when :format
+        RegexpTranslator.translate(options[:with])
+      end
+    end
+
+    def self.serialize_length(options)
+      opts = {}
+      [:minimum, :maximum, :is].each do |k|
+        opts[k.to_s] = options[k] if options[k].is_a?(Integer)
+      end
+      if (range = options[:in] || options[:within]).is_a?(Range)
+        opts["minimum"] = range.min
+        opts["maximum"] = range.max
+      end
+      opts.empty? ? nil : opts
+    end
+
+    def self.serialize_numericality(options)
+      opts = {}
+      opts["only_integer"] = true if options[:only_integer]
+      [:greater_than, :greater_than_or_equal_to, :equal_to,
+       :less_than, :less_than_or_equal_to, :other_than].each do |k|
+        opts[k.to_s] = options[k] if options[k].is_a?(Numeric)
+      end
+      opts.empty? ? true : opts
+    end
+
+    def self.serialize_set(options)
+      list = options[:in] || options[:within]
+      list = list.to_a if list.is_a?(Range)
+      return nil unless list.is_a?(Array)
+      return nil unless list.all? { |v| json_scalar?(v) }
+      { "in" => list }
+    end
+
+    def self.json_scalar?(value)
+      value.is_a?(String) || value.is_a?(Numeric) ||
+        value == true || value == false || value.nil?
+    end
+
+    # Best-effort translation of a Ruby Regexp into a JS-RegExp-compatible
+    # source. The client runs Regexp as a JS RegExp wrapper, so Ruby-only
+    # constructs are either translated (\A, \z, \Z anchors) or, when they have
+    # no safe JS equivalent, the validator is skipped with a warning.
+    module RegexpTranslator
+      # Substrings that JS RegExp cannot accept; presence means "skip".
+      INCOMPATIBLE = ['[[:', '\\h', '\\H', '\\G', '(?>'].freeze
+
+      def self.translate(regexp)
+        return nil unless regexp.is_a?(Regexp)
+
+        if (regexp.options & Regexp::EXTENDED) != 0
+          return skip("extended (x) mode")
+        end
+
+        source = regexp.source
+        if INCOMPATIBLE.any? { |token| source.include?(token) }
+          return skip("uses a construct unsupported by JS RegExp")
+        end
+
+        js_source = source.gsub('\\A', '^').gsub('\\z', '$').gsub('\\Z', '$')
+
+        flags = +''
+        flags << 'i' if (regexp.options & Regexp::IGNORECASE) != 0
+        flags << 'm' if (regexp.options & Regexp::MULTILINE) != 0
+
+        { 'with' => js_source, 'flags' => flags }
+      end
+
+      def self.skip(reason)
+        warn "[Funicular::Schema] skipping a format validator: #{reason}; " \
+             "declare it directly in the Funicular::Model if needed"
+        nil
+      end
+    end
+  end
+end

data/lib/funicular/ssr/runtime.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../compiler"
+
+module Funicular
+  module SSR
+    # Loads the PicoRuby (mrblib) framework runtime and the application's
+    # component classes into the CRuby process so the server can build VDOM
+    # and serialize it to HTML.
+    #
+    # The mrblib runtime is plain Ruby; the only JS access happens inside
+    # methods that SSR never calls (mount, patcher, fetch, history, ...).
+    # `Funicular.server = true` makes the few JS-touching entry points
+    # (Funicular.start, Router#start, FileUpload.mount, Debug) no-ops.
+    module Runtime
+      MRBLIB_DIR = File.expand_path("../../../mrblib", __dir__)
+
+      # Load order is by dependency at *class-body* evaluation time. Most
+      # files reference JS / other classes only inside methods, so only a
+      # few real dependencies exist (vdom before html_serializer; styles and
+      # vdom before component; component before error_boundary).
+      LOAD_ORDER = %w[
+        environment_inquirer
+        vdom
+        html_serializer
+        differ
+        patcher
+        styles
+        debug
+        component
+        error_boundary
+        router
+        0_validations
+        1_validators
+        model
+        store
+        store_singleton
+        store_collection
+        form_builder
+        http
+        cable
+        file_upload
+        funicular
+      ].freeze
+
+      class << self
+        # Load the framework runtime once. Idempotent.
+        def load_framework!
+          return if @framework_loaded
+
+          LOAD_ORDER.each do |name|
+            require File.join(MRBLIB_DIR, "#{name}.rb")
+          end
+          Funicular.server = true
+          @framework_loaded = true
+        end
+
+        # Load the application's component/model/store/initializer files in the
+        # canonical order. Running the initializer registers routes into
+        # Funicular.router (server-safe: Funicular.start skips all DOM work).
+        #
+        # Funicular model files are loaded so that the constants they define
+        # (e.g. Channel, Session) are available when the initializer evaluates
+        # `load_schemas({ Channel => "channel", ... })`. If a Funicular model
+        # shares a name with a same-named ActiveRecord model that Rails has
+        # already auto-loaded, Ruby raises TypeError (superclass mismatch).
+        # In that case we rescue and continue: the AR constant is already defined
+        # and is all that load_schemas needs (it ignores the hash on the server).
+        #
+        # Loaded once per process. Restart the server to pick up changes.
+        def boot!(source_dir)
+          load_framework!
+          return if @app_loaded
+
+          files = Funicular::Compiler.source_files(source_dir.to_s)
+          files.each do |file|
+            begin
+              Kernel.load(file)
+            rescue TypeError => e
+              # Funicular model name conflicts with an already-loaded AR model.
+              # The constant is already defined; safe to skip.
+              warn "[Funicular SSR] Skipped #{File.basename(file)}: #{e.message}"
+            end
+          end
+          @app_loaded = true
+        end
+
+        # Test/escape hatch: forget loaded application state so a different
+        # app (or a reload) can be booted. Does not unload the framework.
+        def reset_app!
+          @app_loaded = false
+        end
+
+        def framework_loaded?
+          !!@framework_loaded
+        end
+      end
+    end
+  end
+end