@svilupp/hash-edit 0.1.0

package/src/index.ts

@@ -0,0 +1,564 @@
+import { createHash, randomUUID } from "node:crypto"
+import { realpathSync } from "node:fs"
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises"
+import { basename, dirname, isAbsolute, join as joinPath, relative, resolve } from "node:path"
+
+export type NewlineStyle = "lf" | "crlf" | "cr" | "none"
+
+export type ReplaceOp = {
+	op: "replace"
+	line: number
+	hash: string
+	lines: string[]
+	end_line?: number
+	end_hash?: string
+}
+
+export type InsertBeforeOp = {
+	op: "insert_before"
+	line: number
+	hash: string
+	lines: string[]
+}
+
+export type InsertAfterOp = {
+	op: "insert_after"
+	line: number
+	hash: string
+	lines: string[]
+}
+
+export type DeleteOp = {
+	op: "delete"
+	line: number
+	hash: string
+	end_line?: number
+	end_hash?: string
+}
+
+export type EditOp = ReplaceOp | InsertBeforeOp | InsertAfterOp | DeleteOp
+
+export type ReadResult = {
+	path: string
+	version: string
+	encoding: string
+	bom: boolean
+	newline: NewlineStyle
+	has_final_newline: boolean
+	hash_length: number
+	total_lines: number
+	start_line: number
+	end_line: number
+	lines: string[]
+}
+
+export type EditResult = {
+	path: string
+	version_before: string
+	version_after: string
+	applied: number
+	first_changed_line: number | null
+	encoding: string
+	bom: boolean
+	newline: NewlineStyle
+	has_final_newline: boolean
+	total_lines: number
+}
+
+export type WriteResult = {
+	path: string
+	version_after: string
+	created: boolean
+	encoding: string
+	bom: boolean
+	newline: NewlineStyle
+	has_final_newline: boolean
+	total_lines: number
+}
+
+type Snapshot = {
+	path: string
+	version: string
+	encoding: string
+	bom: boolean
+	newline: NewlineStyle
+	has_final_newline: boolean
+	lines: string[]
+}
+
+const DEFAULT_ENCODING = "utf-8"
+const DEFAULT_HASH_LENGTH = 2
+const UTF8_BOM = Buffer.from([0xef, 0xbb, 0xbf])
+const PREFIX_RE = /^\s*\d+:[0-9a-f]{2,}\|/
+
+export class HashEditError extends Error {}
+export class PathEscapeError extends HashEditError {}
+export class MixedNewlineError extends HashEditError {}
+export class FileEncodingError extends HashEditError {}
+export class InvalidOperationError extends HashEditError {}
+
+export class VersionConflictError extends HashEditError {
+	path: string
+	expected: string | null
+	actual: string
+
+	constructor(path: string, expected: string | null, actual: string) {
+		const message =
+			expected === null
+				? `${path} already exists. read() first and pass expected_version to overwrite safely.`
+				: `Version conflict for ${path}: expected ${expected}, actual ${actual}. Re-read the file first.`
+		super(message)
+		this.path = path
+		this.expected = expected
+		this.actual = actual
+	}
+}
+
+export class AnchorMismatchError extends HashEditError {
+	mismatches: Array<{ line: number; expected: string; actual: string }>
+
+	constructor(
+		message: string,
+		mismatches: Array<{ line: number; expected: string; actual: string }>,
+	) {
+		super(message)
+		this.mismatches = mismatches
+	}
+}
+
+function newlineSeparator(style: NewlineStyle): string {
+	if (style === "lf") return "\n"
+	if (style === "crlf") return "\r\n"
+	if (style === "cr") return "\r"
+	return "\n"
+}
+
+function detectNewlineStyle(text: string): {
+	newline: NewlineStyle
+	has_final_newline: boolean
+	lines: string[]
+} {
+	const matches = text.match(/\r\n|\n|\r/g) ?? []
+	const unique = new Set(matches)
+	if (unique.size > 1) {
+		throw new MixedNewlineError(`Mixed newline styles detected: ${Array.from(unique).join(", ")}`)
+	}
+	if (matches.length === 0) {
+		return { newline: "none", has_final_newline: false, lines: text === "" ? [] : [text] }
+	}
+	const separator = matches[0] ?? "\n"
+	const newline = separator === "\n" ? "lf" : separator === "\r\n" ? "crlf" : "cr"
+	const has_final_newline = text.endsWith(separator)
+	const split = text.split(separator)
+	const lines = has_final_newline ? split.slice(0, -1) : split
+	return { newline, has_final_newline, lines }
+}
+
+function joinText(lines: string[], newline: NewlineStyle, hasFinalNewline: boolean): string {
+	if (lines.length === 0) return ""
+	const separator = newlineSeparator(newline)
+	let text = lines.join(separator)
+	if (hasFinalNewline) text += separator
+	return text
+}
+
+function versionForBytes(data: Buffer): string {
+	return createHash("blake2s256").update(data).digest("hex").slice(0, 32)
+}
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await stat(path)
+		return true
+	} catch {
+		return false
+	}
+}
+
+export function computeLineHash(
+	lineNumber: number,
+	text: string,
+	hashLength = DEFAULT_HASH_LENGTH,
+): string {
+	if (hashLength < 2) throw new Error("hashLength must be >= 2")
+	const normalized = text.replace(/\r/g, "").replace(/[ \t]+$/u, "")
+	const material = /[\p{L}\p{N}]/u.test(normalized) ? normalized : `${lineNumber}\0${normalized}`
+	return createHash("blake2s256")
+		.update(material, DEFAULT_ENCODING)
+		.digest("hex")
+		.slice(0, hashLength)
+}
+
+export function renderLine(
+	lineNumber: number,
+	text: string,
+	hashLength = DEFAULT_HASH_LENGTH,
+): string {
+	return `${lineNumber}:${computeLineHash(lineNumber, text, hashLength)}|${text}`
+}
+
+export function renderLines(
+	lines: string[],
+	startLine = 1,
+	hashLength = DEFAULT_HASH_LENGTH,
+): string[] {
+	return lines.map((line, index) => renderLine(startLine + index, line, hashLength))
+}
+
+export function stripRenderPrefixes(lines: string[]): string[] {
+	const nonEmpty = lines.filter((line) => line !== "")
+	if (nonEmpty.length > 0 && nonEmpty.every((line) => PREFIX_RE.test(line))) {
+		return lines.map((line) => line.replace(PREFIX_RE, ""))
+	}
+	return [...lines]
+}
+
+function mismatchMessage(
+	path: string,
+	lines: string[],
+	hashLength: number,
+	mismatches: Array<{ line: number; expected: string; actual: string }>,
+): string {
+	const displayLines = new Set<number>()
+	for (const mismatch of mismatches) {
+		for (
+			let line = Math.max(1, mismatch.line - 2);
+			line <= Math.min(lines.length, mismatch.line + 2);
+			line += 1
+		) {
+			displayLines.add(line)
+		}
+	}
+	const rendered: string[] = [
+		`Anchors are stale in ${path}. Re-read the file and use the updated rendered lines below.`,
+	]
+	if (displayLines.size === 0) return rendered.join("\n")
+	rendered.push("")
+	const mismatchSet = new Set(mismatches.map((mismatch) => mismatch.line))
+	let previous = -1
+	for (const lineNumber of [...displayLines].sort((left, right) => left - right)) {
+		if (previous !== -1 && lineNumber > previous + 1) {
+			rendered.push("    ...")
+		}
+		const prefix = mismatchSet.has(lineNumber) ? ">>> " : "    "
+		rendered.push(prefix + renderLine(lineNumber, lines[lineNumber - 1] ?? "", hashLength))
+		previous = lineNumber
+	}
+	return rendered.join("\n")
+}
+
+export class HashEditHarness {
+	#root: string
+	#resolvedRoot: string
+	#encoding: string
+	#hashLength: number
+
+	constructor(root = ".", options: { default_encoding?: string; hash_length?: number } = {}) {
+		this.#root = resolve(root)
+		this.#resolvedRoot = resolveExistingPath(this.#root)
+		this.#encoding = options.default_encoding ?? DEFAULT_ENCODING
+		this.#hashLength = options.hash_length ?? DEFAULT_HASH_LENGTH
+	}
+
+	resolvePath(path: string): string {
+		const absolute = resolve(this.#root, path)
+		const resolved = resolveExistingPath(absolute)
+		const rel = relative(this.#resolvedRoot, resolved)
+		if (rel.startsWith("..") || isAbsolute(rel)) {
+			throw new PathEscapeError(`${path} escapes root ${this.#root}`)
+		}
+		return resolved
+	}
+
+	async read(
+		path: string,
+		options: { start_line?: number; end_line?: number } = {},
+	): Promise<ReadResult> {
+		const resolved = this.resolvePath(path)
+		const snapshot = await this.readSnapshot(resolved)
+		if (snapshot.lines.length === 0) {
+			return {
+				path: snapshot.path,
+				version: snapshot.version,
+				encoding: snapshot.encoding,
+				bom: snapshot.bom,
+				newline: snapshot.newline,
+				has_final_newline: snapshot.has_final_newline,
+				hash_length: this.#hashLength,
+				total_lines: 0,
+				start_line: 0,
+				end_line: 0,
+				lines: [],
+			}
+		}
+
+		const startLine = options.start_line ?? 1
+		const endLine = options.end_line ?? snapshot.lines.length
+		if (startLine < 1 || endLine < startLine || endLine > snapshot.lines.length) {
+			throw new InvalidOperationError(
+				`Invalid read window for ${snapshot.path}: start_line=${startLine}, end_line=${endLine}, total_lines=${snapshot.lines.length}`,
+			)
+		}
+		return {
+			path: snapshot.path,
+			version: snapshot.version,
+			encoding: snapshot.encoding,
+			bom: snapshot.bom,
+			newline: snapshot.newline,
+			has_final_newline: snapshot.has_final_newline,
+			hash_length: this.#hashLength,
+			total_lines: snapshot.lines.length,
+			start_line: startLine,
+			end_line: endLine,
+			lines: renderLines(snapshot.lines.slice(startLine - 1, endLine), startLine, this.#hashLength),
+		}
+	}
+
+	async edit(
+		path: string,
+		ops: EditOp | EditOp[],
+		options: { expected_version: string },
+	): Promise<EditResult> {
+		const resolved = this.resolvePath(path)
+		const snapshot = await this.readSnapshot(resolved)
+		if (options.expected_version !== snapshot.version) {
+			throw new VersionConflictError(snapshot.path, options.expected_version, snapshot.version)
+		}
+
+		const operations = Array.isArray(ops) ? [...ops] : [ops]
+		if (operations.length === 0) {
+			throw new InvalidOperationError("edit() requires at least one operation")
+		}
+		const lines = [...snapshot.lines]
+		const mismatches: Array<{ line: number; expected: string; actual: string }> = []
+
+		const validateAnchor = (line: number, expectedHash: string) => {
+			if (line < 1 || line > lines.length) {
+				throw new InvalidOperationError(
+					`Line ${line} is out of range for ${snapshot.path} (total_lines=${lines.length})`,
+				)
+			}
+			const actual = computeLineHash(line, lines[line - 1] ?? "", this.#hashLength)
+			if (actual !== expectedHash) {
+				mismatches.push({ line, expected: expectedHash, actual })
+			}
+		}
+
+		for (const operation of operations) {
+			validateAnchor(operation.line, operation.hash)
+			if ("end_line" in operation && operation.end_line !== undefined) {
+				if (!operation.end_hash) {
+					throw new InvalidOperationError("Range edits require end_hash")
+				}
+				validateAnchor(operation.end_line, operation.end_hash)
+				if (operation.end_line < operation.line) {
+					throw new InvalidOperationError("end_line must be >= line")
+				}
+			}
+		}
+
+		if (mismatches.length > 0) {
+			throw new AnchorMismatchError(
+				mismatchMessage(snapshot.path, lines, this.#hashLength, mismatches),
+				mismatches,
+			)
+		}
+
+		const sortKey = (operation: EditOp): [number, number] => {
+			const lineNumber =
+				"end_line" in operation && operation.end_line !== undefined
+					? operation.end_line
+					: operation.line
+			const precedence = { replace: 0, delete: 0, insert_after: 1, insert_before: 2 }[operation.op]
+			return [-lineNumber, precedence]
+		}
+
+		let firstChangedLine: number | null = null
+		for (const operation of [...operations].sort((left, right) => {
+			const [leftLine, leftPrec] = sortKey(left)
+			const [rightLine, rightPrec] = sortKey(right)
+			return leftLine - rightLine || leftPrec - rightPrec
+		})) {
+			if (operation.op === "replace") {
+				const replacement = stripRenderPrefixes([...operation.lines])
+				const endLine = operation.end_line ?? operation.line
+				const current = lines.slice(operation.line - 1, endLine)
+				if (
+					current.length === replacement.length &&
+					current.every((line, index) => line === replacement[index])
+				) {
+					throw new InvalidOperationError(
+						`No changes made to ${snapshot.path}. Replacement for ${operation.line}:${operation.hash} is identical.`,
+					)
+				}
+				lines.splice(operation.line - 1, endLine - operation.line + 1, ...replacement)
+				firstChangedLine =
+					firstChangedLine === null ? operation.line : Math.min(firstChangedLine, operation.line)
+			} else if (operation.op === "delete") {
+				const endLine = operation.end_line ?? operation.line
+				lines.splice(operation.line - 1, endLine - operation.line + 1)
+				firstChangedLine =
+					firstChangedLine === null ? operation.line : Math.min(firstChangedLine, operation.line)
+			} else if (operation.op === "insert_before") {
+				const inserted = stripRenderPrefixes([...operation.lines])
+				const payload = inserted.length === 0 ? [""] : inserted
+				lines.splice(operation.line - 1, 0, ...payload)
+				firstChangedLine =
+					firstChangedLine === null ? operation.line : Math.min(firstChangedLine, operation.line)
+			} else {
+				const inserted = stripRenderPrefixes([...operation.lines])
+				const payload = inserted.length === 0 ? [""] : inserted
+				lines.splice(operation.line, 0, ...payload)
+				const insertionLine = operation.line + 1
+				firstChangedLine =
+					firstChangedLine === null ? insertionLine : Math.min(firstChangedLine, insertionLine)
+			}
+		}
+
+		const versionAfter = await this.writeSnapshot(resolved, {
+			lines,
+			bom: snapshot.bom,
+			newline: snapshot.newline,
+			has_final_newline: snapshot.has_final_newline,
+		})
+
+		return {
+			path: snapshot.path,
+			version_before: snapshot.version,
+			version_after: versionAfter,
+			applied: operations.length,
+			first_changed_line: firstChangedLine,
+			encoding: snapshot.encoding,
+			bom: snapshot.bom,
+			newline: snapshot.newline,
+			has_final_newline: snapshot.has_final_newline,
+			total_lines: lines.length,
+		}
+	}
+
+	async write(
+		path: string,
+		text: string,
+		options: { expected_version?: string } = {},
+	): Promise<WriteResult> {
+		const resolved = this.resolvePath(path)
+		const created = !(await pathExists(resolved))
+		const input = detectNewlineStyle(text)
+		let bom = false
+		let newline = input.newline
+
+		let versionAfter: string
+		if (created) {
+			versionAfter = await this.writeSnapshot(resolved, {
+				lines: input.lines,
+				bom: false,
+				newline: input.newline,
+				has_final_newline: input.has_final_newline,
+			})
+		} else {
+			const snapshot = await this.readSnapshot(resolved)
+			if ((options.expected_version ?? null) !== snapshot.version) {
+				throw new VersionConflictError(
+					snapshot.path,
+					options.expected_version ?? null,
+					snapshot.version,
+				)
+			}
+			bom = snapshot.bom
+			newline = snapshot.newline === "none" ? input.newline : snapshot.newline
+			versionAfter = await this.writeSnapshot(resolved, {
+				lines: input.lines,
+				bom,
+				newline,
+				has_final_newline: input.has_final_newline,
+			})
+		}
+
+		return {
+			path: relative(this.#root, resolved),
+			version_after: versionAfter,
+			created,
+			encoding: this.#encoding,
+			bom,
+			newline,
+			has_final_newline: input.has_final_newline,
+			total_lines: input.lines.length,
+		}
+	}
+
+	private async readSnapshot(path: string): Promise<Snapshot> {
+		const raw = Buffer.from(await readFile(path))
+		const version = versionForBytes(raw)
+		const bom = raw.subarray(0, UTF8_BOM.length).equals(UTF8_BOM)
+		const payload = bom ? raw.subarray(UTF8_BOM.length) : raw
+		let text: string
+		try {
+			text = new TextDecoder(this.#encoding as Bun.Encoding, { fatal: true }).decode(payload)
+		} catch (error) {
+			throw new FileEncodingError(`${relative(this.#root, path)} is not valid ${this.#encoding}`, {
+				cause: error,
+			})
+		}
+		const parsed = detectNewlineStyle(text)
+		return {
+			path: relative(this.#root, path),
+			version,
+			encoding: this.#encoding,
+			bom,
+			newline: parsed.newline,
+			has_final_newline: parsed.has_final_newline,
+			lines: parsed.lines,
+		}
+	}
+
+	private async writeSnapshot(
+		path: string,
+		options: { lines: string[]; bom: boolean; newline: NewlineStyle; has_final_newline: boolean },
+	): Promise<string> {
+		await mkdir(dirname(path), { recursive: true })
+		const text = joinText(options.lines, options.newline, options.has_final_newline)
+		let payload = Buffer.from(text, this.#encoding as BufferEncoding)
+		if (options.bom) {
+			payload = Buffer.concat([UTF8_BOM, payload])
+		}
+
+		const tempPath = `${path}.${randomUUID()}.tmp`
+		let mode: number | undefined
+		try {
+			mode = (await stat(path)).mode
+		} catch {}
+		try {
+			await writeFile(tempPath, payload)
+			if (mode !== undefined) {
+				await chmod(tempPath, mode)
+			}
+			await rename(tempPath, path)
+		} finally {
+			await rm(tempPath, { force: true })
+		}
+		return versionForBytes(payload)
+	}
+}
+
+function resolveExistingPath(path: string): string {
+	const missingSegments: string[] = []
+	let current = path
+	while (true) {
+		try {
+			const resolved = realpathSync.native(current)
+			const suffix = [...missingSegments].reverse()
+			return missingSegments.length === 0 ? resolved : joinPath(resolved, ...suffix)
+		} catch (error) {
+			const candidate = error as NodeJS.ErrnoException
+			if (candidate.code !== "ENOENT") {
+				throw candidate
+			}
+			const parent = dirname(current)
+			if (parent === current) {
+				return joinPath(current, ...[...missingSegments].reverse())
+			}
+			missingSegments.push(basename(current))
+			current = parent
+		}
+	}
+}