ryac 0.2.0

data/lib/ryac/pipeline/control_flow_simplify.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Ryac
+  module Pipeline
+    class ControlFlowSimplify < Stage
+      # A collapse can make the enclosing construct collapsible in turn,
+      # so this runs to a fixed point.
+      def fixpoint? = true
+
+      def collect(ctx, patches)
+        @tail_return_ranges = [] #: Array[[Integer, Integer]]
+        walk(ctx.ast, ctx.source, patches)
+      end
+
+      private
+
+      # statement_position: the node is a direct child of a statements list.
+      # A modifier rewrite is only sound there — in value position the
+      # modifier captures the surrounding expression: `x = if c; v; end`
+      # assigns nil when c is false, but `x = v if c` skips the assignment,
+      # leaving x's previous value. (The compactor produces exactly that
+      # shape from `x = c ? v : nil`.)
+      def walk(node, source, patches, statement_position = false)
+        case node
+        when Prism::IfNode
+          # an IfNode with an end keyword always has its if/elsif keyword location
+          if node.end_keyword_loc && !contains_tail_return_patch?(node) &&
+             source.byteslice(node.if_keyword_loc.start_offset, 2) == 'if' # steep:ignore NoMethod
+            if (replacement = try_if(node, source, statement_position))
+              patches << mk(node, replacement)
+              return
+            end
+          end
+        when Prism::UnlessNode
+          if node.end_keyword_loc && !contains_tail_return_patch?(node)
+            if (replacement = try_unless(node, source, statement_position))
+              patches << mk(node, replacement)
+              return
+            end
+          end
+        when Prism::WhileNode, Prism::UntilNode
+          if node.closing_loc
+            keyword = node.is_a?(Prism::WhileNode) ? 'while' : 'until'
+            if (replacement = try_loop(node, source, statement_position, keyword))
+              patches << mk(node, replacement)
+              return
+            end
+          end
+        when Prism::DefNode
+          try_tail_return(node, patches)
+        end
+        child_position = node.is_a?(Prism::StatementsNode)
+        node.compact_child_nodes.each { |child| walk(child, source, patches, child_position) }
+      end
+
+      # The value of a def is its last expression, and "last expression"
+      # extends through every construct whose value the def passes along:
+      # both arms of an if/unless, every when/in body, a begin's body,
+      # rescue and else. A `return expr` in any of those tail positions
+      # only restates the flow, so the keyword goes; `return a, b` is the
+      # array [a, b] spelled longer. Loops and blocks are opaque — a
+      # return there escapes the method for real — and a bare `return`
+      # is not the statement's own value, so both stay. A splat builds a
+      # value the bare expression would not.
+      def try_tail_return(node, patches)
+        collect_tail_returns(node.body, patches)
+      end
+
+      def collect_tail_returns(node, patches)
+        case node
+        when Prism::ReturnNode
+          args = node.arguments&.arguments
+          return unless args && !args.empty?
+          return if args.any? { |a| a.is_a?(Prism::SplatNode) }
+
+          replacement = args.size == 1 ? args[0].slice : "[#{args.map(&:slice).join(',')}]"
+          patches << mk(node, replacement)
+          @tail_return_ranges << [node.location.start_offset, node.location.end_offset]
+        when Prism::StatementsNode
+          collect_tail_returns(node.body[-1], patches)
+        when Prism::IfNode
+          collect_tail_returns(node.statements, patches)
+          collect_tail_returns(node.subsequent, patches)
+        when Prism::UnlessNode
+          collect_tail_returns(node.statements, patches)
+          collect_tail_returns(node.else_clause, patches)
+        when Prism::ElseNode, Prism::WhenNode, Prism::InNode
+          collect_tail_returns(node.statements, patches)
+        when Prism::CaseNode, Prism::CaseMatchNode
+          node.conditions.each { |c| collect_tail_returns(c, patches) }
+          collect_tail_returns(node.else_clause, patches)
+        when Prism::BeginNode
+          # The ensure body is not a value position, but its presence
+          # changes nothing about the others: it runs on both spellings.
+          collect_tail_returns(node.statements, patches)
+          collect_tail_returns(node.rescue_clause, patches)
+          collect_tail_returns(node.else_clause, patches)
+        when Prism::RescueNode
+          collect_tail_returns(node.statements, patches)
+          collect_tail_returns(node.subsequent, patches)
+        end
+      end
+
+      # A same-pass conflict guard: a construct on a tail path may itself
+      # be offered as a modifier/ternary rewrite while the return inside
+      # it is already patched. The return wins the pass; the fixpoint
+      # re-offers the outer rewrite on the return-free text.
+      def contains_tail_return_patch?(node)
+        s = node.location.start_offset
+        e = node.location.end_offset
+        @tail_return_ranges.any? { |rs, re| rs >= s && re <= e }
+      end
+
+      def try_if(node, source, statement_position)
+        cond = src(source, node.predicate)
+        stmts = node.statements
+
+        if node.subsequent.nil?
+          return nil unless stmts && AstUtils.single_statement_body?(stmts)
+          if (folded = try_sole_nested_if(node, stmts.body.first, source))
+            return folded
+          end
+          body = src(source, stmts)
+          return nil if body.include?(';')
+          return nil if condition_assigns_var_used_in_body?(node.predicate, stmts)
+          if statement_position
+            return nil if in_collection_context?(node, source)
+            "#{body} if #{cond}"
+          else
+            # As a value, the bare modifier would capture the surrounding
+            # expression; parenthesized it stays a self-contained nil-or-body.
+            "(#{body} if #{cond})"
+          end
+        else
+          then_body = stmts ? src(source, stmts) : nil
+          else_result = else_text_for_ternary(node.subsequent, source)
+          return nil if else_result.nil?
+
+          return nil if too_complex_for_ternary?(then_body)
+
+          then_node = stmts.body.first if stmts
+          return nil if then_node.is_a?(Prism::MultiWriteNode)
+          result = build_ternary(node.predicate, cond, then_node, then_body, else_result)
+          result = "(#{result})" if AstUtils.ternary_needs_parens?(node, source) || if_end_followed_by_operator?(node, source)
+          result
+        end
+      end
+
+      # `if a` wrapping nothing but `if b` runs the inner body exactly when
+      # a && b: the fold drops a whole if;end frame, and the fixpoint then
+      # offers the merged conditional to the modifier and ternary forms.
+      # Evaluation order is untouched — a, then b, then the body — so no
+      # assignment guard is needed. Only else-less if folds into else-less
+      # if: an elsif node is never a body statement, and if_keyword_loc
+      # rules out the ternary form.
+      def try_sole_nested_if(node, inner, source)
+        return nil unless inner.is_a?(Prism::IfNode) && inner.if_keyword_loc
+        return nil unless inner.subsequent.nil? && inner.statements
+
+        left = logic_operand_text(node.predicate, src(source, node.predicate))
+        right = logic_operand_text(inner.predicate, src(source, inner.predicate))
+        "if #{left}&&#{right};#{src(source, inner.statements)};end"
+      end
+
+      # The operand rule is the Compactor's — CFS emits into its dialect.
+      def logic_operand_text(pred, text)
+        Compactor.loose_logic_operand?(pred, tight: true) ? "(#{text})" : text
+      end
+
+      def else_text_for_ternary(subsequent, source)
+        case subsequent
+        # An elsif chain that just ends: the if's value is nil when no
+        # branch takes, and `()` says so in ternary position.
+        when nil
+          '()'
+        when Prism::ElseNode
+          stmts = subsequent.statements
+          text = stmts ? src(source, stmts) : nil
+          return nil if too_complex_for_ternary?(text)
+          else_node = stmts&.body&.first
+          return nil if else_node.is_a?(Prism::MultiWriteNode)
+          text = "(#{text})" if else_node && AstUtils.modifier_control_flow?(else_node)
+          text
+        when Prism::IfNode
+          cond = src(source, subsequent.predicate)
+          stmts = subsequent.statements
+          then_body = stmts ? src(source, stmts) : nil
+          return nil if too_complex_for_ternary?(then_body)
+
+          else_result = else_text_for_ternary(subsequent.subsequent, source)
+          return nil if else_result.nil?
+
+          then_node = stmts.body.first if stmts
+          # same rule as the top-level then: a multiple assignment's comma
+          # cannot live inside a ternary branch
+          return nil if then_node.is_a?(Prism::MultiWriteNode)
+          build_ternary(subsequent.predicate, cond, then_node, then_body, else_result)
+        end
+      end
+
+      def build_ternary(cond_node, cond, then_node, then_expr, else_expr)
+        if then_node && AstUtils.modifier_control_flow?(then_node)
+          then_expr = "(#{then_expr})"
+          then_node = nil
+        end
+
+        # and/or keywords have lower precedence than ?: — must wrap in parens
+        needs_parens = cond_node.is_a?(Prism::AndNode) || cond_node.is_a?(Prism::OrNode)
+        cond = "(#{cond})" if needs_parens
+
+        if !needs_parens && AstUtils.needs_ternary_q_space?(cond_node)
+          q_pre = ' '
+          q_post = ' '
+        else
+          q_pre = ''
+          q_post = ''
+        end
+
+        if then_node && (AstUtils.ends_with_name_char?(then_node) || AstUtils.ends_with_method_suffix?(then_node))
+          colon_pre = ' '
+          colon_post = ' '
+        elsif else_expr&.start_with?(':')
+          colon_pre = ''
+          colon_post = ' '
+        else
+          colon_pre = ''
+          colon_post = ''
+        end
+
+        "#{cond}#{q_pre}?#{q_post}#{then_expr}#{colon_pre}:#{colon_post}#{else_expr}"
+      end
+
+      def try_unless(node, source, statement_position)
+        stmts = node.statements
+        body = stmts ? src(source, stmts) : nil
+        cond = src(source, node.predicate)
+
+        modifier_ok = statement_position && body && !body.include?(';') &&
+                      !condition_assigns_var_used_in_body?(node.predicate, stmts) &&
+                      !in_collection_context?(node, source)
+
+        if AstUtils.simple_negatable?(node.predicate)
+          neg_cond = "!#{cond}"
+          if modifier_ok
+            "#{body} if #{neg_cond}"
+          else
+            "if #{neg_cond};#{body || ''};end"
+          end
+        elsif modifier_ok
+          "#{body} unless #{cond}"
+        end
+      end
+
+      def try_loop(node, source, statement_position, keyword)
+        return nil unless statement_position
+        stmts = node.statements
+        return nil unless stmts && AstUtils.single_statement_body?(stmts)
+        body = src(source, stmts)
+        return nil if body.include?(';')
+        return nil if condition_assigns_var_used_in_body?(node.predicate, stmts)
+        return nil if in_collection_context?(node, source)
+        cond = src(source, node.predicate)
+        "#{body} #{keyword} #{cond}"
+      end
+
+      def too_complex_for_ternary?(text)
+        text && (text.include?(';') ||
+          text.match?(/\A(?:return|break|next|yield) /))
+      end
+
+      # Modifier if/unless/while/until is invalid inside array, hash, or argument
+      # contexts. Check if the byte before the node (skipping whitespace) is a
+      # comma, open bracket, or open paren.
+      COLLECTION_CONTEXT_BYTES = [','.ord, '['.ord, '('.ord].freeze
+
+      def in_collection_context?(node, source)
+        pos = node.location.start_offset - 1
+        while pos >= 0
+          byte = source.getbyte(pos)
+          if byte == ' '.ord || byte == "\n".ord || byte == "\r".ord || byte == "\t".ord
+            pos -= 1
+          else
+            return COLLECTION_CONTEXT_BYTES.include?(byte)
+          end
+        end
+        false
+      end
+
+      def condition_assigns_var_used_in_body?(predicate, body)
+        assigned = collect_assigned_vars(predicate)
+        return false if assigned.empty?
+        read = collect_read_vars(body)
+        assigned.intersect?(read)
+      end
+
+      # Every node kind that binds a local: plain writes, compound writes
+      # (||= &&= +=), and multi-assignment targets. In the modifier form the
+      # body parses before the condition runs, so a local the condition
+      # binds reads as a method call there — any of these kinds counts.
+      LOCAL_BINDING_NODES = [
+        Prism::LocalVariableWriteNode,
+        Prism::LocalVariableOrWriteNode,
+        Prism::LocalVariableAndWriteNode,
+        Prism::LocalVariableOperatorWriteNode,
+        Prism::LocalVariableTargetNode
+      ].freeze
+
+      def collect_assigned_vars(node)
+        vars = Set.new
+        traverse(node) do |n|
+          case n
+          when *LOCAL_BINDING_NODES
+            # @type var n: Prism::LocalVariableWriteNode | Prism::LocalVariableOrWriteNode | Prism::LocalVariableAndWriteNode | Prism::LocalVariableOperatorWriteNode | Prism::LocalVariableTargetNode
+            vars << n.name
+          end
+        end
+        vars
+      end
+
+      def collect_read_vars(node)
+        vars = Set.new
+        traverse(node) do |n|
+          vars << n.name if n.is_a?(Prism::LocalVariableReadNode)
+        end
+        vars
+      end
+
+      def traverse(node, &block)
+        return unless node
+        yield node
+        node.compact_child_nodes.each { |child| traverse(child, &block) }
+      end
+
+      # Check if `end` keyword is followed by an operator (e.g., `if...end*(expr)`)
+      # In that case, ternary conversion needs parentheses.
+      OPERATOR_START_BYTES = [
+        '*'.ord, '/'.ord, '%'.ord, '+'.ord, '-'.ord, '&'.ord,
+        '|'.ord, '^'.ord, '<'.ord, '>'.ord, '.'.ord, '['.ord
+      ].freeze
+
+      def if_end_followed_by_operator?(node, source)
+        end_loc = node.end_keyword_loc
+        return false unless end_loc
+        after = end_loc.end_offset
+        return false if after >= source.bytesize
+        OPERATOR_START_BYTES.include?(source.getbyte(after))
+      end
+    end
+  end
+end

data/lib/ryac/pipeline/data_types.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Ryac
+  module Pipeline
+    # Represents a single source file discovered during collection
+    # Immutable after creation
+    FileEntry = Data.define(
+      :path,                  # String: Absolute path to the file
+      :content,               # String: Raw file content
+      :dependencies,          # Array<String>: Absolute paths of required files (top-level requires only)
+      :require_nodes,         # Array<Hash>: {type:, path:, line:, in_class:} for require/autoload nodes
+      :in_class_dependencies  # Array<String>: Absolute paths of files required inside class/module bodies
+    ) do
+      # declared on the Data class itself in the RBS
+      def initialize(path:, content:, dependencies:, require_nodes:, in_class_dependencies: []) # steep:ignore UndeclaredMethodDefinition
+        super
+      end
+    end
+
+    # Represents the dependency relationships between files
+    # Uses adjacency list for efficient topological sort
+    class DependencyGraph
+      attr_reader :files, :adjacency, :in_degrees, :rbs_files
+
+      def initialize
+        @files = {}       # Hash<String, FileEntry>: path -> entry mapping
+        @adjacency = {}   # Hash<String, Array<String>>: path -> dependent paths (files that require this one)
+        @in_degrees = {}  # Hash<String, Integer>: path -> number of dependencies
+        @rbs_files = {}   # Hash<String, String>: path -> RBS content
+      end
+
+      # Add a file entry to the graph
+      # @param entry [FileEntry] The file entry to add
+      def add_file(entry)
+        @files[entry.path] = entry
+        @adjacency[entry.path] ||= []
+        @in_degrees[entry.path] ||= 0
+
+        # Update adjacency and in-degrees based on all dependencies
+        (entry.dependencies + entry.in_class_dependencies).each do |dep_path|
+          @adjacency[dep_path] ||= []
+          @adjacency[dep_path] << entry.path
+          @in_degrees[entry.path] += 1
+        end
+      end
+
+      # Get all file paths in the graph
+      # @return [Array<String>]
+      def paths
+        @files.keys
+      end
+
+      # Get file entry by path
+      # @param path [String]
+      # @return [FileEntry, nil]
+      def [](path)
+        @files[path]
+      end
+
+      # Number of files in the graph
+      # @return [Integer]
+      def size
+        @files.size
+      end
+
+      # Check if graph is empty
+      # @return [Boolean]
+      def empty?
+        @files.empty?
+      end
+    end
+
+    # Source map entry for tracking file boundaries in concatenated output
+    FileBoundary = Data.define(
+      :path,        # String: Original file path
+      :start_line,  # Integer: 1-indexed start line in concatenated output
+      :end_line     # Integer: 1-indexed end line in concatenated output
+    )
+
+    # Output of Stage 2 (Concatenator), input to Stage 3 (Minifier)
+    #
+    # Stages that rewrite the text rebuild this with #with(content: ...):
+    # original_size and file_boundaries describe the collected input, not the
+    # current text, and #with is what keeps them traveling unchanged.
+    ConcatenatedSource = Data.define(
+      :content,          # String: All files joined with separators
+      :file_boundaries,  # Array<FileBoundary>: Line ranges are true at concatenation only; the pipeline rewrites the text from compaction on
+      :original_size,    # Integer: Bytes of the input the content descends from
+      :stdlib_requires,  # Array<String>: Standard library requires to preserve
+      :rbs_files         # Hash<String, String>: path -> RBS content for TypeProf
+    ) do
+      # A source built straight from a string (tests, sub-pipelines) has no
+      # file ancestry: everything but the content defaults away, and its
+      # original size is the content itself.
+      def initialize(content:, file_boundaries: [], original_size: nil, stdlib_requires: [], rbs_files: {}) # steep:ignore UndeclaredMethodDefinition
+        super(content: content, file_boundaries: file_boundaries,
+              original_size: original_size || content.bytesize,
+              stdlib_requires: stdlib_requires, rbs_files: rbs_files)
+      end
+    end
+
+    # Output of Stage 3 (Analyzer), input to Stage 4 (Minifier)
+    AnalysisResult = Data.define(
+      :prism_ast,                  # Prism::ProgramNode for rebuild
+      :scope_mappings,             # Hash: cref_id -> variable mapping
+      :constant_mapping,           # ConstantRenameMapping — short names are assigned by ConstantAliaser#collect, the only stage that reads it
+      :rename_map,                 # Hash<location_key, String>: method short names + attr coordinate adjustments
+      :method_alias_map,           # Hash<location_key, Symbol>: method alias replacements
+      :method_transform_map,       # Hash<location_key, String>: structural transforms (e.g. .first → [0])
+      :source,                     # ConcatenatedSource: original input preserved
+      :attr_rename_map,            # Hash<location_key, Hash<Symbol, String>>: attr symbol renames
+      :block_param_names_map,      # Hash<location_key, Hash<Symbol, String>>: pre-computed block param mangled names
+      :syntax_data,                # Hash<[line,col], Hash>: Prism-derived syntax metadata
+      :const_resolution_map,       # Hash<location_key, Array>: resolved constant cpaths
+      :const_full_path_map,        # Hash<location_key, Array>: resolved constant paths (fallback: syntactic)
+      :const_write_cpath_map,      # Hash<location_key, Array>: normalized write cpaths
+      :class_cpath_map,            # Hash<location_key, Array>: class/module cpaths
+      :superclass_resolution_map,  # Hash<location_key, Array>: resolved superclass paths
+      :meta_node_map,              # Hash<location_key, Hash>: meta node info (attr_reader, etc.)
+      :local_rename_entries,       # Hash<location_key, String>: local vars + lambda vars
+      :keyword_rename_entries,     # Hash<location_key, String>: keyword arg renames
+      :ivar_rename_entries,        # Hash<location_key, String>: instance variable renames
+      :attr_ivar_entries,          # Hash<location_key, String>: attr-backed ivar renames (only valid when MethodRenamer runs)
+      :cvar_rename_entries,        # Hash<location_key, String>: class variable renames
+      :gvar_rename_entries         # Hash<location_key, String>: global variable renames
+    ) do
+      def initialize(local_rename_entries: {}, keyword_rename_entries: {}, ivar_rename_entries: {}, attr_ivar_entries: {}, cvar_rename_entries: {}, gvar_rename_entries: {}, **kwargs) # steep:ignore UndeclaredMethodDefinition
+        super(local_rename_entries: local_rename_entries, keyword_rename_entries: keyword_rename_entries, ivar_rename_entries: ivar_rename_entries, attr_ivar_entries: attr_ivar_entries, cvar_rename_entries: cvar_rename_entries, gvar_rename_entries: gvar_rename_entries, **kwargs)
+      end
+    end
+
+    # Compression statistics for the final output
+    CompressionStats = Data.define(
+      :original_size,     # Integer: Bytes before minification
+      :minified_size,     # Integer: Bytes after minification
+      :compression_ratio, # Float: 0.0-1.0 (1.0 = no compression)
+      :file_count         # Integer: Number of files processed
+    )
+
+    # Internal return type of the rename stages: the parts of the program,
+    # not yet assembled. code deliberately carries no requires and no
+    # preamble — the Minifier joins the parts into MinifiedResult#content,
+    # which is why the field is not called content.
+    RenameResult = Data.define(
+      :code,      # String: Minified Ruby code alone (no requires, no preamble)
+      :aliases,   # String: Backward-compatible constant alias declarations (e.g. "MyClass=A;Foo=B")
+      :preamble   # String: External prefix declarations (e.g. "A=Process") — must execute before code
+    ) do
+      def initialize(code:, aliases: '', preamble: '') # steep:ignore UndeclaredMethodDefinition
+        super
+      end
+    end
+
+    # Final output of the pipeline.
+    #
+    # content is the assembled runnable program: stdlib requires, then the
+    # preamble, then the minified code. preamble is a slice of content
+    # carried separately so callers that split output can identify it —
+    # never something to append to content again. aliases are the one part
+    # kept out: optional compatibility shims, attached by full_content or
+    # written to their own file.
+    MinifiedResult = Data.define(
+      :content,   # String: requires + preamble + minified code
+      :aliases,   # String: Backward-compatible constant alias declarations
+      :preamble,  # String: External prefix declarations (already included in content)
+      :stats      # CompressionStats
+    ) do
+      def initialize(content:, aliases: '', preamble: '', stats:) # steep:ignore UndeclaredMethodDefinition
+        super
+      end
+
+      # The program with its alias shims attached — what a caller runs when
+      # not splitting the aliases into a separate file.
+      def full_content # steep:ignore UndeclaredMethodDefinition
+        aliases.empty? ? content : "#{content};#{aliases}" # steep:ignore NoMethod
+      end
+    end
+  end
+end

data/lib/ryac/pipeline/endless_method.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ryac
+  module Pipeline
+    class EndlessMethod < Stage
+      # A conversion can expose another convertible def (nested singles),
+      # so this runs to a fixed point.
+      def fixpoint? = true
+
+      def collect(ctx, patches)
+        walk(ctx.ast, ctx.source, patches)
+      end
+
+      private
+
+      def walk(node, source, patches)
+        if node.is_a?(Prism::DefNode) && node.end_keyword_loc
+          if (replacement = try_def(node, source))
+            patches << mk(node, replacement)
+            return
+          end
+        end
+        node.compact_child_nodes.each { |child| walk(child, source, patches) }
+      end
+
+      def try_def(node, source)
+        body_node = node.body
+        return nil unless body_node.is_a?(Prism::StatementsNode)
+        return nil if AstUtils.setter_def_name?(node.name)
+
+        stmts = body_node.body
+        return nil if stmts.any? { |s| s.is_a?(Prism::MultiWriteNode) }
+
+        body = src(source, body_node)
+
+        if stmts.size > 1
+          body = "(#{body})"
+        elsif (stmt = stmts.first)
+          if keyword_logical?(stmt, source) || AstUtils.modifier_control_flow?(stmt) ||
+             AstUtils.match_rebind?(stmt)
+            body = "(#{body})"
+          end
+        end
+
+        header_end = body_node.location.start_offset
+        # the def header range is always inside the source, so byteslice is non-nil
+        header = source.byteslice(node.location.start_offset, header_end - node.location.start_offset).chomp(';') # steep:ignore NoMethod
+
+        "#{header} =#{body}"
+      end
+
+      def keyword_logical?(node, source)
+        return false unless node.is_a?(Prism::AndNode) || node.is_a?(Prism::OrNode)
+
+        op = source.byteslice(node.operator_loc.start_offset, node.operator_loc.length)
+        op == 'and' || op == 'or'
+      end
+    end
+  end
+end

data/lib/ryac/pipeline/errors.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# The superclasses below resolve at load: this edge is what places their
+# definitions in front of this file in the concatenated artifact.
+require_relative '../errors'
+
+module Ryac
+  module Pipeline
+    # Base class for input-side pipeline failures: the program being
+    # minified (or how it was invoked) is at fault.
+    class StageError < Ryac::InputError; end
+
+    # Raised when a required file cannot be found
+    class FileNotFoundError < StageError
+      attr_reader :path, :required_from, :line
+
+      def initialize(path, required_from: nil, line: nil)
+        @path = path
+        @required_from = required_from
+        @line = line
+
+        message = "File not found: #{path}"
+        message += " (required from #{required_from}:#{line})" if required_from && line
+        super(message)
+      end
+    end
+
+    # Raised when a dynamic require or autoload is detected
+    class DynamicRequireError < StageError
+      attr_reader :path, :line, :expression
+
+      def initialize(path, line:, expression:)
+        @path = path
+        @line = line
+        @expression = expression
+
+        super("Dynamic require at #{path}:#{line}: #{expression}")
+      end
+    end
+
+    # Raised when a circular dependency is detected in the graph
+    class CircularDependencyError < StageError
+      attr_reader :cycle
+
+      def initialize(cycle)
+        @cycle = cycle
+
+        cycle_str = cycle.map { |p| File.basename(p) }.join(' → ')
+        super("Circular dependency: #{cycle_str}")
+      end
+    end
+
+    # Raised when no files are provided to the minifier
+    class NoFilesError < StageError
+      def initialize
+        super("No files provided. Please provide an entry point file.")
+      end
+    end
+
+    # Raised when a gem cannot be found or has no Ruby entry file
+    class GemNotFoundError < StageError
+      attr_reader :gem_name
+
+      def initialize(gem_name)
+        @gem_name = gem_name
+        super("Gem not found: #{gem_name}")
+      end
+    end
+
+    # Raised when the pipeline produced output that does not parse. The broken
+    # output is a bug in a stage, and failing here names the producer instead
+    # of letting the consumer discover it at load time.
+    class InvalidOutputError < Ryac::InternalError
+      def initialize(label, errors)
+        detail = errors.first(3).map { |e|
+          "#{e.location.start_line}:#{e.location.start_column}: #{e.message}"
+        }.join("; ")
+        super("minified #{label} does not parse (#{detail})")
+      end
+    end
+
+    # Raised when two different names in one scope were assigned the same
+    # short name. The output may still parse — `def c(a) = c(a) || d(a)` is
+    # valid Ruby — so this cannot be left to a syntax check.
+    class RenameCollisionError < Ryac::InternalError
+      def initialize(scope, collisions)
+        detail = collisions.map { |short, originals|
+          "#{originals.join(', ')} -> #{short}"
+        }.join("; ")
+        super("rename collision in #{scope}: #{detail}")
+      end
+    end
+  end
+end