@mammothb/pi-hashline 0.2.0

package/src/input.ts

@@ -0,0 +1,232 @@
+/**
+ * High-level patch parser.
+ *
+ * Splits authored hashline input into {@link PatchSection}s, each rooted at a
+ * `¶PATH#HASH` header, and exposes a {@link Patch} class that gives lazy
+ * access to the parsed edits per section.
+ *
+ * The splitter is purely lexical — it doesn't know whether a section's path
+ * actually exists. That's the patcher's job.
+ */
+
+import * as path from "node:path";
+
+import { parsePatch } from "./parser";
+import { Tokenizer } from "./tokenizer";
+import type { Edit, SplitOptions } from "./types";
+
+// ─── Header parsing ──────────────────────────────────────────────────
+
+const TOKENIZER = new Tokenizer();
+
+/**
+ * Split raw input text into per-section structures keyed by `¶PATH#HASH` headers.
+ * Each section collects all non-header lines until the next header.
+ */
+function splitIntoSections(
+  input: string,
+  options: SplitOptions = {},
+): RawSection[] {
+  const lines = input.split("\n");
+  const sections: RawSection[] = [];
+  let current: RawSection | undefined;
+
+  for (const rawLine of lines) {
+    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+    const trimmed = line.trimEnd();
+
+    // Check for section header
+    if (trimmed.startsWith("¶")) {
+      const token = TOKENIZER.tokenize(line);
+      if (token.kind === "header") {
+        // Flush previous section
+        if (
+          current &&
+          current.diffLines.length > 0 &&
+          current.diffLines.some((l) => l.trim().length > 0)
+        ) {
+          sections.push({
+            path: current.path,
+            fileHash: current.fileHash,
+            diffLines: current.diffLines,
+          });
+        }
+
+        // Normalize path: make absolute paths relative to cwd
+        let sectionPath = token.path;
+        if (options.cwd && path.isAbsolute(sectionPath)) {
+          const rel = path.relative(
+            path.resolve(options.cwd),
+            path.resolve(sectionPath),
+          );
+          if (!rel.startsWith("..") && !path.isAbsolute(rel)) {
+            sectionPath = rel || ".";
+          }
+        }
+
+        current = {
+          path: sectionPath,
+          fileHash: token.fileHash,
+          diffLines: [],
+        };
+        continue;
+      }
+    }
+
+    // Accumulate line in current section
+    if (current) {
+      current.diffLines.push(line);
+    }
+    // Lines before the first header are silently dropped
+  }
+
+  // Flush final section
+  if (
+    current &&
+    current.diffLines.length > 0 &&
+    current.diffLines.some((l) => l.trim().length > 0)
+  ) {
+    sections.push({
+      path: current.path,
+      fileHash: current.fileHash,
+      diffLines: current.diffLines,
+    });
+  }
+
+  return sections;
+}
+
+interface RawSection {
+  path: string;
+  fileHash?: string;
+  diffLines: string[];
+}
+
+// ─── PatchSection ────────────────────────────────────────────────────
+
+/**
+ * One section in a parsed {@link Patch}: a target file plus the lazily-
+ * parsed list of edits that should land on it.
+ */
+export class PatchSection {
+  readonly path: string;
+  readonly fileHash: string | undefined;
+  readonly diff: string;
+
+  #parsed: { edits: Edit[]; warnings: string[] } | undefined;
+
+  constructor(raw: RawSection) {
+    this.path = raw.path;
+    this.fileHash = raw.fileHash;
+    this.diff = raw.diffLines.join("\n");
+  }
+
+  /**
+   * Parse this section's diff body. Cached: subsequent calls return the
+   * same `{ edits, warnings }` object.
+   */
+  parse(): { edits: Edit[]; warnings: string[] } {
+    this.#parsed ??= parsePatch(this.diff);
+    return this.#parsed;
+  }
+
+  /** Parsed edits for this section (lazy). */
+  get edits(): Edit[] {
+    return this.parse().edits;
+  }
+
+  /** Warnings emitted during parsing of this section (lazy). */
+  get warnings(): string[] {
+    return this.parse().warnings;
+  }
+
+  /**
+   * True when at least one edit anchors to concrete file content.
+   * Pure `insert head:` / `insert tail:` literal inserts do not count.
+   */
+  get hasAnchoredEdit(): boolean {
+    return this.edits.some((edit) => {
+      if (edit.kind === "delete") {
+        return true;
+      }
+      if (edit.kind === "block") {
+        return true;
+      }
+      return (
+        edit.cursor.kind === "before_anchor" ||
+        edit.cursor.kind === "after_anchor"
+      );
+    });
+  }
+
+  /** Anchor lines touched by this section, sorted ascending and deduplicated. */
+  collectAnchorLines(): number[] {
+    const lines = new Set<number>();
+    for (const edit of this.edits) {
+      if (edit.kind === "delete") {
+        lines.add(edit.anchor.line);
+        continue;
+      }
+      if (edit.kind === "block") {
+        lines.add(edit.anchor.line);
+        continue;
+      }
+      if (
+        edit.cursor.kind === "before_anchor" ||
+        edit.cursor.kind === "after_anchor"
+      ) {
+        lines.add(edit.cursor.anchor.line);
+      }
+    }
+    return [...lines].sort((a, b) => a - b);
+  }
+}
+
+// ─── Patch ───────────────────────────────────────────────────────────
+
+/**
+ * A parsed hashline patch — zero or more {@link PatchSection}s, each rooted
+ * at a `¶PATH#HASH` header.
+ *
+ * `Patch` is pure data: parsing is line-anchored and does not look at the
+ * filesystem. To apply a patch, hand it to the patcher.
+ */
+export class Patch {
+  readonly sections: readonly PatchSection[];
+
+  private constructor(sections: PatchSection[]) {
+    this.sections = sections;
+  }
+
+  /**
+   * Parse `input` into a {@link Patch}.
+   *
+   * `options.cwd` resolves absolute paths inside headers to cwd-relative form.
+   */
+  static parse(input: string, options: SplitOptions = {}): Patch {
+    const rawSections = splitIntoSections(input, options);
+
+    if (rawSections.length === 0) {
+      throw new Error(
+        `Patch input must begin with "¶PATH#HASH" on the first non-blank line for anchored edits. ` +
+          'Example: "¶src/foo.ts#0A3" then edit ops.',
+      );
+    }
+
+    const sections = rawSections.map((raw) => new PatchSection(raw));
+    return new Patch(sections);
+  }
+
+  /**
+   * Parse `input` and return only the first section. Throws if the input
+   * has zero sections.
+   */
+  static parseSingle(input: string, options: SplitOptions = {}): PatchSection {
+    const patch = Patch.parse(input, options);
+    const first = patch.sections[0];
+    if (!first) {
+      throw new Error("Patch input did not produce any sections.");
+    }
+    return first;
+  }
+}

package/src/messages.ts

@@ -0,0 +1,127 @@
+/**
+ * Centralized error and warning text emitted by the hashline edit tool.
+ * Consolidating these as named constants makes them easy to audit and
+ * keeps wording stable across the rendering paths that surface them.
+ */
+
+import { HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+
+// ─── Error messages ──────────────────────────────────────────────────
+
+/**
+ * Build a mismatch error message when the live file's hash doesn't match
+ * the tag the edit was authored against.
+ */
+export function mismatchMessage(
+  sectionPath: string,
+  expectedTag: string,
+  actualTag: string,
+): string {
+  return (
+    `File "${sectionPath}" changed between read and edit (expected tag #${expectedTag}, ` +
+    `live file has tag #${actualTag}). Re-read the file with the read tool to get ` +
+    `the current tag and anchors, then retry the edit.`
+  );
+}
+
+/**
+ * Error when a section has no snapshot tag at all.
+ */
+export function missingTagMessage(sectionPath: string): string {
+  return (
+    `Missing hashline snapshot tag for edit to ${sectionPath}. Use ` +
+    `\`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}TAG\` from your latest read output. ` +
+    `To create a new file, use the write tool.`
+  );
+}
+
+/**
+ * Error when the target file doesn't exist.
+ */
+export function nonExistentFileMessage(filePath: string): string {
+  return (
+    `File does not exist: "${filePath}". Use the write tool to create new files, ` +
+    `then edit them with the tag returned by write.`
+  );
+}
+
+/**
+ * Error when the edit input doesn't start with a `¶PATH#HASH` header.
+ */
+export function noHeaderMessage(): string {
+  return (
+    `Edit input must begin with "${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}TAG" copied ` +
+    `from the read output. Example: "${HL_FILE_PREFIX}src/foo.ts${HL_FILE_HASH_SEP}0A3" ` +
+    `followed by edit operations.`
+  );
+}
+
+// ─── Warning messages ────────────────────────────────────────────────
+
+/**
+ * Warning when head/tail inserts are applied to a file whose tag is stale.
+ * Head/tail position is content-independent so the insert applies safely.
+ */
+export const HEADTAIL_DRIFT_WARNING =
+  "Applied insert head/tail onto the current file content even though the " +
+  "snapshot tag was stale (file changed since your read). Head/tail position " +
+  "is content-independent so the insert was not rejected — re-read if the " +
+  "drift was unexpected.";
+
+/** Warning when recovery succeeds via 3-way merge on an external change. */
+export const RECOVERY_EXTERNAL_WARNING =
+  "Recovered from a stale file hash using a previous read snapshot (file changed externally between read and edit).";
+
+/** Warning when recovery succeeds via replay against a newer in-session snapshot. */
+export const RECOVERY_SESSION_CHAIN_WARNING =
+  "Recovered from a stale file hash using an earlier in-session snapshot (the file hash advanced after a prior edit in this session).";
+
+/** Warning when structured-patch merge refused but anchor-content gate passed. */
+export const RECOVERY_SESSION_REPLAY_WARNING =
+  "Recovered by replaying your edits onto the current file content — your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";
+
+/** Error when the hash was never recorded in the snapshot store. */
+export function unrecognizedHashMessage(expectedTag: string): string {
+  return (
+    `Snapshot tag #${expectedTag} was not recorded in this session — it may be from a different session or fabricated. ` +
+    `Re-read the file to get a current tag.`
+  );
+}
+
+// ─── MismatchError ───────────────────────────────────────────────────
+
+/** Lines of context shown around each anchor in mismatch diagnostics. */
+export const MISMATCH_CONTEXT = 2;
+
+/**
+ * Custom error thrown when tag validation fails.
+ * Carries anchor context so renderers can show rich diagnostics.
+ */
+export class MismatchError extends Error {
+  /** The file path (display-relative). */
+  readonly filePath: string;
+  /** The tag the edit was authored against. */
+  readonly expectedTag: string;
+  /** The tag of the current live file. */
+  readonly actualTag: string;
+  /** Full text of the live file (for diagnostic rendering). */
+  readonly liveText: string;
+  /** Anchor lines targeted by the edit (1-indexed). */
+  readonly anchorLines: readonly number[];
+
+  constructor(
+    filePath: string,
+    expectedTag: string,
+    actualTag: string,
+    liveText: string,
+    anchorLines: readonly number[],
+  ) {
+    super(mismatchMessage(filePath, expectedTag, actualTag));
+    this.name = "MismatchError";
+    this.filePath = filePath;
+    this.expectedTag = expectedTag;
+    this.actualTag = actualTag;
+    this.liveText = liveText;
+    this.anchorLines = anchorLines;
+  }
+}

package/src/normalize.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal text-shape normalization: line-ending detection / round-trip and
+ * BOM stripping. The patcher uses these to canonicalize text to LF before
+ * applying edits and to restore the original shape on write-back.
+ */
+
+export type LineEnding = "\r\n" | "\n";
+
+/** Detect the first line-ending style in `content`. Defaults to LF. */
+export function detectLineEnding(content: string): LineEnding {
+  const crlfIdx = content.indexOf("\r\n");
+  const lfIdx = content.indexOf("\n");
+  if (lfIdx === -1) {
+    return "\n";
+  }
+  if (crlfIdx === -1) {
+    return "\n";
+  }
+  return crlfIdx < lfIdx ? "\r\n" : "\n";
+}
+
+/** Normalize every line ending to LF. */
+export function normalizeToLF(text: string): string {
+  return text.replace(/\r\n?/g, "\n");
+}
+
+/** Re-encode LF text with the requested line ending. */
+export function restoreLineEndings(text: string, ending: LineEnding): string {
+  return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+
+export interface BomResult {
+  /** Either the empty string or the BOM sequence. */
+  bom: string;
+  /** Text with any leading BOM removed. */
+  text: string;
+}
+
+/** Strip a UTF-8 BOM if present. Returns both BOM and trailing text. */
+export function stripBom(content: string): BomResult {
+  return content.startsWith("\uFEFF")
+    ? { bom: "\uFEFF", text: content.slice(1) }
+    : { bom: "", text: content };
+}