WitnessForge

项目介绍

大型机数据迁移到 JSON 文档库的测试并不好做：生产数据副本体量大，还含真实个人信息；手工测试文件又未必覆盖到棘手情况。WitnessForge 读取 COBOL copybook 和一份声明式的源到目标映射，生成一小组符合 copybook 布局的 EBCDIC 记录（witnesses），从构造上就能捕获映射规则错误。

工具会针对映射中的每条规则制造变异（例如丢失隐含小数位、忽略过滤条件、OCCURS 元素错位），在字节层面用正确流水线和每个错误版本逐一处理候选记录，再用贪心集合覆盖保留能检出所有故障的最少记录集，输出逐规则覆盖率，并可按最低分数卡住 CI。另一个命令 verify 将真实流水线加载和拒绝的结果与预期文档比对。

适用对象是处理定长 EBCDIC 大型机文件、COBOL copybook 和 JSON 文档存储的 ETL 与数据迁移团队；运行仅需 Python 3.9+ 和 PyYAML，许可证为 Apache-2.0。

快速使用

在发布到 PyPI 之前从源码安装（README 如此说明）：

git clone https://github.com/skavuri143/witnessforge.git
cd witnessforge
pip install -e ".[dev]"

仓库自带一个覆盖全部支持特性的资格示例，位于 examples/eligibility。生成 witnesses 与覆盖率报告：

witnessforge generate examples/eligibility/member.cpy examples/eligibility/mapping.yaml -o out

generate 会写出定长 EBCDIC 的 witnesses.dat、可读的 witnesses.jsonl、预期的加载/拒绝/过滤 JSONL 文件，以及包含逐规则分数的 report.json/report.md。在示例上，工具报告 27 条 witness 记录检出了 163/163 个映射故障。然后用真实流水线处理 witnesses.dat 并核对输出：

witnessforge verify examples/eligibility/member.cpy examples/eligibility/mapping.yaml \
    --input out/witnesses.dat --actual loaded.jsonl --rejects rejects.jsonl

如果只想查看会检查哪些故障，先运行 witnessforge mutants ...。以上命令也可用作 CI 步骤；--min-score 1.0 会让 generate 在有故障未被检出时以非零码退出。

使用约束

映射规范支持文本、zoned decimal、压缩十进制（COMP-3）和二进制 COMP 字段的解码；支持去空白、大小写、截取、填充、日期重格式化、码表查找、算术、正则替换等转换；支持必填、长度、范围、pattern、allowed 等校验；支持记录级过滤与拒绝、OCCURS 数组，以及由并列 OCCURS 字段构建的嵌套对象。任何有效输入都无法暴露的故障会被报为未检出，项目将其视为等价变异体或规范缺口。

以下场景明确列在路线图中而尚未支持：跨表引用完整性、批次汇总与对账、变更数据捕获与 SCD 历史、跨字段规则、REDEFINES、OCCURS DEPENDING ON，以及容量与性能测试。不支持的 copybook 结构会直接报错，而不是被误读。由于 witness 由映射规范推导，覆盖率只相对于你写下的规则有意义；工具无法证明规范未描述的行为。

HotRepo 点评

WitnessForge 于 2026-11-08 出现在 HotRepo 的 Python 语言新项目榜，记录显示约 2.5 小时内新增 9 颗星，未进入全语言日榜。它吸引人的地方在于承诺了一个明确性质：为大型机 ETL 迁移提供可证明、最小化的测试集，而这一环节的覆盖率通常只能靠猜。需要关注的是范围：按记录的变异方法能较好覆盖映射和校验规则，但仍在路线图上的引用完整性、控制总计、CDC 恰恰是许多真实迁移出错的地方，团队应把 100% 分数理解为对已描述映射规则的结论，而不是整个作业的结论。