AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools JSON Diff Agent Guide

Agent guide for deep JSON comparison with added, removed, and changed dot-path lists.

AGENTS.md

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

Project overview

This guide covers src/tools/json-diff. diffJson parses left and right JSON strings, defaults blank input to null, walks objects by merged key set, walks arrays by index, records added, removed, and changed paths, and reports root changes as (root).

Primary source files

  • src/tools/json-diff/index.ts defines meta, DiffResult, diffJson, isObject, and deepEqual.
  • src/tools/json-diff/index.test.ts covers added keys, removed keys, changed values, invalid left JSON, invalid right JSON, nested changes, and identical objects.
  • src/tools/json-diff/Body.astro owns textareas, compare action, sample behavior, and result sections.
  • src/tools/json-diff/i18n.ts owns localized labels.
  • src/lib/tools.ts registers the tool metadata.

Setup commands

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

Change rules

  • Return ok false with Left JSON error when the left side cannot parse.
  • Return ok false with Right JSON error when the right side cannot parse.
  • Treat blank JSON input as null in the pure helper.
  • Use dot notation for object paths.
  • Use bracket notation for array indices.
  • Use (root) when the root value changes.
  • Do not add fuzzy or order-insensitive comparison without separate options and tests.

Testing

Test invalid JSON on both sides, blank inputs, added and removed nested keys, array additions and removals, root changes, identical values, object key order, and UI result grouping.

PR checklist

  • npm test passes for json-diff.
  • Pure helper behavior and browser UI behavior are aligned.
  • Generated CSS, Markdown, JSON, or image output remains browser-local.
  • Invalid input, copy behavior, and privacy expectations are covered.