Address code review feedback: improve documentation and robustness

Co-authored-by: ankurrera <186232326+ankurrera@users.noreply.github.com>

Author: Copilot

src/hooks/useCoreMetrics.ts

@@ -71,19 +71,47 @@ function mapSkillToContributionData(skill: {
   };
 }
 
+/**
+ * Normalized mapping of characteristic names to Core Metric names
+ * Handles naming variations (e.g., 'Foreign Languages' -> 'Foreign Language')
+ */
+const CHARACTERISTIC_TO_METRIC_MAP: Record<string, CoreMetricName> = {
+  'programming': 'Programming',
+  'learning': 'Learning',
+  'erudition': 'Erudition',
+  'discipline': 'Discipline',
+  'productivity': 'Productivity',
+  'foreign language': 'Foreign Language',
+  'foreign languages': 'Foreign Language',
+  'language': 'Foreign Language',
+  'languages': 'Foreign Language',
+  'fitness': 'Fitness',
+  'drawing': 'Drawing',
+  'hygiene': 'Hygiene',
+  'reading': 'Reading',
+  'communication': 'Communication',
+  'cooking': 'Cooking',
+  'meditation': 'Meditation',
+  'swimming': 'Swimming',
+  'running': 'Running',
+  'math': 'Math',
+  'mathematics': 'Math',
+  'music': 'Music',
+  'cleaning': 'Cleaning',
+};
+
 /**
  * Map characteristic data to contribution format
- * Characteristics contribute to their namesake metric if it exists
+ * Uses a predefined mapping for reliable characteristic-to-metric matching
  */
 function mapCharacteristicToContributionData(char: {
   id: string;
   name: string;
   xp: number;
 }): CharacteristicContributionData {
-  // Check if the characteristic name matches a Core Metric
-  const metricName = PHYSICAL_BALANCE_METRICS.find(
-    m => m.toLowerCase() === char.name.toLowerCase()
-  );
+  // Use normalized lowercase name for lookup
+  const normalizedName = char.name.toLowerCase().trim();
+  const metricName = CHARACTERISTIC_TO_METRIC_MAP[normalizedName];
 
   return {
     id: char.id,

src/lib/coreMetricCalculation.ts

@@ -56,6 +56,14 @@ export interface ComputedCoreMetric extends CoreMetric {
 /**
  * Calculate level from XP using the standard formula
  * Level = floor(sqrt(XP / 100)) + 1
+ * 
+ * XP Thresholds:
+ * - Level 1: 0-99 XP
+ * - Level 2: 100-399 XP
+ * - Level 3: 400-899 XP
+ * - Level 4: 900-1599 XP
+ * - Level 5: 1600-2499 XP
+ * - Level 10: 8100-9999 XP
  */
 export function calculateMetricLevel(xp: number): number {
   return Math.floor(Math.sqrt(xp / 100)) + 1;

src/lib/coreMetrics.ts

@@ -97,14 +97,20 @@ export function getDefaultMapping(area: string | null): Partial<Record<CoreMetri
   return { 'Learning': 0.5, 'Discipline': 0.3, 'Productivity': 0.2 };
 }
 
+/**
+ * Floating point comparison tolerance for weight validation
+ * Used to account for JavaScript floating-point arithmetic imprecision
+ */
+const WEIGHT_SUM_TOLERANCE = 1.0001;
+
 /**
  * Validate that contribution weights sum to ≤ 1
  */
 export function validateContributionWeights(
   contributions: Partial<Record<CoreMetricName, number>>
 ): boolean {
   const sum = Object.values(contributions).reduce((acc, weight) => acc + (weight || 0), 0);
-  return sum <= 1.0001; // Small epsilon for floating point errors
+  return sum <= WEIGHT_SUM_TOLERANCE;
 }
 
 /**
@@ -116,7 +122,7 @@ export function normalizeContributionWeights(
   const result: Partial<Record<CoreMetricName, number>> = {};
   const sum = Object.values(contributions).reduce((acc, weight) => acc + (weight || 0), 0);
 
-  if (sum <= 1.0001) {
+  if (sum <= WEIGHT_SUM_TOLERANCE) {
     // Already valid, just copy
     for (const [key, value] of Object.entries(contributions)) {
       result[key as CoreMetricName] = value || 0;