AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Percentage Calculator in the alexandrai-tools project.

Project overview

This guide covers src/tools/percentage-calculator/index.ts. The tool exposes three pure helpers: percentOf returns percent divided by one hundred times a value, whatPercent returns part divided by whole times one hundred with a zero guard, and percentChange returns change relative to the absolute starting value with a zero guard.

Primary source files

• src/tools/percentage-calculator/index.ts defines meta, percentOf, whatPercent, and percentChange.
• src/tools/percentage-calculator/index.test.ts covers percent-of, zero percent, one hundred percent, what-percent, zero whole, equal part and whole, positive change, negative change, zero from, and no change.
• src/tools/percentage-calculator/Body.astro owns browser controls.
• src/tools/percentage-calculator/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 percentOf as percent divided by one hundred times the base number.
• Return zero from whatPercent when whole is zero.
• Compute whatPercent as part divided by whole times one hundred otherwise.
• Return zero from percentChange when from is zero.
• Use Math.abs(from) as the percentChange denominator.
• Allow negative outputs for decreases.
• If percentage difference is added, implement it as a separate helper.

Testing

Test zero, positive, negative, fractional, and one hundred percent cases, whole equal to zero, part equal to whole, positive and negative percent change, negative starting values, no change, and any new percentage-difference helper.

PR checklist

• npm test passes for percentage-calculator.
• Formula, invalid-input policy, and rounding policy remain documented.
• Pure helpers stay arithmetic-only and browser-local.
• UI labels, metadata, and tests update together for behavior changes.