Metadata-Version: 2.4
Name: summary-tool
Version: 1.0.1
Summary: Compare testdetails tables from HTML reports and generate diff/summary HTML reports.
Author-email: Continue CLI <noreply@continue.dev>, fchyang <fchyang@126.com>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# XTS Summary Tool

## 简介
`summary_tool` 是一个用于提取、比较文本或 HTML 内容并生成差异报告的 Python 包。它可以帮助对比两套文档（如稿件、翻译稿等），并生成可视化的 HTML 报告以及汇总页面。

---

## 环境要求
- Python 3.11 或以上
- 运行环境：Linux (已在 Docker 镜像中测试)

---

## 安装步骤
1. 克隆或下载代码库（已在本目录下）。
2. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```
3. （可选）如果希望以命令行入口使用，推荐以可编辑方式安装：
   ```bash
   pip install -e .
   ```
   这会在 `PATH` 中添加 `summary-tool` 命令。

---

## 使用示例
以AATS实际目录，ex：
单参数：
summary-tool http://10.22.193.246/AATS_XTS_REPORTS/Merlin9_ANR16/DB2881/20260102_171/
- 会把171版本下面所有的报告汇总到xts_summary.html，单列显示
双参数：
summary-tool summary-tool http://10.22.193.246/AATS_XTS_REPORTS/2875P_ANR14/DB2302/20251130_667/ http://10.22.193.246/AATS_XTS_REPORTS/2875P_ANR14/DB2302/20251205_672/
- 会把667、672下面所有报告汇总，然后比对生成xts-diff_summary.html，双列显示

### 单列模式（单参数）
单列模式仅提供左侧路径（目录或 HTML 文件），工具会递归搜索 `test_result_failures_suite.html`（或首个 HTML）并生成单独的汇总报告。
```bash
# 左侧为本地目录，自动递归搜索子目录
python -m summary_tool.cli /path/to/left_root -s cts,gts -o xts_summary.html

# 左侧为远程 URL（目录）
python -m summary_tool.cli https://example.com/reports -r -o remote_summary.html
```
- `-s`：不指定之目录，就会递归搜索所有的子目录下的test_result_failures_suite.html。
- `-r/--recursive`：在单列模式下强制递归搜索（可选，默认若左路径是目录且包含目标文件也会递归）。
- 输出默认 `xts_summary.html`（未指定 `-o` 时）。

### 双列模式（双参数）
双列模式同时提供左、右路径，用于两套报告的对比，生成差异报告。
```bash
# 本地目录对比
python -m summary_tool.cli /path/to/left_root /path/to/right_root -s cts,gts -o xts-diff_summary.html

# 本地文件对比（单个子目录）
python -m summary_tool.cli /path/to/left.html /path/to/right.html -o diff.html

# 远程 URL 对比
python -m summary_tool.cli https://example.com/left https://example.com/right -s sts -o remote_diff.html
```
- `-s`：不指定之目录，就会递归搜索所有的子目录下的test_result_failures_suite.html。
- 输出默认 `xts-diff_summary.html`（未指定 `-o` 时）。
- 若只提供左侧路径，则进入单列模式，上述示例可省略右侧参数。

### 使用已安装的 CLI 命令（若已执行 `pip install -e .`）
```bash
summary-tool -a path/to/first -b path/to/second -o reports
```

运行后会在指定的输出目录生成以下文件，
默认缓存文件输出目录tmp_diff_reports：
- `*_1.html`、`*_2.html`：原始文本的 HTML 展示
- `*-diff.html`：对比后的差异报告
项目根目录：
- `xts_summary.html`、`xts-diff_summary.html`：整体汇总页面

---

## 常见错误及解决办法
| 错误信息                     | 可能原因                         | 解决方案 |
|----------------------------|--------------------------------|----------|
| `ModuleNotFoundError: No module named 'xxx'` | 依赖未安装或虚拟环境不匹配 | 确认已在当前环境执行 `pip install -r requirements.txt`，或使用 `python -m venv venv && source venv/bin/activate` 再安装。 |
| `FileNotFoundError: [Errno 2] No such file or directory` | 提供的路径不存在或拼写错误 | 检查 `--source-a`、`--source-b` 参数，确保路径正确且文件可读。 |
| `UnicodeDecodeError` | 输入文件编码不是 UTF-8 | 在 `extractor.py` 中添加 `encoding='utf-8'`，或先将文件转换为 UTF-8 编码。 |
| `git status` 报 “detected dubious ownership” | 在容器中挂载的目录所有权不被 Git 认可 | 执行 `git config --global --add safe.directory <repo_path>`（已在项目根目录做过此设置）。 |
| 空的 diff 报告 | 两个输入的内容完全相同或提取阶段出错 | 打印 `extractor` 的日志（`utils.py` 中的 `logger`），确认文本已被正确读取。 |

---

## 开发 & 贡献

Continue CLI
