Metadata-Version: 2.4
Name: diffino-cli
Version: 0.5.1
Summary: Declarative diff & text-correction toolkit for tables and documents, powered by Polars. Output Excel, HTML, Typst PDF, DOCX track-changes and cumulative changelogs. 声明式数据差异对比与文本校对工具包（Excel/CSV/Parquet/DuckDB/DOCX，输出 Excel/HTML/Typst PDF/DOCX 修订/累积变更日志）。
License-Expression: MIT
Project-URL: Repository, https://codeberg.org/songwupei/diffino
Keywords: diff,comparison,correction,proofread,changelog,excel,csv,polars,openpyxl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: polars>=0.20.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.9.0
Requires-Dist: duckdb>=0.10.0
Requires-Dist: python-docx>=1.1.0
Dynamic: license-file

# diffino

[![PyPI version](https://img.shields.io/badge/pypi-0.5.1-blue)](https://pypi.org/project/diffino-cli/)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)

> **Declarative data diff & text-correction toolkit for tables and documents, powered by Polars.**
> **声明式数据差异对比与文本校对工具包（表与文档），基于 Polars。**
> Compare Excel, CSV, Parquet, DuckDB, or DOCX files and generate detailed reports with character-level inline diffs — plus a reusable text-correction backend (`diffino.correction`).
> 对比 Excel、CSV、Parquet、DuckDB、DOCX，输出带字符级行内差异的详细报告；并提供可复用的文本校对后端（`diffino.correction`）。

Output formats / 输出格式：**Excel**、**HTML**、**Typst PDF**、**DOCX track-changes / DOCX 修订**、**Changelog / 累积变更日志**。

## What's New / 版本更新（v0.5.0 · 2026-09-03）

- **Text-correction backend / 文本校对后端（`diffino.correction`，CorrectBackend）**：新增纯 Python/Polars 校对后端，面向“表格/文档文本修订评审”场景：
  - **decisions 载入与迁移 / Load & migration**：读取评审 decisions（accept/ignore），源内容变化后按关键字段自动继承旧 accept；
  - **歧义预检 / Ambiguity preflight**：原文在单元格内出现多次时标记 ambiguous，永不自动误改（全局替换通道除外）；
  - **V1 / V2 版本生成 / Version generation**：V1 = 仅人工认可（accept + 高置信通道），V2 = 全建议预览（低置信通道可配置排除）；
  - **重叠合并与冲突清单 / Merge & conflicts**：同位置多条建议按“模拟结果一致”合并，不一致写入冲突清单等待人工裁决，冲突不自动应用；
  - **清单与统计 / Manifest & type summary**：版本清单（manifest）与按类型摘要（应用/歧义/已覆盖/合并/冲突/可疑）全量留痕；
- **Domain-neutral core / 领域无关核心**：输入列名与通道语义（全局替换通道、漏检补充通道、合并优先级等）经 `CorrectionSchema` 注入，默认英文列名开箱即用，核心不硬编码任何领域列名；中文等任意领域只需自定义 schema；
- **Composable API / 可组合**：不依赖 CLI 与 Kedro，可直接 import 组合进评审流程，并能与 diffino 的版本差异报告（V1/V2 → diff.pdf）天然衔接。

> 说明：v0.5.0a1 为同批实验性预发布；本版为正式发布，功能与 a1 一致。

## Installation / 安装

```bash
pip install diffino-cli
```

For development / 开发模式：

```bash
pip install -e ".[dev]"
```

## Quick Start / 快速开始

1. Prepare a config file / 准备配置文件：

```yaml
sources:
  left:
    type: excel
    path: data/v0.2.5.xlsx
  right:
    type: excel
    path: data/v0.2.6.xlsx
    version: "0.2.6"

compare:
  - left_sheet: Sheet1
    key_columns:
      - ID
    ignore_columns:
      - Notes

output:
  project: 我的项目
  formats:
    - excel
    - changelog
  changelog:
    split: true
  report_dir: ./diffs
```

2. Run diffino / 运行对比：

```bash
diffino run config.yaml
```

3. Or generate a changelog from saved reports / 或从已保存报告生成变更日志：

```bash
diffino changelog generate --input-dir ./diffs --releases releases.yaml --split
```

### Text correction / 文本校对（v0.5.0 新增）

`diffino.correction` 是一个纯 Python/Polars 后端，不依赖 CLI。以英文列名
`CorrectionSchema` 为例，生成 V1/V2 版本：

```python
import polars as pl
from diffino.correction import CorrectionSchema, make_v1, make_v2

schema = CorrectionSchema.english()   # 列名: rule_code/column/original/suggestion/type/decision/note
source = pl.read_csv("rules.csv")
decisions = pl.read_csv("decisions.csv")   # 人工评审产物（accept/ignore）

v1, applied1 = make_v1(source, decisions, force_accept_types=("review",), cschema=schema)
v2, applied2, pending = make_v2(source, decisions, exclude_types=("low_precision",), cschema=schema)
```

领域（如中文列名 + 全局替换通道/合并优先级）由调用方提供自己的 `CorrectionSchema`
并注入，核心代码零领域硬编码。

## Features / 功能

- **Multi-format sources / 多格式数据源**：Excel、CSV、Parquet、DuckDB、DOCX
- **Key-based or fingerprint matching / 键或指纹匹配**：复合键或整行哈希进行行匹配
- **Column preprocessing / 列预处理**：小数舍入、文本归一化、日期格式归一化、百分比换算
- **Character-level inline diff / 字符级行内差异**：删除内容红色删除线、新增内容绿色加粗
- **DOCX paragraph diff / DOCX 段落对比**：正文逐段对比并输出行内差异
- **Text-correction backend / 文本校对后端（v0.5.0）**：decisions 迁移 / 歧义预检 /
  V1/V2 生成 / 重叠合并与冲突清单 / manifest / 按类型摘要（`diffino.correction`）
- **Six output formats / 六种输出格式**：
  - **Excel**：新旧行并排、变更单元格黄色高亮、富文本行内差异；`final` / `side_by_side` / `track` 样式
  - **HTML**：自包含报告，`<del>`/`<ins>` 标签 + JS 过滤
  - **Typst**：带封面、彩色表格与字符级行内差异的 Typst PDF
  - **DOCX track-changes / DOCX 修订**：原生 Word 修订跟踪（`<w:ins>`/`<w:del>`）——DOCX 源就地输出，其他源生成对照表
  - **Changelog / 变更日志**：累积变更日志 Typst 文件（`_summary.typ` + `_detail.typ`），随每次运行自动生成并汇总同目录历史报告
  - **json-summary / JSON 摘要**：供 CI/CD 消费的结构化摘要
- **Typst cover page / Typst 封面**：可配置项目名——`{{PROJECT}}对比报告`
- **DiffReport persistence / 报告持久化**：自动保存 JSON 报告（`{old}__{new}.json`）供日志累积
- **Version auto-detection / 版本自动识别**：解析 `name-vX.Y.Z.ext`，也可在 YAML 中手动指定
- **Changelog generation / 变更日志生成**：`diffino changelog generate`——版本汇总表 + 逐版本明细，`--split` 拆分摘要/明细
- **Release date config / 发布日期配置**：`releases.yaml` 或内联配置映射版本→日期
- **Parallel processing / 并行处理**：ThreadPoolExecutor + 可配 `max_workers`，支持多 Sheet 并行
- **CI/CD integration / CI/CD 集成**：`--fail-on-diff` 退出码、`--summary` Markdown 表、`json-summary` 供流水线消费

## CLI Commands / CLI 命令

### `diffino run`

```bash
diffino run config.yaml                 # 运行对比 / Run comparison
diffino run config.yaml --fail-on-diff  # 有差异则退出码 1 / Exit 1 if differences found
diffino run config.yaml --summary       # 输出 Markdown 摘要到 stdout
diffino run config.yaml --summary --summary-detail  # 含单元格级明细
```

在 `output.formats` 加入 `changelog`，每次运行自动生成累积变更日志：

```yaml
output:
  formats:
    - excel
    - changelog        # 自动生成 changelog_summary.typ + changelog_detail.typ
  changelog:
    path: changelog.typ     # 默认 / default
    split: true             # 默认 / default: true
    summary_keep: 3         # 默认 / default: 3
    max_summary_items: 3    # 默认 / default: 3
    releases: releases.yaml # 发布日期配置
```

`formats` 含 `changelog` 时 `save_report` 自动开启——DiffReport JSON 总会被保存。

### `diffino validate`

```bash
diffino validate config.yaml    # 仅校验配置 / Validate config only
```

### `diffino changelog generate`

```bash
diffino changelog generate                # 生成 changelog.typ
  --input-dir ./diffs                     #   diff JSON 目录
  --output changelog.typ                  #   输出 Typst 文件
  --releases releases.yaml                #   发布日期配置
  --summary-keep 3                        #   摘要展示版本数（默认 3）
  --max-summary-items 3                   #   每版本条目数上限（默认 3）
  --split                                 #   拆分为 _summary.typ + _detail.typ
```

## Source Types / 数据源类型

| Type / 类型 | Key config fields / 关键配置字段 |
|---|---|
| `excel` | `path` |
| `csv` | `path` |
| `parquet` | `path` |
| `duckdb` | `database`, `query` |
| `docx` | `path` |

### DOCX mode / DOCX 模式

`sources.*.type = docx` 时，Sheet 按表格标题匹配（精确 / 模糊 / 1-based 序号）。
在对比单元里设 `content: paragraphs` 可对比文档正文而不是表格：

```yaml
compare:
  # 按表格标题对比 / Table diff by caption
  - left_sheet: 表1-客户列表
    key_columns:
      - 客户ID
  # 正文段落对比 / Paragraph diff
  - content: paragraphs
```

## Configuration Reference / 配置参考

完整示例见 `config.example.yaml`。

| Section / 配置段 | Field / 字段 | Description / 说明 |
|---|---|---|
| `sources.left/right` | `type` | 数据源类型：`excel` / `csv` / `parquet` / `duckdb` / `docx` |
| `sources.left/right` | `version` | 手动版本覆盖（默认从文件名解析） |
| `compare[]` | `left_sheet` / `right_sheet` | Sheet 名（或 DOCX 表格标题）；`right_sheet` 默认等于 `left_sheet` |
| `compare[]` | `content` | 设为 `paragraphs` 时对比 DOCX 正文 |
| `compare[]` | `key_columns` | 行匹配用列名 |
| `compare[]` | `fingerprint` | 用整行哈希代替键列匹配 |
| `compare[]` | `ignore_columns` | 不参与对比的列 |
| `compare[]` | `column_rules` | 预处理规则（`decimal` / `text` / `date` / `percentage`） |
| `compare[]` | `label` | 对比单元的可读名称 |
| `output` | `project` | Typst 封面项目名（默认 `数据`） |
| `output` | `title` | 报告标题（默认 `更新说明`） |
| `output` | `formats` | 可选：`excel` / `html` / `typst` / `docx_track` / `changelog` / `json-summary` |
| `output` | `save_report` | 持久化 DiffReport JSON 供变更日志使用 |
| `output` | `report_dir` | 报告保存目录（默认 `./diffs`） |
| `output` | `max_workers` | 线程池大小（默认 4） |
| `output` | `release_date` | 覆盖发布日期（ISO 格式） |
| `output` | `releases` | 内联 releases 配置（替代文件） |
| `output.excel` | `path` | Excel 输出路径 |
| `output.excel` | `style` | `track` / `final` / `side_by_side` |
| `output.html` | `path` | HTML 输出路径 |
| `output.typst` | `path` | Typst 输出路径 |
| `output.typst` | `template` | 自定义 Typst 模板路径 |
| `output.docx_track` | `path` | DOCX 输出路径 |
| `output.changelog` | `path` | 变更日志 Typst 路径（默认 `changelog.typ`） |
| `output.changelog` | `split` | 拆分为 `_summary.typ` + `_detail.typ`（默认 `true`） |
| `output.changelog` | `summary_keep` | 摘要表展示的版本数（默认 3） |
| `output.changelog` | `max_summary_items` | 每版本最大条目数（默认 3） |
| `output.changelog` | `releases` | releases 配置路径（默认 `releases.yaml`） |

### Column preprocessing rules / 列预处理规则

```yaml
column_rules:
  - column: 金额
    type: decimal
    precision: 2
  - column: 名称
    type: text
    normalize_whitespace: true
    case_sensitive: false
  - column: 发布日期
    type: date
    format: "%Y-%m-%d"
    input_format: "%Y/%m/%d"   # 可选 / optional
  - column: 增长率
    type: percentage
    precision: 2
```

### Releases config / 发布日期配置（`releases.yaml`）

支持两种格式：

**带项目名（推荐）/ With project name (recommended)**：

```yaml
name: 穿透监管规则明细表
releases:
  - version: "v1.0"
    date: 2026-02-13
  - version: "v1.1"
    date: 2026-05-19
```

**旧版扁平列表 / Legacy flat list**：

```yaml
releases:
  - version: "0.2.5"
    date: 2026-05-19
  - version: "0.2.6"
    date: 2026-05-20
```

releases 也可以内联写在主配置的 `output.releases` 下。

## Changelog / 变更日志

### 通过 `diffino run`（推荐 / recommended）

在 `output.formats` 加 `changelog`。DiffReport JSON 自动保存到 `output.report_dir`
（默认 `./diffs`）并命名为 `{old_version}__{new_version}.json`。每次运行后，该目录下
所有 JSON 报告会被加载，生成累积 `changelog_summary.typ` + `changelog_detail.typ`。

```yaml
output:
  formats:
    - changelog
  changelog:
    split: true
```

### 独立生成 / Standalone：`diffino changelog generate`

```bash
diffino changelog generate --input-dir ./diffs --split
```

### 输出内容 / Changelog output

- **Summary / 摘要**（`_summary.typ`）：版本表——每个版本的日期与变更计数
- **Detail / 明细**（`_detail.typ`）：逐版本段落——每条新增/删除/修改行及新旧值行内差异

不传 `--split`（或配置 `split: false`）时输出单一 `changelog.typ`。

## Project Structure / 项目结构

```
├── src/diffino/
│   ├── comparator.py          # 行匹配与对比核心 | Row matching & comparison core
│   ├── loader.py              # 多格式数据加载 | Multi-format data loading
│   ├── preprocessor.py        # 列预处理 | Column preprocessing
│   ├── diff_model.py          # 差异数据模型 | Diff data model
│   ├── config.py              # 配置解析 | Config parsing
│   ├── correction/            # ★ 文本校对后端 CorrectBackend（v0.5.0）
│   │   ├── schema.py          #   CorrectionSchema（列映射/通道语义）
│   │   └── core.py            #   decisions/V1/V2/合并/冲突/manifest
│   ├── changelog/             # 累积变更日志 | Cumulative changelog
│   ├── renderers/             # Excel/HTML/Typst/DOCX 渲染器
│   ├── pdf/                   # PDF 提取与对比 | PDF extraction & compare
│   ├── docx_source.py         # DOCX 数据源 | DOCX source
│   └── main.py                # CLI（Typer）| CLI entry
├── config.example.yaml        # 配置示例 | Example config
└── pyproject.toml
```

## Recent Changes / 近期变更

### 2026-09-03 · v0.5.1（文档修订 / docs revision）

- README 中英双语化并完善 v0.5.0 `diffino.correction` 功能介绍（纯功能向，不依赖任何下游项目语境）；同步 PyPI 描述。

### 2026-09-03 · v0.5.0（正式发布 / formal release）

> 功能与 0.5.0a1 实验版一致；0.5.0a1 为同批预发布（PyPI 保留，仓库标签以 v0.5.0 为准）。

- **新增 `diffino.correction`（CorrectBackend / 文本校对后端）**：decisions 载入与迁移、歧义预检、V1/V2 版本生成、重叠建议合并与冲突清单、版本清单（manifest）与按类型摘要；输入列名与通道语义经 `CorrectionSchema` 注入（默认英文列名），核心不硬编码领域列名；
- 校对能力为纯 Python/Polars API，不依赖 CLI，可直接在评审工作流中组合使用。

### 2026-09-03 · v0.5.0a1（实验性预发布 / experimental pre-release）

- 与 v0.5.0 相同的 correction 后端能力（保留为发布历史）。

### 2026-05-22 · v0.4.1

- `diffino run` 支持 `changelog` 输出格式——每次运行自动生成累积
  `changelog_summary.typ` + `changelog_detail.typ`；
- Changelog 渲染器自动创建输出目录；README 重写（DOCX 源、段落差异、changelog 格式、
  完整配置参考）。

### 2026-05-21 · v0.4.0

- DOCX 源支持：按标题表格对比 + 正文段落对比；
- DOCX track-changes 渲染器（`docx_track`），原生 Word 修订跟踪。

### 2026-05-20 · v0.3.x

- Changelog 独立生成（`diffino changelog generate`）、Typst 封面、DiffReport JSON
  持久化、releases 版本→日期配置、键列归一化等。

### 2026-05-19 · v0.1.0–0.2.x

- 初版：Excel/CSV/Parquet 加载、键与指纹匹配、列预处理、Excel/HTML/Typst 输出、
  字符级行内差异、DuckDB 源、并行多 Sheet 处理、CI/CD 退出码与摘要。

## License / 许可证

MIT
