opencode-hashline 1.1.3 → 1.3.0

package/README.en.md

@@ -44,7 +44,12 @@ The AI model can then reference lines by their hash tags for precise editing:
 
 ### 🤔 Why does this help?
 
-Traditional line numbers shift as edits are made, causing off-by-one errors and stale references. Hashline tags are **content-addressable** — they're derived from both the line index and the line's content, so they serve as a stable, verifiable reference that the AI can use to communicate about code locations with precision.
+Hashline solves the fundamental problems of the two existing AI file-editing approaches:
+
+- **`str_replace`** requires an absolutely exact match of `old_string`. Any extra whitespace, wrong indentation, or duplicate lines in the file — and the edit fails with "String to replace not found". This is so common it has a [mega-thread of 27+ related issues on GitHub](https://github.com/anthropics/claude-code/issues).
+- **`apply_patch`** (unified diff) only works on models specifically trained for this format. On other models the results are catastrophic: Grok 4 fails **50.7%** of patches, GLM-4.7 fails **46.2%** ([source](https://habr.com/ru/companies/bothub/news/995986/)).
+
+Hashline addresses each line with a unique `lineNumber:hash`. No string matching, no model-specific training dependency — just precise, verifiable line addressing.
 
 ---
 
@@ -99,6 +104,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.
@@ -150,6 +198,8 @@ const isExcluded = hl.shouldExclude("node_modules/foo.js"); // true
 | `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.).
 
@@ -355,22 +405,25 @@ const hl = createHashline({ cacheSize: 50, hashLength: 3 });
 
 ## 📊 Benchmark
 
-### Correctness: hashline vs str_replace
+### Correctness: hashline vs str_replace vs apply_patch
 
-We tested both approaches on **60 fixtures from [react-edit-benchmark](https://github.com/can1357/oh-my-pi/tree/main/packages/react-edit-benchmark)** — mutated React source files with known bugs (flipped booleans, swapped operators, removed guard clauses, etc.):
+We tested all three approaches on **60 fixtures from [react-edit-benchmark](https://github.com/can1357/oh-my-pi/tree/main/packages/react-edit-benchmark)** — mutated React source files with known bugs (flipped booleans, swapped operators, removed guard clauses, etc.):
 
-| | hashline | str_replace |
-|---|:---:|:---:|
-| **Passed** | **60/60 (100%)** | 58/60 (96.7%) |
-| **Failed** | 0 | 2 |
-| **Ambiguous edits** | 0 | 4 |
+| | hashline | str_replace | apply_patch |
+|---|:---:|:---:|:---:|
+| **Passed** | **60/60 (100%)** | 58/60 (96.7%) | **60/60 (100%)** |
+| **Failed** | 0 | 2 | 0 |
+| **Ambiguous edits** | 0 | 4 | 0 |
 
-str_replace fails when the `old_string` appears multiple times in the file (e.g. repeated guard clauses, similar code blocks). Hashline addresses each line uniquely via `lineNumber:hash`, so ambiguity is impossible.
+`apply_patch` with context lines matches hashline's reliability — **when the model generates the patch correctly**. The key weakness of `apply_patch` is its dependency on model-specific training: models not trained on this format produce malformed diffs (missing context lines, wrong indentation), causing patch application to fail.
+
+`str_replace` fails when `old_string` appears multiple times in the file (repeated guard clauses, similar code blocks). Hashline addresses each line uniquely via `lineNumber:hash` — ambiguity is impossible and no model-specific format is required.
 
 ```bash
 # Run yourself:
-npx tsx benchmark/run.ts              # hashline mode
-npx tsx benchmark/run.ts --no-hash    # str_replace mode
+npx tsx benchmark/run.ts               # hashline mode
+npx tsx benchmark/run.ts --no-hash     # str_replace mode
+npx tsx benchmark/run.ts --apply-patch # apply_patch mode
 ```
 
 <details>
@@ -434,9 +487,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

@@ -44,7 +44,12 @@ AI-модель может ссылаться на строки по их хеш
 
 ### 🤔 Почему это помогает?
 
-Традиционные номера строк сдвигаются при редактировании, вызывая ошибки смещения и устаревшие ссылки. Хеш-теги Hashline **контентно-адресуемы** — они вычисляются из индекса строки и её содержимого, что делает их стабильной, верифицируемой ссылкой для точной коммуникации о местоположении в коде.
+Hashline решает фундаментальные проблемы двух существующих подходов к редактированию файлов AI:
+
+- **`str_replace`** требует абсолютно точного совпадения `old_string`. Любой лишний пробел, неверный отступ или дублирующиеся строки в файле — и редактирование завершается ошибкой «String to replace not found». Это настолько распространённая проблема, что у неё есть [мегатред на 27+ тикетов на GitHub](https://github.com/anthropics/claude-code/issues).
+- **`apply_patch`** (unified diff) работает только на моделях, специально обученных этому формату. На других моделях результаты катастрофические: Grok 4 проваливает **50.7%** патчей, GLM-4.7 — **46.2%** ([источник](https://habr.com/ru/companies/bothub/news/995986/)).
+
+Hashline адресует каждую строку уникальным хешем `lineNumber:hash`. Никакого строкового совпадения, никакой зависимости от специального обучения модели — только точная, верифицируемая адресация.
 
 ---
 
@@ -99,6 +104,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()`), поэтому изменения ведущих пробелов (отступов) обнаруживаются как изменения содержимого, а завершающие пробелы игнорируются.
@@ -150,6 +198,8 @@ const isExcluded = hl.shouldExclude("node_modules/foo.js"); // true
 | `hashLength` | `number \| undefined` | `undefined` (адаптивно) | Принудительная длина хеша |
 | `cacheSize` | `number` | `100` | Макс. файлов в LRU-кеше |
 | `prefix` | `string \| false` | `"#HL "` | Префикс строки (`false` для отключения) |
+| `fileRev` | `boolean` | `true` | Включать ревизию файла (`#HL REV:...`) в аннотации |
+| `safeReapply` | `boolean` | `false` | Автоматический поиск перемещённых строк по хешу |
 
 Паттерны исключения по умолчанию: lock-файлы, `node_modules`, минифицированные файлы, бинарные файлы (изображения, шрифты, архивы и т.д.).
 
@@ -330,22 +380,25 @@ const hl = createHashline({ cacheSize: 50, hashLength: 3 });
 
 ## 📊 Бенчмарк
 
-### Корректность: hashline vs str_replace
+### Корректность: hashline vs str_replace vs apply_patch
 
-Оба подхода протестированы на **60 фикстурах из [react-edit-benchmark](https://github.com/can1357/oh-my-pi/tree/main/packages/react-edit-benchmark)** — мутированных файлах React с известными багами (инвертированные булевы, перепутанные операторы, удалённые guard-клаузы и т.д.):
+Все три подхода протестированы на **60 фикстурах из [react-edit-benchmark](https://github.com/can1357/oh-my-pi/tree/main/packages/react-edit-benchmark)** — мутированных файлах React с известными багами (инвертированные булевы, перепутанные операторы, удалённые guard-клаузы и т.д.):
 
-| | hashline | str_replace |
-|---|:---:|:---:|
-| **Прошло** | **60/60 (100%)** | 58/60 (96.7%) |
-| **Провалено** | 0 | 2 |
-| **Неоднозначные правки** | 0 | 4 |
+| | hashline | str_replace | apply_patch |
+|---|:---:|:---:|:---:|
+| **Прошло** | **60/60 (100%)** | 58/60 (96.7%) | **60/60 (100%)** |
+| **Провалено** | 0 | 2 | 0 |
+| **Неоднозначные правки** | 0 | 4 | 0 |
 
-str_replace ломается, когда `old_string` встречается в файле несколько раз (например, повторяющиеся guard-клаузы, похожие блоки кода). Hashline адресует каждую строку уникально через `lineNumber:hash`, поэтому неоднозначность исключена.
+`apply_patch` с контекстными строками работает так же надёжно, как hashline — **при условии, что модель правильно генерирует патч**. Слабое место `apply_patch` — зависимость от обучения конкретной модели: не обученные под этот формат модели производят некорректные diff-ы (пропускают контекст, путают отступы), что приводит к провалу применения патча.
+
+`str_replace` ломается, когда `old_string` встречается в файле несколько раз (повторяющиеся guard-клаузы, похожие блоки кода). Hashline адресует каждую строку уникально через `lineNumber:hash` — неоднозначность исключена, модельный формат не нужен.
 
 ```bash
 # Запустите сами:
-npx tsx benchmark/run.ts              # режим hashline
-npx tsx benchmark/run.ts --no-hash    # режим str_replace
+npx tsx benchmark/run.ts               # режим hashline
+npx tsx benchmark/run.ts --no-hash     # режим str_replace
+npx tsx benchmark/run.ts --apply-patch # режим apply_patch
 ```
 
 <details>
@@ -409,9 +462,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/dist/{chunk-VPCMHCTB.js → chunk-7KUPGN4M.js}

@@ -4,7 +4,7 @@ import {
   resolveConfig,
   shouldExclude,
   stripHashes
-} from "./chunk-I6RACR3D.js";
+} from "./chunk-DOR4YDIS.js";
 
 // src/hooks.ts
 import { appendFileSync } from "fs";
@@ -94,7 +94,7 @@ function createFileReadAfterHook(cache, config) {
         return;
       }
     }
-    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix);
+    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix, resolved.fileRev);
     output.output = annotated;
     debug("annotated", typeof filePath === "string" ? filePath : input.tool, "lines:", content.split("\n").length);
     if (cache && typeof filePath === "string") {
@@ -206,10 +206,32 @@ function createSystemPromptHook(config) {
         '- Hash references include both the line number AND the content hash, so `2:f1c` means "line 2 with hash f1c".',
         "- If you see a mismatch, do NOT proceed with the edit \u2014 re-read the file to get fresh references.",
         "",
+        "### File revision (`#HL REV:<hash>`):",
+        "- When files are read, the first line may contain a file revision header: `" + prefix + "REV:<8-char-hex>`.",
+        "- This is a hash of the entire file content. Pass it as the `fileRev` parameter to `hashline_edit` to verify the file hasn't changed.",
+        "- If the file was modified between read and edit, the revision check fails with `FILE_REV_MISMATCH` \u2014 re-read the file.",
+        "",
+        "### Safe reapply (`safeReapply`):",
+        "- Pass `safeReapply: true` to `hashline_edit` to enable automatic line relocation.",
+        "- If a line moved (e.g., due to insertions above), safe reapply finds it by content hash.",
+        "- If exactly one match is found, the edit proceeds at the new location.",
+        "- If multiple matches exist, the edit fails with `AMBIGUOUS_REAPPLY` \u2014 re-read the file.",
+        "",
+        "### Structured error codes:",
+        "- `HASH_MISMATCH` \u2014 line content changed since last read",
+        "- `FILE_REV_MISMATCH` \u2014 file was modified since last read",
+        "- `AMBIGUOUS_REAPPLY` \u2014 multiple candidate lines found during safe reapply",
+        "- `TARGET_OUT_OF_RANGE` \u2014 line number exceeds file length",
+        "- `INVALID_REF` \u2014 malformed hash reference",
+        "- `INVALID_RANGE` \u2014 start line is after end line",
+        "- `MISSING_REPLACEMENT` \u2014 replace/insert operation without replacement content",
+        "",
         "### Best practices:",
         "- Use hash references for all edit operations to ensure precision.",
         "- When making multiple edits, work from bottom to top to avoid line number shifts.",
-        "- For large replacements, use range references (e.g., `1:a3f to 10:b2c`) instead of individual lines."
+        "- For large replacements, use range references (e.g., `1:a3f to 10:b2c`) instead of individual lines.",
+        "- Use `fileRev` to guard against stale edits on critical files.",
+        "- Use `safeReapply: true` when editing files that may have shifted due to earlier edits."
       ].join("\n")
     );
   };