kochab 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a614b6dc35cf6bb101732526b9679f51fedd2f4b48a39737d7eca3161fcdbc9
+  data.tar.gz: 055f80b9abb6f3e339bd5fb7949f53b0a83f7c542377b255d8a715205e0789c7
+SHA512:
+  metadata.gz: fa6984ae1709b30cc8b0cfecaf09a52c03e493cc47f5f485f04ad6d084e1a3f452e3150ac09e3717eb111db3af397522560410bfacd4f8c11e22df69aee6b26b
+  data.tar.gz: 524c84d838078662b7881f26f1ded5b5843a40c80a5fd5aea47d7d88c88638f1dbbdbee170f09470daa95c8fc6ba590ad2b837ab66ffc3918aed0ec975a350ed

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — 2026-09-11
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,205 @@
+# Kochab
+
+JSONC parsing with byte ranges, error recovery, and edits that preserve the
+surrounding comments and formatting. Ruby 3.1+, no runtime gem dependencies,
+no custom native extension. Ruby's standard `json` library handles string
+escapes and value serialization; scanning, recovery, and edits are Ruby code.
+
+Kochab are annotations written in a manuscript's margins. `gloss` and `glossa`
+were registered on RubyGems; `kochab` was available when checked on
+2026-09-09. Availability is not a reservation. This checkout is not published.
+
+## Installation
+
+From this checkout:
+
+```sh
+gem build kochab.gemspec
+gem install ./kochab-0.1.0.gem
+```
+
+Or use `gem "kochab", path: "/path/to/checkout"` in your Gemfile.
+
+## Parse and update a setting
+
+```ruby
+require "kochab"
+
+text = <<~JSONC
+  {
+    // Font size in points
+    "editor": { "font_size": 12, "theme": "dark" },
+  }
+JSONC
+
+doc = Kochab.parse(text)
+doc.value                              # {"editor" => {"font_size" => 12, ...}}
+doc.valid?                             # true
+doc.errors                             # []
+
+edits = doc.set(["editor", "font_size"], 14)
+updated = Kochab.apply(text, edits)
+raise unless updated == text.sub("12", "14")
+```
+
+Every offset and range is measured in **UTF-8 bytes**, and ranges exclude the
+end offset. Ruby `String#[]` indexes characters: use `String#byteslice(range)`
+to extract source ranges. Input strings are treated as UTF-8 bytes; other
+encodings are not transcoded because that would change their offsets.
+
+## Source queries
+
+```ruby
+range = doc.range_of(["editor", "font_size"])
+text.byteslice(range)                       # "12"
+doc.key_range_of(["editor", "font_size"])   # includes the key's quotes
+doc.node_at(range.begin).kind               # :number
+doc.path_at(range.begin)                    # ["editor", "font_size"]
+position = doc.utf16_position_at(range.begin) # [line, UTF-16 column], zero-based
+doc.offset_at_utf16_position(*position)      # inverse conversion
+```
+
+Array paths use nonnegative integer indices. Missing paths return `nil`.
+`node_at` descends by binary search through sorted children. Whitespace inside
+a container resolves to that container; offsets outside the root return `nil`.
+UTF-16 conversions reject out-of-range positions, split UTF-8 characters,
+split surrogate pairs, and invalid UTF-8. LF, CRLF, and CR are recognized.
+Positions inside a CRLF delimiter map to the preceding line's end.
+
+Nodes expose `kind`, `range`, `key_range`, `value`, `children`,
+`leading_comments`, `trailing_comment`, `parent`, and `key`. Kinds are
+`:object`, `:array`, `:property`, `:string`, `:number`, `:boolean`, and `:null`.
+Property nodes have one value child; a missing value is a zero-length `:null`
+node. Containers' `value` fields contain their Ruby Hash or Array values.
+Treat the tree and its values as read-only snapshots. `doc.text` is frozen.
+
+## Recovery and strict mode
+
+The default parser consumes the complete input and reports syntax problems in
+`doc.errors`, including invalid UTF-8. It returns the best available value:
+
+```ruby
+doc = Kochab.parse('{"a" 1, "b": , "c": 3}')
+doc.value                 # {"a" => 1, "b" => nil, "c" => 3}
+doc.errors.map(&:code)    # [:expected_colon, :expected_value]
+doc.valid?                # false
+
+Kochab.parse('{"a":1}', strict: true) # standard JSON only
+```
+
+`strict: true` raises `Kochab::ParseError` for invalid syntax and exposes
+all diagnostics through the exception's `errors`. Comments, a BOM, trailing
+commas, and named non-finite numbers are rejected in strict mode. Duplicate
+keys produce `:duplicate_key` warnings and the last occurrence wins; warnings
+do not make `valid?` false. Diagnostic fields are `range`, `code`, `message`,
+and `severity` (`:error` or `:warning`).
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `trailing_commas` | `true` | Set to `false` to diagnose trailing commas |
+| `allow_nan` | `false` | Opt into `NaN`, `Infinity`, `-Infinity` literals |
+| `max_depth` | `512` | Maximum nesting depth; configurable from 1 to 512 |
+
+Unfinished strings end at a line break or EOF; missing colons and commas are
+diagnosed and recovered; unmatched closing brackets are skipped. Overdeep
+subtrees are skipped iteratively and replaced by `nil`. This bounds the Ruby
+call stack while still consuming the document. Integers retain arbitrary
+precision; floats follow Ruby JSON's overflow/underflow behavior. JSON5 features
+(unquoted keys, single quotes, hexadecimal numbers) are excluded. Wrong
+argument types still raise normal Ruby exceptions.
+
+All comments are available as `doc.comments`; each has `range`, `text`, and
+`:line` or `:block` `kind`. Contiguous comments immediately above a node attach
+as `leading_comments`. A same-line comment after a value attaches to that
+value's `trailing_comment`. Comments separated by a blank line, and additional
+comments that cannot occupy the single trailing slot, are `floating_comments`.
+Comment text always retains its original delimiters and bytes.
+
+## Minimal edits
+
+```ruby
+doc.set(["editor", "font_size"], 14)                 # replace one value
+doc.insert(["editor", "language"], "ja", after: "theme")
+doc.remove(["editor", "theme"])                      # delete member + comma
+doc.insert(["recent_files", 0], "/tmp/notes.txt")     # insert into an array
+doc.set([], {"new_root" => true})                     # replace the root
+```
+
+Each method returns `TextEdit` objects with `offset`, `length`, and `text`.
+`set` changes only the value's byte span and can repair an unfinished value;
+it inserts a missing final member when its parent exists. `insert` rejects an
+existing object key; omitted `after` appends. `remove` removes every duplicate
+occurrence of the requested object key; an absent key is a no-op.
+
+Insertion preserves all existing bytes. Removal deletes the requested node
+and its required comma, leaving unrelated whitespace and comments intact.
+Comments inside a removed/replaced subtree belong to that subtree and are
+removed with it. Removing a node can leave blank lines or detached comments.
+`insert` and `remove` require a valid document; `set` can repair a recovered
+node using its recorded value span.
+
+Edits use the original snapshot's coordinates. Reparse after applying edits
+before generating further edits. `apply` validates bounds, UTF-8 boundaries,
+replacement encoding, and overlap. Same-offset insertions are concatenated in
+input order; insertions at a replacement's start precede that replacement.
+It builds the output in one pass without mutating the original string.
+
+## Formatting
+
+```ruby
+pretty = Kochab.format(text, indent: 2, keep_blank_lines: 1)
+```
+
+Formatting normalizes indentation and spacing, preserves every comment and
+literal token verbatim (including escaped strings and trailing commas), uses
+the first newline style present in the input, and appends one final newline.
+`keep_blank_lines` limits consecutive blank lines between tokens. Formatting
+rejects invalid documents to avoid discarding incomplete input. Use minimal
+edits when existing whitespace must be preserved exactly.
+
+## Validation and performance
+
+```sh
+bundle install
+bundle exec rake test          # complete suite, including fuzz and JSON oracle
+bundle exec rake test:oracle   # all 318 pinned upstream JSONTestSuite cases
+bundle exec rake test:fuzz     # 200 recovery cases + 5,000 random/mutated inputs
+bundle exec rake isolation
+bundle exec rake bench:assert  # Ruby with YJIT; machine-dependent budgets
+ruby -Ilib examples/settings.rb
+```
+
+Tests include all `y_`, `n_`, and `i_` parsing cases from
+[JSONTestSuite](https://github.com/nst/JSONTestSuite), pinned in
+`test/fixtures/json_test_suite/PROVENANCE.md` with its MIT license. Every `y_`
+case must pass and every `n_` case must fail; upstream explicitly permits either
+outcome for `i_` cases. Valid inputs are also checked against `JSON.parse`.
+Recovery/fuzz tests check termination, source preservation, and bounded ranges.
+Edit tests check exact replacement bytes and preservation of unrelated comments.
+
+Measured on macOS arm64, Ruby 4.0.0 with YJIT (2026-09-09), seven-sample medians:
+
+| Operation | Observed | Budget |
+| --- | ---: | ---: |
+| Parse 10,256-byte JSONC | 1.13 ms | 2 ms |
+| Parse 1,048,594-byte JSONC | 157.5 ms | 200 ms |
+| Query `node_at` | < 1 µs | 10 µs |
+| Generate a `set` edit | 2 µs | 1 ms |
+
+The corpus contains nested settings, UTF-8 strings, and one comment per setting.
+Run `bench/benchmark.rb` on your deployment machine; these are measurements,
+not timing guarantees. CI uses three times these limits on shared runners.
+Parsing uses memory proportional to input size. Queries
+cost O(depth × log siblings). Object path lookup scans members, whereas
+byte-position queries use binary search.
+
+CI tests Ruby 3.1, 3.2, 3.3, 3.4, and 4.0 on Linux, macOS, and Windows. Performance
+budgets run separately on Linux with Ruby 4.0 and YJIT. Built-gem installation
+and the example are smoke-tested in CI.
+
+## License
+
+MIT; see [LICENSE.txt](LICENSE.txt). Vendored test data retains its original
+MIT notice. The implementation does not depend on `jsonc-parser`; its
+[source API](https://github.com/microsoft/node-jsonc-parser) is a reference for
+the editor-facing behavior.

data/examples/settings.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "kochab"
+
+source = <<~JSONC
+  {
+    // Size in points; this comment survives the update.
+    "editor": { "font_size": 12, "theme": "dark" },
+  }
+JSONC
+
+document = Kochab.parse(source)
+updated = Kochab.apply(source, document.set(["editor", "font_size"], 14))
+puts updated
+raise "Unexpected edit" unless updated == source.sub("12", "14")
+
+document = Kochab.parse(updated)
+puts "Font size bytes: #{document.range_of(['editor', 'font_size'])}"
+puts "LSP position: #{document.utf16_position_at(document.range_of(['editor', 'font_size']).begin)}"

data/lib/kochab/document.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Kochab
+  # A parsed source snapshot. Edits refer to this snapshot and do not mutate it.
+  class Document
+    attr_reader :text, :root, :errors, :comments, :floating_comments
+
+    def initialize(text, root, errors, comments, tokens)
+      @text, @root, @errors, @comments, @tokens = text, root, errors, comments, tokens
+      @floating_comments = []
+    end
+
+    def value
+      @root&.value
+    end
+
+    def valid?
+      @errors.none? { |error| error.severity == :error }
+    end
+
+    # Deepest node covering a byte offset. Whitespace belongs to its container.
+    def node_at(offset)
+      return nil unless offset.is_a?(Integer) && @root && @root.range.cover?(offset)
+
+      current = @root
+      loop do
+        child = current.children.bsearch { |entry| entry.range.end > offset }
+        return current unless child&.range&.cover?(offset)
+
+        current = child
+      end
+    end
+
+    def path_at(offset)
+      current = node_at(offset)
+      return nil unless current
+
+      path = []
+      while current.parent
+        path << current.key if current.kind == :property || current.parent.kind == :array
+        current = current.parent
+      end
+      path.reverse
+    end
+
+    def range_of(path)
+      entry = find_node(path)
+      entry = entry.children.first if entry&.kind == :property
+      entry&.range
+    end
+
+    def key_range_of(path)
+      find_node(path)&.key_range
+    end
+
+    # LSP positions count UTF-16 code units, with zero-based lines/columns.
+    def utf16_position_at(offset)
+      raise EncodingError, "LSP positions require valid UTF-8" unless @text.valid_encoding?
+      check_byte_offset(offset)
+      line = (line_starts.bsearch_index { |start| start > offset } || line_starts.length) - 1
+      prefix = @text.byteslice(line_starts[line]...offset).scrub.sub(/[\r\n]+\z/, "")
+      [line, prefix.encode(Encoding::UTF_16LE).bytesize / 2]
+    end
+
+    def offset_at_utf16_position(line, character)
+      raise EncodingError, "LSP positions require valid UTF-8" unless @text.valid_encoding?
+      unless line.is_a?(Integer) && character.is_a?(Integer) && line >= 0 && character >= 0 && line < line_starts.length
+        raise RangeError, "UTF-16 position is outside the document"
+      end
+      start = line_starts[line]
+      finish = line_starts[line + 1] || @text.bytesize
+      content = @text.byteslice(start...finish).scrub.sub(/[\r\n]+\z/, "")
+      units, bytes = 0, 0
+      content.each_char do |char|
+        break if units == character
+
+        units += char.ord > 0xffff ? 2 : 1
+        raise RangeError, "UTF-16 position splits a surrogate pair" if units > character
+        bytes += char.bytesize
+      end
+      raise RangeError, "UTF-16 position is past the line end" unless units == character
+
+      start + bytes
+    end
+
+    private
+
+    def check_byte_offset(offset)
+      unless offset.is_a?(Integer) && (0..@text.bytesize).cover?(offset)
+        raise RangeError, "Byte offset is outside the document"
+      end
+      byte = @text.getbyte(offset)
+      raise RangeError, "Byte offset splits a UTF-8 character" if @text.valid_encoding? && byte && byte & 0xc0 == 0x80
+    end
+
+    def line_starts
+      @line_starts ||= begin
+        result = [0]
+        @text.b.to_enum(:scan, /\r\n|\r|\n/n).each { result << Regexp.last_match.end(0) }
+        result
+      end
+    end
+
+    def find_node(path)
+      raise TypeError, "path must be an Array" unless path.is_a?(Array)
+
+      path.reduce(@root) do |parent, key|
+        parent = parent.children.first if parent&.kind == :property
+        case parent&.kind
+        when :object
+          raise TypeError, "Object path keys must be Strings" unless key.is_a?(String)
+          parent.children.reverse_each.find { |child| child.key == key }
+        when :array
+          raise TypeError, "Array path indices must be nonnegative Integers" unless key.is_a?(Integer) && key >= 0
+          parent.children[key]
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/kochab/editing.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Kochab
+  class Document
+    # Replace the value at path, or insert a missing final object member.
+    # Only the value's bytes are replaced; adjacent trivia is never included.
+    def set(path, value)
+      entry = find_node(path)
+      return insert(path, value) unless entry
+
+      entry = entry.children.first if entry.kind == :property
+      [TextEdit.new(offset: entry.range.begin, length: entry.range.size, text: JSON.generate(value))]
+    end
+
+    # Remove all occurrences of a member, or one array element. Comments outside
+    # the removed node survive, as do all whitespace and unrelated tokens.
+    def remove(path)
+      raise ArgumentError, "Cannot remove the document root; use set([], nil)" if path == []
+      entry = find_node(path)
+      return [] unless entry
+      raise ParseError, errors unless valid?
+
+      entries = entry.kind == :property ? entry.parent.children.select { |child| child.key == entry.key } : [entry]
+      edits = entries.flat_map do |child|
+        result = [TextEdit.new(offset: child.range.begin, length: child.range.size, text: "")]
+        following = token_after(child.range.end)
+        preceding = token_before(child.range.begin)
+        comma = following&.kind == :comma ? following : (preceding if preceding&.kind == :comma)
+        result << TextEdit.new(offset: comma.range.begin, length: 1, text: "") if comma
+        result
+      end
+      edits.uniq { |edit| [edit.offset, edit.length] }
+    end
+
+    # Insert a new object key (optionally after another key) or an array index.
+    def insert(path, value, after: nil)
+      raise TypeError, "path must be a nonempty Array" unless path.is_a?(Array) && !path.empty?
+      raise ParseError, errors unless valid?
+
+      parent = find_node(path[0...-1])
+      parent = parent.children.first if parent&.kind == :property
+      key = path.last
+      index = insertion_index(parent, key, after)
+      payload = JSON.generate(value)
+      payload = "#{JSON.generate(key)}: #{payload}" if parent.kind == :object
+
+      if (following = parent.children[index])
+        offset = following.leading_comments.first&.range&.begin || following.range.begin
+        prefix = line_prefix(offset)
+        separator = prefix.match?(/\A[ \t]*\z/) ? eol + prefix : " "
+        return [TextEdit.new(offset: offset, length: 0, text: payload + "," + separator)]
+      end
+      append_entry(parent, payload)
+    end
+
+    # Pretty-print the token stream without decoding/re-encoding strings or comments.
+    def format(indent: 2, keep_blank_lines: 1)
+      raise ParseError, errors unless valid?
+      unless indent.is_a?(Integer) && indent >= 0 && keep_blank_lines.is_a?(Integer) && keep_blank_lines >= 0
+        raise ArgumentError, "indent and keep_blank_lines must be nonnegative Integers"
+      end
+      events = (@tokens.reject { |token| token.kind == :eof } + @comments).sort_by { |event| event.range.begin }
+      output = @text.start_with?("\uFEFF") ? +"\uFEFF" : +""
+      depth = 0
+      previous = nil
+      events.each do |event|
+        closing = [:object_end, :array_end].include?(event.kind)
+        depth -= 1 if closing
+        if previous
+          gap = @text.byteslice(previous.range.end...event.range.begin)
+          newlines = gap.scan(/\r\n|\r|\n/).length
+          separator = separator_between(previous, event, newlines)
+          if separator == :newline
+            output << eol * (1 + [[newlines - 1, 0].max, keep_blank_lines].min)
+            output << " " * (indent * depth)
+          elsif separator == :space
+            output << " "
+          end
+        end
+        output << @text.byteslice(event.range)
+        depth += 1 if [:object, :array].include?(event.kind)
+        previous = event
+      end
+      output << eol
+    end
+
+    private
+
+    def token_after(offset)
+      @tokens.bsearch { |token| token.range.begin >= offset }
+    end
+
+    def token_before(offset)
+      index = @tokens.bsearch_index { |token| token.range.begin >= offset }
+      @tokens[index - 1] if index && index.positive?
+    end
+
+    def line_prefix(offset)
+      before = @text.byteslice(0...offset)
+      before.byteslice((before.b.rindex(/[\r\n]/n) || -1) + 1..)
+    end
+
+    def eol
+      @eol ||= @text[/\r\n|\r|\n/] || "\n"
+    end
+
+    def insertion_index(parent, key, after)
+      case parent&.kind
+      when :object
+        raise TypeError, "Object path keys must be Strings" unless key.is_a?(String)
+        raise ArgumentError, "Property already exists; use set" if parent.children.any? { |child| child.key == key }
+        return parent.children.length if after.nil?
+
+        found = parent.children.rindex { |child| child.key == after }
+        raise KeyError, "No property #{after.inspect} to insert after" unless found
+
+        found + 1
+      when :array
+        raise ArgumentError, "Use an array index instead of after" unless after.nil?
+        unless key.is_a?(Integer) && (0..parent.children.length).cover?(key)
+          raise IndexError, "Array insertion index is outside the array"
+        end
+        key
+      else
+        raise KeyError, "Parent path is not an object or array"
+      end
+    end
+
+    def separator_between(previous, event, newlines)
+      return :newline if previous.kind == :line
+      return newlines.positive? ? :newline : :space if event.is_a?(Comment)
+      return :none if [:colon, :comma].include?(event.kind)
+
+      opening = [:object, :array].include?(previous.kind)
+      return opening ? :none : :newline if [:object_end, :array_end].include?(event.kind)
+      return :newline if opening || previous.kind == :comma
+      return :space if previous.kind == :colon
+      return newlines.positive? ? :newline : :space if previous.is_a?(Comment)
+
+      :none
+    end
+
+    def append_entry(parent, payload)
+      closing = token_before(parent.range.end)
+      last = parent.children.last
+      comma = last && token_after(last.range.end)&.kind == :comma
+      edits = []
+      edits << TextEdit.new(offset: last.range.end, length: 0, text: ",") if last && !comma
+      payload += "," if comma
+      if @text.byteslice(parent.range).match?(/[\r\n]/)
+        base = line_prefix(parent.range.begin)[/\A[ \t]*/]
+        first = parent.children.first
+        child_indent = first && line_prefix(first.range.begin)
+        child_indent = base + "  " unless child_indent&.match?(/\A[ \t]+\z/) && child_indent.length > base.length
+        prefix = line_prefix(closing.range.begin)
+        addition = if prefix.match?(/\A[ \t]*\z/) && child_indent.start_with?(prefix)
+          child_indent.delete_prefix(prefix)
+        else
+          eol + child_indent
+        end
+        payload = addition + payload + eol + base
+      elsif last || @comments.any? { |comment| parent.range.cover?(comment.range.begin) }
+        payload = " " + payload unless @text.getbyte(closing.range.begin - 1) == 32
+      end
+      edits << TextEdit.new(offset: closing.range.begin, length: 0, text: payload)
+      edits
+    end
+  end
+end

data/lib/kochab/parser.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module Kochab
+  # Internal scanner/parser. All offsets are bytes, even for invalid UTF-8.
+  class Parser
+    Token = Struct.new(:kind, :range, :value)
+    PUNCTUATION = {123 => :object, 125 => :object_end, 91 => :array,
+      93 => :array_end, 58 => :colon, 44 => :comma}.freeze
+    VALUES = [:object, :array, :string, :number, :boolean, :null].freeze
+    ENDINGS = [:object_end, :array_end, :eof].freeze
+    def initialize(text, strict:, trailing_commas:, allow_nan:, max_depth:)
+      @text = text.dup.force_encoding(Encoding::UTF_8).freeze
+      @scanner = StringScanner.new(@text.b)
+      @strict, @trailing_commas, @allow_nan = strict, trailing_commas, allow_nan
+      @max_depth = max_depth
+      @errors, @comments, @tokens, @nodes = [], [], [], []
+      @index = 0
+    end
+
+    def parse
+      scan
+      root = parse_value(0)
+      until current.kind == :eof
+        diagnose(current.range, :unexpected_token, "Unexpected token after root value")
+        advance
+      end
+      document = Document.new(@text, root, @errors, @comments, @tokens)
+      attach_comments(document)
+      raise ParseError, @errors if @strict && !document.valid?
+
+      document
+    end
+
+    private
+
+    def diagnose(range, code, message, severity = :error)
+      @errors << Error.new(range: range, code: code, message: message, severity: severity)
+    end
+
+    def scan
+      diagnose(0...@text.bytesize, :invalid_encoding, "Input is not valid UTF-8") unless @text.valid_encoding?
+      scan_bom
+
+      until @scanner.eos?
+        next if @scanner.skip(/[ \t\r\n]+/n)
+
+        scan_token
+      end
+      @tokens << Token.new(:eof, @text.bytesize...@text.bytesize)
+    end
+
+    def scan_bom
+      return unless @scanner.scan(/\xEF\xBB\xBF/n)
+
+      diagnose(0...3, :unexpected_bom, "BOM is not permitted in strict JSON") if @strict
+    end
+
+    def scan_token
+      start = @scanner.pos
+      byte = @scanner.peek(1).getbyte(0)
+      if (kind = PUNCTUATION[byte])
+        @scanner.pos += 1
+        @tokens << Token.new(kind, start...@scanner.pos)
+      elsif byte == 34
+        scan_string(start)
+      elsif @scanner.scan(%r{//[^\r\n]*|/\*(?:[^*]++|\*(?!/))*\*/}n)
+        comment(start, @scanner.matched.start_with?("//") ? :line : :block)
+      elsif @scanner.scan(%r{/\*}n)
+        @scanner.terminate
+        comment(start, :block)
+        diagnose(start...@scanner.pos, :unterminated_comment, "Unterminated block comment")
+      elsif @scanner.scan(/(?:-?Infinity|NaN)/n)
+        raw = @scanner.matched
+        value = raw == "NaN" ? Float::NAN : (raw.start_with?("-") ? -Float::INFINITY : Float::INFINITY)
+        @tokens << Token.new(:number, start...@scanner.pos, value)
+        diagnose(start...@scanner.pos, :invalid_number, "Non-finite numbers are disabled") if @strict || !@allow_nan
+      elsif @scanner.scan(/-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/n)
+        raw = @scanner.matched
+        value = raw.match?(/[.eE]/) ? JSON.parse(raw) : raw.to_i
+        @tokens << Token.new(:number, start...@scanner.pos, value)
+      elsif @scanner.scan(/true|false|null/n)
+        raw = @scanner.matched
+        @tokens << Token.new(raw == "null" ? :null : :boolean, start...@scanner.pos,
+          raw == "null" ? nil : raw == "true")
+      else
+        @scanner.scan(/[^\s{}\[\]:,"\/]+/n) || @scanner.get_byte
+        diagnose(start...@scanner.pos, :invalid_token, "Invalid token")
+        @tokens << Token.new(:invalid, start...@scanner.pos)
+      end
+    end
+
+    def scan_string(start)
+      valid = @scanner.scan(/"(?:[^"\\\x00-\x1f]++|\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4}))*"/n)
+      closed = valid || @scanner.scan(/"(?:[^"\\\r\n]++|\\[^\r\n])*"/n)
+      @scanner.scan(/"(?:[^"\\\r\n]++|\\[^\r\n])*\\?/n) unless closed
+      raw = @scanner.matched.force_encoding(Encoding::UTF_8)
+      range = start...@scanner.pos
+      unless closed
+        diagnose(range, :unterminated_string, "Unterminated string")
+        # An unfinished escape has no decoded character yet.
+        raw = (raw.b.sub(/\\\z/n, "") + '"').force_encoding(Encoding::UTF_8)
+      end
+      @tokens << Token.new(:string, range, decode_string(raw, valid, range))
+    end
+
+    def decode_string(raw, valid, range)
+      begin
+        if raw.b.match?(/[\\\x00-\x1f]/n)
+          # Older json releases silently accept unknown escapes, so validate
+          # their syntax ourselves before asking the decoder for their value.
+          raise JSON::ParserError, "Invalid string escape or control character" unless valid
+          value = JSON.parse(raw)
+        else
+          value = raw.byteslice(1, raw.bytesize - 2)
+        end
+        raise JSON::ParserError, "Invalid Unicode string" unless value.valid_encoding?
+      rescue JSON::ParserError, EncodingError
+        diagnose(range, :invalid_string, "Invalid string escape, control character, or Unicode")
+        value = raw.byteslice(1, [raw.bytesize - 2, 0].max).scrub
+      end
+      value
+    end
+
+    def comment(start, kind)
+      range = start...@scanner.pos
+      @comments << Comment.new(range: range, text: @text.byteslice(range), kind: kind)
+      diagnose(range, :comment_not_allowed, "Comments are not permitted in strict JSON") if @strict
+    end
+
+    def current
+      @tokens[@index]
+    end
+
+    def advance
+      token = current
+      @index += 1 unless token.kind == :eof
+      token
+    end
+
+    def node(kind, range, value = nil, children = [], key_range = nil, key = nil)
+      result = Node.new(kind: kind, range: range, value: value, children: children,
+        key_range: key_range, key: key, leading_comments: [])
+      children.each { |child| child.parent = result }
+      @nodes << result
+      result
+    end
+
+    def parse_value(depth)
+      token = current
+      case token.kind
+      when :object, :array
+        if depth >= @max_depth
+          diagnose(token.range, :depth_limit, "Maximum nesting depth exceeded")
+          skip_container
+          return node(:null, token.range.begin...@tokens[@index - 1].range.end)
+        end
+        parse_container(depth + 1)
+      when :string, :number, :boolean, :null
+        advance
+        node(token.kind, token.range, token.value)
+      else
+        diagnose(token.range, :expected_value, "Expected a value")
+        advance unless ENDINGS.include?(token.kind) || token.kind == :comma
+        node(:null, token.range.begin...token.range.begin)
+      end
+    end
+
+    def skip_container
+      depth = 0
+      loop do
+        kind = advance.kind
+        depth += 1 if [:object, :array].include?(kind)
+        depth -= 1 if [:object_end, :array_end].include?(kind)
+        break if depth.zero? || current.kind == :eof
+      end
+    end
+
+    def parse_container(depth)
+      opening = advance
+      object = opening.kind == :object
+      ending = object ? :object_end : :array_end
+      children, value = [], object ? {} : []
+      comma = nil
+      until current.kind == ending || current.kind == :eof
+        if [:object_end, :array_end].include?(current.kind)
+          diagnose(current.range, :mismatched_bracket, "Mismatched closing bracket")
+          advance
+          next
+        end
+        if current.kind == :comma
+          diagnose(current.range, :unexpected_comma, "Unexpected comma")
+          comma = advance
+          next
+        end
+        if children.any? && !comma
+          diagnose(current.range, :expected_comma, "Expected a comma")
+        end
+        before = @index
+        if object
+          child = parse_property(depth)
+          if child
+            diagnose(child.key_range, :duplicate_key, "Duplicate key #{child.key.inspect}", :warning) if value.key?(child.key)
+            value[child.key] = child.value
+            children << child
+          end
+        else
+          child = parse_value(depth)
+          child.key = children.length
+          children << child
+          value << child.value
+        end
+        advance if before == @index
+        comma = current.kind == :comma ? advance : nil
+      end
+      finish = finish_container(ending, comma)
+      node(opening.kind, opening.range.begin...finish, value, children)
+    end
+
+    def finish_container(ending, comma)
+      if current.kind == ending
+        diagnose(comma.range, :trailing_comma, "Trailing comma is not permitted") if comma && (@strict || !@trailing_commas)
+        advance.range.end
+      else
+        diagnose(current.range, :unclosed_container, "Expected #{ending == :object_end ? '}' : ']'}")
+        @text.bytesize
+      end
+    end
+
+    def parse_property(depth)
+      unless current.kind == :string
+        diagnose(current.range, :expected_key, "Expected a quoted property name")
+        advance
+        return nil
+      end
+      key = advance
+      if current.kind == :colon
+        advance
+      else
+        diagnose(current.range, :expected_colon, "Expected ':' after property name")
+      end
+      value = parse_value(depth)
+      node(:property, key.range.begin...value.range.end, value.value, [value], key.range, key.value)
+    end
+
+    def attach_comments(document)
+      return if @comments.empty?
+
+      ends = @nodes
+      starts = comment_targets(document.root)
+      next_comment = nil
+      leading_target = nil
+      @comments.reverse_each do |comment|
+        previous = comment_target_before(ends, comment)
+        following = starts.bsearch { |entry| entry.range.begin >= comment.range.end }
+        gap_before = previous && @text.byteslice(previous.range.end...comment.range.begin).b
+        if next_comment && leading_target && (!following || next_comment.range.begin < following.range.begin)
+          following = leading_target
+          end_of_gap = next_comment.range.begin
+        else
+          end_of_gap = following&.range&.begin
+        end
+        gap_after = end_of_gap && @text.byteslice(comment.range.end...end_of_gap).b
+        leading_target = nil
+        if previous && !previous.trailing_comment && gap_before.match?(/\A[ \t,]*\z/n)
+          previous.trailing_comment = comment
+        elsif following && gap_after.match?(/\A\s*\z/) && gap_after.scan(/\r\n|\r|\n/).length <= 1
+          following.leading_comments.unshift(comment)
+          leading_target = following
+        else
+          document.floating_comments << comment
+        end
+        next_comment = comment
+      end
+      document.floating_comments.sort_by! { |comment| comment.range.begin }
+    end
+
+    def comment_targets(root)
+      starts = []
+      pending = [root]
+      until pending.empty?
+        entry = pending.pop
+        starts << entry unless entry.parent&.kind == :property
+        entry.children.reverse_each { |child| pending << child }
+      end
+      starts
+    end
+
+    def comment_target_before(ends, comment)
+      # Nodes are constructed in postorder, so end offsets are already sorted.
+      before = ends.bsearch_index { |entry| entry.range.end > comment.range.begin } || ends.length
+      previous = before.positive? ? ends[before - 1] : nil
+      # Equal end offsets belong to the innermost value, before its property.
+      while before > 1 && ends[before - 2].range.end == previous.range.end
+        before -= 1
+        previous = ends[before - 1]
+      end
+      previous
+    end
+  end
+end

data/lib/kochab/version.rb

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

data/lib/kochab.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "strscan"
+require_relative "kochab/version"
+
+# JSON with comments, source ranges, and non-destructive editing.
+module Kochab
+  Error = Struct.new(:range, :code, :message, :severity, keyword_init: true)
+  Comment = Struct.new(:range, :text, :kind, keyword_init: true)
+  TextEdit = Struct.new(:offset, :length, :text, keyword_init: true)
+  Node = Struct.new(:kind, :range, :key_range, :value, :children,
+    :leading_comments, :trailing_comment, :key, :parent, keyword_init: true)
+
+  class ParseError < StandardError
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      error = errors.find { |entry| entry.severity == :error }
+      super("#{error.message} at byte #{error.range.begin}")
+    end
+  end
+
+  # Parse UTF-8 bytes. Syntax errors are collected unless strict is true.
+  # Duplicate keys are warnings, with the final occurrence winning.
+  def self.parse(text, strict: false, trailing_commas: true, allow_nan: false, max_depth: 512)
+    raise TypeError, "text must be a String" unless text.is_a?(String)
+    unless max_depth.is_a?(Integer) && (1..512).cover?(max_depth)
+      raise ArgumentError, "max_depth must be an Integer between 1 and 512"
+    end
+
+    Parser.new(text, strict: strict, trailing_commas: trailing_commas,
+      allow_nan: allow_nan, max_depth: max_depth).parse
+  end
+
+  # Apply non-overlapping byte edits against one source snapshot.
+  # Insertions at the same byte offset are concatenated in input order.
+  def self.apply(text, edits)
+    raise TypeError, "text must be a String" unless text.is_a?(String)
+
+    validate_edits(text, edits)
+    ordered = edits.each_with_index.sort_by { |edit, index| [edit.offset, edit.length.zero? ? 0 : 1, index] }
+    cursor = 0
+    output = String.new(encoding: Encoding::BINARY)
+    ordered.each do |edit, _|
+      raise ArgumentError, "Text edits overlap" if edit.offset < cursor
+
+      output << text.byteslice(cursor...edit.offset).b << edit.text.b
+      cursor = edit.offset + edit.length
+    end
+    output << text.byteslice(cursor..).b
+    output.force_encoding(text.encoding)
+  end
+
+  def self.validate_edits(text, edits)
+    edits.each do |edit|
+      unless edit.is_a?(TextEdit) && edit.offset.is_a?(Integer) && edit.length.is_a?(Integer) &&
+          edit.text.is_a?(String) && edit.offset >= 0 && edit.length >= 0 && edit.offset + edit.length <= text.bytesize
+        raise ArgumentError, "Invalid text edit"
+      end
+      if text.encoding == Encoding::UTF_8 && text.valid_encoding?
+        [edit.offset, edit.offset + edit.length].each do |offset|
+          byte = text.getbyte(offset)
+          raise ArgumentError, "Edit splits a UTF-8 character" if byte && byte & 0xc0 == 0x80
+        end
+        raise ArgumentError, "Replacement is not valid UTF-8" unless edit.text.b.force_encoding(Encoding::UTF_8).valid_encoding?
+      end
+    end
+  end
+  private_class_method :validate_edits
+
+  # Normalize whitespace while retaining every comment and token verbatim.
+  def self.format(text, indent: 2, keep_blank_lines: 1)
+    parse(text).format(indent: indent, keep_blank_lines: keep_blank_lines)
+  end
+end
+
+require_relative "kochab/parser"
+require_relative "kochab/document"
+require_relative "kochab/editing"

data/sig/kochab.rbs

@@ -0,0 +1,69 @@
+module Kochab
+  VERSION: String
+  type value = nil | bool | Integer | Float | String | Array[value] | Hash[String, value]
+  type path = Array[String | Integer]
+
+  def self.parse: (String text, ?strict: bool, ?trailing_commas: bool, ?allow_nan: bool, ?max_depth: Integer) -> Document
+  def self.apply: (String text, Array[TextEdit] edits) -> String
+  def self.format: (String text, ?indent: Integer, ?keep_blank_lines: Integer) -> String
+
+  class Error < Struct[untyped]
+    attr_accessor range: Range[Integer]
+    attr_accessor code: Symbol
+    attr_accessor message: String
+    attr_accessor severity: Symbol
+    def initialize: (?range: Range[Integer], ?code: Symbol, ?message: String, ?severity: Symbol) -> void
+  end
+
+  class Comment < Struct[untyped]
+    attr_accessor range: Range[Integer]
+    attr_accessor text: String
+    attr_accessor kind: Symbol
+    def initialize: (?range: Range[Integer], ?text: String, ?kind: Symbol) -> void
+  end
+
+  class TextEdit < Struct[untyped]
+    attr_accessor offset: Integer
+    attr_accessor length: Integer
+    attr_accessor text: String
+    def initialize: (?offset: Integer, ?length: Integer, ?text: String) -> void
+  end
+
+  class Node < Struct[untyped]
+    attr_accessor kind: Symbol
+    attr_accessor range: Range[Integer]
+    attr_accessor key_range: Range[Integer]?
+    attr_accessor value: value
+    attr_accessor children: Array[Node]
+    attr_accessor leading_comments: Array[Comment]
+    attr_accessor trailing_comment: Comment?
+    attr_accessor key: (String | Integer)?
+    attr_accessor parent: Node?
+    def initialize: (?kind: Symbol, ?range: Range[Integer], ?key_range: Range[Integer]?, ?value: value, ?children: Array[Node], ?leading_comments: Array[Comment], ?trailing_comment: Comment?, ?key: (String | Integer)?, ?parent: Node?) -> void
+  end
+
+  class ParseError < StandardError
+    attr_reader errors: Array[Error]
+    def initialize: (Array[Error] errors) -> void
+  end
+
+  class Document
+    attr_reader text: String
+    attr_reader root: Node
+    attr_reader errors: Array[Error]
+    attr_reader comments: Array[Comment]
+    attr_reader floating_comments: Array[Comment]
+    def value: () -> value
+    def valid?: () -> bool
+    def node_at: (Integer offset) -> Node?
+    def path_at: (Integer offset) -> path?
+    def range_of: (path path) -> Range[Integer]?
+    def key_range_of: (path path) -> Range[Integer]?
+    def utf16_position_at: (Integer offset) -> [Integer, Integer]
+    def offset_at_utf16_position: (Integer line, Integer character) -> Integer
+    def set: (path path, value value) -> Array[TextEdit]
+    def remove: (path path) -> Array[TextEdit]
+    def insert: (path path, value value, ?after: String?) -> Array[TextEdit]
+    def format: (?indent: Integer, ?keep_blank_lines: Integer) -> String
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: kochab
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby JSONC parser with byte ranges, syntax recovery, source queries,
+  minimal text edits, formatting, and UTF-16 positions. No runtime gem dependencies.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- examples/settings.rb
+- lib/kochab.rb
+- lib/kochab/document.rb
+- lib/kochab/editing.rb
+- lib/kochab/parser.rb
+- lib/kochab/version.rb
+- sig/kochab.rbs
+homepage: https://github.com/noxdea/kochab
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/noxdea/kochab
+  changelog_uri: https://github.com/noxdea/kochab/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Recoverable JSONC parsing and edits that preserve comments and formatting
+test_files: []