@willwade/aac-processors 0.0.21 → 0.0.23

package/README.md

@@ -267,30 +267,18 @@ console.log(`Average Effort: ${result.total_words}`);
 Validate AAC files against format specifications to ensure data integrity:
 
 ```typescript
-import { ObfProcessor, GridsetProcessor } from "aac-processors";
+import { validateFileOrBuffer, getValidatorForFile } from "@willwade/aac-processors/validation";
 
-// Validate OBF/OBZ files
-const obfProcessor = new ObfProcessor();
-const result = await obfProcessor.validate("board.obf");
-
-console.log(`Valid: ${result.valid}`);
-console.log(`Errors: ${result.errors}`);
-console.log(`Warnings: ${result.warnings}`);
-
-// Detailed validation results
-if (!result.valid) {
-  result.results
-    .filter((check) => !check.valid)
-    .forEach((check) => {
-      console.log(`✗ ${check.description}: ${check.error}`);
-    });
-}
+// Works in Node, Vite, and esbuild (pass Buffers from the browser/CLI)
+const fileName = "board.obf";
+const validator = getValidatorForFile(fileName);
+const bufferOrPath = new Uint8Array(await file.arrayBuffer()); // or fs path in Node
+const result = await validateFileOrBuffer(bufferOrPath, fileName);
 
-// Validate Gridset files (with optional password for encrypted files)
-const gridsetProcessor = new GridsetProcessor({
-  gridsetPassword: "optional-password",
+console.log(result.valid, result.errors, result.warnings);
+result.results.forEach((check) => {
+  if (!check.valid) console.log(`✗ ${check.description}: ${check.error}`);
 });
-const gridsetResult = await gridsetProcessor.validate("vocab.gridsetx");
 ```
 
 #### Using the CLI
@@ -312,11 +300,15 @@ aacprocessors validate board.gridsetx --gridset-password <password>
 #### What Gets Validated?
 
 - **OBF/OBZ**: Spec compliance (Open Board Format)
-  - Required fields (format, id, locale, buttons, grid, images, sounds)
-  - Grid structure (rows, columns, order)
-  - Button references (image_id, sound_id, load_board paths)
-  - Color formats (RGB/RGBA)
-  - Cross-reference validation
+- **Gridset/Gridsetx**: ZIP/XML structure, required Smartbox assets
+- **Snap**: ZIP/package content, settings/pages/images
+- **TouchChat**: ZIP structure, vocab metadata, nested boards
+- **Asterics (.grd)**: JSON parse, grids, elements, coordinates
+- **Excel (.xlsx/.xls)**: Workbook readability and worksheet content
+- **OPML**: XML validity and outline hierarchy
+- **DOT**: Graph nodes/edges present and text content
+- **Apple Panels (.plist/.ascconfig)**: PanelDefinitions presence and buttons
+- **OBFSet**: Bundled board layout checks
 
 - **Gridset**: XML structure
   - Required elements (gridset, pages, cells)
@@ -901,4 +893,4 @@ Want to help with any of these items? See our [Contributing Guidelines](#-contri
 
 ### Credits
 
-Some of the OBF work is directly from https://github.com/open-aac/obf and https://github.com/open-aac/aac-metrics - OBLA too https://www.openboardformat.org/logs 
+Some of the OBF work is directly from https://github.com/open-aac/obf and https://github.com/open-aac/aac-metrics - OBLA too https://www.openboardformat.org/logs 

package/dist/core/treeStructure.d.ts

@@ -1,5 +1,5 @@
-import { AACButton as IAACButton, AACPage as IAACPage, AACTree as IAACTree, AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata, AACStyle } from '../types/aac';
-export { AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata };
+import { AACButton as IAACButton, AACPage as IAACPage, AACTree as IAACTree, AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata, AACStyle, CellScanningOrder, ScanningSelectionMethod } from '../types/aac';
+export { AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata, CellScanningOrder, ScanningSelectionMethod, };
 export declare enum AACSemanticCategory {
     COMMUNICATION = "communication",// Speech, text output
     NAVIGATION = "navigation",// Page/grid navigation

package/dist/core/treeStructure.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AACTree = exports.AACPage = exports.AACButton = exports.AACScanType = exports.AACSemanticIntent = exports.AACSemanticCategory = void 0;
+exports.AACTree = exports.AACPage = exports.AACButton = exports.AACScanType = exports.AACSemanticIntent = exports.AACSemanticCategory = exports.ScanningSelectionMethod = exports.CellScanningOrder = void 0;
+const aac_1 = require("../types/aac");
+Object.defineProperty(exports, "CellScanningOrder", { enumerable: true, get: function () { return aac_1.CellScanningOrder; } });
+Object.defineProperty(exports, "ScanningSelectionMethod", { enumerable: true, get: function () { return aac_1.ScanningSelectionMethod; } });
 // Semantic action categories for cross-platform compatibility
 var AACSemanticCategory;
 (function (AACSemanticCategory) {

package/dist/processors/applePanelsProcessor.js

@@ -10,6 +10,7 @@ const treeStructure_1 = require("../core/treeStructure");
 const plist_1 = __importDefault(require("plist"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const validation_1 = require("../validation");
 function isNormalizedPanel(panel) {
     return typeof panel.id === 'string';
 }
@@ -92,145 +93,187 @@ class ApplePanelsProcessor extends baseProcessor_1.BaseProcessor {
         return texts;
     }
     loadIntoTree(filePathOrBuffer) {
-        let content;
-        if (Buffer.isBuffer(filePathOrBuffer)) {
-            content = filePathOrBuffer.toString('utf8');
-        }
-        else if (typeof filePathOrBuffer === 'string') {
-            // Check if it's a .ascconfig folder or a direct .plist file
-            if (filePathOrBuffer.endsWith('.ascconfig')) {
-                // Read from proper Apple Panels structure: *.ascconfig/Contents/Resources/PanelDefinitions.plist
-                const panelDefsPath = `${filePathOrBuffer}/Contents/Resources/PanelDefinitions.plist`;
-                if (fs_1.default.existsSync(panelDefsPath)) {
-                    content = fs_1.default.readFileSync(panelDefsPath, 'utf8');
+        const filename = typeof filePathOrBuffer === 'string' ? path_1.default.basename(filePathOrBuffer) : 'upload.plist';
+        let buffer;
+        try {
+            if (Buffer.isBuffer(filePathOrBuffer)) {
+                buffer = filePathOrBuffer;
+            }
+            else if (typeof filePathOrBuffer === 'string') {
+                if (filePathOrBuffer.endsWith('.ascconfig')) {
+                    const panelDefsPath = `${filePathOrBuffer}/Contents/Resources/PanelDefinitions.plist`;
+                    if (fs_1.default.existsSync(panelDefsPath)) {
+                        buffer = fs_1.default.readFileSync(panelDefsPath);
+                    }
+                    else {
+                        const validation = (0, validation_1.buildValidationResultFromMessage)({
+                            filename,
+                            filesize: 0,
+                            format: 'applepanels',
+                            message: `Apple Panels file not found: ${panelDefsPath}`,
+                            type: 'missing',
+                            description: 'PanelDefinitions.plist',
+                        });
+                        throw new validation_1.ValidationFailureError('Apple Panels file not found', validation);
+                    }
                 }
                 else {
-                    throw new Error(`Apple Panels file not found: ${panelDefsPath}`);
+                    buffer = fs_1.default.readFileSync(filePathOrBuffer);
                 }
             }
             else {
-                // Fallback: treat as direct .plist file
-                content = fs_1.default.readFileSync(filePathOrBuffer, 'utf8');
-            }
-        }
-        else {
-            throw new Error('Invalid input: expected string path or Buffer');
-        }
-        const parsedData = plist_1.default.parse(content);
-        // Handle both old format (panels array) and new Apple Panels format (Panels dict)
-        let panelsData = [];
-        if (Array.isArray(parsedData.panels)) {
-            panelsData = parsedData.panels.map((panel, index) => {
-                if (isNormalizedPanel(panel)) {
-                    return panel;
-                }
-                const panelData = panel || {
-                    PanelObjects: [],
-                };
-                return normalizePanel(panelData, `panel_${index}`);
-            });
-        }
-        else if (parsedData.Panels) {
-            const panelsDict = parsedData.Panels;
-            panelsData = Object.keys(panelsDict).map((panelId) => {
-                const rawPanel = panelsDict[panelId] || { PanelObjects: [] };
-                return normalizePanel(rawPanel, panelId);
-            });
-        }
-        const data = { panels: panelsData };
-        const tree = new treeStructure_1.AACTree();
-        tree.metadata.format = 'applepanels';
-        data.panels.forEach((panel) => {
-            const page = new treeStructure_1.AACPage({
-                id: panel.id,
-                name: panel.name,
-                grid: [],
-                buttons: [],
-                parentId: null,
-            });
-            // Create a 2D grid to track button positions
-            const gridLayout = [];
-            const maxRows = 20; // Reasonable default for Apple Panels
-            const maxCols = 20;
-            for (let r = 0; r < maxRows; r++) {
-                gridLayout[r] = new Array(maxCols).fill(null);
+                const validation = (0, validation_1.buildValidationResultFromMessage)({
+                    filename,
+                    filesize: 0,
+                    format: 'applepanels',
+                    message: 'Invalid input: expected string path or Buffer',
+                    type: 'input',
+                    description: 'Apple Panels input',
+                });
+                throw new validation_1.ValidationFailureError('Invalid Apple Panels input', validation);
             }
-            panel.buttons.forEach((btn, idx) => {
-                // Create semantic action from Apple Panels button
-                let semanticAction;
-                if (btn.targetPanel) {
-                    semanticAction = {
-                        category: treeStructure_1.AACSemanticCategory.NAVIGATION,
-                        intent: treeStructure_1.AACSemanticIntent.NAVIGATE_TO,
-                        targetId: btn.targetPanel,
-                        platformData: {
-                            applePanels: {
-                                actionType: 'ActionOpenPanel',
-                                parameters: { PanelID: `USER.${btn.targetPanel}` },
-                            },
-                        },
-                        fallback: {
-                            type: 'NAVIGATE',
-                            targetPageId: btn.targetPanel,
-                        },
+            const content = buffer.toString('utf8');
+            const parsedData = plist_1.default.parse(content);
+            let panelsData = [];
+            if (Array.isArray(parsedData.panels)) {
+                panelsData = parsedData.panels.map((panel, index) => {
+                    if (isNormalizedPanel(panel)) {
+                        return panel;
+                    }
+                    const panelData = panel || {
+                        PanelObjects: [],
                     };
+                    return normalizePanel(panelData, `panel_${index}`);
+                });
+            }
+            else if (parsedData.Panels) {
+                const panelsDict = parsedData.Panels;
+                panelsData = Object.keys(panelsDict).map((panelId) => {
+                    const rawPanel = panelsDict[panelId] || { PanelObjects: [] };
+                    return normalizePanel(rawPanel, panelId);
+                });
+            }
+            if (panelsData.length === 0) {
+                const validation = (0, validation_1.buildValidationResultFromMessage)({
+                    filename,
+                    filesize: buffer.byteLength,
+                    format: 'applepanels',
+                    message: 'No panels found in Apple Panels file',
+                    type: 'structure',
+                    description: 'Panels definition',
+                });
+                throw new validation_1.ValidationFailureError('Apple Panels has no panels', validation);
+            }
+            const data = { panels: panelsData };
+            const tree = new treeStructure_1.AACTree();
+            tree.metadata.format = 'applepanels';
+            data.panels.forEach((panel) => {
+                const page = new treeStructure_1.AACPage({
+                    id: panel.id,
+                    name: panel.name,
+                    grid: [],
+                    buttons: [],
+                    parentId: null,
+                });
+                const gridLayout = [];
+                const maxRows = 20;
+                const maxCols = 20;
+                for (let r = 0; r < maxRows; r++) {
+                    gridLayout[r] = new Array(maxCols).fill(null);
                 }
-                else {
-                    semanticAction = {
-                        category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
-                        intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
-                        text: btn.message || btn.label,
-                        platformData: {
-                            applePanels: {
-                                actionType: 'ActionPressKeyCharSequence',
-                                parameters: {
-                                    CharString: btn.message || btn.label || '',
-                                    isStickyKey: false,
+                panel.buttons.forEach((btn, idx) => {
+                    let semanticAction;
+                    if (btn.targetPanel) {
+                        semanticAction = {
+                            category: treeStructure_1.AACSemanticCategory.NAVIGATION,
+                            intent: treeStructure_1.AACSemanticIntent.NAVIGATE_TO,
+                            targetId: btn.targetPanel,
+                            platformData: {
+                                applePanels: {
+                                    actionType: 'ActionOpenPanel',
+                                    parameters: { PanelID: `USER.${btn.targetPanel}` },
                                 },
                             },
+                            fallback: {
+                                type: 'NAVIGATE',
+                                targetPageId: btn.targetPanel,
+                            },
+                        };
+                    }
+                    else {
+                        semanticAction = {
+                            category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                            intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                            text: btn.message || btn.label,
+                            platformData: {
+                                applePanels: {
+                                    actionType: 'ActionPressKeyCharSequence',
+                                    parameters: {
+                                        CharString: btn.message || btn.label || '',
+                                        isStickyKey: false,
+                                    },
+                                },
+                            },
+                            fallback: {
+                                type: 'SPEAK',
+                                message: btn.message || btn.label,
+                            },
+                        };
+                    }
+                    const button = new treeStructure_1.AACButton({
+                        id: `${panel.id}_btn_${idx}`,
+                        label: btn.label,
+                        message: btn.message || btn.label,
+                        targetPageId: btn.targetPanel,
+                        semanticAction: semanticAction,
+                        style: {
+                            backgroundColor: btn.DisplayColor,
+                            fontSize: btn.FontSize,
+                            fontWeight: btn.DisplayImageWeight === 'bold' ? 'bold' : 'normal',
                         },
-                        fallback: {
-                            type: 'SPEAK',
-                            message: btn.message || btn.label,
-                        },
-                    };
-                }
-                const button = new treeStructure_1.AACButton({
-                    id: `${panel.id}_btn_${idx}`,
-                    label: btn.label,
-                    message: btn.message || btn.label,
-                    targetPageId: btn.targetPanel,
-                    semanticAction: semanticAction,
-                    style: {
-                        backgroundColor: btn.DisplayColor,
-                        fontSize: btn.FontSize,
-                        fontWeight: btn.DisplayImageWeight === 'bold' ? 'bold' : 'normal',
-                    },
-                });
-                page.addButton(button);
-                // Place button in grid layout using Rect position data
-                if (btn.Rect) {
-                    const rect = this.parseRect(btn.Rect);
-                    if (rect) {
-                        const gridPos = this.pixelToGrid(rect.x, rect.y);
-                        const gridWidth = Math.max(1, Math.ceil(rect.width / 25));
-                        const gridHeight = Math.max(1, Math.ceil(rect.height / 25));
-                        // Place button in grid (handle width/height span)
-                        for (let r = gridPos.gridY; r < gridPos.gridY + gridHeight && r < maxRows; r++) {
-                            for (let c = gridPos.gridX; c < gridPos.gridX + gridWidth && c < maxCols; c++) {
-                                if (gridLayout[r] && gridLayout[r][c] === null) {
-                                    gridLayout[r][c] = button;
+                    });
+                    page.addButton(button);
+                    if (btn.Rect) {
+                        const rect = this.parseRect(btn.Rect);
+                        if (rect) {
+                            const gridPos = this.pixelToGrid(rect.x, rect.y);
+                            const gridWidth = Math.max(1, Math.ceil(rect.width / 25));
+                            const gridHeight = Math.max(1, Math.ceil(rect.height / 25));
+                            for (let r = gridPos.gridY; r < gridPos.gridY + gridHeight && r < maxRows; r++) {
+                                for (let c = gridPos.gridX; c < gridPos.gridX + gridWidth && c < maxCols; c++) {
+                                    if (gridLayout[r] && gridLayout[r][c] === null) {
+                                        gridLayout[r][c] = button;
+                                    }
                                 }
                             }
                         }
                     }
-                }
+                });
+                page.grid = gridLayout;
+                tree.addPage(page);
             });
-            // Set the page's grid layout
-            page.grid = gridLayout;
-            tree.addPage(page);
-        });
-        return tree;
+            return tree;
+        }
+        catch (err) {
+            if (err instanceof validation_1.ValidationFailureError) {
+                throw err;
+            }
+            const validation = (0, validation_1.buildValidationResultFromMessage)({
+                filename,
+                filesize: Buffer.isBuffer(filePathOrBuffer)
+                    ? filePathOrBuffer.byteLength
+                    : typeof filePathOrBuffer === 'string'
+                        ? fs_1.default.existsSync(filePathOrBuffer)
+                            ? fs_1.default.statSync(filePathOrBuffer).size
+                            : 0
+                        : 0,
+                format: 'applepanels',
+                message: err?.message || 'Failed to parse Apple Panels file',
+                type: 'parse',
+                description: 'Parse Apple Panels plist',
+            });
+            throw new validation_1.ValidationFailureError('Failed to load Apple Panels file', validation, err);
+        }
     }
     processTexts(filePathOrBuffer, translations, outputPath) {
         // Load the tree, apply translations, and save to new file