cocoapods-yaml 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82dbb70f4e4aed183d28e3155d99048f2fb4fab56b2c6937d705c0ff2254216f
+  data.tar.gz: 9dd087ceaa7cb278628592b8941965cee7e8708c543b5a6f889ad074d06a8f85
+SHA512:
+  metadata.gz: 3559c6d25653e343f7c6776fdd0f7a7cd047ea24482f4171759e272a9cedb5cc6c922d8a9414e9971a7b3b0946c5ddb40e827e49545764f5a4bc176e3d1cbd6b
+  data.tar.gz: 05acafb2d925b7a0c9d785ceb623fe8d4a24264d2b3d1c090170db54d11061ae8c1e7567de6867e792493febcf58ed93460ee704ca067970ea0fcc5ff62a343b

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.0.0 - 2026-10-16
+
+以 YAML 文件按 target 管理 CocoaPods 依赖的插件首个正式版本，安装后由 CocoaPods 自动加载。
+
+- 每个 App/扩展 target 一个依赖文件，二方/三方组件统一维护，支持源地址变量复用
+- 本地覆盖文件支持按组件名覆盖任意依赖做联调，新组件直接写入即自动集成
+- 支持按源码引用关系自动裁剪未使用的依赖，加速编译，兼容 Xcode 16 与 Swift 工程
+- 自动注册私有 specs 源并屏蔽官方 CDN 源，避免网络问题与多版本告警
+- 内置 import 写法检查、依赖完整性检查、模拟器架构检查与三方库编译兼容补丁
+- Debug 包内自动生成依赖清单，便于排查组件版本问题
+- 提供依赖关系查询等辅助命令

data/README.md

@@ -0,0 +1,129 @@
+# cocoapods-yaml
+
+以 YAML 文件按 target 管理 CocoaPods 依赖的插件。符合 `cocoapods-*` 插件命名约定，安装后由 CocoaPods 自动加载，Podfile 直接使用 `yaml_dependencies!` DSL
+
+与 [pod-binary-pack](https://rubygems.org/gems/pod-binary-pack) 配套使用：本插件负责壳工程依赖管理与裁剪安装，后者负责组件二进制化打包与双私有源发布。
+
+## 功能特性
+
+- **按 target 管理依赖**：每个 App/扩展 target 一个依赖文件，二方/三方组件统一维护，支持 YAML 锚点变量复用源地址
+- **本地覆盖联调**：`LocalDependencies.yaml` 按 pod 名覆盖任意依赖（path 联调），不提交 git；全新组件直接写入即自动集成主 App target
+- **未使用依赖裁剪**：按源码 import 引用关系裁剪未使用依赖，加速编译；兼容 Xcode 16+ 同步分组与 Swift import
+- **私有源管理**：自动注册私有 specs 源并屏蔽官方 CDN trunk，间接依赖优先命中二进制源
+- **内置检查**：import 写法、podspec 依赖完整性、模拟器架构兼容、三方库源码编译兼容补丁，post_install 自动执行
+- **Debug 依赖清单**：依赖清单 json 仅打入 Debug 包，便于排查组件版本
+
+## 接入
+
+```ruby
+# Podfile
+platform :ios, '15.0'
+
+yaml_dependencies! do |target_name|
+  # target_name: 当前集成的 target 名称(App/扩展)，每个声明了依赖的 target 回调一次
+  # 可按 target 定制，例如扩展用静态库:
+  #   use_frameworks! :linkage => :static if target_name == 'ShareExtension'
+  use_frameworks!
+end
+```
+
+未接入的工程可执行 `pod yaml init` 自动生成模板 Podfile 与依赖文件（已有 Podfile 会先备份为 `Podfile.bak.时间戳` 再替换）。
+
+## 依赖文件
+
+放在工程根目录，两类：
+
+| 文件 | 是否提交 git | 用途 |
+| --- | --- | --- |
+| `<Target>Dependencies.yaml` | 是 | 各 target 的依赖清单，二方/三方统一维护 |
+| `LocalDependencies.yaml` | 否（自动加入 .gitignore） | 本地覆盖联调、临时引入新组件；`TRIM_UNUSED_POD`/`ENABLE_TRUNK` 开关 |
+
+`<Target>Dependencies.yaml` 示例：
+
+```yaml
+SOURCES:
+  - &binary git@gitee.com:xxx/specs.git     # 二进制源(第一个，默认)
+  - &source git@gitee.com:xxx/specs.git     # 源码源(备选)
+
+PODS:
+  - pod: Masonry                # 默认源 + 版本号引用
+    version: 1.1.0
+  - pod: BSDebugPlugins         # 锚点引用源码源 + 仅 Debug 集成
+    version: 1.0.0-SNAPSHOT
+    source: *source
+    configurations: [Debug]
+  - pod: CocoaService           # git 分支引用
+    git: git@gitee.com:xxx/CocoaService.git
+    branch: master
+```
+
+### PODS 字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `pod` | 必填，组件名 |
+| `version` / `path` / `podspec` / `git`+`tag` / `git`+`branch` | 引用方式，五选一 |
+| `source` | 显式指定 specs 源，默认取 `SOURCES` 第一个 |
+| `subspecs` | 仅集成指定 subspec（数组）；与 `configurations` 互斥（CocoaPods 限制，插件自动展开为多条声明） |
+| `configurations` | 仅在指定 Build Configuration 集成，如 `[Debug]` |
+| `inhibit_warnings` | 屏蔽警告，target 文件默认 true、本地覆盖默认 false |
+
+`LocalDependencies.yaml` 的引用方式与字段规则相同，并额外支持顶层开关：
+
+```yaml
+TRIM_UNUSED_POD: false   # 是否裁剪未使用依赖
+ENABLE_TRUNK: false      # 是否恢复官方 CDN trunk 源
+PODS: []
+```
+
+## 本地覆盖与联调
+
+- **同名覆盖**：LocalDependencies 中按 pod 名声明，覆盖任意 `<Target>Dependencies.yaml` 中的同名组件（通常写 `path` 做本地联调）
+- **全新组件**：target 依赖文件都未声明的组件写入 LocalDependencies 后自动加入主 App target（不会被裁剪）；App 扩展 target 不自动注入，需在对应依赖文件显式声明
+- path 引用的本地仓库自动开启 SNAPSHOT tag 强制同步（`git fetch/pull` 自动前移被删除重建的 tag）
+
+## 未使用依赖裁剪
+
+开发模式下可开启，移除未被源码引用的依赖库以加速编译：
+
+```bash
+pod install --trim     # 单次开启(优先于配置文件)
+pod install --full     # 单次关闭
+pod update --trim      # update 同样支持
+```
+
+或在 `LocalDependencies.yaml` 中设置 `TRIM_UNUSED_POD: true` 长期开启。
+
+## 私有源管理
+
+插件按各 target 依赖文件 `SOURCES` 的声明顺序注册 Podfile 顶层 source（二进制源优先，间接依赖优先命中二进制产物），并屏蔽官方 CDN trunk——trunk 既会因网络问题导致 `pod install` 失败，也会与私有源同名 podspec 产生多版本告警。确需 trunk 时在 `LocalDependencies.yaml` 设置 `ENABLE_TRUNK: true`。
+
+## 内置检查（post_install 自动执行）
+
+| 检查 | 说明 |
+| --- | --- |
+| import 检查 | 引号形式 import 在本组件找不到头文件时给出建议写法；多组件同名头文件列出候选；GBK 源文件容错 |
+| podspec 检查 | 代码实际需要的模块 vs podspec 声明，报告可能缺失/未使用的依赖（含嵌套 subspec 与平台级声明）；`DISABLE_CHECK_PODSPEC: true` 可关闭 |
+| 模拟器架构检查 | 报告缺 arm64 模拟器 slice（需 Rosetta）或完全无模拟器 slice 的二进制依赖，Apple Silicon 链接失败根因预警 |
+| 源码兼容补丁 | 三方库源码微调兼容新版 Xcode（YYText 链式比较、废弃头 `<netinet6/in6.h>`、FBRetainCycleDetector 等）；命中文件警告输出，`COCOAPODS_YAML_SKIP_SOURCE_PATCH=1` 整体关闭 |
+
+另自动完成：间接依赖及其引用方输出、Debug 依赖清单 json 生成与注入（Release 不入包）、yaml 文件加入 Pods 工程引用、孤儿依赖文件清理提示。
+
+## 命令
+
+```bash
+pod yaml init                    # 初始化/备份替换 Podfile 与依赖文件模板
+pod yaml relation [组件名]        # 从 Podfile.lock 查询正/反向依赖
+                                 #   --forward 只看正向；--sort 按依赖数量排序
+```
+
+## 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `COCOAPODS_YAML_VERBOSE` | 非空时输出调试细节（等效 `pod install --verbose`） |
+| `COCOAPODS_YAML_SKIP_SOURCE_PATCH` | 非空时跳过全部三方库源码兼容补丁 |
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/cocoapods/yaml.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../core_helper'
+require_relative '../version'
+core_path = Core::CoreHelper.core_path
+
+require "#{core_path}/logger"
+require "#{core_path}/yaml/yaml_dependencies"
+
+# 裁剪未使用依赖的下载流程补丁，是否裁剪由TRIM_UNUSED_POD/pod install/update --trim判定
+require "#{core_path}/thin/installer"
+
+module Pod
+  class Podfile
+    # DSL入口: 在Podfile中通过 yaml_dependencies! 接入
+    # block的参数为当前集成的target名(App/扩展)，可按target定制 use_frameworks! 等配置
+    def yaml_dependencies!
+      plugin('cocoapods-yaml')
+
+      yaml_dep = Pod::YamlDependencies.new
+      CocoaPods::Yaml.log.info("cocoapods-yaml版本:#{CocoaPods::Yaml::VERSION}")
+      yaml_dep.install_yaml_dep(self) do |target_name|
+        yield(target_name) if block_given?
+      end
+    end
+  end
+end

data/lib/cocoapods_plugin.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# CocoaPods 插件入口：gem 以 cocoapods- 开头时，本文件会被 pod 命令自动加载，
+# 因此 Podfile 无需手动 require，直接使用 yaml_dependencies! DSL 即可。
+
+require 'cocoapods'
+
+require_relative 'cocoapods/yaml'
+
+require "#{Core::CoreHelper.core_path}/command/yaml_init"
+require "#{Core::CoreHelper.core_path}/command/yaml_relation"
+require "#{Core::CoreHelper.core_path}/command/trim_mode"
+require "#{Core::CoreHelper.core_path}/check/project"
+require "#{Core::CoreHelper.core_path}/check/podspec"
+require "#{Core::CoreHelper.core_path}/check/simulator_arch"
+require "#{Core::CoreHelper.core_path}/modify/source_patcher"
+require "#{Core::CoreHelper.core_path}/reference/project"
+require "#{Core::CoreHelper.core_path}/indirect/indirect"
+require "#{Core::CoreHelper.core_path}/reference/unused"
+require "#{Core::CoreHelper.core_path}/check/import"
+
+# pod install/update 在工程目录但缺少Podfile时自动生成模板(零风险初始化)；
+# 已有Podfile但未接入时仅提示 pod yaml init，不自动替换
+if ARGV.include?('install') || ARGV.include?('update')
+  CocoaPods::Yaml::PodfileSetup.auto_on_install
+end
+
+module CocoapodsPlugin
+
+  Pod::HooksManager.register('cocoapods-yaml', :post_install) do |context|
+
+    project = Xcodeproj::XCodeProject.new
+
+    # 检查import
+    checker1 = Xcodeproj::ImportChecker.new(project)
+    checker1.check_import
+
+    # 检查podspec
+    checker2 = Xcodeproj::PodspecChecker.new(project)
+    checker2.check_podspec
+
+    # 模拟器架构兼容检查：找出模拟器产物不含arm64 slice的组件
+    # (Apple Silicon 上按默认 arm64 编译模拟器时链接失败的根因)
+    Xcodeproj::SimulatorArchChecker.new.check
+
+    # 三方库源码编译兼容补丁(netinet6 头替换、FBRetainCycleDetector 历史兼容等)，
+    # 同时覆盖普通 pod 与打包期 :path 开发 pod
+    ModifyCode::SourcePatcher.patch(context.sandbox)
+
+    # 间接依赖
+    PodfileLock::Indirect.new.log_indirect
+
+    # 添加yaml到Pods工程引用和gitignore
+    Project::ProjectManager.yaml_reference
+
+    # 生成Debug包内依赖清单json并注入资源脚本(仅Debug)
+    Project::ProjectManager.dependency_manifest(context)
+
+    # 裁剪未使用依赖的开关提示
+    Unused::UnusedManager.check_unused
+
+  end
+
+end

data/lib/core/check/import.rb

@@ -0,0 +1,74 @@
+require_relative 'project'
+
+module Xcodeproj
+  class ImportChecker
+
+    # @return [XCodeProject]
+    attr_accessor :project
+
+    # @param project::[XCodeProject]
+    def initialize(project)
+      @project = project
+    end
+
+    # 检查import规范
+    def check_import
+      CocoaPods::Yaml.log.step("import检查中...")
+      start = (Time.now.to_f * 1000).to_i
+      module_count = 0
+      file_count = 0
+
+      project.module_items.each do |module_name, module_item|
+        unless module_item.is_development_module
+          next
+        end
+        module_count += 1
+
+        messages = []
+
+        did_check_imports = {}
+        module_item.init_import_info
+
+        module_item.import_items.each do |import_item|
+          # 同一组件内同名import只检查一次(无论本组件能否找到头文件)，避免重复告警与重复全量扫描
+          next if did_check_imports.key?(import_item.import_file_name)
+          did_check_imports[import_item.import_file_name] = true
+          file_count += 1
+
+          need_module_item = project.module_items[import_item.module_name]
+          real_path = need_module_item&.header_files&.[](import_item.import_file_name)
+          next if real_path
+
+          # 本组件找不到，去其他组件查找所属模块
+          expect_modules = find_modules_with_header_file(import_item.import_file_name)
+          if expect_modules.size == 1
+            messages << "#{import_item.file_path.basename} 第#{import_item.line_index}行 #{import_item.import_name} => #import <#{expect_modules.first}/#{import_item.import_file_name}>"
+          elsif expect_modules.size > 1
+            # 多个组件含同名头文件时无法确定归属，给出候选而不是猜测一个可能错误的组件
+            messages << "#{import_item.file_path.basename} 第#{import_item.line_index}行 #{import_item.import_name} 在本组件找不到该头文件，且组件#{expect_modules.join('、')}均含同名头文件，请手动确认正确写法"
+          end
+        end
+
+        if messages.size >0
+          CocoaPods::Yaml.log.warn("组件#{module_item.module_name}存在以下情况, 请检查:")
+          messages.each { |message| CocoaPods::Yaml.log.info("  #{message}") }
+        end
+
+      end
+
+      duration = ((Time.now.to_f * 1000).to_i - start)*0.001
+      # 本检查器只解析开发组件源码中的引号形式import(#import "X.h")，尖括号形式由podspec检查器负责
+      CocoaPods::Yaml.log.detail("import检查完毕! 共检查#{module_count}个组件(#{file_count}处引号import，去重后) 耗时:#{duration.round(2)}秒")
+    end
+
+    private
+    # 根据头文件名查找所有包含该头文件的组件(按头文件basename匹配)
+    # @return [Array<String>] 组件名列表；0个=无匹配，1个=可确定归属，>1个=重名无法确定
+    def find_modules_with_header_file(header_file_name)
+      project.module_items.each_with_object([]) do |(_module_name, module_item), result|
+        result << module_item.module_name if module_item.header_files[header_file_name]
+      end
+    end
+
+  end
+end

data/lib/core/check/item.rb

@@ -0,0 +1,220 @@
+
+module Xcodeproj
+  class ImportItem
+    attr_accessor :import_name
+    attr_accessor :module_name
+    attr_accessor :file_path
+    attr_accessor :import_file_name
+    attr_accessor :line_index
+    attr_accessor :belong_module
+    def initialize
+      @import_name = nil
+      @module_name = nil
+      @file_path = nil
+      @import_file_name = nil
+      @line_index = nil
+      @belong_module = nil
+    end
+
+  end
+
+  class ModuleItem
+
+    public
+    # 组名名
+    attr_accessor :module_name
+
+    # 组件路径
+    attr_accessor :module_path
+
+    # podspec路径
+    attr_accessor :podspec_path
+
+    # 组件目录的所有被引用的文件数组
+    attr_accessor :header_files
+
+    # 组件目录的所有被引用的文件数组
+    attr_accessor :source_files
+
+    # 是否是开发模块
+    attr_accessor :is_development_module
+
+    # [ImportItem]
+    attr_accessor :import_items
+
+    # [ImportItem]
+    attr_accessor :absolute_import_items
+
+    # [String]
+    attr_accessor :frameworks
+
+    def initialize(module_name)
+      @module_name = module_name
+      @module_path = nil
+      @podspec_path = nil
+      @header_files = {}
+      @source_files = {}
+      @import_items = []
+      @absolute_import_items = []
+      @is_development_module = false
+      @frameworks = []
+    end
+
+    # 生成 import <XX/YY.h>的信息
+    # 生成 include <XX/YY.h>的信息
+    def init_absolute_import_info
+      source_files.each_value do |source_file_path|
+        if File.directory?(source_file_path)
+          next
+        end
+
+        line_array = safe_readlines(source_file_path)
+        line_array.each_with_index { |line, line_index|
+          line = line.gsub(" ", "")
+
+          # 进入实现体后不再解析import(import按约定只出现在文件头部)，
+          # 该判断必须在#import前缀过滤之前，否则@implementation行已被next而永远不可达
+          if line.start_with?("@implementation")
+            break
+          end
+
+          # 处理特殊情况
+          if line.start_with?("#import\"NBSAppAgent.h\"")
+            line = "#import<tingyunApp/NBSAppAgent.h>"
+          end
+
+          if not line.start_with?("#import<") and not line.start_with?("#include<")
+            next
+          end
+
+          # 前一行用于识别条件编译(#if/#else)内的import
+          pre_index = line_index-1 < 0 ? 0 : line_index-1
+          pre_line = line_array[pre_index]
+
+          import_item = other_module_import(line, source_file_path, line_index, @module_name, pre_line)
+          if import_item
+            absolute_import_items << import_item
+          end
+        }
+      end
+
+      absolute_import_items
+    end
+
+    # 生成 import "XXX.h"的信息
+    def init_import_info
+      source_files.each_value do |source_file_path|
+        if File.directory?(source_file_path)
+          next
+        end
+
+        line_array = safe_readlines(source_file_path)
+        line_array.each_with_index { |line, line_index|
+          line = line.gsub(" ", "")
+
+          # 进入实现体后不再解析import，判断必须在#import前缀过滤之前(否则该行已被next)
+          if line.start_with?("@implementation")
+            break
+          end
+
+          unless line.start_with?("#import")
+            next
+          end
+
+          # 前一行的内容
+          pre_index = line_index-1 < 0 ? 0 : line_index-1
+          pre_line = line_array[pre_index]
+
+          if line.start_with?("#import\"") #本组件
+            import_item = own_module_import(line, source_file_path, line_index, @module_name, pre_line)
+            if import_item
+              import_items << import_item
+            end
+          elsif line.start_with?("#import<") #其他组件
+
+          end
+
+        }
+      end
+
+      import_items
+    end
+
+    private
+    # 生成自己模块的import item
+    # @param line 以 import" 开头
+    def own_module_import(line, file_path, line_index, module_name, pre_line)
+      line_split_array = line.split("\"")
+      if line_split_array.size <= 1
+        return nil
+      end
+
+      import_content = "#{line_split_array[0]}\"#{line_split_array[1]}\"" # import"XXX.h" 或import"XXX.AAA.h" 防止后边有其他内容
+
+      # 特殊处理
+      if import_content == "#import\"NBSAppAgent.h\""
+        return nil
+      end
+
+      pre_line = pre_line.gsub(" ", "").gsub("\n", "")
+      if pre_line.start_with?("#if") or pre_line == "#else"
+        return nil
+      end
+
+      import_file_name = import_content
+      import_file_name = import_file_name.gsub("#import\"", "")
+      import_file_name = import_file_name.gsub("\"", "")
+      # 统一取basename与header_files的键(头文件名)对齐，兼容 #import "Sub/X.h" 带子目录的写法
+      import_file_name = File.basename(import_file_name) # 变成 XX.h
+
+
+      import_item = ImportItem.new # (import_name, module_name, file_name, line_index, podfile)
+      import_item.import_name = import_content.gsub("#import\"", "#import \"")
+      import_item.module_name = module_name
+      import_item.file_path = file_path
+      import_item.import_file_name = import_file_name
+      import_item.line_index = line_index + 1
+
+      import_item
+    end
+
+
+    def other_module_import(line, file_path, line_index, module_name, pre_line)
+      line = line.gsub("\n","")
+      line_split_array = line.split("/") #import<XX/YY.h> 或 #import<XX/YY/ZZ.h>
+      if line_split_array.size <= 1
+        return nil
+      end
+
+      pre_line = pre_line.gsub(" ", "").gsub("\n", "")
+      if pre_line.start_with?("#if") or pre_line == "#else"
+        return nil
+      end
+
+      import_file_name = line_split_array[line_split_array.size-1].gsub(">", "")
+      belong_module =  line_split_array[0].gsub("#import<", "").gsub("#include<", "")
+      import_name = line.gsub("#import<", "#import <").gsub("#include<", "#include <")
+
+      import_item = ImportItem.new # (import_name, module_name, file_name, line_index, podfile)
+      import_item.import_name = import_name
+      import_item.module_name = module_name
+      import_item.file_path = file_path
+      import_item.import_file_name = import_file_name
+      import_item.line_index = line_index + 1
+      import_item.belong_module = belong_module
+
+      import_item
+
+    end
+
+    # 容错读取源码行：历史工程可能存在GBK等非UTF-8文件。
+    # 注意: 直接给IO.readlines传encoding: 'utf-8'在内外编码相同时不会转码，非法字节仍会透传，
+    # 这里先按二进制读取，再显式做一次同编码转换替换非法字节，
+    # 避免后续字符串处理抛invalid byte sequence中断整个post_install钩子
+    def safe_readlines(file_path)
+      content = File.read(file_path, mode: 'rb')
+      content.encode!('UTF-8', 'UTF-8', invalid: :replace, undef: :replace, replace: '?')
+      content.lines
+    end
+  end
+end