Herb Corpus

一个真实世界Rails应用程序的语料库，用于测试Herb（解析器、linter、格式化程序和打印机），针对实际部署的ERB。包含256个应用程序和引擎，32,922个.erb文件，大小约50 MB，每个应用程序固定到特定提交以确保可重现性。A corpus of real-world Rails applications designed for testing Herb — a parser, linter, formatter, and printer — targeted at production-deployed ERB files. This dataset includes 256 applications and engines, 32,922 .erb files with a total size of approximately 50 MB. Each application is pinned to a specific commit to ensure reproducibility.

原始信息汇总

数据集概述

Herb Corpus 是一个由真实世界 Rails 应用程序组成的语料库，专门用于测试 Herb（解析器、linter、格式化器和打印机）对实际生产环境中 ERB 模板的处理能力。每个应用程序都固定到确切的提交，确保跨机器和 CI 的结果可重复。

---

规模统计

指标	数值
应用程序和引擎总数	256
erb/ 目录中的 .erb 文件	32,922（来自 228 个应用）
erb/ 目录大小	~50 MB
待审核许可证的应用（已排除）	28 个

---

双层结构

herb-corpus/ ├── apps/ # 每个应用为一个 git 子模块，固定在确切提交 ├── erb/ # 提取的所有 .erb 文件（扁平排布），附带来源清单 ├── corpus.yml # 每个应用的来源与许可证信息 ├── Yerbafile # corpus.yml 的格式化规则 └── bin/ # 管理 CLI 及 CI 运行的脚本

• apps/：数据源，包含完整 git 历史，占用数 GB 磁盘空间。
• erb/：从 apps/ 生成的扁平 .erb 文件，大小约 50 MB，已包含在仓库中。erb/MANIFEST.json 记录每个提取文件的来源仓库、提交 SHA 和许可证。

---

获取数据集

• 仅需 ERB 文件：直接 git clone。
• 需要完整应用：git clone 后运行 bin/corpus clone。
• 默认仅检出 ERB：bin/corpus clone 使用 blobless 部分克隆和稀疏检出，仅包含 *.erb 及许可证/README 文件。可通过 --full 参数获取完整工作目录。
• 不使用浅克隆：因许多应用固定在非分支顶端提交。

---

命令行工具 (CLI)

所有命令均支持可选的应用程序名称列表和 --help 选项，仅依赖 Ruby 标准库。

命令	功能
bin/corpus clone	克隆未检出的应用（默认仅 ERB）
bin/corpus update	将每个应用的固定提交更新到其跟踪分支的最新提交
bin/corpus status	显示每个应用的固定提交、检出状态和漂移情况
bin/corpus drift	报告哪些应用的固定提交落后于其分支（无需检出）
bin/corpus list	列出应用及其仓库、分支、.erb 文件数和许可证
bin/corpus add	添加新应用为子模块并创建清单条目
bin/corpus remove	移除应用的子模块和检出
bin/corpus extract	将 .erb 文件复制到 erb/ 并附带来源清单
bin/corpus stats	打印语料库统计信息，或刷新 README 中的统计块
bin/corpus measure	在语料库上运行不同 Herb 版本并对比结果

---

corpus.yml 配置

每个应用在 corpus.yml 中为一个条目，包含以下字段：

• name：应用名称，作为所有命令的键
• repo：仓库地址
• license：许可证类型
• license_file：许可证文件名
• redistributable：是否可重新分发（布尔值）
• 可选字段：upstream、fork、note、exclude_paths（排除因许可证不同而不提取的目录）

格式化由 Yerba 维护，条目按 name 字母排序，字段顺序固定，条目间空一行。

---

自动化工作流

• 每周漂移检查：.github/workflows/weekly-drift.yml 每周一运行，使用 bin/corpus drift 检查漂移。
• 漂移处理：当有移动时，克隆相应应用、更新固定提交、重新生成 erb/ 并创建 Pull Request。
• 不自动合并：固定提交更新需人工审核，以确保结果可比性。
• 关键监控指标：解析错误计数，属于 Herb 自己的 CI 范畴。

---

脚本文件

所有 CI 运行的脚本位于 bin/ 目录，可在本地预运行：

脚本	功能
bin/corpus	管理 CLI（克隆、更新、漂移、提取、统计、测量）
bin/check	对 .gitmodules、corpus.yml 和 erb/MANIFEST.json 进行一致性检查
bin/measure-herb	测量一个 Herb 版本在语料库上的表现
bin/diff-runs	比较两次测量运行结果
bin/drift-report	将 corpus drift --json 转换为步骤输出和注释
bin/render-pr-body	构建每周固定提交更新 Pull Request 的正文

---

测量对比

sh bin/corpus measure --herb 0.9.4 --herb 0.10.2 # 比较两个版本 bin/corpus measure --herb 0.10.2 --gem-path ../herb # 版本与工作目录对比 bin/corpus measure --diff runs/a.json,runs/b.json # 重新对比现有运行

• 整个语料库每个版本约需 7 秒。
• 输出包含对比表格和结果有变化的文件列表。
• 可信保证：
  1. 测量代码位于此仓库，Herb 版本为可替换依赖。
  2. 使用单一固定指标：files_with_recursive_errors（递归错误文件数）。
  3. 每次运行记录语料库提交，拒绝对比不同语料库状态的运行。

---

固定提交策略

• 每个应用跟踪其官方上游仓库的默认分支，不指向分支或包含本地补丁。
• bin/corpus update 将应用移动到 .gitmodules 中记录的分支最新提交。
• 远程消失处理：
  • 分支删除：改用 main 分支。
  • 仓库消失：将检出移出语料库（而非删除）。
  • bin/corpus drift 报告不可达问题，每周工作流发出警告。

---

数据来源与许可

• 来源：主要来自 real-world-rails（生产环境 Rails 代码库精选集）及直接添加的应用。
• 包含类型：应用程序和 Rails 引擎，后者更依赖 partial、helper 和 i18n 插值，有助于测试不同解析路径。
• 许可证处理：
  • corpus.yml 记录每个应用的许可证和可重新分发标志。
  • bin/corpus extract 尊重该标志，将许可证文本复制到 erb/<app>/ 中。
  • 标记为 redistributable: false 的应用不纳入 erb/，但仍保留在 apps/ 中供本地测试。
  • 每个应用的许可证均通过阅读实际文件确认，而非仅依赖 GitHub 报告。
  • 存在目录级许可证差异的应用通过 exclude_paths 处理。
• 版权声明：所有应用源代码归各自作者所有，本仓库不主张所有权。

搜集汇总

数据集介绍

构建方式

Herb Corpus是一个面向真实世界Rails应用程序的语料库，专为测试Herb解析器、检查器、格式化工具和打印工具而构建。该语料库通过Git子模块机制，将每个应用程序精确固定于某个提交版本，确保跨机器与CI环境的可重复性。数据集采用双层结构设计：apps/目录存放完整的Git子模块，保留全部历史记录；erb/目录则从apps/中提取所有.erb文件，并以扁平形式存储，附带详细的出处清单（MANIFEST.json），记录每个文件的来源仓库、提交哈希与许可证信息，实现可追溯性。构建流程通过一系列命令行工具自动化完成，包括克隆、提取、统计与更新等操作。

特点

该数据集的核心特色体现在其层次化的可访问性与精确的版本固定机制。apps/提供完整的应用上下文与Git历史，适用于深度分析；而erb/体积小巧（约50 MB），无需克隆完整仓库即可直接使用，特别适合CI批量解析与离线场景。此外，数据集默认采用稀疏检出与无blob部分克隆策略，大幅降低磁盘占用与克隆时间（如dev.to从1 GB缩减至34 MB）。每个应用都追踪其上游默认分支，避免使用携带本地补丁的分支，确保测试的ERB文件真实反映作者实际部署的原始内容，而非经过Herb清理后的版本。每周自动化漂移检测通过git ls-remote远程查询，仅在有变动时才会更新固定点，以最小化资源消耗。

使用方法

使用Herb Corpus分为两种场景。若仅需ERB文件，直接执行git clone命令即可获得erb/目录及其清单文件。若需完整应用上下文，则需运行bin/corpus clone命令，该命令会自动完成子模块的稀疏检出。语料库提供一套完整的CLI工具：bin/corpus list列出所有应用及其元数据，bin/corpus update将指定应用移至其分支的最新提交，bin/corpus extract重新生成erb/目录。对于性能评估，bin/corpus measure命令可针对不同Herb版本执行对比测试，输出包含文件失败数量变化与具体回归文件列表。测量脚本通过显式指定待测版本或工作路径，避免Gemfile固定版本导致的自我对比误差，确保比较结果的可靠性。

背景与挑战

背景概述

Herb Corpus数据集由开发者Marco Roth于2024年创建，旨在为Ruby on Rails生态中的ERB模板解析、格式化与静态分析工具Herb提供真实的测试基准。该数据集整合了256个实际部署的Rails应用与引擎，提取了超过32,000个.erb文件，覆盖了视图组件、局部模板、国际化插值等多样化场景。通过将每个应用锁定至精确的Git提交，确保了跨机器与持续集成环境的可复现性。作为Herb项目的配套资源，Herb Corpus填补了Rails模板工具缺乏标准化测试语料库的空白，为解析器开发、回归测试及性能对比提供了不可或缺的参照系，在Rails工具链的稳健性改进中扮演了基石角色。

当前挑战

Herb Corpus面临的核心挑战在于构建与维护真实且可复现的测试语料库。领域层面，ERB模板的非结构化特性使解析器需应对语法模糊性、编码差异及动态Ruby代码注入，而大规模真实模板的获取需解决版权合规与许可问题，如28个应用因许可证不明被排除分发。构建层面，数据集需平衡存储效率与版本完整性：采用稀疏检出与无blob部分克隆以控制磁盘占用，但深究历史时仍需全量仓库；每周自动漂移检测仅借助远程引用来避免全量克隆，然而当上游分支删除或仓库消失时，已锁定的提交变得不可达，需人工介入调整。此外，不同Herb版本间的度量必须基于相同语料库状态，防止因基线变动而混淆解析器回归与模板内容更新。

常用场景

经典使用场景

Herb Corpus作为一个汇聚了256个真实世界Rails应用、涵盖32922个ERB模板文件的大规模语料库，其最经典的使用场景在于为静态代码分析工具提供基准测试平台。通过将每个应用固定到特定提交版本，该语料库确保了跨机器和持续集成环境的实验结果可复现。研究人员常利用它评估解析器、格式化工具或检查工具对实际生产中ERB模板的处理能力，通过对比不同版本工具在整个语料库上的解析错误率、格式差异等指标，来量化工具的性能改进或回归。这种基于真实世界代码的测试范式，比人工构造的测试用例更能反映工具在复杂工业场景下的鲁棒性。

解决学术问题

该数据集解决了软件工程领域中代码分析工具评估缺乏标准化、可复现真实数据集的学术难题。传统上，解析器或格式化工具的测试往往依赖人工编写的测试样例，难以覆盖真实Rails应用中多样的ERB编写模式——包括复杂的嵌套、不规范的缩进、混合Ruby代码与HTML的边界情况等。Herb Corpus通过提供一个版本可追溯、许可信息透明的大规模语料库，使得研究者能够客观比较不同工具（如ruby_parser、erb_linter等）在实际部署代码上的表现差异，推动了代码分析工具评估从定性描述走向定量分析。其意义在于建立了代码工具评测的基准，促进了该领域实验的可重复性和成果的可信度。

衍生相关工作

围绕Herb Corpus已衍生出一系列工具与工作流。最直接的关联工作是Herb解析器本身，其性能优化和回归检测完全建立在此语料库之上。Yerba——一个针对YAML格式文件的正则格式化工具，正是为解决corpus.yml的排序与格式化自动化而生。此外，社区基于该语料库开发了erb测量脚本和差异比对工具bin/diff-runs，能够精确追踪任意两个Herb版本间解析结果的变化。该语料库还启发了其他语言生态的类似工作，如为Python模板引擎构建真实世界模板语料库的探索，以及将语料库构建模式推广到前端JSX文件分析工具评测的尝试。这些衍生工作共同形成了一个围绕真实世界代码评估工具的生态系统。