plugsuits 1.0.0

package/src/tools/utils/hashline/edit-operations.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "bun:test";
+import {
+  applyHashlineEdits,
+  applyHashlineEditsWithReport,
+  computeLineHash,
+  HashlineMismatchError,
+} from ".";
+
+const OVERLAPPING_REGEX = /[Oo]verlapping/;
+
+describe("hashline - edit operations", () => {
+  it("replaces anchored line", () => {
+    const content = "alpha\nbravo\ncharlie";
+    const bravoHash = computeLineHash(2, "bravo");
+    const result = applyHashlineEdits(content, [
+      { op: "replace", pos: `2#${bravoHash}`, lines: ["BRAVO"] },
+    ]);
+    expect(result).toBe("alpha\nBRAVO\ncharlie");
+  });
+
+  it("inserts with append and prepend", () => {
+    const content = "a\nb";
+    const bHash = computeLineHash(2, "b");
+    const result = applyHashlineEdits(content, [
+      { op: "prepend", pos: `2#${bHash}`, lines: ["before-b"] },
+      { op: "append", pos: `2#${bHash}`, lines: ["after-b"] },
+    ]);
+    expect(result).toBe("a\nbefore-b\nb\nafter-b");
+  });
+
+  it("appends at EOF", () => {
+    const content = "a\nb";
+    const result = applyHashlineEdits(content, [
+      { op: "append", lines: ["c"] },
+    ]);
+    expect(result).toBe("a\nb\nc");
+  });
+
+  it("preserves append order for same anchor", () => {
+    const content = "a\nb";
+    const bHash = computeLineHash(2, "b");
+    const result = applyHashlineEdits(content, [
+      { op: "append", pos: `2#${bHash}`, lines: ["first"] },
+      { op: "append", pos: `2#${bHash}`, lines: ["second"] },
+    ]);
+    expect(result).toBe("a\nb\nsecond\nfirst");
+  });
+
+  it("dedupes semantically identical edits", () => {
+    const content = "a\nb";
+    const bHash = computeLineHash(2, "b");
+    const report = applyHashlineEditsWithReport(content, [
+      { op: "append", pos: `2#${bHash}`, lines: ["dup"] },
+      { op: "append", pos: `2#${bHash}`, lines: ["dup"] },
+    ]);
+    expect(report.content).toBe("a\nb\ndup");
+    expect(report.deduplicatedEdits).toBe(1);
+  });
+
+  it("preserves prepend order for same anchor", () => {
+    const content = "a\nb";
+    const bHash = computeLineHash(2, "b");
+    const result = applyHashlineEdits(content, [
+      { op: "prepend", pos: `2#${bHash}`, lines: ["first"] },
+      { op: "prepend", pos: `2#${bHash}`, lines: ["second"] },
+    ]);
+    expect(result).toBe("a\nsecond\nfirst\nb");
+  });
+
+  it("throws mismatch error for stale anchors", () => {
+    const content = "one\ntwo\nthree";
+    const staleHash = computeLineHash(2, "TWO");
+    expect(() =>
+      applyHashlineEdits(content, [
+        { op: "replace", pos: `2#${staleHash}`, lines: ["two-updated"] },
+      ])
+    ).toThrow(HashlineMismatchError);
+  });
+
+  it("collects remaps for stale anchors", () => {
+    const content = "one\ntwo\nthree";
+    const staleHash = computeLineHash(2, "TWO");
+    try {
+      applyHashlineEdits(content, [
+        { op: "replace", pos: `2#${staleHash}`, lines: ["two-updated"] },
+      ]);
+      throw new Error("Expected HashlineMismatchError to be thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(HashlineMismatchError);
+      const mismatchError = error as HashlineMismatchError;
+      const expectedKey = `2#${staleHash}`;
+      const actualValue = mismatchError.remaps.get(expectedKey);
+      expect(actualValue).toBe(`2#${computeLineHash(2, "two")}`);
+    }
+  });
+
+  it("formats mismatch context lines with pipe delimiter", () => {
+    const content = "one\ntwo\nthree";
+    const staleHash = computeLineHash(2, "TWO");
+    try {
+      applyHashlineEdits(content, [
+        { op: "replace", pos: `2#${staleHash}`, lines: ["two-updated"] },
+      ]);
+      throw new Error("Expected HashlineMismatchError to be thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(HashlineMismatchError);
+      const message = (error as Error).message;
+      expect(message).toContain(`>>> 2#${computeLineHash(2, "two")}|two`);
+    }
+  });
+
+  it("silently deletes lines via replace with empty content", () => {
+    const content = "hello\nworld";
+    const helloHash = computeLineHash(1, "hello");
+    const result = applyHashlineEdits(content, [
+      { op: "replace", pos: `1#${helloHash}`, lines: [] },
+    ]);
+    expect(result).toBe("world");
+  });
+
+  it("reports noop edits", () => {
+    const content = "hello\nworld";
+    const helloHash = computeLineHash(1, "hello");
+    const report = applyHashlineEditsWithReport(content, [
+      { op: "replace", pos: `1#${helloHash}`, lines: ["hello"] },
+    ]);
+    expect(report.noopEdits).toBe(1);
+    expect(report.content).toBe(content);
+  });
+
+  it("detects overlapping range edits", () => {
+    const content = "a\nb\nc\nd\ne";
+    const aH = computeLineHash(1, "a");
+    const cH = computeLineHash(3, "c");
+    const bH = computeLineHash(2, "b");
+    const dH = computeLineHash(4, "d");
+    expect(() =>
+      applyHashlineEdits(content, [
+        {
+          op: "replace",
+          pos: `1#${aH}`,
+          end: `3#${cH}`,
+          lines: ["x", "y", "z"],
+        },
+        {
+          op: "replace",
+          pos: `2#${bH}`,
+          end: `4#${dH}`,
+          lines: ["x", "y", "z"],
+        },
+      ])
+    ).toThrow(OVERLAPPING_REGEX);
+  });
+});

package/src/tools/utils/hashline/edit-operations.ts

@@ -0,0 +1,132 @@
+import { dedupeEdits } from "./edit-deduplication";
+import {
+  applyAppend,
+  applyInsertAfter,
+  applyInsertBefore,
+  applyPrepend,
+  applyReplaceLines,
+  applySetLine,
+} from "./edit-operation-primitives";
+import {
+  collectLineRefs,
+  detectOverlappingRanges,
+  getEditLineNumber,
+} from "./edit-ordering";
+import type { HashlineEdit } from "./types";
+import { validateLineRefs } from "./validation";
+
+/** Compare two string arrays element-by-element. O(n) with early exit. */
+function arraysEqual(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+export interface HashlineApplyReport {
+  content: string;
+  deduplicatedEdits: number;
+  noopEdits: number;
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: core edit application logic
+export function applyHashlineEditsWithReport(
+  content: string,
+  edits: HashlineEdit[]
+): HashlineApplyReport {
+  if (edits.length === 0) {
+    return {
+      content,
+      noopEdits: 0,
+      deduplicatedEdits: 0,
+    };
+  }
+
+  const dedupeResult = dedupeEdits(edits);
+  const EDIT_PRECEDENCE: Record<string, number> = {
+    replace: 0,
+    append: 1,
+    prepend: 2,
+  };
+  const sortedEdits = [...dedupeResult.edits].sort((a, b) => {
+    const lineA = getEditLineNumber(a);
+    const lineB = getEditLineNumber(b);
+    if (lineB !== lineA) {
+      return lineB - lineA;
+    }
+    return (EDIT_PRECEDENCE[a.op] ?? 3) - (EDIT_PRECEDENCE[b.op] ?? 3);
+  });
+
+  let noopEdits = 0;
+
+  let lines = content.length === 0 ? [] : content.split("\n");
+
+  const refs = collectLineRefs(sortedEdits);
+  validateLineRefs(lines, refs);
+
+  const overlapError = detectOverlappingRanges(dedupeResult.edits);
+  if (overlapError) {
+    throw new Error(overlapError);
+  }
+
+  for (const edit of sortedEdits) {
+    switch (edit.op) {
+      case "replace": {
+        const next = edit.end
+          ? applyReplaceLines(lines, edit.pos, edit.end, edit.lines, {
+              skipValidation: true,
+            })
+          : applySetLine(lines, edit.pos, edit.lines, { skipValidation: true });
+        if (arraysEqual(next, lines)) {
+          noopEdits += 1;
+          break;
+        }
+        lines = next;
+        break;
+      }
+      case "append": {
+        const next = edit.pos
+          ? applyInsertAfter(lines, edit.pos, edit.lines, {
+              skipValidation: true,
+            })
+          : applyAppend(lines, edit.lines);
+        if (arraysEqual(next, lines)) {
+          noopEdits += 1;
+          break;
+        }
+        lines = next;
+        break;
+      }
+      case "prepend": {
+        const next = edit.pos
+          ? applyInsertBefore(lines, edit.pos, edit.lines, {
+              skipValidation: true,
+            })
+          : applyPrepend(lines, edit.lines);
+        if (arraysEqual(next, lines)) {
+          noopEdits += 1;
+          break;
+        }
+        lines = next;
+        break;
+      }
+      default: {
+        break;
+      }
+    }
+  }
+
+  return {
+    content: lines.join("\n"),
+    noopEdits,
+    deduplicatedEdits: dedupeResult.deduplicatedEdits,
+  };
+}
+
+export function applyHashlineEdits(
+  content: string,
+  edits: HashlineEdit[]
+): string {
+  return applyHashlineEditsWithReport(content, edits).content;
+}

package/src/tools/utils/hashline/edit-ordering.ts

@@ -0,0 +1,60 @@
+import type { HashlineEdit } from "./types";
+import { parseLineRef } from "./validation";
+
+export function getEditLineNumber(edit: HashlineEdit): number {
+  switch (edit.op) {
+    case "replace":
+      return parseLineRef(edit.end ?? edit.pos).line;
+    case "append":
+      return edit.pos ? parseLineRef(edit.pos).line : Number.POSITIVE_INFINITY;
+    case "prepend":
+      return edit.pos ? parseLineRef(edit.pos).line : Number.NEGATIVE_INFINITY;
+    default:
+      return Number.POSITIVE_INFINITY;
+  }
+}
+
+export function collectLineRefs(edits: HashlineEdit[]): string[] {
+  return edits.flatMap((edit) => {
+    switch (edit.op) {
+      case "replace":
+        return edit.end ? [edit.pos, edit.end] : [edit.pos];
+      case "append":
+      case "prepend":
+        return edit.pos ? [edit.pos] : [];
+      default:
+        return [];
+    }
+  });
+}
+
+export function detectOverlappingRanges(edits: HashlineEdit[]): string | null {
+  const ranges: { start: number; end: number; idx: number }[] = [];
+  for (let i = 0; i < edits.length; i++) {
+    const edit = edits[i];
+    if (edit.op !== "replace" || !edit.end) {
+      continue;
+    }
+    const start = parseLineRef(edit.pos).line;
+    const end = parseLineRef(edit.end).line;
+    ranges.push({ start, end, idx: i });
+  }
+  if (ranges.length < 2) {
+    return null;
+  }
+
+  ranges.sort((a, b) => a.start - b.start || a.end - b.end);
+  for (let i = 1; i < ranges.length; i++) {
+    const prev = ranges[i - 1];
+    const curr = ranges[i];
+    if (curr.start <= prev.end) {
+      return (
+        "Overlapping range edits detected: " +
+        `edit ${prev.idx + 1} (lines ${prev.start}-${prev.end}) overlaps with ` +
+        `edit ${curr.idx + 1} (lines ${curr.start}-${curr.end}). ` +
+        "Use pos-only replace for single-line edits."
+      );
+    }
+  }
+  return null;
+}

package/src/tools/utils/hashline/edit-text-normalization.ts

@@ -0,0 +1,180 @@
+const HASHLINE_PREFIX_RE =
+  /^\s*(?:>>>|>>)?\s*\d+\s*#\s*[ZPMQVRWSNKTXJBYH]{2}\|/;
+const DIFF_PLUS_RE = /^[+](?![+])/;
+const LEADING_WHITESPACE_REGEX = /^\s*/;
+
+function equalsIgnoringWhitespace(a: string, b: string): boolean {
+  if (a === b) {
+    return true;
+  }
+  return a.replace(/\s+/g, "") === b.replace(/\s+/g, "");
+}
+
+function leadingWhitespace(text: string): string {
+  if (!text) {
+    return "";
+  }
+  const match = text.match(LEADING_WHITESPACE_REGEX);
+  return match ? match[0] : "";
+}
+
+export function stripLinePrefixes(lines: string[]): string[] {
+  let hashPrefixCount = 0;
+  let diffPlusCount = 0;
+  let nonEmpty = 0;
+
+  for (const line of lines) {
+    if (line.length === 0) {
+      continue;
+    }
+    nonEmpty += 1;
+    if (HASHLINE_PREFIX_RE.test(line)) {
+      hashPrefixCount += 1;
+    }
+    if (DIFF_PLUS_RE.test(line)) {
+      diffPlusCount += 1;
+    }
+  }
+
+  if (nonEmpty === 0) {
+    return lines;
+  }
+
+  const stripHash = hashPrefixCount > 0 && hashPrefixCount >= nonEmpty * 0.5;
+  const stripPlus =
+    !stripHash && diffPlusCount > 0 && diffPlusCount >= nonEmpty * 0.5;
+
+  if (!(stripHash || stripPlus)) {
+    return lines;
+  }
+
+  return lines.map((line) => {
+    if (stripHash) {
+      return line.replace(HASHLINE_PREFIX_RE, "");
+    }
+    if (stripPlus) {
+      return line.replace(DIFF_PLUS_RE, "");
+    }
+    return line;
+  });
+}
+
+export function toNewLines(input: string | string[]): string[] {
+  if (Array.isArray(input)) {
+    return stripLinePrefixes(input);
+  }
+  return stripLinePrefixes(input.split("\n"));
+}
+
+export function restoreLeadingIndent(
+  templateLine: string,
+  line: string
+): string {
+  if (line.length === 0) {
+    return line;
+  }
+  const templateIndent = leadingWhitespace(templateLine);
+  if (templateIndent.length === 0) {
+    return line;
+  }
+  if (leadingWhitespace(line).length > 0) {
+    return line;
+  }
+  if (templateLine.trim() === line.trim()) {
+    return line;
+  }
+  return `${templateIndent}${line}`;
+}
+
+export function stripInsertAnchorEcho(
+  anchorLine: string,
+  newLines: string[]
+): string[] {
+  if (newLines.length === 0) {
+    return newLines;
+  }
+  if (equalsIgnoringWhitespace(newLines[0], anchorLine)) {
+    return newLines.slice(1);
+  }
+  return newLines;
+}
+
+export function stripInsertBeforeEcho(
+  anchorLine: string,
+  newLines: string[]
+): string[] {
+  if (newLines.length <= 1) {
+    return newLines;
+  }
+  const lastLine = newLines.at(-1);
+  if (
+    lastLine !== undefined &&
+    equalsIgnoringWhitespace(lastLine, anchorLine)
+  ) {
+    return newLines.slice(0, -1);
+  }
+  return newLines;
+}
+
+export function stripInsertBoundaryEcho(
+  afterLine: string,
+  beforeLine: string,
+  newLines: string[]
+): string[] {
+  let out = newLines;
+  if (out.length > 0 && equalsIgnoringWhitespace(out[0], afterLine)) {
+    out = out.slice(1);
+  }
+  const lastLine = out.at(-1);
+  if (
+    out.length > 0 &&
+    lastLine !== undefined &&
+    equalsIgnoringWhitespace(lastLine, beforeLine)
+  ) {
+    out = out.slice(0, -1);
+  }
+  return out;
+}
+
+export function stripRangeBoundaryEcho(
+  lines: string[],
+  startLine: number,
+  endLine: number,
+  newLines: string[]
+): string[] {
+  const replacedCount = endLine - startLine + 1;
+  if (newLines.length <= 1 || newLines.length <= replacedCount) {
+    return newLines;
+  }
+
+  let out = newLines;
+  const beforeIdx = startLine - 2;
+  if (beforeIdx >= 0 && equalsIgnoringWhitespace(out[0], lines[beforeIdx])) {
+    out = out.slice(1);
+  }
+
+  const afterIdx = endLine;
+  const lastLine = out.at(-1);
+  if (
+    afterIdx < lines.length &&
+    out.length > 0 &&
+    lastLine !== undefined &&
+    equalsIgnoringWhitespace(lastLine, lines[afterIdx])
+  ) {
+    out = out.slice(0, -1);
+  }
+
+  return out;
+}
+
+export function parseHashlineText(
+  input: string[] | string | null | undefined
+): string[] {
+  if (input === null || input === undefined) {
+    return [];
+  }
+  if (Array.isArray(input)) {
+    return stripLinePrefixes(input);
+  }
+  return toNewLines(input);
+}

package/src/tools/utils/hashline/file-text-canonicalization.ts

@@ -0,0 +1,58 @@
+export interface FileTextEnvelope {
+  content: string;
+  hadBom: boolean;
+  lineEnding: "\n" | "\r\n";
+}
+
+function detectLineEnding(content: string): "\n" | "\r\n" {
+  const crlfIndex = content.indexOf("\r\n");
+  const lfIndex = content.indexOf("\n");
+  if (lfIndex === -1) {
+    return "\n";
+  }
+  if (crlfIndex === -1) {
+    return "\n";
+  }
+  return crlfIndex < lfIndex ? "\r\n" : "\n";
+}
+
+function stripBom(content: string): { content: string; hadBom: boolean } {
+  if (!content.startsWith("\uFEFF")) {
+    return { content, hadBom: false };
+  }
+  return { content: content.slice(1), hadBom: true };
+}
+
+function normalizeToLf(content: string): string {
+  return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+function restoreLineEndings(
+  content: string,
+  lineEnding: "\n" | "\r\n"
+): string {
+  if (lineEnding === "\n") {
+    return content;
+  }
+  return content.replace(/\n/g, "\r\n");
+}
+
+export function canonicalizeFileText(content: string): FileTextEnvelope {
+  const stripped = stripBom(content);
+  return {
+    content: normalizeToLf(stripped.content),
+    hadBom: stripped.hadBom,
+    lineEnding: detectLineEnding(stripped.content),
+  };
+}
+
+export function restoreFileText(
+  content: string,
+  envelope: FileTextEnvelope
+): string {
+  const withLineEnding = restoreLineEndings(content, envelope.lineEnding);
+  if (!envelope.hadBom) {
+    return withLineEnding;
+  }
+  return `\uFEFF${withLineEnding}`;
+}

package/src/tools/utils/hashline/hash-computation.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "bun:test";
+import {
+  computeFileHash,
+  computeLineHash,
+  streamHashLinesFromLines,
+  streamHashLinesFromUtf8,
+} from ".";
+
+const HASH_PATTERN = /^[ZPMQVRWSNKTXJBYH]{2}$/;
+
+describe("hashline - hash computation", () => {
+  it("computes 2-char line hashes", () => {
+    const hash = computeLineHash(1, "hello");
+    expect(hash).toMatch(HASH_PATTERN);
+  });
+
+  it("uses line number for symbol-only lines", () => {
+    const a = computeLineHash(1, "***");
+    const b = computeLineHash(2, "***");
+    expect(a).not.toBe(b);
+  });
+
+  it("does not use line number for alphanumeric lines", () => {
+    const a = computeLineHash(1, "hello");
+    const b = computeLineHash(2, "hello");
+    expect(a).toBe(b);
+  });
+
+  it("computes deterministic file hash", () => {
+    const a = computeFileHash("a\nb\n");
+    const b = computeFileHash("a\nb\n");
+    const c = computeFileHash("a\nB\n");
+
+    expect(a).toBe(b);
+    expect(a).not.toBe(c);
+  });
+
+  it("streams hashline numbering from lines", async () => {
+    const chunks: string[] = [];
+    for await (const chunk of streamHashLinesFromLines(["a", "b", "c"], {
+      maxChunkLines: 2,
+    })) {
+      chunks.push(chunk);
+    }
+
+    const output = chunks.join("\n");
+    expect(output).toBe(
+      [
+        `1#${computeLineHash(1, "a")}|a`,
+        `2#${computeLineHash(2, "b")}|b`,
+        `3#${computeLineHash(3, "c")}|c`,
+      ].join("\n")
+    );
+  });
+
+  it("streams hashline numbering from UTF-8 bytes", async () => {
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("a\nb\n"));
+        controller.enqueue(new TextEncoder().encode("c\n"));
+        controller.close();
+      },
+    });
+
+    const chunks: string[] = [];
+    for await (const chunk of streamHashLinesFromUtf8(stream, {
+      maxChunkLines: 2,
+    })) {
+      chunks.push(chunk);
+    }
+
+    const output = chunks.join("\n");
+    expect(output).toBe(
+      [
+        `1#${computeLineHash(1, "a")}|a`,
+        `2#${computeLineHash(2, "b")}|b`,
+        `3#${computeLineHash(3, "c")}|c`,
+        `4#${computeLineHash(4, "")}|`,
+      ].join("\n")
+    );
+  });
+});