AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Word Frequency Counter Agent Guide

Agent guide for case-insensitive word frequency analysis with punctuation stripping and deterministic sorting.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Word Frequency Counter in the alexandrai-tools project.

Project overview

This guide covers src/tools/word-frequency-counter/index.ts. The tool splits text on whitespace, strips leading and trailing non-letter and non-number characters with Unicode-aware regular expressions, lowercases tokens, counts them in a map, and returns results sorted by count descending with alphabetical tie breaks.

Primary source files

  • src/tools/word-frequency-counter/index.ts defines meta, WordFrequency, and wordFrequencies.
  • src/tools/word-frequency-counter/index.test.ts covers simple counts, case-insensitivity, punctuation stripping, descending sort, alphabetical ties, empty input, punctuation-only tokens, and a classic repeated-word phrase.
  • src/tools/word-frequency-counter/Body.astro owns browser controls.
  • src/tools/word-frequency-counter/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

  • Return an empty array for empty or whitespace-only input.
  • Split only on whitespace.
  • Strip punctuation only from token edges.
  • Use Unicode letter and number classes for token edge detection.
  • Lowercase tokens before counting.
  • Sort by descending count, then alphabetical word order.
  • If stop words or stemming are added, keep them optional and off by default unless product copy changes.

Testing

Test simple counts, case folding, edge punctuation, internal punctuation, punctuation-only tokens, Unicode letters and numbers, count sorting, alphabetical ties, empty input, and optional filters if added.

PR checklist

  • npm test passes for word-frequency-counter.
  • Browser-local text processing remains browser-local.
  • Existing option defaults and edge-case semantics stay documented.
  • UI copy, metadata, and tests are updated together for behavior changes.