@dgpholdings/greatoak-shared 1.2.15 → 1.2.17

package/dist/utils/scoring/calculateQualityScore.js

@@ -0,0 +1,333 @@
+"use strict";
+// calculateQualityScore.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateQualityScore = calculateQualityScore;
+const constants_1 = require("./constants");
+const helpers_1 = require("./helpers");
+// ---------------------------------------------------------------------------
+// Main Quality Calculation
+// ---------------------------------------------------------------------------
+/**
+ * Calculate the overall quality score and its breakdown.
+ *
+ * @param parsedSets        Cleaned sets (from parseRecords) — only completed sets
+ * @param rawRecords        Original TRecord[] — needed for completion count (includes skipped)
+ * @param timingGuardrails  Exercise's guardrails — for rest period validation
+ * @returns                 { score: 0–100, breakdown: { completion, consistency, effortAdequacy, restDiscipline } }
+ *
+ * @example
+ * const { score, breakdown } = calculateQualityScore(parsed, raw, guardrails);
+ * // score: 81
+ * // breakdown: { completion: 100, consistency: 75, effortAdequacy: 80, restDiscipline: 73 }
+ */
+function calculateQualityScore(parsedSets, rawRecords, timingGuardrails) {
+    // Edge case: no records at all
+    if (rawRecords.length === 0) {
+        return {
+            score: 0,
+            breakdown: {
+                completion: 0,
+                consistency: 0,
+                effortAdequacy: 0,
+                restDiscipline: 0,
+            },
+        };
+    }
+    // Edge case: records exist but NONE were completed
+    // If you didn't do a single set, the score is 0 — no partial credit
+    // from consistency/rest defaults
+    if (parsedSets.length === 0) {
+        return {
+            score: 0,
+            breakdown: {
+                completion: 0,
+                consistency: 0,
+                effortAdequacy: 0,
+                restDiscipline: 0,
+            },
+        };
+    }
+    const completion = calculateCompletion(parsedSets, rawRecords);
+    const consistency = calculateConsistency(parsedSets);
+    const effortAdequacy = calculateEffortAdequacy(rawRecords);
+    const restDiscipline = calculateRestDiscipline(parsedSets, timingGuardrails);
+    const score = Math.round(completion * constants_1.QUALITY_WEIGHTS.completion +
+        consistency * constants_1.QUALITY_WEIGHTS.consistency +
+        effortAdequacy * constants_1.QUALITY_WEIGHTS.effortAdequacy +
+        restDiscipline * constants_1.QUALITY_WEIGHTS.restDiscipline);
+    return {
+        score: (0, helpers_1.clamp)(score, 0, 100),
+        breakdown: {
+            completion: Math.round(completion),
+            consistency: Math.round(consistency),
+            effortAdequacy: Math.round(effortAdequacy),
+            restDiscipline: Math.round(restDiscipline),
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Component A: Completion (0–100)
+// ---------------------------------------------------------------------------
+/**
+ * Did the user complete all their sets?
+ *
+ * Simple ratio: completedSets / totalSets × 100
+ *
+ * This rewards finishing what you started. Skipping sets tanks the score.
+ *
+ * Uses rawRecords.length as total (includes isDone:false) and
+ * parsedSets.length as completed (only isDone:true after filtering).
+ */
+function calculateCompletion(parsedSets, rawRecords) {
+    const total = rawRecords.length;
+    if (total === 0)
+        return 0;
+    const completed = parsedSets.length;
+    return (completed / total) * 100;
+}
+// ---------------------------------------------------------------------------
+// Component B: Consistency (0–100)
+// ---------------------------------------------------------------------------
+/**
+ * Were sets consistent in performance output?
+ *
+ * Measures the coefficient of variation (CV) of the per-set "output metric".
+ * CV = 0 → perfectly consistent → score 100
+ * CV = 0.50 → very variable → score ~0 (clamped to minimum)
+ *
+ * The "output metric" depends on exercise type:
+ *   weight-reps:   kg × reps (volume per set)
+ *   reps-only:     reps (aux weight change is intentional, so just reps)
+ *   duration:      durationSecs
+ *   cardio-machine: avg speed (speedMin + speedMax) / 2
+ *   cardio-free:    effective speed (distance / time)
+ *
+ * SPECIAL CASE — Progressive overload detection:
+ * If values are monotonically increasing (warming up / pyramiding UP)
+ * or monotonically decreasing (drop sets / fatigue), this is INTENTIONAL.
+ * We don't penalize it — instead, we floor the score at 75.
+ * Requires ≥ 3 sets to detect (2 sets are always monotonic).
+ *
+ * SINGLE SET: Returns 100 (nothing to compare against).
+ */
+function calculateConsistency(parsedSets) {
+    if (parsedSets.length <= 1)
+        return 100;
+    const values = parsedSets.map(extractConsistencyMetric);
+    // Filter out zero/invalid values
+    const validValues = values.filter((v) => v > 0);
+    if (validValues.length <= 1)
+        return 100;
+    // Calculate coefficient of variation
+    const cv = (0, helpers_1.coefficientOfVariation)(validValues);
+    // Base score: penalize variance
+    let score = (0, helpers_1.clamp)(100 - cv * constants_1.CONSISTENCY_CV_PENALTY, constants_1.CONSISTENCY_MIN_SCORE, 100);
+    // Progressive overload / intentional progression detection
+    if (validValues.length >= 3) {
+        const isMonotonicallyIncreasing = isMonotonic(validValues, "asc");
+        const isMonotonicallyDecreasing = isMonotonic(validValues, "desc");
+        if (isMonotonicallyIncreasing || isMonotonicallyDecreasing) {
+            score = Math.max(score, constants_1.PROGRESSIVE_OVERLOAD_FLOOR);
+        }
+    }
+    return score;
+}
+/**
+ * Extract the consistency metric for a set based on its type.
+ */
+function extractConsistencyMetric(set) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    switch (set.type) {
+        case "weight-reps": {
+            // Volume per set: weight × reps
+            const kg = (_a = set.kg) !== null && _a !== void 0 ? _a : 0;
+            const reps = (_b = set.reps) !== null && _b !== void 0 ? _b : 0;
+            return kg * reps;
+        }
+        case "reps-only": {
+            // Just reps (aux weight changes are intentional, not inconsistency)
+            return (_c = set.reps) !== null && _c !== void 0 ? _c : 0;
+        }
+        case "duration": {
+            // Hold duration
+            return (_d = set.durationSecs) !== null && _d !== void 0 ? _d : set.activeDurationSecs;
+        }
+        case "cardio-machine": {
+            // Average speed
+            const speedMin = (_e = set.speedMin) !== null && _e !== void 0 ? _e : 0;
+            const speedMax = (_f = set.speedMax) !== null && _f !== void 0 ? _f : 0;
+            return (speedMin + speedMax) / 2;
+        }
+        case "cardio-free": {
+            // Effective speed (km/h)
+            const distance = (_g = set.distance) !== null && _g !== void 0 ? _g : 0;
+            const durationSecs = (_h = set.cardioDurationSecs) !== null && _h !== void 0 ? _h : set.activeDurationSecs;
+            if (durationSecs > 0 && distance > 0) {
+                return distance / (durationSecs / 3600);
+            }
+            return 0;
+        }
+        default:
+            return 0;
+    }
+}
+/**
+ * Check if an array of numbers is monotonically increasing or decreasing.
+ * "Allowing equal" — [10, 10, 12] counts as ascending.
+ */
+function isMonotonic(values, direction) {
+    for (let i = 1; i < values.length; i++) {
+        if (direction === "asc" && values[i] < values[i - 1])
+            return false;
+        if (direction === "desc" && values[i] > values[i - 1])
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Component C: Effort Adequacy (0–100)
+// ---------------------------------------------------------------------------
+/**
+ * Was the user working in a productive effort zone?
+ *
+ * The "productive zone" for most training goals:
+ *   RIR 1–4: close enough to failure to stimulate adaptation, not so close
+ *            that recovery is impaired
+ *   RPE 6–9: same concept from the subjective side
+ *
+ * Scoring per set:
+ * - Within optimal range → 100
+ * - Outside by 1 unit → 80
+ * - Outside by 2 units → 60
+ * - Outside by 3+ units → 40/20
+ *
+ * If neither RPE nor RIR is provided → 70 (neutral, can't confirm or deny).
+ *
+ * Uses RAW records (not parsed sets) because:
+ * 1. We need the original RPE/RIR strings
+ * 2. We only score completed sets (isDone === true)
+ */
+function calculateEffortAdequacy(rawRecords) {
+    const completedRecords = rawRecords.filter((r) => r.isDone);
+    if (completedRecords.length === 0)
+        return 0;
+    const setScores = [];
+    for (const record of completedRecords) {
+        setScores.push(scoreSetEffort(record));
+    }
+    // Average all set effort scores
+    return setScores.reduce((sum, s) => sum + s, 0) / setScores.length;
+}
+/**
+ * Score a single set's effort level.
+ *
+ * Priority: RIR > RPE > no data.
+ * For RIR: optimal range [1, 4]
+ * For RPE: optimal range [6, 9]
+ */
+function scoreSetEffort(record) {
+    // Try RIR first (more objective)
+    if (record.rir !== undefined && record.rir !== "") {
+        const rir = (0, helpers_1.safeParseFloat)(record.rir, -1);
+        if (rir >= 0) {
+            return scoreAgainstRange(rir, constants_1.OPTIMAL_RIR_RANGE);
+        }
+    }
+    // Try RPE
+    if (record.rpe !== undefined && record.rpe !== "") {
+        const rpe = (0, helpers_1.safeParseFloat)(record.rpe, -1);
+        if (rpe >= 1) {
+            return scoreAgainstRange(rpe, constants_1.OPTIMAL_RPE_RANGE);
+        }
+    }
+    // No effort data — neutral score
+    return constants_1.EFFORT_NO_DATA_SCORE;
+}
+/**
+ * Score a value against an optimal range.
+ *
+ * Within [min, max] → 100
+ * Distance 1 outside → 100 - penalty
+ * Distance 2 outside → 100 - 2×penalty
+ * etc., floored at EFFORT_MIN_SCORE
+ */
+function scoreAgainstRange(value, range) {
+    const [min, max] = range;
+    if (value >= min && value <= max)
+        return 100;
+    // Distance from nearest edge of the range
+    const distance = value < min ? min - value : value - max;
+    return Math.max(100 - distance * constants_1.EFFORT_DISTANCE_PENALTY, constants_1.EFFORT_MIN_SCORE);
+}
+// ---------------------------------------------------------------------------
+// Component D: Rest Discipline (0–100)
+// ---------------------------------------------------------------------------
+/**
+ * Were rest periods within the exercise's optimal windows?
+ *
+ * Uses the exercise's timingGuardrails.restPeriods:
+ *   optimalRange [min, max] → 100 points
+ *   within [minimum, maximum] → 60–100 (proportional to how close to optimal)
+ *   outside [minimum, maximum] → 30 points
+ *
+ * Only scores sets that HAVE rest data (last set often doesn't).
+ * If no valid rest data exists at all → neutral 65.
+ *
+ * The stressRestBonus from timingGuardrails is applied as a final multiplier:
+ * exercises where proper rest is especially important (heavy compounds)
+ * get a boost when rest is done right.
+ */
+function calculateRestDiscipline(parsedSets, timingGuardrails) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    // Gather sets that have rest data (non-null)
+    const setsWithRest = parsedSets.filter((s) => s.restDurationSecs !== null);
+    if (setsWithRest.length === 0)
+        return constants_1.REST_NO_DATA_SCORE;
+    // Extract rest period bounds from guardrails
+    const restConfig = timingGuardrails === null || timingGuardrails === void 0 ? void 0 : timingGuardrails.restPeriods;
+    const optimalMin = (_b = (_a = restConfig === null || restConfig === void 0 ? void 0 : restConfig.optimalRange) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : ((_c = restConfig === null || restConfig === void 0 ? void 0 : restConfig.typical) !== null && _c !== void 0 ? _c : constants_1.FALLBACK_REST_SECS) * 0.75;
+    const optimalMax = (_e = (_d = restConfig === null || restConfig === void 0 ? void 0 : restConfig.optimalRange) === null || _d === void 0 ? void 0 : _d[1]) !== null && _e !== void 0 ? _e : ((_f = restConfig === null || restConfig === void 0 ? void 0 : restConfig.typical) !== null && _f !== void 0 ? _f : constants_1.FALLBACK_REST_SECS) * 1.25;
+    const acceptableMin = (_g = restConfig === null || restConfig === void 0 ? void 0 : restConfig.minimum) !== null && _g !== void 0 ? _g : optimalMin * 0.5;
+    const acceptableMax = (_h = restConfig === null || restConfig === void 0 ? void 0 : restConfig.maximum) !== null && _h !== void 0 ? _h : optimalMax * 2;
+    const setScores = [];
+    for (const set of setsWithRest) {
+        const rest = set.restDurationSecs; // Guaranteed non-null by filter
+        if (rest >= optimalMin && rest <= optimalMax) {
+            // Within optimal range → perfect score
+            setScores.push(constants_1.REST_OPTIMAL_SCORE);
+        }
+        else if (rest >= acceptableMin && rest <= acceptableMax) {
+            // Within acceptable range but not optimal
+            // Score proportionally based on how close to optimal
+            let ratio;
+            if (rest < optimalMin) {
+                // Between acceptable min and optimal min
+                ratio = (rest - acceptableMin) / (optimalMin - acceptableMin);
+            }
+            else {
+                // Between optimal max and acceptable max
+                ratio = (acceptableMax - rest) / (acceptableMax - optimalMax);
+            }
+            setScores.push(constants_1.REST_ACCEPTABLE_BASE +
+                ratio * (constants_1.REST_OPTIMAL_SCORE - constants_1.REST_ACCEPTABLE_BASE));
+        }
+        else {
+            // Outside even the acceptable range
+            setScores.push(constants_1.REST_OUTSIDE_SCORE);
+        }
+    }
+    // Average rest scores
+    let avgScore = setScores.reduce((sum, s) => sum + s, 0) / setScores.length;
+    // Apply stressRestBonus: exercises where proper rest matters more
+    // get a boost (capped at 100). E.g., bench press stressRestBonus=1.3
+    // means good rest is 30% more valuable for this exercise.
+    // We only apply this as a REWARD (when score > 60), not to amplify bad rest.
+    const stressRestBonus = (_j = timingGuardrails === null || timingGuardrails === void 0 ? void 0 : timingGuardrails.stressRestBonus) !== null && _j !== void 0 ? _j : 1.0;
+    if (avgScore > 60 && stressRestBonus > 1.0) {
+        // Scale the "above baseline" portion by the bonus
+        const baseline = 60;
+        const aboveBaseline = avgScore - baseline;
+        avgScore = baseline + aboveBaseline * stressRestBonus;
+    }
+    return (0, helpers_1.clamp)(avgScore, 0, 100);
+}

package/dist/utils/scoring/constants.d.ts

@@ -0,0 +1,191 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Constants
+ * ============================================================================
+ *
+ * All magic numbers, default values, and tuning parameters live here.
+ * When we need to adjust scoring behavior, this is the ONLY file to change.
+ *
+ * Naming convention:
+ *   DEFAULT_*   = user-related fallbacks (weight, height, age)
+ *   FALLBACK_*  = exercise timing fallbacks (only when timingGuardrails is missing)
+ *   ABSOLUTE_*  = hard safety bounds (catches truly broken data)
+ *   QUALITY_*   = quality score weights and thresholds
+ *   FACTOR_*    = multipliers used in formulas
+ */
+/** Average adult weight when user hasn't provided theirs */
+export declare const DEFAULT_USER_WEIGHT_KG = 70;
+/** Average adult height */
+export declare const DEFAULT_USER_HEIGHT_CM = 170;
+/** Assumed age when DOB is missing */
+export declare const DEFAULT_USER_AGE = 30;
+/** Seconds per rep when timingGuardrails.singleRep is missing entirely */
+export declare const FALLBACK_SECS_PER_REP = 3;
+/** Set duration when timingGuardrails.setDuration is missing entirely */
+export declare const FALLBACK_SET_DURATION_SECS = 30;
+/** Rest period when timingGuardrails.restPeriods is missing entirely */
+export declare const FALLBACK_REST_SECS = 90;
+/** Fatigue multiplier when timingGuardrails.fatigueMultiplier is missing */
+export declare const FALLBACK_FATIGUE_MULTIPLIER = 1;
+/** Stress rest bonus when timingGuardrails.stressRestBonus is missing */
+export declare const FALLBACK_STRESS_REST_BONUS = 1;
+/**
+ * Absolute sanity bounds — these catch truly absurd sensor/input errors
+ * that even the exercise's own guardrails wouldn't expect.
+ * These are NOT the exercise's min/max; they're a safety net.
+ *
+ * Example: a restDurationSecs of 86400 (24 hours) is clearly a bug,
+ * regardless of what the exercise's guardrails say.
+ */
+export declare const ABSOLUTE_REST_MIN = 0;
+export declare const ABSOLUTE_REST_MAX = 3600;
+export declare const ABSOLUTE_WORK_MIN = 1;
+export declare const ABSOLUTE_WORK_MAX = 14400;
+/**
+ * Effort fraction when neither RPE nor RIR is provided.
+ * 0.6 = moderate effort assumption.
+ */
+export declare const DEFAULT_EFFORT_FRACTION = 0.6;
+/**
+ * Exponent for non-linear RPE/RIR → effort conversion.
+ * Values > 1.0 make the last reps near failure disproportionately harder,
+ * which matches real physiology (RPE 9→10 is a bigger jump than 5→6).
+ */
+export declare const EFFORT_CURVE_EXPONENT = 1.3;
+/**
+ * Effort fraction output range.
+ * effort = BASE + RANGE × (normalized_input ^ EXPONENT)
+ */
+export declare const EFFORT_FRACTION_BASE = 0.5;
+export declare const EFFORT_FRACTION_RANGE = 0.8;
+/**
+ * MET value during rest periods.
+ * Not true resting (1.0) because the body is still elevated after a set.
+ * 1.5 accounts for elevated heart rate and recovery metabolism.
+ */
+export declare const REST_MET = 1.5;
+/**
+ * Default weight intensity multipliers when metabolicData.weightFactors
+ * is missing. Keyed by intensity category.
+ */
+export declare const DEFAULT_WEIGHT_FACTORS: {
+    light: number;
+    moderate: number;
+    heavy: number;
+};
+/** Thresholds for weight category classification (as ratio of bodyweight) */
+export declare const WEIGHT_CATEGORY_THRESHOLDS: {
+    lightMax: number;
+    moderateMax: number;
+};
+/**
+ * Default duration multipliers when metabolicData.durationFactors is missing.
+ */
+export declare const DEFAULT_DURATION_FACTORS: {
+    short: number;
+    medium: number;
+    long: number;
+};
+/** Thresholds for duration category classification (in seconds) */
+export declare const DURATION_CATEGORY_THRESHOLDS: {
+    shortMax: number;
+    mediumMax: number;
+};
+/**
+ * For reps-only / bodyweight exercises: how much of bodyweight is "the load".
+ * Scaled by exercise difficultyLevel (0–4):
+ *   load = (difficultyLevel / 4) × BW_FRACTION_SCALE × userWeightKg
+ *
+ * difficulty 0 → 0.0 × 0.65 = 0% (basically no BW load, e.g. finger exercise)
+ * difficulty 1 → 0.25 × 0.65 = 16% (light BW, e.g. easy crunches)
+ * difficulty 2 → 0.50 × 0.65 = 33% (moderate, e.g. push-ups)
+ * difficulty 4 → 1.00 × 0.65 = 65% (heavy, e.g. pistol squats)
+ */
+export declare const BW_FRACTION_SCALE = 0.65;
+/**
+ * Expected min/max speed range for cardio (km/h) when paceFactors are missing.
+ * Used to normalize speed into a 0–1 fraction for MET interpolation.
+ */
+export declare const CARDIO_SPEED_RANGE: {
+    min: number;
+    max: number;
+};
+/** Fraction of total fatigue stimulus allocated to primary muscles */
+export declare const PRIMARY_MUSCLE_ALLOCATION = 1;
+/** Fraction of total fatigue stimulus allocated to secondary muscles */
+export declare const SECONDARY_MUSCLE_ALLOCATION = 0.35;
+/**
+ * Diminishing returns decay rate for consecutive sets.
+ * setDecay = 1 / (1 + DECAY_RATE × setIndex)
+ *
+ * With 0.15:  set0=1.00, set1=0.87, set2=0.77, set3=0.69, set4=0.63
+ */
+export declare const SET_FATIGUE_DECAY_RATE = 0.15;
+/**
+ * Cardio exercises create cardiovascular fatigue, not the same mechanical
+ * muscle fatigue as strength training. A 30-minute jog doesn't fatigue
+ * your quads the way 5 sets of heavy squats does.
+ *
+ * This dampener reduces the volume-load contribution of cardio exercises
+ * so their muscle fatigue scores are proportional to actual muscle damage/stress.
+ *
+ * 0.3 means cardio produces ~30% of the muscle fatigue that an equivalent
+ * "volume" of strength work would.
+ */
+export declare const CARDIO_MUSCLE_FATIGUE_DAMPENER = 0.3;
+/**
+ * Reference max scaling by difficulty level.
+ * Maps difficultyLevel (0–4) → expected max weight as a fraction of bodyweight.
+ *
+ * This makes fatigue normalization exercise-aware:
+ * - Bicep curl (difficulty 1) → ref weight ~0.6× BW → smaller denominator → fair score
+ * - Squat (difficulty 3)      → ref weight ~1.2× BW → larger denominator → fair score
+ */
+export declare const DIFFICULTY_TO_WEIGHT_FRACTION: (difficulty: number) => number;
+/** Reference set count for "fully fatigued" benchmark */
+export declare const REFERENCE_MAX_SETS = 5;
+/** Reference rep count for "fully fatigued" benchmark */
+export declare const REFERENCE_MAX_REPS = 12;
+/** Reference effort multiplier for "fully fatigued" benchmark */
+export declare const REFERENCE_MAX_EFFORT = 1.3;
+/**
+ * Weights for the four quality sub-components.
+ * Must sum to 1.0.
+ */
+export declare const QUALITY_WEIGHTS: {
+    completion: number;
+    consistency: number;
+    effortAdequacy: number;
+    restDiscipline: number;
+};
+/**
+ * Consistency scoring: how aggressively CV (coefficient of variation) is penalized.
+ * consistencyScore = 100 - CV × PENALTY
+ * CV 0.0 → 100, CV 0.15 → 70, CV 0.50 → 0
+ */
+export declare const CONSISTENCY_CV_PENALTY = 200;
+/** Minimum consistency score (even very inconsistent sets get some credit) */
+export declare const CONSISTENCY_MIN_SCORE = 20;
+/** Floor score for intentional progressive/descending sets (≥3 sets) */
+export declare const PROGRESSIVE_OVERLOAD_FLOOR = 75;
+/**
+ * Optimal RIR range for effort adequacy scoring.
+ * Within this range → 100 points. Outside → penalized by distance.
+ */
+export declare const OPTIMAL_RIR_RANGE: [number, number];
+/** Optimal RPE range for effort adequacy scoring. */
+export declare const OPTIMAL_RPE_RANGE: [number, number];
+/** Penalty per unit of distance from the optimal effort range */
+export declare const EFFORT_DISTANCE_PENALTY = 20;
+/** Minimum effort adequacy score */
+export declare const EFFORT_MIN_SCORE = 20;
+/** Default effort adequacy score when no RPE/RIR data is available */
+export declare const EFFORT_NO_DATA_SCORE = 70;
+/** Score when rest is within the optimal range */
+export declare const REST_OPTIMAL_SCORE = 100;
+/** Score when rest is within acceptable (min–max) but not optimal */
+export declare const REST_ACCEPTABLE_BASE = 60;
+/** Score when rest is completely outside the acceptable range */
+export declare const REST_OUTSIDE_SCORE = 30;
+/** Default rest discipline score when no valid rest data exists */
+export declare const REST_NO_DATA_SCORE = 65;