AGENTS.md

1# hashline-core — Hash-Anchored Edit Primitives (Core)
2 
3**Generated:** 2026-06-17
4 
5## OVERVIEW
6 
7The engine behind the Hashline edit tool (inspired by [oh-my-pi](https://github.com/can1357/oh-my-pi)). Tags every line with a `LINE#HASH|` content hash, validates edit refs against current content (rejecting stale lines), then applies structured `replace`/`append`/`prepend` edits with autocorrection, deduplication, and unified-diff generation. Package: `@oh-my-opencode/hashline-core`.
8 
9## PUBLIC API (`src/index.ts`, ~26 fns + 7 types) — by area
10 
11| Area | Files | Key exports |
12|------|-------|-------------|
13| **Hash compute** | `hash-computation.ts`, `xxhash32.ts`, `constants.ts` | `computeLineHash`, `computeLegacyLineHash`, `formatHashLine(s)`, `streamHashLinesFrom{Utf8,Lines}`, `NIBBLE_STR`, `HASHLINE_DICT` |
14| **Validation** | `validation.ts` | `parseLineRef`, `validateLineRef(s)`, `normalizeLineRef`, `HashlineMismatchError` |
15| **Apply** | `edit-operations.ts`, `edit-operation-primitives.ts` | `applyHashlineEdits`, `applyHashlineEditsWithReport`, `apply{SetLine,ReplaceLines,InsertAfter,InsertBefore,Append,Prepend}` |
16| **Normalize/dedup/order** | `normalize-edits.ts`, `edit-deduplication.ts`, `edit-ordering.ts` | `normalizeHashlineEdits`, `dedupeEdits`, `detectOverlappingRanges` |
17| **Autocorrect** | `autocorrect-replacement-lines.ts`, `edit-text-normalization.ts` | `autocorrectReplacementLines`, prefix/indent/echo strippers |
18| **Diff/display** | `diff-utils.ts`, `hashline-edit-diff.ts` | `toHashlineContent`, `generateUnifiedDiff`, `countLineDiffs`, `generateHashlineDiff` |
19| **Canonicalize/chunk** | `file-text-canonicalization.ts`, `hashline-chunk-formatter.ts` | `canonicalizeFileText`/`restoreFileText` (BOM + LF/CRLF), `createHashlineChunkFormatter` (200 lines / 64 KB) |
20 
21## DEPENDENCIES & CONSUMERS
22 
23- **Depends on:** `diff` (^9) — for `createTwoFilesPatch` in `generateUnifiedDiff` only. Otherwise self-contained.
24- **Consumed by:** the ~15 thin re-export shims under `omo-opencode/src/tools/hashline-edit/`. NOT consumed by the Codex edition (Light has no hashline).
25 
26## NOTES
27 
28- **"Option 2" hashing:** no npm xxhash dependency. `xxhash32.ts` prefers native `Bun.hash.xxHash32()` at call time and falls back to a pure-JS impl, so it runs under Bun and Node.
29- **Legacy hash compatibility:** validation accepts both `computeLineHash` (trimEnd + strip `\r`) and `computeLegacyLineHash` (strip ALL whitespace) — old stored hashes still validate.
30- **Seed rule:** content lines seed `0`; whitespace-only lines seed `lineNumber` (distinct hash per position).
31- **`normalizeHashlineEdits` rejects unknown ops** with `"Legacy format was removed; use op/pos/end/lines."` — the discriminated union is `replace | append | prepend` only.
32- Parent: [`packages/AGENTS.md`](../AGENTS.md).
33