@willwade/aac-processors 0.0.16 → 0.0.18

package/dist/utilities/analytics/metrics/comparison.d.ts

@@ -5,6 +5,7 @@
  * analyze vocabulary differences, and generate CARE component scores.
  */
 import { MetricsResult, ComparisonResult } from './types';
+import { MetricsOptions } from './types';
 export declare class ComparisonAnalyzer {
     private vocabAnalyzer;
     private sentenceAnalyzer;
@@ -17,7 +18,7 @@ export declare class ComparisonAnalyzer {
     compare(targetResult: MetricsResult, compareResult: MetricsResult, options?: {
         includeSentences?: boolean;
         locale?: string;
-    }): ComparisonResult;
+    } & Partial<MetricsOptions>): ComparisonResult;
     /**
      * Calculate CARE component scores
      */

package/dist/utilities/analytics/metrics/comparison.js

@@ -10,6 +10,7 @@ exports.ComparisonAnalyzer = void 0;
 const sentence_1 = require("./sentence");
 const vocabulary_1 = require("./vocabulary");
 const index_1 = require("../reference/index");
+const effort_1 = require("./effort");
 class ComparisonAnalyzer {
     constructor() {
         this.vocabAnalyzer = new vocabulary_1.VocabularyAnalyzer();
@@ -79,7 +80,7 @@ class ComparisonAnalyzer {
             };
         });
         // Calculate CARE components
-        const careComponents = this.calculateCareComponents(targetResult, compareResult, overlappingWords);
+        const careComponents = this.calculateCareComponents(targetResult, compareResult, overlappingWords, options);
         // Analyze high/low effort words
         const highEffortWords = [];
         const lowEffortWords = [];
@@ -216,7 +217,42 @@ class ComparisonAnalyzer {
     /**
      * Calculate CARE component scores
      */
-    calculateCareComponents(targetResult, compareResult, _overlappingWords) {
+    calculateCareComponents(targetResult, compareResult, _overlappingWords, options) {
+        // Load common words with baseline efforts (matching Ruby line 527-534)
+        const commonWordsData = this.referenceLoader.loadCommonWords();
+        const commonWords = new Map();
+        commonWordsData.words.forEach((word) => {
+            commonWords.set(word.toLowerCase(), commonWordsData.efforts[word] || 0);
+        });
+        // Determine prediction settings (default: use common words efforts, not prediction)
+        const usePrediction = options?.usePrediction || false; // Default FALSE (use common words)
+        const predictionSelections = options?.predictionSelections || 1.5;
+        const debugMode = process.env.DEBUG_METRICS === 'true';
+        // Helper function to calculate fallback effort
+        const getFallbackEffort = (word, hasPrediction, spellingBaseEffort) => {
+            const wordLower = word.toLowerCase();
+            // Check common words efforts first (matching Ruby line 533)
+            if (commonWords.has(wordLower)) {
+                const effort = commonWords.get(wordLower);
+                return effort !== undefined ? effort : (0, effort_1.spellingEffort)(word, 10, 2.5);
+            }
+            // If usePrediction is true and prediction is available, use prediction
+            if (usePrediction && hasPrediction && spellingBaseEffort !== undefined) {
+                return (0, effort_1.predictionEffort)(spellingBaseEffort, 2.5, predictionSelections, 2);
+            }
+            // Fallback to manual spelling (matching Ruby spelling_effort: 10 + word.length * 2.5)
+            return (0, effort_1.spellingEffort)(word, 10, 2.5);
+        };
+        // Debug: Check settings
+        const targetHasPrediction = targetResult.has_dynamic_prediction && targetResult.spelling_effort_base !== undefined;
+        const _compareHasPrediction = compareResult.has_dynamic_prediction && compareResult.spelling_effort_base !== undefined;
+        if (debugMode) {
+            console.log(`\n🔍 DEBUG Fallback Effort Settings:`);
+            console.log(`  Common words loaded: ${commonWords.size}`);
+            console.log(`  usePrediction option: ${usePrediction}`);
+            console.log(`  Target has prediction capability: ${targetHasPrediction}`);
+            console.log(`  Target spelling_base: ${targetResult.spelling_effort_base?.toFixed(2) || 'undefined'}`);
+        }
         // Create word maps with normalized keys
         const targetWords = new Map();
         targetResult.buttons.forEach((btn) => {
@@ -237,62 +273,142 @@ class ComparisonAnalyzer {
         // Load reference data
         const coreLists = this.referenceLoader.loadCoreLists();
         const fringe = this.referenceLoader.loadFringe();
+        const commonFringe = this.referenceLoader.loadCommonFringe();
         const sentences = this.referenceLoader.loadSentences();
-        // Calculate core coverage
+        // Calculate core coverage and effort (matching Ruby lines 609-647)
         let coreCount = 0;
         let compCoreCount = 0;
+        let targetCoreEffort = 0;
+        let compCoreEffort = 0;
         const allCoreWords = new Set();
         coreLists.forEach((list) => {
             list.words.forEach((word) => allCoreWords.add(word.toLowerCase()));
         });
         allCoreWords.forEach((word) => {
             const key = this.normalize(word);
-            if (targetWords.has(key))
+            const targetBtn = targetWords.get(key);
+            const compareBtn = compareWords.get(key);
+            if (targetBtn) {
                 coreCount++;
-            if (compareWords.has(key))
+                targetCoreEffort += targetBtn.effort;
+            }
+            else {
+                // Fallback to spelling or prediction effort
+                targetCoreEffort += getFallbackEffort(word, targetResult.has_dynamic_prediction || false, targetResult.spelling_effort_base);
+            }
+            if (compareBtn) {
                 compCoreCount++;
+                compCoreEffort += compareBtn.effort;
+            }
+            else {
+                compCoreEffort += getFallbackEffort(word, compareResult.has_dynamic_prediction || false, compareResult.spelling_effort_base);
+            }
         });
-        // Calculate sentence construction effort
-        let sentenceEffort = 0;
-        let compSentenceEffort = 0;
-        let sentenceWordCount = 0;
+        const avgCoreEffort = allCoreWords.size > 0 ? targetCoreEffort / allCoreWords.size : 0;
+        const avgCompCoreEffort = allCoreWords.size > 0 ? compCoreEffort / allCoreWords.size : 0;
+        // Calculate core component scores (matching Ruby lines 644-647)
+        const coreScore = avgCoreEffort * 5.0;
+        const compCoreScore = avgCompCoreEffort * 5.0;
+        // Calculate sentence construction effort (matching Ruby lines 654-668)
+        const sentenceEfforts = [];
+        const compSentenceEfforts = [];
         sentences.forEach((words) => {
+            let targetSentenceEffort = 0;
+            let compSentenceEffort = 0;
             words.forEach((word) => {
                 const key = this.normalize(word);
                 const targetBtn = targetWords.get(key);
                 const compareBtn = compareWords.get(key);
                 if (targetBtn) {
-                    sentenceEffort += targetBtn.effort;
+                    targetSentenceEffort += targetBtn.effort;
                 }
                 else {
-                    sentenceEffort += 10 + word.length * 2.5; // Spelling effort
+                    targetSentenceEffort += getFallbackEffort(word, targetResult.has_dynamic_prediction || false, targetResult.spelling_effort_base);
                 }
                 if (compareBtn) {
                     compSentenceEffort += compareBtn.effort;
                 }
                 else {
-                    compSentenceEffort += 10 + word.length * 2.5;
+                    compSentenceEffort += getFallbackEffort(word, compareResult.has_dynamic_prediction || false, compareResult.spelling_effort_base);
                 }
-                sentenceWordCount++;
             });
+            // Average effort per sentence (matching Ruby line 657)
+            sentenceEfforts.push(targetSentenceEffort / words.length);
+            compSentenceEfforts.push(compSentenceEffort / words.length);
         });
-        const avgSentenceEffort = sentenceWordCount > 0 ? sentenceEffort / sentenceWordCount : 0;
-        const compAvgSentenceEffort = sentenceWordCount > 0 ? compSentenceEffort / sentenceWordCount : 0;
-        // Calculate fringe coverage
+        const avgSentenceEffort = sentenceEfforts.length > 0
+            ? sentenceEfforts.reduce((a, b) => a + b, 0) / sentenceEfforts.length
+            : 0;
+        const compAvgSentenceEffort = compSentenceEfforts.length > 0
+            ? compSentenceEfforts.reduce((a, b) => a + b, 0) / compSentenceEfforts.length
+            : 0;
+        // Sentence component scores (matching Ruby line 665-668)
+        const sentenceScore = avgSentenceEffort * 3.0;
+        const compSentenceScore = compAvgSentenceEffort * 3.0;
+        // Calculate fringe effort (matching Ruby lines 670-687)
+        const fringeEfforts = [];
+        const compFringeEfforts = [];
         let fringeCount = 0;
         let compFringeCount = 0;
-        let commonFringeCount = 0;
         fringe.forEach((word) => {
             const key = this.normalize(word);
-            const inTarget = targetWords.has(key);
-            const inCompare = compareWords.has(key);
-            if (inTarget)
+            const targetBtn = targetWords.get(key);
+            const compareBtn = compareWords.get(key);
+            if (targetBtn) {
+                fringeEfforts.push(targetBtn.effort);
                 fringeCount++;
-            if (inCompare)
+            }
+            else {
+                fringeEfforts.push(getFallbackEffort(word, targetResult.has_dynamic_prediction || false, targetResult.spelling_effort_base));
+            }
+            if (compareBtn) {
+                compFringeEfforts.push(compareBtn.effort);
                 compFringeCount++;
-            if (inTarget && inCompare)
+            }
+            else {
+                compFringeEfforts.push(getFallbackEffort(word, compareResult.has_dynamic_prediction || false, compareResult.spelling_effort_base));
+            }
+        });
+        const avgFringeEffort = fringeEfforts.length > 0
+            ? fringeEfforts.reduce((a, b) => a + b, 0) / fringeEfforts.length
+            : 0;
+        const avgCompFringeEffort = compFringeEfforts.length > 0
+            ? compFringeEfforts.reduce((a, b) => a + b, 0) / compFringeEfforts.length
+            : 0;
+        // Fringe component scores (matching Ruby line 684-687)
+        const fringeScore = avgFringeEffort * 2.0;
+        const compFringeScore = avgCompFringeEffort * 2.0;
+        // Calculate common fringe effort (matching Ruby lines 689-705)
+        const commonFringeEfforts = [];
+        const compCommonFringeEfforts = [];
+        let commonFringeCount = 0;
+        commonFringe.forEach((word) => {
+            const key = this.normalize(word);
+            const targetBtn = targetWords.get(key);
+            const compareBtn = compareWords.get(key);
+            if (targetBtn && compareBtn) {
+                commonFringeEfforts.push(targetBtn.effort);
+                compCommonFringeEfforts.push(compareBtn.effort);
                 commonFringeCount++;
+            }
         });
+        const avgCommonFringeEffort = commonFringeEfforts.length > 0
+            ? commonFringeEfforts.reduce((a, b) => a + b, 0) / commonFringeEfforts.length
+            : 0;
+        const avgCompCommonFringeEffort = compCommonFringeEfforts.length > 0
+            ? compCommonFringeEfforts.reduce((a, b) => a + b, 0) / compCommonFringeEfforts.length
+            : 0;
+        // Common fringe component scores (matching Ruby line 702-705)
+        const commonFringeScore = avgCommonFringeEffort * 1.0;
+        const compCommonFringeScore = avgCompCommonFringeEffort * 1.0;
+        // Calculate total CARE effort tally (matching Ruby lines 707-708)
+        const PLACEHOLDER = 70;
+        const targetEffortTally = coreScore + sentenceScore + fringeScore + commonFringeScore + PLACEHOLDER;
+        const compEffortTally = compCoreScore + compSentenceScore + compFringeScore + compCommonFringeScore + PLACEHOLDER;
+        // Calculate final CARE scores (matching Ruby line 710-711)
+        // res[:target_effort_score] = [0.0, 350.0 - target_effort_tally].max
+        const careScore = Math.max(0, 350.0 - targetEffortTally);
+        const compCareScore = Math.max(0, 350.0 - compEffortTally);
         return {
             core: coreCount,
             comp_core: compCoreCount,
@@ -302,6 +418,9 @@ class ComparisonAnalyzer {
             comp_fringe: compFringeCount,
             common_fringe: commonFringeCount,
             comp_common_fringe: commonFringeCount,
+            // New composite CARE scores
+            care_score: careScore,
+            comp_care_score: compCareScore,
         };
     }
     /**

package/dist/utilities/analytics/metrics/core.js

@@ -263,7 +263,6 @@ class MetricsCalculator {
     analyzeFrom(tree, brd, setPcts, _isRoot, options = {}) {
         const visitedBoardIds = new Map();
         const visitedBoardEfforts = new Map();
-        let totalButtons = 0;
         const toVisit = [
             {
                 board: brd,
@@ -289,12 +288,6 @@ class MetricsCalculator {
             visitedBoardEfforts.set(board.id, priorEffort);
             const rows = board.grid.length;
             const cols = board.grid[0]?.length || 0;
-            // Count all non-empty buttons reached in this pageset
-            board.buttons.forEach((btn) => {
-                if ((btn.label || '').length > 0) {
-                    totalButtons++;
-                }
-            });
             // Calculate board-level effort
             // Ruby uses grid size (rows * cols) for field size effort
             const gridSize = rows * cols;
@@ -540,10 +533,13 @@ class MetricsCalculator {
             }
             levels[btn.level].push(btn);
         });
+        // Calculate total_buttons as sum of all button counts (matching Ruby line 136)
+        // Ruby: total_buttons: buttons.map{|b| b[:count] || 1}.sum
+        const calculatedTotalButtons = buttons.reduce((sum, btn) => sum + (btn.count || 1), 0);
         return {
             buttons,
             levels,
-            totalButtons,
+            totalButtons: calculatedTotalButtons,
             visitedBoardEfforts,
         };
     }

package/dist/utilities/analytics/metrics/effort.d.ts

@@ -77,6 +77,21 @@ export declare function distanceEffort(x: number, y: number, entryX?: number, en
  * @returns Spelling effort score
  */
 export declare function spellingEffort(word: string, entryEffort?: number, perLetterEffort?: number): number;
+/**
+ * Calculate effort to access a word via prediction
+ *
+ * When prediction is available, the user:
+ * 1. Navigates to the spelling/keyboard page (entryEffort)
+ * 2. Types first 1-3 letters to trigger predictions
+ * 3. Selects from 1-3 predictions (average selections)
+ *
+ * @param entryEffort - Effort to reach the spelling/keyboard page
+ * @param perLetterEffort - Average effort per letter on the keyboard
+ * @param avgSelections - Average number of predictions to check (default 1.5)
+ * @param lettersToType - Letters to type before prediction appears (default 2)
+ * @returns Prediction effort score
+ */
+export declare function predictionEffort(entryEffort?: number, perLetterEffort?: number, avgSelections?: number, lettersToType?: number): number;
 /**
  * Calculate base board effort
  * Combines button size and field size efforts

package/dist/utilities/analytics/metrics/effort.js

@@ -13,6 +13,7 @@ exports.fieldSizeEffort = fieldSizeEffort;
 exports.visualScanEffort = visualScanEffort;
 exports.distanceEffort = distanceEffort;
 exports.spellingEffort = spellingEffort;
+exports.predictionEffort = predictionEffort;
 exports.baseBoardEffort = baseBoardEffort;
 exports.applyReuseDiscount = applyReuseDiscount;
 exports.calculateButtonEffort = calculateButtonEffort;
@@ -103,6 +104,26 @@ function distanceEffort(x, y, entryX = 1.0, entryY = 1.0) {
 function spellingEffort(word, entryEffort = 10, perLetterEffort = 2.5) {
     return entryEffort + word.length * perLetterEffort;
 }
+/**
+ * Calculate effort to access a word via prediction
+ *
+ * When prediction is available, the user:
+ * 1. Navigates to the spelling/keyboard page (entryEffort)
+ * 2. Types first 1-3 letters to trigger predictions
+ * 3. Selects from 1-3 predictions (average selections)
+ *
+ * @param entryEffort - Effort to reach the spelling/keyboard page
+ * @param perLetterEffort - Average effort per letter on the keyboard
+ * @param avgSelections - Average number of predictions to check (default 1.5)
+ * @param lettersToType - Letters to type before prediction appears (default 2)
+ * @returns Prediction effort score
+ */
+function predictionEffort(entryEffort = 10, perLetterEffort = 2.5, avgSelections = 1.5, lettersToType = 2) {
+    // Cost to navigate to keyboard + type first few letters + select from predictions
+    const typingCost = lettersToType * perLetterEffort;
+    const selectionCost = avgSelections * exports.EFFORT_CONSTANTS.SCAN_SELECTION_COST;
+    return entryEffort + typingCost + selectionCost;
+}
 /**
  * Calculate base board effort
  * Combines button size and field size efforts

package/dist/utilities/analytics/metrics/types.d.ts

@@ -94,6 +94,26 @@ export interface MetricsOptions {
      * Optional explicit ID of the spelling/keyboard page
      */
     spellingPageId?: string;
+    /**
+     * Whether to use prediction for missing words
+     *
+     * When true (default): Words not in the board are assumed to be accessible
+     * via prediction at reduced effort (spelling_page_base + prediction_selection)
+     *
+     * When false: Words not in the board must be manually spelled at full effort
+     * (10 + word_length * 2.5 per letter)
+     *
+     * Only applies when the board has prediction capability (e.g., SwiftKey)
+     */
+    usePrediction?: boolean;
+    /**
+     * Average number of selections to find a word in prediction
+     *
+     * When prediction is enabled, this estimates how many prediction
+     * slots a user needs to check before finding their target word.
+     * Default is 1.5 (checking 1-2 predictions on average).
+     */
+    predictionSelections?: number;
 }
 /**
  * Comparison result between two board sets
@@ -143,6 +163,8 @@ export interface ComparisonResult extends MetricsResult {
         comp_fringe: number;
         common_fringe: number;
         comp_common_fringe: number;
+        care_score: number;
+        comp_care_score: number;
     };
     sentences: SentenceAnalysis[];
     fringe_words: FringeWord[];