Add DotRubyVersionFile parser for .ruby-version files

Parses .ruby-version file contents and produces a LanguagePack::RubyVersion
instance. Uses service object pattern: initialize stores contents, call
returns a Result struct with ruby_version and a warnings array.

Supported formats:
- Plain version: 3.4.8
- Ruby prefix: ruby-3.4.8
- With @org suffix: ruby-3.4.8@company-name
- Pre-release (dot or dash): 3.4.0.rc1, 3.4.0-preview2
- Comments (#) and blank lines are ignored

Invalid inputs produce warnings (not errors):
- JRuby prefix
- Version specifiers (>=, ~>, etc.)
- Multiple version lines
- Unparseable content

Author: schneems

lib/language_pack.rb

@@ -141,6 +141,7 @@ def self.detect(arch:, app_path:, cache_path:, environment_name:, gemfile_lock:,
 require "language_pack/helpers/default_env_vars"
 require "language_pack/helpers/outdated_ruby_version"
 require "language_pack/helpers/download_presence"
+require "language_pack/helpers/dot_ruby_version_file"
 require "language_pack/installers/heroku_ruby_installer"
 
 require "language_pack/ruby"

lib/language_pack/helpers/dot_ruby_version_file.rb

@@ -0,0 +1,118 @@
+require "language_pack/shell_helpers"
+require "language_pack/ruby_version"
+
+module LanguagePack
+  module Helpers
+    # Parses contents of `.ruby-version` file to transform it into a RubyVersion
+    #
+    # Example:
+    #
+    #   version = DotRubyVersionFile.new(
+    #     contents: File.read(".ruby-version")
+    #   ).call
+    #   assert_eq [], version.warnings
+    #   assert_eq :ruby, version.ruby_version.engine
+    class DotRubyVersionFile
+      VERSION_PATTERN = /\A(?<version>\d+\.\d+\.\d+)(?:[.-](?<pre>\S+))?\z/
+      JRUBY_PATTERN = /\Ajruby-/i
+      SPECIFIER_PATTERN = />=|<=|~>|>|</
+
+      Result = Data.define(:ruby_version, :warnings)
+
+      def initialize(contents:)
+        @contents = contents
+      end
+
+      def call
+        warnings = []
+        lines = meaningful_lines
+
+        if lines.empty?
+          return Result.new(ruby_version: nil, warnings: warnings)
+        end
+
+        line = lines.first
+        version_string = strip_ruby_prefix_and_at_suffix(line)
+
+        if lines.length > 1
+          warnings << <<~EOF
+            The `.ruby-version` file contains multiple version lines.
+            Only a single version is supported. Remove additional lines.
+
+            Contents:
+
+            ```
+            #{@contents}
+            ```
+          EOF
+        end
+
+        if version_string.match?(JRUBY_PATTERN)
+          warnings << <<~EOF
+            JRuby not supported in `.ruby-version` file.
+
+            The `.ruby-version` file contains a JRuby version however the
+            JRuby engine is not supported by `.ruby-version` on Heroku at this time.
+
+            Contents:
+
+            ```
+            #{@contents}
+            ```
+          EOF
+        end
+
+        if version_string.match?(SPECIFIER_PATTERN)
+          warnings << <<~EOF
+            Cannot parse version specifiers in `.ruby-version` file.
+
+            Only exact versions are supported such as `3.4.8` or `ruby-3.4.8`.
+            Got:
+
+            ```
+            #{@contents}
+            ```
+          EOF
+        end
+
+        if warnings.any?
+          Result.new(ruby_version: nil, warnings: warnings)
+        elsif (match = version_string.match(VERSION_PATTERN))
+          Result.new(
+            ruby_version: LanguagePack::RubyVersion.new(
+              pre: match[:pre],
+              engine: :ruby,
+              default: false,
+              ruby_version: match[:version],
+              engine_version: match[:version]
+            ),
+            warnings: warnings
+          )
+        else
+          warnings << <<~EOF
+            Cannot parse Ruby version from `.ruby-version` file.
+
+            Expected format: `3.4.8` or `ruby-3.4.8`. Got:
+
+            ```
+            #{@contents}
+            ```
+          EOF
+          Result.new(ruby_version: nil, warnings: warnings)
+        end
+      end
+
+      private def meaningful_lines
+        @contents.gsub(/\s*#.*/, "").each_line.filter_map { |line|
+          stripped = line.strip
+          stripped unless stripped.empty?
+        }
+      end
+
+      private def strip_ruby_prefix_and_at_suffix(line)
+        version = line.delete_prefix("ruby-")
+        version.split("@").first
+      end
+    end
+  end
+end

spec/helpers/dot_ruby_version_file_spec.rb

@@ -0,0 +1,146 @@
+require "spec_helper"
+
+describe "DotRubyVersionFile" do
+  it "parses a plain version" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "3.4.8").call
+    expect(result.ruby_version).to be_a(LanguagePack::RubyVersion)
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.ruby_version.engine).to eq(:ruby)
+    expect(result.ruby_version.engine_version).to eq("3.4.8")
+    expect(result.ruby_version.default?).to eq(false)
+    expect(result.warnings).to eq([])
+  end
+
+  it "strips ruby- prefix" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "ruby-3.4.8").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.ruby_version.engine).to eq(:ruby)
+    expect(result.warnings).to eq([])
+  end
+
+  it "trims trailing comment" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "ruby-3.4.8 # our version").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.warnings).to eq([])
+
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "ruby-3.4.8# our version").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.warnings).to eq([])
+  end
+
+  it "strips @company-name suffix with ruby- prefix" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "ruby-3.4.8@company-name").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.warnings).to eq([])
+
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "ruby-3.4.8@company=>name").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.warnings).to eq([])
+  end
+
+  it "strips @org suffix from plain version" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "3.4.8@myorg").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.warnings).to eq([])
+  end
+
+  it "skips comments and blank lines" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: <<~EOF).call
+      # This is a comment
+
+      3.4.8
+    EOF
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.warnings).to eq([])
+  end
+
+  it "strips leading and trailing whitespace from the version line" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "  3.4.8  \n").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.8")
+    expect(result.warnings).to eq([])
+  end
+
+  it "parses pre-release with dot syntax" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "3.4.0.rc1").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.0")
+    expect(result.ruby_version.version_for_download).to eq("ruby-3.4.0.rc1")
+    expect(result.warnings).to eq([])
+  end
+
+  it "normalizes pre-release dash syntax to dot syntax" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "3.4.0-preview2").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.0")
+    expect(result.ruby_version.version_for_download).to eq("ruby-3.4.0.preview2")
+    expect(result.warnings).to eq([])
+  end
+
+  it "normalizes pre-release with ruby- prefix" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "ruby-3.4.0-rc1").call
+    expect(result.ruby_version.ruby_version).to eq("3.4.0")
+    expect(result.ruby_version.version_for_download).to eq("ruby-3.4.0.rc1")
+    expect(result.warnings).to eq([])
+  end
+
+  it "is empty for an empty string" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "").call
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings).to eq([])
+  end
+
+  it "is empty for only whitespace" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "   \n  \n").call
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings).to eq([])
+  end
+
+  it "is empty for only comments" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "# just a comment\n# another").call
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings).to eq([])
+  end
+
+  it "warns for multiple meaningful lines" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: <<~EOF).call
+      3.4.8
+      3.5.0
+    EOF
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings.length).to eq(1)
+    expect(result.warnings.first).to include("multiple version lines")
+  end
+
+  it "warns for jruby" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "jruby-10.0.2.0").call
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings.length).to eq(1)
+    expect(result.warnings.first).to include("JRuby")
+  end
+
+  it "warns for version specifiers with >=" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "ruby >= 3.1.6, < 3.3").call
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings.length).to eq(1)
+    expect(result.warnings.first).to include("version specifiers")
+  end
+
+  it "warns for ~> specifier" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "~> 3.1").call
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings.length).to eq(1)
+    expect(result.warnings.first).to include("version specifiers")
+  end
+
+  it "warns for >= specifier" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: ">= 3.1.6").call
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings.length).to eq(1)
+    expect(result.warnings.first).to include("version specifiers")
+  end
+
+  it "warns for garbage input" do
+    result = LanguagePack::Helpers::DotRubyVersionFile.new(contents: "not-a-version").call
+    expect(result.ruby_version).to be_nil
+    expect(result.warnings.length).to eq(1)
+    expect(result.warnings.first).to include("Cannot parse")
+  end
+end