@willwade/aac-processors 0.3.2 → 0.3.4

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

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Vocabulary Dump (counts-only)
+ *
+ * Inventory of the vocabulary available in an AAC pageset, aggregated by
+ * source and part of speech. Only counts are emitted — never word lists —
+ * so the output is safe to embed in privacy-preserving reports.
+ *
+ * Sources counted:
+ *   buttons              — labelled buttons (the static on-board vocabulary)
+ *   wordLists            — page WordLists feeding dynamic AutoContent cells
+ *                          (Grid 3 `<WordList>`; absent in other formats)
+ *   predictionDictionaries — prediction wordlists attached to prediction cells
+ *                          (Grid 3 `Prediction.PredictThis` dictionaries)
+ *   wordForms            — smart-grammar inflections generated by
+ *                          MetricsCalculator (only when a MetricsResult is
+ *                          supplied)
+ *
+ * Non-Grid 3 formats simply report zeros for the Grid 3-specific sources.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dumpVocabulary = dumpVocabulary;
+/** Normalise an entry: trim, lowercase, collapse internal whitespace. */
+function normalize(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+const UNTAGGED = 'Unknown';
+/** Per-source tally accumulated while walking the tree. */
+class SourceTally {
+    constructor() {
+        this.entries = 0;
+        this.words = new Set();
+        this.phrases = new Set();
+        this.byPos = new Map();
+    }
+    add(text, pos) {
+        const norm = normalize(text);
+        if (!norm)
+            return;
+        this.entries++;
+        if (/\s/.test(norm))
+            this.phrases.add(norm);
+        else
+            this.words.add(norm);
+        const tag = pos && pos.trim() ? pos.trim() : UNTAGGED;
+        let set = this.byPos.get(tag);
+        if (!set) {
+            set = new Set();
+            this.byPos.set(tag, set);
+        }
+        set.add(norm);
+    }
+    counts() {
+        const byPartOfSpeech = {};
+        for (const tag of Array.from(this.byPos.keys()).sort((a, b) => a.localeCompare(b))) {
+            byPartOfSpeech[tag] = this.byPos.get(tag).size;
+        }
+        return {
+            entries: this.entries,
+            uniqueWords: this.words.size,
+            uniquePhrases: this.phrases.size,
+            byPartOfSpeech,
+        };
+    }
+    get wordSet() {
+        return this.words;
+    }
+    get phraseSet() {
+        return this.phrases;
+    }
+}
+/**
+ * Count the vocabulary available in a pageset, by source and part of speech.
+ * Emits counts only — no word lists.
+ *
+ * @example
+ * const processor = new GridsetProcessor();
+ * const tree = await processor.loadIntoTree('my.gridset');
+ * const metrics = new MetricsCalculator().analyze(tree);
+ * const dump = dumpVocabulary(tree, { metrics });
+ * console.log(dump.summary.wordLists.lists, 'wordlists');
+ */
+function dumpVocabulary(tree, options) {
+    const pages = Object.values(tree.pages);
+    const buttonTally = new SourceTally();
+    const wordListTally = new SourceTally();
+    const predictionTally = new SourceTally();
+    let wordListCount = 0;
+    let buttonsWithDictionaries = 0;
+    let totalButtons = 0;
+    for (const page of pages) {
+        totalButtons += page.buttons.length;
+        if (page.wordListItems && page.wordListItems.length > 0) {
+            wordListCount++;
+            for (const item of page.wordListItems) {
+                wordListTally.add(item.text, item.partOfSpeech);
+            }
+        }
+        for (const btn of page.buttons) {
+            const label = btn.label?.trim();
+            if (label) {
+                buttonTally.add(label, btn.pos);
+            }
+            // Prediction dictionaries: parameters.predictions keeps the original
+            // Prediction.PredictThis words even after analyze() expands
+            // btn.predictions with morphological forms.
+            const dict = btn.parameters?.predictions;
+            if (Array.isArray(dict) && dict.length > 0) {
+                buttonsWithDictionaries++;
+                for (const w of dict) {
+                    if (typeof w === 'string') {
+                        predictionTally.add(w, btn.pos);
+                    }
+                }
+            }
+        }
+    }
+    // Smart-grammar word forms: inflected forms generated by MetricsCalculator
+    // (is_word_form buttons), excluding the original dictionary words they
+    // were generated from.
+    let wordForms = null;
+    let formTally = null;
+    if (options?.metrics) {
+        const originals = new Set();
+        for (const page of pages) {
+            for (const btn of page.buttons) {
+                const dict = btn.parameters?.predictions;
+                if (Array.isArray(dict)) {
+                    for (const w of dict) {
+                        if (typeof w === 'string') {
+                            const norm = normalize(w);
+                            if (norm)
+                                originals.add(norm);
+                        }
+                    }
+                }
+            }
+        }
+        formTally = new SourceTally();
+        const parents = new Set();
+        const seen = new Set();
+        for (const b of options.metrics.buttons) {
+            if (!b.is_word_form)
+                continue;
+            const norm = normalize(b.label);
+            if (!norm || seen.has(norm) || originals.has(norm))
+                continue;
+            seen.add(norm);
+            formTally.add(b.label, b.pos);
+            if (b.parent_button_id)
+                parents.add(b.parent_button_id);
+        }
+        wordForms = { ...formTally.counts(), parentButtons: parents.size };
+    }
+    const combinedWords = new Set([
+        ...buttonTally.wordSet,
+        ...wordListTally.wordSet,
+        ...predictionTally.wordSet,
+        ...(formTally ? formTally.wordSet : []),
+    ]);
+    const combinedPhrases = new Set([
+        ...buttonTally.phraseSet,
+        ...wordListTally.phraseSet,
+        ...predictionTally.phraseSet,
+    ]);
+    return {
+        schema: 'aac-vocabulary-dump/v1',
+        generatedAt: new Date().toISOString(),
+        source: {
+            format: tree.metadata?.format,
+            name: tree.metadata?.name,
+            locale: tree.metadata?.locale,
+        },
+        summary: {
+            totalBoards: pages.length,
+            totalButtons,
+            buttons: buttonTally.counts(),
+            wordLists: { ...wordListTally.counts(), lists: wordListCount },
+            predictionDictionaries: {
+                ...predictionTally.counts(),
+                buttonsWithDictionaries,
+            },
+            wordForms,
+            combined: {
+                uniqueEntries: combinedWords.size + combinedPhrases.size,
+                uniqueWords: combinedWords.size,
+                uniquePhrases: combinedPhrases.size,
+            },
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "browser": "dist/browser/index.browser.js",