# textkit.diff · 文本对比

比较两个版本改了什么，不修改文件，不依赖 Git。直接在 Autos 中 `return` 结果表：

```aardio
import textkit.diff;
return textkit.diff.files(oldPath, newPath);
```

已有文本字符串时，调用 `textkit.diff(oldText, newText, options?)`；文件路径只传给 `textkit.diff.files(oldPath, newPath, options?)`。以下两个例子也说明如何指定选项：

```aardio
import textkit.diff;
// 内存文本，只看变动行。
return textkit.diff('var x = 1;\n', 'var x = 2;\n', {context=0});
```

```aardio
import textkit.diff;
// 比较打 Aider 补丁之前的备份和当前文件，生成 Unified Diff。
var r = textkit.diff.files(oldPath, newPath, {format="unified"; label="src/main.aardio"});
if(r.error) return r;
// 原样保存，以免编辑器把补丁行尾全部转换为 CRLF。
if(#r.diff) string.save("/change.patch", r.diff);
return r.summary;
```

## 格式和选项

| `options` 字段 | 用途 |
| --- | --- |
| `format` | `"autos"`（默认）用于查看；`"unified"` 用于生成标准补丁。 |
| `context` | 每侧上下文行数，默认 `3`。`0` 只显示改动。上下文相交或相接时合并块。 |
| `maxBytes` | 可选的 `diff` 字节预算。Autos 默认 `8000`，超出则截断，`0` 只看统计。Unified 默认不截断；显式设置预算且不足时返回 `error`，不会返回半个补丁。 |
| `label` | 仅用于 Unified。目标相对路径，如 `"src/main.aardio"`，分隔符用 `/`。两边的表头分别为 `a/<label>`、`b/<label>`。省略时 `.files` 用新文件的文件名，无目录；内存文本用 `text`。 |

### Autos：只看新文件的行号

```diff
@@ -120,3 +120,4 @@
120|var a = 1;
   -var b = 2;
121+var b = 20;
122+var c = 30;
123|return a + b;
```

`|` 是不变行，`+` 是新增行，`-` 是删除行。行号从 1 起，只对应第二个输入；要看旧文件行号，交换两参数。删除行用空格对齐，不显示行号。修饰符和正文之间没有额外空格。

预览把 CRLF、LF 和 CR 都视为换行，不因换行符种类不同而重复显示整份文件。**末尾有没有换行仍然算差异。** 单行正文最多显示 240 个字节，安全截在 UTF-8 字符边界；替换时尽量保留第一个差异附近。任意裁剪都会设置 `truncated=true`，但统计不受预览预算影响。这个格式不能用来打补丁。

### Unified：保留原始行尾

标准 `---`、`+++` 文件头和 `@@` 变更块。按 LF 分隔补丁记录，逐字节保留输入行里的 CR，没有末尾 LF 时写标准的 `\ No newline at end of file` 标记。只改变行尾也会生成补丁。没有差异时返回 `""`。用 `context=0` 时，`git apply` 需要 `--unidiff-zero`。

`.files` 的 Unified 补丁针对**去掉 BOM、解码后的 UTF-8 文本**，不描述编码或 BOM 的变化，不用于直接修改带 BOM 的原始文件。它比较的是同一目标的两个版本，不生成重命名或文件权限变更。

## 返回值

始终只返回一个表。失败有 `error` 和 `code`；文件读取或解码失败时，还可用 `side`（`"old"` / `"new"`）和 `path` 定位输入。成功没有 `error`，常用字段如下：

| 字段 | 含义 |
| --- | --- |
| `diff` | 所选格式的差异文本。为空也可能是仅编码/换行样式变化，或预览预算为零。 |
| `summary` | 简短摘要。 |
| `identical` | 原输入字节是否完全一致（包括 BOM、换行符）。 |
| `contentIdentical` | 解码后，忽略换行符种类，正文是否一致（末尾有无换行仍比较）。 |
| `added`、`removed`、`hunks` | 所选格式的新增行数、删除行数和完整块数。 |

有对应情况才返回额外字段：

- `charset`：文件有明确 BOM 时识别 `utf-8-sig`、`utf-16`（小端）、`utf-16be`（大端），转为 UTF-8。按 `旧->新` 报告，如 `"utf-8->utf-16be"`。两文件都没有 BOM 时按 UTF-8 读，不返回此字段；无编码参数，不猜测 ANSI。
- `eol`：换行样式摘要，如 `"CRLF->LF"`；当正文相同、两侧都是混合换行且分布变化时，报告 `"mixed->mixed"`。`none` 表示没有换行符。
- `trailingNewline`：`"added"` 或 `"removed"`，表示文件末尾换行的有无变化。
- `truncated`：Autos 预览有裁剪，不代表算法只计算了部分文件。
- `approximate`：差异太大或重复行太多，部分对齐退化为整块替换。操作仍能准确地从旧文本变成新文本；不保证最少增删行。

输入必须是有效文本（拒绝 NUL、非法 UTF-8 及畸形 UTF-16）。每个输入最多 16 MiB（原始字节及解码后），需要计算行差异时每侧最多 250,000 行。适合对比同一文件的版本，不支持二进制或目录。
