teek 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a6639b7742fe7c1be6b94ddb2e7ea7e5f65f66d4525931f5a916a92ebe45a90
-  data.tar.gz: 0ef9c6a423201a35123193b951577f6f1aa2e375cbabdd20d5d34a35bdd47335
+  metadata.gz: bbf5c504422362129bd97b61be21e564e0c4fc4eddced045f97320a14d77d999
+  data.tar.gz: 2a2d74b99b040fe345f67ae83f52b7f759b24c5a2b86a644f3673d0539676023
 SHA512:
-  metadata.gz: 252f099b49231033ba5b59d7108c79f920247e357d80ac236b2ead0772b09e5af9aa023855b91597d73586e1c9d78a16724f8d57d7a1d12cddb082ce35e23de7
-  data.tar.gz: bb50dfed0ede92e95c55a74a047a9382498605579c28c6a874cbd5837ceb5a4e13d94b1360446dca0af22ab556a35c9e9ea7919f10235fb4332f52c7f1529129
+  metadata.gz: 7a380c5190906c2537aaca29e7da5c6def0abb727db6ca1137ace00f2fd9f85876753b192cd1ff327108a62123b25c8db2db20dbe98c01ca82dbb8a2de11333d
+  data.tar.gz: c6ed01ff47f5edf05407b3e60bd1108a94461988053e013becaadbed0fa9697990e92e28ceed55341299d7f42a11dcecdc21b8b803cef86ff50538efe6fcee1b

data/README.md

@@ -12,14 +12,13 @@ require 'teek'
 app = Teek::App.new
 
 app.show
-app.tcl_eval('wm title . "Hello Teek"')
+app.set_window_title('Hello Teek')
 
-# Create widgets with tcl_eval
-app.tcl_eval('ttk::label .lbl -text "Hello, world!"')
-app.tcl_eval('pack .lbl -pady 10')
-
-# Or use the command helper — Ruby values are auto-quoted,
+# Create widgets with the command helper — Ruby values are auto-quoted,
 # symbols pass through bare, and procs become callbacks
+app.command('ttk::label', '.lbl', text: 'Hello, world!')
+app.command(:pack, '.lbl', pady: 10)
+
 app.command('ttk::button', '.btn', text: 'Click me', command: proc {
   app.command('.lbl', :configure, text: 'Clicked!')
 })
@@ -28,17 +27,57 @@ app.command(:pack, '.btn', pady: 10)
 app.mainloop
 ```
 
+## Widgets
+
+`create_widget` returns a `Teek::Widget` — a thin wrapper that holds the widget path and provides convenience methods. Paths are auto-generated from the widget type.
+
+```ruby
+btn = app.create_widget('ttk::button', text: 'Click me')
+btn.pack(pady: 10)
+
+btn.command(:configure, text: 'Updated')  # widget subcommand
+btn.destroy
+```
+
+Nest widgets under a parent:
+
+```ruby
+frame = app.create_widget('ttk::frame')
+frame.pack(fill: :both, expand: 1)
+
+label = app.create_widget('ttk::label', parent: frame, text: 'Hello')
+label.pack(pady: 5)
+```
+
+Widgets work anywhere a path string is expected (via `to_s`):
+
+```ruby
+app.command(:pack, btn, pady: 10)       # equivalent to btn.pack(pady: 10)
+app.tcl_eval("#{btn} configure -text New")  # string interpolation works
+```
+
+The raw `app.command` approach still works for cases where you don't need a wrapper:
+
+```ruby
+app.command('ttk::label', '.mylabel', text: 'Direct')
+app.command(:pack, '.mylabel')
+```
+
 ## Callbacks
 
-Register Ruby procs as Tcl callbacks using `app.register_callback`:
+Pass a `proc` to `command` and it becomes a Tcl callback automatically:
 
 ```ruby
 app = Teek::App.new
 
-cb = app.register_callback(proc { |*args|
-  puts "clicked!"
-})
-app.tcl_eval("button .b -text Click -command {ruby_callback #{cb}}")
+app.command(:button, '.b', text: 'Click', command: proc { puts "clicked!" })
+```
+
+Use `bind` for event bindings with optional substitutions:
+
+```ruby
+app.bind('.b', 'Enter') { puts "hovered" }
+app.bind('.c', 'Button-1', :x, :y) { |x, y| puts "#{x},#{y}" }
 ```
 
 ### Stopping event propagation
@@ -46,11 +85,10 @@ app.tcl_eval("button .b -text Click -command {ruby_callback #{cb}}")
 In `bind` handlers, you can stop an event from propagating to subsequent binding tags by throwing `:teek_break`:
 
 ```ruby
-cb = app.register_callback(proc { |*|
-  puts "handled - stop here"
+app.bind('.entry', 'KeyPress', :keysym) { |key|
+  puts "handled #{key} - stop here"
   throw :teek_break
-})
-app.tcl_eval("bind .entry <Key-Return> {ruby_callback #{cb}}")
+}
 ```
 
 This is equivalent to Tcl's `break` command in a bind script.

data/Rakefile

@@ -26,8 +26,18 @@ namespace :docs do
     end
   end
 
+  desc "Generate per-method coverage JSON from SimpleCov data"
+  task :method_coverage do
+    if Dir.exist?('coverage/results')
+      require_relative 'lib/teek/method_coverage_service'
+      Teek::MethodCoverageService.new(coverage_dir: 'coverage').call
+    else
+      puts "No coverage data found (run tests with COVERAGE=1 first)"
+    end
+  end
+
   desc "Generate API docs (YARD JSON -> HTML)"
-  task yard: :yard_json do
+  task yard: [:yard_json, :method_coverage] do
     Bundler.with_unbundled_env do
       sh 'BUNDLE_GEMFILE=docs_site/Gemfile bundle exec ruby docs_site/build_api_docs.rb'
     end
@@ -261,6 +271,39 @@ namespace :docker do
 
   Rake::Task['docker:test'].enhance { Rake::Task['docker:prune'].invoke }
 
+  namespace :test do
+    desc "Run tests with coverage and generate report"
+    task coverage: 'docker:build' do
+      tcl_version = tcl_version_from_env
+      ruby_version = ruby_version_from_env
+      image_name = docker_image_name(tcl_version, ruby_version)
+
+      require 'fileutils'
+      FileUtils.rm_rf('coverage')
+      FileUtils.mkdir_p('coverage/results')
+
+      # Run tests with coverage enabled
+      ENV['COVERAGE'] = '1'
+      ENV['COVERAGE_NAME'] ||= 'main'
+      Rake::Task['docker:test'].invoke
+
+      # Collate inside Docker (paths match /app/lib/...)
+      puts "Collating coverage results..."
+      cmd = "docker run --rm --init"
+      cmd += " -v #{Dir.pwd}/coverage:/app/coverage"
+      cmd += " #{image_name}"
+      cmd += " bundle exec rake coverage:collate"
+
+      sh cmd
+
+      # Generate per-method coverage (runs locally, just needs Prism)
+      puts "Generating per-method coverage..."
+      Rake::Task['docs:method_coverage'].invoke
+
+      puts "Coverage report: coverage/index.html"
+    end
+  end
+
   # Scan sample files for # teek-record magic comment
   # Format: # teek-record: title=My Demo, codec=vp9
   def find_recordable_samples

data/ext/teek/tcltkbridge.c

@@ -130,9 +130,6 @@ static void interp_deleted_callback(ClientData, Tcl_Interp *);
 /* 16ms ≈ 60fps - balances UI responsiveness with scheduler contention */
 #define DEFAULT_TIMER_INTERVAL_MS 16
 
-/* Global timer interval for TclTkLib.mainloop (mutable) */
-static int g_thread_timer_ms = DEFAULT_TIMER_INTERVAL_MS;
-
 /* struct tcltk_interp is defined in tcltkbridge.h */
 
 /* ---------------------------------------------------------
@@ -1066,109 +1063,6 @@ interp_mainloop(VALUE self)
  * yields between events).
  * --------------------------------------------------------- */
 
-/* Global timer handler - re-registers itself using global interval */
-static void
-global_keepalive_timer_proc(ClientData clientData)
-{
-    if (g_thread_timer_ms > 0) {
-        Tcl_CreateTimerHandler(g_thread_timer_ms, global_keepalive_timer_proc, NULL);
-    }
-}
-
-static VALUE
-lib_mainloop(int argc, VALUE *argv, VALUE self)
-{
-    int check_root = 1;  /* default: exit when no windows remain */
-    int event_flags = TCL_ALL_EVENTS;
-
-    /* Optional check_root argument:
-     *   true (default): exit when Tk_GetNumMainWindows() == 0
-     *   false: keep running even with no windows (for timers, traces, etc.)
-     */
-    if (argc > 0 && argv[0] != Qnil) {
-        check_root = RTEST(argv[0]);
-    }
-
-    for (;;) {
-        /* Exit if check_root enabled and no windows remain */
-        if (check_root && Tk_GetNumMainWindows() <= 0) {
-            break;
-        }
-
-        if (rb_thread_alone()) {
-            /* No other threads - simple blocking wait */
-            Tcl_DoOneEvent(event_flags);
-        } else {
-            /* Other threads exist - use polling with brief sleep.
-             *
-             * We tried rb_thread_call_without_gvl() with Tcl_ThreadAlert to
-             * efficiently release GVL during blocking waits, but it proved
-             * unstable - crashes in Digest and other C extensions, UI freezes,
-             * and unreliable notifier wakeup across platforms.
-             *
-             * This polling approach is simple and stable:
-             * - Process any pending events without blocking
-             * - If no events, brief sleep to avoid spinning (uses ~1-3% CPU idle)
-             * - rb_thread_schedule() lets background threads run during sleep
-             */
-            int had_event = Tcl_DoOneEvent(event_flags | TCL_DONT_WAIT);
-            if (!had_event) {
-                rb_thread_schedule();
-#ifdef _WIN32
-                Sleep(5);  /* 5ms */
-#else
-                struct timespec ts = {0, 5000000};  /* 5ms */
-                nanosleep(&ts, NULL);
-#endif
-            }
-        }
-
-        /* Check for Ruby interrupts (Ctrl-C, etc) */
-        rb_thread_check_ints();
-    }
-
-    return Qnil;
-}
-
-static VALUE
-lib_get_thread_timer_ms(VALUE self)
-{
-    return INT2NUM(g_thread_timer_ms);
-}
-
-static VALUE
-lib_set_thread_timer_ms(VALUE self, VALUE val)
-{
-    int ms = NUM2INT(val);
-    if (ms < 0) {
-        rb_raise(rb_eArgError, "thread_timer_ms must be >= 0 (got %d)", ms);
-    }
-    g_thread_timer_ms = ms;
-    return val;
-}
-
-/* ---------------------------------------------------------
- * TclTkLib.do_one_event(flags = ALL_EVENTS) - Process single event
- *
- * Global function - Tcl_DoOneEvent doesn't require an interpreter.
- * Returns true if event was processed, false if nothing to do.
- * --------------------------------------------------------- */
-
-static VALUE
-lib_do_one_event(int argc, VALUE *argv, VALUE self)
-{
-    int flags = TCL_ALL_EVENTS;
-    int result;
-
-    if (argc > 0) {
-        flags = NUM2INT(argv[0]);
-    }
-
-    result = Tcl_DoOneEvent(flags);
-
-    return result ? Qtrue : Qfalse;
-}
-
 /* ---------------------------------------------------------
  * Interp#thread_timer_ms / #thread_timer_ms= - Get/set timer interval
  * --------------------------------------------------------- */
@@ -1539,10 +1433,6 @@ Init_tcltklib(void)
     rb_define_module_function(mTeek, "split_list", teek_split_list, 1);
     rb_define_module_function(mTeek, "tcl_to_bool", teek_tcl_to_bool, 1);
 
-    /* Global thread timer - doesn't require an interpreter */
-    rb_define_module_function(mTeek, "thread_timer_ms", lib_get_thread_timer_ms, 0);
-    rb_define_module_function(mTeek, "thread_timer_ms=", lib_set_thread_timer_ms, 1);
-
     /* Callback depth detection for unsafe operation warnings */
     rb_define_module_function(mTeek, "in_callback?", lib_in_callback_p, 0);
 

data/lib/teek/background_ractor4x.rb

@@ -153,13 +153,14 @@ module Teek
       # @return [self]
       def close
         @done = true
-        @control_port = nil  # Prevent further message sends
+        # Send stop to let the worker terminate itself — Ruby 4.x doesn't
+        # allow closing a Ractor from outside.
         begin
-          @worker_ractor&.close_incoming
-          @worker_ractor&.close_outgoing
+          @control_port&.send(:stop)
         rescue Ractor::ClosedError
           # Already closed
         end
+        @control_port = nil
         self
       end
 

data/lib/teek/debugger.rb

@@ -75,6 +75,43 @@ module Teek
       $stderr.puts "teek debugger: on_widget_destroyed(#{path}): #{e.message}"
     end
 
+    # Add a variable watch by name. Registers a Tcl trace so changes are recorded.
+    def add_watch(name)
+      return if @watches.key?(name)
+
+      cb_id = @app.register_callback(proc { |var_name, index, *|
+        record_watch(var_name, index)
+      })
+
+      @app.tcl_eval("trace add variable #{Teek.make_list(name)} write {ruby_callback #{cb_id}}")
+
+      @watches[name] = { cb_id: cb_id, values: [] }
+      record_watch(name, nil)
+      update_watches_ui
+    end
+
+    # Remove a variable watch by name.
+    def remove_watch(name)
+      info = @watches.delete(name)
+      return unless info
+
+      @app.tcl_eval(
+        "trace remove variable #{Teek.make_list(name)} write {ruby_callback #{info[:cb_id]}}"
+      )
+      @app.unregister_callback(info[:cb_id])
+
+      # Remove the tree item
+      watch_tree = "#{NB}.watches.tree"
+      item_id = "watch_#{name}"
+      if @app.command(watch_tree, 'exists', item_id) == "1"
+        @app.command(watch_tree, 'delete', item_id)
+      end
+
+      update_watches_ui
+    rescue Teek::TclError => e
+      $stderr.puts "teek debugger: remove_watch(#{name}): #{e.message}"
+    end
+
     private
 
     def setup_ui
@@ -507,38 +544,6 @@ module Teek
       })
     end
 
-    def add_watch(name)
-      return if @watches.key?(name)
-
-      # Register Tcl trace on the variable
-      cb_id = @app.register_callback(proc { |var_name, index, *|
-        record_watch(var_name, index)
-      })
-
-      @app.tcl_eval("trace add variable #{Teek.make_list(name)} write {ruby_callback #{cb_id}}")
-
-      @watches[name] = { cb_id: cb_id, values: [] }
-
-      # Capture current value
-      record_watch(name, nil)
-
-      update_watches_ui
-    end
-
-    def remove_watch(name)
-      info = @watches.delete(name)
-      return unless info
-
-      # Remove Tcl trace
-      @app.tcl_eval(
-        "trace remove variable #{Teek.make_list(name)} write {ruby_callback #{info[:cb_id]}}"
-      )
-      @app.unregister_callback(info[:cb_id])
-
-      update_watches_ui
-    rescue Teek::TclError => e
-      $stderr.puts "teek debugger: remove_watch(#{name}): #{e.message}"
-    end
 
     def record_watch(name, index)
       watch = @watches[name]

data/lib/teek/method_coverage_service.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "json"
+require "prism"
+
+module Teek
+  # @api private
+  # Transforms SimpleCov line coverage data into per-method coverage.
+  #
+  # Merges coverage data from all test suite result files, uses Prism to
+  # parse Ruby source files and find method definitions, then maps
+  # SimpleCov line coverage to calculate per-method percentages.
+  #
+  # @example
+  #   service = MethodCoverageService.new(
+  #     coverage_dir: "coverage",
+  #     source_dirs: ["lib"]
+  #   )
+  #   service.call
+  #   # => writes coverage/method_coverage.json
+  #
+  class MethodCoverageService
+    attr_reader :coverage_dir, :source_dirs, :output_path
+
+    def initialize(coverage_dir:, source_dirs: ["lib"], output_path: nil)
+      @coverage_dir = coverage_dir
+      @source_dirs = source_dirs
+      @output_path = output_path || File.join(coverage_dir, "method_coverage.json")
+    end
+
+    def call
+      coverage_files = Dir.glob(File.join(coverage_dir, "results", "*", "coverage.json"))
+      resultset_files = Dir.glob(File.join(coverage_dir, "results", "*", ".resultset.json"))
+      if coverage_files.empty? && resultset_files.empty?
+        warn "No coverage files found in #{coverage_dir}/results/"
+        return nil
+      end
+
+      coverage_data = load_and_merge_coverage(coverage_files)
+      result = {}
+
+      # Collect all methods from all files
+      all_methods = []
+      source_files.each do |file|
+        all_methods.concat(extract_methods(file))
+      end
+
+      # Group by class path and calculate coverage
+      all_methods.group_by { |m| m[:class_path] }.each do |class_path, methods|
+        class_result = { "class_methods" => {}, "instance_methods" => {} }
+        total_covered = 0
+        total_relevant = 0
+
+        methods.each do |method|
+          file_coverage = coverage_data[method[:file]]
+          next unless file_coverage
+
+          cov = calculate_coverage(file_coverage, method[:start_line], method[:end_line])
+          next unless cov
+
+          # Store [percent, lines_string] - compact format
+          method_data = [cov[:percent], cov[:lines]]
+          if method[:scope] == :class
+            class_result["class_methods"][method[:name]] = method_data
+          else
+            class_result["instance_methods"][method[:name]] = method_data
+          end
+
+          total_covered += cov[:covered]
+          total_relevant += cov[:relevant]
+        end
+
+        next if class_result["class_methods"].empty? && class_result["instance_methods"].empty?
+
+        if total_relevant > 0
+          class_result["total"] = (total_covered.to_f / total_relevant * 100).round(1)
+        end
+
+        result[class_path] = class_result
+      end
+
+      File.write(output_path, JSON.pretty_generate(result))
+      puts "Generated method coverage: #{output_path} (#{result.size} classes/modules)"
+      result
+    end
+
+    private
+
+    def load_and_merge_coverage(coverage_files)
+      merged = {}
+
+      # Read from coverage.json files
+      coverage_files.each do |file|
+        data = JSON.parse(File.read(file))
+        merge_coverage_data(merged, data["coverage"])
+      end
+
+      # Also read from .resultset.json files (worker/subprocess results)
+      resultset_files = Dir.glob(File.join(coverage_dir, "results", "*", ".resultset.json"))
+      resultset_files.each do |file|
+        data = JSON.parse(File.read(file))
+        # Resultsets are nested: { "suite_name" => { "coverage" => { ... } } }
+        data.each do |_suite_name, suite_data|
+          next unless suite_data.is_a?(Hash) && suite_data["coverage"]
+          merge_coverage_data(merged, suite_data["coverage"])
+        end
+      end
+
+      merged
+    end
+
+    def merge_coverage_data(merged, coverage_hash)
+      coverage_hash.each do |path, info|
+        # Normalize Docker /app/... paths to local paths
+        local_path = path.sub(%r{^/app/}, "")
+        lines = info["lines"]
+        if merged[local_path]
+          merged[local_path] = merge_line_coverage(merged[local_path], lines)
+        else
+          merged[local_path] = lines
+        end
+      end
+    end
+
+    def merge_line_coverage(lines_a, lines_b)
+      max_len = [lines_a.size, lines_b.size].max
+      (0...max_len).map do |i|
+        a = lines_a[i]
+        b = lines_b[i]
+        # nil means not relevant (comments, blank lines), "ignored" also not relevant
+        # If EITHER run says nil, treat as not relevant - a comment can't become executable
+        # This handles cases where different test suites have slightly different coverage metadata
+        if a.nil? || a == "ignored" || b.nil? || b == "ignored"
+          # Both nil -> nil, one nil -> nil (trust the nil, it means non-executable)
+          # Unless both are numeric, in which case take max
+          if (a.nil? || a == "ignored") && (b.nil? || b == "ignored")
+            nil
+          elsif a.nil? || a == "ignored"
+            # a is nil, b is numeric - but nil means not relevant, so prefer nil
+            # unless b > 0 (was actually executed, so must be real code)
+            b.to_i > 0 ? b : nil
+          else
+            # b is nil, a is numeric
+            a.to_i > 0 ? a : nil
+          end
+        else
+          [a.to_i, b.to_i].max
+        end
+      end
+    end
+
+    def source_files
+      source_dirs.flat_map { |dir| Dir.glob("#{dir}/**/*.rb") }
+    end
+
+    def extract_methods(file)
+      source = File.read(file)
+      result = Prism.parse(source)
+      methods = []
+
+      visitor = MethodVisitor.new(methods, file)
+      result.value.accept(visitor)
+
+      methods
+    rescue => e
+      warn "Failed to parse #{file}: #{e.message}"
+      []
+    end
+
+    def calculate_coverage(file_lines, start_line, end_line)
+      relevant = 0
+      covered = 0
+      lines_str = +""  # unfrozen string
+
+      # Skip first line (def) and last line (end) - only count method body
+      body_start = start_line + 1
+      body_end = end_line - 1
+
+      return nil if body_start > body_end  # empty method body
+
+      (body_start..body_end).each do |line_num|
+        next if line_num < 1 || line_num > file_lines.size
+        line_cov = file_lines[line_num - 1]  # array is 0-indexed
+        if line_cov.nil? || line_cov == "ignored"
+          lines_str << "-"  # not relevant
+        elsif line_cov.to_i > 0
+          lines_str << "1"  # covered
+          relevant += 1
+          covered += 1
+        else
+          lines_str << "0"  # not covered
+          relevant += 1
+        end
+      end
+
+      return nil if relevant == 0
+      { covered: covered, relevant: relevant, percent: (covered.to_f / relevant * 100).round(1), lines: lines_str }
+    end
+
+    # Prism AST visitor to extract method definitions with class context
+    class MethodVisitor < Prism::Visitor
+      def initialize(methods, file)
+        @methods = methods
+        @file = file
+        @namespace_stack = []  # track current class/module nesting
+        @singleton_depth = 0   # track if we're inside class << self
+      end
+
+      def visit_class_node(node)
+        name = constant_path_to_string(node.constant_path)
+        @namespace_stack.push(name)
+        super
+        @namespace_stack.pop
+      end
+
+      def visit_module_node(node)
+        name = constant_path_to_string(node.constant_path)
+        @namespace_stack.push(name)
+        super
+        @namespace_stack.pop
+      end
+
+      def visit_singleton_class_node(node)
+        @singleton_depth += 1
+        super
+        @singleton_depth -= 1
+      end
+
+      def visit_def_node(node)
+        return super if @namespace_stack.empty?  # skip top-level methods
+
+        scope = if node.receiver || @singleton_depth > 0
+          :class
+        else
+          :instance
+        end
+
+        @methods << {
+          name: node.name.to_s,
+          scope: scope,
+          start_line: node.location.start_line,
+          end_line: node.location.end_line,
+          class_path: @namespace_stack.join("::"),
+          file: @file
+        }
+
+        super
+      end
+
+      private
+
+      def constant_path_to_string(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          parent = node.parent ? constant_path_to_string(node.parent) + "::" : ""
+          parent + node.name.to_s
+        else
+          node.to_s
+        end
+      end
+    end
+  end
+end

data/lib/teek/ractor_support.rb

@@ -232,7 +232,7 @@ module Teek
       @impl.stop
     end
 
-    # Adapter for old yielder API
+    # @api private
     class StreamYielder
       def initialize(task)
         @task = task

data/lib/teek/version.rb

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