glost 0.2.0 → 0.4.0

package/src/cli/migrate.ts

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * GLOST Migration CLI
+ * 
+ * Command-line interface for migrating GLOST documents
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Type declarations for glost-utils (dynamically imported)
+type MigrationResult = {
+  nodesUpdated: number;
+  changes: Array<{ path: string; oldCode: string; newCode: string }>;
+  hasChanges: boolean;
+};
+
+type TranscriptionMigrationResult = {
+  transcriptionsUpdated: number;
+  nodesProcessed: number;
+  hasChanges: boolean;
+  changes: Array<{ path: string; systems: string[] }>;
+};
+
+type GlostUtils = {
+  migrateAllLanguageCodes: (doc: any, options?: any) => MigrationResult;
+  migrateTranscriptionSchema: (doc: any, options?: any) => TranscriptionMigrationResult;
+};
+
+// Import migration functions from glost-utils
+async function loadUtils(): Promise<GlostUtils> {
+  try {
+    // @ts-expect-error - glost-utils is an optional peer dependency
+    const utils = await import('glost-utils') as any;
+    return {
+      migrateAllLanguageCodes: utils.migrateAllLanguageCodes,
+      migrateTranscriptionSchema: utils.migrateTranscriptionSchema,
+    };
+  } catch (error) {
+    console.error('Error: glost-utils is required for migration.');
+    console.error('Install it with: npm install glost-utils');
+    process.exit(1);
+  }
+}
+
+interface CompleteMigrationResult {
+  languageCodes: MigrationResult;
+  transcriptionSchema: TranscriptionMigrationResult;
+  totalChanges: number;
+  success: boolean;
+}
+
+async function migrateToV04(doc: any, options: { dryRun?: boolean; addDefaultRegions?: boolean } = {}): Promise<CompleteMigrationResult> {
+  const { dryRun = false } = options;
+  const utils = await loadUtils();
+
+  const languageCodes = utils.migrateAllLanguageCodes(doc, {
+    addDefaultRegions: options.addDefaultRegions ?? true,
+    dryRun,
+  });
+
+  const transcriptionSchema = utils.migrateTranscriptionSchema(doc, {
+    dryRun,
+  });
+
+  const totalChanges = languageCodes.changes.length + transcriptionSchema.transcriptionsUpdated;
+
+  return {
+    languageCodes,
+    transcriptionSchema,
+    totalChanges,
+    success: true,
+  };
+}
+
+const args = process.argv.slice(2);
+
+function showHelp() {
+  console.log(`
+GLOST Migration Tool
+
+Usage:
+  glost migrate <command> <path>
+
+Commands:
+  v0.3-to-v0.4 <path>      Migrate documents from v0.3.x to v0.4.0
+  analyze <path>           Analyze what would be migrated (dry run)
+  help                     Show this help message
+
+Options:
+  --no-regions            Don't add default regions to language codes
+  --dry-run               Show what would change without modifying files
+
+Examples:
+  glost migrate v0.3-to-v0.4 ./docs
+  glost migrate analyze ./docs/story.glost.json
+  glost migrate v0.3-to-v0.4 ./docs --dry-run
+`);
+}
+
+function isGlostFile(filePath: string): boolean {
+  return filePath.endsWith('.glost.json') || filePath.endsWith('.json');
+}
+
+function findGlostFiles(dir: string): string[] {
+  const files: string[] = [];
+  
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      
+      if (entry.isDirectory()) {
+        if (entry.name !== 'node_modules' && entry.name !== '.git') {
+          files.push(...findGlostFiles(fullPath));
+        }
+      } else if (entry.isFile() && isGlostFile(entry.name)) {
+        files.push(fullPath);
+      }
+    }
+  } catch (error) {
+    console.error(`Error reading directory ${dir}:`, error);
+  }
+  
+  return files;
+}
+
+async function migrateFile(filePath: string, options: { dryRun?: boolean; addDefaultRegions?: boolean }) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const doc = JSON.parse(content);
+    
+    const result = await migrateToV04(doc, options);
+    
+    if (result.totalChanges === 0) {
+      console.log(`✓ ${filePath} - No changes needed`);
+      return { changed: false, file: filePath };
+    }
+    
+    console.log(`${options.dryRun ? '○' : '✓'} ${filePath} - ${result.totalChanges} changes`);
+    
+    if (result.languageCodes.changes.length > 0) {
+      console.log(`  Language codes: ${result.languageCodes.nodesUpdated} nodes updated`);
+    }
+    
+    if (result.transcriptionSchema.transcriptionsUpdated > 0) {
+      console.log(`  Transcriptions: ${result.transcriptionSchema.transcriptionsUpdated} updated`);
+    }
+    
+    if (!options.dryRun) {
+      fs.writeFileSync(filePath, JSON.stringify(doc, null, 2));
+    }
+    
+    return { changed: true, file: filePath, changes: result.totalChanges };
+  } catch (error) {
+    console.error(`✗ ${filePath} - Error:`, (error as Error).message);
+    return { changed: false, file: filePath, error };
+  }
+}
+
+async function main() {
+  if (args.length === 0 || args[0] === 'help') {
+    showHelp();
+    process.exit(0);
+  }
+  
+  const command = args[0];
+  const targetPath = args[1];
+  
+  if (!targetPath) {
+    console.error('Error: No path provided');
+    showHelp();
+    process.exit(1);
+  }
+  
+  const options = {
+    dryRun: args.includes('--dry-run'),
+    addDefaultRegions: !args.includes('--no-regions'),
+  };
+  
+  const fullPath = path.resolve(targetPath);
+  
+  if (!fs.existsSync(fullPath)) {
+    console.error(`Error: Path does not exist: ${fullPath}`);
+    process.exit(1);
+  }
+  
+  const stats = fs.statSync(fullPath);
+  let files: string[];
+  
+  if (stats.isDirectory()) {
+    files = findGlostFiles(fullPath);
+    
+    if (files.length === 0) {
+      console.log('No GLOST files found in directory');
+      process.exit(0);
+    }
+    
+    console.log(`Found ${files.length} GLOST file(s)\n`);
+  } else if (stats.isFile()) {
+    if (!isGlostFile(fullPath)) {
+      console.error('Error: File does not appear to be a GLOST document');
+      process.exit(1);
+    }
+    files = [fullPath];
+  } else {
+    console.error('Error: Path is neither a file nor a directory');
+    process.exit(1);
+  }
+  
+  switch (command) {
+    case 'v0.3-to-v0.4':
+    case 'v0-to-v04':
+    case 'migrate': {
+      if (options.dryRun) {
+        console.log('DRY RUN - No files will be modified\n');
+      }
+      
+      let totalChanged = 0;
+      let totalChanges = 0;
+      
+      for (const file of files) {
+        const result = await migrateFile(file, options);
+        if (result.changed) {
+          totalChanged++;
+          totalChanges += result.changes || 0;
+        }
+      }
+      
+      console.log(`\nSummary:`);
+      console.log(`  Files processed: ${files.length}`);
+      console.log(`  Files ${options.dryRun ? 'needing changes' : 'changed'}: ${totalChanged}`);
+      console.log(`  Total changes: ${totalChanges}`);
+      
+      if (options.dryRun && totalChanged > 0) {
+        console.log(`\nRun without --dry-run to apply changes`);
+      }
+      
+      break;
+    }
+    
+    case 'analyze': {
+      for (const file of files) {
+        try {
+          const content = fs.readFileSync(file, 'utf-8');
+          const doc = JSON.parse(content);
+          const result = await migrateToV04(doc, { dryRun: true });
+          
+          console.log(`\nFile: ${file}`);
+          console.log(`Total changes needed: ${result.totalChanges}`);
+          
+          if (result.languageCodes.changes.length > 0) {
+            console.log(`\nLanguage code changes (${result.languageCodes.changes.length}):`);
+            result.languageCodes.changes.slice(0, 5).forEach(change => {
+              console.log(`  ${change.path}: ${change.oldCode} → ${change.newCode}`);
+            });
+            if (result.languageCodes.changes.length > 5) {
+              console.log(`  ... and ${result.languageCodes.changes.length - 5} more`);
+            }
+          }
+          
+          if (result.transcriptionSchema.changes.length > 0) {
+            console.log(`\nTranscription schema changes (${result.transcriptionSchema.changes.length}):`);
+            result.transcriptionSchema.changes.slice(0, 5).forEach(change => {
+              console.log(`  ${change.path}: systems ${change.systems.join(', ')}`);
+            });
+            if (result.transcriptionSchema.changes.length > 5) {
+              console.log(`  ... and ${result.transcriptionSchema.changes.length - 5} more`);
+            }
+          }
+          
+          if (result.totalChanges === 0) {
+            console.log('No changes needed');
+          }
+        } catch (error) {
+          console.error(`Error analyzing ${file}:`, (error as Error).message);
+        }
+      }
+      break;
+    }
+    
+    default:
+      console.error(`Unknown command: ${command}`);
+      showHelp();
+      process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/src/errors.ts

@@ -0,0 +1,394 @@
+/**
+ * GLOST Error Classes
+ * 
+ * Comprehensive error handling with context, suggestions, and helpful messages
+ * 
+ * @packageDocumentation
+ */
+
+import type { GLOSTNode } from './types.js';
+
+/**
+ * Context information for GLOST errors
+ */
+export interface GLOSTErrorContext {
+  /** The node where the error occurred */
+  node?: GLOSTNode;
+  /** Path to the node in the document tree */
+  path?: string[];
+  /** Source file path (if known) */
+  file?: string;
+  /** Suggestion for fixing the error */
+  suggestion?: string;
+  /** URL to relevant documentation */
+  docsUrl?: string;
+  /** Additional context data */
+  [key: string]: any;
+}
+
+/**
+ * Base class for all GLOST errors
+ */
+export class GLOSTError extends Error {
+  public readonly context: GLOSTErrorContext;
+
+  constructor(message: string, context: GLOSTErrorContext = {}) {
+    super(message);
+    this.name = 'GLOSTError';
+    this.context = context;
+
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Format error message with context
+   */
+  toString(): string {
+    const parts: string[] = [];
+
+    // Header
+    parts.push(`${this.name}: ${this.message}`);
+    parts.push('');
+
+    // Location information
+    if (this.context.path) {
+      parts.push(`  Location: ${this.context.path.join('.')}`);
+    }
+    if (this.context.file) {
+      parts.push(`  File: ${this.context.file}`);
+    }
+    if (this.context.node) {
+      parts.push(`  Node type: ${(this.context.node as any).type || 'unknown'}`);
+    }
+
+    // Suggestion
+    if (this.context.suggestion) {
+      parts.push('');
+      parts.push(`  Suggestion: ${this.context.suggestion}`);
+    }
+
+    // Documentation link
+    if (this.context.docsUrl) {
+      parts.push('');
+      parts.push(`  Documentation: ${this.context.docsUrl}`);
+    }
+
+    // Stack trace
+    if (this.stack) {
+      parts.push('');
+      parts.push('  Stack trace:');
+      const stackLines = this.stack.split('\n').slice(1); // Skip first line (message)
+      parts.push(...stackLines.map(line => `  ${line}`));
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Get a concise error summary
+   */
+  toSummary(): string {
+    let summary = `${this.name}: ${this.message}`;
+    if (this.context.path) {
+      summary += ` (at ${this.context.path.join('.')})`;
+    }
+    return summary;
+  }
+}
+
+/**
+ * Validation error for schema violations
+ */
+export class GLOSTValidationError extends GLOSTError {
+  constructor(message: string, context: GLOSTErrorContext = {}) {
+    super(message, context);
+    this.name = 'GLOSTValidationError';
+  }
+
+  toString(): string {
+    const parts: string[] = [];
+
+    parts.push(`${this.name}: ${this.message}`);
+    parts.push('');
+
+    // Location
+    if (this.context.path) {
+      const location = this.context.path.length > 0 
+        ? this.context.path.join('.')
+        : 'root';
+      parts.push(`  Location: ${location}`);
+    }
+
+    if (this.context.node) {
+      const node = this.context.node as any;
+      parts.push(`  Node type: ${node.type || 'unknown'}`);
+    }
+
+    if (this.context.file) {
+      parts.push(`  File: ${this.context.file}`);
+    }
+
+    // Expected vs Received
+    if (this.context.expected) {
+      parts.push('');
+      parts.push(`  Expected: ${JSON.stringify(this.context.expected, null, 2)}`);
+    }
+
+    if (this.context.received) {
+      parts.push(`  Received: ${JSON.stringify(this.context.received, null, 2)}`);
+    }
+
+    // Problem explanation
+    if (this.context.problem) {
+      parts.push('');
+      parts.push(`  Problem: ${this.context.problem}`);
+    }
+
+    // Suggestion
+    if (this.context.suggestion) {
+      parts.push('');
+      parts.push(`  Suggestion: ${this.context.suggestion}`);
+    }
+
+    // Documentation
+    if (this.context.docsUrl) {
+      parts.push('');
+      parts.push(`  Documentation: ${this.context.docsUrl}`);
+    }
+
+    return parts.join('\n');
+  }
+}
+
+/**
+ * Error for missing required fields
+ */
+export class GLOSTMissingFieldError extends GLOSTValidationError {
+  constructor(
+    fieldName: string,
+    nodeType: string,
+    context: GLOSTErrorContext = {}
+  ) {
+    const message = `Missing required field '${fieldName}' on ${nodeType}`;
+    super(message, {
+      ...context,
+      problem: `${nodeType} must have a '${fieldName}' field.`,
+      docsUrl: context.docsUrl || `https://glost.dev/docs/node-types#${nodeType.toLowerCase()}`,
+    });
+    this.name = 'GLOSTMissingFieldError';
+  }
+}
+
+/**
+ * Error for invalid field types
+ */
+export class GLOSTInvalidTypeError extends GLOSTValidationError {
+  constructor(
+    fieldName: string,
+    expectedType: string,
+    receivedType: string,
+    context: GLOSTErrorContext = {}
+  ) {
+    const message = `Invalid type for field '${fieldName}': expected ${expectedType}, got ${receivedType}`;
+    super(message, {
+      ...context,
+      problem: `Field '${fieldName}' must be of type ${expectedType}.`,
+      suggestion: `Convert the value to ${expectedType} or check your data source.`,
+    });
+    this.name = 'GLOSTInvalidTypeError';
+  }
+}
+
+/**
+ * Error for invalid language codes
+ */
+export class GLOSTInvalidLanguageCodeError extends GLOSTValidationError {
+  constructor(
+    code: string,
+    context: GLOSTErrorContext = {}
+  ) {
+    const message = `Invalid language code: "${code}"`;
+    super(message, {
+      ...context,
+      problem: `Language codes must follow BCP-47 format (e.g., "en-US", "th-TH").`,
+      suggestion: `Use normalizeLanguageCode() from glost-common to convert "${code}" to a valid format.`,
+      docsUrl: context.docsUrl || 'https://glost.dev/docs/languages#bcp-47',
+    });
+    this.name = 'GLOSTInvalidLanguageCodeError';
+  }
+}
+
+/**
+ * Error for extension processing
+ */
+export class GLOSTExtensionError extends GLOSTError {
+  constructor(
+    extensionName: string,
+    message: string,
+    context: GLOSTErrorContext = {}
+  ) {
+    super(`[${extensionName}] ${message}`, context);
+    this.name = 'GLOSTExtensionError';
+  }
+}
+
+/**
+ * Error for provider issues
+ */
+export class GLOSTProviderError extends GLOSTError {
+  constructor(
+    providerName: string,
+    message: string,
+    context: GLOSTErrorContext = {}
+  ) {
+    super(`[${providerName} Provider] ${message}`, context);
+    this.name = 'GLOSTProviderError';
+  }
+}
+
+/**
+ * Error for document parsing
+ */
+export class GLOSTParseError extends GLOSTError {
+  constructor(message: string, context: GLOSTErrorContext = {}) {
+    super(message, context);
+    this.name = 'GLOSTParseError';
+  }
+}
+
+/**
+ * Error for serialization issues
+ */
+export class GLOSTSerializationError extends GLOSTError {
+  constructor(message: string, context: GLOSTErrorContext = {}) {
+    super(message, context);
+    this.name = 'GLOSTSerializationError';
+  }
+}
+
+/**
+ * Create a validation error with helpful context
+ * 
+ * @param message - Error message
+ * @param options - Error options
+ * @returns GLOSTValidationError instance
+ * 
+ * @example
+ * ```typescript
+ * throw createValidationError('Invalid word node', {
+ *   node: wordNode,
+ *   path: ['document', 'children', '0'],
+ *   suggestion: 'Add a "text" field to the word node',
+ *   docsUrl: 'https://glost.dev/docs/node-types#word'
+ * });
+ * ```
+ */
+export function createValidationError(
+  message: string,
+  options: {
+    node?: GLOSTNode;
+    path?: string[];
+    file?: string;
+    suggestion?: string;
+    docsUrl?: string;
+    expected?: any;
+    received?: any;
+    problem?: string;
+  } = {}
+): GLOSTValidationError {
+  return new GLOSTValidationError(message, options);
+}
+
+/**
+ * Format a path array as a readable string
+ * 
+ * @param path - Path array
+ * @returns Formatted path string
+ * 
+ * @example
+ * ```typescript
+ * formatPath(['document', 'children', '0', 'text'])
+ * // Returns: "document.children[0].text"
+ * ```
+ */
+export function formatPath(path: Array<string | number>): string {
+  if (path.length === 0) return 'root';
+
+  return path.reduce<string>((acc, segment, index) => {
+    if (index === 0) return String(segment);
+    
+    if (typeof segment === 'number' || !isNaN(Number(segment))) {
+      return `${acc}[${segment}]`;
+    }
+    
+    return `${acc}.${segment}`;
+  }, '');
+}
+
+/**
+ * Assert that a condition is true, throw validation error if not
+ * 
+ * @param condition - Condition to check
+ * @param message - Error message if condition is false
+ * @param context - Error context
+ * 
+ * @example
+ * ```typescript
+ * glostAssert(
+ *   node.type === 'word',
+ *   'Node must be a word node',
+ *   { node, path: ['document', 'children', '0'] }
+ * );
+ * ```
+ */
+export function glostAssert(
+  condition: any,
+  message: string,
+  context?: GLOSTErrorContext
+): asserts condition {
+  if (!condition) {
+    throw new GLOSTValidationError(message, context);
+  }
+}
+
+/**
+ * Wrap an error with additional GLOST context
+ * 
+ * @param error - Original error
+ * @param context - Additional context
+ * @returns GLOST error
+ * 
+ * @example
+ * ```typescript
+ * try {
+ *   await processNode(node);
+ * } catch (error) {
+ *   throw wrapError(error, {
+ *     node,
+ *     path: ['document', 'children', '0'],
+ *     suggestion: 'Check that the node has all required fields'
+ *   });
+ * }
+ * ```
+ */
+export function wrapError(
+  error: Error,
+  context: GLOSTErrorContext
+): GLOSTError {
+  if (error instanceof GLOSTError) {
+    // Merge contexts - create new error with merged context
+    return new GLOSTError(error.message, {
+      ...error.context,
+      ...context,
+    });
+  }
+
+  // Create new GLOST error
+  return new GLOSTError(error.message, {
+    ...context,
+    originalError: error,
+  });
+}

package/src/guards.ts

@@ -13,7 +13,7 @@ import type {
   GLOSTWhiteSpace,
   GLOSTWord,
   GLOSTNode,
-} from "./types";
+} from "./types.js";
 
 // ============================================================================
 // Core Node Type Guards