swift-evolution-metadata-extractor

Swift Evolution 仪表板的 JSON 元数据生成器。

swift-evolution-metadata-extractor 工具读取 swift-evolution 仓库的主分支，提取提案元数据，并生成一个 JSON 文件，用作 Swift Evolution 仪表板 的数据源。

除了提取工具外，此软件包还提供 EvolutionMetadataModel 库，该库为进化元数据 JSON 文件提供编码和解码的类型。此库旨在供驱动进化仪表板的元数据文件的客户端使用。

swift-evolution-metadata-extractor

不带任何参数运行命令将执行以下操作

1. 从 swift-evolution 仓库获取当前提案列表
2. 从 swift.org 获取之前的元数据结果
3. 获取并提取有更改的提案的元数据
4. 将提取的元数据写入命令所在目录中的 evolution.json 文件

默认行为可以通过多种方式配置。

使用 --output-path 选项 (-o) 来指定不同的输出位置或文件名。

如果指定的路径不存在，该工具将尝试创建必要的目录。

• 使用不带文件扩展名的路径结尾来指定路径并使用默认文件名

  swift-evolution-metadata-extractor --output-path ~/Desktop

  将输出写入 ~/Desktop/evolution.json

• 使用带文件扩展名的路径结尾来指定路径和文件名

  swift-evolution-metadata-extractor -o ~/Desktop/my-metadata.json

  将输出写入 ~/Desktop/my-metadata.json

• 使用值 'none' 来禁止输出

  swift-evolution-metadata-extractor --output-path none

默认情况下，会检查先前提取的提案的 SHA 值，以避免处理没有更改的提案。

使用 --force-extract 选项强制提取所有或指定的提案进行获取和处理。

• 使用值 'all' 强制处理所有提案，忽略先前的结果
  swift-evolution-metadata-extractor --force-extract all

• 使用提案标识符强制处理特定的提案
  swift-evolution-metadata-extractor --force-extract SE-0287

• 多次使用 --force-extract 选项以处理多个提案
  swift-evolution-metadata-extractor --force-extract SE-0287 --force-extract SE-0123

在开发期间，使用 --snapshot-path 选项指定本地 evosnapshot 目录作为数据源。

• 使用值 'default' 指定所有进化提案的默认快照
  swift-evolution-metadata-extractor --snapshot-path default

• 使用值 'malformed' 指定格式错误的进化提案的测试快照
  swift-evolution-metadata-extractor --snapshot-path malformed

有关快照的更多信息，请参阅 用于开发和测试的快照。

在工具运行时，使用 --verbose 选项 (-v) 获取详细输出。

使用可选的环境变量来提供代理和授权信息。

HTTP_PROXY | http_proxy
如果存在，HTTP 网络请求将使用指定的代理。

HTTPS_PROXY | https_proxy
如果存在，HTTPS 网络请求将使用指定的代理。

GITHUB_TOKEN
如果存在，提供的令牌将作为授权标头包含在 GitHub API 请求中。

该软件包提供 EvolutionMetadataModel 库。该库定义了 Codable、Equatable、Sendable 值类型，这些类型适用于解码生成的进化元数据文件。

使用 snapshot 子命令来记录快照。

swift-evolution-metadata-extractor snapshot

快照是一个输入文件和预期结果的目录，用于开发和测试。快照目录使用文件扩展名 evosnapshot，但在 macOS 上未正式声明为 bundles。

也可以手动构建 Ad hoc 快照，以创建用于特定测试的内容，例如验证是否在格式错误的提案中正确检测到验证错误。

snapshot 子命令具有与 extract 命令选项类似的选项

• 使用 --output-path 选项 (-o) 来指定不同的输出位置或文件名。

• 在工具运行时，使用 --verbose 选项 (-v) 获取详细输出。

• 使用 --snapshot-path 选项来指定本地 evosnapshot 目录作为数据源。

  当现有快照的预期结果发生更改时，请使用此选项创建包含现有快照输入文件和最新预期结果的新快照。例如，当添加验证用例时，这将很有用，这些用例为 Malformed.evosnapshot 快照中的提案生成新的或不同的错误和警告。

快照是一个带有扩展名 evosnapshot 的目录，其中包含具有众所周知名称的文件。

如 Ad hoc 快照 中所述，快照可以包含文件子集。

例如，由 snapshot 子命令生成的快照不包含 previous-results.json 文件。

• 提案 markdown 文件目录
  proposals/XXXX-proposal-files.md

• 来自源数据的预期结果
  expected-results.json

• GitHub 提案目录查询结果。包含提案 SHA 值
  proposal-listing.json

• 关于分支或 PR 的 GitHub 查询结果。包括名称和标识符
  source-info.json

• 先前的结果。如果存在，将在处理中使用，除非指定强制提取
  previous-results.json

为了进行测试，可以在手动构建的快照中表示各种情况，这些情况代表格式错误的提案或很少遇到的状态。

例如，ExtractionTests 目标中的 Malformed.evosnapshot 用于测试内容验证警告和错误。

这些 ad hoc 快照通常仅包含 proposals 目录和 expected-results.json 文件。

通常，快照中不存在 previous-results.json 文件，但可能存在于用于测试使用先前结果或强制提取的快照中。