konpeito 0.2.4 → 0.3.0

data/Justfile

@@ -0,0 +1,107 @@
+# Konpeito — Ruby AOT Native Compiler
+# Task runner recipes (https://github.com/casey/just)
+
+# Default recipe: show available recipes
+default:
+    @just --list
+
+# --- Development ---
+
+# Install dependencies
+setup:
+    bundle install
+
+# Clean build artifacts and caches
+clean:
+    rm -rf .konpeito_cache/
+    find . -name "*.bundle" -not -path "./vendor/*" -delete
+    find . -name "*.so" -not -path "./vendor/*" -delete
+    find . -name "*.jar" -not -path "./vendor/*" -delete
+    find . -name "*.class" -not -path "./vendor/*" -delete
+    find . -name "*.o" -not -path "./vendor/*" -delete
+    find . -name "*.ll" -not -path "./vendor/*" -delete
+    find . -name "*.bc" -not -path "./vendor/*" -delete
+
+# Check environment (LLVM, Java, etc.)
+doctor:
+    bundle exec ruby -Ilib bin/konpeito doctor
+
+# --- Testing ---
+
+# Run all unit tests
+test:
+    bundle exec rake test
+
+# Run a specific test file
+test-file path:
+    bundle exec ruby -Ilib:test {{path}}
+
+# Run conformance tests (all backends)
+conformance:
+    bundle exec rake conformance
+
+# Run conformance tests (native only)
+conformance-native:
+    bundle exec rake conformance:native
+
+# Run conformance tests (JVM only)
+conformance-jvm:
+    bundle exec rake conformance:jvm
+
+# --- Linting & Formatting ---
+
+# Run RuboCop linter
+lint:
+    bundle exec rubocop
+
+# Run RuboCop with auto-fix
+lint-fix:
+    bundle exec rubocop -A
+
+# Format source files (via RuboCop)
+fmt *args:
+    bundle exec ruby -Ilib bin/konpeito fmt {{args}}
+
+# Check formatting (via RuboCop)
+fmt-check:
+    bundle exec ruby -Ilib bin/konpeito fmt --check
+
+# --- Build & Run ---
+
+# Compile a Ruby file to CRuby extension
+build *args:
+    bundle exec ruby -Ilib bin/konpeito build {{args}}
+
+# Compile and run a Ruby file
+run *args:
+    bundle exec ruby -Ilib bin/konpeito run {{args}}
+
+# Type-check a Ruby file
+check *args:
+    bundle exec ruby -Ilib bin/konpeito check {{args}}
+
+# --- Benchmarks ---
+
+# Run a benchmark (e.g., just bench native_internal)
+bench name:
+    bundle exec ruby benchmark/{{name}}_bench.rb
+
+# List available benchmarks
+bench-list:
+    @ls benchmark/*_bench.rb | sed 's|benchmark/||; s|_bench.rb||'
+
+# --- Install ---
+
+# Build and install gem locally
+install:
+    gem build konpeito.gemspec && gem install konpeito-*.gem && rm -f konpeito-*.gem
+
+# --- Tools ---
+
+# Start LSP server
+lsp:
+    bundle exec ruby -Ilib bin/konpeito lsp
+
+# Generate shell completion
+completion shell:
+    bundle exec ruby -Ilib bin/konpeito completion {{shell}}

data/README.md

@@ -16,6 +16,81 @@ Konpeito uses a three-tier type resolution strategy:
 
 Adding an RBS signature promotes a dynamic fallback to static dispatch. The compiler tells you where the boundaries are — fix them if you want, or leave them dynamic. Your call.
 
+## What Gets Compiled
+
+Konpeito compiles your `.rb` source files into native code. Understanding the boundary between compiled and non-compiled code is key:
+
+**Compiled (native code):**
+- All `.rb` files you pass to `konpeito build`
+- Files resolved via `require` / `require_relative` at compile time (when source is available on the load path via `-I`)
+- Within compiled code: type-resolved operations become native CPU instructions; unresolved operations fall back to `rb_funcallv` (CRuby's dynamic dispatch) with a compiler warning
+
+**Not compiled (loaded at runtime by CRuby):**
+- Installed gems referenced by `require` — the compiler detects these and emits `rb_require` calls so CRuby loads them at runtime
+- Standard libraries (`json`, `net/http`, `fileutils`, etc.) — same treatment
+- Any Ruby code running in the host CRuby process outside the compiled extension
+
+The compiled extension and CRuby coexist in the same process. Native code calls CRuby C API functions (`rb_define_class`, `rb_funcallv`, `rb_ary_push`, etc.), so compiled code can freely create Ruby objects, call Ruby methods, and interact with any loaded gem. The speed gain comes from the parts where Konpeito resolves types and emits native instructions instead of going through Ruby's method dispatch.
+
+This leads to two usage patterns:
+
+### Pattern 1: Extension Library
+
+Compile performance-critical code into a CRuby extension (`.bundle` / `.so`). Your main application stays as regular Ruby and loads the compiled code via `require`:
+
+```ruby
+# math.rb — compiled by Konpeito
+module MyMath
+  def self.sum_up_to(n)
+    total = 0
+    i = 1
+    while i <= n
+      total += i
+      i += 1
+    end
+    total
+  end
+end
+```
+
+```bash
+konpeito build math.rb   # → math.bundle
+```
+
+```ruby
+# app.rb — regular Ruby, NOT compiled
+require_relative "math"
+puts MyMath.sum_up_to(10_000_000)   # calls into compiled native code
+```
+
+Your code can `require` installed gems freely. The compiler compiles your code and emits runtime `require` calls for the gems, so everything works together at runtime:
+
+```ruby
+# my_app.rb — compiled by Konpeito
+require "kumiki"     # gem — loaded at runtime by CRuby
+include Kumiki
+
+class MyComponent < Component
+  # ... your code is compiled natively
+  # ... calls to kumiki methods go through rb_funcallv (dynamic dispatch)
+end
+```
+
+This is the pattern shown in [Hello World](#hello-world) below.
+
+### Pattern 2: Whole Application
+
+Compile an entire Ruby application including framework code — the compiler traces all `require` statements on the load path specified by `-I` and compiles everything into a single extension:
+
+```bash
+konpeito build -I /path/to/kumiki/lib counter.rb   # → counter.bundle (971 KB)
+ruby -r ./counter -e ""                             # load and run
+```
+
+The difference from Pattern 1: framework code (kumiki) is also compiled, enabling direct dispatch, monomorphization, and inlining across the entire codebase. Without `-I`, only your code is compiled (~50 KB) and the framework is loaded at runtime — this still works, but method calls into the framework go through dynamic dispatch.
+
+See [Tutorial](docs/tutorial.md) for step-by-step walkthroughs of both patterns with working examples.
+
 ## Quick Start
 
 ### Prerequisites
@@ -65,18 +140,20 @@ Write a small Ruby file:
 
 ```ruby
 # math.rb
-def add(a, b)
-  a + b
-end
+module MyMath
+  def self.add(a, b)
+    a + b
+  end
 
-def sum_up_to(n)
-  total = 0
-  i = 1
-  while i <= n
-    total = total + i
-    i = i + 1
+  def self.sum_up_to(n)
+    total = 0
+    i = 1
+    while i <= n
+      total = total + i
+      i = i + 1
+    end
+    total
   end
-  total
 end
 ```
 
@@ -88,19 +165,26 @@ konpeito build math.rb          # produces math.bundle (macOS), math.so (Linux),
 
 ```ruby
 require_relative "math"
-puts add(3, 4)        # => 7
-puts sum_up_to(100)   # => 5050
+puts MyMath.add(3, 4)        # => 7
+puts MyMath.sum_up_to(100)   # => 5050
 ```
 
-A few more commands to get you going:
+### CLI Overview
 
 ```bash
-konpeito doctor                        # check your environment
-konpeito run --target jvm main.rb      # compile and run in one step
-konpeito fmt                           # format source files
-konpeito fmt --check                   # check formatting without modifying
+konpeito build src/main.rb                          # compile to CRuby extension
+konpeito build --target jvm -o app.jar src/main.rb  # compile to standalone JAR
+konpeito run src/main.rb                            # build and run in one step
+konpeito check src/main.rb                          # type check only (no codegen)
+konpeito init my_project                            # scaffold a new project
+konpeito test                                       # run project tests
+konpeito fmt                                        # format source files
+konpeito watch src/main.rb                          # auto-recompile on changes
+konpeito doctor                                     # check your environment
 ```
 
+For detailed options and examples, see [CLI Reference](docs/cli-reference.md).
+
 ## Features
 
 - **HM Type Inference** — Types are inferred automatically. No annotations needed for most code.
@@ -118,9 +202,38 @@ konpeito fmt --check                   # check formatting without modifying
 - **Pattern Matching** — Full `case/in` support with array, hash, guard, and capture patterns.
 - **Modern Ruby Syntax** — `_1`/`_2` numbered params, `it`, endless methods, `class << self`, safe navigation (`&.`), and more.
 - **Concurrency** — Fiber, Thread, Mutex, ConditionVariable, SizedQueue, and Ractor (with `Ractor::Port`, `Ractor.select`, `Ractor[:key]` local storage, `name:`, `monitor`/`unmonitor`). JVM Ractor uses Virtual Threads for scheduling but does not enforce object isolation — objects are shared by reference, unlike CRuby's strict isolation model.
-- **Built-in Tooling** — Formatter (`fmt`), LSP (hover, completion, go-to-def, references, rename), debug info (`-g`), and profiling (`--profile`).
+- **Built-in Tooling** — Formatter (`fmt`), debug info (`-g`), and profiling (`--profile`).
 - **Castella UI** — A reactive GUI framework for the JVM backend (see below).
 
+## Supported Ruby Syntax
+
+Konpeito supports most Ruby 4.0 syntax:
+
+| Category | Supported |
+|----------|-----------|
+| Literals | Integer, Float, String, Symbol, Array, Hash, Regexp, Range, Heredoc, nil/true/false |
+| String interpolation | `"Hello #{name}"` |
+| Variables | Local, `@instance`, `@@class`, `$global` |
+| Control flow | `if`/`unless`, `while`/`until`, `for`, `case`/`when`, `case`/`in`, `break`, `next`, `return` |
+| Methods & OOP | Classes, modules, inheritance, `super`, `attr_accessor`, method visibility (`private`/`protected`) |
+| Blocks & closures | `yield`, `block_given?`, Proc, Lambda, `&blk` |
+| Pattern matching | Literals, arrays, hashes, guards (`if`), captures (`=>`), pins (`^`), rest (`*`) |
+| Exceptions | `begin`/`rescue`/`else`/`ensure`, custom exception classes |
+| Modern syntax | `_1`/`_2` numbered params, `it`, endless methods, `class << self`, `&.` safe navigation |
+| Operators | Full overloading (`+`, `-`, `*`, `==`, `<=>`, etc.), compound assignment (`+=`, `\|\|=`, `&&=`) |
+| Arguments | Keyword args, rest args (`*args`), keyword rest (`**kwargs`), splat (`foo(*arr)`) |
+| Concurrency | Fiber, Thread, Mutex, ConditionVariable, SizedQueue, Ractor (JVM) |
+| Misc | `alias`, `defined?`, open classes, multi-assignment, `%w`/`%i` literals |
+
+### Not Supported (by design)
+
+- `eval`, `instance_eval`, `class_eval`
+- `define_method`, `method_missing`
+- `ObjectSpace`, `Binding`
+- Dynamic `require`/`load` (variable-based require)
+
+For the complete specification, see [Language Specification](docs/language-specification.md).
+
 ## JVM Backend
 
 Konpeito can also compile to JVM bytecode, producing standalone JAR files:
@@ -370,45 +483,32 @@ app.run
 
 ## Performance
 
-Konpeito shines in compute-heavy, typed loops where unboxed arithmetic and backend optimizations kick in. All benchmarks compare against Ruby 4.0.1 with YJIT enabled on Apple M4 Max.
+Konpeito targets compute-heavy, typed loops where unboxed arithmetic and backend optimizations can make a meaningful difference. Actual speedups depend heavily on the workload, input data, and hardware — the numbers below are from one specific environment and should be taken as rough indicators, not guarantees.
 
 ### LLVM Backend (CRuby Extension)
 
-| Benchmark | vs Ruby (YJIT) |
-|---|---|
-| N-Body simulation (5M steps) | **81x** faster |
-| Numeric method inlining (abs, even?, odd?) | **25-29x** faster |
-| Range enumerable (each, reduce, select) | **40-53x** faster |
-| Integer#times (nested, typed) | **891-972x** faster |
-| Typed reduce over Array[Integer] | **7x** faster |
-| Loop sum (n=100) | **18x** faster |
-| Typed counter loop (LICM + LLVM O2) | **5,345x** faster |
-| StaticArray/NativeArray sum (4 elements) | **65x** faster |
-| StaticArray/NativeArray sum (16 elements) | **232x** faster |
+Typical speedup ranges observed on our test machine (vs Ruby YJIT):
 
-These numbers compare native-internal performance (the loop itself runs inside compiled code). Single cross-boundary calls see smaller gains due to CRuby interop overhead.
+- **Numeric loops** (arithmetic, counters, reductions): often **5–80x** faster, depending on how much of the loop body can be fully unboxed
+- **Native data structures** (NativeArray, StaticArray): **~10–60x** faster for tight element-access loops
+- **Iterator inlining** (each, map, reduce, times): **~7–50x** faster with typed arrays or ranges
 
-### JVM Backend (Standalone JAR)
+These figures reflect native-internal performance — the loop itself runs entirely inside compiled code. Cross-boundary calls (Ruby ↔ native) see smaller gains due to interop overhead.
 
-Benchmarks run on Java 21 (HotSpot) with JIT warmup. "Realistic" mode uses variable arguments to prevent constant folding.
+**Where Konpeito is slower:** Pattern matching (`case/in`) is currently **~2–3x slower** than YJIT — Ruby's VM is highly optimized for this. String operations (NativeString) are also slower than CRuby's mature string implementation due to conversion overhead. Workloads that are I/O-bound, rely heavily on dynamic features, or hit areas where YJIT already excels may see no benefit or even regressions.
 
-| Benchmark (10M iterations) | Ruby (YJIT) | Konpeito JVM | Speedup |
-|---|---|---|---|
-| Multiply Add (realistic) | 196 ms | 5.0 ms | **39x** faster |
-| Compute Chain (realistic) | 300 ms | 5.1 ms | **59x** faster |
-| Arithmetic Intensive (realistic) | 272 ms | 5.0 ms | **55x** faster |
-| Loop Sum (realistic) | 107 ms | 2.6 ms | **41x** faster |
-| Fibonacci fib(30) x 10 (recursive) | 300 ms | 9.8 ms | **31x** faster |
+### JVM Backend (Standalone JAR)
 
-The JVM backend benefits from HotSpot's JIT compilation on top of Konpeito's static type resolution, yielding **30-60x** speedups for numeric workloads.
+For numeric workloads, the JVM backend typically shows **~30–60x** speedups over Ruby YJIT, benefiting from HotSpot's JIT on top of Konpeito's static type resolution. I/O-bound or polymorphic code will see less improvement.
 
-> **Environment:** Apple M4 Max, Ruby 4.0.1 + YJIT, Java 21.0.10 (HotSpot), macOS 15.
+> **Test environment:** Apple M4 Max, Ruby 4.0.1 + YJIT, Java 21.0.10 (HotSpot), macOS 15. Results will vary on different hardware and configurations.
 
 ## Documentation
 
 ### User Guides
 
 - **[Getting Started](docs/getting-started.md)** — Installation, Hello World, first project, Castella UI tutorial
+- **[Tutorial](docs/tutorial.md)** — Extension library and whole-application compilation patterns
 - **[CLI Reference](docs/cli-reference.md)** — All commands, options, and configuration
 - **[API Reference](docs/api-reference.md)** — Castella UI widgets, native data structures, standard library
 
@@ -439,7 +539,7 @@ This project was developed collaboratively between a human director ([Yasushi It
 
 Konpeito is in an early stage. Bugs and undocumented limitations should be expected. Actively improving — bug reports and feedback are very welcome.
 
-The JVM backend might be more mature than the LLVM/CRuby backend at this point. If you're getting started, try the JVM backend first (`--target jvm`).
+Both LLVM and JVM backends are tested against the project's conformance test suite covering core language features (control flow, classes, blocks, exceptions, pattern matching, concurrency, etc.). The LLVM backend has been successfully used to compile and run [kumiki](https://github.com/i2y/kumiki)'s `all_widgets_demo.rb` — a non-trivial reactive GUI application with 20+ widget types — as a CRuby extension.
 
 ## Contributing
 

data/konpeito.gemspec

@@ -21,6 +21,8 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
   spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["documentation_uri"] = "#{spec.homepage}/blob/main/docs/getting-started.md"
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
@@ -35,9 +37,8 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "prism"
   spec.add_dependency "rbs"
-  spec.add_dependency "language_server-protocol", "~> 3.17"
 
   # ruby-llvm is optional — only needed for native/CRuby extension compilation (--target native).
-  # JVM backend (--target jvm), type checking, LSP, and formatting work without it.
+  # JVM backend (--target jvm), type checking, and formatting work without it.
   # Install manually: gem install ruby-llvm
 end

data/lib/konpeito/cli/build_command.rb

@@ -16,11 +16,14 @@ module Konpeito
         parse_options!
 
         if args.empty?
-          error("No source file specified. Usage: konpeito build <source.rb>")
+          source_file = find_default_source
+          unless source_file
+            error("No source file specified. Usage: konpeito build <source.rb>")
+          end
+        else
+          source_file = args.first
         end
 
-        source_file = args.first
-
         unless File.exist?(source_file)
           error("File not found: #{source_file}")
         end
@@ -204,6 +207,16 @@ module Konpeito
             size_str = File.exist?(output_file) ? " (#{format_size(File.size(output_file))})" : ""
             emit("Finished", "in #{duration_str} -> #{output_file}#{size_str}")
           end
+
+          # Show usage hint (skip for --run and --lib)
+          unless options[:run_after] || options[:library]
+            if options[:target] == :jvm
+              emit("Hint", "java -jar #{output_file}")
+            else
+              ext_name = File.basename(output_file, File.extname(output_file))
+              emit("Hint", "ruby -r ./#{ext_name} -e \"YourModule.method\"")
+            end
+          end
         end
       rescue Konpeito::DependencyError => e
         display_dependency_error(e)
@@ -215,6 +228,11 @@ module Konpeito
         $stderr.puts "Error: #{e.message}"
         exit 1
       end
+
+      def find_default_source
+        candidates = ["src/main.rb", "main.rb", "app.rb"]
+        candidates.find { |f| File.exist?(f) }
+      end
     end
   end
 end