@willwade/aac-processors 0.0.9 → 0.0.11

package/README.md

@@ -27,6 +27,7 @@ A comprehensive **TypeScript library** for processing AAC (Augmentative and Alte
 - 🌍 **Translation workflows** - Built-in i18n support with `processTexts()`
 - 🎨 **Comprehensive styling support** - Preserve visual appearance across formats
 - 🧪 **Property-based testing** - Robust validation with 140+ tests
+- ✅ **Format validation** - Spec-based validation for all supported formats
 - ⚡ **Performance optimized** - Memory-efficient processing of large files
 - 🛡️ **Error recovery** - Graceful handling of corrupted data
 - 🔒 **Thread-safe** - Concurrent processing support
@@ -191,6 +192,78 @@ const translatedBuffer = processor.processTexts(
 console.log("Translation complete!");
 ```
 
+### Format Validation
+
+Validate AAC files against format specifications to ensure data integrity:
+
+```typescript
+import { ObfProcessor, GridsetProcessor } from "aac-processors";
+
+// 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}`);
+    });
+}
+
+// Validate Gridset files (with optional password for encrypted files)
+const gridsetProcessor = new GridsetProcessor({
+  gridsetPassword: "optional-password",
+});
+const gridsetResult = await gridsetProcessor.validate("vocab.gridsetx");
+```
+
+#### Using the CLI
+
+```bash
+# Validate a file
+aacprocessors validate board.obf
+
+# JSON output
+aacprocessors validate board.obf --json
+
+# Quiet mode (just valid/invalid)
+aacprocessors validate board.gridset --quiet
+
+# Validate encrypted Gridset file
+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**: XML structure
+  - Required elements (gridset, pages, cells)
+  - FixedCellSize configuration
+  - Page and cell attributes
+  - Image references
+
+- **Snap**: Package structure
+  - ZIP package validity
+  - Settings file format
+  - Page/button configurations
+
+- **TouchChat**: XML structure
+  - PageSet hierarchy
+  - Button definitions
+  - Navigation links
+
 ### Cross-Format Conversion
 
 Convert between any supported AAC formats:
@@ -506,6 +579,7 @@ npx aac-processors analyze examples/example.gridset --pretty
 - `--pretty` - Human-readable output (analyze command)
 - `--verbose` - Detailed output (extract command)
 - `--quiet` - Minimal output (extract command)
+- `--gridset-password <password>` - Password for encrypted Grid 3 archives (`.gridsetx`)
 
 **Button Filtering Options:**
 
@@ -594,17 +668,17 @@ interface AACButton {
 
 ### Supported Processors
 
-| Processor               | File Extensions | Description                   |
-| ----------------------- | --------------- | ----------------------------- |
-| `DotProcessor`          | `.dot`          | Graphviz DOT format           |
-| `OpmlProcessor`         | `.opml`         | OPML hierarchical format      |
-| `ObfProcessor`          | `.obf`, `.obz`  | Open Board Format (JSON/ZIP)  |
-| `SnapProcessor`         | `.sps`, `.spb`  | Tobii Dynavox Snap format     |
-| `GridsetProcessor`      | `.gridset`      | Smartbox Grid 3 format        |
-| `TouchChatProcessor`    | `.ce`           | PRC-Saltillo TouchChat format |
-| `ApplePanelsProcessor`  | `.plist`        | iOS Apple Panels format       |
-| `AstericsGridProcessor` | `.grd`          | Asterics Grid native format   |
-| `ExcelProcessor`        | `.xlsx`         | Microsoft Excel format        |
+| Processor               | File Extensions         | Description                   |
+| ----------------------- | ----------------------- | ----------------------------- |
+| `DotProcessor`          | `.dot`                  | Graphviz DOT format           |
+| `OpmlProcessor`         | `.opml`                 | OPML hierarchical format      |
+| `ObfProcessor`          | `.obf`, `.obz`          | Open Board Format (JSON/ZIP)  |
+| `SnapProcessor`         | `.sps`, `.spb`          | Tobii Dynavox Snap format     |
+| `GridsetProcessor`      | `.gridset`, `.gridsetx` | Smartbox Grid 3 format        |
+| `TouchChatProcessor`    | `.ce`                   | PRC-Saltillo TouchChat format |
+| `ApplePanelsProcessor`  | `.plist`                | iOS Apple Panels format       |
+| `AstericsGridProcessor` | `.grd`                  | Asterics Grid native format   |
+| `ExcelProcessor`        | `.xlsx`                 | Microsoft Excel format        |
 
 ---
 

package/dist/cli/index.js

@@ -23,6 +23,9 @@ function detectFormat(filePath) {
 // Helper function to parse filtering options from CLI arguments
 function parseFilteringOptions(options) {
     const processorOptions = {};
+    if (options.gridsetPassword) {
+        processorOptions.gridsetPassword = options.gridsetPassword;
+    }
     // Handle preserve all buttons flag
     if (options.preserveAllButtons) {
         processorOptions.preserveAllButtons = true;
@@ -63,6 +66,7 @@ commander_1.program
     .option('--no-exclude-navigation', "Don't exclude navigation buttons (Home, Back)")
     .option('--no-exclude-system', "Don't exclude system buttons (Delete, Clear, etc.)")
     .option('--exclude-buttons <list>', 'Comma-separated list of button labels/terms to exclude')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
     .action((file, options) => {
     try {
         // Parse filtering options
@@ -97,6 +101,7 @@ commander_1.program
     .option('--no-exclude-navigation', "Don't exclude navigation buttons (Home, Back)")
     .option('--no-exclude-system', "Don't exclude system buttons (Delete, Clear, etc.)")
     .option('--exclude-buttons <list>', 'Comma-separated list of button labels/terms to exclude')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
     .action((file, options) => {
     try {
         // Parse filtering options
@@ -142,6 +147,7 @@ commander_1.program
     .option('--no-exclude-navigation', "Don't exclude navigation buttons (Home, Back)")
     .option('--no-exclude-system', "Don't exclude system buttons (Delete, Clear, etc.)")
     .option('--exclude-buttons <list>', 'Comma-separated list of button labels/terms to exclude')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
     .action(async (input, output, options) => {
     try {
         if (!options.format) {
@@ -182,6 +188,87 @@ commander_1.program
         process.exit(1);
     }
 });
+commander_1.program
+    .command('validate <file>')
+    .description('Validate an AAC file format')
+    .option('--format <format>', 'Format type (auto-detected if not specified)')
+    .option('--json', 'Output results as JSON')
+    .option('--quiet', 'Only output validation result (valid/invalid)')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
+    .action(async (file, options) => {
+    try {
+        // Auto-detect format if not specified
+        const format = options.format || detectFormat(file);
+        // Get processor with gridset password if provided
+        const processorOptions = {};
+        if (options.gridsetPassword) {
+            processorOptions.gridsetPassword = options.gridsetPassword;
+        }
+        const processor = (0, analyze_1.getProcessor)(format, processorOptions);
+        // Check if processor supports validation
+        if (!processor.validate) {
+            console.error(`Error: Validation not supported for format '${format}'`);
+            process.exit(1);
+        }
+        // Run validation
+        const result = await processor.validate(file);
+        // Output results
+        if (options.quiet) {
+            console.log(result.valid ? 'valid' : 'invalid');
+        }
+        else if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            // Pretty print validation results
+            console.log(`\nValidation Results for: ${result.filename}`);
+            console.log(`Format: ${result.format}`);
+            console.log(`File size: ${result.filesize} bytes`);
+            console.log(`Status: ${result.valid ? '✓ VALID' : '✗ INVALID'}`);
+            console.log(`Errors: ${result.errors}`);
+            console.log(`Warnings: ${result.warnings}\n`);
+            if (result.errors > 0 || result.warnings > 0) {
+                if (result.errors > 0) {
+                    console.log('Errors:');
+                    result.results
+                        .filter((r) => !r.valid)
+                        .forEach((check) => {
+                        console.log(`  ✗ ${check.description}`);
+                        if (check.error) {
+                            console.log(`    ${check.error}`);
+                        }
+                    });
+                }
+                if (result.warnings > 0) {
+                    console.log('\nWarnings:');
+                    result.results.forEach((check) => {
+                        if (check.warnings && check.warnings.length > 0) {
+                            console.log(`  ⚠ ${check.description}`);
+                            check.warnings.forEach((warning) => {
+                                console.log(`    ${warning}`);
+                            });
+                        }
+                    });
+                }
+            }
+            // Show sub-results if available
+            if (result.sub_results && result.sub_results.length > 0) {
+                console.log('\nSub-results:');
+                result.sub_results.forEach((sub, idx) => {
+                    console.log(`  [${idx + 1}] ${sub.filename}`);
+                    console.log(`      Status: ${sub.valid ? '✓' : '✗'} (${sub.errors} errors, ${sub.warnings} warnings)`);
+                });
+            }
+            console.log('');
+        }
+        // Exit with appropriate code
+        process.exit(result.valid ? 0 : 1);
+    }
+    catch (error) {
+        console.error('Error validating file:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
 // Show help if no command provided
 if (process.argv.length <= 2) {
     commander_1.program.help();

package/dist/core/analyze.js

@@ -27,6 +27,7 @@ function getProcessor(format, options) {
         case 'ce': // TouchChat file extension
             return new touchchatProcessor_1.TouchChatProcessor(options);
         case 'gridset':
+        case 'gridsetx':
             return new gridsetProcessor_1.GridsetProcessor(options); // Grid3 format
         case 'grd': // Asterics Grid file extension
             return new astericsGridProcessor_1.AstericsGridProcessor(options);

package/dist/core/baseProcessor.d.ts

@@ -1,10 +1,15 @@
 import { AACTree, AACButton } from './treeStructure';
 import { StringCasing } from './stringCasing';
+import { ValidationResult } from '../validation/validationTypes';
 export interface ProcessorOptions {
     excludeNavigationButtons?: boolean;
     excludeSystemButtons?: boolean;
+    gridsetPassword?: string;
     customButtonFilter?: (button: AACButton) => boolean;
     preserveAllButtons?: boolean;
+    grid3SymbolDir?: string;
+    grid3Path?: string;
+    grid3Locale?: string;
 }
 export interface ExtractedString {
     string: string;
@@ -44,6 +49,7 @@ declare abstract class BaseProcessor {
     abstract loadIntoTree(filePathOrBuffer: string | Buffer): AACTree;
     abstract processTexts(filePathOrBuffer: string | Buffer, translations: Map<string, string>, outputPath: string): Buffer;
     abstract saveFromTree(tree: AACTree, outputPath: string): void | Promise<void>;
+    validate?(filePath: string): Promise<ValidationResult>;
     /**
      * Extract strings with metadata for external platform integration
      * @param filePath - Path to the AAC file

package/dist/core/fileProcessor.js

@@ -20,6 +20,7 @@ class FileProcessor {
             const ext = path_1.default.extname(filePathOrBuffer).toLowerCase();
             switch (ext) {
                 case '.gridset':
+                case '.gridsetx':
                     return 'gridset';
                 case '.obf':
                 case '.obz':

package/dist/core/treeStructure.d.ts

@@ -115,7 +115,7 @@ export declare class AACButton implements IAACButton {
     parameters?: {
         [key: string]: any;
     };
-    constructor({ id, label, message, targetPageId, semanticAction, audioRecording, style, contentType, contentSubType, image, resolvedImageEntry, x, y, columnSpan, rowSpan, scanBlocks, visibility, directActivate, parameters, type, action, }: {
+    constructor({ id, label, message, targetPageId, semanticAction, audioRecording, style, contentType, contentSubType, image, resolvedImageEntry, symbolLibrary, symbolPath, x, y, columnSpan, rowSpan, scanBlocks, visibility, directActivate, parameters, type, action, }: {
         id: string;
         label?: string;
         message?: string;
@@ -132,6 +132,8 @@ export declare class AACButton implements IAACButton {
         contentSubType?: string;
         image?: string;
         resolvedImageEntry?: string;
+        symbolLibrary?: string;
+        symbolPath?: string;
         x?: number;
         y?: number;
         columnSpan?: number;

package/dist/core/treeStructure.js

@@ -43,7 +43,7 @@ var AACSemanticIntent;
     AACSemanticIntent["PLATFORM_SPECIFIC"] = "PLATFORM_SPECIFIC";
 })(AACSemanticIntent || (exports.AACSemanticIntent = AACSemanticIntent = {}));
 class AACButton {
-    constructor({ id, label = '', message = '', targetPageId, semanticAction, audioRecording, style, contentType, contentSubType, image, resolvedImageEntry, x, y, columnSpan, rowSpan, scanBlocks, visibility, directActivate, parameters, 
+    constructor({ id, label = '', message = '', targetPageId, semanticAction, audioRecording, style, contentType, contentSubType, image, resolvedImageEntry, symbolLibrary, symbolPath, x, y, columnSpan, rowSpan, scanBlocks, visibility, directActivate, parameters, 
     // Legacy input support
     type, action, }) {
         this.id = id;
@@ -57,6 +57,8 @@ class AACButton {
         this.contentSubType = contentSubType;
         this.image = image;
         this.resolvedImageEntry = resolvedImageEntry;
+        this.symbolLibrary = symbolLibrary;
+        this.symbolPath = symbolPath;
         this.x = x;
         this.y = y;
         this.columnSpan = columnSpan;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './core/baseProcessor';
 export * from './core/stringCasing';
 export * from './processors';
 export { collectUnifiedHistory, listGrid3Users as listHistoryGrid3Users, listSnapUsers as listHistorySnapUsers, } from './analytics/history';
+export * from './validation';
 import { BaseProcessor } from './core/baseProcessor';
 /**
  * Factory function to get the appropriate processor for a file extension

package/dist/index.js

@@ -27,6 +27,7 @@ var history_1 = require("./analytics/history");
 Object.defineProperty(exports, "collectUnifiedHistory", { enumerable: true, get: function () { return history_1.collectUnifiedHistory; } });
 Object.defineProperty(exports, "listHistoryGrid3Users", { enumerable: true, get: function () { return history_1.listGrid3Users; } });
 Object.defineProperty(exports, "listHistorySnapUsers", { enumerable: true, get: function () { return history_1.listSnapUsers; } });
+__exportStar(require("./validation"), exports);
 const dotProcessor_1 = require("./processors/dotProcessor");
 const excelProcessor_1 = require("./processors/excelProcessor");
 const opmlProcessor_1 = require("./processors/opmlProcessor");
@@ -58,6 +59,7 @@ function getProcessor(filePathOrExtension) {
         case '.obz':
             return new obfProcessor_1.ObfProcessor();
         case '.gridset':
+        case '.gridsetx':
             return new gridsetProcessor_1.GridsetProcessor();
         case '.spb':
         case '.sps':
@@ -84,6 +86,7 @@ function getSupportedExtensions() {
         '.obf',
         '.obz',
         '.gridset',
+        '.gridsetx',
         '.spb',
         '.sps',
         '.ce',

package/dist/optional/symbolTools.js

@@ -7,6 +7,7 @@ exports.TouchChatSymbolResolver = exports.TouchChatSymbolExtractor = exports.Gri
 exports.resolveSymbol = resolveSymbol;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
+const password_1 = require("../processors/gridset/password");
 // --- Base Classes ---
 class SymbolExtractor {
 }
@@ -76,8 +77,9 @@ class Grid3SymbolExtractor extends SymbolExtractor {
         const zip = new AdmZip(filePath);
         const parser = new XMLParser();
         const refs = new Set();
-        zip.getEntries().forEach((entry) => {
-            if (entry.entryName.endsWith('.gridset')) {
+        const entries = (0, password_1.getZipEntriesWithPassword)(zip, (0, password_1.resolveGridsetPasswordFromEnv)());
+        entries.forEach((entry) => {
+            if (entry.entryName.endsWith('.gridset') || entry.entryName.endsWith('.gridsetx')) {
                 const xmlBuffer = entry.getData();
                 // Parse to validate XML structure (future: extract refs)
                 parser.parse(xmlBuffer.toString('utf8'));

package/dist/processors/gridset/colorUtils.d.ts

@@ -54,6 +54,24 @@ export declare function toHexColor(value: string): string | undefined;
  * @returns Darkened hex color
  */
 export declare function darkenColor(hex: string, amount: number): string;
+/**
+ * Lighten a hex color by a specified amount
+ * @param hex - Hex color string
+ * @param amount - Amount to lighten (0-255)
+ * @returns Lightened hex color
+ */
+export declare function lightenColor(hex: string, amount: number): string;
+/**
+ * Convert hex color to RGBA object
+ * @param hex - Hex color string (#RRGGBB or #RRGGBBAA)
+ * @returns RGBA object with r, g, b, a properties (0-1 for alpha)
+ */
+export declare function hexToRgba(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
 /**
  * Normalize any color format to Grid3's 8-digit hex format
  * @param input - Color string in any supported format

package/dist/processors/gridset/colorUtils.js

@@ -16,6 +16,8 @@ exports.clampColorChannel = clampColorChannel;
 exports.clampAlpha = clampAlpha;
 exports.toHexColor = toHexColor;
 exports.darkenColor = darkenColor;
+exports.lightenColor = lightenColor;
+exports.hexToRgba = hexToRgba;
 exports.normalizeColor = normalizeColor;
 exports.ensureAlphaChannel = ensureAlphaChannel;
 /**
@@ -288,6 +290,40 @@ function darkenColor(hex, amount) {
     const newB = clamp(b - amount);
     return `#${channelToHex(newR)}${channelToHex(newG)}${channelToHex(newB)}${alpha.toUpperCase()}`;
 }
+/**
+ * Lighten a hex color by a specified amount
+ * @param hex - Hex color string
+ * @param amount - Amount to lighten (0-255)
+ * @returns Lightened hex color
+ */
+function lightenColor(hex, amount) {
+    const normalized = ensureAlphaChannel(hex).substring(1); // strip #
+    const rgb = normalized.substring(0, 6);
+    const alpha = normalized.substring(6) || 'FF';
+    const r = parseInt(rgb.substring(0, 2), 16);
+    const g = parseInt(rgb.substring(2, 4), 16);
+    const b = parseInt(rgb.substring(4, 6), 16);
+    const clamp = (val) => Math.max(0, Math.min(255, val));
+    const newR = clamp(r + amount);
+    const newG = clamp(g + amount);
+    const newB = clamp(b + amount);
+    return `#${channelToHex(newR)}${channelToHex(newG)}${channelToHex(newB)}${alpha.toUpperCase()}`;
+}
+/**
+ * Convert hex color to RGBA object
+ * @param hex - Hex color string (#RRGGBB or #RRGGBBAA)
+ * @returns RGBA object with r, g, b, a properties (0-1 for alpha)
+ */
+function hexToRgba(hex) {
+    const normalized = ensureAlphaChannel(hex).substring(1); // strip #
+    const rgb = normalized.substring(0, 6);
+    const alphaHex = normalized.substring(6) || 'FF';
+    const r = parseInt(rgb.substring(0, 2), 16);
+    const g = parseInt(rgb.substring(2, 4), 16);
+    const b = parseInt(rgb.substring(4, 6), 16);
+    const a = parseInt(alphaHex, 16) / 255;
+    return { r, g, b, a };
+}
 /**
  * Normalize any color format to Grid3's 8-digit hex format
  * @param input - Color string in any supported format

package/dist/processors/gridset/commands.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Grid 3 Command Definitions and Detection System
+ *
+ * This module provides comprehensive metadata for all Grid 3 commands,
+ * organized by plugin/category. It enables:
+ * - Command detection and classification
+ * - Parameter extraction
+ * - Future extensibility for command execution
+ * - Semantic action mapping
+ *
+ * Grid 3 has 33+ plugins with 200+ commands. This catalog captures
+ * the most commonly used and important commands.
+ */
+/**
+ * Command categories in Grid 3
+ */
+export declare enum Grid3CommandCategory {
+    NAVIGATION = "navigation",
+    COMMUNICATION = "communication",
+    TEXT_EDITING = "text_editing",
+    COMPUTER_CONTROL = "computer_control",
+    WEB_BROWSER = "web_browser",
+    EMAIL = "email",
+    PHONE = "phone",
+    SMS = "sms",
+    SYSTEM = "system",
+    SETTINGS = "settings",
+    SPEECH = "speech",
+    AUTO_CONTENT = "auto_content",
+    ENVIRONMENT_CONTROL = "environment_control",
+    MOUSE = "mouse",
+    WINDOW = "window",
+    MEDIA = "media",
+    CUSTOM = "custom"
+}
+/**
+ * Parameter definition for commands
+ */
+export interface CommandParameter {
+    key: string;
+    type: 'string' | 'number' | 'boolean' | 'grid' | 'color' | 'font';
+    required: boolean;
+    description?: string;
+}
+/**
+ * Command metadata definition
+ */
+export interface Grid3CommandDefinition {
+    id: string;
+    category: Grid3CommandCategory;
+    pluginId: string;
+    displayName: string;
+    description: string;
+    parameters?: CommandParameter[];
+    platforms?: ('desktop' | 'ios' | 'medicare' | 'medicareBionics')[];
+    deprecated?: boolean;
+}
+/**
+ * Registry of all Grid 3 commands
+ * Key is command ID (e.g., 'Jump.To', 'Action.InsertText')
+ */
+export declare const GRID3_COMMANDS: Record<string, Grid3CommandDefinition>;
+/**
+ * Get command definition by ID
+ */
+export declare function getCommandDefinition(commandId: string): Grid3CommandDefinition | undefined;
+/**
+ * Check if a command ID is known
+ */
+export declare function isKnownCommand(commandId: string): boolean;
+/**
+ * Get all commands for a specific plugin
+ */
+export declare function getCommandsByPlugin(pluginId: string): Grid3CommandDefinition[];
+/**
+ * Get all commands in a category
+ */
+export declare function getCommandsByCategory(category: Grid3CommandCategory): Grid3CommandDefinition[];
+/**
+ * Get all command IDs
+ */
+export declare function getAllCommandIds(): string[];
+/**
+ * Get all plugin IDs that have commands
+ */
+export declare function getAllPluginIds(): string[];
+/**
+ * Extract parameters from a Grid 3 command object
+ */
+export interface ExtractedParameters {
+    [key: string]: string | number | boolean;
+}
+export declare function extractCommandParameters(command: any): ExtractedParameters;
+/**
+ * Detect and categorize a command from Grid 3
+ */
+export declare function detectCommand(commandObj: any): {
+    id: string;
+    definition?: Grid3CommandDefinition;
+    parameters: ExtractedParameters;
+    category: Grid3CommandCategory | 'unknown';
+    pluginId: string | 'unknown';
+};