@globaltypesystem/gts-ts 0.1.0

package/src/cast.ts

@@ -0,0 +1,179 @@
+import { CastResult } from './types';
+import { GtsStore } from './store';
+import { Gts } from './gts';
+import { GtsCompatibility } from './compatibility';
+
+export class GtsCast {
+  static castInstance(store: GtsStore, fromId: string, toSchemaId: string): CastResult {
+    try {
+      const fromGtsId = Gts.parseGtsID(fromId);
+      const fromEntity = store.get(fromGtsId.id);
+
+      if (!fromEntity) {
+        return {
+          ok: false,
+          fromId,
+          toId: toSchemaId,
+          error: `Instance not found: ${fromId}`,
+        };
+      }
+
+      if (!fromEntity.schemaId) {
+        return {
+          ok: false,
+          fromId,
+          toId: toSchemaId,
+          error: `No schema found for instance: ${fromId}`,
+        };
+      }
+
+      const toGtsId = Gts.parseGtsID(toSchemaId);
+      const toSchema = store.get(toGtsId.id);
+
+      if (!toSchema) {
+        return {
+          ok: false,
+          fromId,
+          toId: toSchemaId,
+          error: `Target schema not found: ${toSchemaId}`,
+        };
+      }
+
+      if (!toSchema.isSchema) {
+        return {
+          ok: false,
+          fromId,
+          toId: toSchemaId,
+          error: `Target is not a schema: ${toSchemaId}`,
+        };
+      }
+
+      const fromSchemaEntity = store.get(fromEntity.schemaId);
+      if (!fromSchemaEntity) {
+        return {
+          ok: false,
+          fromId,
+          toId: toSchemaId,
+          error: `Source schema not found: ${fromEntity.schemaId}`,
+        };
+      }
+
+      const compatCheck = GtsCompatibility.checkCompatibility(store, fromEntity.schemaId, toSchemaId, 'full');
+
+      if (!compatCheck.compatible) {
+        return {
+          ok: false,
+          fromId,
+          toId: toSchemaId,
+          error: `Schemas are not compatible: ${compatCheck.errors.join('; ')}`,
+        };
+      }
+
+      const castedInstance = this.performCast(
+        fromEntity.content,
+        fromSchemaEntity.content,
+        toSchema.content,
+        toSchemaId
+      );
+
+      return {
+        ok: true,
+        fromId,
+        toId: toSchemaId,
+        result: castedInstance,
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        fromId,
+        toId: toSchemaId,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  private static performCast(instance: any, fromSchema: any, toSchema: any, toSchemaId: string): any {
+    const result: any = { ...instance };
+
+    const fromSegments = Gts.parseID(fromSchema['$$id'] || fromSchema['$id']).segments;
+    const toSegments = Gts.parseID(toSchemaId).segments;
+
+    if (fromSegments.length > 0 && toSegments.length > 0) {
+      const fromVersion = `v${fromSegments[0].verMajor}.${fromSegments[0].verMinor ?? 0}`;
+      const toVersion = `v${toSegments[0].verMajor}.${toSegments[0].verMinor ?? 0}`;
+
+      if ('gtsId' in result) {
+        result.gtsId = result.gtsId.replace(fromVersion, toVersion);
+      }
+    }
+
+    if ('$schema' in result || '$$schema' in result) {
+      result['$schema'] = toSchemaId;
+      if ('$$schema' in result) {
+        result['$$schema'] = toSchemaId;
+      }
+    }
+
+    const toProps = toSchema.properties || {};
+    const toRequired = new Set(toSchema.required || []);
+
+    const filtered: any = {};
+    for (const [key, value] of Object.entries(result)) {
+      if (key in toProps || key === 'gtsId' || key === '$schema' || key === '$$schema') {
+        filtered[key] = value;
+      }
+    }
+
+    for (const prop of toRequired) {
+      if (!((prop as string) in filtered)) {
+        const propSchema = toProps[prop as string];
+        if (propSchema) {
+          filtered[prop as string] = this.getDefaultValue(propSchema);
+        }
+      }
+    }
+
+    // Also add properties with default values that aren't required
+    for (const [propName, propSchema] of Object.entries(toProps)) {
+      if (!(propName in filtered) && propSchema && typeof propSchema === 'object' && 'default' in propSchema) {
+        filtered[propName] = propSchema.default;
+      }
+    }
+
+    return filtered;
+  }
+
+  private static getDefaultValue(schema: any): any {
+    if ('default' in schema) {
+      return schema.default;
+    }
+
+    const type = schema.type;
+    if (Array.isArray(type)) {
+      if (type.includes('null')) {
+        return null;
+      }
+      return this.getDefaultForType(type[0]);
+    }
+
+    return this.getDefaultForType(type);
+  }
+
+  private static getDefaultForType(type: string): any {
+    switch (type) {
+      case 'string':
+        return '';
+      case 'number':
+      case 'integer':
+        return 0;
+      case 'boolean':
+        return false;
+      case 'array':
+        return [];
+      case 'object':
+        return {};
+      default:
+        return null;
+    }
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { validateGtsID, parseGtsID, matchIDPattern, idToUUID, extractID, GTS, createJsonEntity } from '../index';
+
+const program = new Command();
+
+program
+  .name('gts')
+  .description('GTS CLI - Global Type System command-line interface')
+  .version('0.1.0')
+  .option('--path <path>', 'Path to JSON and schema files', process.env.GTS_PATH)
+  .option('--config <config>', 'Path to GTS config JSON file', process.env.GTS_CONFIG)
+  .option('-v, --verbose', 'Verbose output', false);
+
+// OP#1 - Validate ID
+program
+  .command('validate-id')
+  .description('Validate a GTS ID')
+  .requiredOption('-i, --id <id>', 'GTS ID to validate')
+  .action((options) => {
+    const result = validateGtsID(options.id);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 1);
+  });
+
+// OP#2 - Extract ID
+program
+  .command('extract-id')
+  .description('Extract GTS ID from JSON content')
+  .requiredOption('-f, --file <file>', 'JSON file to extract ID from')
+  .action((options) => {
+    try {
+      const content = JSON.parse(fs.readFileSync(options.file, 'utf-8'));
+      const result = extractID(content);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+// OP#3 - Parse ID
+program
+  .command('parse-id')
+  .description('Parse a GTS ID into components')
+  .requiredOption('-i, --id <id>', 'GTS ID to parse')
+  .action((options) => {
+    const result = parseGtsID(options.id);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 1);
+  });
+
+// OP#4 - Match ID
+program
+  .command('match-id')
+  .description('Match GTS ID against pattern')
+  .requiredOption('-p, --pattern <pattern>', 'Pattern to match against')
+  .requiredOption('-c, --candidate <candidate>', 'Candidate ID to match')
+  .action((options) => {
+    const result = matchIDPattern(options.candidate, options.pattern);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.match ? 0 : 1);
+  });
+
+// OP#5 - UUID
+program
+  .command('uuid')
+  .description('Generate UUID from GTS ID')
+  .requiredOption('-i, --id <id>', 'GTS ID to convert')
+  .action((options) => {
+    const result = idToUUID(options.id);
+    if (result.error) {
+      console.error(`Error: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(result.uuid);
+  });
+
+// OP#6 - Validate Instance
+program
+  .command('validate')
+  .description('Validate instance against schema')
+  .requiredOption('-i, --id <id>', 'Instance ID to validate')
+  .action((options, command) => {
+    const gts = loadStore(command.parent);
+    const result = gts.validateInstance(options.id);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 1);
+  });
+
+// OP#7 - Relationships
+program
+  .command('relationships')
+  .description('Resolve relationships for an entity')
+  .requiredOption('-i, --id <id>', 'Entity ID')
+  .action((options, command) => {
+    const gts = loadStore(command.parent);
+    const result = gts.resolveRelationships(options.id);
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+// OP#8 - Compatibility
+program
+  .command('compatibility')
+  .description('Check schema compatibility')
+  .requiredOption('-o, --old <old>', 'Old schema ID')
+  .requiredOption('-n, --new <new>', 'New schema ID')
+  .option('-m, --mode <mode>', 'Compatibility mode (backward|forward|full)', 'full')
+  .action((options, command) => {
+    const gts = loadStore(command.parent);
+    const result = gts.checkCompatibility(options.old, options.new, options.mode);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.compatible ? 0 : 1);
+  });
+
+// OP#9 - Cast
+program
+  .command('cast')
+  .description('Cast instance to different schema version')
+  .requiredOption('-f, --from <from>', 'Source instance ID')
+  .requiredOption('-t, --to <to>', 'Target schema ID')
+  .action((options, command) => {
+    const gts = loadStore(command.parent);
+    const result = gts.castInstance(options.from, options.to);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 1);
+  });
+
+// OP#10 - Query
+program
+  .command('query')
+  .description('Query entities')
+  .requiredOption('-e, --expr <expr>', 'Query expression')
+  .option('-l, --limit <limit>', 'Maximum results', '100')
+  .action((options, command) => {
+    const gts = loadStore(command.parent);
+    const result = gts.query(options.expr, parseInt(options.limit, 10));
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+// OP#11 - Attribute
+program
+  .command('attr')
+  .description('Get attribute value')
+  .requiredOption('-p, --path <path>', 'Attribute path (e.g., gts.vendor.pkg.ns.type.v1.0@name)')
+  .action((options, command) => {
+    const gts = loadStore(command.parent);
+    const result = gts.getAttribute(options.path);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.resolved ? 0 : 1);
+  });
+
+// List entities
+program
+  .command('list')
+  .description('List all entities')
+  .option('-l, --limit <limit>', 'Maximum results', '100')
+  .action((options, command) => {
+    const gts = loadStore(command.parent);
+    const entities = gts['store'].getAll().slice(0, parseInt(options.limit, 10));
+    const result = {
+      count: entities.length,
+      items: entities.map((e) => e.id),
+    };
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+// Server command
+program
+  .command('server')
+  .description('Start HTTP server')
+  .option('--host <host>', 'Host to bind to', '127.0.0.1')
+  .option('--port <port>', 'Port to listen on', '8000')
+  .action(async (options, command) => {
+    const parentOpts = command.parent.opts();
+
+    // Import server dynamically
+    const { GtsServer } = await import('../server/server');
+
+    const config = {
+      host: options.host,
+      port: parseInt(options.port, 10),
+      verbose: parentOpts.verbose ? 2 : 1,
+      path: parentOpts.path,
+    };
+
+    const server = new GtsServer(config);
+
+    // Load entities if path provided
+    if (config.path) {
+      const gts = loadStore(command.parent);
+      // Transfer loaded entities to server
+      const entities = gts['store'].getAll();
+      for (const entity of entities) {
+        server['store'].register(entity.content);
+      }
+      console.log(`Loaded ${entities.length} entities from ${config.path}`);
+    }
+
+    await server.start();
+  });
+
+// OpenAPI command
+program
+  .command('openapi')
+  .description('Generate OpenAPI specification')
+  .option('-o, --out <file>', 'Output file')
+  .action((options) => {
+    const spec = {
+      openapi: '3.0.0',
+      info: {
+        title: 'GTS API',
+        version: '0.1.0',
+        description: 'Global Type System API',
+      },
+      servers: [
+        {
+          url: 'http://127.0.0.1:8000',
+          description: 'Default GTS Server',
+        },
+      ],
+      paths: {},
+      components: {},
+    };
+
+    const output = JSON.stringify(spec, null, 2);
+
+    if (options.out) {
+      fs.writeFileSync(options.out, output);
+      console.log(`OpenAPI spec written to ${options.out}`);
+    } else {
+      console.log(output);
+    }
+  });
+
+// Helper function to load entities from path
+function loadStore(command: any): GTS {
+  const options = command.opts();
+  const gts = new GTS({ validateRefs: false });
+
+  if (!options.path) {
+    return gts;
+  }
+
+  const paths = options.path.split(',');
+
+  for (const dirPath of paths) {
+    if (!fs.existsSync(dirPath)) {
+      if (options.verbose) {
+        console.warn(`Path does not exist: ${dirPath}`);
+      }
+      continue;
+    }
+
+    const stats = fs.statSync(dirPath);
+    if (!stats.isDirectory()) {
+      if (options.verbose) {
+        console.warn(`Path is not a directory: ${dirPath}`);
+      }
+      continue;
+    }
+
+    loadEntitiesFromDir(gts, dirPath, options.verbose);
+  }
+
+  return gts;
+}
+
+function loadEntitiesFromDir(gts: GTS, dirPath: string, verbose: boolean): void {
+  const files = fs.readdirSync(dirPath);
+
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+
+    const filePath = path.join(dirPath, file);
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const data = JSON.parse(content);
+
+      // Handle arrays of entities
+      const entities = Array.isArray(data) ? data : [data];
+
+      for (const entity of entities) {
+        try {
+          const gtsEntity = createJsonEntity(entity);
+          if (gtsEntity.id) {
+            gts.register(entity);
+            if (verbose) {
+              console.log(`Loaded: ${gtsEntity.id}`);
+            }
+          }
+        } catch (err) {
+          if (verbose) {
+            console.warn(`Failed to load entity from ${file}: ${err}`);
+          }
+        }
+      }
+    } catch (err) {
+      if (verbose) {
+        console.warn(`Failed to read ${file}: ${err}`);
+      }
+    }
+  }
+}
+
+// Parse arguments
+program.parse(process.argv);
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/src/compatibility.ts

@@ -0,0 +1,201 @@
+import { CompatibilityResult } from './types';
+import { GtsStore } from './store';
+import { Gts } from './gts';
+
+export class GtsCompatibility {
+  static checkCompatibility(
+    store: GtsStore,
+    oldId: string,
+    newId: string,
+    mode: 'backward' | 'forward' | 'full' = 'full'
+  ): CompatibilityResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    try {
+      const oldGtsId = Gts.parseGtsID(oldId);
+      const newGtsId = Gts.parseGtsID(newId);
+
+      const oldEntity = store.get(oldGtsId.id);
+      const newEntity = store.get(newGtsId.id);
+
+      if (!oldEntity) {
+        errors.push(`Old schema not found: ${oldId}`);
+        return { compatible: false, oldId, newId, mode, errors, warnings };
+      }
+
+      if (!newEntity) {
+        errors.push(`New schema not found: ${newId}`);
+        return { compatible: false, oldId, newId, mode, errors, warnings };
+      }
+
+      if (!oldEntity.isSchema) {
+        errors.push(`Old entity is not a schema: ${oldId}`);
+        return { compatible: false, oldId, newId, mode, errors, warnings };
+      }
+
+      if (!newEntity.isSchema) {
+        errors.push(`New entity is not a schema: ${newId}`);
+        return { compatible: false, oldId, newId, mode, errors, warnings };
+      }
+
+      const oldSchema = oldEntity.content;
+      const newSchema = newEntity.content;
+
+      if (mode === 'backward' || mode === 'full') {
+        this.checkBackwardCompatibility(oldSchema, newSchema, errors, warnings);
+      }
+
+      if (mode === 'forward' || mode === 'full') {
+        this.checkForwardCompatibility(oldSchema, newSchema, errors, warnings);
+      }
+
+      return {
+        compatible: errors.length === 0,
+        oldId,
+        newId,
+        mode,
+        errors,
+        warnings,
+      };
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+      return {
+        compatible: false,
+        oldId,
+        newId,
+        mode,
+        errors,
+        warnings,
+      };
+    }
+  }
+
+  private static checkBackwardCompatibility(
+    oldSchema: any,
+    newSchema: any,
+    errors: string[],
+    warnings: string[]
+  ): void {
+    const oldProps = oldSchema.properties || {};
+    const newProps = newSchema.properties || {};
+    const oldRequired = new Set(oldSchema.required || []);
+    const newRequired = new Set(newSchema.required || []);
+
+    for (const prop of oldRequired) {
+      if (!newRequired.has(prop)) {
+        warnings.push(`Property '${prop}' is no longer required in new schema`);
+      }
+    }
+
+    for (const [propName, propSchema] of Object.entries(oldProps)) {
+      if (!(propName in newProps)) {
+        if (oldRequired.has(propName)) {
+          errors.push(`Required property '${propName}' removed in new schema`);
+        } else {
+          warnings.push(`Optional property '${propName}' removed in new schema`);
+        }
+      } else {
+        this.checkPropertyCompatibility(propName, propSchema, newProps[propName], errors, warnings, 'backward');
+      }
+    }
+  }
+
+  private static checkForwardCompatibility(oldSchema: any, newSchema: any, errors: string[], warnings: string[]): void {
+    const oldProps = oldSchema.properties || {};
+    const newProps = newSchema.properties || {};
+    const oldRequired = new Set(oldSchema.required || []);
+    const newRequired = new Set(newSchema.required || []);
+
+    for (const prop of newRequired) {
+      if (!oldRequired.has(prop)) {
+        errors.push(`New required property '${prop}' added in new schema`);
+      }
+    }
+
+    for (const [propName, propSchema] of Object.entries(newProps)) {
+      if (!(propName in oldProps)) {
+        if (newRequired.has(propName)) {
+          errors.push(`New required property '${propName}' added`);
+        } else {
+          warnings.push(`New optional property '${propName}' added`);
+        }
+      } else {
+        this.checkPropertyCompatibility(propName, oldProps[propName], propSchema, errors, warnings, 'forward');
+      }
+    }
+  }
+
+  private static checkPropertyCompatibility(
+    propName: string,
+    oldProp: any,
+    newProp: any,
+    errors: string[],
+    warnings: string[],
+    direction: 'backward' | 'forward'
+  ): void {
+    const oldType = this.normalizeType(oldProp.type);
+    const newType = this.normalizeType(newProp.type);
+
+    if (oldType !== newType) {
+      if (this.areTypesCompatible(oldType, newType, direction)) {
+        warnings.push(`Property '${propName}' type changed from ${oldType} to ${newType}`);
+      } else {
+        errors.push(`Property '${propName}' type incompatibly changed from ${oldType} to ${newType}`);
+      }
+    }
+
+    if (oldProp.enum && newProp.enum) {
+      const oldEnum = new Set(oldProp.enum);
+      const newEnum = new Set(newProp.enum);
+
+      if (direction === 'backward') {
+        for (const value of oldEnum) {
+          if (!newEnum.has(value)) {
+            errors.push(`Enum value '${value}' removed from property '${propName}'`);
+          }
+        }
+      } else {
+        for (const value of newEnum) {
+          if (!oldEnum.has(value)) {
+            warnings.push(`Enum value '${value}' added to property '${propName}'`);
+          }
+        }
+      }
+    }
+  }
+
+  private static normalizeType(type: any): string {
+    if (Array.isArray(type)) {
+      return type.join('|');
+    }
+    return type || 'any';
+  }
+
+  private static areTypesCompatible(oldType: string, newType: string, direction: 'backward' | 'forward'): boolean {
+    if (oldType === newType) return true;
+
+    if (direction === 'backward') {
+      if (newType === 'any') return true;
+      if (oldType === 'integer' && newType === 'number') return true;
+    } else {
+      if (oldType === 'any') return true;
+      if (newType === 'integer' && oldType === 'number') return true;
+    }
+
+    const oldTypes = new Set(oldType.split('|'));
+    const newTypes = new Set(newType.split('|'));
+
+    if (direction === 'backward') {
+      for (const t of oldTypes) {
+        if (!newTypes.has(t)) return false;
+      }
+    } else {
+      for (const t of newTypes) {
+        if (!oldTypes.has(t)) return false;
+      }
+    }
+
+    return true;
+  }
+}