gem_override_marker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 265013f3f192df295c3802b378f3251fdfb9594d03bf3b7b274625ca5bae7545
+  data.tar.gz: 7dc4627efb1af8adb2f883d0bc306961ede5a23fedb182a88f9f131c58dd2dda
+SHA512:
+  metadata.gz: 7659a48c44abb5afe4dde1b9c6085d3fec4973e59455357ea3800753d4d0e4d5eb77340a4c5bf3814024cc477a6f5fa4b09f1cdf74f83cc65ce6c96d7552526a
+  data.tar.gz: acd6fdf55af7c6688a2ea7b2b8ee12060dc1b95ca404dd23958f9b76e66d2a631b4942d80fc553a52066a34a88b38565cea5f742f977880a02ca026bdc28a94b

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: ../../.rubocop.yml

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 be agile Co., Ltd.
+
+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.ja.md

@@ -0,0 +1,302 @@
+# gem_override_marker
+
+[English](README.md) | 日本語
+
+gem の中のメソッドや view をカスタムしたいとき、本家のメソッドや view を
+コピーして必要な箇所だけ修正することがあります。この方法は、gem のバージョン
+アップ時にコピー元のメソッドや view が書き換わっていると、変更に気づけず
+バグにつながります。
+
+`gem_override_marker` は、gem のバージョンアップ時に、新しいバージョンへ
+同等のカスタムを効率的に再適用するための手段を提供します。
+
+## 使い方 (チュートリアル)
+
+`greeter` という gem に `Greeter::Message#hello` というメソッドがあるとします。
+
+```ruby
+# greeter 1.0.0 の本家コード:
+# gems/greeter-1.0.0/lib/greeter/message.rb
+module Greeter
+  class Message
+    def hello(name)
+      "Hello, #{name}."
+    end
+  end
+end
+```
+
+### 1. カスタムして、マーカーを書く
+
+この挨拶を日本語にしたい。本家を再オープンして `hello` を上書きします
+(モンキーパッチ)。このとき、**どの gem の・どの版の・どこを基準にしたか**を
+マーカーで1行書いておきます。
+
+```ruby
+# app/overrides/greeter_patch.rb
+# @gem-override greeter-1.0.0/lib/greeter/message.rb#hello
+# @see https://github.com/your-org/your-repo/issues/42
+module Greeter
+  class Message
+    def hello(name)
+      "こんにちは、#{name}さん。"
+    end
+  end
+end
+```
+
+### 2. マーカーが認識されているか確認
+
+```console
+$ rake gem_override_marker:list
+app/overrides/greeter_patch.rb:2	greeter-1.0.0/lib/greeter/message.rb#hello
+
+1 marker(s)
+```
+
+ついでに、本家との差分（＝自分が何を変えたか）も今すぐ見られます。
+
+```console
+$ rake gem_override_marker:diff
+--- source greeter-1.0.0/lib/greeter/message.rb#hello
++++ override app/overrides/greeter_patch.rb#hello
+@@ -1,3 +1,3 @@
+ def hello(name)
+-  "Hello, #{name}."
++  "こんにちは、#{name}さん。"
+ end
+```
+
+### 3. gem がバージョンアップした
+
+`greeter` 2.0.0 が出て、本家の `hello` の実装が変わったとします。
+
+```ruby
+# greeter 2.0.0 の本家コード (実装が変わった):
+module Greeter
+  class Message
+    def hello(name)
+      greeting = "Hello"
+      "#{greeting}, #{name}! Welcome."
+    end
+  end
+end
+```
+
+`Gemfile` を 2.0.0 に上げて `bundle update` します。**自分のカスタムは
+まだ 1.0.0 ベースのまま**で、本家の `! Welcome.` のような変更は反映されて
+いません。
+
+### 4. 「以前の版で何を変えたか」を確認する
+
+`bundle update` しても 1.0.0 のソースは `gems/` に残っています。マーカーは
+まだ `greeter-1.0.0` を指しているので、`diff` は **1.0.0 の本家 vs 自分の
+カスタム**、つまり「自分が何を変えたか」をそのまま見せてくれます。
+
+```console
+$ rake gem_override_marker:diff
+--- source greeter-1.0.0/lib/greeter/message.rb#hello
++++ override app/overrides/greeter_patch.rb#hello
+@@ -1,3 +1,3 @@
+ def hello(name)
+-  "Hello, #{name}."
++  "こんにちは、#{name}さん。"
+ end
+```
+
+→ 自分がやったのは「挨拶を日本語にした」だけだと分かります。
+
+### 5. 新しい本家に、その変更を当て直す
+
+本家 2.0.0 の新しい実装（`greeting` 変数・`Welcome.` の追加）を土台にして、
+自分の変更（日本語化）だけを乗せ直します。あわせてマーカーの版を 2.0.0 に
+更新します。
+
+```ruby
+# app/overrides/greeter_patch.rb
+# @gem-override greeter-2.0.0/lib/greeter/message.rb#hello
+# @see https://github.com/your-org/your-repo/issues/42
+module Greeter
+  class Message
+    def hello(name)
+      greeting = "こんにちは"
+      "#{greeting}、#{name}さん！ようこそ。"
+    end
+  end
+end
+```
+
+最後に、新しい本家との差分が意図通り（日本語化だけ）になっているか確認します。
+
+```console
+$ rake gem_override_marker:diff
+--- source greeter-2.0.0/lib/greeter/message.rb#hello
++++ override app/overrides/greeter_patch.rb#hello
+@@ -1,4 +1,4 @@
+ def hello(name)
+-  greeting = "Hello"
+-  "#{greeting}, #{name}! Welcome."
++  greeting = "こんにちは"
++  "#{greeting}、#{name}さん！ようこそ。"
+ end
+```
+
+本家 2.0.0 の `Welcome.` を取りこぼさず、自分の「日本語化」だけが差分として
+残りました。これで追随完了です。
+
+## 設計の考え方：「自分の差分」を新本家に塗り直す
+
+チュートリアルのステップ 4〜5 がこのツールの肝です。提供する差分が
+「**本家 vs 自分の上書き**」だけなのは、次の考え方を前提にしているためです。
+
+- ✅ **自分が本家に加えた差分だけを確認し、それを新しい本家に対して当て直す**
+- ❌ 「旧本家と新本家の差分」を上書きに取り込む、ではない
+
+後者は本家が大規模にリファクタしていると無関係な差分が大量に出るだけで大変
+です。自分が知るべきは「自分が何を変えたか」だけで、それを新しい土台に塗り
+直す方がずっと簡単です。上書きが10個あっても、見るのは「自分が触った箇所」
+だけ。本家の巨大な changelog を全部読む必要はありません。
+
+これを成立させているのが「`bundle update` しても旧版のソースは `gems/` に残る」
+という事実です。マーカーが旧版を指している限り、新版を入れた後でも
+「旧版 vs 自分の上書き」を再生でき、それを見ながら新版に当て直せます。
+
+### 本家が変わった上書きを選別する (upstream_diff)
+
+複数の gem をまとめてバージョンアップしたとき、全ての上書きを律儀に当て直す
+のは無駄です。上書き対象によっては本家側が一切変わっておらず、その場合は
+マーカーの版を上げるだけで済みます。`upstream_diff` は、各マーカーの対象に
+ついて **本家の2版間 (旧版 → 新版) の差分** を出すことで、この2グループを
+選別します (本家 vs 自分の上書き、ではない点に注意)。
+
+```console
+$ rake gem_override_marker:upstream_diff
+========================================================================
+app/overrides/greeter_patch.rb:2  greeter-1.0.0/lib/greeter/message.rb#hello
+========================================================================
+--- upstream greeter-1.0.0/lib/greeter/message.rb#hello
++++ upstream greeter-2.0.0/lib/greeter/message.rb#hello
+@@ -1,3 +1,4 @@
+ def hello(name)
+-  "Hello, #{name}."
++  greeting = "Hello"
++  "#{greeting}, #{name}! Welcome."
+ end
+```
+
+- **変更なし** (`(no upstream change)`) → 本家はその箇所を触っていないので、
+  上書きコードはそのままにして、マーカーの版だけ上げます (例: 1.0.0 → 2.0.0)。
+- **変更あり** → `diff` で「自分が何を変えたか」を確認し、ステップ 5 の要領で
+  新しい本家に当て直して、マーカーの版を上げます。
+
+比較先の版は省略時 `Gemfile.lock` の版 (アップグレード後の版) を使います。
+`to_version` を渡せば任意の版と比較できます。これは設計の考え方を崩しません
+— 本家の差分を上書きにマージするのではなく、「どこを当て直す必要があるか」を
+見極めるための道具です。
+
+### マーカーの版ズレを検出する (check)
+
+当て直した後にマーカーの版を更新し忘れると、マーカーが指す版 (旧版) と
+`Gemfile.lock` の実際の版 (新版) がズレます。`check` はこのズレを検出し、
+ズレがあれば終了コード 1 で落とします (CI で回せる)。マーカーを「付けた
+まま放置」にしないための番人です。
+
+```console
+$ rake gem_override_marker:check
+❌ Marker versions differ from Gemfile.lock (possible outdated overrides):
+  app/overrides/greeter_patch.rb:2
+    marker version: greeter-1.0.0
+    locked version: greeter-2.0.0
+```
+
+## マーカーの書き方
+
+上書きしているメソッドの直前 / 上書きファイルの冒頭に1行で宣言します。
+
+```ruby
+# @gem-override spree_core-5.1.6/app/models/spree/stock/packer.rb#default_package
+def default_package
+  # ...
+end
+```
+
+view / partial の丸ごと上書きはメソッド名を省略し、ファイル全体を対象とします。
+
+```erb
+<%# @gem-override spree_storefront-5.1.6/app/views/spree/products/_cart_form.html.erb %>
+```
+
+マーカー1行の形式は `{gem名}-{バージョン}/{gem内パス}#{メソッド名}` です。
+gem 名を含むため、1リポジトリから複数 gem が配布される場合 (Spree 等) でも
+「どの gem の版と比較するか」が一意に決まります。
+
+ツールが処理に使うのは `@gem-override` の行だけです。なぜその上書きをしたのか、
+関連 issue はどれか、といった補足は、続く行に自由に書けます (ツールは無視します)。
+issue へのポインタを残すなら YARD の `@see` タグが使えます。
+
+```ruby
+# @gem-override spree_core-5.1.6/app/models/spree/stock/packer.rb#default_package
+# @see https://github.com/your-org/your-repo/issues/1187
+def default_package
+  # ...
+end
+```
+
+マーカーは「コメント記号 + 半角スペース1個ちょうど + `@gem-override`」で
+始まる行だけを有効とします。ドキュメント中で字下げして例示したものや、文中に
+引用したものを誤検出しないためです。
+
+## コマンドリファレンス
+
+```bash
+# マーカー一覧
+rake gem_override_marker:list
+
+# 本家 vs 上書き の差分 (マーカーの版を基準に比較)
+rake gem_override_marker:diff
+
+# 本家2版間の差分 (旧版 → Gemfile.lock の版、または指定した to_version)
+rake gem_override_marker:upstream_diff
+rake gem_override_marker:upstream_diff[,2.0.0]
+
+# マーカーの版と Gemfile.lock の版のズレ検出 (ズレがあれば exit 1)
+rake gem_override_marker:check
+```
+
+引数なしの `list` / `diff` / `upstream_diff` / `check` はリポジトリ全体の
+全マーカーが対象です。引数 (selector) で対象を狙い撃ちできます。
+
+```bash
+# ① 上書きファイルのパス → ファイル内の全マーカー
+rake gem_override_marker:diff[app/overrides/greeter_patch.rb]
+
+# ② パス + メソッド名 → そのメソッドだけ
+rake gem_override_marker:diff[app/overrides/greeter_patch.rb,hello]
+
+# ③ マーカーの論理名そのまま → 一意に狙い撃ち
+rake gem_override_marker:diff[greeter-1.0.0/lib/greeter/message.rb#hello]
+```
+
+## 動作の仕組み
+
+参考までに、内部の処理は次の通りです。
+
+- **メソッド抽出**: Ruby 3.3 標準の `prism` でソースを AST 解析し、対象メソッドの
+  `DefNode` だけを slice します。`def` から `end` を正規表現で切り出すのは
+  ネストした `end` の判別ができず不可能なため、パーサで抽出します。
+- **インデント正規化**: 本家 (class 直下) と上書き (module 多階層) の
+  ネスト差を吸収するため、抽出後に dedent します。
+- **diff**: `diff-lcs` で unified diff を生成します。
+- **本家ソース解決**: 実環境の gem インストールパス
+  (`Gem.path` 配下の `gems/{gem名}-{版}/`) から解決します。`upstream_diff` は
+  同じパス解決を2つの版に対して行い (「`bundle update` しても旧版のソースは
+  `gems/` に残る」ことを利用)、同じ抽出処理で両者を diff します。
+- **版の照合 (check)**: `Bundler::LockfileParser` で `Gemfile.lock` を読み、
+  マーカーの版と突き合わせます。`Gemfile.lock` のパスは Bundler が自動解決します。
+
+これらは本家・上書きをテキストとして解析するだけなので、Rails の
+`:environment` には依存せず、DB 接続やアプリ初期化を起動せずに動きます。
+
+## License
+
+MIT

data/README.md

@@ -0,0 +1,316 @@
+# gem_override_marker
+
+English | [日本語](README.ja.md)
+
+When you want to customize a method or view inside a gem, you often copy the
+upstream method or view and edit just the parts you need. The problem: when the
+gem is upgraded and the original method or view has changed, you won't notice,
+and that silently becomes a bug.
+
+`gem_override_marker` gives you a way to efficiently re-apply your customization
+to the new version when a gem is upgraded.
+
+## Tutorial
+
+Suppose a gem `greeter` has a method `Greeter::Message#hello`.
+
+```ruby
+# Upstream code of greeter 1.0.0:
+# gems/greeter-1.0.0/lib/greeter/message.rb
+module Greeter
+  class Message
+    def hello(name)
+      "Hello, #{name}."
+    end
+  end
+end
+```
+
+### 1. Customize it, and write a marker
+
+Say you want the greeting in Japanese. You reopen the class and override `hello`
+(a monkey patch). At this point you write a one-line **marker** declaring
+**which gem, which version, and what you based it on**.
+
+```ruby
+# app/overrides/greeter_patch.rb
+# @gem-override greeter-1.0.0/lib/greeter/message.rb#hello
+# @see https://github.com/your-org/your-repo/issues/42
+module Greeter
+  class Message
+    def hello(name)
+      "こんにちは、#{name}さん。"
+    end
+  end
+end
+```
+
+### 2. Check that the marker is recognized
+
+```console
+$ rake gem_override_marker:list
+app/overrides/greeter_patch.rb:2	greeter-1.0.0/lib/greeter/message.rb#hello
+
+1 marker(s)
+```
+
+You can also see the diff against upstream (i.e. what you changed) right away.
+
+```console
+$ rake gem_override_marker:diff
+--- source greeter-1.0.0/lib/greeter/message.rb#hello
++++ override app/overrides/greeter_patch.rb#hello
+@@ -1,3 +1,3 @@
+ def hello(name)
+-  "Hello, #{name}."
++  "こんにちは、#{name}さん。"
+ end
+```
+
+### 3. The gem gets upgraded
+
+Suppose `greeter` 2.0.0 is released and the upstream `hello` implementation has
+changed.
+
+```ruby
+# Upstream code of greeter 2.0.0 (implementation changed):
+module Greeter
+  class Message
+    def hello(name)
+      greeting = "Hello"
+      "#{greeting}, #{name}! Welcome."
+    end
+  end
+end
+```
+
+You bump `Gemfile` to 2.0.0 and run `bundle update`. **Your customization is
+still based on 1.0.0**, so upstream changes like `! Welcome.` are not reflected.
+
+### 4. See "what you changed in the old version"
+
+Even after `bundle update`, the 1.0.0 source remains under `gems/`. Since the
+marker still points to `greeter-1.0.0`, `diff` shows **upstream 1.0.0 vs your
+customization** — that is, exactly what you changed.
+
+```console
+$ rake gem_override_marker:diff
+--- source greeter-1.0.0/lib/greeter/message.rb#hello
++++ override app/overrides/greeter_patch.rb#hello
+@@ -1,3 +1,3 @@
+ def hello(name)
+-  "Hello, #{name}."
++  "こんにちは、#{name}さん。"
+ end
+```
+
+→ You can see that all you did was "make the greeting Japanese".
+
+### 5. Re-apply that change onto the new upstream
+
+Take upstream 2.0.0's new implementation (the `greeting` variable and the added
+`Welcome.`) as the base, and re-apply only your change (the Japanese greeting).
+Also update the marker version to 2.0.0.
+
+```ruby
+# app/overrides/greeter_patch.rb
+# @gem-override greeter-2.0.0/lib/greeter/message.rb#hello
+# @see https://github.com/your-org/your-repo/issues/42
+module Greeter
+  class Message
+    def hello(name)
+      greeting = "こんにちは"
+      "#{greeting}、#{name}さん！ようこそ。"
+    end
+  end
+end
+```
+
+Finally, confirm that the diff against the new upstream is as intended (just the
+Japanese greeting).
+
+```console
+$ rake gem_override_marker:diff
+--- source greeter-2.0.0/lib/greeter/message.rb#hello
++++ override app/overrides/greeter_patch.rb#hello
+@@ -1,4 +1,4 @@
+ def hello(name)
+-  greeting = "Hello"
+-  "#{greeting}, #{name}! Welcome."
++  greeting = "こんにちは"
++  "#{greeting}、#{name}さん！ようこそ。"
+ end
+```
+
+Upstream 2.0.0's `Welcome.` is preserved, and only your "Japanese greeting" shows
+up as the diff. You have successfully kept up with the upgrade.
+
+## Design philosophy: re-apply "your diff" onto the new upstream
+
+Steps 4–5 of the tutorial are the heart of this tool. The diff it provides is
+only "**upstream vs your override**", and that is by design — it assumes you
+work this way:
+
+- ✅ **Review only the diff you added on top of upstream, then re-apply it onto
+  the new upstream**
+- ❌ NOT "merge the diff between old and new upstream into your override"
+
+The latter is painful: if upstream has been heavily refactored, a huge amount of
+unrelated diff shows up. All you need to know is "what you changed", and
+re-applying that onto the new base is far easier. Even if you have 10 overrides,
+you only look at the spots you touched — you don't have to read the entire
+upstream changelog.
+
+What makes this possible is the fact that **`bundle update` leaves the old
+version's source under `gems/`**. As long as the marker points to the old
+version, you can regenerate "old upstream vs your override" even after installing
+the new version, and use it as a guide while re-applying onto the new version.
+
+### Triaging which overrides upstream actually changed (upstream_diff)
+
+When many gems are upgraded at once, re-applying every override blindly is
+wasteful: some overrides target a spot upstream didn't touch at all, so all you
+need to do there is bump the marker version. `upstream_diff` tells the two
+groups apart by diffing the **two upstream versions** (old → new) for each
+marker's target — not upstream vs your override.
+
+```console
+$ rake gem_override_marker:upstream_diff
+========================================================================
+app/overrides/greeter_patch.rb:2  greeter-1.0.0/lib/greeter/message.rb#hello
+========================================================================
+--- upstream greeter-1.0.0/lib/greeter/message.rb#hello
++++ upstream greeter-2.0.0/lib/greeter/message.rb#hello
+@@ -1,3 +1,4 @@
+ def hello(name)
+-  "Hello, #{name}."
++  greeting = "Hello"
++  "#{greeting}, #{name}! Welcome."
+ end
+```
+
+- **No change** (`(no upstream change)`) → upstream didn't touch this spot, so
+  leave the override code alone and just bump the marker version (e.g. 1.0.0 →
+  2.0.0).
+- **Changed** → use `diff` to review what *you* changed, then re-apply it onto
+  the new upstream as in step 5, and bump the marker version.
+
+The target version defaults to the one in `Gemfile.lock` (the upgraded
+version). Pass `to_version` to compare against a specific version instead. This
+keeps the design philosophy intact — it does not merge upstream's diff into your
+override; it only helps you decide where re-applying is even needed.
+
+### Detecting version drift (check)
+
+If you forget to update the marker version after re-applying, the version the
+marker points to (old) and the actual version in `Gemfile.lock` (new) will
+drift. `check` detects this drift and exits with code 1 if found (so it can run
+in CI). It is the watchdog that keeps markers from being "set and forgotten".
+
+```console
+$ rake gem_override_marker:check
+❌ Marker versions differ from Gemfile.lock (possible outdated overrides):
+  app/overrides/greeter_patch.rb:2
+    marker version: greeter-1.0.0
+    locked version: greeter-2.0.0
+```
+
+## Writing markers
+
+Declare it on one line, right before the overridden method / at the top of the
+overriding file.
+
+```ruby
+# @gem-override spree_core-5.1.6/app/models/spree/stock/packer.rb#default_package
+def default_package
+  # ...
+end
+```
+
+For a whole-file override of a view / partial, omit the method name; the entire
+file is the target.
+
+```erb
+<%# @gem-override spree_storefront-5.1.6/app/views/spree/products/_cart_form.html.erb %>
+```
+
+The marker format is `{gem}-{version}/{path-in-gem}#{method}`. Because it
+includes the gem name, even when a single repository ships multiple gems (e.g.
+Spree), "which gem's version to compare against" is unambiguous.
+
+The tool only uses the `@gem-override` line. You can freely add notes on the
+following lines — why you made the override, which issue it relates to, etc.
+(the tool ignores them). To leave a pointer to an issue, the YARD `@see` tag
+works well.
+
+```ruby
+# @gem-override spree_core-5.1.6/app/models/spree/stock/packer.rb#default_package
+# @see https://github.com/your-org/your-repo/issues/1187
+def default_package
+  # ...
+end
+```
+
+Only lines that start with "comment marker + exactly one space + `@gem-override`"
+are treated as valid markers. This avoids false positives from indented examples
+in documentation or quoted mentions in prose.
+
+## Command reference
+
+```bash
+# List markers
+rake gem_override_marker:list
+
+# Diff upstream vs override (compared against the marker's version)
+rake gem_override_marker:diff
+
+# Diff two upstream versions for each marker (old → Gemfile.lock version, or a given to_version)
+rake gem_override_marker:upstream_diff
+rake gem_override_marker:upstream_diff[,2.0.0]
+
+# Detect drift between marker version and Gemfile.lock (exits 1 on mismatch)
+rake gem_override_marker:check
+```
+
+Without arguments, `list` / `diff` / `upstream_diff` / `check` target every
+marker in the repository. They also accept a selector argument to target
+specific markers.
+
+```bash
+# (1) override file path -> all markers in the file
+rake gem_override_marker:diff[app/overrides/greeter_patch.rb]
+
+# (2) path + method name -> just that method
+rake gem_override_marker:diff[app/overrides/greeter_patch.rb,hello]
+
+# (3) the marker's logical name -> a single unambiguous target
+rake gem_override_marker:diff[greeter-1.0.0/lib/greeter/message.rb#hello]
+```
+
+## How it works
+
+For reference, the internals are as follows.
+
+- **Method extraction**: Parses the source into an AST with `prism` (standard in
+  Ruby 3.3) and slices only the target method's `DefNode`. Cutting from `def` to
+  `end` with a regex is impossible because nested `end`s can't be distinguished,
+  so a parser is used.
+- **Indent normalization**: Upstream (directly under a class) and the override
+  (nested in modules) differ in nesting depth, so the slice is dedented to absorb
+  the difference.
+- **Diff**: Generates a unified diff with `diff-lcs`.
+- **Upstream source resolution**: Resolved from the actual gem install path
+  (`gems/{gem}-{version}/` under `Gem.path`). `upstream_diff` resolves the same
+  path for two versions — relying on `bundle update` leaving the old version's
+  source under `gems/` — and diffs them with the same extraction pipeline.
+- **Version check**: Reads `Gemfile.lock` with `Bundler::LockfileParser` and
+  compares against the marker's version. The `Gemfile.lock` path is resolved
+  automatically by Bundler.
+
+Since these only analyze upstream and the override as text, they do not depend on
+Rails' `:environment`; they run without booting DB connections or app
+initialization.
+
+## License
+
+MIT

data/gem_override_marker.gemspec

@@ -0,0 +1,33 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "gem_override_marker/version"
+
+Gem::Specification.new do |s|
+  s.platform    = Gem::Platform::RUBY
+  s.name        = "gem_override_marker"
+  s.version     = GemOverrideMarker::VERSION
+  s.summary     = "Track diffs between gem source and your prepend/copy overrides via markers"
+  s.description = <<~DESC
+    When you override a gem's method (e.g. with prepend) or copy a gem's
+    view/partial and edit it, upstream changes on upgrade can silently break it.
+    gem_override_marker lets you declare what each override is based on with a
+    @gem-override marker, and generate the diff against upstream on demand, so you
+    can efficiently re-apply your customization to the new version.
+  DESC
+  s.required_ruby_version = ">= 3.3"
+
+  s.author      = "be agile Co., Ltd."
+  s.email       = "develop@be-agile.jp"
+  s.homepage    = "https://github.com/be-agile/gem_override_marker"
+  s.licenses    = [ "MIT" ]
+
+  s.files       = `git ls-files`.split("\n").reject { |f| f.match(/^spec/) && !f.match(%r{^spec/fixtures}) }
+  s.require_path = "lib"
+
+  # prism は Ruby 3.3 以降は標準同梱だが、gem としての依存を明示しておく。
+  s.add_dependency "diff-lcs", ">= 1.2.0", "< 2.0"
+  s.add_dependency "prism", "~> 1.0"
+
+  s.add_development_dependency "rspec", "~> 3.0"
+end