glost 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,150 @@
 # glost
 
+## 0.4.0
+
+### Minor Changes
+
+- Fixed critical production issues (ESM imports, BCP-47 language standardization, removed redundant transcription schema fields, renamed translation API sourceLanguage/targetLanguage → from/to) and added major DX improvements (typed extras via declaration merging, comprehensive error classes with suggestions, standard GLOSTDataProvider interface, built-in migration CLI tool npx glost migrate).
+
+### Patch Changes
+
+- Updated dependencies
+  - glost-common@0.2.0
+  - glost-utils@0.2.0
+
+## 0.4.0
+
+### Major Changes
+
+GLOST v0.4.0 brings critical production fixes and developer experience improvements based on 6+ months of real-world usage feedback from the lalia-prism team processing 50+ language learning stories across Thai and French.
+
+#### Breaking Changes
+
+**1. ESM Imports Fixed** 🔧
+
+- Added `.js` extensions to all barrel exports for proper Node.js ESM support
+- Updated TypeScript config to `moduleResolution: "node16"`
+- **Impact**: Fixes `Cannot find module` errors in Node.js ESM
+- **Migration**: Automatic when upgrading packages
+
+**2. BCP-47 Language Code Standard** 🌍
+
+- All language codes now standardized on BCP-47 format (e.g., `en-US`, `th-TH`)
+- Added comprehensive language utilities: `normalizeLanguageCode()`, `matchLanguage()`, `parseLanguageCode()`, `findBestMatch()`, `getLanguageFallbacks()`
+- **Impact**: Language codes like `"th"` become `"th-TH"`
+- **Migration**: Use `npx glost-migrate v0.3-to-v0.4 ./src` or `migrateAllLanguageCodes()` utility
+
+**3. Transcription Schema Cleanup** ✨
+
+- Removed redundant `system` field from `TranscriptionInfo` type
+- System name is already the key in the transcription object
+- **Before**: `{ ipa: { text: "hello", system: "ipa" } }`
+- **After**: `{ ipa: { text: "hello" } }`
+- **Migration**: Use `migrateTranscriptionSchema()` utility
+
+**4. Translation API Clarity** 📝
+
+- Renamed confusing `sourceLanguage`/`targetLanguage` to clear `from`/`to`
+- **Before**: `createTranslationExtension({ sourceLanguage: "th", targetLanguage: "en", ... })`
+- **After**: `createTranslationExtension({ from: "th", to: "en", ... })`
+- **Migration**: Manual update of extension calls
+
+#### New Features
+
+**Typed Extras via Declaration Merging** 🎯
+
+- Extensions can now augment `GLOSTExtras` interface for full type safety
+- Automatic TypeScript autocomplete for extension fields
+- No runtime overhead, pure type-level enhancement
+
+```typescript
+// In extension package
+declare module "glost" {
+  interface GLOSTExtras {
+    frequency?: {
+      rank: number;
+      category: "very-common" | "common" | "uncommon" | "rare";
+    };
+  }
+}
+
+// In user code - full autocomplete!
+word.extras.frequency?.rank; // number | undefined
+```
+
+**Standard Provider Interface** 🔌
+
+- New `GLOSTDataProvider<TInput, TOutput>` interface for consistency
+- Built-in support for batch processing, caching, and cleanup
+- Helper utilities: `createSimpleProvider()`, `createCachedProvider()`, `createFallbackProvider()`
+
+**Better Error Messages** 💬
+
+- New error classes with context, suggestions, and documentation links
+- Helpful error formatting with file paths and node locations
+- Error types: `GLOSTValidationError`, `GLOSTExtensionError`, `GLOSTProviderError`, etc.
+
+```typescript
+GLOSTValidationError: Missing required field 'text' on WordNode
+
+  Location: document.children[0]
+  Node type: WordNode
+  File: stories/test.glost.json:42
+
+  Suggestion: Add a 'text' field containing the word's text content.
+  Documentation: https://glost.dev/docs/node-types#wordnode
+```
+
+**Language Code Utilities** 🛠️
+
+- `normalizeLanguageCode()` - Convert to BCP-47
+- `matchLanguage()` - Flexible matching with options
+- `parseLanguageCode()` - Parse into components
+- `findBestMatch()` - Find closest match from available codes
+- `getLanguageFallbacks()` - Get fallback chain
+- `isValidBCP47()` - Validation
+- `asBCP47()` - Type-safe casting
+
+**Migration CLI** 🚀
+
+- Built-in migration CLI: `npx glost migrate`
+- Automated migration from v0.3.x to v0.4.0
+- Commands: `v0.3-to-v0.4`, `analyze`, `help`
+- Dry-run support for safe testing
+- Programmatic migration utilities in `glost-utils`
+
+### Improvements
+
+- **Bundle Size**: Foundation laid for future optimizations
+- **Type Safety**: Changed `GLOSTExtras` from type to interface for declaration merging
+- **Documentation**: Comprehensive migration guide and updated language docs
+- **Developer Experience**: Better error messages save significant debugging time
+
+### Fixes
+
+- Fixed ESM imports in all language packages
+- Fixed TypeScript moduleResolution for proper ESM output
+- Removed redundant schema fields reducing JSON size
+
+### Migration Guide
+
+See [MIGRATION_v0.3_to_v0.4.md](../../MIGRATION_v0.3_to_v0.4.md) for complete upgrade instructions.
+
+Quick migration:
+
+```bash
+npx glost migrate v0.3-to-v0.4 ./src
+```
+
+### Acknowledgments
+
+Special thanks to the lalia-prism team for their comprehensive RFC and 6+ months of production feedback that made this release possible. Their real-world experience with Thai and French language learning content identified critical issues and guided these improvements.
+
+### Dependencies
+
+- glost-common@0.4.0
+- glost-utils@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/cli/migrate.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * GLOST Migration CLI
+ *
+ * Command-line interface for migrating GLOST documents
+ */
+export {};
+//# sourceMappingURL=migrate.d.ts.map

package/dist/cli/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/cli/migrate.ts"],"names":[],"mappings":";AACA;;;;GAIG"}

package/dist/cli/migrate.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * GLOST Migration CLI
+ *
+ * Command-line interface for migrating GLOST documents
+ */
+import fs from 'fs';
+import path from 'path';
+// Import migration functions from glost-utils
+async function loadUtils() {
+    try {
+        // @ts-expect-error - glost-utils is an optional peer dependency
+        const utils = await import('glost-utils');
+        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);
+    }
+}
+async function migrateToV04(doc, options = {}) {
+    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) {
+    return filePath.endsWith('.glost.json') || filePath.endsWith('.json');
+}
+function findGlostFiles(dir) {
+    const files = [];
+    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, options) {
+    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.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;
+    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.message);
+                }
+            }
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            showHelp();
+            process.exit(1);
+    }
+}
+main().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=migrate.js.map

package/dist/cli/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/cli/migrate.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 declare class GLOSTError extends Error {
+    readonly context: GLOSTErrorContext;
+    constructor(message: string, context?: GLOSTErrorContext);
+    /**
+     * Format error message with context
+     */
+    toString(): string;
+    /**
+     * Get a concise error summary
+     */
+    toSummary(): string;
+}
+/**
+ * Validation error for schema violations
+ */
+export declare class GLOSTValidationError extends GLOSTError {
+    constructor(message: string, context?: GLOSTErrorContext);
+    toString(): string;
+}
+/**
+ * Error for missing required fields
+ */
+export declare class GLOSTMissingFieldError extends GLOSTValidationError {
+    constructor(fieldName: string, nodeType: string, context?: GLOSTErrorContext);
+}
+/**
+ * Error for invalid field types
+ */
+export declare class GLOSTInvalidTypeError extends GLOSTValidationError {
+    constructor(fieldName: string, expectedType: string, receivedType: string, context?: GLOSTErrorContext);
+}
+/**
+ * Error for invalid language codes
+ */
+export declare class GLOSTInvalidLanguageCodeError extends GLOSTValidationError {
+    constructor(code: string, context?: GLOSTErrorContext);
+}
+/**
+ * Error for extension processing
+ */
+export declare class GLOSTExtensionError extends GLOSTError {
+    constructor(extensionName: string, message: string, context?: GLOSTErrorContext);
+}
+/**
+ * Error for provider issues
+ */
+export declare class GLOSTProviderError extends GLOSTError {
+    constructor(providerName: string, message: string, context?: GLOSTErrorContext);
+}
+/**
+ * Error for document parsing
+ */
+export declare class GLOSTParseError extends GLOSTError {
+    constructor(message: string, context?: GLOSTErrorContext);
+}
+/**
+ * Error for serialization issues
+ */
+export declare class GLOSTSerializationError extends GLOSTError {
+    constructor(message: string, context?: GLOSTErrorContext);
+}
+/**
+ * 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 declare function createValidationError(message: string, options?: {
+    node?: GLOSTNode;
+    path?: string[];
+    file?: string;
+    suggestion?: string;
+    docsUrl?: string;
+    expected?: any;
+    received?: any;
+    problem?: string;
+}): GLOSTValidationError;
+/**
+ * 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 declare function formatPath(path: Array<string | number>): string;
+/**
+ * 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 declare function glostAssert(condition: any, message: string, context?: GLOSTErrorContext): asserts condition;
+/**
+ * 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 declare function wrapError(error: Error, context: GLOSTErrorContext): GLOSTError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}