Skip to content
@kettle-rb

kettle-rb

Tools that simplify development & testing in Ruby
README.md

kettle-rb

A collection of freeze-dried and vacuum-sealed Yak shavings for Ruby development & testing.

AST Merging and Templating Gems

The *-merge Gem Family

The *-merge gem family provides intelligent, AST-based merging for various file formats. At the foundation is tree_haver, which provides a unified cross-Ruby parsing API that works seamlessly across MRI, JRuby, and TruffleRuby.

Gem Version CI Language
/ Format		 Parser Backend(s) Description
tree_haver Version Version Multi MRI C, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus, Parslet Foundation: Cross-Ruby adapter for parsing libraries (like Faraday for HTTP)
ast-merge Version Version Text internal Infrastructure: Shared base classes and merge logic for all *-merge gems
bash-merge Version Version Bash tree-sitter-bash (via tree_haver) Smart merge for Bash scripts
commonmarker-merge Version Version Markdown Commonmarker (via tree_haver) Smart merge for Markdown (CommonMark via comrak Rust)
dotenv-merge Version Version Dotenv internal Smart merge for .env files
json-merge Version Version JSON tree-sitter-json (via tree_haver) Smart merge for JSON files
jsonc-merge Version Version JSONC tree-sitter-jsonc (via tree_haver) ⚠️ Proof of concept; Smart merge for JSON with Comments
markdown-merge Version Version Markdown Commonmarker / Markly (via tree_haver) Foundation: Shared base for Markdown mergers with inner code block merging
markly-merge Version Version Markdown Markly (via tree_haver) Smart merge for Markdown (CommonMark via cmark-gfm C)
prism-merge Version Version Ruby Prism (prism std lib gem) Smart merge for Ruby source files
psych-merge Version Version YAML Psych (psych std lib gem) Smart merge for YAML files
rbs-merge Version Version RBS tree-sitter-bash (via tree_haver), RBS (rbs std lib gem) Smart merge for Ruby type signatures
toml-merge Version Version TOML Parslet + toml, Citrus + toml-rb, tree-sitter-toml (all via tree_haver) Smart merge for TOML files

Backend Platform Compatibility

tree_haver supports multiple parsing backends, but not all backends work on all Ruby platforms:

Platform 👉️
TreeHaver Backend 👇️		 MRI JRuby TruffleRuby Notes
MRI (ruby_tree_sitter) ✅ ❌ ❌ C extension, MRI only
Rust (tree_stump) ✅ ❌ ❌ Rust extension via magnus/rb-sys, MRI only
FFI ✅ ✅ ❌ TruffleRuby's FFI doesn't support STRUCT_BY_VALUE
Java (jtreesitter) ❌ ✅ ❌ JRuby only, requires grammar JARs
Prism ✅ ✅ ✅ Ruby parsing, stdlib in Ruby 3.4+
Psych ✅ ✅ ✅ YAML parsing, stdlib
Citrus ✅ ✅ ✅ Pure Ruby PEG parser, no native dependencies
Parslet ✅ ✅ ✅ Pure Ruby PEG parser, no native dependencies
Commonmarker ✅ ❌ ❓ Rust extension for Markdown
Markly ✅ ❌ ❓ C extension for Markdown

Legend: ✅ = Works, ❌ = Does not work, ❓ = Untested

Why some backends don't work on certain platforms:

  • JRuby: Runs on the JVM; cannot load native C/Rust extensions (.so files)
  • TruffleRuby: Has C API emulation via Sulong/LLVM, but it doesn't expose all MRI internals that native extensions require (e.g., RBasic.flags, rb_gc_writebarrier)
  • FFI on TruffleRuby: TruffleRuby's FFI implementation doesn't support returning structs by value, which tree-sitter's C API requires

Example implementations for the gem templating use case:

Gem Purpose Description
kettle-dev Gem Development Gem templating tool using *-merge gems
kettle-jem Gem Templating Gem template library with smart merge support

Example implementations for the gem templating use case:

Gem Purpose Description
kettle-jem Gem Templating Gem template library with smart merge support

Dev Harness

Gem Purpose Description
kettle-dev Gem Development Complete rake & dev harness for Ruby development; tasks for coverage, GHA console, linting, debugging, etc.

Test Harness

Gem Purpose Description
kettle-test Spec Development Complete RSpec test harness, temporal manipulation, silent output testing, block expectations, etc.
kettle-soup-cover Test Coverage Harness A Covered Kettle of SOUP. Configure SimpleCov in 4 LOC for every CI platform, w/ 12-factor ENV-based controls

Ruby Utilities

Gem Purpose Description
kettle-wash Spec Development Coming soon! Runner up name: "constant_change". Provides a pattern for resetting constants for consistent deterministic results.

Pinned Loading

  1. kettle-soup-cover kettle-soup-cover Public

    🥘 A Covered Kettle of SOUP, A Code Coverage Meta Gem

    Ruby 10 1

  2. kettle-dev kettle-dev Public

    🍲 Setup a complete rake & dev harness for Ruby development; tasks for coverage, GHA console, linting, debugging, etc.

    Ruby 2 1

  3. kettle-test kettle-test Public

    🍲 Setup a complete RSpec test harness, temporal manipulation, silent output testing, block expectations, etc.

    Ruby 1

  4. prism-merge prism-merge Public

    ☯️ Intelligently merges two versions of a Ruby file using Prism AST analysis. It's like a smart "git merge" specifically designed for Ruby code.

    Ruby 17

Repositories

Showing 10 of 22 repositories
  • jsonc-merge Public

    ☯️ Jsonc::Merge provides smart JSONC (JSON with Comments) file merging that preserves comments, understands JSON structure, and supports freeze blocks for protecting destination content. Perfect for merging configuration files like devcontainer.json, tsconfig.json, package.json, and VS Code settings.

    kettle-rb/jsonc-merge’s past year of commit activity
    Ruby 0 MIT 0 0 0 Updated Jan 12, 2026
  • json-merge Public

    ☯️ Json::Merge provides smart JSON file merging that understands JSON structure. Perfect for merging strict JSON configuration files like package.json, tsconfig.json (without comments), and other standard JSON files. For JSON with Comments (JSONC) files like devcontainer.json and VS Code settings, use jsonc-merge.

    kettle-rb/json-merge’s past year of commit activity
    Ruby 0 MIT 0 0 0 Updated Jan 12, 2026
  • bash-merge Public

    ☯️ Bash::Merge provides smart Bash script merging that preserves comments, understands shell structure, and supports freeze blocks for protecting destination content. Perfect for merging configuration scripts and shell templates with customized destination files.

    kettle-rb/bash-merge’s past year of commit activity
    Ruby 1 MIT 0 0 0 Updated Jan 12, 2026
  • ast-merge Public

    ☯️ A TreeHaver-based merge/templating tool, Ast::Merge provides base classes, modules, and RSpec shared examples for building intelligent file mergers using AST analysis. Works with all Ruby platforms, and all language grammars, yes, including those.

    kettle-rb/ast-merge’s past year of commit activity
    Ruby 3 MIT 0 0 0 Updated Jan 12, 2026
  • tree_haver Public

    🌴 TreeHaver is a cross-Ruby adapter for many AST parsing libraries; supporting MRI Ruby, JRuby, & TruffleRuby. Provides unified parsing API & AST when using ruby_tree_sitter, parslet, citrus, ffi, tree_stump (Rust), JRuby JARs, etc. As Faraday is to HTTP clients, this is for ASTs: "Learn once & write once & run anywhere"

    kettle-rb/tree_haver’s past year of commit activity
    Ruby 15 MIT 0 0 0 Updated Jan 12, 2026
  • .github Public

    A collection of frozen Yak shavings for Ruby development & testing.

    kettle-rb/.github’s past year of commit activity
    0 MIT 0 0 0 Updated Jan 12, 2026
  • dotenv-merge Public

    ☯️ Dotenv::Merge provides smart .env file merging that preserves comments, understands variable assignments, and supports freeze blocks for protecting sensitive configuration. Perfect for merging environment templates with local overrides.

    kettle-rb/dotenv-merge’s past year of commit activity
    Ruby 0 MIT 0 0 1 Updated Jan 12, 2026
  • toml-merge Public

    ☯️ Intelligently merges TOML files by analyzing their AST structure with tree-sitter, preserving key organization and resolving conflicts based on structural similarity.

    kettle-rb/toml-merge’s past year of commit activity
    Ruby 1 MIT 0 0 0 Updated Jan 9, 2026
  • rbs-merge Public

    ☯️ Intelligently merge RBS type signature files by parsing and comparing AST structures. Supports freeze blocks to protect customizations, signature-based matching, and configurable merge strategies.

    kettle-rb/rbs-merge’s past year of commit activity
    Ruby 0 MIT 0 0 1 Updated Jan 8, 2026
  • ts-grammar-action Public

    📦️ GHA: Install tree sitter, language grammars, rust, java, and al the fiddly bits like ENV variables

    kettle-rb/ts-grammar-action’s past year of commit activity
    1 MIT 0 0 0 Updated Jan 7, 2026
View all repositories

Top languages

Loading…

Most used topics

Loading…