json-repair 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83ede681caac8ebbc294902937c8af11ebc90fe066beed41e15013782fbd0b96
-  data.tar.gz: da309d72a1c564f05dd405c02115985572c38c8b2c28aad85f778b94cc2a68e9
+  metadata.gz: b4892b62960d0c4d27976577c506585ea8df11bfbf14dc1a9b40952947ad1f20
+  data.tar.gz: fe26e3da464e5356bd33021e5b08a7a1f1ad938e125f0ef384777ff64b13f813
 SHA512:
-  metadata.gz: da63df705106d20701700dd55712ed06676cdb4e6615f36d915cae12f3bdf7ac085ea919a553c77e8e0876663e5ad7d0067b46b00fddd3a7cca837eb38e54fc8
-  data.tar.gz: d4471c07b5a3a39505ec890b8afc359ca12fa3042c953143675af2d88bd8a4f56fe6225f00e0d4665eaf66465862f2b273929a2bb7fd54a81f79f1abf39ecfa1
+  metadata.gz: 4cf46eae9e05e718c978e7a503578bd867bacce1b71565764ec88af8b762f498ceceada6ce37d73663e6bcff56b85013746c7a82e84eda6eb55ed57e3535fe0d
+  data.tar.gz: f2fc802dd1bfbd26bb04f34ca2902189d11537d4bbbebc131d14ef7672bcd9f2dd01bcc2157182ba6801eea0f92693883086197013add4f86f69e6fcf32e5a3b

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changes
 
+### 2026-05-12 (0.6.0)
+
+* `JSON.repair` accepts a `return_objects:` keyword argument. Pass
+  `return_objects: true` to receive the parsed Ruby value (Hash, Array,
+  or scalar) instead of a serialized JSON string. Default is `false`,
+  preserving the existing return-a-string contract. Mirrors Python's
+  `return_objects` option on
+  [`json_repair`](https://github.com/mangiucugna/json_repair).
+
 ### 2026-05-12 (0.5.0)
 
 * `JSON::JSONRepairError#position` returns the input index at which the

data/CLAUDE.md

@@ -5,13 +5,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Commands
 
 - `bin/setup` — install dependencies via Bundler.
-- `bundle exec rake` — default task; runs both RSpec and RuboCop.
+- `bundle exec rake` — default task; runs RSpec, RuboCop, RBS validate, and Steep.
 - `bundle exec rspec` — run the test suite.
 - `bundle exec rspec spec/json_spec.rb:42` — run a single example by line number; nearly all behavioral specs live in `spec/json_spec.rb`.
 - `bundle exec rubocop` — lint. Project-specific exclusions in `.rubocop.yml` deliberately disable several `Metrics/*` cops for `lib/json/repairer.rb` and `lib/json/repair/string_utils.rb` because the parser is long by design — don't try to "fix" it by chopping methods up.
 - `bin/console` — IRB with the gem preloaded.
 - `bundle exec rake install` / `bundle exec rake release` — local install / publish to rubygems.org.
-- Type checking: `Steepfile` checks `lib/` against `sig/`. Run `bundle exec steep check` if/when steep is installed (not in `Gemfile` by default).
+- Type checking: `Steepfile` checks `lib/` against `sig/`. `bundle exec steep check` (typecheck) and `bundle exec rbs validate` (sig syntax) both run in CI and as part of the default rake task. `steep` and `rbs` are dev dependencies in the `Gemfile`.
 
 Ruby `>= 3.0.0` is required (per gemspec). CI runs against Ruby 3.3.1.
 

data/README.md

@@ -31,6 +31,13 @@ puts repaired_json  # Outputs: {"name": "Alice", "age": 25}
 
 The `repair` method takes a string containing JSON data and returns a corrected version of this string, ensuring it is valid JSON.
 
+Pass `return_objects: true` to get the parsed Ruby value (Hash, Array, or scalar) instead of a string:
+
+```ruby
+JSON.repair('{a: 1, b: [2, 3,]}', return_objects: true)
+# => {"a" => 1, "b" => [2, 3]}
+```
+
 ## Command line
 
 The gem ships a `json-repair` executable. It reads from stdin or a file and writes to stdout, `--output FILE`, or back over the input file with `--overwrite`.

data/Rakefile

@@ -9,4 +9,14 @@ require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+desc 'Validate RBS signatures in sig/'
+task :rbs do
+  sh 'bundle exec rbs validate'
+end
+
+desc 'Run Steep type check against sig/'
+task :steep do
+  sh 'bundle exec steep check'
+end
+
+task default: %i[spec rubocop rbs steep]

data/Steepfile

@@ -3,4 +3,9 @@
 target :lib do
   signature 'sig'
   check 'lib'
+
+  library 'optparse'
+  library 'tempfile'
+  library 'fileutils'
+  library 'json'
 end

data/lib/json/repair/cli.rb

@@ -34,7 +34,8 @@ module JSON
 
       def run(argv)
         positional = catch(:halt) { parser.parse(argv) }
-        return @halt if @halt
+        halt = @halt
+        return halt if halt
 
         input_path = positional.first
         return 1 unless validate(positional, input_path)
@@ -61,7 +62,7 @@ module JSON
       end
 
       def read_input(input_path)
-        raw = input_path ? File.read(input_path) : @stdin.read
+        raw = (input_path ? File.read(input_path) : @stdin.read).to_s
         raw.force_encoding(Encoding::UTF_8)
         raise JSON::JSONRepairError, 'input is not valid UTF-8' unless raw.valid_encoding?
 
@@ -69,10 +70,10 @@ module JSON
       end
 
       def write_output(repaired, input_path)
-        if @overwrite
+        if @overwrite && input_path
           replace_in_place(input_path, repaired)
-        elsif @output_path
-          File.write(@output_path, repaired)
+        elsif (output_path = @output_path)
+          File.write(output_path, repaired)
         else
           @stdout.write(repaired)
           @stdout.write("\n") unless repaired.end_with?("\n")

data/lib/json/repair/version.rb

@@ -2,6 +2,6 @@
 
 module JSON
   module Repair
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/json/repair.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 require_relative 'repair/version'
 require_relative 'repairer'
 
@@ -13,7 +15,8 @@ module JSON
     end
   end
 
-  def self.repair(json)
-    Repairer.new(json).repair
+  def self.repair(json, return_objects: false)
+    repaired = Repairer.new(json).repair
+    return_objects ? JSON.parse(repaired) : repaired
   end
 end

data/lib/json/repairer.rb

@@ -227,9 +227,19 @@ module JSON
           if processed_colon || truncated_text
             # repair missing object value
             @output << 'null'
+          # :nocov:
           else
+            # Unreachable through JSON.repair: if we got here, the colon-repair
+            # branch above ran, which required start_of_value? to be true. Every
+            # char that satisfies start_of_value? (see REGEX_START_OF_VALUE plus
+            # quote chars) is consumable by some parse_* method, so parse_value
+            # cannot return false in this state. Preserved for parity with the
+            # upstream JS parser; if a future change to REGEX_START_OF_VALUE or
+            # parse_unquoted_string invalidates that invariant, this branch
+            # becomes live and the :nocov: will hide it.
             throw_colon_expected
           end
+          # :nocov:
         end
       end
 
@@ -725,10 +735,10 @@ module JSON
         processed_value = parse_value
       end
 
-      unless processed_value
-        # repair: remove trailing comma
-        @output = strip_last_occurrence(@output, ',')
-      end
+      # repair: remove trailing comma
+      # (the `while processed_value` loop above only exits when processed_value
+      # is falsy, so the upstream JS `if (!processedValue)` guard is redundant)
+      @output = strip_last_occurrence(@output, ',')
 
       # repair: wrap the output inside array brackets
       @output = "[\n#{@output}\n]"

data/sig/json/repair/cli.rbs

@@ -1,16 +1,47 @@
 module JSON
   module Repair
     class CLI
-      # `::IO | ::StringIO` because `::StringIO` is not an `::IO` subclass; the
-      # specs inject `::StringIO` instances and any other duck-typed stream
-      # that implements `#read` / `#write` / `#puts` would work too.
+      # `::IO | ::StringIO` because `::StringIO` is not an `::IO` subclass
+      # and the specs inject `::StringIO` instances.
       type stream = ::IO | ::StringIO
 
+      # Marked `private_constant` in `lib/json/repair/cli.rb`. RBS has no
+      # `private_constant` syntax, so the declaration is unavoidably public
+      # in the signature; do not rely on it from outside this class.
+      OVERWRITE_DESC: ::String
+
+      @stdin: stream
+      @stdout: stream
+      @stderr: stream
+      @output_path: ::String?
+      @halt: ::Integer?
+      @overwrite: bool
+
       def self.call: (::Array[::String] argv, ?stdin: stream, ?stdout: stream, ?stderr: stream) -> ::Integer
 
       def initialize: (?stdin: stream, ?stdout: stream, ?stderr: stream) -> void
 
       def call: (::Array[::String] argv) -> ::Integer
+
+      private
+
+      def run: (::Array[::String] argv) -> ::Integer
+
+      def validate: (::Array[::String] positional, ::String? input_path) -> bool
+
+      def validation_error: (::Array[::String] positional, ::String? input_path) -> ::String?
+
+      def read_input: (::String? input_path) -> ::String
+
+      def write_output: (::String repaired, ::String? input_path) -> void
+
+      def replace_in_place: (::String input_path, ::String repaired) -> void
+
+      def parser: () -> ::OptionParser
+
+      def define_options: (::OptionParser opts) -> void
+
+      def halt_with: (::String message) -> void
     end
   end
 end

data/sig/json/repair.rbs

@@ -10,4 +10,6 @@ module JSON
   end
 
   def self.repair: (::String json) -> ::String
+                 | (::String json, return_objects: false) -> ::String
+                 | (::String json, return_objects: true) -> untyped
 end

data/sig/json/repairer.rbs

@@ -1,6 +1,15 @@
 module JSON
   class Repairer
-    @json: ::String
+    # `untyped` (not `::String`) because the parser idiomatically uses
+    # `@json[@index]` past EOF, relying on Ruby returning `nil` as a
+    # sentinel. Declaring `@json: ::String` makes steep infer `String?`
+    # from `String#[]` and rejects ~15 downstream call sites that pass
+    # the result to methods expecting `String`. Tightening would either
+    # require pervasive nil-extraction at every indexing site or a
+    # private accessor — both of which break parity with the upstream
+    # JS source (see CLAUDE.md and `.rubocop.yml` exceptions for
+    # `lib/json/repairer.rb`).
+    @json: untyped
 
     @index: Integer
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json-repair
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Aleksandr Zykov