cocoapods-yaml 1.0.0

data/lib/core/yaml/yaml_dependencies.rb

@@ -0,0 +1,774 @@
+require_relative 'yaml_pod'
+require_relative '../../version'
+require_relative '../my_constants'
+require_relative '../check/xcodeproj'
+require_relative '../variable'
+require 'colored2'
+require 'yaml'
+require 'json'
+require 'shellwords'
+
+module Pod
+  class YamlDependencies
+
+    # 需要集成依赖的主工程target列表(application/app扩展)
+    # @return [Array]
+    attr_accessor :targets
+
+    # 所有yaml文件定义的依赖
+    # @return {String => {String => Pod:YamlPod}}  key: yaml文件名
+    attr_accessor :yaml_deps
+
+    # 所有target最终生效的依赖(已合并LocalDependencies覆盖)
+    # @return {target对象 => [Pod:YamlPod]}
+    attr_accessor :targets_dependencies
+
+    # 每个target依赖文件声明的SOURCES(有序)
+    # @return {String => [String]}  key: yaml文件名
+    attr_accessor :file_sources
+
+    attr_accessor :local_yaml_name
+
+    def initialize
+      super
+      @targets = []
+      @yaml_deps = {}
+      @targets_dependencies = {}
+      @file_sources = {}
+      @local_yaml_name = MyConstants::LOCAL_DEPENDENCIES_YAML
+    end
+
+    # 某个target对应的依赖yaml文件名
+    def target_yaml_name(target_name)
+      "#{target_name}#{MyConstants::DEPENDENCIES_YAML_SUFFIX}"
+    end
+
+    # 某个target对应的包内依赖清单文件名(仅Debug入包)
+    def target_json_name(target_name)
+      "#{target_name}#{MyConstants::DEPENDENCIES_JSON_SUFFIX}"
+    end
+
+    # 仅主App(.application)和App扩展(.app-extension)需要通过yaml集成依赖
+    def integratable_target?(target)
+      type = target.product_type.to_s
+      type.end_with?('.application') || type.end_with?('.app-extension')
+    end
+
+    def install_yaml_dep(podfile)
+      analysis_yaml_dep
+
+      # 为路径依赖的组件仓库开启 SNAPSHOT tag 自动同步(最小权限: 只配置被本地引用的仓库)
+      ensure_local_path_tag_sync
+
+      # 将YAML中声明的私有源注册为Podfile顶层source，屏蔽CocoaPods隐式追加的CDN trunk源
+      configure_private_sources(podfile)
+
+      install_dependencies(targets_dependencies, podfile) do|name|
+        yield(name) if block_given?
+      end
+    end
+
+    # 是否允许使用CocoaPods官方CDN trunk源。
+    # 由LocalDependencies.yaml顶层 ENABLE_TRUNK 控制(工程级，不提交git，只影响本工程)，默认false
+    def trunk_enabled?
+      content = read_yaml_content(local_yaml_name)
+      content ? content['ENABLE_TRUNK'] == true : false
+    end
+
+    # Podfile未声明任何顶层source时，CocoaPods会隐式加入CDN trunk源(cdn.cocoapods.org)。
+    # 团队组件(含三方库fork)全部在私有源，无需trunk：trunk既会因网络问题导致pod install失败，
+    # 也会与私有源存在同名podspec(如WechatOpenSDK)而产生"Found multiple specifications"警告。
+    # 这里按各target依赖文件中SOURCES的声明顺序注册为顶层source(把二进制源放在第一位，
+    # 可保证间接依赖优先命中二进制产物)，逐依赖显式指定的source追加在后。
+    def configure_private_sources(podfile)
+      if trunk_enabled?
+        log.detail("已开启CDN trunk源(LocalDependencies.yaml中ENABLE_TRUNK: true)")
+        return
+      end
+
+      private_sources = []
+      targets.each do |target|
+        name = target_yaml_name(target.name)
+        Array(file_sources[name]).each { |repo| private_sources << repo }
+        dependencies = yaml_deps[name]
+        next unless dependencies.is_a?(Hash)
+        dependencies.each_value do |dependency|
+          repo = dependency.source.to_s.strip
+          private_sources << repo unless repo.empty?
+        end
+      end
+      private_sources.uniq!
+
+      log.info('')
+      if private_sources.empty?
+        log.warn("target依赖文件未声明任何私有源(SOURCES)，保留CocoaPods默认CDN trunk源")
+        return
+      end
+
+      private_sources.each { |repo| podfile.source(repo) }
+      log.detail("已限定使用#{private_sources.size}个私有specs源，不使用CDN trunk")
+      private_sources.each { |repo| log.info("  - #{repo}") }
+      log.info("  如需恢复trunk，在#{local_yaml_name}顶层设置 ENABLE_TRUNK: true")
+      log.info('')
+    end
+
+    # SNAPSHOT 同名 tag 每次发布会被删除后前移，而 git 默认 fetch 不会覆盖本地已存在的 tag，
+    # 导致本地/同事本地的组件仓 tag 停留在旧位置。
+    # 这里仅对 LocalDependencies.yaml 中以 path 方式引用、且本身是 git 仓库的目录，
+    # 幂等写入仓库级(.git/config)配置:
+    #   1. fetch refspec 对 tags 加 '+' 前缀，允许强制更新已移动的 tag
+    #   2. tagOpt=--no-tags 关闭默认的 tag 自动跟随，避免与上面的显式 refspec 冲突
+    #      (否则会报 multiple updates for ref 'refs/tags/xxx' not allowed)
+    def ensure_local_path_tag_sync
+      local_deps = yaml_deps[local_yaml_name]
+      return unless local_deps.is_a?(Hash)
+
+      tag_refspec = '+refs/tags/*:refs/tags/*'
+      configured = 0
+
+      local_deps.values.map(&:path).compact.uniq.each do |raw_path|
+        repo_path = File.expand_path(raw_path)
+        next unless File.exist?(File.join(repo_path, '.git'))
+
+        begin
+          existing = `git -C #{Shellwords.escape(repo_path)} config --get-all remote.origin.fetch 2>/dev/null`.to_s
+          next if existing.lines.map(&:strip).include?(tag_refspec)
+
+          # 数组形式system避免路径/refs注入，并检查退出码，失败不静默
+          add_ok = system('git', '-C', repo_path, 'config', '--add', 'remote.origin.fetch', tag_refspec,
+                          out: File::NULL, err: File::NULL)
+          tag_ok = add_ok && system('git', '-C', repo_path, 'config', 'remote.origin.tagOpt', '--no-tags',
+                                    out: File::NULL, err: File::NULL)
+          unless add_ok && tag_ok
+            log.warn("路径仓库SNAPSHOT tag自动同步配置未生效(git config执行失败): #{repo_path}")
+            next
+          end
+
+          log.info('') if configured == 0
+          log.detail("已开启路径仓库的SNAPSHOT tag自动同步(后续 git fetch/pull 会自动前移): #{repo_path}")
+          configured += 1
+        rescue => e
+          log.warn("配置路径仓库tag同步失败(#{repo_path}): #{e.message}")
+        end
+      end
+
+      log.detail("共为#{configured}个路径仓库开启了SNAPSHOT tag自动同步") if configured > 0
+    end
+
+    def install_dependencies(targets_dependencies, podfile)
+      # 存储所有的依赖
+      targets_dependencies.each { |target_obj, dependencies|
+        # 零依赖target(如尚未声明依赖的扩展)不生成空的Podfile target块
+        next if dependencies.empty?
+        target_name = target_obj.name
+        podfile.target target_name do
+          dependencies.each { |dependency|
+            if dependency.version
+              podfile.pod dependency.pod, dependency.version, dependency.option
+            else
+              podfile.pod dependency.pod, dependency.option
+            end
+          }
+          yield(target_name) if block_given?
+        end
+      }
+    end
+
+    # 解析所有target在yaml文件中定义的依赖
+    # @return targets_dependencies
+    def analysis_yaml_dep
+      init_main_targets
+      check_orphan_yaml_files
+      generate_yaml
+      read_yaml_deps
+      resolve_targets_deps
+      print_targets_deps
+      targets_dependencies
+    end
+
+    # 构建各target最终依赖的结构化记录(供包内依赖清单json使用，不生成模板文件、不打印日志)
+    # @return {String => Array<Hash>} key: target名
+    def build_dependency_records
+      init_main_targets
+      read_yaml_deps
+      resolve_targets_deps
+      records = {}
+      targets_dependencies.each do |target, dependencies|
+        records[target.name] = dependencies.map { |dependency| dependency_record(dependency) }
+      end
+      records
+    end
+
+    # 归一化依赖记录(空值与默认值不输出，保持与yaml精简风格一致)
+    def dependency_record(dependency)
+      record = { 'pod' => dependency.pod }
+      %w[version git tag branch podspec path].each do |field|
+        value = dependency.public_send(field)
+        record[field] = value unless value.nil? || value.to_s.strip.empty?
+      end
+      record['configurations'] = dependency.configurations if Array(dependency.configurations).any?
+      record['source'] = dependency.source unless dependency.source.to_s.strip.empty?
+      # 默认true，仅false(本地覆盖默认值)时显式输出
+      record['inhibit_warnings'] = false if dependency.inhibit_warnings == false
+      record['local'] = true if dependency.from_local
+      record
+    end
+
+    # 合并LocalDependencies.yaml的本地声明到某个target的依赖上
+    # 规则:
+    #   1. 对target文件中已声明的同名组件(按组件根名匹配)做本地覆盖；
+    #      覆盖时清除该组件在target中的全部旧声明(含各subspec)，
+    #      否则root(path来源)与subspec(版本号来源)会触发CocoaPods多源冲突
+    #   2. target文件未声明的"全新组件"不在此处处理，
+    #      由inject_local_only_dependencies统一注入主App target
+    # @param file_deps {String => YamlPod} target依赖文件中的依赖
+    # @return {String => YamlPod}
+    def merge_local_dependencies(file_deps)
+      result = file_deps.dup
+      local_deps = yaml_deps[local_yaml_name]
+      return result unless local_deps.is_a?(Hash)
+
+      declared_roots = result.keys.map { |key| key.split('/').first }.uniq
+
+      local_deps.each do |name, dep|
+        real_name = name.split('/')[0]
+        next unless declared_roots.include?(real_name)
+
+        result.delete_if { |key, _| key.split('/').first == real_name }
+        # 覆盖明细不单独打印，下方依赖逐行输出中的[本地覆盖]标记已体现
+        result[name] = dep
+      end
+      result
+    end
+
+    def resolve_targets_deps
+      merged_hashes = {}
+      targets.each do |target|
+        file_deps = yaml_deps[target_yaml_name(target.name)] || {}
+        merged_hashes[target] = merge_local_dependencies(file_deps)
+      end
+
+      # LocalDependencies中声明、但所有target依赖文件都未声明的全新组件，注入主App target
+      inject_local_only_dependencies(merged_hashes)
+
+      merged_hashes.each { |target, deps| targets_dependencies[target] = deps.values }
+      targets_dependencies
+    end
+
+    # LocalDependencies.yaml里声明、但没有任何target依赖文件声明的组件(本地联调主动引入的新组件)。
+    # 统一注入主App target(.application)：
+    #   - 本地开发新增组件的标准路径就是写LocalDependencies，理应能直接pod install集成
+    #   - 裁剪(TRIM_UNUSED_POD)对LocalDependencies中的组件本就整体保留，注入后同样不会被剪掉
+    # 不向App扩展target注入：扩展通常只允许子集依赖，自动塞入无关库会拖大扩展体积甚至引发链接问题，
+    # 扩展需要新组件时请在对应<Target>Dependencies.yaml显式声明
+    # @param merged_hashes {target => {String => YamlPod}} 各target已合并本地覆盖的依赖
+    def inject_local_only_dependencies(merged_hashes)
+      local_deps = yaml_deps[local_yaml_name]
+      return unless local_deps.is_a?(Hash) && local_deps.any?
+
+      declared_roots = targets.flat_map { |target| (yaml_deps[target_yaml_name(target.name)] || {}).keys }
+                              .map { |key| key.split('/').first }
+                              .uniq
+
+      new_entries = local_deps.reject { |name, _| declared_roots.include?(name.split('/').first) }
+      return if new_entries.empty?
+
+      main_target = targets.find { |target| target.product_type.to_s.end_with?('.application') }
+      new_roots = new_entries.keys.map { |name| name.split('/').first }.uniq
+      unless main_target
+        log.warn("LocalDependencies.yaml中的新组件(#{new_roots.join('、')})未在任何target依赖文件中声明，且未找到主App target，无法自动集成；请在对应<Target>Dependencies.yaml中声明")
+        return
+      end
+
+      # version引用且未显式指定source时，借用主App target依赖文件SOURCES的第一个源，
+      # 与target依赖文件"不写source默认取SOURCES第一个"的语义保持一致；
+      # path/podspec/git引用不经过specs源解析，无需补source
+      default_source = file_sources[target_yaml_name(main_target.name)]&.first
+
+      merged = merged_hashes[main_target]
+      added_roots = []
+      new_entries.each do |name, dep|
+        next if merged.key?(name)
+
+        dep.local_injected = true
+        dep.source = default_source if dep.version && default_source && dep.source.to_s.strip.empty?
+        merged[name] = dep
+        added_roots << name.split('/').first
+      end
+
+      log.detail("LocalDependencies中的新组件(#{added_roots.uniq.join('、')})未在target依赖文件声明，已自动加入主App target[#{main_target.name}](不会被裁剪；App扩展target不会自动注入，需在对应依赖文件显式声明)") if added_roots.any?
+    end
+
+    # 读取所有target和本地覆盖的yaml文件
+    def read_yaml_deps
+      targets.each { |target| read_yaml_deps_file(target_yaml_name(target.name)) }
+      read_yaml_deps_file(local_yaml_name)
+    end
+
+    def read_yaml_deps_file(yaml_name)
+
+      yaml_content = read_yaml_content(yaml_name)
+
+      unless yaml_content
+        return
+      end
+
+      unless yaml_content["PODS"]
+        log.detail("#{yaml_name}共0个依赖(文件内的key[PODS]不存在)")
+        return
+      end
+
+      if yaml_content["PODS"].class != Array
+        log.detail("#{yaml_name}共0个依赖(文件配置的依赖PODS项不是数组或数组为空)")
+        return
+      end
+
+      if yaml_name != local_yaml_name
+        sources = yaml_content["SOURCES"]
+        # 零依赖文件(如尚未配置的扩展)允许SOURCES留空；一旦声明依赖，SOURCES必须是非空字符串数组
+        unless yaml_content["PODS"].empty?
+          if sources.class != Array or sources.empty? or sources.any? { |s| s.to_s.strip.empty? }
+            log.error("#{yaml_name}的SOURCES字段必须是非空数组，例如: SOURCES: ['git@xxx_binary.git', 'git@xxx_source.git']")
+            exit!
+          end
+        end
+        if sources.is_a?(Array) and sources.all? { |s| s.to_s.strip != "" }
+          file_sources[yaml_name] = sources.map(&:to_s).map(&:strip)
+        end
+      end
+
+      # 依赖未显式指定source时，默认使用SOURCES中的第一个源(通常把二进制源放在第一位)
+      default_source = file_sources[yaml_name]&.first
+
+      # 依赖列表
+      dependencies_pods = yaml_content['PODS']
+
+      # 当前yaml文件的组件名字 用来校验本文件内是否重复
+      dependencies_name = []
+
+      yaml_dependencies = {}
+
+      # 遍历依赖库列表
+      dependencies_pods.each { |dependency|
+
+        check_pod(dependency, yaml_name, dependencies_name)
+
+        # source: 显式指定优先，否则取默认源；LocalDependencies无SOURCES时允许为空(path/podspec引用不需要)
+        source = dependency['source'].to_s.strip
+        source = default_source if source.empty? && default_source
+
+        # inhibit_warnings: target依赖文件默认true(远程库警告不好修改)，本地覆盖文件默认false(开发时能看到本地库警告)
+        inhibit_warnings = if dependency.key?('inhibit_warnings')
+                             !!dependency['inhibit_warnings']
+                           else
+                             yaml_name != local_yaml_name
+                           end
+
+        # configurations和subspecs cocoapods不能同时支持，所以要展开
+        if Array(dependency['subspecs']).size > 0 and Array(dependency['configurations']).size > 0
+          dependency['subspecs'].each {|subspec|
+            dep = new_yaml_dep(dependency, "#{dependency['pod']}/#{subspec}", source, inhibit_warnings, yaml_name)
+            dep.subspecs = nil
+            yaml_dependencies[dep.pod] = dep
+          }
+
+        else
+          dep = new_yaml_dep(dependency, dependency['pod'], source, inhibit_warnings, yaml_name)
+          yaml_dependencies[dep.pod] = dep
+        end
+      }
+
+      yaml_deps[yaml_name] = yaml_dependencies
+
+      yaml_dependencies
+    end
+
+    def new_yaml_dep(dependency, pod_name, source, inhibit_warnings, yaml_name)
+      dep = YamlPod.new(pod_name)
+      dep.subspecs = dependency['subspecs']
+      dep.path = dependency['path']
+      dep.podspec = dependency['podspec']
+      dep.version = dependency['version']
+      dep.git = dependency['git']
+      dep.tag = dependency['tag']
+      dep.branch = dependency['branch']
+      dep.configurations = dependency['configurations']
+      dep.inhibit_warnings = inhibit_warnings
+      dep.source = source
+      dep.from_local = (yaml_name == local_yaml_name)
+      dep
+    end
+
+    def check_pod(dependency, yaml_name, dependencies_name)
+      # 依赖条目必须是keyValue形式；写成"- Foo"这种纯字符串时后续each_key会抛原始堆栈，这里前置拦截
+      unless dependency.is_a?(Hash)
+        log.error("#{yaml_name}: 依赖条目必须为keyValue形式(每项以 - pod: 开头)，当前条目: #{dependency.inspect}")
+        exit!
+      end
+
+      # 不支持提醒
+      available_keys = %w[pod subspecs path podspec version git tag branch configurations inhibit_warnings source]
+      dependency.each_key { |key|
+        unless available_keys.include?(key)
+          gem_name = "cocoapods-yaml"
+          log.error("#{yaml_name}: 当前#{gem_name}版本(#{CocoaPods::Yaml::VERSION})不支持字段#{key}")
+          log.info("请检查对应字段或尝试执行如下命令升级")
+          log.info("gem uninstall #{gem_name} && gem install #{gem_name}")
+          exit!
+        end
+      }
+
+      # 校验字段
+      unless dependency['pod']
+        log.error("#{yaml_name}: pod 字段(组件名字)必须存在,请检查:")
+        exit!
+      end
+
+      current_type = nil
+      current_type = check_only_one_dep(dependency, "path", current_type, yaml_name)
+      current_type = check_only_one_dep(dependency, "podspec", current_type, yaml_name)
+      current_type = check_only_one_dep(dependency, "version", current_type, yaml_name)
+      current_type = check_only_one_dep(dependency, "tag", current_type, yaml_name)
+      current_type = check_only_one_dep(dependency, "branch", current_type, yaml_name)
+
+      unless current_type
+        log.error("#{yaml_name} - #{dependency['pod']}: path/podspec/version/git/tag/branch 字段请指定其中一个")
+        exit!
+      end
+
+      unless dependency['git']
+        if dependency['tag']
+          log.error("#{yaml_name} - #{dependency['pod']}: 你指定了tag，但未配置git地址，请为此组件配置git字段")
+          exit!
+        end
+        if dependency['branch']
+          log.error("#{yaml_name} - #{dependency['pod']}: 你指定了branch，但未配置git地址，请为此组件配置git字段")
+          exit!
+        end
+      end
+
+      #  检查数据类型
+      if dependency['configurations'] and dependency['configurations'].class != Array
+        log.error("#{yaml_name} - #{dependency['pod']} - #{dependency['configurations']}: configurations字段必须是数组，例如:['Debug','Release']")
+        exit!
+      end
+
+      if dependency['subspecs'] and dependency['subspecs'].class != Array
+        log.error("#{yaml_name} - #{dependency['pod']} - #{dependency['subspecs']}: subspecs字段必须是数组，例如:['A','B','C']")
+        exit!
+      end
+
+      # 校验自身文件重复
+      if dependencies_name.include?(dependency['pod'])
+        log.error("发现#{yaml_name}内重复组件:#{dependency['pod']},请检查并删除重复依赖")
+        exit!
+      else
+        dependencies_name << dependency['pod']
+      end
+
+      # 警告
+      if dependency['path'] and yaml_name != local_yaml_name
+        log.warn("组件#{dependency['pod']}使用path依赖方式应该写在#{local_yaml_name}")
+      end
+      if dependency['podspec'] and yaml_name != local_yaml_name
+        log.warn("组件#{dependency['pod']}使用podspec依赖方式应该写在#{local_yaml_name}")
+      end
+
+    end
+
+    def check_only_one_dep(dependency, key, current_type, yaml_name)
+      if dependency[key]
+        if current_type
+          log.error("#{yaml_name} - #{dependency['pod']}: #{current_type}字段和#{key}只能使用其中一个，请删除不需要的一个")
+          exit!
+        else
+          return key
+        end
+      end
+      current_type
+    end
+
+    def read_yaml_content(yaml_name)
+      unless File.exist?(yaml_name)
+        log.detail("文件不存在:#{yaml_name}")
+        return nil
+      end
+
+      begin
+        # aliases: true 支持YAML锚点变量(SOURCES上的 &binary/&source 锚点被组件的 *source 引用)
+        yaml_content = YAML.load_file(yaml_name, aliases: true)
+      rescue Exception => e
+        log.error(e.to_s)
+        log.error("#{yaml_name}文件解析异常, 请检查 ⬆️")
+        exit!
+      end
+
+      unless yaml_content.class == Hash
+        log.warn("#{yaml_name} => (文件不是keyValue形式)")
+        return nil
+      end
+
+      yaml_content
+    end
+
+    def print_targets_deps
+      log.step('读取依赖文件')
+      yaml_deps.each do |yaml_name, deps|
+        next if yaml_name == local_yaml_name
+        log.detail("#{yaml_name} => #{deps.size}个")
+      end
+      local_deps = yaml_deps[local_yaml_name]
+      log.detail("#{local_yaml_name} => #{local_deps ? local_deps.size : 0}个(本地覆盖)") if local_deps
+
+      targets_dependencies.each do |target, dependencies|
+        # 零依赖target只打印个数，不遍历具体依赖
+        log.step("target[#{target.name}] 解析后依赖共计#{dependencies.size}个")
+        next if dependencies.empty?
+
+        sort_deps = dependencies.sort do |dep1, dep2|
+          if dep1.type != dep2.type
+            dep1.type < dep2.type ? 1 : -1
+          else
+            dep1.pod.downcase <=> dep2.pod.downcase
+          end
+        end
+
+        # 默认值只在这里打印一次，与默认值相同的字段不再逐行输出
+        default_source = file_sources[target_yaml_name(target.name)]&.first
+        log.detail("以下字段使用默认值时逐行省略: :inhibit_warnings => true#{default_source ? ", :source => '#{default_source}'" : ''}")
+        log.info('')
+        sort_deps.each { |dependency|
+          # 依赖行缩进2空格，归属到当前target块
+          puts_result = "  pod '#{dependency.pod}'"
+
+          if dependency.path #路径引用
+            puts_result += ", :path => '#{dependency.path}'"
+          elsif dependency.podspec #podspec引用
+            puts_result += ", :podspec => '#{dependency.podspec}'"
+          elsif dependency.version #版本号引用
+            puts_result += ", '#{dependency.version.to_s}'"
+          elsif dependency.git #git仓库引用
+            puts_result += ", :git => '#{dependency.git}'"
+            if dependency.tag
+              puts_result += ", :tag => '#{dependency.tag}'"
+            elsif dependency.branch
+              puts_result += ", :branch => '#{dependency.branch}'"
+            end
+          end
+
+          if dependency.configurations
+            puts_result += ", :configurations => ['#{dependency.configurations.join("','")}']"
+          end
+          if dependency.subspecs
+            puts_result += ", :subspecs => ['#{dependency.subspecs.join("','")}']"
+          end
+          # inhibit_warnings默认true，仅显式false时打印
+          puts_result += ", :inhibit_warnings => false" if dependency.inhibit_warnings == false
+          # source默认取SOURCES第一个，仅版本号引用且使用非默认源时打印
+          if dependency.version and dependency.source and dependency.source != default_source
+            puts_result += ", :source => '#{dependency.source}'"
+          end
+          if dependency.local_injected
+            puts_result += " [本地新增]"
+          elsif dependency.from_local
+            puts_result += " [本地覆盖]"
+          end
+
+          if dependency.path
+            branch = repo_branch(dependency.path)
+            modify = repo_modify(dependency.path)
+            # 路径依赖青色，分支名/仓库修改状态品红
+            log.info(colorize(puts_result, :cyan) + colorize(branch, :magenta) + colorize(modify, :magenta))
+
+          elsif dependency.branch
+            log.info(colorize(puts_result, :yellow))
+          else
+            log.info(puts_result)
+          end
+
+        }
+      end
+    end
+
+    # 检查工程里不存在对应target的孤儿依赖文件(target改名/删除后残留)
+    def check_orphan_yaml_files
+      expected = targets.map { |target| target_yaml_name(target.name) }
+      Dir.glob("*#{MyConstants::DEPENDENCIES_YAML_SUFFIX}").each do |file|
+        next if file == local_yaml_name
+        next if expected.include?(file)
+        # 文件名约定为 <TargetName>Dependencies.yaml，去掉后缀即配置对应的 target 名
+        target_name = File.basename(file, MyConstants::DEPENDENCIES_YAML_SUFFIX)
+        log.warn("检测到配置文件 #{file} 在工程目录中，但未检测到工程的target '#{target_name}'，已忽略加载该配置文件。请检查该target是否存在并仍在使用，如不存在建议删除该配置文件，以免再次产生此警告")
+      end
+    end
+
+    # 生成默认yaml文件
+    def generate_yaml
+      generate_local_yaml
+      targets.each { |target| generate_target_yaml(target_yaml_name(target.name)) }
+    end
+
+    def generate_local_yaml
+      if File.exist?(local_yaml_name)
+        return
+      end
+      log.detail("生成#{local_yaml_name}文件")
+
+      content = ""
+      content = content + "# 本地依赖文件(不提交git)，两种用途:\n"
+      content = content + "#   1. 按pod名覆盖任意 <TargetName>Dependencies.yaml 中的同名组件(通常写path做本地联调)\n"
+      content = content + "#   2. 直接引入target依赖文件未声明的新组件: 会自动加入主App target且不被裁剪;\n"
+      content = content + "#      App扩展target不会自动注入，扩展需要的新组件请在对应target依赖文件显式声明\n"
+      content = content + "# 引用方式(path/podspec/tag/branch)与字段规则同target依赖文件\n"
+      content = content + "# inhibit_warnings 不写默认false，方便开发时看到本地库的警告并及时修改\n\n"
+
+      content = content + "# TRIM_UNUSED_POD为true时自动移除未被引用的依赖库，加速开发编译\n"
+      content = content + "TRIM_UNUSED_POD: false\n\n"
+
+      content = content + "# 默认只使用target依赖文件中SOURCES声明的私有源，不使用CocoaPods官方CDN trunk源\n"
+      content = content + "# 如本工程确需trunk，把下行改为true(仅本工程生效)\n"
+      content = content + "ENABLE_TRUNK: false\n\n"
+
+      content = content + "PODS: []\n\n"
+
+      content = content + "# 示例:\n"
+      content = content + "# - pod: Masonry\n"
+      content = content + "#   path: ~/MasonryCodePath\n"
+      content = content + "# - pod: MJRefresh\n"
+      content = content + "#   git: git@gitee.com:xxx/MJRefresh.git\n"
+      content = content + "#   branch: master\n"
+
+      File.open(local_yaml_name, 'w') { |file|
+        file.write(content)
+      }
+    end
+
+    def generate_target_yaml(yaml_name)
+      if File.exist?(yaml_name)
+        return
+      end
+      log.detail("生成#{yaml_name}文件")
+
+      content = ""
+      content = content + "# #{File.basename(yaml_name, MyConstants::DEPENDENCIES_YAML_SUFFIX)} target的依赖清单(企业内部组件与第三方组件统一维护)\n"
+      content = content + "# 1、每个组件只能指定 version/tag/branch/path/podspec 其中一种引用方式(tag/branch需配合git)\n"
+      content = content + "# 2、path/podspec 本地联调依赖请写在#{local_yaml_name}中\n"
+      content = content + "# 3、组件不写source时默认使用SOURCES中的第一个源(通常把二进制源放第一位)\n"
+      content = content + "# 4、源地址可用YAML锚点定义为变量(&名字)，组件下通过 *名字 引用，避免重复书写\n"
+      content = content + "# 5、inhibit_warnings 不写默认true(屏蔽远程库警告)；configurations/subspecs 为数组且不能同时使用\n\n"
+
+      content = content + "SOURCES:\n"
+      content = content + "# - &binary 这里替换成默认specs源(一般是二进制源)\n"
+      content = content + "# - &source 这里替换成备选specs源(如源码源)\n\n"
+
+      content = content + "PODS: []\n\n"
+
+      content = content + "# 示例:\n"
+      content = content + "# - pod: Masonry              # 默认源 + 版本号引用\n"
+      content = content + "#   version: 1.1.0\n"
+      content = content + "# - pod: BSDebugPlugins       # 用锚点引用源码源 + 仅Debug集成\n"
+      content = content + "#   version: 1.0.0-SNAPSHOT\n"
+      content = content + "#   source: *source\n"
+      content = content + "#   configurations: [Debug]\n"
+      content = content + "# - pod: CocoaService          # git分支引用\n"
+      content = content + "#   git: git@gitee.com:xxx/CocoaService.git\n"
+      content = content + "#   branch: master\n"
+
+      File.open(yaml_name, 'w') { |file|
+        file.write(content)
+      }
+    end
+
+    # 解析路径依赖仓库的真实.git目录。
+    # 普通仓库/.git是目录；submodule与worktree下.git是文件(内容为 gitdir: 实际git目录路径)
+    # @return [String, ""] 真实.git目录绝对路径，非git仓库返回""
+    def resolve_git_dir(path)
+      full_path = File.expand_path(path)
+      git_path = "#{full_path}/.git"
+      return "" unless Dir.exist?(git_path) || File.file?(git_path)
+
+      return git_path if Dir.exist?(git_path)
+
+      gitdir = File.read(git_path)[/gitdir:\s*(.+)/, 1]
+      return "" if gitdir.to_s.strip.empty?
+
+      File.expand_path(gitdir.strip, full_path)
+    end
+
+    # 获取某个目录下的当前分支
+    def repo_branch(path)
+      git_dir = resolve_git_dir(path)
+      return "" if git_dir.empty?
+
+      head_path = "#{git_dir}/HEAD"
+      unless File.exist?(head_path)
+        return ""
+      end
+
+      content = File.read(head_path)
+      content = content.gsub("\n", "")
+
+      branch_key_word = "ref: refs/heads/"
+      if content.include?(branch_key_word)
+        branch = content.gsub(branch_key_word, "")
+        return "(#{branch})"
+      end
+
+      if content.size >= 8
+        short_sha = content.slice(0, 7)
+        return "(#{short_sha})"
+      end
+
+      " #(#{content})"
+    end
+
+    # 获取仓库状态是否有修改
+    def repo_modify(path)
+      git_dir = resolve_git_dir(path)
+      return "" if git_dir.empty?
+
+      # git -C 在子进程中切换目录，避免全局Dir.chdir的副作用；
+      # 传仓库工作副本根目录，submodule/worktree由git自身通过.git文件定位真实git目录
+      status = %x(git -C #{Shellwords.escape(File.expand_path(path))} status -suno 2>/dev/null)
+      status.size > 0 ? "[modified]" : ""
+    end
+
+    # 读取主工程需要集成依赖的target列表
+    def init_main_targets
+      project_manager = XCProject::XcodeprojManager.share_manager
+      @targets = project_manager.get_app_targets.select { |target| integratable_target?(target) }
+    end
+
+    # 是否裁剪未被引用的依赖库(加速编译)
+    # 单次选项 pod install/update --trim/--full 优先于 LocalDependencies.yaml 的 TRIM_UNUSED_POD
+    def trim_unused_pod?
+      yaml_content = read_yaml_content(local_yaml_name)
+      return $trim_unused_pod unless $trim_unused_pod.nil?
+      yaml_content ? !!(yaml_content["TRIM_UNUSED_POD"]) : false
+    end
+
+    #是否禁用检查podspec文件
+    def disable_check_podspec
+      yaml_content = read_yaml_content(local_yaml_name)
+      disable_check_podspec = yaml_content ? !!(yaml_content["DISABLE_CHECK_PODSPEC"]) : false
+      if disable_check_podspec
+        log.warn("已关闭podspec文件检查，如需开启，请在#{local_yaml_name}里设置DISABLE_CHECK_PODSPEC为false")
+      end
+      disable_check_podspec
+    end
+
+    private
+
+    # 统一日志入口
+    def log
+      CocoaPods::Yaml.log
+    end
+
+    # 仅TTY下对着色，避免CI/重定向日志出现ANSI转义码
+    def colorize(text, color)
+      return text.to_s if text.to_s.empty?
+      $stdout.tty? ? text.to_s.public_send(color) : text.to_s
+    end
+
+  end
+end