patch_util 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6922fb856381f64462a95b3d1cac90be5d9cce4eca63783cb0966da67252047
+  data.tar.gz: c4b080b73b5e6eacc8bf030c375ae3bd5caf12bc490bb55d6e78b6d2aca00f87
+SHA512:
+  metadata.gz: 815db1d23e934a049c97f733b7948d8fa88cb040262c52fe00f0f3241f96e6d35ffad69553b4245b35de98007314017716356f8e324987d5358bda7e8a5f9b93
+  data.tar.gz: d1b3348828a4732ca3250b3a4ab392fa3738c45d273463124e18bdc30f06f1dc1f971f3fdb458a5fa0513a8f63c040e48d97eabc68bb9c25c73549e0ce3cce16

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+Initial release.
+
+- Add GitHub Actions CI for Ruby matrix testing.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hmdne
+
+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,285 @@
+# PatchUtil
+
+PatchUtil is a Ruby library and CLI for splitting one large patch into a sequence of smaller, reviewable patches. It is designed around an `inspect -> plan -> apply` workflow that works well for both humans and AI agents.
+
+The main surface is the `split` subsystem:
+
+- `split inspect` shows a patch with stable hunk and changed-line labels
+- `split plan` turns those labels into named split chunks
+- `split apply` materializes the saved plan as ordered patch files or rewritten commits
+
+The `rewrite` subsystem is supporting machinery for harder git-history splits. It manages retained rewrite state, conflict recovery, and resume/restore flows after `split apply --rewrite` has started.
+
+The API and CLI are still evolving and should be considered unstable until version 1.0.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "patch_util"
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+If you want the gem installed directly:
+
+```sh
+gem install patch_util
+```
+
+For local development from this checkout:
+
+```sh
+bundle install
+bundle exec rake spec
+```
+
+## Why PatchUtil
+
+PatchUtil is built for cases where one diff or one commit mixes several independent intent units.
+
+Typical examples:
+
+- split a large refactor into reviewable commits
+- separate rename/mode metadata from later content edits
+- split one earlier git commit and replay descendants on top
+- let an AI agent inspect a large patch, propose chunk boundaries, and then apply them deterministically
+
+The project uses stable hunk labels (`a`, `b`, `c`) and changed-line labels (`a1`, `a2`, `b1`) so plans can stay textual and easy to generate.
+
+## Split Workflow
+
+The normal workflow is:
+
+1. inspect the commit or patch
+2. choose selectors for named chunks
+3. persist the plan
+4. apply the plan
+
+### Inspect
+
+Choose source options based on what you are splitting:
+
+- use `--repo` plus `--commit` for a git-backed split workflow
+- use `--patch` (and usually `--plan`) for a standalone patch-file workflow
+- these flags are contextual source selectors, not mandatory boilerplate on every invocation
+
+Inspect a git commit:
+
+```sh
+patch_util split inspect --repo /path/to/repo --commit HEAD~2
+```
+
+Inspect a patch file:
+
+```sh
+patch_util split inspect --patch sample.diff --plan sample.plan.json
+```
+
+The output labels hunks and changed lines so you can refer to them later:
+
+- whole hunks: `a`, `b`, `c`
+- whole-hunk ranges: `a-c`, `z-ab`
+- single changed lines: `a1`, `a2`
+- ranges inside one hunk: `a1-a4`
+
+Default inspect output is the full annotated diff because it is the authoritative planning surface.
+
+### Compact Inspect For Agents
+
+For large commits, especially vendor-heavy ones, compact inspect gives a skim-friendly overview:
+
+```sh
+patch_util split inspect --repo /path/to/repo --commit HEAD~2 --compact
+```
+
+Compact mode keeps the same labels but adds a layered summary:
+
+- compact legend
+- file index
+- per-file and per-hunk counts
+- largest-first index ordering
+- compact hunk summaries in original diff order
+
+You can then drill into only the hunks that matter:
+
+```sh
+patch_util split inspect --repo /path/to/repo --commit HEAD~2 --compact --expand a-c,br
+```
+
+That keeps the compact skim for the whole patch while expanding only the selected hunks to full annotated row bodies.
+
+`--expand` is intentionally narrow:
+
+- it only works together with `--compact`
+- it accepts whole-hunk labels and hunk ranges such as `a,b,br` or `a-c`
+- it does not accept changed-line selectors such as `a1-a4`
+
+Recommended agent loop for very large commits:
+
+1. start with full `split inspect` if the patch still looks manageable
+2. switch to `--compact` when the patch is too noisy to scan directly
+3. use `--expand` only on the few hunks that look relevant
+4. move to `split plan` once the chunk boundaries are clear
+
+### Plan
+
+Create a split plan from named chunks and selectors:
+
+```sh
+patch_util split plan \
+  --repo /path/to/repo \
+  --commit HEAD~2 \
+  "rename and setup" "a-b" \
+  "logic change" "c1-c4,d" \
+  "leftovers"
+```
+
+Selectors can combine whole hunks and changed-line ranges:
+
+```text
+a-c,e1-e4,e6
+```
+
+Rules:
+
+- selecting a whole hunk and partial lines from that same hunk is an error
+- overlapping selections across chunks are an error
+- if changed lines are left unassigned, planning fails unless you declare a leftovers chunk
+- leftovers are declared as the final positional chunk name, with no selector text after it
+
+If you do not specify a leftovers chunk, PatchUtil fails closed instead of silently dropping the unassigned changes. That is deliberate: omitted leftovers would otherwise mean those changed lines disappear from the emitted patches or rewritten history.
+
+Today, PatchUtil treats that as a safety stop, even though removal might sometimes be the right outcome. In those cases, the current workflow is to re-plan explicitly rather than relying on implicit omission.
+
+Example with leftovers:
+
+```sh
+patch_util split plan \
+  --repo /path/to/repo \
+  --commit HEAD~2 \
+  "rename metadata" "a" \
+  "core logic" "b1-b5,c-d" \
+  "leftovers"
+```
+
+Inside a git repository, plans default to `.git/patch_util/plans.json`.
+
+### Apply
+
+Materialize the saved plan as patch files:
+
+```sh
+patch_util split apply \
+  --patch sample.diff \
+  --plan sample.plan.json \
+  --output-dir out
+```
+
+Use this mode when you want PatchUtil to emit patch files only, without changing git history.
+
+Apply a saved git-backed plan by rewriting an earlier commit:
+
+```sh
+patch_util split apply \
+  --repo /path/to/repo \
+  --commit HEAD~2 \
+  --rewrite
+```
+
+Use `--rewrite` only when the split should become real replacement commits inside the repository history. In other words:
+
+- without `--rewrite`, PatchUtil emits patch files
+- with `--rewrite`, PatchUtil replaces the targeted commit with one commit per chunk and then replays later descendants on top
+
+When rewriting history, PatchUtil:
+
+- creates one replacement commit per named chunk
+- preserves the original split commit's author, committer, body, and trailers
+- appends `Split-from:` and `Original-subject:` metadata
+- replays later descendants on top
+- records a backup ref under `refs/patch_util-backups/...`
+
+Current rewrite guardrails:
+
+- merge commits are rejected as split targets
+- descendant replay is only supported on linear history; replay ranges containing merge commits fail up front
+
+## Rewrite Subsystem
+
+The top-level `rewrite` commands are mainly recovery and inspection tools for difficult history rewrites.
+
+You normally start from `split apply --rewrite`, and only use `rewrite ...` if the rewrite needs help afterward.
+
+For agents, this boundary matters:
+
+- prefer `split inspect`, `split plan`, and `split apply` in normal explanations
+- treat `rewrite ...` as recovery/support tooling, not the default planning interface
+- surface `rewrite status`, `rewrite conflicts`, `rewrite continue`, and `rewrite restore` after a rewrite has already started or failed
+
+Examples:
+
+```sh
+patch_util rewrite status
+patch_util rewrite conflicts
+patch_util rewrite continue
+patch_util rewrite restore
+```
+
+This layer exists so harder split rewrites can be resumed, inspected, or restored without mixing that recovery flow into the main `split` planning UX.
+
+## After PatchUtil
+
+PatchUtil handles the split itself. After that, you may still want ordinary git history-polish steps outside PatchUtil.
+
+Human-driven follow-up:
+
+- use `git rebase -i` later if you want to combine adjacent split commits, reorder them, or reword commit messages
+
+Agent-friendly or non-TTY follow-up:
+
+- use non-interactive git commands such as `git commit --amend -m ...`, `git reset --soft HEAD~2 && git commit ...`, or scripted cherry-pick/replay flows when you need similar cleanup without an interactive editor
+
+Those steps are outside PatchUtil's command surface, but they fit naturally after `split apply --rewrite` has produced the first-pass split history.
+
+## Agent Skill
+
+PatchUtil is intended to be usable by AI agents. This repository includes a `SKILL.md` focused on the `split` workflow.
+
+OpenCode one-liner install:
+
+```sh
+mkdir -p ~/.config/opencode/skills/patch_util && curl -fsSL https://raw.githubusercontent.com/rbutils/patch_util/master/SKILL.md -o ~/.config/opencode/skills/patch_util/SKILL.md
+```
+
+After that, OpenCode can discover the skill from the standard global skills directory.
+
+## Development
+
+After checking out the repo, run:
+
+```sh
+bundle install
+bundle exec rake spec
+```
+
+You can run the executable directly from the checkout:
+
+```sh
+bundle exec exe/patch_util version
+bundle exec exe/patch_util split help
+bundle exec exe/patch_util rewrite help
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rbutils/patch_util.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: patch_util
+description: Split large diffs or commits into smaller reviewable patches with an inspect -> plan -> apply workflow. Prefer the split subsystem; use rewrite only for retained rewrite recovery and harder history-rewrite cases.
+license: MIT
+---
+
+# PatchUtil Skill
+
+Use this skill when you need to break one large git commit or diff into smaller reviewable units.
+
+## When To Use It
+
+- a git commit should be split into several commits
+- a patch file needs the same inspect -> plan -> apply treatment outside a repository
+- you need a stable textual selector language for agent-planned patch splits
+- a large commit is easier to navigate in compact inspect mode before choosing split boundaries
+
+## Preferred Workflow
+
+Default to the `split` subsystem:
+
+1. `split inspect` on the git commit you want to split
+2. `split plan` against that same git-backed source
+3. `split apply --rewrite` when the split should become real replacement commits
+
+Source selectors are contextual:
+
+- use `--repo` with `--commit` for the primary git-backed workflow
+- use `--patch` for standalone diff files when there is no repository-backed source
+- `--repo` and `--commit` are optional source selectors, not mandatory boilerplate
+- these flags are not all required at once; they describe which source PatchUtil should inspect or apply
+
+Treat the top-level `rewrite` subsystem as advanced recovery machinery for `split apply --rewrite`, not as the first thing to expose to users.
+
+## Core Commands
+
+Primary git-backed inspect:
+
+```sh
+patch_util split inspect --repo /path/to/repo --commit HEAD~2
+```
+
+Compact inspect for a large git commit:
+
+```sh
+patch_util split inspect --repo /path/to/repo --commit HEAD~2 --compact
+```
+
+Compact inspect with targeted drill-down:
+
+```sh
+patch_util split inspect --repo /path/to/repo --commit HEAD~2 --compact --expand a-c,br
+```
+
+Git-backed planning:
+
+```sh
+patch_util split plan \
+  --repo /path/to/repo \
+  --commit HEAD~2 \
+  "first chunk" "a-c" \
+  "second chunk" "d1-d4,e" \
+  "leftovers"
+```
+
+Use `--expand` only with `--compact`, and only with whole-hunk labels or hunk ranges.
+
+Git-backed apply by rewriting the original history:
+
+```sh
+patch_util split apply \
+  --repo /path/to/repo \
+  --commit HEAD~2 \
+  --rewrite
+```
+
+Use `--rewrite` only when the result should become real replacement commits in repository history. If you only want emitted patch files, use `split apply` without `--rewrite` and provide `--output-dir` instead.
+
+Patch-file inspect remains available when there is no repo-backed source:
+
+```sh
+patch_util split inspect --patch sample.diff --plan sample.plan.json
+```
+
+Patch-file apply remains available when you want emitted patch files instead of history rewrite:
+
+```sh
+patch_util split apply --patch sample.diff --plan sample.plan.json --output-dir out
+```
+
+## Selector Rules
+
+- whole hunks use labels like `a`, `b`, `c`
+- whole-hunk ranges use labels like `a-c` or `z-ab`
+- changed lines use labels like `a1`, `a2`, `b1`
+- ranges must stay inside one hunk, for example `a1-a4`
+- do not mix whole-hunk and partial selection for the same hunk in one plan
+- if anything is intentionally left unassigned, add a leftovers chunk name as the final positional argument to `split plan`
+
+If no leftovers chunk is declared, PatchUtil fails instead of silently removing unassigned changes. That fail-closed behavior is deliberate: implicit omission would otherwise drop those changes from the output. If removal is actually intended, PatchUtil currently expects a more explicit re-plan rather than treating missing leftovers as permission to delete.
+
+## Agent Guidance
+
+- start with git-backed `split inspect --repo ... --commit ...` unless the work is explicitly patch-file-only
+- use `--compact` for large or noisy commits
+- use `--expand` only after compact inspect has identified the interesting hunks
+- keep `--expand` inputs at whole-hunk labels or hunk ranges only; changed-line selectors belong to `split plan`, not to compact drill-down
+- propose chunk names based on reviewable intent, not file count alone
+- preserve rename/mode/file-operation intent as first-class patch units when present
+- prefer `split` language in explanations; mention `rewrite` only when recovery or history replay becomes relevant
+- surface `rewrite` commands only after `split apply --rewrite` has started or failed
+
+## Rewrite Notes
+
+If `split apply --rewrite` hits trouble, the retained rewrite commands are available:
+
+- `rewrite status`
+- `rewrite conflicts`
+- `rewrite continue`
+- `rewrite restore`
+
+These are support tools for difficult rewrite cases, not the main planning interface.
+
+Rewrite guardrails still apply:
+
+- merge commits are not supported as split targets
+- descendant replay ranges containing merge commits are rejected up front
+
+## After The Split
+
+PatchUtil's job is to produce the split cleanly. After that, normal git tools may still be useful.
+
+- a human may use `git rebase -i` later to combine split commits, reorder them, or reword commit messages
+- agents should prefer non-interactive follow-up commands such as `git commit --amend -m ...`, `git reset --soft HEAD~2 && git commit ...`, or scripted cherry-pick/replay flows instead of assuming an interactive TTY editor
+- those follow-up git steps are outside PatchUtil itself, but they are normal after `split apply --rewrite` has created the first-pass split history
+
+## Installation
+
+If `patch_util` is not available on the machine yet, install the gem first:
+
+```sh
+gem install patch_util
+```
+
+Agents should do that whenever they intend to use the tool and the command is not available.
+
+OpenCode global install:
+
+```sh
+mkdir -p ~/.config/opencode/skills/patch_util && curl -fsSL https://raw.githubusercontent.com/rbutils/patch_util/master/SKILL.md -o ~/.config/opencode/skills/patch_util/SKILL.md
+```
+
+Repo-local install:
+
+```sh
+mkdir -p .opencode/skills/patch_util && cp SKILL.md .opencode/skills/patch_util/SKILL.md
+```

data/exe/patch_util

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require "patch_util"
+
+begin
+  PatchUtil::CLI.start(ARGV)
+rescue PatchUtil::Error => e
+  warn e.message
+  exit 1
+end

data/lib/patch_util/cli.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module PatchUtil
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'version', 'Display PatchUtil version'
+    def version
+      puts PatchUtil::VERSION
+    end
+
+    desc 'rewrite SUBCOMMAND ...ARGS', 'Manage retained git rewrite sessions'
+    subcommand 'rewrite', PatchUtil::Git::RewriteCLI
+
+    desc 'split SUBCOMMAND ...ARGS', 'Inspect, plan, and emit split patches'
+    subcommand 'split', PatchUtil::Split::CLI
+  end
+end

data/lib/patch_util/diff.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module PatchUtil
+  Diff = Data.define(:source, :file_diffs) do
+    def hunks
+      file_diffs.flat_map(&:hunks)
+    end
+
+    def change_rows
+      hunks.flat_map(&:change_rows)
+    end
+
+    def hunk_by_label(label)
+      hunks.find { |hunk| hunk.label == label }
+    end
+
+    def row_by_id(row_id)
+      hunks.each do |hunk|
+        row = hunk.rows.find { |candidate| candidate.id == row_id }
+        return row if row
+      end
+      nil
+    end
+  end
+
+  FileDiff = Data.define(:old_path, :new_path, :hunks, :diff_git_line, :metadata_lines) do
+    def modification?
+      old_path != '/dev/null' && new_path != '/dev/null'
+    end
+
+    def addition?
+      old_path == '/dev/null'
+    end
+
+    def deletion?
+      new_path == '/dev/null'
+    end
+
+    def rename?
+      metadata_lines.any? { |line| line.start_with?('rename from ') || line.start_with?('rename to ') }
+    end
+
+    def copy?
+      metadata_lines.any? { |line| line.start_with?('copy from ') || line.start_with?('copy to ') }
+    end
+
+    def binary?
+      hunks.any?(&:binary?)
+    end
+
+    def operation_hunks
+      hunks.select(&:operation?)
+    end
+
+    def operation_hunk
+      operation_hunks.first
+    end
+
+    def path_operation_hunk
+      operation_hunks.find(&:path_change?)
+    end
+
+    def text_hunks
+      hunks.select(&:text?)
+    end
+  end
+
+  Hunk = Data.define(:label, :old_start, :old_count, :new_start, :new_count, :section, :rows, :kind, :patch_lines) do
+    def change_rows
+      rows.select(&:change?)
+    end
+
+    def change_lines
+      lines = []
+      change_rows.each do |row|
+        lines << ChangeLine.new(
+          label: row.change_label,
+          row_id: row.id,
+          kind: row.kind,
+          text: row.text,
+          old_lineno: row.old_lineno,
+          new_lineno: row.new_lineno
+        )
+      end
+      lines
+    end
+
+    def operation?
+      kind == :file_operation
+    end
+
+    def binary?
+      kind == :binary
+    end
+
+    def text?
+      kind == :text
+    end
+
+    def path_change?
+      patch_lines.any? do |line|
+        line.start_with?('rename from ') || line.start_with?('rename to ') ||
+          line.start_with?('copy from ') || line.start_with?('copy to ')
+      end
+    end
+  end
+
+  Row = Data.define(:id, :kind, :text, :old_lineno, :new_lineno, :change_label, :change_ordinal) do
+    def change?
+      !change_ordinal.nil?
+    end
+
+    def display_prefix
+      case kind
+      when :context
+        ' '
+      when :deletion
+        '-'
+      when :addition
+        '+'
+      when :file_operation
+        '='
+      when :binary
+        '='
+      else
+        raise PatchUtil::UnsupportedFeatureError, "unknown row kind: #{kind.inspect}"
+      end
+    end
+  end
+
+  ChangeLine = Data.define(:label, :row_id, :kind, :text, :old_lineno, :new_lineno)
+end