# TapTrail

TapTrail 是一个纯 MoonBit 实现的 TAP13 测试输出解析、校验和报告生成库。它把 TAP 文本解析成结构化数据，检查计划行、测试点编号、失败用例、Bail out、未知行和 YAMLish 诊断块，并输出适合 CI 留痕的 Markdown、紧凑 JSON 或 JUnit 风格 XML。

## 解决的问题

MoonBit 项目常见验收要求包括可运行测试、CI、测试记录和可追踪发布过程。TapTrail 提供一个小而明确的测试报告核心：把已有测试输出转换为可审计的结果，让库作者、工具作者和评审者能快速看到测试是否按计划执行、失败在哪里、诊断信息是否完整。

## 适用场景

- MoonBit 包的 CI 测试结果摘要。
- 自定义测试框架输出 TAP 后的质量门禁。
- 发布前生成 Markdown 测试记录。
- WebAssembly 或命令行工具在无复杂外部依赖环境下的报告解析。

## 安装

发布后可通过 Mooncakes 安装：

```bash
moon add MX-ai-nb/taptrail
```

当前 `moon.mod` 已使用 `MX-ai-nb/taptrail` 作为 Mooncakes 包名，并指向公开仓库地址 `https://github.com/MX-ai-nb/taptrail.git`。

## 最小示例

```mbt
fn main {
  let tap = #|TAP version 13
    #|1..2
    #|ok 1 - parser
    #|ok 2 - report
  let report = parse_and_report(tap)
  println(to_markdown(report))
}
```

运行仓库内示例：

```bash
moon run examples/basic_report
```

## 本地运行

```bash
moon check
moon build
moon test
moon run cmd/main
moon run examples/basic_report
```

发布前自检：

```bash
moon publish --dry-run
```

## 核心功能

- `parse_tap(input)`：解析 TAP13-ish 文本为 `TapDocument`。
- `summarize(doc)`：统计 planned、total、passed、failed、skipped、todo、diagnostics、yaml_blocks。
- `validate(doc)`：生成可用于 CI gate 的 `TapReport`。
- `parse_and_report(input)`：解析并校验一步完成。
- `to_markdown(report)`：生成 Markdown 测试记录。
- `to_compact_json(report)`：生成紧凑 JSON 摘要。
- `to_junit_xml(report, suite_name="taptrail")`：生成 JUnit 风格 XML。
- `report_passes(input)`：返回是否无校验问题。

## 支持范围

- `TAP version 13`。
- `1..N` 计划行，包括 `1..0 # SKIP ...` 形式。
- `ok N - name` 与 `not ok N - name`。
- `# SKIP reason` 与 `# TODO reason` 指令。
- `# diagnostic` 注释行。
- 缩进 YAMLish 诊断块 `---` 到 `...`。
- `Bail out! reason`。
- Markdown、紧凑 JSON 与 JUnit 风格 XML 文本导出。

## 暂不支持范围

- 完整 YAML 语义解析。
- TAP nested subtest 的层级建模。
- 从文件系统直接读取 TAP 文件。
- JUnit XML、SARIF、LCOV 等其他测试报告格式。

## 测试与验收命令

当前测试覆盖正常输入、错误输入、边界输入、数据结构转换、核心校验、导出结果、CLI smoke 和主要错误路径：

```bash
moon test
```

完整验收命令：

```bash
moon check
moon build
moon test
moon run cmd/main
moon run examples/basic_report
moon publish --dry-run
```

## Mooncakes 包名

当前模块名为 `MX-ai-nb/taptrail`。正式发布时，`MX-ai-nb` 必须与 Mooncakes owner 一致。

发布后检查地址：

- `https://mooncakes.io/docs/MX-ai-nb/taptrail`
- `https://mooncakes.io/api/v0/manifest/MX-ai-nb/taptrail`

## 开源许可证与第三方说明

本项目使用 MIT 许可证。核心实现为原创 MoonBit 代码；未移植第三方源码，未包含第三方素材或私有测试数据。项目仅参考 TAP 文本格式的公开约定和 MoonBit 官方文档。