add better validation

Author: willwade

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 

src/processors/applePanelsProcessor.ts

@@ -17,6 +17,7 @@ import {
 import plist, { PlistValue } from 'plist';
 import fs from 'fs';
 import path from 'path';
+import { ValidationFailureError, buildValidationResultFromMessage } from '../validation';
 
 interface ApplePanelsActionParameters {
   CharString?: string;
@@ -216,152 +217,195 @@ class ApplePanelsProcessor extends BaseProcessor {
   }
 
   loadIntoTree(filePathOrBuffer: string | Buffer): AACTree {
-    let content: string;
-
-    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.existsSync(panelDefsPath)) {
-          content = fs.readFileSync(panelDefsPath, 'utf8');
+    const filename =
+      typeof filePathOrBuffer === 'string' ? path.basename(filePathOrBuffer) : 'upload.plist';
+    let buffer: 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.existsSync(panelDefsPath)) {
+            buffer = fs.readFileSync(panelDefsPath);
+          } else {
+            const validation = buildValidationResultFromMessage({
+              filename,
+              filesize: 0,
+              format: 'applepanels',
+              message: `Apple Panels file not found: ${panelDefsPath}`,
+              type: 'missing',
+              description: 'PanelDefinitions.plist',
+            });
+            throw new ValidationFailureError('Apple Panels file not found', validation);
+          }
         } else {
-          throw new Error(`Apple Panels file not found: ${panelDefsPath}`);
+          buffer = fs.readFileSync(filePathOrBuffer);
         }
       } else {
-        // Fallback: treat as direct .plist file
-        content = fs.readFileSync(filePathOrBuffer, 'utf8');
+        const validation = buildValidationResultFromMessage({
+          filename,
+          filesize: 0,
+          format: 'applepanels',
+          message: 'Invalid input: expected string path or Buffer',
+          type: 'input',
+          description: 'Apple Panels input',
+        });
+        throw new ValidationFailureError('Invalid Apple Panels input', validation);
       }
-    } else {
-      throw new Error('Invalid input: expected string path or Buffer');
-    }
 
-    const parsedData = plist.parse(content) as ApplePanelsParsedDocument;
+      const content = buffer.toString('utf8');
+      const parsedData = plist.parse(content) as ApplePanelsParsedDocument;
 
-    // Handle both old format (panels array) and new Apple Panels format (Panels dict)
-    let panelsData: ApplePanelsPanel[] = [];
-    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: ApplePanelsDocument = { panels: panelsData };
-    const tree = new AACTree();
-    tree.metadata.format = 'applepanels';
-
-    data.panels.forEach((panel) => {
-      const page = new AACPage({
-        id: panel.id,
-        name: panel.name,
-        grid: [],
-        buttons: [],
-        parentId: null,
-      });
+      let panelsData: ApplePanelsPanel[] = [];
+      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);
+        });
+      }
 
-      // Create a 2D grid to track button positions
-      const gridLayout: (AACButton | null)[][] = [];
-      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);
+      if (panelsData.length === 0) {
+        const validation = buildValidationResultFromMessage({
+          filename,
+          filesize: buffer.byteLength,
+          format: 'applepanels',
+          message: 'No panels found in Apple Panels file',
+          type: 'structure',
+          description: 'Panels definition',
+        });
+        throw new ValidationFailureError('Apple Panels has no panels', validation);
       }
 
-      panel.buttons.forEach((btn, idx) => {
-        // Create semantic action from Apple Panels button
-        let semanticAction: AACSemanticAction | undefined;
-
-        if (btn.targetPanel) {
-          semanticAction = {
-            category: AACSemanticCategory.NAVIGATION,
-            intent: AACSemanticIntent.NAVIGATE_TO,
-            targetId: btn.targetPanel,
-            platformData: {
-              applePanels: {
-                actionType: 'ActionOpenPanel',
-                parameters: { PanelID: `USER.${btn.targetPanel}` },
+      const data: ApplePanelsDocument = { panels: panelsData };
+      const tree = new AACTree();
+      tree.metadata.format = 'applepanels';
+
+      data.panels.forEach((panel) => {
+        const page = new AACPage({
+          id: panel.id,
+          name: panel.name,
+          grid: [],
+          buttons: [],
+          parentId: null,
+        });
+
+        const gridLayout: (AACButton | null)[][] = [];
+        const maxRows = 20;
+        const maxCols = 20;
+        for (let r = 0; r < maxRows; r++) {
+          gridLayout[r] = new Array(maxCols).fill(null);
+        }
+
+        panel.buttons.forEach((btn, idx) => {
+          let semanticAction: AACSemanticAction | undefined;
+
+          if (btn.targetPanel) {
+            semanticAction = {
+              category: AACSemanticCategory.NAVIGATION,
+              intent: AACSemanticIntent.NAVIGATE_TO,
+              targetId: btn.targetPanel,
+              platformData: {
+                applePanels: {
+                  actionType: 'ActionOpenPanel',
+                  parameters: { PanelID: `USER.${btn.targetPanel}` },
+                },
               },
-            },
-            fallback: {
-              type: 'NAVIGATE',
-              targetPageId: btn.targetPanel,
-            },
-          };
-        } else {
-          semanticAction = {
-            category: AACSemanticCategory.COMMUNICATION,
-            intent: AACSemanticIntent.SPEAK_TEXT,
-            text: btn.message || btn.label,
-            platformData: {
-              applePanels: {
-                actionType: 'ActionPressKeyCharSequence',
-                parameters: {
-                  CharString: btn.message || btn.label || '',
-                  isStickyKey: false,
+              fallback: {
+                type: 'NAVIGATE',
+                targetPageId: btn.targetPanel,
+              },
+            };
+          } else {
+            semanticAction = {
+              category: AACSemanticCategory.COMMUNICATION,
+              intent: 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,
-            },
-          };
-        }
+              fallback: {
+                type: 'SPEAK',
+                message: btn.message || btn.label,
+              },
+            };
+          }
 
-        const button = new 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;
+          const button = new 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);
+
+          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;
+                  }
                 }
               }
             }
           }
-        }
-      });
+        });
 
-      // Set the page's grid layout
-      page.grid = gridLayout;
-      tree.addPage(page);
-    });
+        page.grid = gridLayout;
+        tree.addPage(page);
+      });
 
-    return tree;
+      return tree;
+    } catch (err: any) {
+      if (err instanceof ValidationFailureError) {
+        throw err;
+      }
+      const validation = buildValidationResultFromMessage({
+        filename,
+        filesize: Buffer.isBuffer(filePathOrBuffer)
+          ? filePathOrBuffer.byteLength
+          : typeof filePathOrBuffer === 'string'
+            ? fs.existsSync(filePathOrBuffer)
+              ? fs.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 ValidationFailureError('Failed to load Apple Panels file', validation, err);
+    }
   }
 
   processTexts(