AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Text Diff Agent Guide

Agent guide for line-based LCS diffing and responsive size limits.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Text Diff in the alexandrai-tools project.

Project overview

This guide covers src/tools/text-diff/index.ts. The tool splits input into lines, builds a longest-common-subsequence table, backtracks into unified diff lines marked equal, added, or deleted, and exposes safeDiffLines to reject inputs whose dynamic-programming table would exceed MAX_DIFF_CELLS.

Primary source files

  • src/tools/text-diff/index.ts defines meta, DiffType, DiffLine, MAX_DIFF_CELLS, SafeDiffResult, diffLines, and safeDiffLines.
  • src/tools/text-diff/index.test.ts covers basic diffs, all equal, all added, all deleted, both empty, safe limits, and over-limit rejection.
  • src/tools/text-diff/Body.astro owns the browser compare UI.
  • src/tools/text-diff/i18n.ts owns localized copy.
  • src/lib/tools.ts registers metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Keep diffLines pure and deterministic.
  • Use safeDiffLines from UI code when comparing user-entered text.
  • Keep MAX_DIFF_CELLS enforced before allocating the LCS table.
  • Represent output with eq, add, and del types.
  • Do not upload compared text or log diff contents.
  • If character-level diffing is added, keep it separate from line-level output.
  • When optimizing memory, preserve current ordering and tie behavior unless tests change deliberately.

Testing

Test equal lines, additions, deletions, replacements, empty left, empty right, both empty, duplicate lines, over-limit input, boundary-size input, and UI rendering for each diff type.

PR checklist

  • npm test passes for text-diff.
  • Large inputs are rejected before heavy allocation.
  • Diff output keeps stable order.
  • Compared text remains browser-local.