ryac 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2bddb3f3efea0d09081975f55f29c156ef437180470e5dc08ef30046dd19b995
+  data.tar.gz: 062e95d78fa295320ef0ea800d01aa3dff509e9f2c20b341781a06e9ed60671e
+SHA512:
+  metadata.gz: 308731a116d5765d712d85be56b819821345847b21cdb1feb591a34071c865f0073addb6e36de31d21c117138e74b6967068fb1e4e5d897176b4a4edff44d5f6
+  data.tar.gz: bcd1419c8b24b9f718e20a0b529636b265ecf531689d0468920f101d10f82e10e5019da28ac183a31fe5fa8c072cbd2f00ff1e9f78b5525b916009adf971ad42

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ahogappa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# ryac
+
+**ryac** — minify the word *ruby* and you are left with *ry*; this tool then analyzes and compacts, so: **R**ub**y**, **A**nalyzed & **C**ompacted. Pronounced *ryaku*, like 略 — the Japanese word for "abbreviation".
+
+A Ruby code minifier that uses [TypeProf](https://github.com/ruby/typeprof) for type-aware analysis and AST-based transformations to achieve high compression rates while preserving functional equivalence.
+
+## Philosophy
+
+This project takes an **aggressive optimization** approach. In Ruby, even comment removal requires context awareness — for example, `foo\n# comment\n.to_s` works because the comment connects the method chain, but removing it causes a syntax error. Whether a given comment is safe to remove depends entirely on context, making the boundary between safe and unsafe transformations inherently blurry. Since conservative minification is already difficult in Ruby, we choose to optimize as aggressively as possible. TypeProf's type analysis helps make these transformations more informed, but the goal is always maximum compression.
+
+## Features
+
+- **Multi-file support**: Follows `require_relative` and `autoload` to collect and concatenate dependencies into a single output
+- **Whitespace & comment removal**: Strips all unnecessary whitespace and comments
+- **AST transformations**: Boolean/char shortening, constant folding, control flow simplification, endless methods, parenthesis optimization
+- **Constant aliasing**: Renames user-defined constants and shortens repeated external constant paths
+- **Variable renaming**: Shortens local variables, keyword arguments, instance/class/global variables
+- **Method renaming**: Shortens method names with `send(:sym)` coordination and attr-backed ivar optimization
+- **Method alias shortening**: Replaces long stdlib method names with shorter aliases (e.g., `collect` → `map`)
+- **Dead code elimination**: Removes unreachable code after `return`, `break`, `next`, `raise`
+- **Dynamic code detection**: Disables renaming in scopes containing `eval`, `binding`, `send`, etc.
+
+## Installation
+
+```ruby
+gem 'ryac'
+```
+
+## Usage
+
+### Command Line
+
+```bash
+# Minify a file (follows require_relative automatically)
+bin/ryac path/to/entry.rb
+
+# Specify compression level (stable or unstable)
+bin/ryac path/to/entry.rb -c stable
+bin/ryac path/to/entry.rb -c unstable
+
+# Write to output file
+bin/ryac path/to/entry.rb -o minified.rb
+
+# Write constant aliases to a separate file
+bin/ryac path/to/entry.rb -o minified.rb -a aliases.rb
+
+# Multiple entry points
+bin/ryac file1.rb file2.rb
+
+# Minify installed gem(s) by name (resolved via Gem::Specification)
+bin/ryac -g rack
+bin/ryac -g rack,rack-session -o bundle.rb
+
+# Show version / help
+bin/ryac -v
+bin/ryac -h
+```
+
+### Ruby API
+
+```ruby
+require 'ryac'
+
+minifier = Ryac::Minifier.new
+result = minifier.call('path/to/entry.rb')
+
+puts result.content           # minified code
+puts result.preamble          # external prefix declarations (e.g., "A=TypeProf::Core::AST")
+puts result.aliases           # backward-compat alias declarations (e.g., "MyClass=A")
+puts result.stats.file_count  # number of files processed
+puts result.stats.compression_ratio  # e.g., 0.44 (56% reduction)
+
+# Specify optimization level (:stable or :unstable, default: :stable)
+result = minifier.call('path/to/entry.rb', level: :unstable)
+```
+
+## Optimization Levels
+
+There are exactly two levels, named for their promise. The default is **`stable`**.
+
+| Level | Transformations | Promise |
+|-------|----------------|---------|
+| `stable` | AST compaction and folding, constant/class/module renaming with compatibility aliases, external prefix aliasing, local/keyword/instance/class/global variable renaming | Verified frame-for-frame on a real program (Optcarrot). Sound under closed-world analysis; reflection over *names the program renames* is the caveat. |
+| `unstable` | + Method renaming, attr-backed ivar coordination | A program can defeat method renaming by construction (names inside strings, `eval`'d source, `send(computed)`), so this works only when the program plays along. Verified by self-hosting. |
+
+Finer configurations are not levels: the pipeline is built from steps, and callers can pass an explicit stage list in place of a level name (`Minifier#call(path, level: [...stage defs...])`). The unit tests pin each step's behavior through exactly that mechanism.
+
+See [`tests/ryac/pipeline/`](tests/ryac/pipeline/) for per-stage transformation examples, and [`tests/ryac/levels/`](tests/ryac/levels/) for end-to-end compression examples.
+
+### What the levels are verified against
+
+The supported boundary is defined by two programs, both verified in CI:
+
+- **[Optcarrot](https://github.com/mame/optcarrot) at `stable`** — the minified emulator matches the original frame-for-frame across the 180-frame demo and three scripted play scenarios (1,820 frames of title menus, piece rotation, pausing and button mashing) ([`tests/test_optcarrot.rb`](tests/test_optcarrot.rb))
+- **This minifier itself at `unstable`** — the minified minifier re-minifies the original source to identical output, and minifying its own output is a byte-identical fixed point ([`tests/test_integration.rb`](tests/test_integration.rb))
+
+Whether `unstable` holds for a given program depends on the program. Optcarrot stops at `stable` because it defeats method renaming by construction: it builds its CPU/PPU cores as source strings and `eval`s them, scans that text for `@ivar` names with a regexp, and dispatches through `send(computed_symbol)` — method names survive inside strings, out of reach of static analysis. The sinatra and rubocop suites run in CI as regression canaries on a keyword-only step composition, but they sit outside this boundary and do not define it.
+
+## Development
+
+```bash
+bundle install
+
+# Run tests (fast, excludes self-hosting)
+rake test
+
+# Run all tests including self-hosting
+rake test:all
+
+# Run self-hosting test only
+rake test:integration
+
+# Run gem integration tests (minifies real gems and runs their test suites)
+rake test:gems
+
+# Minify optcarrot at :stable and compare rendered frames against the original
+# (requires gem_tests/optcarrot: git clone https://github.com/mame/optcarrot gem_tests/optcarrot)
+rake test:optcarrot
+
+# Show compression ratio on self-hosting
+rake benchmark
+```
+
+## Architecture
+
+The minification pipeline:
+
+```
+FileCollector → Concatenator → StageRunner (Compactor → stage list) → Output
+```
+
+1. **FileCollector** — Resolves `require_relative` / `autoload` and collects all source files into a dependency graph
+2. **Concatenator** — Topologically sorts files and concatenates them into a single source
+3. **StageRunner** — Compacts the source (AST rebuilt into minimal whitespace form), then walks the level's ordered stage list. Every stage implements one contract — `needs_analysis?` / `fixpoint?` / `collect(ctx, patches)` / `finish(ctx)` — and phase is list position:
+   - **Syntactic stages** (no analysis): `ControlFlowSimplify`, `EndlessMethod`, `ConstantFold`, `BooleanShorten`, `CharShorten` before the rename batch; `ParenOptimizer` after it
+   - **Analysis stages**: `ConstantAliaser`, `AttrDeclShorten`, `VariableRenamer` (plus `MethodRenamer` at `unstable`) — consecutive analysis stages form one batch sharing a single TypeProf pass, and the runner rejects a list that would need two
+
+## Dependencies
+
+- [TypeProf](https://github.com/ruby/typeprof) - Type-aware AST analysis
+- [Prism](https://github.com/ruby/prism) - Syntax validation
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib"
+  t.test_files = FileList["tests/**/test_*.rb"].exclude("tests/test_integration.rb", "tests/test_fixtures.rb", "tests/test_gem_minification.rb", "tests/test_optcarrot.rb", "tests/_archive/**/*")
+end
+
+Rake::TestTask.new("test:all") do |t|
+  t.libs << "lib"
+  t.test_files = FileList["tests/**/test_*.rb"].exclude("tests/test_fixtures.rb", "tests/test_gem_minification.rb", "tests/test_optcarrot.rb", "tests/_archive/**/*")
+end
+
+Rake::TestTask.new("test:integration") do |t|
+  t.libs << "lib"
+  t.test_files = FileList["tests/test_integration.rb"]
+end
+
+Rake::TestTask.new("test:gems") do |t|
+  t.libs << "lib"
+  t.test_files = FileList["tests/test_gem_minification.rb"]
+end
+
+desc "Minify optcarrot at the supported level and compare rendered frames"
+Rake::TestTask.new("test:optcarrot") do |t|
+  t.libs << "lib"
+  t.test_files = FileList["tests/test_optcarrot.rb"]
+end
+
+desc "Show self-hosting compression ratio"
+task :benchmark do
+  $LOAD_PATH.unshift File.expand_path("lib", __dir__)
+  require "ryac"
+
+  entry_path = File.join(__dir__, "lib", "ryac.rb")
+  minifier = Ryac::Minifier.new
+  result = minifier.call(entry_path)
+  stats = result.stats
+  compression = ((1 - stats.compression_ratio) * 100).round(1)
+  puts "#{stats.file_count} files: #{stats.original_size} -> #{stats.minified_size} bytes (#{compression}% reduction)"
+end
+
+task default: :test

data/Steepfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  collection_config "rbs_collection.yaml"
+end

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ryac"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/ryac

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative '../lib/ryac'
+
+options = {
+  output: nil,
+  aliases: nil,
+  level: nil,
+  gems: nil
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: minify [options] [FILE...]"
+
+  opts.on("-o", "--output FILE", "Write output to FILE instead of stdout") do |file|
+    options[:output] = file
+  end
+
+  opts.on("-a", "--aliases FILE", "Write constant alias declarations to FILE") do |file|
+    options[:aliases] = file
+  end
+
+  opts.on("-g", "--gem GEM_NAMES", "Minify installed gem(s) by name (comma-separated)") do |names|
+    options[:gems] = names.split(',').map(&:strip).reject(&:empty?)
+  end
+
+  opts.on("-c", "--compress LEVEL", "Set compression level (stable or unstable)") do |value|
+    begin
+      options[:level] = Ryac::Minifier.resolve_level(value)
+    rescue ArgumentError => e
+      warn "Error: #{e.message}"
+      warn opts
+      exit 1
+    end
+  end
+
+  opts.on("-h", "--help", "Display this help message") do
+    puts opts
+    exit 0
+  end
+
+  opts.on("-v", "--version", "Display version") do
+    puts "ryac version #{Ryac::VERSION}"
+    exit 0
+  end
+end
+
+begin
+  parser.parse!
+rescue OptionParser::InvalidOption => e
+  warn "Error: #{e.message}"
+  warn parser
+  exit 1
+end
+
+if options[:gems]
+  unless ARGV.empty?
+    warn "Error: Cannot specify both --gem and file arguments"
+    exit 1
+  end
+
+  if options[:gems].empty?
+    warn "Error: No gem names specified"
+    exit 1
+  end
+
+  begin
+    gem_args = Ryac::GemResolver.minifier_args(options[:gems])
+    entry = gem_args[:entry]
+    project_root = gem_args[:project_root]
+    gem_require_paths = gem_args[:gem_require_paths]
+  rescue Ryac::Pipeline::GemNotFoundError => e
+    warn "Error: #{e.message}"
+    exit 1
+  end
+else
+  if ARGV.empty?
+    warn "Error: No entry file specified"
+    warn parser
+    exit 1
+  end
+
+  ARGV.each do |file|
+    unless File.exist?(file)
+      warn "Error: File not found: #{file}"
+      exit 1
+    end
+  end
+
+  entry = ARGV.size == 1 ? ARGV[0] : ARGV.dup
+  project_root = nil
+  gem_require_paths = []
+end
+
+gem_names = options[:gems] || []
+
+begin
+  minifier = Ryac::Minifier.new
+  level_opts = options[:level] ? { level: options[:level] } : {}
+  result = minifier.call(entry, **level_opts, project_root: project_root, gem_names: gem_names, gem_require_paths: gem_require_paths)
+
+  content = if options[:aliases]
+    File.write(options[:aliases], result.aliases)
+    result.content
+  else
+    result.full_content
+  end
+
+  if options[:output]
+    File.write(options[:output], content)
+  else
+    puts content
+  end
+
+  warn "Compression: #{((1 - result.stats.compression_ratio) * 100).round(1)}%"
+  warn "Files processed: #{result.stats.file_count}"
+rescue Ryac::SyntaxError => e
+  warn "Error: the input does not parse"
+  warn "  #{e.message}"
+  exit 2
+rescue Ryac::InputError => e
+  warn "Error: #{e.message}"
+  exit 2
+rescue Ryac::InternalError => e
+  warn "Error: this is a bug in ryac, not in your program — please report it"
+  warn "  #{e.message}"
+  exit 3
+rescue => e
+  warn "Error: this is a bug in ryac, not in your program — please report it"
+  warn "  #{e.class}: #{e.message}"
+  exit 3
+end

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here