funicular 0.0.1 → 0.2.0

data/lib/generators/funicular/chat/templates/funicular_chat_component_picotest.rb.tt

@@ -0,0 +1,64 @@
+class FunicularChatComponentTest < Funicular::Testing::DOMTest
+  def setup
+    super
+    Funicular::HTTP.__test_messages = [
+      { "id" => 1, "name" => "Alice", "body" => "Hello from Rails" }
+    ]
+  end
+
+  def test_renders_loaded_messages
+    mount FunicularChatComponent
+    drain
+
+    assert_text "Funicular Chat"
+    assert_text "Hello from Rails"
+  end
+end
+
+module Funicular
+  module HTTP
+    class << self
+      attr_accessor :__test_messages
+
+      def get(url, &block)
+        block.call(Response.new(200, __test_messages))
+      end
+
+      def post(url, body = nil, &block)
+        block.call(Response.new(201, { "id" => 2, "name" => body[:message][:name], "body" => body[:message][:body] }))
+      end
+    end
+  end
+
+  module Cable
+    class TestConsumer
+      attr_reader :subscriptions
+
+      def initialize
+        @subscriptions = TestSubscriptions.new
+      end
+
+      def cleanup
+      end
+    end
+
+    class TestSubscriptions
+      def create(params, &block)
+        TestSubscription.new
+      end
+    end
+
+    class TestSubscription
+      def on_connected(&block)
+        block.call
+      end
+
+      def unsubscribe
+      end
+    end
+
+    def self.create_consumer(url)
+      TestConsumer.new
+    end
+  end
+end

data/lib/generators/funicular/chat/templates/funicular_chat_controller.rb.tt

@@ -0,0 +1,4 @@
+class FunicularChatController < ApplicationController
+  def show
+  end
+end

data/lib/generators/funicular/chat/templates/funicular_chat_message.rb.tt

@@ -0,0 +1,13 @@
+class FunicularChatMessage < ApplicationRecord
+  validates :name, presence: true, length: { maximum: 40 }
+  validates :body, presence: true, length: { maximum: 500 }
+
+  def as_json(*)
+    {
+      id: id,
+      name: name,
+      body: body,
+      created_at: created_at.iso8601
+    }
+  end
+end

data/lib/generators/funicular/chat/templates/funicular_chat_messages_controller.rb.tt

@@ -0,0 +1,23 @@
+class FunicularChatMessagesController < ApplicationController
+  def index
+    messages = FunicularChatMessage.order(:created_at).last(50)
+    render json: messages
+  end
+
+  def create
+    message = FunicularChatMessage.new(message_params)
+
+    if message.save
+      ActionCable.server.broadcast("funicular_chat", message.as_json)
+      render json: message, status: :created
+    else
+      render json: { errors: message.errors.full_messages }, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def message_params
+    params.require(:message).permit(:name, :body)
+  end
+end

data/lib/generators/funicular/chat/templates/initializer.rb.tt

@@ -0,0 +1,4 @@
+Funicular.start(container: "app") do |router|
+  router.get("/funicular_chat", to: FunicularChatComponent, as: "funicular_chat")
+  router.set_default("/funicular_chat")
+end

data/lib/generators/funicular/chat/templates/show.html.erb.tt

@@ -0,0 +1,6 @@
+<%% content_for :head do %>
+  <%%= stylesheet_link_tag "funicular_chat", "data-turbo-track": "reload" %>
+<%% end %>
+
+<%%= funicular_app_container %>
+<script type="application/x-mrb" src="<%%= asset_path("app.mrb") %>"></script>

data/lib/tasks/funicular.rake

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+namespace :funicular do
+  desc "Compile Funicular Ruby files to .mrb format"
+  task compile: :environment do
+    require "funicular/compiler"
+    require "funicular/plugin"
+
+    source_dir = Rails.root.join("app", "funicular")
+    output_file = Rails.root.join("app", "assets", "builds", "app.mrb")
+    debug_mode = !Rails.env.production?
+
+    unless Dir.exist?(source_dir)
+      puts "Skipping Funicular compilation: #{source_dir} does not exist"
+      next
+    end
+
+    begin
+      plugin_registry = Funicular::Plugin::Registry.new(Rails.root)
+      plugin_registry.validate!
+      plugin_registry.sync_assets
+      compiler = Funicular::Compiler.new(
+        source_dir: source_dir,
+        output_file: output_file,
+        debug_mode: debug_mode,
+        prepend_source_files: plugin_registry.local_source_files
+      )
+      compiler.compile
+    rescue Funicular::Plugin::Error => e
+      puts "ERROR: #{e.message}"
+      exit 1
+    rescue Funicular::Compiler::PicorbcMissingError => e
+      puts "ERROR: #{e.message}"
+      exit 1
+    rescue => e
+      puts "ERROR: Failed to compile Funicular application"
+      puts e.message
+      puts e.backtrace.join("\n")
+      exit 1
+    end
+  end
+
+  desc "Show all Funicular routes"
+  task routes: :environment do
+    require "funicular/commands/routes"
+
+    begin
+      Funicular::Commands::Routes.new.execute
+    rescue => e
+      puts "ERROR: Failed to display routes"
+      puts e.message
+      puts e.backtrace.join("\n")
+      exit 1
+    end
+  end
+
+  desc "Install Funicular debug assets, PicoRuby.wasm artifacts, and test support into a Rails app"
+  task install: ["install:debug_assets", "install:wasm", "install:test"] do
+    puts ""
+    puts "All Funicular assets installed."
+    puts ""
+    puts "Next steps:"
+    puts "  1. In your layout, replace any hardcoded PicoRuby <script> tag with:"
+    puts '       <%= picoruby_include_tag %>'
+    puts ""
+    puts "  2. (Optional) Edit config/initializers/funicular.rb to choose the source"
+    puts "     for each environment (:local_debug, :local_dist, :cdn)."
+    puts ""
+    puts "  3. (Optional, development only) Add to your layout to enable"
+    puts "     the component highlighter:"
+    puts '       <% if Rails.env.development? %>'
+    puts '         <%= javascript_include_tag "funicular_debug", "data-turbo-track": "reload" %>'
+    puts '         <%= stylesheet_link_tag "funicular_debug", "data-turbo-track": "reload" %>'
+    puts '       <% end %>'
+    puts ""
+    puts "  4. Run `npm install` if package.json was created or updated."
+    puts "     Client-side Funicular tests live under test/funicular/client/**/*_picotest.rb"
+    puts "     and run through `bin/rails test`."
+  end
+
+  namespace :install do
+    desc "Install Funicular debug JS/CSS assets and the gem initializer"
+    task :debug_assets do
+      require "fileutils"
+
+      javascripts_dir  = Rails.root.join("app", "assets", "javascripts")
+      stylesheets_dir  = Rails.root.join("app", "assets", "stylesheets")
+      initializers_dir = Rails.root.join("config", "initializers")
+
+      FileUtils.mkdir_p(javascripts_dir)
+      FileUtils.mkdir_p(stylesheets_dir)
+      FileUtils.mkdir_p(initializers_dir)
+
+      source_js          = File.expand_path("../funicular/assets/funicular_debug.js", __dir__)
+      source_css         = File.expand_path("../funicular/assets/funicular_debug.css", __dir__)
+      source_initializer = File.expand_path("../funicular/assets/funicular.rb", __dir__)
+
+      dest_js          = javascripts_dir.join("funicular_debug.js")
+      dest_css         = stylesheets_dir.join("funicular_debug.css")
+      dest_initializer = initializers_dir.join("funicular.rb")
+
+      FileUtils.cp(source_js,          dest_js)
+      FileUtils.cp(source_css,         dest_css)
+      FileUtils.cp(source_initializer, dest_initializer)
+
+      puts "Installed Funicular debug assets:"
+      puts "  - #{dest_js}"
+      puts "  - #{dest_css}"
+      puts "  - #{dest_initializer}"
+    end
+
+    desc "Install vendored PicoRuby.wasm artifacts (dist + debug) into public/picoruby/"
+    task :wasm do
+      require "fileutils"
+
+      vendor_root = File.expand_path("../funicular/vendor/picoruby", __dir__)
+      unless Dir.exist?(vendor_root)
+        abort "Vendored PicoRuby artifacts not found at #{vendor_root}. " \
+              "Reinstall the funicular gem or run `rake funicular:vendor` from a checkout."
+      end
+
+      dest_root = Rails.root.join("public", "picoruby")
+      FileUtils.mkdir_p(dest_root)
+
+      %w[dist debug].each do |variant|
+        src = File.join(vendor_root, variant)
+        dst = dest_root.join(variant)
+
+        unless Dir.exist?(src)
+          warn "Skipping #{variant}: #{src} not found"
+          next
+        end
+
+        FileUtils.rm_rf(dst)
+        FileUtils.mkdir_p(dst)
+        FileUtils.cp_r(File.join(src, "."), dst)
+
+        puts "Installed PicoRuby #{variant} build to #{dst}"
+      end
+    end
+
+
+    desc "Install Funicular client test support"
+    task :test do
+      require "fileutils"
+      require "json"
+
+      test_dir = Rails.root.join("test")
+      funicular_test_dir = test_dir.join("funicular")
+      client_test_dir = funicular_test_dir.join("client")
+      FileUtils.mkdir_p(client_test_dir)
+
+      test_helper = test_dir.join("test_helper.rb")
+      unless File.exist?(test_helper)
+        File.write(test_helper, <<~TEST_HELPER)
+          ENV["RAILS_ENV"] ||= "test"
+
+          require_relative "../config/environment"
+          require "rails/test_help"
+        TEST_HELPER
+        puts "Installed #{test_helper}"
+      end
+
+      application_test = funicular_test_dir.join("application_test.rb")
+      unless File.exist?(application_test)
+        File.write(application_test, <<~APPLICATION_TEST)
+          require_relative "../test_helper"
+          require "funicular/testing"
+
+          class FunicularApplicationTest < ActiveSupport::TestCase
+            test "client-side Funicular tests" do
+              result = Funicular::Testing.run!(timeout_ms: 10_000)
+              Funicular::Testing.assert_picotests(self, result)
+            end
+          end
+        APPLICATION_TEST
+        puts "Installed #{application_test}"
+      end
+
+      keep_file = client_test_dir.join(".keep")
+      FileUtils.touch(keep_file) unless File.exist?(keep_file)
+
+      package_json = Rails.root.join("package.json")
+      package = if File.exist?(package_json)
+                  JSON.parse(File.read(package_json))
+                else
+                  { "private" => true }
+                end
+      package["devDependencies"] ||= {}
+      package["devDependencies"]["jsdom"] ||= "^26.1.0"
+      File.write(package_json, JSON.pretty_generate(package) + "\n")
+      puts "Updated #{package_json}"
+
+      gitignore = Rails.root.join(".gitignore")
+      if File.exist?(gitignore)
+        content = File.read(gitignore)
+        unless content.lines.any? { |line| line.chomp == "/node_modules" }
+          File.open(gitignore, "a") do |f|
+            f.puts
+            f.puts "# Ignore Node dependencies."
+            f.puts "/node_modules"
+          end
+          puts "Updated #{gitignore}"
+        end
+      end
+
+      puts "Installed Funicular test support:"
+      puts "  - #{application_test}"
+      puts "  - #{client_test_dir}"
+      puts "  - jsdom dev dependency in #{package_json}"
+    end
+  end
+end
+
+# Hook into assets:precompile for production deployment
+if Rake::Task.task_defined?("assets:precompile")
+  Rake::Task["assets:precompile"].enhance(["funicular:compile"])
+end

data/minitest/fixtures/funicular_app/components/greeting_component.rb

@@ -0,0 +1,16 @@
+class GreetingComponent < Funicular::Component
+  def initialize_state
+    { title: "Default Title", items: [] }
+  end
+
+  def render
+    div(class: "greeting") do
+      h1 { state.title }
+      ul do
+        state.items.each do |item|
+          li(key: item["id"]) { item["name"] }
+        end
+      end
+    end
+  end
+end

data/minitest/fixtures/funicular_app/initializer.rb

@@ -0,0 +1,5 @@
+Funicular.start(container: "app") do |router|
+  router.get("/greet", to: GreetingComponent, as: "greet")
+  router.get("/greet/:id", to: GreetingComponent, as: "greet_item")
+  router.set_default("/greet")
+end

data/minitest/funicular_test.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class FunicularTest < Minitest::Test
+  def test_VERSION
+    assert ::Funicular.const_defined?(:VERSION)
+  end
+
+  def test_something_useful
+    assert("expected"!="actual")
+  end
+end

data/minitest/hydration_test.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Exercises the hydration mismatch guard under CRuby. The structural decision
+# (`hydration_match?`) and the dev warning (`warn_hydration_mismatch`) are pure
+# Ruby, so they are tested here without a DOM. The actual recovery swap done by
+# `full_render_fallback` (Renderer + replaceChild) is JS-only and is covered by
+# the browser/manual verification step, not here.
+#
+# A plain Hash stands in for the server DOM node: hydration_match? only reads
+# `dom_element[:tagName]`, which a Hash answers the same way a JS::Element does.
+class HydrationMatchTest < Minitest::Test
+  def setup
+    Funicular::SSR::Runtime.load_framework!
+    Funicular.env = "development"
+  end
+
+  def teardown
+    Funicular.env = "development"
+  end
+
+  # Builds the probe at runtime (Class.new) so the suite matches its picotest
+  # twin and never references Funicular::Component at load time. render is never
+  # invoked here (we feed vnodes directly); it only satisfies the abstract API.
+  def probe
+    klass = Class.new(Funicular::Component) do
+      def render
+        div { "x" }
+      end
+
+      def match?(vnode, dom)
+        hydration_match?(vnode, dom)
+      end
+
+      def warn_for(vnode, dom)
+        warn_hydration_mismatch(vnode, dom)
+      end
+    end
+    klass.new
+  end
+
+  def el(tag)
+    Funicular::VDOM::Element.new(tag, {}, ["x"])
+  end
+
+  # --- hydration_match? (the decision that drives the fallback) ---------
+
+  def test_matches_when_root_tags_agree
+    assert_equal true, probe.match?(el("div"), { tagName: "DIV" })
+  end
+
+  def test_detects_mismatched_root_tag
+    assert_equal false, probe.match?(el("div"), { tagName: "SPAN" })
+  end
+
+  def test_tag_comparison_is_case_insensitive
+    assert_equal true, probe.match?(el("h1"), { tagName: "H1" })
+  end
+
+  def test_non_element_vnode_is_treated_as_match
+    assert_equal true, probe.match?(Funicular::VDOM::Text.new("hi"), { tagName: "DIV" })
+  end
+
+  def test_missing_dom_tag_name_is_treated_as_match
+    assert_equal true, probe.match?(el("div"), {})
+  end
+
+  # --- warn_hydration_mismatch (dev-only diagnostics) -------------------
+
+  def test_warning_fires_in_development
+    out, _err = capture_io do
+      probe.warn_for(el("div"), { tagName: "SPAN" })
+    end
+    assert_includes out, "Hydration mismatch"
+    assert_includes out, "<div>"
+    assert_includes out, "<span>"
+  end
+
+  def test_warning_is_silent_in_production
+    Funicular.env = "production"
+    out, _err = capture_io do
+      probe.warn_for(el("div"), { tagName: "SPAN" })
+    end
+    assert_equal "", out
+  end
+end

data/minitest/plugin_test.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+require_relative "test_helper"
+
+class PluginTest < Minitest::Test
+  def test_registry_resolves_funicular_group_gems_and_syncs_assets
+    Dir.mktmpdir do |dir|
+      rails_root = File.join(dir, "app")
+      gem_root = File.join(dir, "funicular-datepicker")
+      FileUtils.mkdir_p(File.join(gem_root, "lib", "components"))
+      FileUtils.mkdir_p(File.join(gem_root, "assets"))
+      File.write(File.join(gem_root, "lib", "date_picker.rb"), "# plugin entry\n")
+      File.write(File.join(gem_root, "lib", "components", "date_picker_component.rb"), "# component\n")
+      File.write(File.join(gem_root, "assets", "date_picker.css"), "/* css */\n")
+
+      spec = Gem::Specification.new do |s|
+        s.name = "funicular-datepicker"
+        s.version = "0.1.0"
+        s.full_gem_path = gem_root
+      end
+
+      registry = Funicular::Plugin::Registry.new(rails_root)
+      registry.define_singleton_method(:funicular_specs) { [spec] }
+      registry.sync_assets
+
+      synced_css = File.join(
+        rails_root,
+        "app",
+        "assets",
+        "builds",
+        "funicular",
+        "plugins",
+        "funicular_datepicker",
+        "date_picker.css"
+      )
+      assert File.exist?(synced_css)
+
+      entries = registry.asset_entries
+      assert_equal 1, entries.size
+      assert_equal "css", entries.first["type"]
+      assert_equal "funicular/plugins/funicular_datepicker/date_picker.css", entries.first["logical_path"]
+      assert_equal [
+        File.join(gem_root, "lib", "components", "date_picker_component.rb"),
+        File.join(gem_root, "lib", "date_picker.rb")
+      ], registry.local_source_files
+    end
+  end
+end

data/minitest/schema_test.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "active_model"
+
+# Exercises Funicular::Schema.validations_for: deriving client validation rules
+# from an ActiveModel class, honoring the attribute allowlist and the per-kind
+# denylist, skipping unsupported/conditional validators, and translating the
+# `format` regexp for the JS RegExp engine.
+class SchemaDerivationTest < Minitest::Test
+  class Account
+    include ActiveModel::Validations
+    attr_accessor :name, :email, :age, :role, :code, :score
+
+    # Custom validator (kind :even) stands in for any non-standard validator
+    # the client has no counterpart for; it must be skipped during derivation.
+    class EvenValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value); end
+    end
+
+    validates :name, presence: true, length: { maximum: 30 }
+    validates :email, format: { with: /\A[^@\s]+@[^@\s]+\z/ }
+    validates :age, numericality: { only_integer: true, greater_than: 0 }
+    validates :role, inclusion: { in: %w[admin user] }
+    validates :code, presence: true, if: -> { false }      # conditional -> skipped
+    validates :score, even: true                           # unsupported kind -> skipped
+  end
+
+  def derive(attrs, except: {})
+    Funicular::Schema.validations_for(Account, attrs, except: except)
+  end
+
+  def test_presence_and_length
+    result = derive(["name"])
+    assert_equal({ "presence" => true, "length" => { "maximum" => 30 } }, result["name"])
+  end
+
+  def test_only_listed_attributes_are_introspected
+    result = derive(["name"])
+    assert_equal ["name"], result.keys
+  end
+
+  def test_numericality_and_inclusion
+    result = derive(["age", "role"])
+    assert_equal({ "only_integer" => true, "greater_than" => 0 }, result["age"]["numericality"])
+    assert_equal({ "in" => %w[admin user] }, result["role"]["inclusion"])
+  end
+
+  def test_format_translates_ruby_anchors
+    result = derive(["email"])
+    fmt = result["email"]["format"]
+    # \A and \z become ^ and $ for JS RegExp.
+    assert_equal "^[^@\\s]+@[^@\\s]+$", fmt["with"]
+  end
+
+  def test_denylist_suppresses_a_kind
+    result = derive(["name"], except: { name: [:length] })
+    assert_equal({ "presence" => true }, result["name"])
+  end
+
+  def test_conditional_validator_is_skipped
+    result = derive(["code"])
+    assert_nil result["code"]
+  end
+
+  def test_unsupported_kind_is_skipped
+    result = derive(["score"])
+    assert_nil result["score"]
+  end
+
+  def test_build_inlines_validations_into_attributes
+    schema = Funicular::Schema.build(
+      Account,
+      attributes: {
+        "display_name" => { type: "string", readonly: false },
+        "name" => { type: "string", readonly: false }
+      },
+      endpoints: { "update" => { method: "PATCH", path: "/x/:id" } },
+      except: { name: [:length] }
+    )
+    # Attribute with no validators is untouched.
+    assert_equal({ type: "string", readonly: false }, schema[:attributes]["display_name"])
+    # Validators are merged inline; denylist drops :length here.
+    assert_equal(
+      { type: "string", readonly: false, validations: { "presence" => true } },
+      schema[:attributes]["name"]
+    )
+    assert_equal({ "update" => { method: "PATCH", path: "/x/:id" } }, schema[:endpoints])
+  end
+
+  def test_extended_regexp_is_skipped
+    klass = Class.new do
+      include ActiveModel::Validations
+      def self.name; "Extended"; end
+      attr_accessor :token
+      validates :token, format: { with: /
+        \A \d+ \z   # an integer, written with x-mode whitespace
+      /x }
+    end
+    result = nil
+    capture_io do  # silence the skip warning
+      result = Funicular::Schema.validations_for(klass, ["token"])
+    end
+    assert_nil result["token"]
+  end
+end