@mammothb/pi-hashline 0.2.0

package/src/parser.ts

@@ -0,0 +1,415 @@
+/**
+ * Token-driven parser that converts a stream of {@link Token}s into a flat
+ * list of {@link Edit}s.
+ *
+ * Sits between the {@link Tokenizer} and the applier. Block ops (`replace
+ * block N:`, `delete block N`) are parsed but not resolved — resolution
+ * requires file text + language detection and happens at apply time.
+ */
+
+import { HL_PAYLOAD_REPLACE } from "./format";
+import type { BlockTarget, Token } from "./tokenizer";
+import { Tokenizer } from "./tokenizer";
+import type { Anchor, Cursor, Edit, ParsedRange } from "./types";
+
+// ─── Warning / error message constants ───────────────────────────────
+
+const BARE_BODY_AUTO_PIPED_WARNING =
+  "Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines.";
+
+const EMPTY_REPLACE =
+  "`replace N..M:` needs at least one `+TEXT` body row. To delete lines, use `delete N..M`.";
+
+const EMPTY_INSERT = "`insert` needs at least one `+TEXT` body row.";
+
+const EMPTY_BLOCK =
+  "`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete N..M` with the block's line range.";
+
+const DELETE_TAKES_NO_BODY =
+  "`delete N..M` does not take body rows. Remove the body, or use `replace N..M:`.";
+
+const DELETE_BLOCK_TAKES_NO_BODY =
+  "`delete block N` does not take body rows. Remove the body, or use `replace block N:` to replace the block.";
+
+const MINUS_ROW_REJECTED =
+  "`-` rows are not valid; hashline ranges already name the lines being changed. To insert a literal line starting with `-`, write `+-…`.";
+
+// ─── Internal payload row ────────────────────────────────────────────
+
+interface PayloadRow {
+  text: string;
+  lineNum: number;
+}
+
+// ─── Clone helpers ───────────────────────────────────────────────────
+
+function cloneAnchor(a: Anchor): Anchor {
+  return { line: a.line };
+}
+
+function cloneCursor(c: Cursor): Cursor {
+  switch (c.kind) {
+    case "before_anchor":
+      return { kind: "before_anchor", anchor: cloneAnchor(c.anchor) };
+    case "after_anchor":
+      return { kind: "after_anchor", anchor: cloneAnchor(c.anchor) };
+    default:
+      return c;
+  }
+}
+
+// ─── Range expansion ─────────────────────────────────────────────────
+
+function expandRange(range: ParsedRange): Anchor[] {
+  const anchors: Anchor[] = [];
+  for (let line = range.start.line; line <= range.end.line; line++) {
+    anchors.push({ line });
+  }
+  return anchors;
+}
+
+// ─── Parse state ─────────────────────────────────────────────────────
+
+interface PendingOp {
+  target: BlockTarget;
+  lineNum: number;
+  payloads: PayloadRow[];
+}
+
+interface ParseState {
+  edits: Edit[];
+  warnings: string[];
+  editIndex: number;
+  pending: PendingOp | undefined;
+  terminated: boolean;
+}
+
+function createState(): ParseState {
+  return {
+    edits: [],
+    warnings: [],
+    editIndex: 0,
+    pending: undefined,
+    terminated: false,
+  };
+}
+
+// ─── Edit emission ───────────────────────────────────────────────────
+
+function pushInsert(
+  state: ParseState,
+  cursor: Cursor,
+  text: string,
+  lineNum: number,
+  mode?: "replacement",
+): void {
+  state.edits.push({
+    kind: "insert",
+    cursor: cloneCursor(cursor),
+    text,
+    lineNum,
+    index: state.editIndex++,
+    ...(mode === undefined ? {} : { mode }),
+  });
+}
+
+function pushDelete(state: ParseState, anchor: Anchor, lineNum: number): void {
+  state.edits.push({
+    kind: "delete",
+    anchor: cloneAnchor(anchor),
+    lineNum,
+    index: state.editIndex++,
+  });
+}
+
+function pushBlock(
+  state: ParseState,
+  anchor: Anchor,
+  payloads: readonly PayloadRow[],
+  lineNum: number,
+): void {
+  state.edits.push({
+    kind: "block",
+    anchor: cloneAnchor(anchor),
+    payloads: payloads.map((p) => p.text),
+    lineNum,
+    index: state.editIndex++,
+  });
+}
+
+function emitPayloads(
+  state: ParseState,
+  cursor: Cursor,
+  payloads: readonly PayloadRow[],
+  lineNum: number,
+  mode?: "replacement",
+): void {
+  for (const payload of payloads) {
+    pushInsert(state, cursor, payload.text, lineNum, mode);
+  }
+}
+
+// ─── Flush pending op ────────────────────────────────────────────────
+
+function flushPending(state: ParseState): void {
+  const pending = state.pending;
+  if (!pending) {
+    return;
+  }
+  state.pending = undefined;
+
+  const { target, lineNum, payloads } = pending;
+
+  switch (target.kind) {
+    case "delete": {
+      // Delete takes no body
+      for (const anchor of expandRange(target.range)) {
+        pushDelete(state, anchor, lineNum);
+      }
+      return;
+    }
+
+    case "delete_block": {
+      // Block delete with no payloads
+      pushBlock(state, target.anchor, [], lineNum);
+      return;
+    }
+
+    case "block": {
+      // Replace block needs body
+      if (payloads.length === 0) {
+        throw new Error(`line ${lineNum}: ${EMPTY_BLOCK}`);
+      }
+      pushBlock(state, target.anchor, payloads, lineNum);
+      return;
+    }
+
+    case "replace": {
+      // Replace needs body
+      if (payloads.length === 0) {
+        throw new Error(`line ${lineNum}: ${EMPTY_REPLACE}`);
+      }
+      const cursor: Cursor = {
+        kind: "before_anchor",
+        anchor: cloneAnchor(target.range.start),
+      };
+      emitPayloads(state, cursor, payloads, lineNum, "replacement");
+      for (const anchor of expandRange(target.range)) {
+        pushDelete(state, anchor, lineNum);
+      }
+      return;
+    }
+
+    case "insert_before": {
+      if (payloads.length === 0) {
+        throw new Error(`line ${lineNum}: ${EMPTY_INSERT}`);
+      }
+      emitPayloads(
+        state,
+        { kind: "before_anchor", anchor: cloneAnchor(target.anchor) },
+        payloads,
+        lineNum,
+      );
+      return;
+    }
+
+    case "insert_after": {
+      if (payloads.length === 0) {
+        throw new Error(`line ${lineNum}: ${EMPTY_INSERT}`);
+      }
+      emitPayloads(
+        state,
+        { kind: "after_anchor", anchor: cloneAnchor(target.anchor) },
+        payloads,
+        lineNum,
+      );
+      return;
+    }
+
+    case "bof": {
+      if (payloads.length === 0) {
+        throw new Error(`line ${lineNum}: ${EMPTY_INSERT}`);
+      }
+      emitPayloads(state, { kind: "bof" }, payloads, lineNum);
+      return;
+    }
+
+    case "eof": {
+      if (payloads.length === 0) {
+        throw new Error(`line ${lineNum}: ${EMPTY_INSERT}`);
+      }
+      emitPayloads(state, { kind: "eof" }, payloads, lineNum);
+      return;
+    }
+  }
+}
+
+// ─── Validate range order ────────────────────────────────────────────
+
+function validateRangeOrder(range: ParsedRange, lineNum: number): void {
+  if (range.end.line < range.start.line) {
+    throw new Error(
+      `line ${lineNum}: range ${range.start.line}..${range.end.line} ends before it starts.`,
+    );
+  }
+}
+
+// ─── Overlapping delete detection ────────────────────────────────────
+
+function validateNoOverlappingDeletes(edits: Edit[]): void {
+  const sourceLinesByAnchor = new Map<number, number[]>();
+  for (const edit of edits) {
+    if (edit.kind !== "delete") {
+      continue;
+    }
+    let sourceLines = sourceLinesByAnchor.get(edit.anchor.line);
+    if (sourceLines === undefined) {
+      sourceLines = [];
+      sourceLinesByAnchor.set(edit.anchor.line, sourceLines);
+    }
+    if (!sourceLines.includes(edit.lineNum)) {
+      sourceLines.push(edit.lineNum);
+    }
+  }
+  for (const [anchorLine, sourceLines] of sourceLinesByAnchor) {
+    if (sourceLines.length < 2) {
+      continue;
+    }
+    const [firstBlock, secondBlock] = [...sourceLines].sort((a, b) => a - b);
+    throw new Error(
+      `line ${secondBlock}: anchor line ${anchorLine} is already targeted by another hunk on line ${firstBlock}. Issue ONE hunk per range.`,
+    );
+  }
+}
+
+// ─── Token consumer ──────────────────────────────────────────────────
+
+function feedToken(state: ParseState, token: Token): void {
+  if (state.terminated) {
+    return;
+  }
+
+  switch (token.kind) {
+    case "envelope-begin":
+    case "envelope-separator":
+    case "blank":
+      // Silently consumed
+      return;
+
+    case "envelope-end":
+    case "abort":
+      state.terminated = true;
+      return;
+
+    case "header":
+      // A new section header flushes the previous section's pending op
+      flushPending(state);
+      return;
+
+    case "op-block": {
+      // Validate range order for literal replace/delete
+      if (token.target.kind === "replace" || token.target.kind === "delete") {
+        validateRangeOrder(token.target.range, token.lineNum);
+      }
+      flushPending(state);
+      state.pending = {
+        target: token.target,
+        lineNum: token.lineNum,
+        payloads: [],
+      };
+      return;
+    }
+
+    case "payload-literal": {
+      if (!state.pending) {
+        throw new Error(
+          `line ${token.lineNum}: payload line has no preceding hunk header. Got ${JSON.stringify(`${HL_PAYLOAD_REPLACE}${token.text}`)}.`,
+        );
+      }
+      if (
+        state.pending.target.kind === "delete" ||
+        state.pending.target.kind === "delete_block"
+      ) {
+        const msg =
+          state.pending.target.kind === "delete"
+            ? DELETE_TAKES_NO_BODY
+            : DELETE_BLOCK_TAKES_NO_BODY;
+        throw new Error(`line ${token.lineNum}: ${msg}`);
+      }
+      state.pending.payloads.push({
+        text: token.text,
+        lineNum: token.lineNum,
+      });
+      return;
+    }
+
+    case "raw": {
+      // Raw line without a pending op is an error
+      if (!state.pending) {
+        const trimmed = token.text.trim();
+        if (trimmed.length === 0) {
+          return; // blank-like
+        }
+        throw new Error(
+          `line ${token.lineNum}: payload line has no preceding hunk header. Use \`replace N..M:\`, \`delete N..M\`, or \`insert before|after|head|tail:\` above the body. Got ${JSON.stringify(token.text)}.`,
+        );
+      }
+
+      // Delete ops can't have body
+      if (
+        state.pending.target.kind === "delete" ||
+        state.pending.target.kind === "delete_block"
+      ) {
+        const msg =
+          state.pending.target.kind === "delete"
+            ? DELETE_TAKES_NO_BODY
+            : DELETE_BLOCK_TAKES_NO_BODY;
+        throw new Error(`line ${token.lineNum}: ${msg}`);
+      }
+
+      // Reject `-` rows (unified-diff contamination)
+      if (token.text.trimStart().startsWith("-")) {
+        throw new Error(`line ${token.lineNum}: ${MINUS_ROW_REJECTED}`);
+      }
+
+      // Auto-pipe bare body rows
+      if (!state.warnings.includes(BARE_BODY_AUTO_PIPED_WARNING)) {
+        state.warnings.push(BARE_BODY_AUTO_PIPED_WARNING);
+      }
+      state.pending.payloads.push({
+        text: token.text,
+        lineNum: token.lineNum,
+      });
+      return;
+    }
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Parse hashline diff text into a flat list of edits and warnings.
+ *
+ * This is the core parsing entry point. It tokenizes the input, feeds
+ * tokens through the state machine, flushes any pending op, and validates
+ * the result.
+ */
+export function parsePatch(diff: string): {
+  edits: Edit[];
+  warnings: string[];
+} {
+  const tokenizer = new Tokenizer();
+  const state = createState();
+
+  for (const token of tokenizer.tokenizeAll(diff)) {
+    feedToken(state, token);
+  }
+
+  // Flush any remaining pending op
+  flushPending(state);
+
+  // Validate no overlapping deletes
+  validateNoOverlappingDeletes(state.edits);
+
+  return { edits: state.edits, warnings: state.warnings };
+}

package/src/prompt.md

@@ -0,0 +1,110 @@
+# Hashline Edit Grammar
+
+You are editing files using **hashline anchoring**. Every file you read has a `¶PATH#TAG` header. Every edit you make must include that same header so the tool can validate you're working against the version you read.
+
+## Section Headers
+
+Every file section starts with `¶PATH#TAG`. Copy the entire header from the `read` or `grep` output. **The tag is REQUIRED** — there is no hashless form. To create a new file, use the `write` tool.
+
+## Operations
+
+```
+replace N..M:         Replace original lines N–M with the body rows below.
+                      Single line: `replace N..N:`.
+                      Body length is irrelevant — replacing 1 line with 10 is still `replace N..N:`.
+
+delete N..M           Delete original lines N–M. No body, no colon.
+                      Single line: `delete N`.
+
+insert before N:      Insert body rows immediately before line N.
+insert after N:       Insert body rows immediately after line N.
+insert head:          Insert body rows at the very start of the file.
+insert tail:          Insert body rows at the very end of the file.
+```
+
+## Body Rows
+
+Body rows appear only under a `:` header. Every body row is:
+
+```
++TEXT     Add a new literal line TEXT, verbatim. Leading whitespace is kept.
+          Use `+` alone to add a blank line.
+```
+
+There is NO other body row kind. **Never write `-old` rows or bare context lines.** To keep a line, leave it out of every range. To insert a literal line starting with `-`, prefix it: `+-text`.
+
+## Critical Rules
+
+1. **Re-ground after every edit.** Each applied edit mints a fresh `#TAG` and renumbers the file. The tag and line numbers you just used are dead. Take the next edit's `¶PATH#TAG` and line numbers from the edit response or a fresh `read`, never from pre-edit memory.
+
+2. **Ranges are tight.** Cover only lines whose content actually changes. Never widen a range to swallow an unchanged signature, brace, or statement. A stale single-line replace corrupts one line; a stale block replace shreds everything.
+
+3. **The body is the final content.** Only `+TEXT` rows under a `:` header. The range does the deleting — never include both old and new lines.
+
+4. **One hunk per range.** The body is the final desired content, never an old/new pair. To change lines 2 and 5 while keeping 3–4, issue two separate hunks.
+
+5. **Never format code with this tool.** Use the project's formatter (e.g. `bash: npm run format`) for reordering imports, re-indenting, or mechanical restyling.
+
+## Examples
+
+Read returns:
+```
+¶src/greet.ts#A1B2
+1:function greet(name: string) {
+2:  console.log("Hello, " + name);
+3:}
+```
+
+Replace line 2:
+```
+¶src/greet.ts#A1B2
+replace 2..2:
++  console.log(`Hello, ${name}`);
+```
+
+Insert after line 1:
+```
+¶src/greet.ts#A1B2
+insert after 1:
++  if (!name) name = "world";
+```
+
+Delete line 2:
+```
+¶src/greet.ts#A1B2
+delete 2
+```
+
+Add header and footer:
+```
+¶src/greet.ts#A1B2
+insert head:
++// Auto-generated
+insert tail:
++export default greet;
+```
+
+## Anti-Patterns (WRONG)
+
+```
+# WRONG — empty replace to delete. Use delete 4 instead.
+replace 4..4:
+
+# WRONG — range describes post-edit size. Use replace 1..1: (body length is irrelevant).
+replace 1..2:
++function greet(name: string) {
+
+# WRONG — `-` rows do not exist. The range deletes; the body is only new content.
+replace 3..3:
+    old line
+-   removed line
++   new line
+
+# RIGHT
+replace 3..3:
++   new line
+```
+
+## On Stale-Tag Rejection
+
+If the edit tool says the tag is stale ("file changed between read and edit"), re-`read` the file to get the current tag and line numbers. Never stack more edits onto stale numbers.

package/src/prompt.ts

@@ -0,0 +1,59 @@
+/**
+ * Prompt injection for hashline — loads the LLM-facing grammar reference
+ * and injects it into the system prompt before each agent turn.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ─── Prompt loading ──────────────────────────────────────────────────
+
+let _cachedPrompt: string | undefined;
+let _cachedPath: string | undefined;
+
+function getPromptPath(): string {
+  if (_cachedPath === undefined) {
+    _cachedPath = join(dirname(fileURLToPath(import.meta.url)), "prompt.md");
+  }
+  return _cachedPath;
+}
+
+/** Load the hashline grammar prompt (cached after first read). */
+export function loadPrompt(): string {
+  if (_cachedPrompt === undefined) {
+    _cachedPrompt = readFileSync(getPromptPath(), "utf-8");
+  }
+  return _cachedPrompt;
+}
+
+// ─── Injection helpers ───────────────────────────────────────────────
+
+const PROMPT_MARKER = "<!-- HASHLINE_GRAMMAR -->";
+
+/**
+ * Inject the hashline grammar prompt into the system message.
+ * Appends after the marker if present, otherwise appends to the end.
+ */
+export function injectPrompt(messages: unknown[]): void {
+  const prompt = loadPrompt();
+  if (messages.length === 0) {
+    return;
+  }
+
+  // Find the system message (first message with role "system").
+  const systemMsg = messages[0] as { role?: string; content?: string };
+  if (
+    systemMsg !== null &&
+    typeof systemMsg === "object" &&
+    systemMsg.role === "system" &&
+    typeof systemMsg.content === "string"
+  ) {
+    // If there's a marker, replace it. Otherwise append.
+    if (systemMsg.content.includes(PROMPT_MARKER)) {
+      systemMsg.content = systemMsg.content.replace(PROMPT_MARKER, prompt);
+    } else {
+      systemMsg.content += `\n\n${prompt}`;
+    }
+  }
+}