ryac 0.2.0 → 0.3.0

data/lib/ryac/analysis/local_scopes.rb

@@ -42,6 +42,8 @@ module Ryac
       @program = program_node
       @scopes = []
       @scope_by_node = {}
+      @children = {}
+      @constraints = {}
       build(program_node)
     end
 
@@ -86,6 +88,26 @@ module Ryac
       end
     end
 
+    # {scope_id => post-rename local names visible inside that scope}: its own
+    # locals plus those of enclosing scopes, looking through block and lambda
+    # boundaries the way variable lookup does. Locals a scope keeps (never
+    # renamed, or already short) count the same as renamed ones — a bare call
+    # whose new name matches any visible local parses as that local, not the
+    # method, so collision guards must see the full set.
+    def visible_local_names
+      @scopes.to_h do |scope|
+        names = Set.new #: Set[String]
+        current = scope #: Scope?
+        while current
+          mapping = current.mapping || {}
+          current.node.locals.each { |var| names << (mapping[var] || var.to_s) }
+          break unless %i[block lambda].include?(current.kind)
+          current = current.parent
+        end
+        [scope.id, names]
+      end
+    end
+
     # Phase 3 outputs.
     attr_reader :rename_entries, :def_param_names, :block_param_names, :for_index_names
 
@@ -112,6 +134,7 @@ module Ryac
                         parent: parent, owner_call: owner_call, mapping: nil)
       @scopes << scope
       @scope_by_node[node.object_id] = scope
+      (@children[parent.object_id] ||= []) << scope if parent
       scope
     end
 
@@ -167,9 +190,8 @@ module Ryac
       locals = scope.node.locals
       return unless locals.any?
 
-      # A :top scope's node is always a ProgramNode, which has #statements.
-      unsafe, pinned = scope_constraints(scope.node.statements) # steep:ignore NoMethod
-      generator = NameGenerator.new(pinned.map(&:to_s))
+      unsafe, pinned = constraints_for(scope)
+      generator = NameGenerator.new(pinned.map(&:to_s) + reserved_names(scope))
       mapping = {} #: Hash[Symbol, String]
       locals.each do |var|
         mapping[var] = allocated_name(var, unsafe, pinned, generator)
@@ -182,7 +204,7 @@ module Ryac
       node = scope.node #: Prism::DefNode
       return unless node.body
 
-      unsafe, pinned = scope_constraints(node.body)
+      unsafe, pinned = constraints_for(scope)
       keyword_params = keyword_param_names(node)
       unused_rescue = unused_rescue_vars(node.body)
       kw_mapping = kw_def_map[scope.id]
@@ -193,10 +215,16 @@ module Ryac
       # point: re-minifying the output (where the hinting call already writes
       # short keywords, so no hint arises) would allocate the burned names.
       hints = hints.reject { |var, _| keyword_params.include?(var) }
+      # An unused rescue variable is left as written, and so is every name
+      # reserved_names lists; a hint or an allocation landing on one of them
+      # would bind two variables to one name.
+      kept = unused_rescue.map(&:to_s) + reserved_names(scope)
+      hints = hints.reject { |_, name| kept.include?(name) }
 
       reserved = hints.values.dup
       reserved.concat(kw_mapping.values) if kw_mapping
       reserved.concat(pinned.map(&:to_s))
+      reserved.concat(kept)
       keyword_names = {} #: Hash[Symbol, String]
       keyword_params.each do |kw|
         keyword_names[kw] = kw_mapping&.[](kw) || kw.to_s
@@ -230,9 +258,9 @@ module Ryac
       node = scope.node #: Prism::BlockNode
       return unless node.body
 
-      unsafe, pinned = scope_constraints(node.body)
+      unsafe, pinned = constraints_for(scope)
       f_args = block_formal_names(node)
-      parent_names = ancestor_mapping_values(scope)
+      parent_names = ancestor_visible_names(scope) + reserved_names(scope)
       reserved = parent_names + pinned.map(&:to_s)
 
       if !unsafe && use_numbered_params?(node, f_args, parent_names)
@@ -280,22 +308,92 @@ module Ryac
       scope.mapping = mapping
     end
 
-    # Names a block avoids: every allocated ancestor's, all the way to the
-    # top. Visibility actually ends at the first def boundary, so anything
-    # beyond it is over-reservation — but the allocation order downstream is
-    # built around this exact set, and narrowing it reshuffles names without
-    # making any of them safer.
-    def ancestor_mapping_values(scope)
+    # The names a scope's allocation must not hand out on account of what
+    # the scope itself and the blocks and lambdas nested in it keep as
+    # written. A block's body locals and a lambda's names are never renamed,
+    # and Ruby resolves them by spelling: an outer name allocated onto one
+    # of them turns the inner assignment into a write to the outer variable
+    # (optcarrot's palette — `|rf, gf, bf|` renamed to `|a, b, c|` over an
+    # inner `b = ...`). A block adds ancestor_visible_names on top.
+    def reserved_names(scope)
+      kept_local_names(scope) + descendant_kept_names(scope)
+    end
+
+    # What a block sees from outside: every allocated ancestor's names, all
+    # the way to the top — visibility actually ends at the first def
+    # boundary, so anything beyond it is over-reservation, but the
+    # allocation order downstream is built around this exact set, and
+    # narrowing it reshuffles names without making any of them safer — plus
+    # the kept locals of the blocks and lambdas up to that boundary. A
+    # parameter allocated onto one of those would shadow what its body
+    # still reads.
+    def ancestor_visible_names(scope)
       names = [] #: Array[String]
+      visible = true
       current = scope.parent
       while current
         # allocated? guarantees mapping is non-nil here.
         names.concat(current.mapping.values) if current.allocated? # steep:ignore NoMethod
+        names.concat(kept_local_names(current)) if visible
+        visible &&= %i[block lambda].include?(current.kind)
         current = current.parent
       end
       names
     end
 
+    # Kept names of every block and lambda nested in the scope, as far as
+    # variable lookup reaches: a def or class boundary ends the descent.
+    def descendant_kept_names(scope)
+      names = [] #: Array[String]
+      stack = (@children[scope.object_id] || []).dup
+      until stack.empty?
+        child = stack.pop #: Scope
+        next unless %i[block lambda].include?(child.kind)
+
+        names.concat(kept_local_names(child))
+        stack.concat(@children[child.object_id] || [])
+      end
+      names
+    end
+
+    # The locals a scope leaves as written: a block renames only its
+    # parameters — its body locals, and the parameters it pins or leaves
+    # under eval, stay — and a lambda renames nothing.
+    def kept_local_names(scope)
+      node = scope.node
+      case scope.kind
+      when :block
+        unsafe, pinned = constraints_for(scope)
+        return node.locals.map(&:to_s) if unsafe
+
+        # @type var node: Prism::BlockNode
+        renamed = renamed_block_param_names(node)
+        node.locals.filter_map { |var| var.to_s if pinned.include?(var) || !renamed.include?(var) }
+      when :lambda
+        node.locals.map(&:to_s)
+      else
+        []
+      end
+    end
+
+    def renamed_block_param_names(node)
+      names = block_formal_names(node).compact.reject { |p| p.to_s.match?(/\A_\d*\z/) }
+      block_multi_targets(node).each { |mt| names.concat(collect_multi_target_names(mt)) }
+      params = block_parameters(node)
+      names.concat(collect_extra_block_param_names(params)) if params
+      names.to_set
+    end
+
+    # scope_constraints, once per scope: reserved_names asks about every
+    # nested block repeatedly.
+    def constraints_for(scope)
+      @constraints[scope.id] ||= begin
+        node = scope.node
+        body = node.is_a?(Prism::ProgramNode) ? node.statements : node.body
+        scope_constraints(body)
+      end
+    end
+
     # One walk answers both per-scope safety questions: whether the scope
     # defeats renaming entirely (eval and friends can read any local by its
     # original name) and which locals are name-pinned — a regex named

data/lib/ryac/analysis/method/collection.rb

@@ -3,12 +3,27 @@
 module Ryac
   module AnalysisPhases
     def collect_method_definitions(prism_root)
+      setter_mids = Set.new
       Nesting.each_method_definition(prism_root) do |node, method_key|
         next if EXCLUDED_METHODS.include?(method_key[2])
 
+        # An explicit `def foo=` keeps its name: short names are allocated
+        # per group, so nothing promises the setter would land on
+        # `<getter's name>=`, and the def patcher would strip the `=` from
+        # any unpaired spelling. The base name is kept with it — a compound
+        # write reads through one spelling and writes through the other, so
+        # the pair must move in lockstep or not at all (the same doctrine
+        # that keeps accessor pairs in compound writes unrenamed).
+        # attr-declared setters are different — they rename textually
+        # coupled to their getter.
+        if AstUtils.setter_def_name?(method_key[2])
+          setter_mids << method_key[2] << method_key[2].to_s.chomp('=').to_sym
+        end
+
         @method_rename_mapping.add_method(method_key, node)
         link_module_function_variant(node, method_key)
       end
+      @method_rename_mapping.exclude_methods_by_mid(setter_mids) unless setter_mids.empty?
 
       # attr_reader/attr_accessor define getters worth renaming; attr_writer's
       # setter is derived from the getter name and is never registered on its
@@ -54,7 +69,86 @@ module Ryac
       merge_super_groups(super_merges)
       merge_polymorphic_groups(call_node_to_keys)
       merge_unresolved_calls(resolved_call_keys)
-      @method_rename_mapping.merge_blind_def_groups
+      # Folding blind defs into same-name sited groups is a probability
+      # bet, not a proof — the aggressive policy's territory.
+      @method_rename_mapping.merge_blind_def_groups if @method_policy == :aggressive
+    end
+
+    # An attr declared below a class that touches its ivar — `attr_reader
+    # :label_text` in a subclass of the class assigning @label_text — cannot
+    # rename: the coordination that moves ivar sites along with a renamed
+    # attr walks from the declaring class down, never up to that ancestor,
+    # which would go on writing the original name. The pair keeps its name.
+    def collect_inherited_attr_exclusions(prism_root)
+      touching = Hash.new { |h, k| h[k] = Set.new } #: Hash[Symbol, Set[Array[Symbol]]]
+      Nesting.each(prism_root) do |node, cpath, _singleton, _in_def|
+        case node
+        when Prism::InstanceVariableReadNode, *IVAR_WRITE_NODES
+          # @type var node: Prism::InstanceVariableReadNode | ivar_write_node
+          touching[node.name] << cpath
+        end
+      end
+
+      excluded = Set.new
+      each_attr_declaration(prism_root, ATTR_DECLARATION_METHODS, require_class_body: false) do |_node, cpath, _singleton, sym|
+        classes = touching.fetch(:"@#{sym}", nil)
+        next unless classes
+
+        @oracle.each_ancestor_cpath(cpath, false) do |ancestor_cpath|
+          excluded << sym << :"#{sym}=" if ancestor_cpath != cpath && classes.include?(ancestor_cpath)
+        end
+      end
+      @method_rename_mapping.exclude_methods_by_mid(excluded) unless excluded.empty?
+    end
+
+    # Renaming an attr declaration renames its backing ivar with it. In a
+    # class that touches ivars dynamically (optcarrot's Config assigns
+    # every option via instance_variable_set), the dynamic side keeps the
+    # original spelling and a renamed reader silently returns nil. The
+    # ivar renamer already refuses such classes; the attr names there must
+    # survive for the same reason, under either policy.
+    def collect_dynamic_ivar_attr_exclusions(prism_root)
+      dynamic_cpaths = Set.new
+      Nesting.each(prism_root) do |node, cpath, _singleton, _in_def|
+        next unless node.is_a?(Prism::CallNode) && DYNAMIC_IVAR_METHODS.include?(node.name)
+
+        recv = node.receiver
+        dynamic_cpaths << cpath if recv.nil? || recv.is_a?(Prism::SelfNode)
+      end
+      return if dynamic_cpaths.empty?
+
+      excluded = Set.new
+      each_attr_declaration(prism_root, ATTR_DECLARATION_METHODS, require_class_body: false) do |_node, cpath, _singleton, sym|
+        excluded << sym << :"#{sym}=" if dynamic_cpaths.include?(cpath)
+      end
+      @method_rename_mapping.exclude_methods_by_mid(excluded) unless excluded.empty?
+    end
+
+    # eval and send-by-string dispatch from strings, not the syntax tree:
+    # a method whose name is spelled inside any string literal may be
+    # called from text the renamer cannot rewrite, so under the safe
+    # policy it keeps its name. Setters count as mentioned when their
+    # base word is.
+    def collect_string_literal_mentions(prism_root)
+      words = Set.new
+      AstUtils.each_node(prism_root) do |node|
+        next unless node.is_a?(Prism::StringNode)
+
+        # Byte escapes (`"\x89PNG"`) leave the literal invalid in the source
+        # encoding, and String#scan refuses invalid text; the identifier
+        # pattern is pure ASCII, so scanning the bytes finds the same words.
+        # The pattern has no capture groups, so scan only produces strings;
+        # the is_a? narrows the union scan's signature declares.
+        node.unescaped.b.scan(/[a-zA-Z_][a-zA-Z0-9_]*[?!]?/).each do |w|
+          words << w.to_sym if w.is_a?(String)
+        end
+      end
+      return if words.empty?
+
+      mentioned = @method_rename_mapping.method_mids.select { |mid|
+        words.include?(mid) || words.include?(mid.to_s.chomp('=').to_sym)
+      }
+      @method_rename_mapping.exclude_methods_by_mid(mentioned.to_set) unless mentioned.empty?
     end
 
     # Visibility resets at every reopen of this module, so each collection
@@ -154,7 +248,9 @@ module Ryac
           end
         end
 
-        if should_exclude
+        # An unresolved call the aggressive policy folds into the group is
+        # exactly the bet the safe policy refuses: the name goes untouched.
+        if should_exclude || (@method_policy == :safe && mapped_calls.any?)
           exclude_mids << mid
         elsif mapped_calls.any?
           @method_rename_mapping.merge_all_by_mid(mid)
@@ -211,7 +307,8 @@ module Ryac
       @method_rename_mapping.exclude_methods_by_mid(punned) if punned.any?
     end
 
-    VISIBILITY_MODIFIERS = %i[private protected public module_function].freeze
+    VISIBILITY_MODIFIERS = %i[private protected public module_function
+                              private_class_method public_class_method].freeze
 
     def collect_visibility_modifier_methods(prism_root)
       excluded_mids = Set.new

data/lib/ryac/analysis/method/rename_mapping.rb

@@ -101,6 +101,19 @@ module Ryac
       (blind_mids & sited_mids).each { |mid| merge_all_by_mid(mid) }
     end
 
+    # A def no resolved call reaches is either dead or called from outside
+    # the program (a library's public surface, a runner script requiring
+    # the bundle) — renaming it is unsound both ways, so the safe policy
+    # drops those names before assignment.
+    def exclude_uncalled_methods
+      mids = Set.new
+      groups_by_root.each_value do |keys|
+        sites = keys.sum { |key| @methods[key][:call_sites].size }
+        keys.each { |key| mids << key[2] } if sites.zero?
+      end
+      exclude_methods_by_mid(mids) unless mids.empty?
+    end
+
     def add_unresolved_sites_for_mid(mid, call_nodes)
       target_key = @methods.keys.find { |k| k[2] == mid }
       return unless target_key
@@ -123,11 +136,13 @@ module Ryac
       end
     end
 
-    def assign_short_names(scope_mappings, oracle = nil)
+    # scope_vars: LocalScopes#visible_local_names — every local name visible
+    # at a scope after renaming, so implicit-receiver sites can refuse a
+    # short name a bare call would resolve as a variable read.
+    def assign_short_names(scope_vars, oracle = nil)
       group_entries = build_group_entries(groups_by_root)
       group_entries.sort_by! { |entry| -(entry.original_name.size * entry.total_occurrences) }
 
-      scope_vars = self.class.build_scope_vars(scope_mappings)
       existing_methods, hierarchy = oracle ? build_existing_method_names(oracle) : [{}, {}] #: [Hash[class_key, Set[String]], hierarchy]
 
       group_entries.each do |entry|
@@ -241,16 +256,6 @@ module Ryac
       result
     end
 
-    # Class method: the attr coordination inverts scope_mappings the same
-    # way for its own collision check, so there is exactly one inversion.
-    def self.build_scope_vars(scope_mappings)
-      scope_vars = Hash.new { |h, k| h[k] = Set.new } #: Hash[scope_id, Set[String]]
-      scope_mappings.each do |cref_id, mapping|
-        mapping.each_value { |mangled| scope_vars[cref_id] << mangled }
-      end
-      scope_vars
-    end
-
     def groups_by_root
       groups = Hash.new { |h, k| h[k] = [] } #: Hash[method_key, Array[method_key]]
       @methods.each_key { |key| groups[uf_root(key)] << key }

data/lib/ryac/analysis/type_oracle.rb

@@ -19,13 +19,18 @@ module Ryac
     # internals the boot requires — the Service construction and the
     # private @rb_text_nodes table behind update_rb_file — so an upstream
     # change to either breaks here and nowhere else.
-    def self.boot(content, rbs_files)
+    #
+    # TypeProf does not register a class defined inside a block, and a lazy
+    # region (LazyRegions) is exactly that. It reads the view with the
+    # region wrappers blanked instead — same byte positions, which is what
+    # the coordinate join below relies on.
+    def self.boot(content, rbs_files, prism_root)
       path = '(minify_concat)'
       service = TypeProf::Core::Service.new({})
       rbs_files.each do |rbs_path, rbs_content|
         service.update_rbs_file(rbs_path, rbs_content)
       end
-      service.update_rb_file(path, content)
+      service.update_rb_file(path, LazyRegions.typeprof_view(content, prism_root))
       new(service.genv, service.instance_variable_get(:@rb_text_nodes)[path])
     end
 

data/lib/ryac/driver_file.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Ryac
+  # The two-file layout of a program with lazy regions: the minified program
+  # as a pure library — loader, core and aliases, nothing that runs — and a
+  # runner holding the regions, which loads the library, registers them and
+  # starts the program with an expression given on its command line:
+  #
+  #   ruby driver.rb minify.rb --exec "Optcarrot::NES.new.run" game.nes
+  #
+  # The runner strips its own arguments before anything else reads ARGV, so
+  # the program's option parsing sees only what follows. Registering after
+  # the load means a dynamic require the core runs while loading — rather
+  # than from a method called later, the shape that made the file lazy —
+  # would miss its region and fall through to the loader's real require.
+  module DriverFile
+    HEADER = <<~'RUBY'
+      # Generated by ryac. Usage: ruby driver.rb CORE [--exec EXPR] [ARGS...]
+      # Loads CORE, registers the regions below, then evals EXPR at top level
+      # with ARGS left in ARGV. Arguments after "--" are never read.
+      core = ARGV.shift or abort("usage: ruby #{$0} CORE [--exec EXPR] [ARGS...]")
+      stop = ARGV.index("--")
+      at = ARGV.index("--exec")
+      expr = ARGV.slice!(at, 2)[1] if at && (!stop || at < stop)
+      load core
+    RUBY
+
+    FOOTER = "eval(expr, TOPLEVEL_BINDING, \"--exec\") if expr\n"
+
+    # Splits the program's full content into [core, driver]: the region
+    # registrations go to the driver, one per line, everything else stays
+    # the core in its original order.
+    def self.split(full_content)
+      result = Prism.parse(full_content)
+      raise Pipeline::InvalidOutputError.new('program', result.errors) unless result.errors.none?
+
+      registrations = [] #: Array[String]
+      core = [] #: Array[String]
+      result.value.statements.body.each do |statement|
+        (LazyRegions.registration_lambda(statement) ? registrations : core) << statement.slice
+      end
+      raise MinifyError, 'cannot write a driver file: the program has no lazy regions' if registrations.empty?
+
+      [core.join(';'), "#{HEADER}#{registrations.join("\n")}\n#{FOOTER}"]
+    end
+  end
+end

data/lib/ryac/minifier.rb

@@ -52,44 +52,44 @@ module Ryac
       raise ArgumentError, "Invalid compress level: #{value} (valid: #{STAGES.keys.join(', ')})"
     end
 
-    ALL_VAR_FEATURES = { features: { keywords: true, ivars: true, cvars: true, gvars: true } }.freeze
     ALL_VAR_WITH_ATTR = { features: { keywords: true, ivars: true, cvars: true, gvars: true, attr_ivars: true } }.freeze
 
     # :unstable is derived from :stable, never hand-copied — the superset
-    # law lives here as code. "attrs renamed" is one fact spelled by three
-    # co-moving switches: AttrDeclShorten rename_attrs (declarations),
-    # attr_ivars (backing ivars) and MethodRenamer (call sites). This
-    # transform flips all three together; a hand-composed list must too.
+    # law lives here as code. The one switch between them is the method
+    # renamer's policy: :safe touches only names whose every caller type
+    # inference resolved; :aggressive also takes the bets.
     def self.derive_unstable(stable)
-      stable.flat_map do |entry|
-        if entry[0].equal?(Pipeline::AttrDeclShorten)
-          [[Pipeline::AttrDeclShorten, { rename_attrs: true }]] #: Array[stage_entry]
-        elsif entry[0].equal?(Pipeline::VariableRenamer)
-          [[Pipeline::VariableRenamer, ALL_VAR_WITH_ATTR], [Pipeline::MethodRenamer]] #: Array[stage_entry]
-        else
-          [entry]
-        end
-      end.freeze
+      stable.map { |entry|
+        entry[0].equal?(Pipeline::MethodRenamer) ? [Pipeline::MethodRenamer] #: stage_entry
+          : entry
+      }.freeze
     end
 
     # The two levels, named for their promise rather than a number.
     #
-    # :stable is the boundary the optcarrot test certifies frame-for-frame on
-    # a real program: everything up to class, constant and variable renaming,
-    # which closed-world analysis can keep sound.
+    # :stable is the boundary the optcarrot test certifies frame-for-frame
+    # on a real program: class, constant and variable renaming, plus method
+    # renaming under the :safe policy — a group renames only when type
+    # inference resolved every caller and no dynamic escape hatch (a string
+    # mention, a dynamic-ivar class, an uncalled def) touches its name.
+    # "attrs renamed" is one fact spelled by three co-moving switches:
+    # AttrDeclShorten rename_attrs (declarations), attr_ivars (backing
+    # ivars) and MethodRenamer (call sites) — all three live here together.
     #
-    # :unstable adds method renaming, which a program can defeat by
-    # construction — names survive inside strings, eval'd source and computed
-    # send targets, out of reach of any static analysis. It is certified by
-    # self-hosting and works only when the program plays along.
+    # :unstable switches method renaming to :aggressive, which a program
+    # can defeat by construction — names survive inside strings, eval'd
+    # source and computed send targets, out of reach of any static
+    # analysis. It is certified by self-hosting and works only when the
+    # program plays along.
     #
     # Finer configurations are not levels: individual steps stay composable
     # by passing an explicit stage list in place of a level name.
     STABLE_STAGES = [
       *OPTIMIZE_PRE,
       [Pipeline::ConstantAliaser, { rename_classes: true }],
-      [Pipeline::AttrDeclShorten],
-      [Pipeline::VariableRenamer, ALL_VAR_FEATURES],
+      [Pipeline::AttrDeclShorten, { rename_attrs: true }],
+      [Pipeline::VariableRenamer, ALL_VAR_WITH_ATTR],
+      [Pipeline::MethodRenamer, { policy: :safe }],
       *OPTIMIZE_POST,
     ].freeze
 
@@ -100,8 +100,8 @@ module Ryac
 
     # code is raw (uncompacted) text — compaction is the runner's fixed
     # first step, so every stage list starts from the same dialect.
-    def self.run_stages(code, stages, stdlib_requires: [], rbs_files: {})
-      Pipeline::StageRunner.new(stdlib_requires: stdlib_requires, rbs_files: rbs_files)
+    def self.run_stages(code, stages, stdlib_requires: [], rbs_files: {}, lazy_files: [])
+      Pipeline::StageRunner.new(stdlib_requires: stdlib_requires, rbs_files: rbs_files, lazy_files: lazy_files)
                            .call(code, stages)
     end
 
@@ -133,7 +133,8 @@ module Ryac
       stages = target_level.is_a?(Array) ? target_level : STAGES.fetch(self.class.resolve_level(target_level))
       self.class.run_stages(source.content, stages,
         stdlib_requires: source.stdlib_requires,
-        rbs_files: source.rbs_files
+        rbs_files: source.rbs_files,
+        lazy_files: source.lazy_files
       )
     end
 

data/lib/ryac/packer.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Ryac
+  # Self-extracting output encoding, applied after minification. The emitted
+  # file is a short plain-Ruby stub followed by the real program compressed
+  # after __END__; running it inflates the bytes and evals them with $0 as
+  # the file name, so a `$PROGRAM_NAME == __FILE__` launcher still fires and
+  # relative requires resolve as they would from the plain artifact.
+  #
+  # This is an output format, not a stage: stages rewrite Ruby into
+  # equivalent Ruby and re-parse to a fixed point, while a packed file is
+  # opaque bytes. Two formats:
+  #
+  #   :self — an LZSS decoder (4KB window, 3..18-byte matches) inlined in
+  #           the stub; no require at all, runs on any Ruby.
+  #   :zlib — deflate via the zlib default gem; smaller, but dead on a Ruby
+  #           built without it.
+  module Packer
+    FORMATS = %i[self zlib].freeze
+
+    SELF_STUB = 's=DATA.binmode.read;o="".b;i=0;while i<s.size;f=s.getbyte i;i+=1;' \
+                '8.times{break if i>=s.size;if f&1>0;o<<s.getbyte(i);i+=1;else;' \
+                'a=s.getbyte i;b=s.getbyte i+1;i+=2;d=(a<<4|b>>4)+1;l=(b&15)+3;' \
+                'l.times{o<<o.getbyte(o.size-d)};end;f>>=1};end;' \
+                'eval o.force_encoding("UTF-8"),nil,$0' \
+                "\n__END__\n"
+
+    ZLIB_STUB = 'require"zlib";eval Zlib.inflate(DATA.binmode.read).force_encoding("UTF-8"),nil,$0' \
+                "\n__END__\n"
+
+    def self.resolve_format(value)
+      format = value.to_sym
+      return format if FORMATS.include?(format)
+
+      raise ArgumentError, "Invalid pack format: #{value} (valid: #{FORMATS.join(', ')})"
+    end
+
+    def self.pack(source, format)
+      reject_data_readers(source)
+      case resolve_format(format)
+      when :zlib
+        require 'zlib'
+        ZLIB_STUB.b + Zlib::Deflate.deflate(source, Zlib::BEST_COMPRESSION)
+      else
+        SELF_STUB.b + lzss_compress(source)
+      end
+    end
+
+    # The stub consumes the packed file's one __END__/DATA stream, so a
+    # program carrying its own data section or reading DATA would read
+    # compressed garbage instead.
+    def self.reject_data_readers(source)
+      result = Prism.parse(source)
+      offending = result.data_loc ? '__END__' : nil
+      unless offending
+        AstUtils.each_node(result.value) do |node|
+          case node
+          when Prism::ConstantReadNode
+            offending = 'DATA' if node.name == :DATA
+          when Prism::ConstantPathNode
+            offending = 'DATA' if node.parent.nil? && node.name == :DATA
+          end
+          break if offending
+        end
+      end
+      return unless offending
+
+      raise MinifyError, "cannot pack: the program uses #{offending}, and the self-extracting stub owns the packed file's data section"
+    end
+
+    # Greedy LZSS: flag byte per 8 tokens (1 bit = literal), matches encoded
+    # as 12-bit distance-1 / 4-bit length-3. The decoder in SELF_STUB is the
+    # exact inverse.
+    def self.lzss_compress(data)
+      n = data.bytesize
+      out = +''.b
+      index = Hash.new { |h, k| h[k] = [] } #: Hash[String, Array[Integer]]
+      i = 0
+      flags = 0
+      nflag = 0
+      chunk = +''.b
+      flush = lambda do
+        out << flags.chr << chunk
+        flags = 0
+        nflag = 0
+        chunk = +''.b
+      end
+      while i < n
+        best_len = 0
+        best_dist = 0
+        if i + 3 <= n
+          index[data.byteslice(i, 3) || ''].reverse_each do |j|
+            d = i - j
+            break if d > 4096
+
+            l = 0
+            l += 1 while l < 18 && i + l < n && data.getbyte(j + l) == data.getbyte(i + l)
+            if l > best_len
+              best_len = l
+              best_dist = d
+              break if l == 18
+            end
+          end
+        end
+        if best_len >= 3
+          dm = best_dist - 1
+          chunk << (dm >> 4).chr << (((dm & 15) << 4) | (best_len - 3)).chr
+          best_len.times do
+            index[data.byteslice(i, 3) || ''] << i if i + 3 <= n
+            i += 1
+          end
+        else
+          flags |= (1 << nflag)
+          # getbyte(i) is non-nil for every i < n
+          chunk << data.getbyte(i).chr # steep:ignore NoMethod
+          index[data.byteslice(i, 3) || ''] << i if i + 3 <= n
+          i += 1
+        end
+        nflag += 1
+        flush.call if nflag == 8
+      end
+      flush.call if nflag.positive?
+      out
+    end
+    private_class_method :lzss_compress
+  end
+end