opencode-hashline 1.2.0 → 1.3.1

package/README.en.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<img src="banner.jpg" alt="opencode-hashline banner" width="100%" />
+
 # 🔗 opencode-hashline
 
 **Content-addressable line hashing for precise AI code editing**
@@ -61,7 +63,6 @@ Hash length automatically adapts to file size to minimize collisions:
 
 | File Size | Hash Length | Possible Values |
 |-----------|:----------:|:---------------:|
-| ≤ 256 lines | 2 hex chars | 256 |
 | ≤ 4,096 lines | 3 hex chars | 4,096 |
 | > 4,096 lines | 4 hex chars | 65,536 |
 
@@ -94,7 +95,7 @@ Built-in LRU cache (`filePath → annotatedContent`) with configurable size (def
 Verify that a line hasn't changed since it was read — protects against race conditions:
 
 ```typescript
-import { verifyHash } from "opencode-hashline";
+import { verifyHash } from "opencode-hashline/utils";
 
 const result = verifyHash(2, "f1c", currentContent);
 if (!result.valid) {
@@ -104,6 +105,49 @@ if (!result.valid) {
 
 Hash verification uses the length of the provided hash reference (not the current file size), so a reference like `2:f1` remains valid even if the file has grown.
 
+### 🔒 File Revision (`fileRev`)
+
+In addition to per-line hashes, hashline computes a whole-file hash (FNV-1a, 8 hex chars). It's prepended as the first annotation line:
+
+```
+#HL REV:72c4946c
+#HL 1:a3f|function hello() {
+#HL 2:f1c|  return "world";
+```
+
+Pass `fileRev` to `hashline_edit` when editing — if the file changed since it was read, the edit is rejected with `FILE_REV_MISMATCH`.
+
+### 🔄 Safe Reapply
+
+If a line moved (e.g., due to insertions above), `safeReapply` finds it by content hash:
+
+- **1 candidate** — edit applies at the new position
+- **>1 candidates** — `AMBIGUOUS_REAPPLY` error (ambiguous)
+- **0 candidates** — `HASH_MISMATCH` error
+
+```typescript
+const result = applyHashEdit(
+  { operation: "replace", startRef: "1:a3f", replacement: "new" },
+  content,
+  undefined,
+  true, // safeReapply
+);
+```
+
+### 🏷️ Structured Errors
+
+All hashline errors are instances of `HashlineError` with error codes, diagnostics, and hints:
+
+| Code | Description |
+|------|-------------|
+| `HASH_MISMATCH` | Line content changed since last read |
+| `FILE_REV_MISMATCH` | File was modified since last read |
+| `AMBIGUOUS_REAPPLY` | Multiple candidates found during safe reapply |
+| `TARGET_OUT_OF_RANGE` | Line number exceeds file length |
+| `INVALID_REF` | Malformed hash reference |
+| `INVALID_RANGE` | Start line is after end line |
+| `MISSING_REPLACEMENT` | Replace/insert operation without content |
+
 ### 🔍 Indentation-Sensitive Hashing
 
 Hash computation uses `trimEnd()` (not `trim()`), so changes to leading whitespace (indentation) are detected as content changes, while trailing whitespace is ignored.
@@ -113,7 +157,7 @@ Hash computation uses `trimEnd()` (not `trim()`), so changes to leading whitespa
 Resolve and replace ranges of lines by hash references:
 
 ```typescript
-import { resolveRange, replaceRange } from "opencode-hashline";
+import { resolveRange, replaceRange } from "opencode-hashline/utils";
 
 // Get lines between two hash references
 const range = resolveRange("1:a3f", "3:0e7", content);
@@ -131,7 +175,7 @@ const newContent = replaceRange(
 Create custom Hashline instances with specific settings:
 
 ```typescript
-import { createHashline } from "opencode-hashline";
+import { createHashline } from "opencode-hashline/utils";
 
 const hl = createHashline({
   exclude: ["**/node_modules/**", "**/*.min.js"],
@@ -151,10 +195,12 @@ const isExcluded = hl.shouldExclude("node_modules/foo.js"); // true
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `exclude` | `string[]` | See below | Glob patterns for files to skip |
-| `maxFileSize` | `number` | `1_000_000` | Max file size in bytes |
+| `maxFileSize` | `number` | `1_048_576` (1 MB) | Max file size in bytes |
 | `hashLength` | `number \| undefined` | `undefined` (adaptive) | Force specific hash length |
 | `cacheSize` | `number` | `100` | Max files in LRU cache |
 | `prefix` | `string \| false` | `"#HL "` | Line prefix (`false` to disable) |
+| `fileRev` | `boolean` | `true` | Include file revision hash (`#HL REV:...`) in annotations |
+| `safeReapply` | `boolean` | `false` | Auto-relocate moved lines by content hash |
 
 Default exclude patterns cover: lock files, `node_modules`, minified files, binary files (images, fonts, archives, etc.).
 
@@ -257,7 +303,7 @@ The plugin needs to determine which tools are "file-read" tools (to annotate the
 The `isFileReadTool()` function is exported for testing and advanced usage:
 
 ```typescript
-import { isFileReadTool } from "opencode-hashline";
+import { isFileReadTool } from "opencode-hashline/utils";
 
 isFileReadTool("read_file");                          // true
 isFileReadTool("mcp.read");                           // true
@@ -442,9 +488,12 @@ The idea behind hashline is inspired by concepts from **oh-my-pi** by [can1357](
 
 Hashline solves this by assigning each line a short, deterministic hash tag (e.g. `2:f1c`), making line addressing **exact and unambiguous**. The model can reference any line or range precisely, eliminating off-by-one errors and duplicate-line confusion.
 
+The advanced features — **file revision** (`fileRev`), **safe reapply**, and **structured errors** — are inspired by the hash-based editing implementation in **AssistAgents** by [OzeroHAX](https://github.com/OzeroHAX/AssistAgents), which independently applied a similar approach for OpenCode with additional integrity checks and error diagnostics.
+
 **References:**
 - [oh-my-pi by can1357](https://github.com/can1357/oh-my-pi) — AI coding agent toolkit: coding agent CLI, unified LLM API, TUI libraries
 - [The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) — blog post describing the problem in detail
+- [AssistAgents by OzeroHAX](https://github.com/OzeroHAX/AssistAgents) — hash-based editing for OpenCode with file revision, safe reapply, and structured conflicts
 - [Описание подхода на Хабре](https://habr.com/ru/companies/bothub/news/995986/) — overview of the approach in Russian
 
 ---

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<img src="banner.jpg" alt="opencode-hashline banner" width="100%" />
+
 # 🔗 opencode-hashline
 
 **Контентно-адресуемое хеширование строк для точного редактирования кода с помощью AI**
@@ -34,7 +36,7 @@ Hashline аннотирует каждую строку файла коротк
 #HL 3:0e7|}
 ```
 
-> **Примечание:** Длина хеша адаптивная — она зависит от размера файла (2 символа для ≤256 строк, 3 символа для ≤4096 строк, 4 символа для >4096 строк). В примерах ниже используются 3-символьные хеши. Префикс `#HL ` защищает от ложных срабатываний при удалении хешей и является настраиваемым.
+> **Примечание:** Длина хеша адаптивная — она зависит от размера файла (3 символа для ≤4096 строк, 4 символа для >4096 строк). Минимальная длина хеша — 3 символа. В примерах ниже используются 3-символьные хеши. Префикс `#HL ` защищает от ложных срабатываний при удалении хешей и является настраиваемым.
 
 AI-модель может ссылаться на строки по их хеш-тегам для точного редактирования:
 
@@ -61,7 +63,6 @@ Hashline адресует каждую строку уникальным хеш
 
 | Размер файла | Длина хеша | Возможных значений |
 |-------------|:----------:|:------------------:|
-| ≤ 256 строк | 2 hex-символа | 256 |
 | ≤ 4 096 строк | 3 hex-символа | 4 096 |
 | > 4 096 строк | 4 hex-символа | 65 536 |
 
@@ -94,7 +95,7 @@ const hl = createHashline({ prefix: false });
 Проверка того, что строка не изменилась с момента чтения — защита от race conditions:
 
 ```typescript
-import { verifyHash } from "opencode-hashline";
+import { verifyHash } from "opencode-hashline/utils";
 
 const result = verifyHash(2, "f1c", currentContent);
 if (!result.valid) {
@@ -104,6 +105,49 @@ if (!result.valid) {
 
 Верификация хешей использует длину предоставленной хеш-ссылки (а не текущий размер файла), поэтому ссылка вроде `2:f1` остаётся валидной даже если файл вырос.
 
+### 🔒 Ревизия файла (`fileRev`)
+
+Помимо построчных хешей, hashline вычисляет хеш всего файла (FNV-1a, 8 hex-символов). Он добавляется первой строкой аннотации:
+
+```
+#HL REV:72c4946c
+#HL 1:a3f|function hello() {
+#HL 2:f1c|  return "world";
+```
+
+При редактировании передайте `fileRev` в `hashline_edit` — если файл изменился с момента чтения, правка будет отклонена с ошибкой `FILE_REV_MISMATCH`.
+
+### 🔄 Safe Reapply
+
+Если строка переместилась (например, из-за вставки строк выше), `safeReapply` находит её по хешу контента:
+
+- **1 кандидат** — правка применяется к новой позиции
+- **>1 кандидатов** — ошибка `AMBIGUOUS_REAPPLY` (неоднозначность)
+- **0 кандидатов** — ошибка `HASH_MISMATCH`
+
+```typescript
+const result = applyHashEdit(
+  { operation: "replace", startRef: "1:a3f", replacement: "new" },
+  content,
+  undefined,
+  true, // safeReapply
+);
+```
+
+### 🏷️ Structured Errors
+
+Все ошибки hashline — экземпляры `HashlineError` с кодом, диагностикой и подсказками:
+
+| Код | Описание |
+|-----|----------|
+| `HASH_MISMATCH` | Содержимое строки изменилось |
+| `FILE_REV_MISMATCH` | Файл модифицирован с момента чтения |
+| `AMBIGUOUS_REAPPLY` | Несколько кандидатов при safe reapply |
+| `TARGET_OUT_OF_RANGE` | Номер строки за пределами файла |
+| `INVALID_REF` | Некорректная хеш-ссылка |
+| `INVALID_RANGE` | Начало диапазона после конца |
+| `MISSING_REPLACEMENT` | Операция replace/insert без содержимого |
+
 ### 🔍 Чувствительность к отступам
 
 Вычисление хеша использует `trimEnd()` (а не `trim()`), поэтому изменения ведущих пробелов (отступов) обнаруживаются как изменения содержимого, а завершающие пробелы игнорируются.
@@ -113,7 +157,7 @@ if (!result.valid) {
 Резолвинг и замена диапазонов строк по хеш-ссылкам:
 
 ```typescript
-import { resolveRange, replaceRange } from "opencode-hashline";
+import { resolveRange, replaceRange } from "opencode-hashline/utils";
 
 // Получить строки между двумя хеш-ссылками
 const range = resolveRange("1:a3f", "3:0e7", content);
@@ -131,7 +175,7 @@ const newContent = replaceRange(
 Создание кастомных экземпляров Hashline с определёнными настройками:
 
 ```typescript
-import { createHashline } from "opencode-hashline";
+import { createHashline } from "opencode-hashline/utils";
 
 const hl = createHashline({
   exclude: ["**/node_modules/**", "**/*.min.js"],
@@ -151,10 +195,12 @@ const isExcluded = hl.shouldExclude("node_modules/foo.js"); // true
 | Параметр | Тип | По умолчанию | Описание |
 |----------|-----|:------------:|----------|
 | `exclude` | `string[]` | См. ниже | Glob-паттерны для исключения файлов |
-| `maxFileSize` | `number` | `1_000_000` | Макс. размер файла в байтах |
+| `maxFileSize` | `number` | `1_048_576` (1 МБ) | Макс. размер файла в байтах |
 | `hashLength` | `number \| undefined` | `undefined` (адаптивно) | Принудительная длина хеша |
 | `cacheSize` | `number` | `100` | Макс. файлов в LRU-кеше |
 | `prefix` | `string \| false` | `"#HL "` | Префикс строки (`false` для отключения) |
+| `fileRev` | `boolean` | `true` | Включать ревизию файла (`#HL REV:...`) в аннотации |
+| `safeReapply` | `boolean` | `false` | Автоматический поиск перемещённых строк по хешу |
 
 Паттерны исключения по умолчанию: lock-файлы, `node_modules`, минифицированные файлы, бинарные файлы (изображения, шрифты, архивы и т.д.).
 
@@ -417,9 +463,12 @@ npm run typecheck
 
 Hashline решает эту проблему, присваивая каждой строке короткий детерминированный хеш-тег (например, `2:f1c`), что делает адресацию строк **точной и однозначной**. Модель может ссылаться на любую строку или диапазон без ошибок смещения и путаницы с дубликатами.
 
+Продвинутые фичи — **ревизия файла** (`fileRev`), **safe reapply** и **structured errors** — вдохновлены реализацией hash-based editing в проекте **AssistAgents** от [OzeroHAX](https://github.com/OzeroHAX/AssistAgents), который независимо применил аналогичный подход для OpenCode с дополнительными механизмами проверки целостности и диагностики ошибок.
+
 **Ссылки:**
 - [oh-my-pi от can1357](https://github.com/can1357/oh-my-pi) — AI-тулкит для разработки: coding agent CLI, unified LLM API, TUI-библиотеки
 - [The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) — блог-пост с подробным описанием проблемы
+- [AssistAgents от OzeroHAX](https://github.com/OzeroHAX/AssistAgents) — hash-based editing для OpenCode с file revision, safe reapply и structured conflicts
 - [Статья на Хабре](https://habr.com/ru/companies/bothub/news/995986/) — описание подхода на русском языке
 
 ---

package/README.ru.md

@@ -34,7 +34,7 @@ Hashline аннотирует каждую строку файла коротк
 #HL 3:0e7|}
 ```
 
-> **Примечание:** Длина хеша адаптивная — она зависит от размера файла (2 символа для ≤256 строк, 3 символа для ≤4096 строк, 4 символа для >4096 строк). В примерах ниже используются 3-символьные хеши. Префикс `#HL ` защищает от ложных срабатываний при удалении хешей и является настраиваемым.
+> **Примечание:** Длина хеша адаптивная — она зависит от размера файла (3 символа для ≤4096 строк, 4 символа для >4096 строк). Минимальная длина хеша — 3 символа. В примерах ниже используются 3-символьные хеши. Префикс `#HL ` защищает от ложных срабатываний при удалении хешей и является настраиваемым.
 
 AI-модель может ссылаться на строки по их хеш-тегам для точного редактирования:
 
@@ -56,7 +56,6 @@ AI-модель может ссылаться на строки по их хеш
 
 | Размер файла | Длина хеша | Возможных значений |
 |-------------|:----------:|:------------------:|
-| ≤ 256 строк | 2 hex-символа | 256 |
 | ≤ 4 096 строк | 3 hex-символа | 4 096 |
 | > 4 096 строк | 4 hex-символа | 65 536 |
 
@@ -89,7 +88,7 @@ const hl = createHashline({ prefix: false });
 Проверка того, что строка не изменилась с момента чтения — защита от race conditions:
 
 ```typescript
-import { verifyHash } from "opencode-hashline";
+import { verifyHash } from "opencode-hashline/utils";
 
 const result = verifyHash(2, "f1c", currentContent);
 if (!result.valid) {
@@ -108,7 +107,7 @@ if (!result.valid) {
 Резолвинг и замена диапазонов строк по хеш-ссылкам:
 
 ```typescript
-import { resolveRange, replaceRange } from "opencode-hashline";
+import { resolveRange, replaceRange } from "opencode-hashline/utils";
 
 // Получить строки между двумя хеш-ссылками
 const range = resolveRange("1:a3f", "3:0e7", content);
@@ -126,7 +125,7 @@ const newContent = replaceRange(
 Создание кастомных экземпляров Hashline с определёнными настройками:
 
 ```typescript
-import { createHashline } from "opencode-hashline";
+import { createHashline } from "opencode-hashline/utils";
 
 const hl = createHashline({
   exclude: ["**/node_modules/**", "**/*.min.js"],
@@ -146,10 +145,12 @@ const isExcluded = hl.shouldExclude("node_modules/foo.js"); // true
 | Параметр | Тип | По умолчанию | Описание |
 |----------|-----|:------------:|----------|
 | `exclude` | `string[]` | См. ниже | Glob-паттерны для исключения файлов |
-| `maxFileSize` | `number` | `1_000_000` | Макс. размер файла в байтах |
+| `maxFileSize` | `number` | `1_048_576` (1 МБ) | Макс. размер файла в байтах |
 | `hashLength` | `number \| undefined` | `undefined` (адаптивно) | Принудительная длина хеша |
 | `cacheSize` | `number` | `100` | Макс. файлов в LRU-кеше |
 | `prefix` | `string \| false` | `"#HL "` | Префикс строки (`false` для отключения) |
+| `fileRev` | `boolean` | `true` | Включать ревизию файла (`#HL REV:...`) в аннотации |
+| `safeReapply` | `boolean` | `false` | Автоматический поиск перемещённых строк по хешу |
 
 Паттерны исключения по умолчанию: lock-файлы, `node_modules`, минифицированные файлы, бинарные файлы (изображения, шрифты, архивы и т.д.).