AGENTS.md

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

Project overview

This guide covers src/tools/grade-calculator. calcRequiredFinal validates current grade, final weight, and desired grade, normalizes final weight from percent to decimal when needed, and solves the required final exam score using the weighted average equation.

Primary source files

• src/tools/grade-calculator/index.ts defines meta, FinalGradeResult, and calcRequiredFinal.
• src/tools/grade-calculator/index.test.ts covers percent weight, decimal weight, already-above-target cases, 100 percent final weight, zero weight, overweight, desired grade above 100, and current grade above 100.
• src/tools/grade-calculator/Body.astro owns numeric inputs and result display.
• src/tools/grade-calculator/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

• Reject final weights less than or equal to zero.
• Reject final weights greater than 100.
• Accept final weight as either decimal or percentage.
• Reject desired grades outside zero through 100.
• Reject current grades outside zero through 100.
• Return the raw required score even when it is above 100 or below zero.
• Keep result interpretation in UI copy rather than changing the pure calculation.

Testing

Test decimal and percentage weights, 100 percent final weight, required scores above 100, low required scores, all validation errors, boundary values, UI result interpretation, and displayed rounding.

PR checklist

• npm test passes for grade-calculator.
• Calculator formulas, units, and rounding rules are documented.
• Health and fitness outputs keep informational safety scope.
• UI labels, validation, and pure helper tests stay aligned.