AGENTS.md

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

Project overview

This guide covers src/tools/ratio-calculator/index.ts. The tool rounds inputs before its local GCD, rejects non-finite or non-positive ratio values, simplifies a:b by dividing both sides by the rounded GCD, and solves proportions of the form A:B = C:x with x equal to B times C divided by A.

Primary source files

• src/tools/ratio-calculator/index.ts defines meta, gcd, SimplifyResult, simplifyRatio, ProportionResult, and solveProportion.
• src/tools/ratio-calculator/index.test.ts covers GCD, equal values, already-simple ratios, zero and negative ratio errors, proportion solving, fractional results, and zero A errors.
• src/tools/ratio-calculator/Body.astro owns browser controls.
• src/tools/ratio-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

• Round inputs inside the ratio-local gcd helper.
• Use absolute values inside gcd.
• Return ok false for non-finite ratio values.
• Return ok false for zero or negative ratio values.
• Simplify by dividing original a and b by the computed gcd.
• Return ok false when A is zero in solveProportion.
• Allow solveProportion to return fractional x values.

Testing

Test GCD, rounded decimal inputs, simple ratios, already-simple ratios, equal values, zero values, negative values, non-finite values, proportion solving, fractional x, zero A, and negative proportion inputs if UI permits them.

PR checklist

• npm test passes for ratio-calculator.
• Return types, edge cases, and numeric limits remain documented.
• Pure math helpers stay browser-local and side-effect free.
• UI labels, metadata, and tests update together for behavior changes.