@butlerw/vellum 0.1.0

package/src/tui/components/Input/__tests__/highlight.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Tests for Input Highlight Utilities
+ */
+import { describe, expect, it } from "vitest";
+import {
+  applyHighlightStyle,
+  findSegmentAtCursor,
+  getHighlightStyleDescription,
+  type HighlightSegment,
+  highlightInput,
+  parseHighlights,
+  splitSegmentAtCursor,
+} from "../highlight.js";
+
+describe("highlight", () => {
+  describe("parseHighlights", () => {
+    it("returns empty segments for empty string", () => {
+      const result = parseHighlights("");
+      expect(result.segments).toHaveLength(0);
+      expect(result.hasHighlights).toBe(false);
+    });
+
+    it("returns plain text when no highlights", () => {
+      const result = parseHighlights("plain text here");
+      expect(result.segments).toHaveLength(1);
+      expect(result.segments[0]?.text).toBe("plain text here");
+      expect(result.segments[0]?.type).toBeUndefined();
+      expect(result.hasHighlights).toBe(false);
+    });
+
+    it("detects @mentions", () => {
+      const result = parseHighlights("Check @file.ts");
+      expect(result.hasHighlights).toBe(true);
+      const mention = result.segments.find((s: HighlightSegment) => s.type === "mention");
+      expect(mention?.text).toBe("@file.ts");
+    });
+
+    it("detects slash commands", () => {
+      const result = parseHighlights("Use /help command");
+      expect(result.hasHighlights).toBe(true);
+      const command = result.segments.find((s: HighlightSegment) => s.type === "command");
+      expect(command?.text).toBe("/help");
+    });
+
+    it("detects URLs", () => {
+      const result = parseHighlights("Visit https://example.com");
+      expect(result.hasHighlights).toBe(true);
+      const url = result.segments.find((s: HighlightSegment) => s.type === "url");
+      expect(url?.text).toBe("https://example.com");
+    });
+
+    it("detects http URLs", () => {
+      const result = parseHighlights("Visit http://example.com");
+      const url = result.segments.find((s: HighlightSegment) => s.type === "url");
+      expect(url?.text).toBe("http://example.com");
+    });
+
+    it("detects inline code", () => {
+      const result = parseHighlights("Run `npm install`");
+      expect(result.hasHighlights).toBe(true);
+      const code = result.segments.find((s: HighlightSegment) => s.type === "code");
+      expect(code?.text).toBe("`npm install`");
+    });
+
+    it("handles multiple highlights", () => {
+      const result = parseHighlights("Check @file.ts with /help");
+      expect(result.hasHighlights).toBe(true);
+      const mention = result.segments.find((s: HighlightSegment) => s.type === "mention");
+      const command = result.segments.find((s: HighlightSegment) => s.type === "command");
+      expect(mention?.text).toBe("@file.ts");
+      expect(command?.text).toBe("/help");
+    });
+
+    it("preserves text order", () => {
+      const result = parseHighlights("start @mid end");
+      expect(result.segments).toHaveLength(3);
+      expect(result.segments[0]?.text).toBe("start ");
+      expect(result.segments[1]?.text).toBe("@mid");
+      expect(result.segments[2]?.text).toBe(" end");
+    });
+
+    it("sets correct start and end positions", () => {
+      const result = parseHighlights("prefix @file suffix");
+      const mention = result.segments.find((s: HighlightSegment) => s.type === "mention");
+      expect(mention?.start).toBe(7);
+      expect(mention?.end).toBe(12);
+    });
+  });
+
+  describe("applyHighlightStyle", () => {
+    it("returns plain text for undefined type", () => {
+      const result = applyHighlightStyle("text");
+      expect(result).toBe("text");
+    });
+
+    it("applies style to mentions and returns text", () => {
+      const result = applyHighlightStyle("@file", "mention");
+      expect(result).toContain("@file");
+      // Result should contain the original text (chalk may or may not add ANSI codes depending on env)
+      expect(typeof result).toBe("string");
+    });
+
+    it("applies style to commands and returns text", () => {
+      const result = applyHighlightStyle("/help", "command");
+      expect(result).toContain("/help");
+      expect(typeof result).toBe("string");
+    });
+
+    it("applies style to URLs and returns text", () => {
+      const result = applyHighlightStyle("https://x.com", "url");
+      expect(result).toContain("https://x.com");
+      expect(typeof result).toBe("string");
+    });
+
+    it("applies style to code and returns text", () => {
+      const result = applyHighlightStyle("`code`", "code");
+      expect(result).toContain("`code`");
+      expect(typeof result).toBe("string");
+    });
+  });
+
+  describe("getHighlightStyleDescription", () => {
+    it('returns "plain" for undefined type', () => {
+      expect(getHighlightStyleDescription()).toBe("plain");
+      expect(getHighlightStyleDescription(undefined)).toBe("plain");
+    });
+
+    it("returns correct descriptions", () => {
+      expect(getHighlightStyleDescription("mention")).toBe("cyan");
+      expect(getHighlightStyleDescription("command")).toBe("green");
+      expect(getHighlightStyleDescription("url")).toBe("blue underline");
+      expect(getHighlightStyleDescription("code")).toBe("dim");
+    });
+  });
+
+  describe("highlightInput", () => {
+    it("returns styled string for input with highlights", () => {
+      const result = highlightInput("@file /help");
+      expect(result).toContain("@file");
+      expect(result).toContain("/help");
+    });
+
+    it("returns plain string for input without highlights", () => {
+      const result = highlightInput("plain text");
+      expect(result).toBe("plain text");
+    });
+
+    it("handles empty string", () => {
+      expect(highlightInput("")).toBe("");
+    });
+  });
+
+  describe("findSegmentAtCursor", () => {
+    const segments: HighlightSegment[] = [
+      { text: "start ", start: 0, end: 6 },
+      { text: "@file", type: "mention", start: 6, end: 11 },
+      { text: " end", start: 11, end: 15 },
+    ];
+
+    it("finds segment at cursor position", () => {
+      const seg = findSegmentAtCursor(segments, 7);
+      expect(seg?.text).toBe("@file");
+      expect(seg?.type).toBe("mention");
+    });
+
+    it("finds segment at start boundary", () => {
+      const seg = findSegmentAtCursor(segments, 6);
+      expect(seg?.text).toBe("@file");
+    });
+
+    it("returns undefined for position beyond segments", () => {
+      const seg = findSegmentAtCursor(segments, 100);
+      expect(seg).toBeUndefined();
+    });
+
+    it("handles empty segments array", () => {
+      const seg = findSegmentAtCursor([], 5);
+      expect(seg).toBeUndefined();
+    });
+  });
+
+  describe("splitSegmentAtCursor", () => {
+    const segment: HighlightSegment = {
+      text: "hello",
+      start: 0,
+      end: 5,
+    };
+
+    it("splits segment at cursor position", () => {
+      const result = splitSegmentAtCursor(segment, 2);
+      expect(result.before).toBe("he");
+      expect(result.cursorChar).toBe("l");
+      expect(result.after).toBe("lo");
+      expect(result.localPosition).toBe(2);
+    });
+
+    it("handles cursor at start", () => {
+      const result = splitSegmentAtCursor(segment, 0);
+      expect(result.before).toBe("");
+      expect(result.cursorChar).toBe("h");
+      expect(result.after).toBe("ello");
+    });
+
+    it("handles cursor at end", () => {
+      const result = splitSegmentAtCursor(segment, 5);
+      expect(result.before).toBe("hello");
+      expect(result.cursorChar).toBe(" "); // Default when past end
+      expect(result.after).toBe("");
+    });
+
+    it("handles segment with non-zero start", () => {
+      const seg: HighlightSegment = { text: "world", start: 10, end: 15 };
+      const result = splitSegmentAtCursor(seg, 12);
+      expect(result.before).toBe("wo");
+      expect(result.cursorChar).toBe("r");
+      expect(result.localPosition).toBe(2);
+    });
+  });
+});

package/src/tui/components/Input/__tests__/slash-command-utils.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for Slash Command Parsing Utilities
+ *
+ * Tests slash command parsing functionality.
+ */
+
+import { describe, expect, it } from "vitest";
+import { parseSlashCommand } from "../slash-command-utils.js";
+
+describe("parseSlashCommand", () => {
+  it("should parse simple command without arguments", () => {
+    const result = parseSlashCommand("/help");
+
+    expect(result).toEqual({
+      name: "help",
+      args: [],
+      raw: "/help",
+    });
+  });
+
+  it("should parse command with single argument", () => {
+    const result = parseSlashCommand("/search query");
+
+    expect(result).toEqual({
+      name: "search",
+      args: ["query"],
+      raw: "/search query",
+    });
+  });
+
+  it("should parse command with multiple arguments", () => {
+    const result = parseSlashCommand("/config set value true");
+
+    expect(result).toEqual({
+      name: "config",
+      args: ["set", "value", "true"],
+      raw: "/config set value true",
+    });
+  });
+
+  it("should handle double-quoted arguments with spaces", () => {
+    const result = parseSlashCommand('/search "hello world"');
+
+    expect(result).toEqual({
+      name: "search",
+      args: ["hello world"],
+      raw: '/search "hello world"',
+    });
+  });
+
+  it("should handle single-quoted arguments with spaces", () => {
+    const result = parseSlashCommand("/search 'hello world'");
+
+    expect(result).toEqual({
+      name: "search",
+      args: ["hello world"],
+      raw: "/search 'hello world'",
+    });
+  });
+
+  it("should handle mixed quoted and unquoted arguments", () => {
+    const result = parseSlashCommand('/filter "user name" --type admin');
+
+    expect(result.args).toEqual(["user name", "--type", "admin"]);
+  });
+
+  it("should handle escaped quotes within quoted strings", () => {
+    const result = parseSlashCommand('/echo "say \\"hello\\""');
+
+    expect(result.args).toEqual(['say "hello"']);
+  });
+
+  it("should handle escaped backslash", () => {
+    const result = parseSlashCommand("/path C:\\\\Users\\\\test");
+
+    expect(result.args).toEqual(["C:\\Users\\test"]);
+  });
+
+  it("should trim whitespace from input", () => {
+    const result = parseSlashCommand("  /help  ");
+
+    expect(result.name).toBe("help");
+    expect(result.raw).toBe("/help");
+  });
+
+  it("should handle multiple spaces between arguments", () => {
+    const result = parseSlashCommand("/cmd  arg1   arg2");
+
+    expect(result.args).toEqual(["arg1", "arg2"]);
+  });
+
+  it("should handle command with only spaces after name", () => {
+    const result = parseSlashCommand("/help   ");
+
+    expect(result.name).toBe("help");
+    expect(result.args).toEqual([]);
+  });
+
+  it("should handle flag-style arguments", () => {
+    const result = parseSlashCommand("/list --all -v --format=json");
+
+    expect(result.args).toEqual(["--all", "-v", "--format=json"]);
+  });
+});

package/src/tui/components/Input/highlight.ts

@@ -0,0 +1,362 @@
+/**
+ * Input Highlight Utilities (T009-HL)
+ *
+ * Provides text highlighting for special patterns in user input:
+ * - @mentions: File paths and folder references
+ * - Slash commands: /mode, /model, /help, etc.
+ * - URLs: http:// and https:// links
+ * - Inline code: `backtick-wrapped` code
+ *
+ * @module tui/components/Input/highlight
+ */
+
+import chalk from "chalk";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Types of highlightable patterns.
+ */
+export type HighlightType = "mention" | "command" | "url" | "code";
+
+/**
+ * A segment of highlighted text.
+ */
+export interface HighlightSegment {
+  /** The text content */
+  readonly text: string;
+  /** The type of highlight, or undefined for plain text */
+  readonly type?: HighlightType;
+  /** Start index in original string */
+  readonly start: number;
+  /** End index in original string (exclusive) */
+  readonly end: number;
+}
+
+/**
+ * Result of parsing input for highlights.
+ */
+export interface HighlightResult {
+  /** Array of text segments with highlight info */
+  readonly segments: readonly HighlightSegment[];
+  /** Whether any highlights were found */
+  readonly hasHighlights: boolean;
+}
+
+// =============================================================================
+// Patterns
+// =============================================================================
+// Caching
+// =============================================================================
+
+/**
+ * LRU cache for highlight results to avoid recomputing on every keystroke.
+ * Limited to 50 entries to prevent memory bloat.
+ */
+const HIGHLIGHT_CACHE_SIZE = 50;
+const highlightCache = new Map<string, HighlightResult>();
+
+/**
+ * Add result to cache with LRU eviction.
+ */
+function cacheResult(input: string, result: HighlightResult): void {
+  // Evict oldest entry if at capacity
+  if (highlightCache.size >= HIGHLIGHT_CACHE_SIZE) {
+    const firstKey = highlightCache.keys().next().value;
+    if (firstKey !== undefined) {
+      highlightCache.delete(firstKey);
+    }
+  }
+  highlightCache.set(input, result);
+}
+
+/**
+ * Get cached result if available.
+ */
+function getCachedResult(input: string): HighlightResult | undefined {
+  const cached = highlightCache.get(input);
+  if (cached) {
+    // Move to end for LRU (delete and re-add)
+    highlightCache.delete(input);
+    highlightCache.set(input, cached);
+  }
+  return cached;
+}
+
+// =============================================================================
+// Patterns
+// =============================================================================
+
+/**
+ * Pattern definitions for highlighting.
+ * Order matters - patterns are matched in priority order.
+ */
+const HIGHLIGHT_PATTERNS: readonly { type: HighlightType; pattern: RegExp }[] = [
+  // URLs: Match http:// or https:// followed by non-whitespace
+  {
+    type: "url",
+    pattern: /https?:\/\/[^\s]+/g,
+  },
+  // Inline code: Backtick-wrapped text (non-greedy, no nested backticks)
+  {
+    type: "code",
+    pattern: /`[^`]+`/g,
+  },
+  // Slash commands: /word at start of input or after whitespace
+  {
+    type: "command",
+    pattern: /(?:^|\s)(\/[a-zA-Z][a-zA-Z0-9_-]*)/g,
+  },
+  // @mentions: @path/to/file or @filename.ext
+  {
+    type: "mention",
+    pattern: /@[\w./-]+/g,
+  },
+];
+
+// =============================================================================
+// Core Functions
+// =============================================================================
+
+/**
+ * Find all highlight matches in the input text.
+ * Returns matches sorted by start position.
+ */
+function findMatches(
+  input: string
+): Array<{ type: HighlightType; start: number; end: number; text: string }> {
+  const matches: Array<{ type: HighlightType; start: number; end: number; text: string }> = [];
+
+  for (const { type, pattern } of HIGHLIGHT_PATTERNS) {
+    // Reset regex state
+    pattern.lastIndex = 0;
+    let match = pattern.exec(input);
+
+    while (match !== null) {
+      // For command pattern, we capture group 1 (the actual command without leading whitespace)
+      const text = type === "command" && match[1] ? match[1] : match[0];
+      const start =
+        type === "command" && match[1] ? match.index + match[0].indexOf(match[1]) : match.index;
+      const end = start + text.length;
+
+      matches.push({ type, start, end, text });
+      match = pattern.exec(input);
+    }
+  }
+
+  // Sort by start position
+  return matches.sort((a, b) => a.start - b.start);
+}
+
+/**
+ * Remove overlapping matches, keeping earlier/higher priority matches.
+ */
+function removeOverlaps(
+  matches: Array<{ type: HighlightType; start: number; end: number; text: string }>
+): Array<{ type: HighlightType; start: number; end: number; text: string }> {
+  const result: Array<{ type: HighlightType; start: number; end: number; text: string }> = [];
+
+  for (const match of matches) {
+    // Check if this match overlaps with any existing match
+    const overlaps = result.some(
+      (existing) => match.start < existing.end && match.end > existing.start
+    );
+
+    if (!overlaps) {
+      result.push(match);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse input text and identify highlighted segments.
+ * Results are cached to avoid redundant regex processing.
+ *
+ * @param input - The input text to parse
+ * @returns HighlightResult with segments and metadata
+ *
+ * @example
+ * ```ts
+ * const result = parseHighlights("Check @file.ts with /help");
+ * // result.segments = [
+ * //   { text: "Check ", start: 0, end: 6 },
+ * //   { text: "@file.ts", type: "mention", start: 6, end: 14 },
+ * //   { text: " with ", start: 14, end: 20 },
+ * //   { text: "/help", type: "command", start: 20, end: 25 }
+ * // ]
+ * ```
+ */
+export function parseHighlights(input: string): HighlightResult {
+  if (!input) {
+    return { segments: [], hasHighlights: false };
+  }
+
+  // Check cache first
+  const cached = getCachedResult(input);
+  if (cached) {
+    return cached;
+  }
+
+  const matches = removeOverlaps(findMatches(input));
+  const segments: HighlightSegment[] = [];
+  let currentPos = 0;
+
+  for (const match of matches) {
+    // Add plain text before this match
+    if (match.start > currentPos) {
+      segments.push({
+        text: input.slice(currentPos, match.start),
+        start: currentPos,
+        end: match.start,
+      });
+    }
+
+    // Add the highlighted segment
+    segments.push({
+      text: match.text,
+      type: match.type,
+      start: match.start,
+      end: match.end,
+    });
+
+    currentPos = match.end;
+  }
+
+  // Add remaining plain text
+  if (currentPos < input.length) {
+    segments.push({
+      text: input.slice(currentPos),
+      start: currentPos,
+      end: input.length,
+    });
+  }
+
+  const result: HighlightResult = {
+    segments,
+    hasHighlights: matches.length > 0,
+  };
+
+  // Cache the result for future lookups
+  cacheResult(input, result);
+
+  return result;
+}
+
+// =============================================================================
+// Styling Functions
+// =============================================================================
+
+/**
+ * Apply chalk styling to a highlight type.
+ *
+ * @param text - The text to style
+ * @param type - The highlight type
+ * @returns Styled string with ANSI codes
+ */
+export function applyHighlightStyle(text: string, type?: HighlightType): string {
+  if (!type) {
+    return text;
+  }
+
+  switch (type) {
+    case "mention":
+      return chalk.cyan(text);
+    case "command":
+      return chalk.green(text);
+    case "url":
+      return chalk.blue.underline(text);
+    case "code":
+      return chalk.dim(text);
+    default:
+      return text;
+  }
+}
+
+/**
+ * Get the style description for a highlight type (for accessibility/testing).
+ *
+ * @param type - The highlight type
+ * @returns Human-readable style description
+ */
+export function getHighlightStyleDescription(type?: HighlightType): string {
+  if (!type) {
+    return "plain";
+  }
+
+  switch (type) {
+    case "mention":
+      return "cyan";
+    case "command":
+      return "green";
+    case "url":
+      return "blue underline";
+    case "code":
+      return "dim";
+    default:
+      return "plain";
+  }
+}
+
+/**
+ * Apply highlights to input and return styled string.
+ * This is a convenience function for simple use cases.
+ *
+ * @param input - The input text to highlight
+ * @returns Styled string with ANSI codes
+ *
+ * @example
+ * ```ts
+ * const styled = highlightInput("Check @file.ts with /help");
+ * console.log(styled); // Cyan @file.ts, green /help
+ * ```
+ */
+export function highlightInput(input: string): string {
+  const { segments } = parseHighlights(input);
+  return segments.map((seg) => applyHighlightStyle(seg.text, seg.type)).join("");
+}
+
+// =============================================================================
+// Cursor-Aware Functions
+// =============================================================================
+
+/**
+ * Find which segment contains a given cursor position.
+ *
+ * @param segments - Array of highlight segments
+ * @param cursorPosition - The cursor position to locate
+ * @returns The segment containing the cursor, or undefined if not found
+ */
+export function findSegmentAtCursor(
+  segments: readonly HighlightSegment[],
+  cursorPosition: number
+): HighlightSegment | undefined {
+  return segments.find((seg) => cursorPosition >= seg.start && cursorPosition < seg.end);
+}
+
+/**
+ * Split a segment at a cursor position for rendering with cursor indicator.
+ *
+ * @param segment - The segment to split
+ * @param cursorPosition - The cursor position within the segment
+ * @returns Object with before, cursor char, and after portions
+ */
+export function splitSegmentAtCursor(
+  segment: HighlightSegment,
+  cursorPosition: number
+): {
+  before: string;
+  cursorChar: string;
+  after: string;
+  localPosition: number;
+} {
+  const localPosition = cursorPosition - segment.start;
+  const before = segment.text.slice(0, localPosition);
+  const cursorChar = segment.text[localPosition] || " ";
+  const after = segment.text.slice(localPosition + 1);
+
+  return { before, cursorChar, after, localPosition };
+}