AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools ROI Calculator Agent Guide

Agent guide for return on investment percentage and net gain calculation.

AGENTS.md

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

Project overview

This guide covers src/tools/roi-calculator/index.ts. The tool validates finite cost and gain values, rejects non-positive cost with null, computes netGain as gain minus cost, and computes roiPct as netGain divided by cost times one hundred.

Primary source files

  • src/tools/roi-calculator/index.ts defines meta, RoiResult, and calcRoi.
  • src/tools/roi-calculator/index.test.ts covers positive ROI, zero net gain, negative ROI, non-positive cost, and non-finite inputs.
  • src/tools/roi-calculator/Body.astro owns browser controls.
  • src/tools/roi-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

  • Return null for non-finite cost or gain.
  • Return null when cost is less than or equal to zero.
  • Allow gain to be lower than cost and produce negative ROI.
  • Compute netGain as gain minus cost.
  • Compute roiPct as netGain divided by cost times one hundred.
  • Do not round in pure calculation.
  • Keep this as arithmetic output, not investment guidance.

Testing

Test positive ROI, zero ROI, negative ROI, zero cost, negative cost, non-finite cost, non-finite gain, fractional inputs, large values, and UI formatting.

PR checklist

  • npm test passes for roi-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.