copy_tuner_client 1.5.0 → 2.0.0

data/lib/copy_tuner_client/configuration.rb

@@ -10,7 +10,7 @@ require 'copy_tuner_client/copyray_middleware'
 
 module CopyTunerClient
   # Used to set up and modify settings for the client.
-  class Configuration
+  class Configuration # rubocop:disable Metrics/ClassLength
     # These options will be present in the Hash returned by {#to_hash}.
     OPTIONS = %i[api_key development_environments environment_name host
                  http_open_timeout http_read_timeout client_name client_url
@@ -18,7 +18,7 @@ module CopyTunerClient
                  proxy_port proxy_user secure polling_delay sync_interval
                  sync_interval_staging sync_ignore_path_regex logger
                  framework middleware disable_middleware disable_test_translation
-                 ca_file exclude_key_regexp local_first_key_regexp s3_host locales ignored_keys ignored_key_handler
+                 ca_file local_first_key_regexp s3_host locales ignored_keys ignored_key_handler
                  download_cache_dir].freeze
 
     # NOTE: Rails 標準ロケールで非文字列値（precision: Integer, significant: Boolean,
@@ -43,7 +43,8 @@ module CopyTunerClient
     attr_accessor :host
 
     # @return [Fixnum] The port on which your CopyTuner server runs (defaults to +443+ for secure connections, +80+ for insecure connections).
-    attr_accessor :port
+    # NOTE: reader は default_port フォールバック付きの明示定義（#port）があるため attr_accessor を使わない
+    attr_writer :port
 
     # @return [Boolean] +true+ for https connections, +false+ for http connections.
     attr_accessor :secure
@@ -94,7 +95,8 @@ module CopyTunerClient
     attr_accessor :polling_delay
 
     # @return [Integer] The time, in seconds, in between each sync to the server in development. Defaults to +60+.
-    attr_accessor :sync_interval
+    # NOTE: reader は environment で分岐する明示定義（#sync_interval）があるため attr_accessor を使わない
+    attr_writer :sync_interval
 
     # @return [Integer] The time, in seconds, in between each sync to the server in development. Defaults to +60+.
     attr_accessor :sync_interval_staging
@@ -128,10 +130,6 @@ module CopyTunerClient
 
     attr_accessor :poller
 
-    # @return [Regexp] Regular expression to exclude keys.
-    # @deprecated Use {#local_first_key_regexp} instead.
-    attr_reader :exclude_key_regexp
-
     # @return [Regexp] Keys (without locale) matching this regexp bypass the
     #   copy_tuner cache and are looked up from local config/locales
     #   (I18n::Backend::Simple) first. Used for gradual migration from
@@ -141,15 +139,12 @@ module CopyTunerClient
     # @return [String] The S3 host to connect to (defaults to +copy-tuner-us.s3.amazonaws.com+).
     attr_accessor :s3_host
 
-    # @return [Boolean] To disable Copyray comment injection, set true
+    # @return [Boolean] To disable Copyray marker injection, set true
     attr_accessor :disable_copyray_comment_injection
 
     # @return [Array<Symbol>] Restrict blurb locales to upload
     attr_accessor :locales
 
-    # @return [Boolean] Html escape
-    attr_accessor :html_escape
-
     # @return [Array<String>] A list of ignored keys
     attr_accessor :ignored_keys
 
@@ -165,7 +160,7 @@ module CopyTunerClient
     alias secure? secure
 
     # Instantiated from {CopyTunerClient.configure}. Sets defaults.
-    def initialize
+    def initialize # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       self.client_name = 'CopyTuner Client'
       self.client_url = 'https://rubygems.org/gems/copy_tuner_client'
       self.client_version = VERSION
@@ -182,7 +177,6 @@ module CopyTunerClient
       self.upload_disabled_environments = %w[production staging]
       self.s3_host = 'copy-tuner.sg-apps.com' # NOTE: cloudfront host
       self.disable_copyray_comment_injection = false
-      self.html_escape = true
       self.ignored_keys = []
       self.ignored_key_handler = ->(e) { raise e }
       self.local_first_key_regexp = nil
@@ -197,7 +191,7 @@ module CopyTunerClient
     # @param [Symbol] option Key for a given attribute
     # @return [Object] the given attribute
     def [](option)
-      send(option)
+      public_send(option)
     end
 
     # Returns a hash of all configurable options
@@ -206,7 +200,7 @@ module CopyTunerClient
       base_options = { public: public?, upload_disabled: upload_disabled? }
 
       OPTIONS.inject(base_options) do |hash, option|
-        hash.merge option.to_sym => send(option)
+        hash.merge option.to_sym => public_send(option)
       end
     end
 
@@ -258,7 +252,10 @@ module CopyTunerClient
     # This creates the {I18nBackend} and puts them together.
     #
     # When {#test?} returns +false+, the poller will be started.
-    def apply
+    def apply # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # NOTE: project_id は必須。未設定なら apply 時点で明示的に失敗させる
+      validate_project_id!
+
       self.locales ||= self.locales = if defined?(::Rails)
                                         ::Rails.application.config.i18n.available_locales.presence || Array(::Rails.application.config.i18n.default_locale)
                                       else
@@ -337,18 +334,6 @@ module CopyTunerClient
       @api_key = api_key
     end
 
-    # @deprecated Use {#local_first_key_regexp} instead.
-    def exclude_key_regexp=(value)
-      unless value.nil?
-        ActiveSupport::Deprecation.new.warn(
-          'exclude_key_regexp is deprecated and will be removed in a future release. ' \
-          'Use local_first_key_regexp instead (note: it matches keys WITHOUT the locale prefix, ' \
-          'e.g. /\Aviews\./ instead of /\Aja\.views\./).'
-        )
-      end
-      @exclude_key_regexp = value
-    end
-
     # Sync interval for Rack Middleware
     def sync_interval
       if environment_name == 'staging'
@@ -358,16 +343,11 @@ module CopyTunerClient
       end
     end
 
-    # @return [String] current project url by api_key
+    # @return [String] current project url by project_id
     def project_url
-      path =
-        if project_id
-          "/projects/#{project_id}"
-        else
-          ActiveSupport::Deprecation.new.warn('Please set project_id.')
-          "/projects/#{api_key}"
-        end
+      validate_project_id!
 
+      path = "/projects/#{project_id}"
       URI::Generic.build(scheme: self.protocol, host: self.host, port: self.port.to_i, path:).to_s
     end
 
@@ -389,6 +369,12 @@ module CopyTunerClient
 
     private
 
+    # project_id は必須。未設定なら明示的に失敗させる。
+    # apply（起動時の全体検証）と project_url（apply を経ない経路へのセーフネット）の両方から呼ぶ。
+    def validate_project_id!
+      raise ArgumentError, 'project_id is required' if project_id.nil?
+    end
+
     def default_port
       if secure?
         443

data/lib/copy_tuner_client/copyray/marker.rb

@@ -0,0 +1,24 @@
+module CopyTunerClient
+  class Copyray
+    # 訳文に埋め込むキーマーカーの可視テキストトークン。
+    # サーバ側（CopyrayMiddleware の Rewriter）だけが encode/scan/strip すればよく、
+    # フロントは data 属性化された後の DOM を見るので decode は不要。
+    #
+    # 例: encode('views.home.message') #=> "⟦CT:views.home.message⟧"
+    module Marker
+      # NOTE: 通常の本文・属性値に出現しない記号（U+27E6 / U+27E7）と固定プレフィックス CT: で
+      # 偶発衝突を二重に下げる。除去漏れても可読なので人間が原因に気づける（不可視文字は不採用）。
+      PREFIX = '⟦CT:'.freeze
+      SUFFIX = '⟧'.freeze
+
+      # NOTE: PREFIX/SUFFIX から動的構築し、区切り変更時に encode と SCAN_REGEXP がズレないようにする。
+      SCAN_REGEXP = /#{Regexp.escape(PREFIX)}(.*?)#{Regexp.escape(SUFFIX)}/
+
+      module_function
+
+      def encode(key)
+        "#{PREFIX}#{key}#{SUFFIX}"
+      end
+    end
+  end
+end

data/lib/copy_tuner_client/copyray/rewriter.rb

@@ -0,0 +1,113 @@
+require 'nokogiri'
+require 'copy_tuner_client/copyray/marker'
+
+module CopyTunerClient
+  class Copyray
+    # 完成 HTML を走査し、マーカートークンを含むテキストノードの親要素・属性値を持つ要素に
+    # data-copyray-key 属性を付与し、トークンを完全に除去する。
+    # CopyrayMiddleware の HTML 後処理（CSS/JS 挿入）の前段で呼ばれる。
+    module Rewriter
+      DATA_ATTR = 'data-copyray-key'.freeze
+
+      # NOTE: マーカーを含む巨大 HTML を Nokogiri で parse/traverse/再シリアライズすると
+      # サイズに比例して重くなる（実測 ~1MB で 167ms, ~3MB で 514ms）。development 限定機能で
+      # レスポンスを大きく悪化させないため、この閾値超では Nokogiri を通さず可視トークン除去のみ行う。
+      # 失うのは data-copyray-key（オーバーレイ編集導線）だけで、フォールバックの gsub は巨大ページでも数ms。
+      MAX_REWRITE_BYTESIZE = 1_000_000
+
+      class << self
+        # NOTE: 戻り値は [html, skipped]。skipped は data-copyray-key を付与できなかったことを表す
+        # （巨大DOMでのスキップ・Nokogiri 例外の双方で true）。ミドルウェアがこれを JS に伝え、
+        # オーバーレイ非対応である旨をツールバーで案内する。
+        def rewrite(html)
+          # NOTE: ボディが ASCII-8BIT に転落していると UTF-8 の Marker::PREFIX との include? 比較が
+          # Encoding::CompatibilityError を投げる（ミドルウェアのボディ連結で非ASCIIバイトを含む
+          # ASCII-8BIT チャンクが混じると発生）。実バイト列は本来 UTF-8 なので判定用に UTF-8 とみなす。
+          # String.new でエンコーディングだけ付け替える（元オブジェクトを破壊せずバッファもコピーしない）。
+          scannable = html.encoding == Encoding::UTF_8 ? html : String.new(html, encoding: Encoding::UTF_8)
+
+          # NOTE: マーカーが無ければ Copyray 無効時・マーカーの無い通常ページなので一切変形しない（高速パス）。
+          # これによりマーカー非注入の HTML は完全に無傷で、Nokogiri の正規化も通らない。
+          # （そもそも CopyrayMiddleware は development 限定で本番のスタックには登録されず、本番では呼ばれない。）
+          # 判定は正規表現より安い部分文字列検索で行う（プレフィックスがあれば必ずマーカー候補）。
+          return [html, false] unless scannable.include?(Marker::PREFIX)
+
+          # NOTE: 閾値超は Nokogiri を通さず可視トークン除去のみ。skipped=true で編集導線を諦めた旨を伝える。
+          return [strip_markers(scannable), true] if scannable.bytesize > MAX_REWRITE_BYTESIZE
+
+          [rewrite_with_nokogiri(scannable), false]
+        rescue StandardError => e
+          # NOTE: Copyray は開発支援機能なので、壊れた HTML 等で Nokogiri 処理が落ちても
+          # ページを 500 にしない。data-copyray-key 付与（編集導線）は諦め、最低限可視トークンだけ除去する。
+          warn_rewrite_failure(e)
+          [strip_markers(scannable), true]
+        end
+
+        private
+
+        # NOTE: gsub 対象が html ではなく scannable なのは、ASCII-8BIT のままだと UTF-8 の
+        # SCAN_REGEXP との比較で Encoding::CompatibilityError が再発しうるため。
+        def strip_markers(scannable)
+          scannable.gsub(Marker::SCAN_REGEXP, '')
+        end
+
+        def rewrite_with_nokogiri(scannable)
+          doc = Nokogiri::HTML(scannable)
+
+          doc.traverse do |node|
+            if node.text?
+              annotate_text_node(node)
+            elsif node.element?
+              annotate_attributes(node)
+            end
+          end
+
+          # NOTE: Nokogiri 走査はテキストノード親要素・属性値への属性付与とノード単位の除去を担うが、
+          # serialize 時の正規化（エンティティ復元等）でトークンが復活しうる縁を塞ぐため、
+          # 最終出力にもう一度 gsub をかけて残留トークンを保険で全除去する（可視トークンの除去漏れは画面に出るため）。
+          strip_markers(doc.to_html)
+        end
+
+        # NOTE: logger 未設定の構成でもフォールバック自体が落ちないよう nil ガードする。
+        def warn_rewrite_failure(error)
+          logger = CopyTunerClient.configuration.logger
+          logger&.warn("CopyTuner Copyray::Rewriter failed: #{error.class.name}: #{error.message}")
+        end
+
+        def annotate_text_node(node)
+          keys = scan_keys(node.content)
+          return if keys.empty?
+
+          set_keys(node.parent, keys)
+          node.content = node.content.gsub(Marker::SCAN_REGEXP, '')
+        end
+
+        def annotate_attributes(element)
+          element.attribute_nodes.each do |attr|
+            keys = scan_keys(attr.value)
+            next if keys.empty?
+
+            set_keys(element, keys)
+            attr.value = attr.value.gsub(Marker::SCAN_REGEXP, '')
+          end
+        end
+
+        # NOTE: 空キーは除く（JS 側も split 後に空要素を捨てるため、表現を両端で揃える）。
+        def scan_keys(text)
+          text.scan(Marker::SCAN_REGEXP).flatten.reject(&:empty?)
+        end
+
+        # NOTE: 同一テキストノード／属性値に複数マーカーが連結されると全キーをここで受け取り、
+        # 1 要素に複数キーをカンマ区切りで保持する（1 要素 1 キーだと 2 個目以降の編集導線が消える）。
+        # 既存値がある場合（同じ要素を複数経路で踏むケース）はマージして重複排除し、出現順を保つ。
+        # I18n キーに ',' は通常含まれないため区切り文字として安全。JS 側もカンマ区切りを前提に読む。
+        def set_keys(element, keys)
+          return if element.nil? || !element.element?
+
+          existing = element[DATA_ATTR]&.split(',') || []
+          element[DATA_ATTR] = (existing + keys).uniq.join(',')
+        end
+      end
+    end
+  end
+end

data/lib/copy_tuner_client/copyray.rb

@@ -1,9 +1,12 @@
+require 'copy_tuner_client/copyray/marker'
+
 module CopyTunerClient
   class Copyray
     # This:
     #   message
     # Becomes:
-    #   <!--COPYRAY views.home.index.message-->message
+    #   ⟦CT:views.home.index.message⟧message
+    # マーカートークンは CopyrayMiddleware の Rewriter で data-copyray-key 属性に変換され、HTML から除去される。
     def self.augment_template(source, key)
       return source if source.blank? || !source.is_a?(String)
 
@@ -11,9 +14,13 @@ module CopyTunerClient
       # オーバーレイマーカーを出さない。編集できないキーを編集可能だと誤認させないため。
       return source if CopyTunerClient.configuration.local_first_key?(key)
 
-      escape = CopyTunerClient.configuration.html_escape && !source.html_safe?
-      augmented = "<!--COPYRAY #{key}-->#{escape ? ERB::Util.html_escape(source) : source}"
-      augmented.html_safe
+      # NOTE: マーカーは平文・html_safe どちらの訳文にも埋め込む（画面に出る全テキストをオーバーレイ対象にする）。
+      # トークンの区切り記号 ⟦⟧ は HTML 特殊文字ではないため、平文が ActionView でエスケープされても無傷で残り、
+      # Rewriter の走査は崩れない。
+      # html_safe フラグは source のものを引き継ぐ。html_safe を勝手に立てると平文訳文の本体（& < >）が
+      # エスケープされず XSS になり、逆に html_safe を落とすと _html 訳文がエスケープされて壊れるため。
+      augmented = Marker.encode(key) + source
+      source.html_safe? ? augmented.html_safe : augmented
     end
   end
 end

data/lib/copy_tuner_client/copyray_middleware.rb

@@ -1,5 +1,7 @@
 # cf) xray-rails : xray/middleware.rb
 
+require 'copy_tuner_client/copyray/rewriter'
+
 module CopyTunerClient
   class CopyrayMiddleware
     def initialize(app)
@@ -11,8 +13,13 @@ module CopyTunerClient
       status, headers, response = @app.call(env)
       if html_headers?(status, headers) && body = response_body(response)
         csp_nonce = env['action_dispatch.content_security_policy_nonce'] || env['secure_headers_content_security_policy_nonce']
+        # NOTE: CSS/JS 挿入の前に Rewriter を通す。serialize 後も </body> は必ず出力されるので
+        # append_to_html_body の rindex は機能し、CSS/JS タグはトークン非含有なので二重処理も起きない。
+        # NOTE: skipped は data-copyray-key を付与できなかったこと（巨大DOM/Nokogiri例外）を表す。
+        # JS にこれを伝え、オーバーレイ非対応である旨をツールバーで案内させる。
+        body, skipped = CopyTunerClient::Copyray::Rewriter.rewrite(body)
         body = append_css(body, csp_nonce)
-        body = append_js(body, csp_nonce)
+        body = append_js(body, csp_nonce, skipped: skipped)
         content_length = body.bytesize.to_s
         headers['Content-Length'] = content_length
         # maintains compatibility with other middlewares
@@ -37,7 +44,7 @@ module CopyTunerClient
       append_to_html_body(html, css_tag)
     end
 
-    def append_js(html, csp_nonce)
+    def append_js(html, csp_nonce, skipped: false)
       json =
         if CopyTunerClient::TranslationLog.initialized?
           CopyTunerClient::TranslationLog.translations.to_json
@@ -49,6 +56,7 @@ module CopyTunerClient
         window.CopyTuner = {
           url: '#{CopyTunerClient.configuration.project_url}',
           data: #{json},
+          keysSkipped: #{skipped},
         }
       SCRIPT
       append_to_html_body(html, helpers.javascript_include_tag('copytuner', type: 'module', crossorigin: 'anonymous', nonce: csp_nonce))

data/lib/copy_tuner_client/helper_extension.rb

@@ -60,9 +60,6 @@ module CopyTunerClient
             alias_method :translate_without_copyray_comment, :translate
             alias_method :translate, :translate_with_copyray_comment
             alias :t :translate
-            alias :tt :translate_without_copyray_comment
-          else
-            alias :tt :translate
           end
         end
       end

data/lib/copy_tuner_client/i18n_backend.rb

@@ -26,18 +26,11 @@ module CopyTunerClient
     #
     # @return [Object] the translated key (usually a String)
     def translate(locale, key, options = {})
-      # I18nの標準処理に任せる（内部でlookupが呼ばれる）
-      content = super
-
-      return content if content.nil? || content.is_a?(Hash)
-
-      # HTML escapeの処理（ツリー構造のHashは除く）
-      if CopyTunerClient.configuration.html_escape
-        content
-      else
-        # Backward compatible
-        content.respond_to?(:html_safe) ? content.html_safe : content
-      end
+      # I18nの標準処理に任せる（内部でlookupが呼ばれる）。
+      # NOTE: html_safe 化は backend では行わない。.html/_html キーの html_safe 化は
+      # ActionView の TranslationHelper（ActiveSupport::HtmlSafeTranslation）が担うため、
+      # backend は I18n 標準どおり素の content を返すだけにする（旧 html_escape 分岐は廃止）。
+      super
     end
 
     # Returns locales available for this CopyTuner project.

data/lib/copy_tuner_client/version.rb

@@ -1,6 +1,6 @@
 module CopyTunerClient
   # Client version
-  VERSION = '1.5.0'.freeze
+  VERSION = '2.0.0'.freeze
 
   # API version being used to communicate with the server
   API_VERSION = '2.0'.freeze

data/skills/copy-tuner/SKILL.md

@@ -71,13 +71,44 @@ license: MIT
 削除せず `config/initializers/copy_tuner.rb` の `ignored_keys` に追加する。
 一定期間どこからも参照されていないことを確認してから手動削除する。
 
-## `t` と `tt` の使い分け
+## 翻訳ヘルパー（`t`）
 
-**HTML 要素の属性値には `tt` を使う**（それ以外の通常出力は `t`）。`tt` は copy_tuner_client gem の
-`HelperExtension` が提供するエイリアス。`t` は CopyTuner の都合で HTML コメント (`<!-- ... -->`) を
-埋め込むため、属性値に入ると表示崩れや動作不良の原因になる。
+**通常出力・属性値ともに `t`（`translate`）を使う。** 属性値も含めて区別は不要。
+
+**`tt` は削除済み。** PR #122 で存在理由を喪失したため削除した。既存の `tt` 呼び出しは `t` へ置き換える（属性値含め）。
+
+## 落とし穴: 開発環境で訳文にマーカートークンが混入する
+
+PR #122 の可視トークン方式では、development（`middleware` 有効時）の `t('key')` の戻り値は
+`⟦CT:key⟧訳文本体`（記号は U+27E6 / U+27E7）のように、訳文先頭に Copyray マーカートークンが付いた
+文字列になる。トークンは配信直前に `CopyrayMiddleware` → `Rewriter` が `data-copyray-key` 属性へ変換
+して HTML から完全除去するため画面表示は正常だが、**ビューで訳文を文字列として加工するコードは、
+除去前のトークン込み文字列に作用してしまう。**
+
+**本番では再現しない。** 本番では `CopyrayMiddleware` 自体が登録されずマーカー注入もされないため、
+戻り値は素の訳文。**開発環境だけ挙動が違う**のが見落としやすい点。
+
+危険なコード例:
+
+```erb
+<%= truncate(t('views.foo.body')) %>   <%# ⟦CT:...⟧ 込みの長さで切られ、トークン途中で切れる／本文が短く切られる %>
+<%= t('views.foo.title').length %>     <%# トークン長が加算され想定外の値になる %>
+```
+
+一般化すると、`t(...)` の戻り値を `truncate` / `length` / スライス（`[0..n]`）/ 正規表現マッチ /
+文字数バリデーション等で**文字列処理する全般**が対象。
+
+**対処**: 訳文を文字列加工する場合、マーカーを注入しない `I18n.t`（`translate` ヘルパーではなく
+`I18n` モジュールを直接呼ぶ）で訳文を取得してから加工する。`I18n.t` は HelperExtension のラッパーを
+通らないためトークンが付かない。
 
 ```erb
-<div title="<%= tt('views.tooltips.help_text') %>">...</div>
-<h1><%= t('views.simulation.show.title') %></h1>
+<%= truncate(I18n.t('views.foo.body')) %>
 ```
+
+注意:
+- `I18n.t` は partial 相対キー（先頭ドットの `t('.body')`）を解決しないので、`I18n.t('views.foo.body')`
+  のように**絶対キーで書く**こと。
+
+**このスキルでの注意**: キー追加・参照・コード差し替えを行う際、上記のように訳文を文字列加工して
+いるコードを書く／触る場合はこの罠を念頭に置くこと。

data/skills/copy-tuner-to-locales-cleanup/SKILL.md

@@ -82,10 +82,10 @@ migrate-prefix 側で配置を直してから戻る。
 
 ### 3. `tt` ヘルパーをアプリ側へ退避
 
-copy_tuner_client は `ActionView` の `translate` をフックする際に **`tt` という独自エイリアス**を生やす
-（copyray コメント注入なしの純粋な翻訳。シグネチャは `tt(key, **options)`）。アプリのビューが `tt(...)` を
-使っていると、gem 撤去で `tt` が消えて `NoMethodError`（テンプレートで未定義ヘルパー）になる。**gem を抜く前に**
-アプリ側へ移しておく。
+copy_tuner_client はかつて `ActionView` の `translate` をフックする際に **`tt` という独自エイリアス**を生やして
+いた（シグネチャは `tt(key, **options)`）。PR #122 で存在理由を喪失したため gem からは削除済みだが、過去の
+copy_tuner_client を使っていたアプリのビューに `tt(...)` 呼び出しが残っていると `NoMethodError`（テンプレートで
+未定義ヘルパー）になる。**gem を抜く前に**アプリ側へ移しておく（既に gem 側に `tt` が無い場合も手順は同じ）。
 
 1. 利用箇所を洗い出す（残っていれば移行対象）:
 

data/skills/copy-tuner-to-locales-migrate-prefix/references/local-first-regexp.md

@@ -60,13 +60,8 @@ config.local_first_key_regexp = Regexp.union(
 （`/\Aviews\./`。`Regexp.union` に文字列を渡す場合は自動エスケープされるが、Regexp リテラルを渡すときは自分で
 書く）。
 
-## deprecated な exclude_key_regexp との違い
+## 旧 exclude_key_regexp について
 
-| | `local_first_key_regexp` | `exclude_key_regexp`（非推奨） |
-|---|---|---|
-| 対象キー | locale を**除いた**キー（`views.foo`） | locale を**含む**キー（`ja.views.foo`） |
-| 作用タイミング | lookup（読み込み）時 | upload（送信）時 |
-| 効果 | ローカル YAML を優先（完全分離） | サーバへのアップロードを抑止するだけ |
-
-`exclude_key_regexp` は PR #110 で非推奨化された（設定すると `ActiveSupport::Deprecation` 警告が出る）。
-移行では使わない。もし既存設定に `exclude_key_regexp` があれば、cleanup スキルで gem ごと撤去される。
+かつて存在した `exclude_key_regexp` オプションは v2 で削除済み。`local_first_key_regexp` を使うこと
+（対象は locale を**除いた**キー `views.foo`、lookup 時に作用しローカル YAML を優先＝完全分離）。
+既存 initializer に `exclude_key_regexp` の設定が残っている場合は削除する。

data/skills/copy-tuner-to-t-migrate/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: copy-tuner-to-t-migrate
+description: >-
+  copy_tuner_client v2.0.0 への移行で、削除された独自ヘルパー tt の呼び出しを Rails 標準の t（translate）へ
+  置換するスキル。tt は PR #122 で存在理由を失い gem から削除されたため、残った tt(...) は NoMethodError に
+  なる。大半は機械的に tt( → t( で済むが、訳文を文字列加工している箇所だけは t ではなく I18n.t へ移す必要があり
+  （開発環境のマーカートークン混入バグ対策）、そこは 1 件ずつ確認する。対象は app 配下の .rb / .haml / .erb。
+disable-model-invocation: true
+license: MIT
+---
+
+# tt → t 移行スキル（copy_tuner_client v2.0.0）
+
+copy_tuner_client がかつて `ActionView` にフックして生やしていた独自ヘルパー **`tt`**（シグネチャは
+`tt(key, **options)`、引数は `t` と完全同一）を、Rails 標準の `t`（`translate`）へ置き換えるワークフロー。
+gem を v2.0.0 に上げたアプリのビューに `tt(...)` が残っていると **`NoMethodError`（未定義ヘルパー）** になる。
+
+このスキルは**破壊的な一括書き換え**を含むため、ユーザが明示的に呼んだときだけ動く（`disable-model-invocation`）。
+
+## なぜ tt を t へ置換するのか
+
+`tt` はもともと「**copyray マーカーを注入しない生の訳文を取る**」ためのヘルパーだった。旧方式では `t('key')` の
+戻り値そのものにマーカーが埋め込まれ、`truncate` / `length` 等で**訳文を文字列加工する箇所**でマーカー長が
+混入して壊れる問題があり、その対策が `tt` だった。
+
+PR #122 のマーカー方式刷新で、マーカー注入は戻り値ではなく middleware（`CopyrayMiddleware` → `Rewriter`）で
+行い HTML 配信前に完全除去するようになった。これにより通常の `t` がどこでも安全に使えるようになり、`tt` は
+存在理由を失って削除された。背景の詳細は `skills/copy-tuner/SKILL.md` の「翻訳ヘルパー（`t`）」と
+「落とし穴: 開発環境で訳文にマーカートークンが混入する」を参照。
+
+**ただし罠が一つ残る。** マーカー除去は「最終的に HTML へ出力される訳文」に対してのみ効く。development で
+`t('key')` の戻り値を**ビュー内で文字列加工する**コードは、除去前のマーカー込み文字列に作用してしまう（本番では
+middleware 自体が無いので再現しない＝開発環境だけ壊れる）。
+
+→ つまり **`tt` を素朴に `t` へ変えてよいのは「文字列加工していない箇所」だけ**。文字列加工している `tt` を
+`t` にすると、`tt` がもともと潰していたバグをそのまま復活させてしまう。そこは middleware のラッパーを通らない
+**`I18n.t`（絶対キー）** へ移すのが正解で、機械的には決められないため 1 件ずつ確認する。
+
+## 変換の 3 分類
+
+| 分類 | 例 | 扱い |
+|---|---|---|
+| **safe** | `tt('views.foo')` / `= tt '.title'` / `tt(key, default: x)` | `tt(` → `t(` に決定論的一括変換 |
+| **suspicious** | `truncate(tt('k'))` / `tt('k').length` / `tt('k')[0..n]` / `tt('k') =~ /re/` / `tt('k').gsub(...)` 等 | `I18n.t('絶対キー')` へ。**1 件ずつ確認**。スクリプトは触らない |
+| **other** | `def tt` / `alias tt`（定義側）/ app 外（`lib/` 等）/ `tt` を含む別識別子の誤検出 | 最後にまとめて提示。自動変換しない |
+
+**重要（定義側の罠）:** アプリが v2.0.0 を待つ間の後方互換として `ApplicationHelper` に `def tt(key, **) = t(key, **)`
+のような **`tt` の定義**を生やしていることがある。これは「呼び出し」ではないので `t(` へ機械置換すると Rails の `t`
+を再定義して破滅する。スクリプトは `def tt` / `alias tt` を **other** に隔離して自動変換しない。**呼び出しを全て
+`t` / `I18n.t` へ移し終えた後**に、この定義を手で削除する（順序を逆にすると呼び出しが `NoMethodError` になる）。
+
+判定はヒューリスティック（完全な AST ではない）。**誤判定のコストが非対称**なので疑わしきは suspicious に倒す:
+safe を取りこぼす（本当は怪しいのに safe）とマーカー混入バグが再発して重大、suspicious を過剰検出しても人間が
+1 件確認するだけで軽微。
+
+## ワークフロー
+
+### 1. 利用箇所の洗い出しと 3 分類
+
+同梱スクリプトで `app/` 配下の `.rb` / `.haml` / `.erb` を走査し、3 分類でレポートする（変更は加えない）。
+Rails context は不要なので素の `ruby` で動く。
+
+```bash
+ruby skills/copy-tuner-to-t-migrate/scripts/migrate_tt.rb --report
+```
+
+safe / suspicious / other の件数と該当箇所（`ファイル:行: コード`）が出る。まず全体像をユーザと共有する。
+
+### 2. safe な箇所を一括変換
+
+safe 分類は引数がそのまま通る（`tt(key, **options)` → `t(key, **options)`）ので決定論的に置換できる。
+**件数をユーザに伝え、承認を得てから**適用する（`--apply-safe` はファイルを直接書き換えるため）。
+
+```bash
+ruby skills/copy-tuner-to-t-migrate/scripts/migrate_tt.rb --apply-safe
+```
+
+suspicious / other の行は**一切触らない**（行番号で限定しているため）。適用後に `git diff` を見せて、safe 行
+だけが `t(` になったことを確認してもらう。
+
+### 3. suspicious な箇所を 1 件ずつ確認
+
+ここが人間の判断が要る核心。手順 1 の suspicious 各件について、次を 1 件ずつ提示して確認を取る:
+
+- 該当コード（`ファイル:行`）と、なぜ怪しいか（戻り値を文字列加工している＝マーカー混入の危険）
+- 提案する置換: `t(...)` ではなく **`I18n.t('絶対キー')`**（`I18n` モジュール直呼びはラッパーを通らずマーカーが付かない）
+
+注意点:
+- **たとえユーザが「全部まとめて I18n.t にして」と言っても、suspicious は必ず 1 件ずつ提示する。** 相対キーを含む件は絶対キーをユーザと確認しないと置換できないためで、省略すると誤ったキーを書き込む危険がある。
+- **相対キー（先頭ドット `tt('.foo')`）は `I18n.t` では解決できない。** 絶対キー（`I18n.t('views.foo.bar')`）へ
+  書き換える必要があり、partial のパスからキーを補う判断が要る。スクリプトはこの相対キーの suspicious を
+  `相対キー(.foo)は絶対キーへ書き換えが必要` と強調表示するので、特に丁寧に確認する。ヘルパーや
+  コントローラ（`app/helpers/`, `app/controllers/`）に相対キーがある場合は、呼び出し元のビューのパスを
+  調べて基点キーを特定するか、ユーザに直接絶対キーを確認する。絶対キーが不明なときは
+  `grep -r "キー末尾部分" config/locales/` でロケールファイルを検索して候補を絞り込む。
+- 本当に文字列加工していない（誤検出）なら、その場合は `t(...)` でよい。ユーザの判断に従う。
+
+確認が取れた箇所だけ Edit で個別に置換する（スクリプトでは変換しない）。
+
+### 4. その他ヒット（定義側・app 外・誤検出）を提示
+
+手順 1 の other をまとめて提示する。
+
+- **`def tt` / `alias tt`（定義側）**: 後方互換シムが残っていることが多い。**呼び出しを全て移し終えてから手で削除**する
+  （3 分類表の「定義側の罠」参照）。早く消すと残った呼び出しが `NoMethodError` になる。
+- **app 外（`lib/` のヘルパーやコントローラ等）**: ビューヘルパー `tt` がそのスコープから見えるかは別問題なので、
+  自動変換せずユーザに判断を委ねる。
+
+念のため、スクリプトの単語境界判定をすり抜けた可能性に備えて素朴な grep でも最終確認する:
+
+```bash
+git grep -nwI tt -- app   # -I でバイナリ（画像等）の誤マッチを除外
+```
+
+### 5. 検証
+
+- `git grep -nwI tt -- app` の残りが「未対応の suspicious + まだ消していない定義側」だけであること
+  （safe は 0 件、`I18n.t` 化した suspicious も `tt` としては消える）。
+- 対象アプリで `bundle exec rspec`（または該当アプリのテスト）を回し、`NoMethodError` が出ないこと。
+- development で実画面を開き、文字列加工していた箇所にマーカートークン（`⟦CT:...⟧`）が混入していないこと。
+
+## スクリプトの責務（決定論的な範囲のみ）
+
+`scripts/migrate_tt.rb` は**機械的に確定できる部分だけ**を担う:
+
+- `--report`（既定）: 3 分類を出力。`--json` で機械可読出力も可能。**ファイルは変更しない**。
+- `--apply-safe`: safe 分類のみ `tt(` → `t(` を適用。suspicious / other は触らない。
+- `--root DIR`: リポジトリルート指定（既定はカレント）。
+
+suspicious の確定変換（`I18n.t` 化・相対→絶対キー）は機械的に決められないため**スクリプトは行わない**。
+必ず手順 3 で人間が 1 件ずつ確認する。