feat: add error snippet formatter

Author: ClaudiuCeia

docs/guide.md

@@ -162,10 +162,15 @@ avoid both false successes and confusing backtracking.
 ### Formatting failures
 
 ```ts
-import { formatErrorCompact, formatErrorStack } from "@claudiu-ceia/combine";
+import {
+  formatErrorCompact,
+  formatErrorSnippet,
+  formatErrorStack,
+} from "@claudiu-ceia/combine";
 
 if (!result.success) {
   console.error(formatErrorCompact(result));
+  console.error(formatErrorSnippet(result)); // line snippet with caret
   console.error(formatErrorStack(result));
 }
 ```

src/Parser.ts

@@ -172,3 +172,81 @@ export const formatErrorCompact = (f: Failure): string => {
   const context = f.stack.length > 0 ? ` (${f.stack[0].label})` : "";
   return `expected ${f.expected}${context} at ${f.location.line}:${f.location.column}`;
 };
+
+const expandTabs = (s: string, tabWidth: number): string => {
+  if (tabWidth <= 0) return s;
+  return s.replaceAll("\t", " ".repeat(tabWidth));
+};
+
+const ansi = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+};
+
+export type FormatErrorSnippetOptions = Readonly<{
+  /** Include N lines before and after the error line. Default: 1 */
+  contextLines?: number;
+  /** Expand tabs to this many spaces. Default: 2 */
+  tabWidth?: number;
+  /** Add ANSI color codes. Default: false */
+  color?: boolean;
+}>;
+
+/**
+ * Format a failure with a small source snippet and caret indicator.
+ */
+export const formatErrorSnippet = (
+  f: Failure,
+  opts: FormatErrorSnippetOptions = {},
+): string => {
+  const contextLines = opts.contextLines ?? 1;
+  const tabWidth = opts.tabWidth ?? 2;
+  const color = opts.color ?? false;
+
+  const lines = f.ctx.text.split("\n").map((l) =>
+    l.endsWith("\r") ? l.slice(0, -1) : l
+  );
+  const lineIdx = Math.max(0, Math.min(lines.length - 1, f.location.line - 1));
+
+  const startLine = Math.max(0, lineIdx - contextLines);
+  const endLine = Math.min(lines.length - 1, lineIdx + contextLines);
+  const maxLineNo = endLine + 1;
+  const lineNoWidth = String(maxLineNo).length;
+
+  const header =
+    `expected ${f.expected} at line ${f.location.line}, column ${f.location.column}`;
+  const out: string[] = [
+    color ? `${ansi.red}${header}${ansi.reset}` : header,
+  ];
+
+  for (let i = startLine; i <= endLine; i++) {
+    const rawLine = lines[i] ?? "";
+    const printedLine = expandTabs(rawLine, tabWidth);
+    const lineNo = String(i + 1).padStart(lineNoWidth, " ");
+
+    out.push(
+      color
+        ? `${ansi.dim}${lineNo}${ansi.reset} | ${printedLine}`
+        : `${lineNo} | ${printedLine}`,
+    );
+
+    if (i === lineIdx) {
+      // 1-based column -> prefix length in original line (clamped).
+      const rawPrefixLen = Math.max(
+        0,
+        Math.min(rawLine.length, f.location.column - 1),
+      );
+      const rawPrefix = rawLine.slice(0, rawPrefixLen);
+      const caretPos = expandTabs(rawPrefix, tabWidth).length;
+
+      const gutter = " ".repeat(lineNoWidth);
+      const caretLine = `${gutter} | ${" ".repeat(caretPos)}^`;
+      out.push(color ? `${ansi.yellow}${caretLine}${ansi.reset}` : caretLine);
+    }
+  }
+
+  return out.join("\n");
+};

tests/error_stack.test.ts

@@ -7,6 +7,7 @@ import {
   failure,
   fatalFailure,
   formatErrorCompact,
+  formatErrorSnippet,
   formatErrorStack,
   getLocation,
   isFatal,
@@ -103,6 +104,32 @@ Deno.test("formatErrorCompact produces single-line output", () => {
   assertEquals(compact.includes("1:"), true);
 });
 
+Deno.test("formatErrorSnippet shows +/- 1 line context and a caret", () => {
+  const text = ["aaa", "bbb", "ccc"].join("\n");
+  const f = failure({ text, index: 5 }, "'x'"); // line 2, column 2
+
+  const snippet = formatErrorSnippet(f, { contextLines: 1, tabWidth: 2 });
+
+  assertEquals(snippet.includes("expected 'x' at line 2, column 2"), true);
+  assertEquals(snippet.includes("1 | aaa"), true);
+  assertEquals(snippet.includes("2 | bbb"), true);
+  assertEquals(snippet.includes("3 | ccc"), true);
+  assertEquals(snippet.includes("  |  ^"), true);
+});
+
+Deno.test("formatErrorSnippet handles CRLF and tab expansion", () => {
+  const text = "a\r\n\tb\r\nc\r\n";
+  const f = failure({ text, index: 4 }, "boom"); // line 2, column 2 (after '\t')
+
+  const snippet = formatErrorSnippet(f, { contextLines: 1, tabWidth: 2 });
+
+  // No stray '\r' in rendered lines.
+  assertEquals(snippet.includes("\r"), false);
+  // Tab rendered as 2 spaces, caret aligned after them.
+  assertEquals(snippet.includes("2 |   b"), true);
+  assertEquals(snippet.includes("  |   ^"), true);
+});
+
 Deno.test("context combinator adds context on failure", () => {
   const parser = context("in greeting", str("hello"));
   const result = parser({ text: "world", index: 0 });