@vibe-lang/runtime 0.2.5

package/src/runtime/tools/test/ts-schema.test.ts

@@ -0,0 +1,357 @@
+import { describe, expect, test, beforeAll } from 'bun:test';
+import { vibeTypeToJsonSchema, extractTypeSchema, createTypeExtractor, clearSchemaCache } from '../ts-schema';
+import type { TypeExtractor } from '../ts-schema';
+import { join } from 'path';
+
+describe('vibeTypeToJsonSchema', () => {
+  // ============================================================================
+  // Primitive types
+  // ============================================================================
+
+  test('converts text type to string schema', () => {
+    const schema = vibeTypeToJsonSchema('text');
+    expect(schema).toEqual({ type: 'string' });
+  });
+
+  test('converts prompt type to string schema', () => {
+    const schema = vibeTypeToJsonSchema('prompt');
+    expect(schema).toEqual({ type: 'string' });
+  });
+
+  test('converts number type to number schema', () => {
+    const schema = vibeTypeToJsonSchema('number');
+    expect(schema).toEqual({ type: 'number' });
+  });
+
+  test('converts boolean type to boolean schema', () => {
+    const schema = vibeTypeToJsonSchema('boolean');
+    expect(schema).toEqual({ type: 'boolean' });
+  });
+
+  test('converts json type to object schema', () => {
+    const schema = vibeTypeToJsonSchema('json');
+    expect(schema).toEqual({ type: 'object', additionalProperties: true });
+  });
+
+  // ============================================================================
+  // Array types
+  // ============================================================================
+
+  test('converts text[] to array of strings', () => {
+    const schema = vibeTypeToJsonSchema('text[]');
+    expect(schema).toEqual({
+      type: 'array',
+      items: { type: 'string' },
+    });
+  });
+
+  test('converts number[] to array of numbers', () => {
+    const schema = vibeTypeToJsonSchema('number[]');
+    expect(schema).toEqual({
+      type: 'array',
+      items: { type: 'number' },
+    });
+  });
+
+  test('converts boolean[] to array of booleans', () => {
+    const schema = vibeTypeToJsonSchema('boolean[]');
+    expect(schema).toEqual({
+      type: 'array',
+      items: { type: 'boolean' },
+    });
+  });
+
+  test('converts json[] to array of objects', () => {
+    const schema = vibeTypeToJsonSchema('json[]');
+    expect(schema).toEqual({
+      type: 'array',
+      items: { type: 'object', additionalProperties: true },
+    });
+  });
+
+  // ============================================================================
+  // Unknown types
+  // ============================================================================
+
+  test('returns generic object for unknown type', () => {
+    const schema = vibeTypeToJsonSchema('UnknownType');
+    expect(schema).toEqual({ type: 'object', additionalProperties: true });
+  });
+
+  test('falls back to generic object for unmapped type', () => {
+    const importedTypes = new Map<string, string>();
+    const schema = vibeTypeToJsonSchema('UnknownType', importedTypes);
+    expect(schema).toEqual({ type: 'object', additionalProperties: true });
+  });
+});
+
+// ============================================================================
+// TypeScript type extraction tests using fixtures
+// Compiles once in beforeAll for efficiency (~1s instead of ~10s)
+// ============================================================================
+
+describe('extractTypeSchema with fixtures', () => {
+  const fixturesDir = join(__dirname, 'fixtures');
+  const testTypesFile = join(fixturesDir, 'test-types.ts');
+  const baseTypesFile = join(fixturesDir, 'base-types.ts');
+
+  let extractor: TypeExtractor;
+
+  beforeAll(() => {
+    clearSchemaCache();
+    // Compile both files once - this is where the time is spent
+    extractor = createTypeExtractor([testTypesFile, baseTypesFile]);
+  });
+
+  // ============================================================================
+  // Simple primitives from test-types.ts
+  // ============================================================================
+
+  test('extracts Person interface with primitives', () => {
+    const schema = extractor.extract('Person');
+    expect(schema).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+        active: { type: 'boolean' },
+      },
+      required: ['name', 'age', 'active'],
+    });
+  });
+
+  test('extracts Config interface with optional properties', () => {
+    const schema = extractor.extract('Config');
+    expect(schema.properties).toHaveProperty('required');
+    expect(schema.properties).toHaveProperty('optional');
+    expect(schema.required).toContain('required');
+    expect(schema.required).not.toContain('optional');
+  });
+
+  test('extracts Container interface with array property', () => {
+    const schema = extractor.extract('Container');
+    expect(schema.properties?.items).toEqual({
+      type: 'array',
+      items: { type: 'string' },
+    });
+  });
+
+  test('extracts Status type alias', () => {
+    const schema = extractor.extract('Status');
+    expect(schema).toEqual({ type: 'string' });
+  });
+
+  // ============================================================================
+  // JSDoc extraction
+  // ============================================================================
+
+  test('extracts JSDoc descriptions from Documented interface', () => {
+    const schema = extractor.extract('Documented');
+    expect(schema.properties?.id.description).toBe("The user's unique identifier");
+    expect(schema.properties?.name.description).toBe("The user's display name");
+  });
+
+  // ============================================================================
+  // Types from base-types.ts (imported by test-types.ts)
+  // ============================================================================
+
+  test('extracts Address interface from base-types', () => {
+    const schema = extractor.extract('Address');
+    expect(schema).toMatchObject({
+      type: 'object',
+      properties: {
+        street: { type: 'string' },
+        city: { type: 'string' },
+        zipCode: { type: 'string' },
+        country: { type: 'string' },
+      },
+    });
+    expect(schema.required).toContain('street');
+    expect(schema.required).toContain('city');
+    expect(schema.required).not.toContain('country'); // optional
+  });
+
+  test('extracts ContactInfo with nested Address', () => {
+    const schema = extractor.extract('ContactInfo');
+    expect(schema.properties?.email).toEqual({ type: 'string' });
+    expect(schema.properties?.address).toMatchObject({
+      type: 'object',
+      properties: {
+        street: { type: 'string' },
+        city: { type: 'string' },
+      },
+    });
+  });
+
+  test('extracts Metadata interface with JSDoc and optional array', () => {
+    const schema = extractor.extract('Metadata');
+    expect(schema.properties?.createdAt.description).toBe('When the entity was created');
+    expect(schema.properties?.updatedAt.description).toBe('When the entity was last updated');
+    expect(schema.properties?.tags).toMatchObject({
+      type: 'array',
+      items: { type: 'string' },
+    });
+    expect(schema.required).not.toContain('tags'); // optional
+  });
+
+  test('extracts OrderItem interface', () => {
+    const schema = extractor.extract('OrderItem');
+    expect(schema).toMatchObject({
+      type: 'object',
+      properties: {
+        productId: { type: 'string' },
+        productName: { type: 'string' },
+        quantity: { type: 'number' },
+        unitPrice: { type: 'number' },
+      },
+    });
+  });
+
+  // ============================================================================
+  // Complex types using imports (test-types.ts using base-types.ts)
+  // ============================================================================
+
+  test('extracts User with imported ContactInfo and Metadata', () => {
+    const schema = extractor.extract('User');
+    expect(schema.properties?.id).toEqual({ type: 'string' });
+    expect(schema.properties?.username).toEqual({ type: 'string' });
+    expect(schema.properties?.contact).toMatchObject({
+      type: 'object',
+      properties: {
+        email: { type: 'string' },
+      },
+    });
+    expect(schema.properties?.metadata).toMatchObject({
+      type: 'object',
+      properties: {
+        createdAt: { type: 'string' },
+      },
+    });
+  });
+
+  test('extracts Customer with optional shippingAddress', () => {
+    const schema = extractor.extract('Customer');
+    expect(schema.required).toContain('billingAddress');
+    expect(schema.required).not.toContain('shippingAddress'); // optional
+  });
+
+  test('extracts Order with array of OrderItems', () => {
+    const schema = extractor.extract('Order');
+    expect(schema.properties?.items).toMatchObject({
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          productId: { type: 'string' },
+          quantity: { type: 'number' },
+        },
+      },
+    });
+  });
+
+  // ============================================================================
+  // Array types interface
+  // ============================================================================
+
+  test('extracts ArrayTypes with various array properties', () => {
+    const schema = extractor.extract('ArrayTypes');
+    expect(schema.properties?.strings).toEqual({ type: 'array', items: { type: 'string' } });
+    expect(schema.properties?.numbers).toEqual({ type: 'array', items: { type: 'number' } });
+    expect(schema.properties?.booleans).toEqual({ type: 'array', items: { type: 'boolean' } });
+    expect(schema.properties?.nested).toMatchObject({
+      type: 'array',
+      items: { type: 'object' },
+    });
+  });
+
+  // ============================================================================
+  // Optional-only types
+  // ============================================================================
+
+  test('extracts AllOptional with no required fields', () => {
+    const schema = extractor.extract('AllOptional');
+    expect(schema.required).toBeUndefined();
+  });
+
+  // ============================================================================
+  // Error handling
+  // ============================================================================
+
+  test('throws error for non-existent type', () => {
+    expect(() => extractor.extract('NonExistentType')).toThrow(
+      "Type 'NonExistentType' not found"
+    );
+  });
+});
+
+// ============================================================================
+// Tests for extractTypeSchema (the single-file API with caching)
+// ============================================================================
+
+describe('extractTypeSchema caching', () => {
+  const fixturesDir = join(__dirname, 'fixtures');
+  const testTypesFile = join(fixturesDir, 'test-types.ts');
+
+  test('caches schema for same file and type', () => {
+    clearSchemaCache();
+
+    // First call - compiles the file
+    const schema1 = extractTypeSchema(testTypesFile, 'Person');
+
+    // Second call - should use cache
+    const schema2 = extractTypeSchema(testTypesFile, 'Person');
+
+    expect(schema1).toEqual(schema2);
+  });
+
+  test('throws error for non-existent file', () => {
+    expect(() => extractTypeSchema('/nonexistent/path/file.ts', 'SomeType')).toThrow();
+  });
+
+  test('throws error for non-existent type in file', () => {
+    expect(() => extractTypeSchema(testTypesFile, 'NonExistentType')).toThrow(
+      "Type 'NonExistentType' not found"
+    );
+  });
+});
+
+// ============================================================================
+// vibeTypeToJsonSchema with imported types (uses fixture file)
+// ============================================================================
+
+describe('vibeTypeToJsonSchema with imported types', () => {
+  const fixturesDir = join(__dirname, 'fixtures');
+  const testTypesFile = join(fixturesDir, 'test-types.ts');
+
+  test('resolves imported type from map', () => {
+    clearSchemaCache();
+    const importedTypes = new Map<string, string>();
+    importedTypes.set('Person', testTypesFile);
+
+    const schema = vibeTypeToJsonSchema('Person', importedTypes);
+    expect(schema).toMatchObject({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+        active: { type: 'boolean' },
+      },
+    });
+  });
+
+  test('handles array of imported type', () => {
+    const importedTypes = new Map<string, string>();
+    importedTypes.set('Person', testTypesFile);
+
+    const schema = vibeTypeToJsonSchema('Person[]', importedTypes);
+    expect(schema).toMatchObject({
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+        },
+      },
+    });
+  });
+});

package/src/runtime/tools/ts-schema.ts

@@ -0,0 +1,341 @@
+import ts from 'typescript';
+import type { JsonSchema } from './types';
+
+// Cache for extracted schemas to avoid re-parsing the same file
+const schemaCache = new Map<string, Map<string, JsonSchema>>();
+
+/**
+ * Extract JSON Schema from a TypeScript type definition.
+ *
+ * @param sourceFile - Path to the TypeScript source file
+ * @param typeName - Name of the type/interface to extract
+ * @returns JSON Schema representation of the type
+ */
+export function extractTypeSchema(sourceFile: string, typeName: string): JsonSchema {
+  // Check cache first
+  const fileCache = schemaCache.get(sourceFile);
+  if (fileCache?.has(typeName)) {
+    return fileCache.get(typeName)!;
+  }
+
+  // Create TypeScript program to analyze the file
+  const program = ts.createProgram([sourceFile], {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    strict: true,
+  });
+
+  const checker = program.getTypeChecker();
+  const source = program.getSourceFile(sourceFile);
+
+  if (!source) {
+    throw new Error(`Could not load source file: ${sourceFile}`);
+  }
+
+  // Find the type declaration
+  const typeSymbol = findTypeSymbol(source, typeName, checker);
+  if (!typeSymbol) {
+    throw new Error(`Type '${typeName}' not found in ${sourceFile}`);
+  }
+
+  const type = checker.getDeclaredTypeOfSymbol(typeSymbol);
+  const schema = typeToJsonSchema(type, checker, new Set());
+
+  // Cache the result
+  if (!schemaCache.has(sourceFile)) {
+    schemaCache.set(sourceFile, new Map());
+  }
+  schemaCache.get(sourceFile)!.set(typeName, schema);
+
+  return schema;
+}
+
+/**
+ * Find a type symbol by name in a source file.
+ */
+function findTypeSymbol(
+  source: ts.SourceFile,
+  typeName: string,
+  checker: ts.TypeChecker
+): ts.Symbol | undefined {
+  let result: ts.Symbol | undefined;
+
+  function visit(node: ts.Node) {
+    if (result) return;
+
+    if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) {
+      if (node.name.text === typeName) {
+        result = checker.getSymbolAtLocation(node.name);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(source);
+  return result;
+}
+
+/**
+ * Convert a TypeScript type to JSON Schema.
+ *
+ * @param type - The TypeScript type to convert
+ * @param checker - TypeScript type checker
+ * @param visited - Set of visited type IDs to prevent infinite recursion
+ */
+function typeToJsonSchema(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  visited: Set<number>
+): JsonSchema {
+  // Prevent infinite recursion for recursive types
+  const typeId = (type as { id?: number }).id;
+  if (typeId !== undefined && visited.has(typeId)) {
+    return { type: 'object', additionalProperties: true };
+  }
+  if (typeId !== undefined) {
+    visited.add(typeId);
+  }
+
+  // Handle primitive types
+  if (type.flags & ts.TypeFlags.String) {
+    return { type: 'string' };
+  }
+  if (type.flags & ts.TypeFlags.Number) {
+    return { type: 'number' };
+  }
+  if (type.flags & ts.TypeFlags.Boolean) {
+    return { type: 'boolean' };
+  }
+  if (type.flags & ts.TypeFlags.Null || type.flags & ts.TypeFlags.Undefined) {
+    return { type: 'object' }; // JSON doesn't have null type, use object
+  }
+
+  // Handle string literal types
+  if (type.flags & ts.TypeFlags.StringLiteral) {
+    return { type: 'string' };
+  }
+
+  // Handle number literal types
+  if (type.flags & ts.TypeFlags.NumberLiteral) {
+    return { type: 'number' };
+  }
+
+  // Handle boolean literal types
+  if (type.flags & ts.TypeFlags.BooleanLiteral) {
+    return { type: 'boolean' };
+  }
+
+  // Handle union types (e.g., string | number, or T | undefined for optional)
+  if (type.flags & ts.TypeFlags.Union) {
+    const unionType = type as ts.UnionType;
+
+    // Filter out undefined and null from the union (common for optional types)
+    const nonNullTypes = unionType.types.filter(
+      (t) => !(t.flags & ts.TypeFlags.Undefined) && !(t.flags & ts.TypeFlags.Null)
+    );
+
+    // If only one type remains after filtering, use that
+    if (nonNullTypes.length === 1) {
+      return typeToJsonSchema(nonNullTypes[0], checker, new Set(visited));
+    }
+
+    // For remaining types, try to find a common type
+    const types = nonNullTypes.map((t) => typeToJsonSchema(t, checker, new Set(visited)));
+
+    // If all types are the same, return that type
+    const typeSet = new Set(types.map((t) => t.type));
+    if (typeSet.size === 1) {
+      return types[0];
+    }
+
+    // Otherwise, return a generic object
+    return { type: 'object', additionalProperties: true };
+  }
+
+  // Handle arrays
+  if (checker.isArrayType(type)) {
+    const typeRef = type as ts.TypeReference;
+    const elementType = typeRef.typeArguments?.[0];
+    if (elementType) {
+      return {
+        type: 'array',
+        items: typeToJsonSchema(elementType, checker, new Set(visited)),
+      };
+    }
+    return { type: 'array' };
+  }
+
+  // Handle tuples as arrays
+  if (checker.isTupleType(type)) {
+    const tupleType = type as ts.TupleType;
+    // Use the first element type or object for mixed tuples
+    if (tupleType.typeArguments && tupleType.typeArguments.length > 0) {
+      return {
+        type: 'array',
+        items: typeToJsonSchema(tupleType.typeArguments[0], checker, new Set(visited)),
+      };
+    }
+    return { type: 'array' };
+  }
+
+  // Handle objects/interfaces
+  if (type.flags & ts.TypeFlags.Object) {
+    const objectType = type as ts.ObjectType;
+
+    // Check if it's a function type
+    const callSignatures = type.getCallSignatures();
+    if (callSignatures.length > 0) {
+      return { type: 'object', additionalProperties: true };
+    }
+
+    const properties: Record<string, JsonSchema> = {};
+    const required: string[] = [];
+
+    const typeProperties = objectType.getProperties();
+    for (const prop of typeProperties) {
+      const propType = checker.getTypeOfSymbol(prop);
+      const propSchema = typeToJsonSchema(propType, checker, new Set(visited));
+
+      // Get JSDoc comment if available
+      const jsDocComment = prop.getDocumentationComment(checker);
+      if (jsDocComment.length > 0) {
+        propSchema.description = jsDocComment.map((c) => c.text).join('\n');
+      }
+
+      properties[prop.name] = propSchema;
+
+      // Check if property is required (not optional)
+      if (!(prop.flags & ts.SymbolFlags.Optional)) {
+        required.push(prop.name);
+      }
+    }
+
+    return {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined,
+    };
+  }
+
+  // Default fallback
+  return { type: 'object', additionalProperties: true };
+}
+
+/**
+ * Convert a Vibe type annotation to JSON Schema.
+ * Handles both built-in types and imported TS type names.
+ *
+ * @param vibeType - The Vibe type annotation (e.g., "text", "CustomerInfo", "Order[]")
+ * @param importedTypes - Map of type name to source file for resolving imported types
+ */
+export function vibeTypeToJsonSchema(
+  vibeType: string,
+  importedTypes?: Map<string, string>
+): JsonSchema {
+  // Handle array types
+  if (vibeType.endsWith('[]')) {
+    const elementType = vibeType.slice(0, -2);
+    return {
+      type: 'array',
+      items: vibeTypeToJsonSchema(elementType, importedTypes),
+    };
+  }
+
+  // Handle built-in Vibe types
+  switch (vibeType) {
+    case 'text':
+    case 'prompt':
+      return { type: 'string' };
+    case 'number':
+      return { type: 'number' };
+    case 'boolean':
+      return { type: 'boolean' };
+    case 'json':
+      return { type: 'object', additionalProperties: true };
+  }
+
+  // Handle imported TS type
+  if (importedTypes?.has(vibeType)) {
+    const sourceFile = importedTypes.get(vibeType)!;
+    return extractTypeSchema(sourceFile, vibeType);
+  }
+
+  // Unknown type - return generic object
+  return { type: 'object', additionalProperties: true };
+}
+
+/**
+ * Clear the schema cache (useful for testing or when files change).
+ */
+export function clearSchemaCache(): void {
+  schemaCache.clear();
+}
+
+/**
+ * A type extractor that has already compiled a TypeScript program.
+ * Use this when you need to extract multiple types from the same file(s)
+ * to avoid recompiling for each extraction.
+ */
+export interface TypeExtractor {
+  /**
+   * Extract a type by name from any of the compiled source files.
+   */
+  extract(typeName: string): JsonSchema;
+
+  /**
+   * Get the type checker for advanced use cases.
+   */
+  getChecker(): ts.TypeChecker;
+}
+
+/**
+ * Create a type extractor by compiling TypeScript files once.
+ * Much more efficient than calling extractTypeSchema multiple times.
+ *
+ * @param sourceFiles - Array of TypeScript file paths to compile
+ * @returns A TypeExtractor that can extract types without recompiling
+ */
+export function createTypeExtractor(sourceFiles: string[]): TypeExtractor {
+  const program = ts.createProgram(sourceFiles, {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.NodeJs,
+    strict: true,
+  });
+
+  const checker = program.getTypeChecker();
+  const sources = sourceFiles.map((f) => program.getSourceFile(f)).filter(Boolean) as ts.SourceFile[];
+
+  // Build a map of all exported types across all source files
+  const typeSymbols = new Map<string, ts.Symbol>();
+
+  for (const source of sources) {
+    function visit(node: ts.Node) {
+      if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) {
+        const symbol = checker.getSymbolAtLocation(node.name);
+        if (symbol) {
+          typeSymbols.set(node.name.text, symbol);
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  }
+
+  return {
+    extract(typeName: string): JsonSchema {
+      const symbol = typeSymbols.get(typeName);
+      if (!symbol) {
+        throw new Error(`Type '${typeName}' not found in compiled sources`);
+      }
+
+      const type = checker.getDeclaredTypeOfSymbol(symbol);
+      return typeToJsonSchema(type, checker, new Set());
+    },
+
+    getChecker(): ts.TypeChecker {
+      return checker;
+    },
+  };
+}