sloprb 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ff98879a675d5126bf4e37c9401d8d87fa35e0cdb42e033abc7ab4136aa53fd
-  data.tar.gz: 745f8d3681d84fe32cc2ea7a09d24e9ed96aa06bbfbc67674b9f20538a82c6f5
+  metadata.gz: 506617067b45365d7b15feb11e2cc0dab95787adb139adbf60e5c544a7a2dd0f
+  data.tar.gz: 722f67bc7a699d4be54fed15ab204d39d5b68928b2d836d690df958f78a5ca60
 SHA512:
-  metadata.gz: 2f7be175ddca3b762712a0316f9901c0c7142cefa3588824a799eb5a0d7eaf132f13930a8afb0d68f944f8bb9e775d5c559a2db53e1aeb3a02e6f2f1cdd93bda
-  data.tar.gz: 013c7d4091e2254d5dc7fddd5862e993dbee44e5a7159c55f408ca4127c4265d68e901c818bd37adf7288d979dc265148c541d9492b4ff75c9ee9e4e10d6aeb7
+  metadata.gz: 23ec911d3f3fd26a939b58bde4171e4bed6579b2326fca4f186c5afd22e3159782cd975228bb09ba6d3d24175d4a39e5b4eb1c5063ceca646f7bc480cbebae0b
+  data.tar.gz: 11d5af26a6ea5f78b9bef9c2e199fbc6775966719081fee60b3c1b2ef75b2c02573b95c0060f593461eeb3351f2b26f6753aae4932269c962a20d397b8c41420

data/CHANGELOG.md

@@ -1,3 +1,9 @@
 # Change log
 
 ## master
+
+## 0.1.0 (2026-06-28)
+
+- Initial release. ([@palkan][])
+
+[@palkan]: https://github.com/palkan

data/README.md

@@ -3,45 +3,163 @@
 
 # Sloprb
 
-TBD
+Stop writing code, let LLMs slop it for you at boot time 🦾.
+
+SlopRB uses [Require Hooks][require-hooks] to intercept Ruby's `require` calls and generate some code for you using LLMs. Currently supported scenarios:
+- [Slop method implementations](#slopping-methods) on the fly. Just mark a method with `# :slop:`, describe what it should do in comments, and SlopRB fills in the body when the file is loaded.
+- [Auto-correct syntax errors](#eating-typos). When loading a file fails with a SyntaxError, the LLM fixes it, persists the fix, and retries the load.
 
 ## Installation
 
-Adding to a gem:
+Add to your Gemfile:
+
+```ruby
+gem "sloprb"
+```
+
+## Slopping methods
+
+1. You write a method stub with a `# :slop:` marker and optional doc comments describing the desired behavior.
+2. When the file is required, SlopRB parses it with [Prism](https://github.com/ruby/prism), extracts all slop-marked methods, and sends the source to an LLM.
+3. The LLM generates the method bodies, SlopRB splices them into the source, validates syntax, and returns the transformed code to Ruby.
+
+Consider an example:
 
 ```ruby
-# my-cool-gem.gemspec
-Gem::Specification.new do |spec|
-  # ...
-  spec.add_dependency "sloprb"
-  # ...
+class Calculator
+  # Evaluates the passed arithmetic expression.
+  def evaluate(expr) # :slop:
+  end
 end
+
+puts Calculator.new.evaluate("2 + 2 * 3") #=> 8
 ```
 
-Or adding to your project:
+You can also provide a sketch of the method or some hints in the body:
 
 ```ruby
-# Gemfile
-gem "sloprb"
+class Greeting
+  # Generate a friendly greeting message for the given name.
+  def greet(name) # :slop:
+    stable_index = ... # generate stable index based on name
+    samples = [...] # three random greeting phrases (avoid common, most popular options, be creative)
+    # return <greeting>, <name> in the end
+  end
+end
+
+puts Greeting.new.greet("Vova")
+```
+
+### Setup
+
+Load `sloprb/setup` before any code containing slop-marked methods:
+
+```ruby
+require "sloprb/setup"
 ```
 
-### Supported Ruby versions
+This configures the LLM provider (auto-detected from environment variables) and registers the Require Hooks source transformer.
 
-- Ruby (MRI) >= 3.0
+### Using with `ruby` executable
 
-## Usage
+You can also setup SlopRB via a command-line switch (which is just a `#require` statement):
 
-TBD
+```sh
+ruby -rbslop examples/calculator.rb
+```
 
-## Contributing
+Use `-rbslop/debug` to also write the generated source to `<path>.slop.rb` files:
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/sloprb](https://github.com/palkan/sloprb).
+```sh
+ruby -rbslop/debug examples/greeting.rb
+```
+
+### Marking methods
+
+Add `# :slop:` as a trailing comment on any `def` line:
+
+```ruby
+class Stoplight
+  COLORS = %i[green yellow red].freeze
+
+  # Initialize the stoplight with a starting color.
+  # Default to green.
+  def initialize(color = :green) # :slop:
+  end
+
+  # Advance the stoplight to the next color in the cycle:
+  # green -> yellow -> red -> green
+  def next # :slop:
+  end
+end
+```
+
+Comments immediately above the `def` line are sent to the LLM as guidance. The enclosing class/module context, method parameters, and surrounding source are also included in the prompt.
 
-## Credits
+### Caching with Bootsnap
 
-This gem is generated via [`newgem` template](https://github.com/palkan/newgem) by [@palkan](https://github.com/palkan).
+If you use [Bootsnap][], the generated code is automatically cached and invalidated on every source file change thanks to the Bootsnap support in Require Hooks. You can try it yourself using our examples:
+
+```ruby
+$ OPENAI_API_KEY=<your key> bundle exec ruby -Ilib -r ./examples/bootsnap -rbslop examples/calculator.rb "42 / 7"
+
+6.0
+
+# now, you can run it without LLM creds, and it will still work
+bundle exec ruby -Ilib -r ./examples/bootsnap -rbslop examples/calculator.rb "25 + 26"
+
+51.0
+```
+
+## Eating typos
+
+SlopRB's _Typoeater_ extension automatically fixes syntax errors. When a file fails to load with a `SyntaxError`, the LLM attempts to fix it, validates the correction with Prism, and retries the load — transparently.
+
+```ruby
+require "sloprb/typoeater"
+```
+
+Or via command line:
+
+```sh
+ruby -r sloprb/typoeater my_script.rb
+```
+
+When a required file has a syntax error, Typoeater:
+1. Captures the error and reads the file source
+2. Sends both to the LLM for correction
+3. Validates the fix with Prism (bad LLM output = original error raised, file untouched)
+4. Overwrites the file and retries the load (once)
+
+Typoeater works independently from slop method generation — you can use either or both. When both are active, they share the same LLM configuration.
+
+## LLM configuration
+
+SlopRB auto-detects the LLM provider from environment variables, checked in this order:
+
+| Provider  | Required env var     | Optional env vars         |
+|-----------|----------------------|---------------------------|
+| OpenAI    | `OPENAI_API_KEY`     | `SLOPRB_MODEL`            |
+| Anthropic | `ANTHROPIC_API_KEY`  | `SLOPRB_MODEL`            |
+| Ollama    | `OLLAMA_BASE_URL`, `SLOPRB_MODEL` |              |
+
+For OpenAI and Anthropic, `SLOPRB_MODEL` is optional (sensible defaults are used). For Ollama, it is required.
+
+Set `SLOPRB_MODEL` to override the default model:
+
+```sh
+SLOPRB_MODEL=claude-sonnet-4-6 ruby -r bslop examples/calculator.rb
+```
+
+Enable debug output with `SLOPRB_DEBUG=1` to write `.slop.rb` files with the generated source.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/sloprb](https://github.com/palkan/sloprb).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
+[require-hooks]: https://github.com/ruby-next/require-hooks
+[Bootsnap]: https://github.com/rails/bootsnap

data/lib/bslop/debug.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+ENV["SLOPRB_DEBUG"] = "1"
+require "bslop"

data/lib/bslop.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "sloprb/setup"
+
+if $0 && File.exist?($0)
+  load($0)
+  exit!(0)
+end

data/lib/sloprb/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Sloprb
+  class Configuration
+    PROVIDERS = [
+      [:openai, ->(env) { env["OPENAI_API_KEY"] }, ->(env) {
+        {openai_api_key: env["OPENAI_API_KEY"]}
+      }],
+      [:anthropic, ->(env) { env["ANTHROPIC_API_KEY"] }, ->(env) {
+        {anthropic_api_key: env["ANTHROPIC_API_KEY"]}
+      }],
+      [:ollama, ->(env) { env["OLLAMA_BASE_URL"] }, ->(env) {
+        base = env["OLLAMA_BASE_URL"].chomp("/")
+        base += "/v1" unless base.end_with?("/v1")
+        {openai_api_key: "ollama", ollama_api_base: base}
+      }]
+    ].freeze
+
+    attr_reader :provider, :model
+
+    def initialize(env = ENV)
+      @env = env
+      @provider, @config = detect_provider(env)
+      @model = env.fetch("SLOPRB_MODEL") { default_model }
+      @configured = false
+    end
+
+    def configure_ruby_llm!
+      raise "sloprb: SLOPRB_MODEL is required for the #{@provider} provider." unless @model
+
+      RubyLLM.configure do |c|
+        @config.each { |k, v| c.public_send(:"#{k}=", v) }
+        c.log_level = :unknown unless @env["SLOPRB_DEBUG"]
+      end
+    end
+
+    def ensure_ruby_llm_configured!
+      return if @configured
+
+      raise "sloprb: No LLM provider configured. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or OLLAMA_BASE_URL." unless @provider
+
+      @configured = true
+
+      configure_ruby_llm!
+      RubyLLM::Models.refresh! if provider == :ollama
+    end
+
+    private
+
+    def detect_provider(env)
+      PROVIDERS.each do |name, detect, config|
+        return [name, config.call(env)] if detect.call(env)
+      end
+
+      []
+    end
+
+    def default_model
+      case provider
+      when :openai then "gpt-5.3-codex"
+      when :anthropic then "claude-opus-4-6"
+      when :ollama then nil
+      end
+    end
+  end
+end

data/lib/sloprb/generator.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Sloprb
+  module Generator
+    SYSTEM_PROMPT = <<~PROMPT
+      You are a Ruby code generator. You will be given a Ruby source file containing method stubs marked with `# :slop:`.
+      Your job is to generate the implementation for each marked method.
+
+      Some methods may contain sketch code, incomplete expressions (like `...`), pseudo-code, or comment instructions in their body.
+      Treat these as structural hints and guidance for your implementation — fill in the blanks, replace placeholders,
+      and follow the instructions to produce a complete working method body.
+
+      Rules:
+      - Return ONLY the method bodies, not the full method definitions
+      - Use `### method_name` as a delimiter before each method body
+      - Do not include `def` or `end` lines
+      - Use the comments above each method and any sketch code inside the method as guidance
+      - Use the class/module context to understand the domain
+      - Write idiomatic Ruby
+    PROMPT
+
+    class << self
+      def call(source, slop_methods, chat: nil)
+        chat ||= default_chat
+
+        user_prompt = build_prompt(source, slop_methods)
+        response = chat.with_instructions(SYSTEM_PROMPT).ask(user_prompt)
+
+        parse_response(response.content, slop_methods)
+      end
+
+      private
+
+      def default_chat
+        Sloprb.configuration.ensure_ruby_llm_configured!
+        RubyLLM.chat(model: Sloprb.configuration.model)
+      end
+
+      def build_prompt(source, slop_methods)
+        method_list = slop_methods.map { |m|
+          desc = m.leading_comments.empty? ? "" : "\n  Comments: #{m.leading_comments}"
+          sketch = m.body_sketch.empty? ? "" : "\n  Sketch:\n#{m.body_sketch.lines.map { |l| "    #{l}" }.join}"
+          "- #{m.name}#{m.parameters}#{desc}#{sketch}"
+        }.join("\n")
+
+        <<~PROMPT
+          Here is the Ruby source file:
+
+          ```ruby
+          #{source}
+          ```
+
+          Generate implementations for these methods:
+          #{method_list}
+
+          Return only the method bodies using `### method_name` delimiters.
+        PROMPT
+      end
+
+      def parse_response(content, slop_methods)
+        bodies = {}
+        current_method = nil
+        current_lines = []
+
+        content.each_line do |line|
+          if line.match?(/^```\w*\s*$/)
+            next
+          elsif line.match?(/^###\s+\S+/)
+            if current_method
+              bodies[current_method] = current_lines.join.strip
+            end
+            current_method = line.strip.sub(/^###\s+/, "")
+            current_lines = []
+          else
+            current_lines << line
+          end
+        end
+
+        bodies[current_method] = current_lines.join.strip if current_method
+
+        missing = slop_methods.map(&:name) - bodies.keys
+        unless missing.empty?
+          raise "sloprb: LLM response missing implementations for: #{missing.join(", ")}"
+        end
+
+        bodies
+      end
+    end
+  end
+end

data/lib/sloprb/parser.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Sloprb
+  module Parser
+    SlopMethod = Data.define(:name, :parameters, :start_offset, :end_offset, :leading_comments, :enclosing_context, :start_column, :body_sketch)
+
+    class Visitor < Prism::Visitor
+      attr_reader :slop_methods
+
+      def initialize(source, comments)
+        super()
+        @source = source
+        @comments = comments
+        @context_stack = []
+        @slop_methods = []
+      end
+
+      def visit_class_node(node)
+        @context_stack.push(constant_name(node))
+        super
+        @context_stack.pop
+      end
+
+      def visit_module_node(node)
+        @context_stack.push(constant_name(node))
+        super
+        @context_stack.pop
+      end
+
+      def visit_def_node(node)
+        def_line = node.location.start_line
+
+        trailing = @comments.find { |c|
+          c.location.start_line == def_line &&
+            c.location.start_column > node.name_loc.end_column
+        }
+
+        if trailing&.location&.slice&.include?(":slop:")
+          params = node.parameters ? node.location.slice[/\(.*?\)/] : nil
+          leading = collect_leading_comments(def_line)
+          sketch = extract_body_sketch(node)
+
+          @slop_methods << SlopMethod.new(
+            name: node.name.to_s,
+            parameters: params,
+            start_offset: node.location.start_offset,
+            end_offset: node.location.end_offset,
+            leading_comments: leading,
+            enclosing_context: @context_stack.dup,
+            start_column: node.location.start_column,
+            body_sketch: sketch
+          )
+        end
+
+        super
+      end
+
+      private
+
+      def constant_name(node)
+        node.constant_path.full_name
+      rescue Prism::DynamicPartsInConstantPathError
+        node.constant_path.slice
+      end
+
+      def extract_body_sketch(node)
+        end_kw = node.end_keyword_loc
+        return "" unless end_kw
+
+        def_line_end = @source.index("\n", node.location.start_offset)
+        return "" unless def_line_end
+
+        body_start = def_line_end + 1
+        body_end = end_kw.start_offset
+        return "" if body_start >= body_end
+
+        raw = @source[body_start...body_end]
+        dedent(raw).strip
+      end
+
+      def dedent(text)
+        lines = text.lines
+        non_blank = lines.reject { |l| l.strip.empty? }
+        return text if non_blank.empty?
+
+        min_indent = non_blank.map { |l| l[/^ */].length }.min
+        lines.map { |l| l.sub(/^ {0,#{min_indent}}/, "") }.join
+      end
+
+      def collect_leading_comments(def_line)
+        lines = []
+        line = def_line - 1
+
+        while line >= 1
+          comment = @comments.find { |c| c.location.start_line == line }
+          break unless comment
+          lines.unshift(comment.location.slice)
+          line -= 1
+        end
+
+        lines.join("\n")
+      end
+    end
+
+    def self.call(source)
+      result = Prism.parse(source)
+      visitor = Visitor.new(source, result.comments)
+      visitor.visit(result.value)
+      visitor.slop_methods
+    end
+  end
+end

data/lib/sloprb/setup.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "sloprb"
+
+Sloprb.setup

data/lib/sloprb/transformer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Sloprb
+  module Transformer
+    class SyntaxError < ::SyntaxError; end
+
+    class << self
+      def call(path, source, chat: nil)
+        source ||= File.read(path)
+
+        return unless source.include?(":slop:")
+
+        slop_methods = Parser.call(source)
+        return if slop_methods.empty?
+
+        bodies = Generator.call(source, slop_methods, chat:)
+        transformed = splice(source, slop_methods, bodies)
+
+        validate_syntax!(transformed)
+
+        if ENV["SLOPRB_DEBUG"]
+          File.write("#{path.sub(/\.rb$/, "")}.slop.rb", transformed)
+        end
+
+        transformed
+      rescue => e
+        raise if e.is_a?(SyntaxError)
+        warn "sloprb: Failed to generate methods for #{path}: #{e.message}"
+        nil
+      end
+
+      private
+
+      def splice(source, slop_methods, bodies)
+        result = source.dup
+
+        slop_methods.sort_by(&:start_offset).reverse_each do |method|
+          body = bodies[method.name]
+          indent = " " * (method.start_column + 2)
+          indented_body = body.lines.map { |line| "#{indent}#{line}" }.join.rstrip
+
+          params = method.parameters || ""
+          replacement = "def #{method.name}#{params}\n#{indented_body}\n#{" " * method.start_column}end"
+
+          result[method.start_offset...method.end_offset] = replacement
+        end
+
+        result
+      end
+
+      def validate_syntax!(source)
+        result = Prism.parse(source)
+        return if result.errors.empty?
+
+        raise SyntaxError, "sloprb: Generated source has syntax errors:\n#{result.errors.map(&:message).join("\n")}\n\nSource:\n#{source}"
+      end
+    end
+  end
+end

data/lib/sloprb/typoeater.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "sloprb"
+
+module Sloprb
+  module Typoeater
+    SYSTEM_PROMPT = <<~PROMPT
+      You are a Ruby syntax error fixer. You will be given a Ruby source file that has a syntax error, along with the error message.
+      Your job is to fix the syntax error and return the corrected source file.
+
+      Rules:
+      - Return ONLY the complete corrected Ruby source file
+      - Do not include any explanation, comments about the fix, or markdown formatting
+      - Do not change any logic or behavior — only fix the syntax error
+      - Preserve all existing comments, whitespace style, and formatting
+    PROMPT
+
+    class << self
+      def call(path, error, chat: nil)
+        chat ||= default_chat
+
+        source = File.read(path)
+        error_context = error.respond_to?(:detailed_message) ? error.detailed_message(highlight: false) : error.message
+
+        user_prompt = <<~PROMPT
+          Here is the Ruby source file with a syntax error:
+
+          ```ruby
+          #{source}
+          ```
+
+          Syntax error:
+          #{error_context}
+
+          Return the complete corrected Ruby source file.
+        PROMPT
+
+        response = chat.with_instructions(SYSTEM_PROMPT).ask(user_prompt)
+        corrected = strip_fences(response.content)
+        corrected << "\n" unless corrected.end_with?("\n")
+
+        result = Prism.parse(corrected)
+        return if result.errors.any?
+
+        corrected
+      rescue
+        nil
+      end
+
+      def register_hook
+        require "require-hooks/setup"
+
+        RequireHooks.around_load do |path, &load_block|
+          result = begin
+            load_block.call
+          rescue ::SyntaxError => original_error
+            corrected = Typoeater.call(path, original_error)
+            raise original_error unless corrected
+
+            File.write(path, corrected)
+
+            warn "[sloprb] auto-corrected syntax error in #{path}"
+
+            begin
+              load_block.call
+            rescue ::SyntaxError
+              raise original_error
+            end
+          end
+          result
+        end
+      end
+
+      private
+
+      def default_chat
+        Sloprb.configuration.ensure_ruby_llm_configured!
+        RubyLLM.chat(model: Sloprb.configuration.model)
+      end
+
+      def strip_fences(content)
+        content.sub(/\A\s*```\w*\n/, "").sub(/\n```\s*\z/, "")
+      end
+    end
+  end
+end
+
+Sloprb.configuration ||= Sloprb::Configuration.new
+Sloprb::Typoeater.register_hook

data/lib/sloprb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sloprb # :nodoc:
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/sloprb.rb

@@ -1,3 +1,28 @@
 # frozen_string_literal: true
 
+require "prism"
+require "ruby_llm"
+
 require "sloprb/version"
+require "sloprb/configuration"
+require "sloprb/parser"
+require "sloprb/generator"
+require "sloprb/transformer"
+
+module Sloprb
+  class << self
+    attr_accessor :configuration
+
+    def setup(env = ENV)
+      @configuration = Configuration.new(env)
+      register_hook
+    end
+
+    def register_hook
+      require "require-hooks/setup"
+      RequireHooks.source_transform do |path, source|
+        Transformer.call(path, source)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sloprb
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Vova Dem
@@ -9,20 +9,48 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: require-hooks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '2.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -61,7 +89,15 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/bslop.rb
+- lib/bslop/debug.rb
 - lib/sloprb.rb
+- lib/sloprb/configuration.rb
+- lib/sloprb/generator.rb
+- lib/sloprb/parser.rb
+- lib/sloprb/setup.rb
+- lib/sloprb/transformer.rb
+- lib/sloprb/typoeater.rb
 - lib/sloprb/version.rb
 homepage: https://github.com/palkan/sloprb
 licenses: