@willwade/aac-processors 0.0.9 → 0.0.10

package/dist/validation/snapValidator.js

@@ -0,0 +1,237 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapValidator = void 0;
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const xml2js = __importStar(require("xml2js"));
+const adm_zip_1 = __importDefault(require("adm-zip"));
+const baseValidator_1 = require("./baseValidator");
+/**
+ * Validator for Snap files (.spb, .sps)
+ * Snap files are zipped packages containing XML configuration
+ */
+class SnapValidator extends baseValidator_1.BaseValidator {
+    constructor() {
+        super();
+    }
+    /**
+     * Validate a Snap file from disk
+     */
+    static async validateFile(filePath) {
+        const validator = new SnapValidator();
+        const content = fs.readFileSync(filePath);
+        const stats = fs.statSync(filePath);
+        return validator.validate(content, path.basename(filePath), stats.size);
+    }
+    /**
+     * Check if content is Snap format
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    static async identifyFormat(content, filename) {
+        const name = filename.toLowerCase();
+        if (name.endsWith('.spb') || name.endsWith('.sps')) {
+            return true;
+        }
+        // Try to parse as ZIP and check for Snap structure
+        try {
+            const zip = new adm_zip_1.default(content);
+            const entries = zip.getEntries();
+            // Snap packages typically have settings.xml or similar
+            return entries.some((e) => e.entryName.includes('settings') || e.entryName.includes('.xml'));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Main validation method
+     */
+    async validate(content, filename, filesize) {
+        this.reset();
+        await this.add_check('filename', 'file extension', async () => {
+            if (!filename.match(/\.(spb|sps)$/)) {
+                this.warn('filename should end with .spb or .sps');
+            }
+        });
+        let zip = null;
+        let validZip = false;
+        await this.add_check('zip', 'valid zip package', async () => {
+            try {
+                // Ensure content is a Buffer for AdmZip
+                const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+                zip = new adm_zip_1.default(buffer);
+                const entries = zip.getEntries();
+                validZip = entries.length > 0;
+            }
+            catch (e) {
+                this.err(`file is not a valid zip package: ${e.message}`, true);
+            }
+        });
+        if (!validZip || !zip) {
+            return this.buildResult(filename, filesize, 'snap');
+        }
+        await this.validateSnapStructure(zip, filename);
+        return this.buildResult(filename, filesize, 'snap');
+    }
+    /**
+     * Validate Snap package structure
+     */
+    async validateSnapStructure(zip, _filename) {
+        // Check for required files
+        await this.add_check('required_files', 'required package files', async () => {
+            const entries = zip.getEntries();
+            const entryNames = entries.map((e) => e.entryName);
+            // Look for common Snap files
+            const hasSettings = entryNames.some((n) => n.toLowerCase().includes('settings'));
+            const hasXml = entryNames.some((n) => n.toLowerCase().endsWith('.xml'));
+            if (!hasSettings && !hasXml) {
+                this.err('Snap package must contain settings.xml or similar configuration file');
+            }
+            if (entries.length === 0) {
+                this.err('Snap package is empty');
+            }
+        });
+        // Try to parse and validate the main settings file
+        const settingsEntry = zip
+            .getEntries()
+            .find((e) => e.entryName.toLowerCase().includes('settings'));
+        if (settingsEntry) {
+            await this.validateSettingsFile(zip, settingsEntry);
+        }
+        // Check for pages
+        const pageEntries = zip.getEntries().filter((e) => e.entryName.toLowerCase().includes('page'));
+        await this.add_check('pages', 'pages in package', async () => {
+            if (pageEntries.length === 0) {
+                this.warn('Snap package should contain at least one page file');
+            }
+        });
+        // Validate a sample of pages
+        const samplePages = pageEntries.slice(0, 5); // Limit to first 5 pages
+        for (let i = 0; i < samplePages.length; i++) {
+            await this.validatePageFile(zip, samplePages[i], i);
+        }
+        // Check for images
+        const imageEntries = zip
+            .getEntries()
+            .filter((e) => e.entryName.toLowerCase().match(/\.(png|jpg|jpeg|gif|bmp)$/i));
+        await this.add_check('images', 'image files', async () => {
+            if (imageEntries.length === 0) {
+                this.warn('Snap package should contain image files for buttons');
+            }
+        });
+        // Check for audio files
+        const audioEntries = zip
+            .getEntries()
+            .filter((e) => e.entryName.toLowerCase().match(/\.(wav|mp3|m4a|ogg)$/i));
+        await this.add_check('audio', 'audio files', async () => {
+            // Audio files are optional, so just warn if missing
+            if (audioEntries.length === 0) {
+                // This is informational, not a warning
+            }
+        });
+        // Check for unexpected files
+        await this.add_check('unexpected_files', 'unexpected file types', async () => {
+            const entries = zip.getEntries();
+            const unexpectedFiles = entries.filter((e) => {
+                const name = e.entryName.toLowerCase();
+                // Skip common system files and directories
+                if (name.startsWith('__macosx') || name.startsWith('.ds_store')) {
+                    return false;
+                }
+                // Allowed file types
+                return !name.match(/\.(xml|png|jpg|jpeg|gif|bmp|wav|mp3|m4a|ogg|json)$/i);
+            });
+            if (unexpectedFiles.length > 0) {
+                const unexpectedNames = unexpectedFiles.map((f) => f.entryName).slice(0, 5);
+                this.warn(`Package contains unexpected file types: ${unexpectedNames.join(', ')}`);
+            }
+        });
+    }
+    /**
+     * Validate the main settings file
+     */
+    async validateSettingsFile(zip, entry) {
+        await this.add_check('settings_format', 'settings file format', async () => {
+            try {
+                const content = zip.readAsText(entry.entryName);
+                const parser = new xml2js.Parser();
+                const xml = await parser.parseStringPromise(content);
+                // Check for expected root element
+                if (!xml.settings && !xml.Settings && !xml.page && !xml.Page) {
+                    this.warn('settings file does not contain expected root element');
+                }
+                // Check for required settings attributes if present
+                const settings = xml.settings || xml.Settings;
+                if (settings) {
+                    const id = settings.$?.id || settings.$?.Id;
+                    const name = settings.$?.name || settings.$?.Name;
+                    if (!id && !name) {
+                        this.warn('settings should have an id or name attribute');
+                    }
+                }
+            }
+            catch (e) {
+                this.err(`Failed to parse settings file: ${e.message}`);
+            }
+        });
+    }
+    /**
+     * Validate a page file
+     */
+    async validatePageFile(zip, entry, index) {
+        await this.add_check(`page[${index}]`, `page file ${index}: ${entry.entryName}`, async () => {
+            try {
+                const content = zip.readAsText(entry.entryName);
+                const parser = new xml2js.Parser();
+                const xml = await parser.parseStringPromise(content);
+                const page = xml.page || xml.Page;
+                if (!page) {
+                    this.err(`Page file ${entry.entryName} does not contain a page element`);
+                    return;
+                }
+                // Check page attributes
+                const pageId = page.$?.id || page.$?.Id;
+                if (!pageId) {
+                    this.warn(`Page ${entry.entryName} is missing an id attribute`);
+                }
+                // Check for cells/buttons
+                const cells = page.cells || page.Cells || page.button || page.Button;
+                if (!cells || (Array.isArray(cells) && cells.length === 0)) {
+                    this.warn(`Page ${entry.entryName} has no cells or buttons`);
+                }
+            }
+            catch (e) {
+                this.err(`Failed to parse page file ${entry.entryName}: ${e.message}`);
+            }
+        });
+    }
+}
+exports.SnapValidator = SnapValidator;

package/dist/validation/touchChatValidator.d.ts

@@ -0,0 +1,33 @@
+import { BaseValidator } from './baseValidator';
+import { ValidationResult } from './validationTypes';
+/**
+ * Validator for TouchChat files (.ce)
+ * TouchChat files are XML-based
+ */
+export declare class TouchChatValidator extends BaseValidator {
+    constructor();
+    /**
+     * Validate a TouchChat file from disk
+     */
+    static validateFile(filePath: string): Promise<ValidationResult>;
+    /**
+     * Check if content is TouchChat format
+     */
+    static identifyFormat(content: any, filename: string): Promise<boolean>;
+    /**
+     * Main validation method
+     */
+    validate(content: Buffer | Uint8Array, filename: string, filesize: number): Promise<ValidationResult>;
+    /**
+     * Validate TouchChat structure
+     */
+    private validateTouchChatStructure;
+    /**
+     * Validate a single page
+     */
+    private validatePage;
+    /**
+     * Validate a single button
+     */
+    private validateButton;
+}

package/dist/validation/touchChatValidator.js

@@ -0,0 +1,229 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TouchChatValidator = void 0;
+/* eslint-disable @typescript-eslint/require-await */
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const xml2js = __importStar(require("xml2js"));
+const baseValidator_1 = require("./baseValidator");
+/**
+ * Validator for TouchChat files (.ce)
+ * TouchChat files are XML-based
+ */
+class TouchChatValidator extends baseValidator_1.BaseValidator {
+    constructor() {
+        super();
+    }
+    /**
+     * Validate a TouchChat file from disk
+     */
+    static async validateFile(filePath) {
+        const validator = new TouchChatValidator();
+        const content = fs.readFileSync(filePath);
+        const stats = fs.statSync(filePath);
+        return validator.validate(content, path.basename(filePath), stats.size);
+    }
+    /**
+     * Check if content is TouchChat format
+     */
+    static async identifyFormat(content, filename) {
+        const name = filename.toLowerCase();
+        if (name.endsWith('.ce')) {
+            return true;
+        }
+        // Try to parse as XML and check for TouchChat structure
+        try {
+            const contentStr = Buffer.isBuffer(content) ? content.toString('utf-8') : content;
+            const parser = new xml2js.Parser();
+            const result = await parser.parseStringPromise(contentStr);
+            // TouchChat files typically have specific structure
+            return result && (result.PageSet || result.Pageset || result.page || result.Page);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Main validation method
+     */
+    async validate(content, filename, filesize) {
+        this.reset();
+        await this.add_check('filename', 'file extension', async () => {
+            if (!filename.match(/\.ce$/i)) {
+                this.warn('filename should end with .ce');
+            }
+        });
+        let xmlObj = null;
+        await this.add_check('xml_parse', 'valid XML', async () => {
+            try {
+                const parser = new xml2js.Parser();
+                const contentStr = content.toString('utf-8');
+                xmlObj = await parser.parseStringPromise(contentStr);
+            }
+            catch (e) {
+                this.err(`Failed to parse XML: ${e.message}`, true);
+            }
+        });
+        if (!xmlObj) {
+            return this.buildResult(filename, filesize, 'touchchat');
+        }
+        await this.add_check('xml_structure', 'TouchChat root element', async () => {
+            // TouchChat can have different root elements
+            const hasValidRoot = xmlObj.PageSet ||
+                xmlObj.Pageset ||
+                xmlObj.page ||
+                xmlObj.Page ||
+                xmlObj.pages ||
+                xmlObj.Pages;
+            if (!hasValidRoot) {
+                this.err('file does not contain a recognized TouchChat structure');
+            }
+        });
+        const root = xmlObj.PageSet ||
+            xmlObj.Pageset ||
+            xmlObj.page ||
+            xmlObj.Page ||
+            xmlObj.pages ||
+            xmlObj.Pages;
+        if (root) {
+            await this.validateTouchChatStructure(root);
+        }
+        return this.buildResult(filename, filesize, 'touchchat');
+    }
+    /**
+     * Validate TouchChat structure
+     */
+    async validateTouchChatStructure(root) {
+        // Check for ID
+        await this.add_check('root_id', 'root element ID', async () => {
+            const id = root.$?.id || root.$?.Id;
+            if (!id) {
+                this.warn('root element should have an id attribute');
+            }
+        });
+        // Check for name
+        await this.add_check('root_name', 'root element name', async () => {
+            const name = root.$?.name || root.$?.Name || root.name?.[0];
+            if (!name) {
+                this.warn('root element should have a name');
+            }
+        });
+        // Check for pages
+        await this.add_check('pages', 'pages collection', async () => {
+            const pages = root.page || root.Page || root.pages || root.Pages;
+            if (!pages) {
+                this.err('TouchChat file must contain pages');
+            }
+            else if (!Array.isArray(pages) || pages.length === 0) {
+                this.err('TouchChat file must contain at least one page');
+            }
+        });
+        // Validate individual pages
+        const pages = root.page || root.Page || root.pages || root.Pages;
+        if (pages && Array.isArray(pages)) {
+            await this.add_check('page_count', 'page count', async () => {
+                if (pages.length === 0) {
+                    this.err('Must contain at least one page');
+                }
+            });
+            // Sample first few pages
+            const sampleSize = Math.min(pages.length, 5);
+            for (let i = 0; i < sampleSize; i++) {
+                await this.validatePage(pages[i], i);
+            }
+        }
+    }
+    /**
+     * Validate a single page
+     */
+    async validatePage(page, index) {
+        await this.add_check(`page[${index}]_id`, `page ${index} ID`, async () => {
+            const id = page.$?.id || page.$?.Id;
+            if (!id) {
+                this.warn(`page ${index} is missing an id attribute`);
+            }
+        });
+        await this.add_check(`page[${index}]_name`, `page ${index} name`, async () => {
+            const name = page.$?.name || page.$?.Name || page.name?.[0];
+            if (!name) {
+                this.warn(`page ${index} should have a name`);
+            }
+        });
+        // Check for buttons/items
+        await this.add_check(`page[${index}]_buttons`, `page ${index} buttons`, async () => {
+            const buttons = page.button || page.Button || page.item || page.Item;
+            if (!buttons) {
+                this.warn(`page ${index} has no buttons/items`);
+            }
+            else if (Array.isArray(buttons) && buttons.length === 0) {
+                this.warn(`page ${index} should contain at least one button`);
+            }
+        });
+        // Validate button references
+        const buttons = page.button || page.Button || page.item || page.Item;
+        if (buttons && Array.isArray(buttons)) {
+            const sampleSize = Math.min(buttons.length, 3);
+            for (let i = 0; i < sampleSize; i++) {
+                await this.validateButton(buttons[i], index, i);
+            }
+        }
+    }
+    /**
+     * Validate a single button
+     */
+    async validateButton(button, pageIdx, buttonIdx) {
+        await this.add_check(`page[${pageIdx}]_button[${buttonIdx}]_label`, `button label`, async () => {
+            const label = button.$?.label || button.$?.Label || button.label?.[0];
+            if (!label) {
+                this.warn(`button ${buttonIdx} on page ${pageIdx} should have a label`);
+            }
+        });
+        await this.add_check(`page[${pageIdx}]_button[${buttonIdx}]_vocalization`, `button vocalization`, async () => {
+            const vocalization = button.$?.vocalization || button.$?.Vocalization || button.vocalization?.[0];
+            if (!vocalization) {
+                // Vocalization is optional, so just info
+            }
+        });
+        // Check for image reference
+        await this.add_check(`page[${pageIdx}]_button[${buttonIdx}]_image`, `button image`, async () => {
+            const image = button.$?.image || button.$?.Image || button.img?.[0];
+            if (!image) {
+                this.warn(`button ${buttonIdx} on page ${pageIdx} should have an image reference`);
+            }
+        });
+        // Check for link/action
+        await this.add_check(`page[${pageIdx}]_button[${buttonIdx}]_action`, `button action`, async () => {
+            const link = button.$?.link || button.$?.Link;
+            const action = button.$?.action || button.$?.Action;
+            if (!link && !action) {
+                // Not all buttons need actions, they can just speak
+            }
+        });
+    }
+}
+exports.TouchChatValidator = TouchChatValidator;

package/dist/validation/validationTypes.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Custom error class for validation errors
+ * Can be marked as a blocker to stop validation immediately
+ */
+export declare class ValidationError extends Error {
+    blocker: boolean;
+    constructor(message: string, blocker?: boolean);
+}
+/**
+ * Represents a single validation check with its result
+ */
+export interface ValidationCheck {
+    /** Type/category of the check (e.g., 'json_parse', 'grid', 'buttons') */
+    type: string;
+    /** Human-readable description of what is being checked */
+    description: string;
+    /** Whether the check passed */
+    valid: boolean;
+    /** Error message if the check failed */
+    error?: string;
+    /** Non-blocking warnings */
+    warnings?: string[];
+}
+/**
+ * Complete validation result for a file
+ */
+export interface ValidationResult {
+    /** Name of the file that was validated */
+    filename: string;
+    /** Size of the file in bytes */
+    filesize: number;
+    /** Format identifier (e.g., 'obf', 'gridset', 'snap') */
+    format: string;
+    /** Overall validity - true if no errors */
+    valid: boolean;
+    /** Total number of errors found */
+    errors: number;
+    /** Total number of warnings found */
+    warnings: number;
+    /** Array of individual validation checks */
+    results: ValidationCheck[];
+    /** Nested validation results (e.g., boards within an OBZ) */
+    sub_results?: ValidationResult[];
+}
+/**
+ * Options for validation behavior
+ */
+export interface ValidationOptions {
+    /** Whether to include warnings in validation (default: true) */
+    includeWarnings?: boolean;
+    /** Whether to stop on first blocker error (default: true) */
+    stopOnBlocker?: boolean;
+    /** Custom validation rules to apply */
+    customRules?: ValidationRule[];
+}
+/**
+ * Custom validation rule that can be added
+ */
+export interface ValidationRule {
+    type: string;
+    description: string;
+    check: (data: any) => Promise<boolean> | boolean;
+    errorMessage?: string;
+}

package/dist/validation/validationTypes.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+/**
+ * Custom error class for validation errors
+ * Can be marked as a blocker to stop validation immediately
+ */
+class ValidationError extends Error {
+    constructor(message, blocker = false) {
+        super(message);
+        this.name = 'ValidationError';
+        this.blocker = blocker;
+    }
+}
+exports.ValidationError = ValidationError;

package/examples/README.md

@@ -19,6 +19,13 @@ This directory contains example AAC pagesets in various formats used for testing
 - **example.obf** - OBF pageset (JSON-based)
 - **example.obz** - OBZ pageset (compressed)
 
+**obf/** - Directory containing validation test samples from the obf-node project:
+- **simple.obf** - Simple, valid OBF file for basic validation tests
+- **aboutme.json** - Invalid OBF (missing locale field) for error testing
+- **hash.json** - Non-OBF JSON structure for format detection tests
+- **array.json** - JSON array (not object) for structure validation tests
+- **links.obz** - OBZ package with links for zip archive validation
+
 ### Asterics Grid Format (.grd)
 - **example.grd** - Asterics Grid pageset
 - **example2.grd** - Alternative Asterics Grid pageset