cocoapods-podgenerate 0.1.2 → 0.1.4

data/lib/cocoapods-podgenerate/patches/cache_analyzer_patch.rb

@@ -1,16 +1,35 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Monkey-patches ProjectCacheAnalyzer to parallelize cache key computation.
+# Monkey-patches ProjectCacheAnalyzer，并行计算缓存键。
 #
-# v0.1.2 Optimization:
-#  1. Parallel MD5 cache key computation across all pod targets
+# 优化原理：
+#   ProjectCacheAnalyzer#create_cache_key_mappings 为所有 pod_target
+#   和 aggregate_target 计算 TargetCacheKey。每个 target 的计算需要
+#   - 遍历文件列表计算 MD5 校验和
+#   - 汇总上游依赖的资源信息
+#   所有 target 的计算完全独立，天然适合并行化。
 #
-# TargetCacheKey.from_pod_target computes MD5 checksums of build settings
-# and collects resource dependencies per target. Each computation is fully
-# independent and can run in parallel.
+# 性能收益（150 pod target 场景）：
+#   原串行实现逐个计算 MD5，总耗时随 pod 数量线性增长。
+#   线程池并行后，计算时间除以线程数（通常 10+ 线程 → ~10x 加速）。
 #
-# Reference: CocoaPods — lib/cocoapods/installer/project_cache/project_cache_analyzer.rb
+# v0.1.3 修复：
+#   - Bug 修复：线程内错误不再导致 nil 条目。异常时同步重试，
+#     确保 results Hash 中每个 label 都有有效的 TargetCacheKey。
+#
+# v0.1.4 改进：
+#   - M1: wait_for_termination 添加 120 秒超时
+#   - 优化 compute_cache_key 为独立方法便于错误恢复
+#   - 添加详细中文注释
+#
+# 线程安全保证：
+#   - sandbox.local? 和 sandbox.checkout_sources 都是只读操作
+#   - target_by_label Hash 在所有线程间只读共享
+#   - results Hash 的写入用 Mutex 保护
+#
+# 参考：CocoaPods 源码
+#   - lib/cocoapods/installer/project_cache/project_cache_analyzer.rb
 
 require 'concurrent'
 require 'etc'
@@ -25,9 +44,19 @@ module Pod
         end
 
         module ParallelCacheKeyComputation
-          # Override create_cache_key_mappings to parallelize MD5 computation
-          # The original iterates target_by_label sequentially, computing cache keys.
-          # Since each target is independent, we use a thread pool.
+          # 并行计算所有 target 的缓存键
+          #
+          # 原实现（串行）:
+          #   Hash[target_by_label.map { |label, target| [label, compute_key(target)] }]
+          #
+          # 优化后（并行）:
+          #   使用 Concurrent::FixedThreadPool，每个 target 分配一个线程，
+          #   并发计算 TargetCacheKey，结果通过 Mutex 合并到 results Hash。
+          #
+          # @param target_by_label [Hash{String => PodTarget|AggregateTarget}]
+          #   target 标签到 target 对象的映射
+          # @return [Hash{String => TargetCacheKey}]
+          #   target 标签到缓存键的映射
           def create_cache_key_mappings(target_by_label)
             UI.message '- Creating cache key mappings (parallel)' do
               pool_size = compute_pool_size
@@ -35,36 +64,58 @@ module Pod
               mutex = Mutex.new
               results = {}
 
+              # 为每个 target 提交一个线程任务
               target_by_label.each do |label, target|
                 pool.post do
-                  key = case target
-                        when PodTarget
-                          local = sandbox.local?(target.pod_name)
-                          checkout_options = sandbox.checkout_sources[target.pod_name]
-                          TargetCacheKey.from_pod_target(sandbox, target_by_label, target,
-                                                         :is_local_pod => local,
-                                                         :checkout_options => checkout_options)
-                        when AggregateTarget
-                          TargetCacheKey.from_aggregate_target(sandbox, target_by_label, target)
-                        else
-                          raise "[BUG] Unknown target type #{target}"
-                        end
+                  key = compute_cache_key(target, target_by_label)
                   mutex.synchronize { results[label] = key }
                 rescue StandardError => e
-                  mutex.synchronize do
-                    Pod::UI.warn "[cocoapods-podgenerate] Cache key computation error: #{e.message}"
-                  end
+                  # v0.1.3 bug 修复: 异常时同步重试，确保 results[label] 不为 nil
+                  # 如果重试仍然失败，异常会传播导致 pod install 失败（正确的行为）
+                  Pod::UI.warn "[cocoapods-podgenerate] Cache key computation error, retrying sync: #{e.message}"
+                  fallback_key = compute_cache_key(target, target_by_label)
+                  mutex.synchronize { results[label] = fallback_key }
                 end
               end
 
+              # v0.1.4: 带超时的等待
               pool.shutdown
-              pool.wait_for_termination
+              unless pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT)
+                Pod::UI.warn '[cocoapods-podgenerate] Cache key computation timed out after 120s'
+                pool.kill
+              end
+
               results
             end
           end
 
           private
 
+          # 计算单个 target 的缓存键
+          #
+          # 根据 target 类型（PodTarget 或 AggregateTarget）调用不同的计算逻辑:
+          #   - PodTarget:  检查是否本地 pod + checkout 选项 → from_pod_target
+          #   - AggregateTarget: 直接调用 from_aggregate_target
+          #
+          # @param target [PodTarget|AggregateTarget] 要计算的目标
+          # @param target_by_label [Hash] 完整的 label→target 映射（from_pod_target 需要）
+          # @return [TargetCacheKey] 缓存键对象
+          def compute_cache_key(target, target_by_label)
+            case target
+            when PodTarget
+              local = sandbox.local?(target.pod_name)
+              checkout_options = sandbox.checkout_sources[target.pod_name]
+              TargetCacheKey.from_pod_target(sandbox, target_by_label, target,
+                                             :is_local_pod => local,
+                                             :checkout_options => checkout_options)
+            when AggregateTarget
+              TargetCacheKey.from_aggregate_target(sandbox, target_by_label, target)
+            else
+              raise "[BUG] Unknown target type #{target}"
+            end
+          end
+
+          # 计算线程池大小
           def compute_pool_size
             [[Etc.nprocessors - 1, 2].max, 16].min
           rescue NameError

data/lib/cocoapods-podgenerate/patches/installer_patch.rb

@@ -1,18 +1,38 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Monkey-patches Pod::Installer and PodsProjectGenerator for step 3/4 optimizations.
+# Monkey-patches Pod::Installer 和 PodsProjectGenerator，优化步骤 3/4。
 #
-# v0.1.1 Optimizations:
-#  1. Force-enable incremental_installation + generate_multiple_pod_projects
-#  2. Skip project generation entirely when nothing changed
-#  3. Parallelize PodTargetIntegrator integration
+# 优化原理：
+#   CocoaPods 内置了 incremental_installation 和 generate_multiple_pod_projects
+#   两个选项。本补丁强制启用这两个选项，并在其基础上进一步增强：
+#     - 完全无变更时跳过整个项目生成
+#     - 并行执行 PodTargetIntegrator
+#     - 并行配置 scheme 文件
+#     - 修复快速跳过路径的 ivars 和 hooks 缺失问题
 #
-# v0.1.2 Optimization:
-#  4. Parallelize configure_schemes across projects
+# v0.1.1 优化:
+#   1. 强制启用 incremental_installation + generate_multiple_pod_projects
+#   2. 完全无变更时跳过项目生成
+#   3. 并行化 PodTargetIntegrator 集成
 #
-# Reference: CocoaPods — lib/cocoapods/installer.rb
-#            lib/cocoapods/installer/xcode/pods_project_generator.rb
+# v0.1.2 优化:
+#   4. 并行化 configure_schemes（跨项目）
+#
+# v0.1.4 修复:
+#   - C2: 快速跳过路径设置缺失的 @pods_project/@pod_target_subprojects/@generated_projects
+#         并确保 run_podfile_post_install_hooks 被调用（即使在跳过路径上）
+#   - H1: 跳过路径不再传入空 InstallationResults，而是保留上次的 @target_installation_results
+#   - M1: wait_for_termination 使用 ThreadPool::DEFAULT_TIMEOUT
+#   - M3: integrate_targets 改用 Concurrent::FixedThreadPool（限制并发数，避免 200 线程）
+#
+# 线程安全保证：
+#   - configure_schemes: 每个 project 独立 xcodeproj → 并行安全
+#   - integrate_targets: 每个 PodTargetIntegrator 操作独立的 target → 并行安全
+#
+# 参考：CocoaPods 源码
+#   - lib/cocoapods/installer.rb
+#   - lib/cocoapods/installer/xcode/pods_project_generator.rb
 
 require 'concurrent'
 require 'etc'
@@ -22,12 +42,19 @@ module Pod
     module Patches
       module InstallerPatch
         def self.apply
-          Pod::UI.message '[cocoapods-podgenerate] Applying InstallerPatch v3'
+          Pod::UI.message '[cocoapods-podgenerate] Applying InstallerPatch v4'
           Pod::Installer.prepend(ForceIncrementalInstall)
           Pod::Installer::Xcode::PodsProjectGenerator.prepend(ParallelInstall)
         end
 
-        # ── Optimization 1: Force-enable incremental_installation ──
+        # ── 优化 1: 强制启用增量安装模式 ──
+        #
+        # 在 install! 入口处设置 installation_options，强制启用:
+        #   - incremental_installation:   只重新生成有变更的 target
+        #   - generate_multiple_pod_projects: 每个 pod 独立 xcodeproj
+        #
+        # 这两个选项是 CocoaPods 内置的（默认关闭），我们通过 monkey-patch
+        # 在 super 之前设置，对所有后续流程生效。
         module ForceIncrementalInstall
           def install!
             installation_options.incremental_installation = true
@@ -35,7 +62,25 @@ module Pod
             super
           end
 
-          # ── Optimization 2: Skip project generation when nothing changed ──
+          # ── 优化 2: 完全无变更时跳过项目生成 + C2/H1 修复 ──
+          #
+          # 原流程即使没有任何 target 变更，create_and_save_projects 仍会被调用，
+          # 执行大量 file I/O 操作。本方法在 analyze_project_cache 之后检查:
+          #   如果 pod_targets_to_generate 和 aggregate_targets_to_generate
+          #   都为空（即没有任何 target 需要重新生成），则:
+          #     1. 跳过 create_and_save_projects（pod 项目已在磁盘上，内容未变）
+          #     2. 仍执行 SandboxDirCleaner（清理可能被移除的 pod 的残留文件）
+          #     3. 仍调用 update_project_cache（保持缓存时间戳最新）
+          #     4. 仍调用 run_podfile_post_install_hooks（Podfile hook 不能跳过）
+          #
+          # v0.1.4 修复 (C2):
+          #   - 设置 @pods_project = nil, @pod_target_subprojects = [],
+          #     @generated_projects = []（避免下游引用 nil）
+          #   - 调用 run_podfile_post_install_hooks（之前被跳过导致 hook 静默丢失）
+          #
+          # v0.1.4 修复 (H1):
+          #   - 使用上次的 @target_installation_results 更新缓存
+          #     （而非空的 InstallationResults，避免清除 metadata_cache）
           def generate_pods_project
             stage_sandbox(sandbox, pod_targets)
 
@@ -45,15 +90,28 @@ module Pod
 
             if ptg.empty? && (atg.nil? || atg.empty?)
               Pod::UI.puts "[cocoapods-podgenerate] No changes — skipping project generation"
+
+              # C2 修复: 初始化所有实例变量（避免下游代码获得 nil）
               @generated_aggregate_targets = aggregate_targets
               @generated_pod_targets = []
+              @pods_project = nil
+              @pod_target_subprojects = []
+              @generated_projects = []
+
+              # C2 修复: 确保 post-install hooks 被调用
+              run_podfile_post_install_hooks
+
+              # 清理沙盒中残留的文件
               Pod::Installer::SandboxDirCleaner.new(sandbox, pod_targets, aggregate_targets).clean!
-              update_project_cache(cache_analysis_result,
-                Pod::Installer::Xcode::PodsProjectGenerator::InstallationResults.new({}, {}))
+
+              # H1 修复: 使用上次的安装结果（而非空结果）更新缓存
+              prev_results = @target_installation_results ||
+                Pod::Installer::Xcode::PodsProjectGenerator::InstallationResults.new({}, {})
+              update_project_cache(cache_analysis_result, prev_results)
               return
             end
 
-            # Normal path
+            # 正常路径: 有 target 需要重新生成
             ptg.each do |pod_target|
               pod_target.build_headers.implode_path!(pod_target.headers_sandbox)
               sandbox.public_headers.implode_path!(pod_target.headers_sandbox)
@@ -65,7 +123,15 @@ module Pod
             update_project_cache(cache_analysis_result, target_installation_results)
           end
 
-          # ── Optimization 3+4: create_and_save_projects with parallel configure_schemes ──
+          # ── 优化 3+4: 项目生成 + 并行 configure_schemes ──
+          #
+          # 完全覆盖原 create_and_save_projects 方法，添加并行 configure_schemes。
+          # 流程:
+          #   1. 创建 generator → 调用 generate!（并行安装 pod targets）
+          #   2. 设置实例变量（@pods_project 等）
+          #   3. UUID 预测 + 稳定化
+          #   4. 创建 writer → 并行清理/重建 scheme/保存
+          #   5. 并行 configure_schemes（每个 project 独立）
           def create_and_save_projects(pod_targets_to_generate, aggregate_targets_to_generate,
                                        build_configurations, project_object_version)
             UI.section 'Generating Pods project' do
@@ -77,7 +143,7 @@ module Pod
               @target_installation_results = pod_project_generation_result.target_installation_results
               @pods_project = pod_project_generation_result.project
               @pod_target_subprojects = pod_project_generation_result.projects_by_pod_targets.keys
-              @generated_projects = ([pods_project] + pod_target_subprojects || []).compact
+              @generated_projects = ([pods_project] + pod_target_subprojects).compact
               @generated_pod_targets = pod_targets_to_generate
               @generated_aggregate_targets = aggregate_targets_to_generate || []
               projects_by_pod_targets = pod_project_generation_result.projects_by_pod_targets
@@ -92,7 +158,7 @@ module Pod
                 run_podfile_post_install_hooks
               end
 
-              # Parallel configure_schemes (each project is independent)
+              # 并行 configure_schemes（多项目时）
               pods_project_pod_targets = pod_targets_to_generate - projects_by_pod_targets.values.flatten
               all_projects_by_pod_targets = {}
               if pods_project
@@ -112,29 +178,51 @@ module Pod
 
           private
 
+          # 并行配置所有项目的 scheme 文件
+          #
+          # 每个 scheme 文件是独立的 .xcscheme，存储在不同 xcodeproj 的
+          # xcuserdata 目录中。每个 project 完全独立 → 无锁并行。
+          #
+          # v0.1.4: rescue 范围缩小到只包裹 Concurrent::FixedThreadPool 创建
           def parallel_configure_schemes(projects_by_pod_targets, generator, generation_result)
             pool_size = [[Etc.nprocessors - 1, 2].max, 16].min
             Pod::UI.message "- Configuring schemes across #{projects_by_pod_targets.size} projects (pool: #{pool_size})"
 
-            pool = Concurrent::FixedThreadPool.new(pool_size)
-            projects_by_pod_targets.each do |project, pts|
-              pool.post do
+            pool = begin
+              Concurrent::FixedThreadPool.new(pool_size)
+            rescue NameError
+              nil # concurrent-ruby 不可用，回退到串行
+            end
+
+            if pool
+              projects_by_pod_targets.each do |project, pts|
+                pool.post do
+                  generator.configure_schemes(project, pts, generation_result)
+                rescue StandardError => e
+                  Pod::UI.warn "[cocoapods-podgenerate] Scheme configuration error: #{e.message}"
+                end
+              end
+              pool.shutdown
+              unless pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT)
+                Pod::UI.warn '[cocoapods-podgenerate] Scheme configuration timed out'
+                pool.kill
+              end
+            else
+              projects_by_pod_targets.each do |project, pts|
                 generator.configure_schemes(project, pts, generation_result)
-              rescue StandardError => e
-                Pod::UI.warn "[cocoapods-podgenerate] Scheme configuration error: #{e.message}"
               end
             end
-            pool.shutdown
-            pool.wait_for_termination
-          rescue NameError
-            # Fallback: sequential
-            projects_by_pod_targets.each do |project, pts|
-              generator.configure_schemes(project, pts, generation_result)
-            end
           end
         end
 
-        # ── Optimization 3: Parallelize PodTargetIntegrator ──
+        # ── 优化 3: 并行化 PodTargetIntegrator（修复 M3）──
+        #
+        # PodTargetIntegrator 为每个 pod target 添加脚本构建阶段
+        # （如 embed frameworks、copy resources）。每个 integrator 操作
+        # 独立的 target，无共享状态 → 并行安全。
+        #
+        # v0.1.4 修复 (M3): 使用 Concurrent::FixedThreadPool（限制并发数）
+        #   替代原来的裸 Thread.new（可能同时创建 200+ 线程导致资源耗尽）
         module ParallelInstall
           def install_pod_targets(project, pod_targets)
             super
@@ -152,18 +240,34 @@ module Pod
             return if pods_to_integrate.empty?
 
             use_io_paths = !installation_options.disable_input_output_paths
-            threads = pods_to_integrate.map do |result|
-              Thread.new do
-                begin
-                  Pod::Installer::Xcode::PodsProjectGenerator::PodTargetIntegrator.new(
-                    result, :use_input_output_paths => use_io_paths
-                  ).integrate!
-                rescue StandardError => e
-                  Pod::UI.warn "[cocoapods-podgenerate] Integrate error: #{e.message}"
-                end
+
+            if pods_to_integrate.size <= 1
+              # 单 target: 直接调用，无需线程开销
+              Pod::Installer::Xcode::PodsProjectGenerator::PodTargetIntegrator.new(
+                pods_to_integrate.first, :use_input_output_paths => use_io_paths
+              ).integrate!
+              return
+            end
+
+            # 多 target: 使用线程池并行集成（M3 修复）
+            pool_size = [[Etc.nprocessors - 1, 2].max, 16].min
+            pool = Concurrent::FixedThreadPool.new(pool_size)
+
+            pods_to_integrate.each do |result|
+              pool.post do
+                Pod::Installer::Xcode::PodsProjectGenerator::PodTargetIntegrator.new(
+                  result, :use_input_output_paths => use_io_paths
+                ).integrate!
+              rescue StandardError => e
+                Pod::UI.warn "[cocoapods-podgenerate] Integrate error: #{e.message}"
               end
             end
-            threads.each(&:join)
+
+            pool.shutdown
+            unless pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT)
+              Pod::UI.warn '[cocoapods-podgenerate] Target integration timed out'
+              pool.kill
+            end
           end
         end
       end

data/lib/cocoapods-podgenerate/patches/multi_project_generator_patch.rb

@@ -1,19 +1,28 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Monkey-patches MultiPodsProjectGenerator to parallelize pod target installation.
+# Monkey-patches MultiPodsProjectGenerator，将 PodTarget 安装并行化。
 #
-# v0.1.2 Optimization:
-#  1. Parallel install_all_pod_targets — each pod target's install is independent I/O
+# 优化原理：
+#   `generate_multiple_pod_projects` 启用了后，每个 pod 有自己独立的
+#   .xcodeproj 文件。原实现串行遍历所有 project，逐个调用
+#   `install_pod_targets`。由于每个 project 的 xcodeproj 目录不同，
+#   PodTargetInstaller（创建 xcconfig、module map、脚本等文件 I/O）可以
+#   安全地并行执行，无需加锁。
 #
-# Architecture:
-#  Instead of overriding create_pods_project (which has Ruby constant resolution issues
-#  in prepended modules for PodsProjectGenerator's inner classes), we keep the original
-#  project creation + file references sequential, and only parallelize the pod target
-#  installation step which is the heaviest I/O operation.
+# v0.1.4 改进：
+#   - Bug 修复：线程池内错误不再静默吞掉，失败时传播异常避免依赖图不完整
+#   - 添加 wait_for_termination 超时（120 秒），防止死锁导致进程永久挂起
 #
-# Reference: CocoaPods — lib/cocoapods/installer/xcode/multi_pods_project_generator.rb
-#            lib/cocoapods/installer/xcode/pods_project_generator.rb
+# 线程安全保证：
+#   - 每个 project 是独立的 Xcodeproj::Project 实例（各自 .xcodeproj 目录）
+#   - install_pod_targets 只修改传入的 project，不访问其他 project
+#   - sandbox 读取操作是线程安全的（写操作进入不同 pod 子目录）
+#   - 结果合并使用 Mutex 保护共享的 all_results Hash
+#
+# 参考：CocoaPods 源码
+#   - lib/cocoapods/installer/xcode/multi_pods_project_generator.rb
+#   - lib/cocoapods/installer/xcode/pods_project_generator.rb
 
 require 'concurrent'
 require 'etc'
@@ -22,45 +31,72 @@ module Pod
   module PodGenerate
     module Patches
       module MultiProjectGeneratorPatch
+        # 激活补丁：对 MultiPodsProjectGenerator prepend 我们的并行版本
         def self.apply
           Pod::UI.message '[cocoapods-podgenerate] Applying MultiProjectGeneratorPatch (parallel pod target install)'
           Pod::Installer::Xcode::MultiPodsProjectGenerator.prepend(ParallelMultiProjectGenerator)
         end
 
         module ParallelMultiProjectGenerator
-          # ── Optimization: Parallel install_all_pod_targets ──
-          # Each project has independent pod targets (different xcodeproj directories),
-          # so PodTargetInstaller operations can run concurrently without locking.
+          # 并行安装所有 pod target
+          #
+          # 原实现（串行）:
+          #   projects_by_pod_targets.each_with_object({}) { |(p, pts), r| r.merge!(install_pod_targets(p, pts)) }
+          #
+          # 优化后（并行）:
+          #   使用 Concurrent::FixedThreadPool，每个 project 分配一个线程
+          #   并发调用 install_pod_targets，结果通过 Mutex 合并到 all_results
+          #
+          # @param projects_by_pod_targets [Hash{Project => Array<PodTarget>}]
+          #   项目到 pod target 列表的映射
+          # @return [Hash{String => TargetInstallationResult}]
+          #   pod target 名称到安装结果的映射
           def install_all_pod_targets(projects_by_pod_targets)
             UI.message '- Installing Pod Targets (parallel)' do
               pool_size = compute_pool_size
               mutex = Mutex.new
               all_results = {}
+              errors = [] # v0.1.4: 收集错误而不是静默吞掉
 
               pool = Concurrent::FixedThreadPool.new(pool_size)
               projects_by_pod_targets.each do |project, pts|
                 pool.post do
+                  # 每个 project 独立安装其 pod target
                   target_results = install_pod_targets(project, pts)
                   mutex.synchronize { all_results.merge!(target_results) }
                 rescue StandardError => e
                   mutex.synchronize do
-                    Pod::UI.warn "[cocoapods-podgenerate] Pod target install: #{e.message}"
+                    errors << [project.path, e]
+                    Pod::UI.warn "[cocoapods-podgenerate] Pod target install failed for #{project.path}: #{e.message}"
                   end
                 end
               end
 
+              # v0.1.4: 带超时的等待，防止死锁
               pool.shutdown
-              pool.wait_for_termination
+              unless pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT)
+                Pod::UI.warn '[cocoapods-podgenerate] Pod target install timed out after 120s — forcing shutdown'
+                pool.kill
+              end
+
+              # v0.1.4: 如果有任何失败，抛出异常让 CocoaPods 知道安装不完整
+              unless errors.empty?
+                raise Pod::Informative, "[cocoapods-podgenerate] #{errors.size} pod target(s) failed to install"
+              end
+
               all_results
             end
           end
 
           private
 
+          # 计算适合当前机器的线程池大小
+          # 使用 CPU 核心数 - 1（为主线程留一个），最小 2，最大 16
+          # @return [Integer]
           def compute_pool_size
             [[Etc.nprocessors - 1, 2].max, 16].min
           rescue NameError
-            4
+            4 # Etc 不可用时的安全回退
           end
         end
       end

data/lib/cocoapods-podgenerate/patches/project_patch.rb

@@ -1,44 +1,77 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Monkey-patches Pod::Project to cache pod_group lookups.
-# Original implementation does O(n) linear scan for every pod_group call:
-#   pod_groups.find { |group| group.name == pod_name }
+# Monkey-patches Pod::Project，将 pod_group 查找从 O(n) 优化为 O(1)。
 #
-# With 200+ pods and pod_group called 3-5 times per pod, this is 600-1000
-# linear scans of a 200-element array = ~120k-200k iterations.
+# 优化原理：
+#   原始 `pod_group(pod_name)` 每次调用都执行:
+#     pod_groups.find { |group| group.name == pod_name }
+#   这是 O(n) 的线性扫描（n = pod 数量）。
 #
-# Fix: cache groups in a Hash for O(1) lookup. Invalidate on add_pod_group.
+#   在项目生成过程中，pod_group 被调用 3-5 次/pod（从
+#   FileReferencesInstaller、PodTargetInstaller 的不同位置调用）。
+#   对于 200+ pod 的项目，这意味着 600-1000 次线性扫描，
+#   每次扫描 200 个元素 → ~120k-200k 次比较。
 #
-# Reference: CocoaPods source — lib/cocoapods/project.rb
+# 修复策略：
+#   1. 首次调用 pod_group 时，构建 Hash 缓存（O(n) 一次性成本）
+#   2. 后续调用直接用 cached_hash[pod_name]，O(1) 查找
+#   3. 调用 add_pod_group（添加新 pod group）时，清除缓存强制下次重建
+#   4. 使用 `||=` 懒初始化缓存（只有第一次调用时才构建）
+#
+# 线程安全：
+#   所有操作在主线程的 install! 流程中执行，无并发访问。
+#
+# 参考：CocoaPods 源码 — lib/cocoapods/project.rb
 
 module Pod
   module PodGenerate
     module Patches
       module ProjectPatch
+        # 激活补丁：对 Pod::Project prepend 缓存版本
         def self.apply
           Pod::UI.message '[cocoapods-podgenerate] Applying ProjectPatch (pod_group hash cache)'
           Pod::Project.prepend(CachedPodGroup)
         end
 
         module CachedPodGroup
-          # Build a hash cache of pod_name => PBXGroup
-          # Called once when first needed, then kept in sync.
+          # O(1) 查找 pod_group
+          #
+          # 首次调用时通过 build_pod_group_cache 构建 Hash 缓存，
+          # 后续调用直接从缓存中查找。缓存键为 pod_name，值为 PBXGroup。
+          #
+          # @param pod_name [String] pod 名称
+          # @return [PBXGroup, nil] 对应的 group，或 nil（pod 不存在）
           def pod_group(pod_name)
             @pod_group_cache ||= build_pod_group_cache
             @pod_group_cache[pod_name]
           end
 
-          # Override add_pod_group to invalidate the cache
+          # 添加新 pod group 时清除缓存
+          #
+          # 原始方法在 main_group 或 pods/development_pods group 下
+          # 创建新的 PBXGroup。由于 project 结构发生了变化，
+          # 我们需要清除缓存，让下一次 pod_group 调用重新构建。
+          #
+          # @param pod_name [String] pod 名称
+          # @param path [String] pod 路径
+          # @param development [Boolean] 是否为开发 pod
+          # @param absolute [Boolean] 是否为绝对路径
+          # @return [PBXGroup] 新创建的 group
           def add_pod_group(pod_name, path, development = false, absolute = false)
             group = super
-            # Invalidate cache so the next call to pod_group rebuilds it
             @pod_group_cache = nil if defined?(@pod_group_cache)
             group
           end
 
           private
 
+          # 构建 pod_name → PBXGroup 的 Hash 缓存
+          #
+          # 遍历 pods group 和 development_pods group 下的所有子 group，
+          # 以 group.name 为键构建查找表。这是一个 O(n) 操作，但只执行一次。
+          #
+          # @return [Hash{String => PBXGroup}]
           def build_pod_group_cache
             cache = {}
             pod_groups.each do |group|