More async patches, docs updating , JSDoc updating

Author: willwade

src/cli/index.ts

@@ -559,7 +559,7 @@ program
         let care = undefined;
         if (options.care) {
           const comparison = new ComparisonAnalyzer();
-          care = comparison.compare(metrics, metrics, {
+          care = await comparison.compare(metrics, metrics, {
             includeSentences: true,
             usePrediction: !!options.usePrediction,
             scanningConfig,

src/processors/excelProcessor.ts

@@ -20,7 +20,7 @@ export class ExcelProcessor extends BaseProcessor {
   /**
    * Extract all text content from an Excel file
    * @param filePathOrBuffer - Path to Excel file or Buffer containing Excel data
-   * @returns Array of all text content found in the Excel file
+   * @returns Promise resolving to all text content found in the Excel file
    */
   async extractTexts(_filePathOrBuffer: ProcessorInput): Promise<string[]> {
     console.warn('ExcelProcessor.extractTexts is not implemented yet.');
@@ -30,7 +30,7 @@ export class ExcelProcessor extends BaseProcessor {
   /**
    * Load Excel file into AACTree structure
    * @param filePathOrBuffer - Path to Excel file or Buffer containing Excel data
-   * @returns AACTree representation of the Excel file
+   * @returns Promise resolving to an AACTree representation of the Excel file
    */
   async loadIntoTree(_filePathOrBuffer: ProcessorInput): Promise<AACTree> {
     console.warn('ExcelProcessor.loadIntoTree is not implemented yet.');
@@ -44,7 +44,7 @@ export class ExcelProcessor extends BaseProcessor {
    * @param filePathOrBuffer - Path to Excel file or Buffer containing Excel data
    * @param translations - Map of original text to translated text
    * @param outputPath - Path where translated Excel file should be saved
-   * @returns Buffer containing the translated Excel file
+   * @returns Promise resolving to a buffer containing the translated Excel file
    */
   async processTexts(
     _filePathOrBuffer: ProcessorInput,

src/processors/gridsetProcessor.ts

@@ -1964,7 +1964,7 @@ class GridsetProcessor extends BaseProcessor {
    * This method uses shared translation utilities that work across all AAC formats.
    *
    * @param filePathOrBuffer - Path to gridset file or buffer
-   * @returns Array of symbol information for LLM processing
+   * @returns Promise resolving to symbol information for LLM processing
    */
   async extractSymbolsForLLM(filePathOrBuffer: string | Buffer): Promise<ButtonForTranslation[]> {
     const tree = await this.loadIntoTree(filePathOrBuffer);
@@ -1997,7 +1997,7 @@ class GridsetProcessor extends BaseProcessor {
    * @param llmTranslations - Array of LLM translations with symbol info
    * @param outputPath - Where to save the translated gridset
    * @param options - Translation options (e.g., allowPartial for testing)
-   * @returns Buffer of the translated gridset
+   * @returns Promise resolving to a buffer of the translated gridset
    */
   async processLLMTranslations(
     filePathOrBuffer: string | Buffer,

src/processors/obfProcessor.ts

@@ -778,7 +778,7 @@ class ObfProcessor extends BaseProcessor {
    * This method uses shared translation utilities that work across all AAC formats.
    *
    * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
-   * @returns Array of symbol information for LLM processing
+   * @returns Promise resolving to symbol information for LLM processing
    */
   async extractSymbolsForLLM(filePathOrBuffer: ProcessorInput): Promise<ButtonForTranslation[]> {
     const tree = await this.loadIntoTree(filePathOrBuffer);
@@ -811,7 +811,7 @@ class ObfProcessor extends BaseProcessor {
    * @param llmTranslations - Array of LLM translations with symbol info
    * @param outputPath - Where to save the translated OBF/OBZ file
    * @param options - Translation options (e.g., allowPartial for testing)
-   * @returns Buffer of the translated OBF/OBZ file
+   * @returns Promise resolving to a buffer of the translated OBF/OBZ file
    */
   async processLLMTranslations(
     filePathOrBuffer: ProcessorInput,

src/processors/snapProcessor.ts

@@ -1442,7 +1442,7 @@ class SnapProcessor extends BaseProcessor {
    * Get available PageLayouts for a Snap file
    * Useful for UI components that want to let users select layout size
    * @param filePath - Path to the Snap file
-   * @returns Array of available PageLayouts with their dimensions
+   * @returns Promise resolving to available PageLayouts with their dimensions
    */
   async getAvailablePageLayouts(filePath: string): Promise<PageLayoutInfo[]> {
     const { writeBinaryToPath, removePath, pathExists, join } = this.options.fileAdapter;

src/processors/touchchatProcessor.ts

@@ -1356,7 +1356,7 @@ class TouchChatProcessor extends BaseProcessor {
    * This method uses shared translation utilities that work across all AAC formats.
    *
    * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
-   * @returns Array of symbol information for LLM processing
+   * @returns Promise resolving to symbol information for LLM processing
    */
   async extractSymbolsForLLM(filePathOrBuffer: string | Buffer): Promise<ButtonForTranslation[]> {
     const tree = await this.loadIntoTree(filePathOrBuffer);
@@ -1389,7 +1389,7 @@ class TouchChatProcessor extends BaseProcessor {
    * @param llmTranslations - Array of LLM translations with symbol info
    * @param outputPath - Where to save the translated TouchChat file
    * @param options - Translation options (e.g., allowPartial for testing)
-   * @returns Buffer of the translated TouchChat file
+   * @returns Promise resolving to a buffer of the translated TouchChat file
    */
   async processLLMTranslations(
     filePathOrBuffer: string | Uint8Array,

src/utilities/analytics/docs/AAC_METRICS_GUIDE.md

@@ -45,7 +45,7 @@ The `MetricsCalculator` is format-agnostic. You can use any processor to load a
 import { ObfsetProcessor, Analytics } from '@willwade/aac-processors';
 
 const processor = new ObfsetProcessor();
-const tree = processor.loadIntoTree('set.obfset');
+const tree = await processor.loadIntoTree('set.obfset');
 const result = new Analytics.MetricsCalculator().analyze(tree);
 ```
 
@@ -54,7 +54,7 @@ const result = new Analytics.MetricsCalculator().analyze(tree);
 import { GridsetProcessor, Analytics } from '@willwade/aac-processors';
 
 const processor = new GridsetProcessor();
-const tree = processor.loadIntoTree('my_file.gridset');
+const tree = await processor.loadIntoTree('my_file.gridset');
 const result = new Analytics.MetricsCalculator().analyze(tree);
 ```
 
@@ -63,7 +63,7 @@ const result = new Analytics.MetricsCalculator().analyze(tree);
 import { SnapProcessor, Analytics } from '@willwade/aac-processors';
 
 const processor = new SnapProcessor();
-const tree = processor.loadIntoTree('SnapBackup.pageSet');
+const tree = await processor.loadIntoTree('SnapBackup.pageSet');
 const result = new Analytics.MetricsCalculator().analyze(tree);
 ```
 
@@ -72,7 +72,7 @@ const result = new Analytics.MetricsCalculator().analyze(tree);
 import { TouchChatProcessor, Analytics } from '@willwade/aac-processors';
 
 const processor = new TouchChatProcessor();
-const tree = processor.loadIntoTree('TouchChatBackup.zip');
+const tree = await processor.loadIntoTree('TouchChatBackup.zip');
 const result = new Analytics.MetricsCalculator().analyze(tree);
 ```
 

src/utilities/analytics/docs/SCANNING_METRICS_GUIDE.md

@@ -100,7 +100,7 @@ Grid 3 stores scan block information directly on each button in the XML:
 import { GridsetProcessor, Analytics } from '@willwade/aac-processors';
 
 const processor = new GridsetProcessor();
-const tree = processor.loadIntoTree('my_file.gridset');
+const tree = await processor.loadIntoTree('my_file.gridset');
 
 // Scan blocks are automatically extracted from @ScanBlock attribute
 const result = new Analytics.MetricsCalculator().analyze(tree);
@@ -157,7 +157,7 @@ import { SnapProcessor, Analytics } from '@willwade/aac-processors';
 
 // Option 1: Default - prefer largest layout with scanning enabled
 const processor = new SnapProcessor();
-const tree = processor.loadIntoTree('Core First Scanning.sps');
+const tree = await processor.loadIntoTree('Core First Scanning.sps');
 
 // Option 2: Specify layout preference
 const processor = new SnapProcessor(null, {
@@ -233,7 +233,7 @@ console.log('Core Words scan blocks:', scanBlockCounts);
 import { TouchChatProcessor, Analytics } from '@willwade/aac-processors';
 
 const processor = new TouchChatProcessor();
-const tree = processor.loadIntoTree('TouchChatBackup.zip');
+const tree = await processor.loadIntoTree('TouchChatBackup.zip');
 
 // All buttons have scanBlock = 1 (linear scanning)
 // Or scanBlock = undefined (no grouping)
@@ -298,7 +298,7 @@ import { SnapProcessor, Analytics } from '@willwade/aac-processors';
 const processor = new SnapProcessor(null, {
   pageLayoutPreference: 'scanning'  // Use scanning layout
 });
-const tree = processor.loadIntoTree('Core First Scanning.sps');
+const tree = await processor.loadIntoTree('Core First Scanning.sps');
 
 // Set root page for multi-vocab pagesets
 tree.rootId = '0219f681-1069-4296-be42-790ee828a7b4'; // Core Words

src/utilities/analytics/docs/VOCABULARY_ANALYSIS_GUIDE.md

@@ -24,14 +24,14 @@ import { ObfsetProcessor, Analytics } from '@willwade/aac-processors';
 
 // Load board set
 const processor = new ObfsetProcessor();
-const tree = processor.loadIntoTree('path/to/boardset.obfset');
+const tree = await processor.loadIntoTree('path/to/boardset.obfset');
 
 // Calculate metrics
 const metrics = new Analytics.MetricsCalculator().analyze(tree);
 
 // Analyze vocabulary coverage
 const vocabAnalyzer = new Analytics.VocabularyAnalyzer();
-const analysis = vocabAnalyzer.analyze(metrics);
+const analysis = await vocabAnalyzer.analyze(metrics);
 
 console.log("Core Coverage:", analysis.core_coverage);
 console.log("High Effort Words:", analysis.high_effort_words);
@@ -132,7 +132,7 @@ const compareResult = calculator.analyze(compareTree);
 
 // Compare
 const comparisonAnalyzer = new Analytics.ComparisonAnalyzer();
-const comparison = comparisonAnalyzer.compare(targetResult, compareResult, {
+const comparison = await comparisonAnalyzer.compare(targetResult, compareResult, {
   includeSentences: true,
 });
 
@@ -230,12 +230,12 @@ All processors can now use these analysis features:
 import { ObfProcessor, Analytics } from '@willwade/aac-processors';
 
 const processor = new ObfProcessor();
-const tree = processor.loadIntoTree('my-board.obf');
+const tree = await processor.loadIntoTree('my-board.obf');
 
 const metrics = new Analytics.MetricsCalculator().analyze(tree);
 
 const vocabAnalyzer = new Analytics.VocabularyAnalyzer();
-const coverage = vocabAnalyzer.analyze(metrics);
+const coverage = await vocabAnalyzer.analyze(metrics);
 
 // Identify gaps in core vocabulary
 Object.entries(coverage.core_coverage).forEach(([id, data]) => {

src/utilities/translation/README.md

@@ -76,8 +76,8 @@ interface LLMLTranslationResult {
 import { extractAllButtonsForTranslation } from './translation/translationProcessor';
 
 // For gridset format
-extractSymbolsForLLM(filePath): ButtonForTranslation[] {
-  const tree = this.loadIntoTree(filePath);
+async extractSymbolsForLLM(filePath): Promise<ButtonForTranslation[]> {
+  const tree = await this.loadIntoTree(filePath);
 
   const allButtons: any[] = [];
   Object.values(tree.pages).forEach((page) => {
@@ -132,8 +132,8 @@ processLLMTranslations(
   filePath: string | Buffer,
   llmTranslations: LLMLTranslationResult[],
   outputPath: string
-): Buffer {
-  const tree = this.loadIntoTree(filePath);
+): Promise<Buffer> {
+  const tree = await this.loadIntoTree(filePath);
 
   // Validate using shared utility
   const buttonIds = Object.values(tree.pages).flatMap((page) =>
@@ -176,7 +176,7 @@ processLLMTranslations(
   });
 
   // Save and return
-  this.saveFromTree(tree, outputPath);
+  await this.saveFromTree(tree, outputPath);
   return fs.readFileSync(outputPath);
 }
 ```
@@ -202,8 +202,8 @@ extractSymbolsForLLM(filePath: string | Buffer): ButtonForTranslation[] {
 
 ```typescript
 // snapProcessor.ts
-extractSymbolsForLLM(filePath: string | Buffer): ButtonForTranslation[] {
-  const tree = this.loadIntoTree(filePath);
+async extractSymbolsForLLM(filePath: string | Buffer): Promise<ButtonForTranslation[]> {
+  const tree = await this.loadIntoTree(filePath);
   const allButtons: any[] = [];
 
   Object.values(tree.pages).forEach((page) => {