plugsuits 1.0.0

package/src/tools/utils/hashline/validation.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "bun:test";
+import {
+  computeLineHash,
+  HashlineMismatchError,
+  parseHashlineText,
+  parseLineRef,
+  parseLineTag,
+  tryParseLineTag,
+  validateLineRef,
+  validateLineRefs,
+} from ".";
+
+describe("hashline - validation", () => {
+  it("parses line refs with noisy prefixes", () => {
+    expect(parseLineRef(">>> 12#ZP")).toEqual({
+      line: 12,
+      hash: "ZP",
+    });
+  });
+
+  it("parses line tags via alias", () => {
+    expect(parseLineTag("42#VK")).toEqual({
+      line: 42,
+      hash: "VK",
+    });
+  });
+
+  it("parses anchors with diff marker prefix", () => {
+    expect(parseLineRef(">>> 42#VK")).toEqual({ line: 42, hash: "VK" });
+  });
+
+  it("parses anchors with spaces around #", () => {
+    expect(parseLineRef("42 # VK")).toEqual({ line: 42, hash: "VK" });
+  });
+
+  it("strips pipe-delimited content from refs", () => {
+    expect(parseLineRef("12#ZP|some content")).toEqual({
+      line: 12,
+      hash: "ZP",
+    });
+  });
+
+  it("parses first ref from multiline input (ignores rest)", () => {
+    const result = parseLineRef("1#HK|alpha\n2#KM|bravo");
+    expect(result).toEqual({ line: 1, hash: "HK" });
+  });
+
+  it("returns undefined for invalid tags via tryParseLineTag", () => {
+    expect(tryParseLineTag("invalid")).toBeUndefined();
+    expect(tryParseLineTag(undefined)).toBeUndefined();
+  });
+
+  it("strips copied hashline prefixes from string inputs", () => {
+    const parsed = parseHashlineText("1#ZP|foo\n2#MQ|bar\n");
+    expect(parsed).toEqual(["foo", "bar", ""]);
+  });
+
+  it("preserves markdown list lines starting with '-'", () => {
+    const parsed = parseHashlineText("- item one\n- item two\n");
+    expect(parsed).toEqual(["- item one", "- item two", ""]);
+  });
+
+  it("preserves checkbox list lines", () => {
+    const parsed = parseHashlineText("- [ ] task one\n- [x] task two\n");
+    expect(parsed).toEqual(["- [ ] task one", "- [x] task two", ""]);
+  });
+
+  it("keeps lines that start with '++' intact", () => {
+    const parsed = parseHashlineText("++conflict marker\n++another\n");
+    expect(parsed).toEqual(["++conflict marker", "++another", ""]);
+  });
+
+  it("validates a matching line reference", () => {
+    const lines = ["a", "b", "c"];
+    const ref = `2#${computeLineHash(2, "b")}`;
+    expect(() => validateLineRef(lines, ref)).not.toThrow();
+  });
+
+  it("throws mismatch error from validateLineRef", () => {
+    const lines = ["a", "b", "c"];
+    const ref = `2#${computeLineHash(2, "B")}`;
+    expect(() => validateLineRef(lines, ref)).toThrow(HashlineMismatchError);
+  });
+
+  it("batch validates multiple refs", () => {
+    const lines = ["a", "b", "c"];
+    const refs = [
+      `1#${computeLineHash(1, "a")}`,
+      `2#${computeLineHash(2, "b")}`,
+    ];
+    expect(() => validateLineRefs(lines, refs)).not.toThrow();
+  });
+
+  it("batch validates collecting multiple mismatches", () => {
+    const lines = ["a", "b", "c"];
+    const staleB = computeLineHash(2, "B");
+    const staleC = computeLineHash(3, "C");
+    const refs = [`2#${staleB}`, `3#${staleC}`];
+
+    try {
+      validateLineRefs(lines, refs);
+      throw new Error("Expected error");
+    } catch (error) {
+      expect(error).toBeInstanceOf(HashlineMismatchError);
+      const e = error as HashlineMismatchError;
+      expect(e.remaps.size).toBe(2);
+    }
+  });
+});

package/src/tools/utils/hashline/validation.ts

@@ -0,0 +1,212 @@
+import { HASHLINE_REF_PATTERN } from "./constants";
+import { computeLineHash } from "./hash-computation";
+
+export interface LineRef {
+  hash: string;
+  line: number;
+}
+
+interface HashMismatch {
+  expected: string;
+  line: number;
+}
+
+const MISMATCH_CONTEXT = 2;
+
+const LINE_REF_EXTRACT_PATTERN = /([0-9]+#[ZPMQVRWSNKTXJBYH]{2})/;
+const DIFF_PREFIX_REGEX = /^(?:>>>|[+-])\s*/;
+const HASH_SPACE_REGEX = /\s*#\s*/;
+const PIPE_SUFFIX_REGEX = /\|.*$/;
+const DIGITS_ONLY_REGEX = /^\d+$/;
+const HASH_ID_REGEX = /^[ZPMQVRWSNKTXJBYH]{2}$/;
+const TRAILING_HASH_REGEX = /#([ZPMQVRWSNKTXJBYH]{2})$/;
+
+function normalizeLineRef(ref: string): string {
+  const originalTrimmed = ref.trim();
+  let trimmed = originalTrimmed;
+  trimmed = trimmed.replace(DIFF_PREFIX_REGEX, "");
+  trimmed = trimmed.replace(HASH_SPACE_REGEX, "#");
+  trimmed = trimmed.replace(PIPE_SUFFIX_REGEX, "");
+  trimmed = trimmed.trim();
+
+  if (HASHLINE_REF_PATTERN.test(trimmed)) {
+    return trimmed;
+  }
+
+  const extracted = trimmed.match(LINE_REF_EXTRACT_PATTERN);
+  if (extracted) {
+    return extracted[1];
+  }
+
+  return originalTrimmed;
+}
+
+export function parseLineRef(ref: string): LineRef {
+  const normalized = normalizeLineRef(ref);
+  const match = normalized.match(HASHLINE_REF_PATTERN);
+  if (match) {
+    return {
+      line: Number.parseInt(match[1], 10),
+      hash: match[2],
+    };
+  }
+  // normalized equals ref.trim() in all error paths — extraction only succeeds for valid refs
+  const hashIdx = normalized.indexOf("#");
+  if (hashIdx > 0) {
+    const prefix = normalized.slice(0, hashIdx);
+    const suffix = normalized.slice(hashIdx + 1);
+    if (!DIGITS_ONLY_REGEX.test(prefix) && HASH_ID_REGEX.test(suffix)) {
+      throw new Error(
+        `Invalid line reference: "${ref}". "${prefix}" is not a line number. ` +
+          "Use the actual line number from the read output."
+      );
+    }
+  }
+  throw new Error(
+    `Invalid line reference format: "${ref}". Expected format: "{line_number}#{hash_id}"`
+  );
+}
+
+export function validateLineRef(lines: string[], ref: string): void {
+  const { line, hash } = parseLineRefWithHint(ref, lines);
+
+  if (line < 1 || line > lines.length) {
+    throw new Error(
+      `Line number ${line} out of bounds. File has ${lines.length} lines.`
+    );
+  }
+
+  const content = lines[line - 1];
+  const currentHash = computeLineHash(line, content);
+
+  if (currentHash !== hash) {
+    throw new HashlineMismatchError([{ line, expected: hash }], lines);
+  }
+}
+
+export class HashlineMismatchError extends Error {
+  readonly remaps: ReadonlyMap<string, string>;
+
+  constructor(mismatches: HashMismatch[], fileLines: string[]) {
+    super(HashlineMismatchError.formatMessage(mismatches, fileLines));
+    this.name = "HashlineMismatchError";
+    const remaps = new Map<string, string>();
+    for (const mismatch of mismatches) {
+      const actual = computeLineHash(
+        mismatch.line,
+        fileLines[mismatch.line - 1] ?? ""
+      );
+      remaps.set(
+        `${mismatch.line}#${mismatch.expected}`,
+        `${mismatch.line}#${actual}`
+      );
+    }
+    this.remaps = remaps;
+  }
+
+  static formatMessage(
+    mismatches: HashMismatch[],
+    fileLines: string[]
+  ): string {
+    const mismatchByLine = new Map<number, HashMismatch>();
+    for (const mismatch of mismatches) {
+      mismatchByLine.set(mismatch.line, mismatch);
+    }
+
+    const displayLines = new Set<number>();
+    for (const mismatch of mismatches) {
+      const low = Math.max(1, mismatch.line - MISMATCH_CONTEXT);
+      const high = Math.min(fileLines.length, mismatch.line + MISMATCH_CONTEXT);
+      for (let line = low; line <= high; line++) {
+        displayLines.add(line);
+      }
+    }
+
+    const sortedLines = [...displayLines].sort((a, b) => a - b);
+    const output: string[] = [];
+    output.push(
+      `${mismatches.length} line${mismatches.length > 1 ? "s have" : " has"} changed since last read. ` +
+        "Use updated {line_number}#{hash_id} references below (>>> marks changed lines)."
+    );
+    output.push("");
+
+    let previousLine = -1;
+    for (const line of sortedLines) {
+      if (previousLine !== -1 && line > previousLine + 1) {
+        output.push("    ...");
+      }
+      previousLine = line;
+
+      const content = fileLines[line - 1] ?? "";
+      const hash = computeLineHash(line, content);
+      const prefix = `${line}#${hash}|${content}`;
+      if (mismatchByLine.has(line)) {
+        output.push(`>>> ${prefix}`);
+      } else {
+        output.push(`    ${prefix}`);
+      }
+    }
+
+    return output.join("\n");
+  }
+}
+
+function suggestLineForHash(ref: string, lines: string[]): string | null {
+  const hashMatch = ref.trim().match(TRAILING_HASH_REGEX);
+  if (!hashMatch) {
+    return null;
+  }
+  const hash = hashMatch[1];
+  for (let i = 0; i < lines.length; i++) {
+    if (computeLineHash(i + 1, lines[i]) === hash) {
+      return `Did you mean "${i + 1}#${hash}"?`;
+    }
+  }
+  return null;
+}
+function parseLineRefWithHint(ref: string, lines: string[]): LineRef {
+  try {
+    return parseLineRef(ref);
+  } catch (parseError) {
+    const hint = suggestLineForHash(ref, lines);
+    if (hint && parseError instanceof Error) {
+      throw new Error(`${parseError.message} ${hint}`);
+    }
+    throw parseError;
+  }
+}
+
+export function validateLineRefs(lines: string[], refs: string[]): void {
+  const mismatches: HashMismatch[] = [];
+
+  for (const ref of refs) {
+    const { line, hash } = parseLineRefWithHint(ref, lines);
+
+    if (line < 1 || line > lines.length) {
+      throw new Error(
+        `Line number ${line} out of bounds (file has ${lines.length} lines)`
+      );
+    }
+
+    const content = lines[line - 1];
+    const currentHash = computeLineHash(line, content);
+    if (currentHash !== hash) {
+      mismatches.push({ line, expected: hash });
+    }
+  }
+
+  if (mismatches.length > 0) {
+    throw new HashlineMismatchError(mismatches, lines);
+  }
+}
+
+export function tryParseLineTag(tag: string | undefined): LineRef | undefined {
+  if (!tag) {
+    return undefined;
+  }
+  try {
+    return parseLineRef(tag);
+  } catch {
+    return undefined;
+  }
+}