js_regex_to_ruby 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdbe70d784541cad9e2009b2306416e72349cfc5e9136cadb998faf811d5ad91
+  data.tar.gz: fee286185020e60bf68b8c36736993ed75f8056fae28a882d977498a35445b44
+SHA512:
+  metadata.gz: b9290e4565d2635db41c94ffbf865dbe3a085d943c413e5f5c635c74b67584ff73e09e0fe230674f662146cf170e8977e474d9aa0963b47aa84da4a3012a18ce
+  data.tar.gz: d12f32df94de6834ce18c083e0b0ba9eaadacdf1ed4c56a6e39c236e4308e1337710eb33a1ebe5f34474e52ba75db90af5654c6eadea37ecee8c2e8f90f54cd0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 jasl
+
+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,222 @@
+# JsRegexToRuby
+
+A Ruby gem that converts ECMAScript (JavaScript) regular expressions to Ruby `Regexp` objects, preserving behavior as closely as Ruby's regex engine allows.
+
+## Why This Gem?
+
+JavaScript and Ruby regular expressions have subtle but important differences:
+
+| Feature | JavaScript | Ruby |
+|---------|-----------|------|
+| `^` and `$` anchors | Match start/end of **string** by default | Match start/end of **line** by default |
+| `/s` flag (dotAll) | Makes `.` match newlines | N/A (use `/m` in Ruby) |
+| `/m` flag (multiline) | Makes `^`/`$` match line boundaries | N/A (already default behavior) |
+| `[^]` (any character) | Matches any char including `\n` | Invalid syntax (use `[\s\S]`) |
+| `/g`, `/y`, `/d`, `/u`, `/v` flags | Various features | No direct equivalents |
+
+This gem handles these conversions automatically, emitting warnings when perfect conversion isn't possible.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "js_regex_to_ruby"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install js_regex_to_ruby
+```
+
+## Usage
+
+### Basic Conversion
+
+```ruby
+require "js_regex_to_ruby"
+
+# From a JS regex literal
+result = JsRegexToRuby.convert("/^foo$/i")
+result.regexp        #=> /\Afoo\z/i
+result.success?      #=> true
+
+# From pattern + flags separately
+result = JsRegexToRuby.convert("^hello$", flags: "im")
+result.regexp        #=> /^hello$/i
+result.ruby_source   #=> "^hello$"
+result.ruby_options  #=> 1 (Regexp::IGNORECASE)
+```
+
+### Quick Conversion with `try_convert`
+
+If you just need the `Regexp` and want `nil` on failure (no exceptions):
+
+```ruby
+# Returns Regexp on success
+JsRegexToRuby.try_convert("/^foo$/i")  #=> /\Afoo\z/i
+
+# Returns nil on invalid input (never raises)
+JsRegexToRuby.try_convert("/unterminated")  #=> nil
+JsRegexToRuby.try_convert("/(?invalid/")    #=> nil
+JsRegexToRuby.try_convert(nil)              #=> nil
+```
+
+### Parsing JS Literal Without Converting
+
+```ruby
+pattern, flags = JsRegexToRuby.parse_literal('/foo\\/bar/gi')
+pattern  #=> "foo\\/bar"
+flags    #=> "gi"
+```
+
+### Handling Warnings
+
+```ruby
+result = JsRegexToRuby.convert("/test/guy")
+
+result.warnings
+#=> ["JS flag(s) not representable as Ruby Regexp options: g, u, y"]
+
+result.ignored_js_flags
+#=> ["g", "u", "y"]
+```
+
+### Result Object
+
+The `Result` struct provides comprehensive information:
+
+| Method | Description |
+|--------|-------------|
+| `regexp` | The compiled `Regexp` object (or `nil` if compilation failed) |
+| `success?` | Returns `true` if `regexp` is not `nil` |
+| `ruby_source` | The converted Ruby regex pattern string |
+| `ruby_options` | Integer flags (`Regexp::IGNORECASE`, `Regexp::MULTILINE`, etc.) |
+| `ruby_flags_string` | Human-readable flags string (e.g., `"im"`) |
+| `ruby_literal` | Best-effort Ruby literal representation (e.g., `/pattern/im`) |
+| `warnings` | Array of warning messages about the conversion |
+| `ignored_js_flags` | Array of JS flags with no Ruby equivalent |
+| `js_source` | Original JS pattern |
+| `js_flags` | Original JS flags string |
+
+### Without Compilation
+
+If you only need the converted source without compiling:
+
+```ruby
+result = JsRegexToRuby.convert("/^test$/", compile: false)
+result.ruby_source  #=> "\\Atest\\z"
+result.regexp       #=> nil
+```
+
+## Conversion Details
+
+### Flag Mapping
+
+| JS Flag | Ruby Equivalent | Notes |
+|---------|-----------------|-------|
+| `i` | `Regexp::IGNORECASE` | Case-insensitive matching |
+| `s` | `Regexp::MULTILINE` | JS dotAll → Ruby multiline (`.` matches `\n`) |
+| `m` | *(behavior change)* | Keeps `^`/`$` as-is instead of converting to `\A`/`\z` |
+| `g` | *(ignored)* | Global matching - handle in application code |
+| `y` | *(ignored)* | Sticky matching - no equivalent |
+| `u` | *(ignored)* | Unicode mode - Ruby handles Unicode differently |
+| `v` | *(ignored)* | Unicode sets mode - no equivalent |
+| `d` | *(ignored)* | Indices for matches - no equivalent |
+
+### Anchor Conversion
+
+By default (without JS `m` flag):
+- `^` → `\A` (start of string)
+- `$` → `\z` (end of string)
+
+With JS `m` flag:
+- `^` and `$` are preserved (matching line boundaries, which is Ruby's default behavior)
+
+### Inline Modifiers
+
+JavaScript's inline modifier groups are converted:
+
+```ruby
+# JS: (?s:a.c) - dotAll only inside group
+result = JsRegexToRuby.convert("(?s:a.c)")
+result.ruby_source  #=> "(?m:a.c)"
+
+# JS: (?m:^foo$) - multiline anchors inside group
+result = JsRegexToRuby.convert("(?m:^foo$)bar$")
+result.ruby_source  #=> "(?:^foo$)bar\\z"
+```
+
+### Control Character Escapes
+
+JavaScript's `\cX` control escapes are converted to the actual control character:
+
+```ruby
+result = JsRegexToRuby.convert('\\cA')
+result.ruby_source.bytes.first  #=> 1 (Ctrl+A)
+```
+
+### Any Character Class `[^]`
+
+JavaScript's `[^]` matches any character including newlines (equivalent to `[\s\S]`). This is invalid syntax in Ruby, so it's automatically converted:
+
+```ruby
+result = JsRegexToRuby.convert("/a[^]b/")
+result.ruby_source  #=> "a[\\s\\S]b"
+
+# Matches any character including newline
+result.regexp.match?("a\nb")  #=> true
+result.regexp.match?("axb")   #=> true
+```
+
+Note: Negated character classes like `[^abc]` are NOT affected and work as expected.
+
+## Limitations
+
+1. **No runtime flags**: JS flags like `g` (global) and `y` (sticky) affect matching behavior at runtime and have no Ruby `Regexp` equivalent. Handle these in your application logic.
+
+2. **Unicode properties**: `\p{...}` syntax exists in both JS and Ruby but with different property names and semantics. No automatic conversion is performed.
+
+3. **Named capture groups**: Both languages support named groups with identical syntax (`(?<name>...)`), so no conversion is needed.
+
+4. **Backreferences**: Numbered backreferences (`\1`, `\2`) work similarly, but behavior edge cases may differ.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+```bash
+git clone https://github.com/jasl/js_regex_to_ruby.git
+cd js_regex_to_ruby
+bin/setup
+rake test
+```
+
+You can also run `bin/console` for an interactive prompt to experiment with the gem.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jasl/js_regex_to_ruby.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## See Also
+
+- [MDN: Regular Expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)
+- [Ruby Regexp Documentation](https://ruby-doc.org/core/Regexp.html)
+- [js_regex](https://github.com/jaynetics/js_regex) - A similar gem with a different approach
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/js_regex_to_ruby/converter.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+module JsRegexToRuby
+  # Convert an ECMAScript-style regular expression (pattern + flags) into a Ruby Regexp.
+  #
+  # The goal is to preserve behavior as much as Ruby's regex engine allows.
+  #
+  # Key conversions implemented:
+  # - JS /s (dotAll) => Ruby /m (dot-all in Ruby)
+  # - JS /m (multiline anchors) => Ruby has ^/$ multiline by default, so we rewrite ^/$
+  #   to \A/\z when JS multiline is NOT enabled.
+  # - JS inline modifiers (?ims-ims:...) are supported, with mapping s->m and special handling for m.
+  # - JS [^] (match any character including newline) => Ruby [\s\S]
+  # - JS /g, /y, /u, /v, /d have no direct Regexp equivalent; we report them in Result#ignored_js_flags.
+  class Converter
+    JS_KNOWN_FLAGS = %w[d g i m s u v y].freeze
+    JS_GROUP_MOD_FLAGS = %w[i m s].freeze
+
+    # Tracks modifier state during source rewriting (immutable).
+    Context = Data.define(:js_multiline_anchors, :ruby_ignorecase, :ruby_dotall)
+
+    # Parse a JS regex literal like `/foo\\/bar/i`.
+    # Returns [pattern, flags].
+    def self.parse_literal(literal)
+      raise ArgumentError, "literal must be a String" unless literal.is_a?(String)
+
+      s = literal.strip
+      raise ArgumentError, "JS RegExp literal must start with /" unless s.start_with?("/")
+
+      in_class = false
+      escaped = false
+      i = 1
+      while i < s.length
+        ch = s[i]
+        if escaped
+          escaped = false
+          i += 1
+          next
+        end
+
+        if ch == "\\"
+          escaped = true
+          i += 1
+          next
+        end
+
+        if in_class
+          in_class = false if ch == "]"
+          i += 1
+          next
+        end
+
+        case ch
+        when "["
+          in_class = true
+        when "/"
+          pattern = s[1...i]
+          flags = s[(i + 1)..] || ""
+          return [pattern, flags]
+        end
+        i += 1
+      end
+
+      raise ArgumentError, "Unterminated JS RegExp literal (missing closing /)"
+    end
+
+    # Convert a JS regex into a Ruby regex.
+    #
+    # @param input [String] Either a JS literal `/.../flags` or a JS pattern source.
+    # @param flags [String, nil] JS flags if input is not a literal.
+    # @param compile [Boolean] Whether to compile and return a Regexp in the result.
+    # @return [JsRegexToRuby::Result]
+    def self.convert(input, flags: nil, compile: true)
+      warnings = []
+
+      js_source, js_flags = if flags.nil? && looks_like_literal?(input)
+                              parse_literal(input)
+      else
+                              raise ArgumentError, "input must be a String" unless input.is_a?(String)
+                              [input, (flags || "")]
+      end
+
+      js_flags = js_flags.to_s
+      seen_flags, unknown_flags, duplicate_flags = normalize_flags(js_flags)
+
+      warnings << "Unknown JS RegExp flag(s): #{unknown_flags.uniq.join(', ')}" unless unknown_flags.empty?
+      warnings << "Duplicate JS RegExp flag(s) ignored: #{duplicate_flags.uniq.join(', ')}" unless duplicate_flags.empty?
+
+      ignored_js_flags = (seen_flags.keys - %w[i m s]).sort
+
+      unless ignored_js_flags.empty?
+        warnings << "JS flag(s) not representable as Ruby Regexp options: #{ignored_js_flags.join(', ')}"
+      end
+
+      base_js_multiline = seen_flags["m"]
+      base_js_ignorecase = seen_flags["i"]
+      base_js_dotall = seen_flags["s"]
+
+      ruby_options = 0
+      ruby_options |= Regexp::IGNORECASE if base_js_ignorecase
+      ruby_options |= Regexp::MULTILINE if base_js_dotall # Ruby /m is dot-all
+
+      base_ctx = Context.new(
+        js_multiline_anchors: base_js_multiline,
+        ruby_ignorecase: base_js_ignorecase,
+        ruby_dotall: base_js_dotall
+      )
+
+      ruby_source = rewrite_source(js_source, base_ctx, warnings)
+
+      regexp = nil
+      if compile
+        begin
+          regexp = Regexp.new(ruby_source, ruby_options)
+        rescue RegexpError => e
+          warnings << "Ruby RegexpError: #{e.message}"
+          regexp = nil
+        end
+      end
+
+      Result.new(
+        ruby_source: ruby_source,
+        ruby_options: ruby_options,
+        regexp: regexp,
+        warnings: warnings,
+        ignored_js_flags: ignored_js_flags,
+        js_source: js_source,
+        js_flags: js_flags
+      )
+    end
+
+    def self.looks_like_literal?(s)
+      s.is_a?(String) && s.lstrip.start_with?("/")
+    end
+
+    def self.normalize_flags(flags)
+      seen = {}
+      unknown = []
+      duplicates = []
+
+      flags.each_char do |c|
+        if seen.key?(c)
+          duplicates << c
+          next
+        end
+        if JS_KNOWN_FLAGS.include?(c)
+          seen[c] = true
+        else
+          unknown << c
+          seen[c] = true
+        end
+      end
+
+      [seen, unknown, duplicates]
+    end
+
+    # Rewrite JS source to Ruby source.
+    #
+    # - Converts ^/$ depending on whether JS multiline-anchors mode is enabled in the current scope.
+    # - Converts inline modifiers (?ims-ims:...) into Ruby equivalents (i and m only; s->m).
+    # - Converts JS control escapes (\cA ... \cZ) to the actual control character.
+    # - Converts JS [^] (any character) to Ruby [\s\S].
+    def self.rewrite_source(src, base_ctx, warnings)
+      out = +""
+      in_class = false
+      stack = [base_ctx]
+
+      i = 0
+      while i < src.length
+        ch = src[i]
+
+        if in_class
+          if ch == "\\"
+            # handle escapes inside class
+            if control_escape_at?(src, i)
+              out << control_char(src[i + 2])
+              i += 3
+              next
+            end
+
+            out << ch
+            if i + 1 < src.length
+              out << src[i + 1]
+              i += 2
+            else
+              i += 1
+            end
+            next
+          end
+
+          out << ch
+          in_class = false if ch == "]"
+          i += 1
+          next
+        end
+
+        case ch
+        when "\\"
+          if control_escape_at?(src, i)
+            out << control_char(src[i + 2])
+            i += 3
+          else
+            out << ch
+            if i + 1 < src.length
+              out << src[i + 1]
+              i += 2
+            else
+              i += 1
+            end
+          end
+
+        when "["
+          # Check for [^] which matches any character (including newline) in JS
+          # This is invalid syntax in Ruby, so convert to [\s\S]
+          if src[i + 1] == "^" && src[i + 2] == "]"
+            out << "[\\s\\S]"
+            i += 3
+          else
+            in_class = true
+            out << ch
+            i += 1
+          end
+
+        when "("
+          # Try parse JS modifier group: (?ims-ims:...)
+          mod = parse_js_modifier_group(src, i)
+          if mod
+            current = stack.last
+            desired = apply_js_group_modifiers(current, mod[:enable], mod[:disable])
+
+            ruby_prefix = build_ruby_modifier_prefix(current, desired)
+            out << ruby_prefix
+
+            stack << desired
+            i = mod[:after_colon]
+          else
+            out << "("
+            stack << stack.last
+            i += 1
+          end
+
+        when ")"
+          out << ")"
+          if stack.length > 1
+            stack.pop
+          else
+            warnings << "Unbalanced ) in source; continuing"
+          end
+          i += 1
+
+        when "^"
+          if stack.last.js_multiline_anchors
+            out << "^"
+          else
+            out << '\\A'
+          end
+          i += 1
+
+        when "$"
+          if stack.last.js_multiline_anchors
+            out << "$"
+          else
+            out << '\\z'
+          end
+          i += 1
+
+        else
+          out << ch
+          i += 1
+        end
+      end
+
+      warnings << "Unbalanced ( in source: #{stack.length - 1} group(s) not closed" if stack.length > 1
+      warnings << "Unterminated character class ([...) in source" if in_class
+
+      out
+    end
+
+    def self.control_escape_at?(src, index)
+      return false unless src[index] == "\\"
+      return false unless src[index + 1] == "c"
+      letter = src[index + 2]
+      !!(letter && letter.match?(/[A-Za-z]/))
+    end
+
+    def self.control_char(letter)
+      # MDN: \cX where X is A-Z maps to the character code of X modulo 32.
+      # (A->1, B->2, ... Z->26)
+      (letter.ord & 0x1F).chr
+    end
+
+    # If a modifier group begins at src[index] (which should be '('),
+    # returns { enable: 'im', disable: 's', after_colon: <index after ':'> }.
+    # Otherwise returns nil.
+    def self.parse_js_modifier_group(src, index)
+      return nil unless src[index] == "("
+      return nil unless src[index + 1] == "?"
+
+      j = index + 2
+      enable = +""
+      while (c = src[j]) && JS_GROUP_MOD_FLAGS.include?(c)
+        enable << c
+        j += 1
+      end
+
+      disable = +""
+      if src[j] == "-"
+        j += 1
+        while (c = src[j])
+          break unless JS_GROUP_MOD_FLAGS.include?(c)
+          disable << c
+          j += 1
+        end
+      end
+
+      return nil unless src[j] == ":"
+      return nil if enable.empty? && disable.empty?
+
+      {
+        enable: enable,
+        disable: disable,
+        after_colon: j + 1,
+      }
+    end
+
+    def self.apply_js_group_modifiers(current, enable, disable)
+      js_m = current.js_multiline_anchors
+      ruby_i = current.ruby_ignorecase
+      ruby_dotall = current.ruby_dotall
+
+      enable.each_char do |f|
+        case f
+        when "m" then js_m = true
+        when "i" then ruby_i = true
+        when "s" then ruby_dotall = true
+        end
+      end
+
+      disable.each_char do |f|
+        case f
+        when "m" then js_m = false
+        when "i" then ruby_i = false
+        when "s" then ruby_dotall = false
+        end
+      end
+
+      current.with(
+        js_multiline_anchors: js_m,
+        ruby_ignorecase: ruby_i,
+        ruby_dotall: ruby_dotall
+      )
+    end
+
+    def self.build_ruby_modifier_prefix(current, desired)
+      enable = +""
+      disable = +""
+
+      if desired.ruby_ignorecase != current.ruby_ignorecase
+        (desired.ruby_ignorecase ? enable : disable) << "i"
+      end
+
+      # JS dotAll (s) maps to Ruby /m (dot-all)
+      if desired.ruby_dotall != current.ruby_dotall
+        (desired.ruby_dotall ? enable : disable) << "m"
+      end
+
+      if enable.empty? && disable.empty?
+        "(?:"
+      elsif disable.empty?
+        "(?#{enable}:"
+      elsif enable.empty?
+        "(?-#{disable}:"
+      else
+        "(?#{enable}-#{disable}:"
+      end
+    end
+
+    private_class_method :looks_like_literal?, :normalize_flags,
+                         :rewrite_source, :control_escape_at?, :control_char,
+                         :parse_js_modifier_group, :apply_js_group_modifiers,
+                         :build_ruby_modifier_prefix
+  end
+end

data/lib/js_regex_to_ruby/result.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module JsRegexToRuby
+  # A conversion outcome (immutable value object).
+  #
+  # @!attribute [r] ruby_source
+  #   @return [String] Ruby regex source (not wrapped with /.../)
+  # @!attribute [r] ruby_options
+  #   @return [Integer] Regexp option bits (IGNORECASE, MULTILINE, etc.)
+  # @!attribute [r] regexp
+  #   @return [Regexp, nil] Compiled Regexp, or nil if compile: false or compilation failed
+  # @!attribute [r] warnings
+  #   @return [Array<String>] Warning messages from conversion
+  # @!attribute [r] ignored_js_flags
+  #   @return [Array<String>] Flags that have no direct Ruby Regexp equivalent
+  # @!attribute [r] js_source
+  #   @return [String] Original JS pattern source
+  # @!attribute [r] js_flags
+  #   @return [String] Original JS flags string
+  Result = Data.define(
+    :ruby_source,
+    :ruby_options,
+    :regexp,
+    :warnings,
+    :ignored_js_flags,
+    :js_source,
+    :js_flags
+  ) do
+    def success?
+      !regexp.nil?
+    end
+
+    def ruby_flags_string
+      s = +""
+      s << "i" if (ruby_options & Regexp::IGNORECASE) != 0
+      s << "m" if (ruby_options & Regexp::MULTILINE) != 0
+      s
+    end
+
+    # Best-effort Ruby literal representation (not necessarily re-escapable).
+    def ruby_literal
+      "/#{ruby_source.gsub("/", "\\/")}/#{ruby_flags_string}"
+    end
+  end
+end

data/lib/js_regex_to_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JsRegexToRuby
+  VERSION = "0.1.1"
+end

data/lib/js_regex_to_ruby.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "js_regex_to_ruby/version"
+require_relative "js_regex_to_ruby/result"
+require_relative "js_regex_to_ruby/converter"
+
+module JsRegexToRuby
+  # Convenience API.
+  #
+  # @example
+  #   JsRegexToRuby.convert('/^foo$/i').regexp #=> /\Afoo\z/i
+  def self.convert(input, flags: nil, compile: true)
+    Converter.convert(input, flags: flags, compile: compile)
+  end
+
+  # Try to convert a JS regex to Ruby Regexp.
+  # Returns the compiled Regexp on success, or nil on failure.
+  # Never raises exceptions for invalid input.
+  #
+  # @example
+  #   JsRegexToRuby.try_convert('/^foo$/i')  #=> /\Afoo\z/i
+  #   JsRegexToRuby.try_convert('not a regex')  #=> nil
+  #   JsRegexToRuby.try_convert('/invalid[/') #=> nil
+  #
+  # @param input [String] Either a JS literal `/.../flags` or a JS pattern source.
+  # @param flags [String, nil] JS flags if input is not a literal.
+  # @return [Regexp, nil] The compiled Ruby Regexp, or nil if conversion/compilation failed.
+  def self.try_convert(input, flags: nil)
+    result = Converter.convert(input, flags: flags, compile: true)
+    result.regexp
+  rescue ArgumentError, RegexpError
+    nil
+  end
+
+  def self.parse_literal(literal)
+    Converter.parse_literal(literal)
+  end
+end

data/sig/js_regex_to_ruby.rbs

@@ -0,0 +1,64 @@
+module JsRegexToRuby
+  VERSION: String
+
+  # Convenience API to convert a JS regex to Ruby
+  def self.convert: (String input, ?flags: String?, ?compile: bool) -> Result
+
+  # Try to convert a JS regex to Ruby Regexp, returns nil on failure
+  def self.try_convert: (String input, ?flags: String?) -> Regexp?
+
+  # Parse a JS regex literal into pattern and flags
+  def self.parse_literal: (String literal) -> [String, String]
+
+  # Conversion result (immutable value object)
+  class Result < Data
+    attr_reader ruby_source: String
+    attr_reader ruby_options: Integer
+    attr_reader regexp: Regexp?
+    attr_reader warnings: Array[String]
+    attr_reader ignored_js_flags: Array[String]
+    attr_reader js_source: String
+    attr_reader js_flags: String
+
+    def self.new: (
+      ruby_source: String,
+      ruby_options: Integer,
+      regexp: Regexp?,
+      warnings: Array[String],
+      ignored_js_flags: Array[String],
+      js_source: String,
+      js_flags: String
+    ) -> Result
+
+    # Returns true if regexp compilation succeeded
+    def success?: () -> bool
+
+    # Returns Ruby flags as a string (e.g., "im")
+    def ruby_flags_string: () -> String
+
+    # Returns a Ruby literal representation
+    def ruby_literal: () -> String
+  end
+
+  # Converter class for JS to Ruby regex conversion
+  class Converter
+    JS_KNOWN_FLAGS: Array[String]
+    JS_GROUP_MOD_FLAGS: Array[String]
+
+    # Parse a JS regex literal like `/foo\\/bar/i`
+    def self.parse_literal: (String literal) -> [String, String]
+
+    # Convert a JS regex into a Ruby regex
+    def self.convert: (String input, ?flags: String?, ?compile: bool) -> Result
+
+    # Context for tracking modifier state during rewriting (immutable)
+    class Context < Data
+      attr_reader js_multiline_anchors: bool?
+      attr_reader ruby_ignorecase: bool?
+      attr_reader ruby_dotall: bool?
+
+      def self.new: (js_multiline_anchors: bool?, ruby_ignorecase: bool?, ruby_dotall: bool?) -> Context
+      def with: (?js_multiline_anchors: bool?, ?ruby_ignorecase: bool?, ?ruby_dotall: bool?) -> Context
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: js_regex_to_ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- jasl
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A Ruby gem that converts ECMAScript (JavaScript) regular expressions to Ruby Regexp objects,
+  preserving behavior as closely as Ruby's regex engine allows. Handles flag mapping (i, s, m),
+  anchor conversion (^/$ to \A/\z), inline modifiers, and control character escapes.
+  Emits warnings for JS features without direct Ruby equivalents (g, y, u, v, d flags).
+email:
+- jasl9187@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/js_regex_to_ruby.rb
+- lib/js_regex_to_ruby/converter.rb
+- lib/js_regex_to_ruby/result.rb
+- lib/js_regex_to_ruby/version.rb
+- sig/js_regex_to_ruby.rbs
+homepage: https://github.com/jasl/js_regex_to_ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jasl/js_regex_to_ruby
+  bug_tracker_uri: https://github.com/jasl/js_regex_to_ruby/issues
+  documentation_uri: https://github.com/jasl/js_regex_to_ruby#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Convert JavaScript regular expressions to Ruby Regexp objects
+test_files: []