porrima 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a343ef7bf35f119ee70c360d6fb3f4d69e20e052911cbd8f449ea87964b40284
-  data.tar.gz: fabc56760d330596512fa8481359dcc364a7793af4e8984e98a920b230c6b052
+  metadata.gz: 12e94d3fff8b491f17f5cb13beb41d396496816c54995c16be69b3aebdba875f
+  data.tar.gz: df24fab43b8358f2fcc522b548a1ead14ef53faf365a6601d0bc10c3a798aeed
 SHA512:
-  metadata.gz: 48f5568c01680dab34f4633161d19d3e34486e2b8e7299ddf31eb40765fabe57f7ea796c73b11a39686bc3237a4c52d70c83422f842c98f94aefe90b681c66d6
-  data.tar.gz: 46430b633bdc526768d2f186d2f73d6030a7d764a97c65692033246204441ead795faacb391bdd24652de5231cd659d63a617aa03b65b5a8e38fb4a142733637
+  metadata.gz: 24a68e804a09990a553b353e9ca2c547f64ca72cb382a121212ee1222f44b75d17b0ed07ca499a4200539279d245484723e602b43a3bb1972c51cbd86251b81c
+  data.tar.gz: b61f20f0ea9d25c231e30b1efd01a91152f7e3e76bd69edd3dec00c634c27123fcb15c9d2e4c66a33f35a2207d0b0c72d800cc2c605578ca42b15823a975824c

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0 — 2026-09-15
+
+- Add zero-based merge output regions for conflict marker blocks.
+- Add immutable single and bulk conflict resolution with custom replacement text.
+- Add word-level inline refinement for conflict alternatives.
+
 ## 0.1.0 — 2026-09-12
 
 - Initial release.

data/README.md

@@ -1,18 +1,39 @@
-# Porrima
-
-[![Gem version](https://img.shields.io/gem/v/porrima.svg)](https://rubygems.org/gems/porrima)
-[![CI](https://github.com/noxdea/porrima/actions/workflows/main.yml/badge.svg)](https://github.com/noxdea/porrima/actions/workflows/main.yml)
-[![CRuby 3.1+](https://img.shields.io/badge/CRuby-%3E%3D%203.1-cc342d.svg)](porrima.gemspec)
-[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
-
-Line, word, and three-way diff, patch, and merge in pure Ruby.
-
-## Scope
-
-Porrima computes from two or three texts. Its core never reads files, knows
-nothing about Git, and has no runtime dependencies. Color, width, truncation,
-caching, and other display policy belong to the caller. The CLI only connects
-files to the library's interoperable formats.
+<h1 align="center">Porrima</h1>
+
+<p align="center">
+  <strong>Dependency-free line, word, and three-way diff, exact patching, and structured merge for Ruby.</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/porrima"><img src="https://img.shields.io/gem/v/porrima.svg" alt="Gem version"></a>
+  <a href="https://github.com/noxdea/porrima/actions/workflows/main.yml"><img src="https://github.com/noxdea/porrima/actions/workflows/main.yml/badge.svg" alt="CI status"></a>
+  <a href="porrima.gemspec"><img src="https://img.shields.io/badge/CRuby-%3E%3D%203.1-cc342d.svg" alt="CRuby 3.1 or newer"></a>
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="https://noxdea.github.io/porrima/">Website</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#core-api">Core API</a> ·
+  <a href="#cli">CLI</a>
+</p>
+
+---
+
+Porrima turns two or three texts into structured edits, hunks, patches, and
+merge conflicts. Its core performs no I/O, knows nothing about Git, and leaves
+color, width, truncation, caching, and other display policy to the caller.
+
+## Features
+
+- Linear-space Myers diff for lines and inline word or character refinement
+- Context hunks, change statistics, gutter marks, and paired rows
+- Unified diff output with strict patch parsing, application, and reversal
+- Three-way merge with structured conflicts, output regions, and immutable resolution
+- CLI output as unified text or JSON
+- No runtime dependencies
 
 ## Installation
 
@@ -20,43 +41,96 @@ files to the library's interoperable formats.
 gem install porrima
 ```
 
+Or add `gem "porrima"` to your Gemfile. Porrima requires CRuby 3.1 or newer.
+
 ## Quick start
 
 ```ruby
 require "porrima"
 
-result = Porrima.diff("one\ntwo\n", "one\nchanged\n", context: 1)
-result.hunks
-result.stat.to_h # => {insertions: 1, deletions: 1, hunks: 1}
-result.marks
-result.rows
-result.to_unified(old_name: "a/example", new_name: "b/example")
+before = "one\ntwo\n"
+after = "one\nchanged\n"
+diff = Porrima.diff(before, after, context: 1)
+
+diff.stat.to_h
+# => { insertions: 1, deletions: 1, hunks: 1 }
+
+puts diff.to_unified(old_name: "a/example", new_name: "b/example")
+```
+
+## Core API
+
+| API | Result |
+| --- | --- |
+| `Porrima.diff(before, after)` | Lazy `Diff` snapshot with every result view |
+| `Porrima.edits(before, after)` | Ordered equal, deleted, and inserted lines |
+| `Porrima.hunks(before, after)` | Context-aware change groups |
+| `Porrima.unified(before, after)` | Unified diff text |
+| `Porrima.apply(text, hunk)` | Text with one exact hunk applied |
+| `Porrima.revert(text, hunk)` | Text with one exact hunk reversed |
+| `Porrima::Inline.refine(before, after)` | Word- or character-level spans |
+| `Porrima::Patch.parse(text)` | Parsed unified file diffs |
+| `Porrima::Merge.three_way(...)` | Structured three-way merge result |
+
+### Diff result
+
+| View | Contains |
+| --- | --- |
+| `edits` | Equal, deleted, or inserted lines with old and new positions |
+| `hunks` | Context-aware groups with exact old and new text |
+| `stat` | Insertion, deletion, and hunk counts |
+| `marks` | Added, modified, or removed ranges on the new side |
+| `rows` | Old and new lines paired for side-by-side display |
+
+Use `hunk_at(new_line:)` or `mark_at(new_line:)` for position lookup,
+`to_unified` for interoperable text, and `to_h` for serialization.
+
+`Diff` snapshots its inputs and lazily memoizes these collections. Finish the
+fields needed by another thread on the producing thread before sharing it.
 
+### Inline diff
+
+```ruby
 old_spans, new_spans = Porrima::Inline.refine("hello old", "hello new")
-patch = Porrima::Patch.parse(result.to_unified).first
-patch.apply("one\ntwo\n")
+```
 
-merge = Porrima::Merge.three_way(base: "old\n", ours: "ours\n", theirs: "theirs\n")
-Porrima::Merge.to_text(merge, style: :diff3)
+Pass `granularity: :char` to compare grapheme clusters instead of words.
+
+### Patch
+
+```ruby
+file = Porrima::Patch.parse(diff.to_unified).first
+file.applies?(before) # => true
+file.apply(before)    # => "one\nchanged\n"
+file.revert(after)    # => "one\ntwo\n"
 ```
 
-`Porrima.edits`, `.hunks`, `.unified`, `.apply`, and `.revert` are available
-as lower-level entry points. `Porrima::Budget` can replace an oversized input
-as one block or raise `Porrima::BudgetExceeded`.
+Patch application is exact: stale or malformed input raises a Porrima error.
 
-## Data model
+### Three-way merge
 
-- `Edit` is an equal, deleted, or inserted line with old and new positions.
-- `Hunk` groups edits and exposes its exact old and new text.
-- `Mark` locates an added, modified, or removed block on the new side.
-- `Row` pairs old and new lines without presentation policy.
-- `Span` describes equal, deleted, or inserted inline text.
-- `Merge::Result` contains plain sections and structured conflicts; markers are
-  only produced by `Merge.to_text`.
+```ruby
+merge = Porrima::Merge.three_way(
+  base: "old\n",
+  ours: "ours\n",
+  theirs: "theirs\n"
+)
+
+merge.clean?
+merge.conflicts
+merge.regions # zero-based locations in merge-marker output
+Porrima::Merge.to_text(merge, style: :diff3)
 
-`Diff` snapshots its inputs and lazily memoizes these collections. Finish the
-fields needed by another thread on the producing thread before handing the
-instance across.
+resolved = Porrima::Merge.resolve(merge, 0, :ours)
+Porrima::Merge.to_resolved_text(resolved) # => "ours\n"
+Porrima::Merge.conflict_inline(merge.conflicts.first)
+```
+
+`resolve` accepts `:ours`, `:theirs`, `:base`, `:ours_then_theirs`,
+`:theirs_then_ours`, a replacement string, or an array of replacement strings.
+It returns a new result and leaves the source result unchanged. Use `resolve_all`
+to apply one choice to every conflict. `to_resolved_text` rejects results that
+still contain a conflict.
 
 ## CLI
 
@@ -68,14 +142,24 @@ porrima apply [options] PATCH [FILE]
 
 Diff supports unified output, `--json`, `--quiet`, and `--max-bytes`. Merge
 supports structured JSON or `diff3`/`merge` markers. Apply supports
-`--reverse` and validation-only `--check`. Exit status is 0 for no
-diff/conflict, 1 for a diff/conflict, and 2 for an error.
+`--reverse` and validation-only `--check`.
 
-## Compatibility
+Exit status is 0 for no diff or conflict, 1 for a diff or conflict, and 2 for
+an error.
 
-Porrima requires CRuby 3.1 or newer. The line edit, hunk, unified output, and
-revert behavior are byte-compatible with the original Canopus diff engine.
-Public struct field names and order are part of the 0.1 contract.
+## Compatibility and limits
+
+- Line edits, hunks, unified output, and revert behavior are byte-compatible
+  with the original Canopus diff engine.
+- Public struct field names and order are part of the 0.1 contract.
+- Comparison uses `String#==`; callers own encoding normalization.
+- Patch application intentionally has no fuzz matching.
+- Inline refinement treats over 2,000 combined tokens as one replacement.
+- Merge region positions are zero-based and cover the complete conflict marker
+  block produced by `to_text(style: :merge)`.
+- `Porrima::Budget` can replace an oversized input as one block or raise
+  `Porrima::BudgetExceeded`.
+- During 0.x releases, minor versions may contain breaking changes.
 
 ## Development
 
@@ -88,14 +172,11 @@ bundle exec rake bench:assert
 gem build --strict porrima.gemspec
 ```
 
-## Limits
+## Contributing
 
-- Comparison uses `String#==`; callers own encoding normalization.
-- Patch application is exact and intentionally has no fuzz matching.
-- Inline refinement treats over 2,000 combined tokens as a whole-text replacement.
-- `Diff` memoization is not synchronized; complete it before cross-thread use.
-- During 0.x releases, minor versions may contain breaking changes.
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/noxdea/porrima).
 
 ## License
 
-Porrima is released under the [MIT License](LICENSE.txt).
+Porrima is available under the [MIT License](LICENSE.txt).

data/lib/porrima/merge.rb

@@ -4,17 +4,56 @@ module Porrima
   module Merge
     Change = Struct.new(:start, :finish, :replacement, :side, keyword_init: true)
     Conflict = Struct.new(:base_start, :base_count, :base, :ours, :theirs, keyword_init: true)
+    Region = Struct.new(:conflict, :output_start, :output_count, :index, keyword_init: true)
+    RESOLUTION_CHOICES = %i[ours theirs base ours_then_theirs theirs_then_ours].freeze
+    private_constant :RESOLUTION_CHOICES
 
     class Result
       attr_reader :sections, :conflicts
 
       def initialize(sections)
-        @sections = sections.freeze
-        @conflicts = sections.grep(Conflict).freeze
+        raise ArgumentError, "sections must be an array" unless sections.is_a?(Array)
+        @sections = sections.map { |section| snapshot(section) }.freeze
+        @conflicts = @sections.grep(Conflict).freeze
         freeze
       end
 
       def clean? = conflicts.empty?
+      def resolved? = conflicts.empty?
+
+      def regions
+        output_line = conflict_index = 0
+        sections.each_with_object([]) do |section, regions|
+          unless section.is_a?(Conflict)
+            output_line += section.count("\n")
+            next
+          end
+
+          marked = +""
+          Merge.send(:append_conflict_text, marked, section, :merge, ["ours", "base", "theirs"])
+          output_count = marked.count("\n")
+          regions << Region.new(conflict: section, output_start: output_line,
+            output_count: output_count, index: conflict_index).freeze
+          output_line += output_count
+          conflict_index += 1
+        end.freeze
+      end
+
+      private
+
+      def snapshot(section)
+        return section.dup.freeze if section.is_a?(String)
+        raise ArgumentError, "sections must contain strings or conflicts" unless section.is_a?(Conflict)
+        unless section.base_start.is_a?(Integer) && section.base_start >= 0 &&
+            section.base_count.is_a?(Integer) && section.base_count >= 0 &&
+            [section.base, section.ours, section.theirs].all?(String)
+          raise ArgumentError, "invalid conflict"
+        end
+
+        Conflict.new(base_start: section.base_start, base_count: section.base_count,
+          base: section.base.dup.freeze, ours: section.ours.dup.freeze,
+          theirs: section.theirs.dup.freeze).freeze
+      end
     end
 
     module_function
@@ -65,16 +104,38 @@ module Porrima
           output << section
           next
         end
-        output << "<<<<<<< #{labels[0]}\n"
-        append_marked_text(output, section.ours)
-        if style == :diff3
-          output << "||||||| #{labels[1]}\n"
-          append_marked_text(output, section.base)
-        end
-        output << "=======\n"
-        append_marked_text(output, section.theirs)
-        output << ">>>>>>> #{labels[2]}\n"
+        append_conflict_text(output, section, style, labels)
+      end
+    end
+
+    def resolve(result, index, choice)
+      validate_result(result)
+      unless index.is_a?(Integer) && index.between?(0, result.conflicts.length - 1)
+        raise ArgumentError, "index must identify a conflict"
       end
+      validate_choice(choice)
+      conflict = result.conflicts[index]
+      Result.new(result.sections.map { |section| section.equal?(conflict) ? resolution_text(conflict, choice) : section })
+    end
+
+    def resolve_all(result, choice)
+      validate_result(result)
+      validate_choice(choice)
+      Result.new(result.sections.map { |section| section.is_a?(Conflict) ? resolution_text(section, choice) : section })
+    end
+
+    def to_resolved_text(result)
+      validate_result(result)
+      raise ArgumentError, "merge result has unresolved conflicts" unless result.resolved?
+      result.sections.join
+    end
+
+    def conflict_inline(conflict)
+      unless conflict.is_a?(Conflict) && [conflict.ours, conflict.theirs].all?(String)
+        raise ArgumentError, "conflict must contain ours and theirs text"
+      end
+      ours, theirs = Inline.refine(conflict.ours, conflict.theirs)
+      {ours: ours, theirs: theirs}
     end
 
     def lines(text) = text.is_a?(String) ? text.lines : text
@@ -130,5 +191,49 @@ module Porrima
       output << "\n" unless text.empty? || text.end_with?("\n")
     end
     private_class_method :append_marked_text
+
+    def append_conflict_text(output, conflict, style, labels)
+      output << "<<<<<<< #{labels[0]}\n"
+      append_marked_text(output, conflict.ours)
+      if style == :diff3
+        output << "||||||| #{labels[1]}\n"
+        append_marked_text(output, conflict.base)
+      end
+      output << "=======\n"
+      append_marked_text(output, conflict.theirs)
+      output << ">>>>>>> #{labels[2]}\n"
+    end
+    private_class_method :append_conflict_text
+
+    def validate_result(result)
+      raise ArgumentError, "result must be a Porrima::Merge::Result" unless result.is_a?(Result)
+    end
+    private_class_method :validate_result
+
+    def validate_choice(choice)
+      valid = RESOLUTION_CHOICES.include?(choice) || choice.is_a?(String) ||
+        (choice.is_a?(Array) && choice.all?(String))
+      raise ArgumentError, "invalid resolution choice" unless valid
+    end
+    private_class_method :validate_choice
+
+    def resolution_text(conflict, choice)
+      case choice
+      when :ours then conflict.ours
+      when :theirs then conflict.theirs
+      when :base then conflict.base
+      when :ours_then_theirs then join_alternatives(conflict.ours, conflict.theirs)
+      when :theirs_then_ours then join_alternatives(conflict.theirs, conflict.ours)
+      when Array then choice.join
+      else choice
+      end
+    end
+    private_class_method :resolution_text
+
+    def join_alternatives(first, second)
+      return first + second if first.empty? || second.empty? || first.end_with?("\n")
+      first + "\n" + second
+    end
+    private_class_method :join_alternatives
   end
 end

data/lib/porrima/version.rb

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

data/sig/porrima.rbs

@@ -2,6 +2,7 @@ module Porrima
   VERSION: String
   type lines = String | Array[String]
   type kind = :equal | :delete | :insert
+  type merge_choice = :ours | :theirs | :base | :ours_then_theirs | :theirs_then_ours | String | Array[String]
 
   class Error < StandardError
   end
@@ -110,14 +111,27 @@ module Porrima
       attr_accessor theirs: String
       def self.new: (base_start: Integer, base_count: Integer, base: String, ours: String, theirs: String) -> instance
     end
+    class Region < Struct[untyped]
+      attr_accessor conflict: Conflict
+      attr_accessor output_start: Integer
+      attr_accessor output_count: Integer
+      attr_accessor index: Integer
+      def self.new: (conflict: Conflict, output_start: Integer, output_count: Integer, index: Integer) -> instance
+    end
     class Result
       attr_reader sections: Array[String | Conflict]
       attr_reader conflicts: Array[Conflict]
       def initialize: (Array[String | Conflict]) -> void
       def clean?: () -> bool
+      def resolved?: () -> bool
+      def regions: () -> Array[Region]
     end
     def self.three_way: (base: String, ours: String, theirs: String) -> Result
     def self.to_text: (Result, ?style: (:diff3 | :merge), ?labels: Array[String]) -> String
+    def self.resolve: (Result, Integer, merge_choice) -> Result
+    def self.resolve_all: (Result, merge_choice) -> Result
+    def self.to_resolved_text: (Result) -> String
+    def self.conflict_inline: (Conflict) -> { ours: Array[Span], theirs: Array[Span] }
   end
 
   def self.diff: (lines, lines, ?context: Integer, ?budget: Budget?) -> Diff

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: porrima
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -10,7 +10,8 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Linear-space Myers diff with context hunks, gutter marks, paired rows,
-  unified output, strict patch application, and three-way merge. No I/O, no dependencies.
+  unified output, strict patch application, and resolvable three-way merge. No I/O,
+  no dependencies.
 email:
 - t.yudai92@gmail.com
 executables:
@@ -58,7 +59,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Line, word, and three-way diff, patch, and merge in pure Ruby
 test_files: []