dotdo 0.0.1 → 0.1.0

package/cli/commands/introspect/emitter.ts

@@ -0,0 +1,315 @@
+/**
+ * Type Emitter - Generate .do/types.d.ts from schemas
+ *
+ * Converts MdxSchema and DOSchema into TypeScript declaration files.
+ */
+
+import type { MdxSchema, MdxEntity } from '../../../db/schema/mdx'
+import type { DOSchema, DOClassSchema } from '../../../types/introspect'
+
+export interface TypeEmitterOptions {
+  /** Include JSDoc comments */
+  includeComments?: boolean
+  /** Module name for declare module */
+  moduleName?: string
+}
+
+export interface EmittedTypes {
+  /** The generated .d.ts content */
+  content: string
+  /** Entity names found */
+  entities: string[]
+  /** Method signatures found */
+  methods: string[]
+  /** Event types found */
+  events: string[]
+}
+
+/**
+ * Convert MDX field type to TypeScript type
+ */
+function mdxTypeToTs(type: string): string {
+  // Handle array types [->Type]
+  if (type.startsWith('[') && type.endsWith(']')) {
+    const inner = type.slice(1, -1)
+    return `${mdxTypeToTs(inner)}[]`
+  }
+
+  // Handle relationship operators
+  const operators = ['->', '~>', '<-', '<~']
+  for (const op of operators) {
+    if (type.startsWith(op)) {
+      return type.slice(op.length)
+    }
+  }
+
+  // Handle code blocks
+  if (type.startsWith('`') && type.endsWith('`')) {
+    return mdxTypeToTs(type.slice(1, -1))
+  }
+
+  // Primitive mappings
+  const primitives: Record<string, string> = {
+    string: 'string',
+    number: 'number',
+    boolean: 'boolean',
+    Date: 'Date',
+    date: 'Date',
+    any: 'unknown',
+    object: 'Record<string, unknown>',
+  }
+
+  return primitives[type] || type
+}
+
+/**
+ * Generate entity interface from MdxEntity
+ */
+function emitEntityInterface(name: string, entity: MdxEntity, includeComments: boolean): string {
+  const lines: string[] = []
+
+  if (includeComments && entity.description) {
+    lines.push(`  /** ${entity.description} */`)
+  }
+
+  lines.push(`  export interface ${name} {`)
+  lines.push(`    id: string`)
+
+  for (const [fieldName, field] of Object.entries(entity.fields)) {
+    const tsType = mdxTypeToTs(field.type)
+    if (includeComments && field.description) {
+      lines.push(`    /** ${field.description} */`)
+    }
+    lines.push(`    ${fieldName}: ${tsType}`)
+  }
+
+  lines.push(`  }`)
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate state union type
+ */
+function emitStateType(name: string, states: string[]): string {
+  const stateUnion = states.map((s) => `'${s}'`).join(' | ')
+  return `  export type ${name}State = ${stateUnion}`
+}
+
+/**
+ * Generate event type
+ */
+function emitEventType(entityName: string, events: string[]): string {
+  const lines: string[] = []
+  for (const event of events) {
+    // Parse event like "Customer.signup" or just "signup"
+    const [noun, verb] = event.includes('.') ? event.split('.') : [entityName, event]
+    lines.push(`    '${noun}.${verb}': { ${noun.toLowerCase()}: ${noun} }`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Emit types from MDX schema
+ */
+export function emitFromMdxSchema(schema: MdxSchema, options: TypeEmitterOptions = {}): EmittedTypes {
+  const { includeComments = true, moduleName = '@dotdo/client' } = options
+
+  const entities: string[] = []
+  const events: string[] = []
+  const entityBlocks: string[] = []
+  const stateBlocks: string[] = []
+  const eventLines: string[] = []
+
+  for (const [name, entity] of Object.entries(schema.entities)) {
+    entities.push(name)
+    entityBlocks.push(emitEntityInterface(name, entity, includeComments))
+
+    if (entity.states && entity.states.length > 0) {
+      stateBlocks.push(emitStateType(name, entity.states))
+    }
+
+    if (entity.events && entity.events.length > 0) {
+      events.push(...entity.events)
+      eventLines.push(emitEventType(name, entity.events))
+    }
+  }
+
+  const content = `// Auto-generated by dotdo introspect
+// Source: ${schema.source}
+// Do not edit manually
+
+declare module '${moduleName}' {
+  // ============================================================================
+  // ENTITIES
+  // ============================================================================
+
+${entityBlocks.join('\n\n')}
+
+  // ============================================================================
+  // STATE TYPES
+  // ============================================================================
+
+${stateBlocks.join('\n\n') || '  // No state types defined'}
+
+  // ============================================================================
+  // ENTITY REGISTRY
+  // ============================================================================
+
+  export interface Entities {
+${entities.map((e) => `    ${e}: ${e}`).join('\n')}
+  }
+
+  // ============================================================================
+  // EVENTS
+  // ============================================================================
+
+  export interface Events {
+${eventLines.join('\n') || '    // No events defined'}
+  }
+}
+`
+
+  return {
+    content,
+    entities,
+    methods: [],
+    events,
+  }
+}
+
+/**
+ * Emit types from DOSchema (runtime introspection)
+ */
+export function emitFromDOSchema(schema: DOSchema, options: TypeEmitterOptions = {}): EmittedTypes {
+  const { includeComments = true, moduleName = '@dotdo/client' } = options
+
+  const entities: string[] = []
+  const methods: string[] = []
+  const classBlocks: string[] = []
+  const methodLines: string[] = []
+
+  for (const cls of schema.classes) {
+    entities.push(cls.name)
+    classBlocks.push(emitDOClassInterface(cls, includeComments))
+
+    // Extract methods from tools
+    for (const tool of cls.tools) {
+      const methodName = `${cls.name}.${tool.name}`
+      methods.push(methodName)
+      methodLines.push(`    '${methodName}': (input: unknown) => Promise<unknown>`)
+    }
+  }
+
+  const content = `// Auto-generated by dotdo introspect
+// Namespace: ${schema.ns}
+// Do not edit manually
+
+declare module '${moduleName}' {
+  // ============================================================================
+  // DO CLASSES
+  // ============================================================================
+
+${classBlocks.join('\n\n')}
+
+  // ============================================================================
+  // METHODS
+  // ============================================================================
+
+  export interface Methods {
+${methodLines.join('\n') || '    // No methods defined'}
+  }
+
+  // ============================================================================
+  // NOUNS
+  // ============================================================================
+
+  export interface Nouns {
+${schema.nouns.map((n) => `    ${n.noun}: { singular: '${n.noun}', plural: '${n.plural}' }`).join('\n')}
+  }
+}
+`
+
+  return {
+    content,
+    entities,
+    methods,
+    events: [],
+  }
+}
+
+/**
+ * Emit DO class interface
+ */
+function emitDOClassInterface(cls: DOClassSchema, includeComments: boolean): string {
+  const lines: string[] = []
+
+  if (includeComments) {
+    lines.push(`  /** DO Class: ${cls.name} (${cls.type}) */`)
+  }
+
+  lines.push(`  export interface ${cls.name} {`)
+  lines.push(`    id: string`)
+
+  for (const prop of cls.properties) {
+    if (includeComments && prop.description) {
+      lines.push(`    /** ${prop.description} */`)
+    }
+    const required = prop.required !== false ? '' : '?'
+    lines.push(`    ${prop.name}${required}: ${prop.type}`)
+  }
+
+  lines.push(`  }`)
+
+  return lines.join('\n')
+}
+
+/**
+ * Merge multiple EmittedTypes into one
+ */
+export function mergeEmittedTypes(types: EmittedTypes[], moduleName = '@dotdo/client'): string {
+  const allEntities = new Set<string>()
+  const allMethods = new Set<string>()
+  const allEvents = new Set<string>()
+  const entityBlocks: string[] = []
+  const methodLines: string[] = []
+  const eventLines: string[] = []
+
+  for (const t of types) {
+    for (const e of t.entities) allEntities.add(e)
+    for (const m of t.methods) allMethods.add(m)
+    for (const ev of t.events) allEvents.add(ev)
+  }
+
+  // Extract entity blocks from content (simplified)
+  for (const t of types) {
+    const match = t.content.match(/\/\/ ENTITIES[\s\S]*?(export interface \w+[\s\S]*?})/g)
+    if (match) {
+      entityBlocks.push(...match)
+    }
+  }
+
+  return `// Auto-generated by dotdo introspect
+// Do not edit manually
+
+declare module '${moduleName}' {
+  export interface Entities {
+${Array.from(allEntities)
+  .map((e) => `    ${e}: ${e}`)
+  .join('\n')}
+  }
+
+  export interface Methods {
+${Array.from(allMethods)
+  .map((m) => `    '${m}': (...args: unknown[]) => Promise<unknown>`)
+  .join('\n')}
+  }
+
+  export interface Events {
+${Array.from(allEvents)
+  .map((e) => `    '${e}': unknown`)
+  .join('\n')}
+  }
+}
+`
+}

package/cli/commands/introspect/index.ts

@@ -0,0 +1,193 @@
+/**
+ * dotdo introspect - Generate .do/types.d.ts from schemas
+ *
+ * Usage:
+ *   dotdo introspect              Generate types
+ *   dotdo introspect --watch      Watch mode
+ *   dotdo introspect --check      Validate only (no write)
+ *   dotdo introspect --out <path> Custom output path
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, watch } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { loadAndMergeSchemas } from '../../../db/schema/mdx'
+import { emitFromMdxSchema, mergeEmittedTypes, type EmittedTypes } from './emitter'
+
+export interface IntrospectOptions {
+  /** Project root directory */
+  root?: string
+  /** Output file path */
+  out?: string
+  /** Watch mode */
+  watch?: boolean
+  /** Check only (no write) */
+  check?: boolean
+  /** Verbose output */
+  verbose?: boolean
+}
+
+const DEFAULT_OUTPUT = '.do/types.d.ts'
+
+/**
+ * Parse CLI arguments into options
+ */
+function parseArgs(args: string[]): IntrospectOptions {
+  const options: IntrospectOptions = {}
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '--watch' || arg === '-w') {
+      options.watch = true
+    } else if (arg === '--check' || arg === '-c') {
+      options.check = true
+    } else if (arg === '--verbose' || arg === '-v') {
+      options.verbose = true
+    } else if (arg === '--out' || arg === '-o') {
+      options.out = args[++i]
+    } else if (arg === '--root' || arg === '-r') {
+      options.root = args[++i]
+    } else if (!arg.startsWith('-')) {
+      // Positional arg = root directory
+      options.root = arg
+    }
+  }
+
+  return options
+}
+
+/**
+ * Generate types from project schemas
+ */
+async function generateTypes(options: IntrospectOptions): Promise<EmittedTypes | null> {
+  const root = resolve(options.root || process.cwd())
+  const outPath = options.out || join(root, DEFAULT_OUTPUT)
+
+  if (options.verbose) {
+    console.log(`📁 Scanning: ${root}`)
+  }
+
+  // Load and merge all schema files
+  const merged = await loadAndMergeSchemas(root)
+
+  if (Object.keys(merged.entities).length === 0) {
+    console.log('⚠️  No schemas found. Create a DB.mdx file to get started.')
+    return null
+  }
+
+  // Emit types
+  const emitted = emitFromMdxSchema(
+    {
+      entities: merged.entities,
+      source: merged.sources.join(', '),
+    },
+    { includeComments: true },
+  )
+
+  if (options.verbose) {
+    console.log(`📦 Found ${emitted.entities.length} entities:`)
+    for (const e of emitted.entities) {
+      console.log(`   - ${e}`)
+    }
+  }
+
+  if (options.check) {
+    // Check mode - compare with existing
+    if (existsSync(outPath)) {
+      const existing = readFileSync(outPath, 'utf-8')
+      if (existing === emitted.content) {
+        console.log('✅ Types are up to date')
+        return emitted
+      } else {
+        console.log('❌ Types are out of date. Run `dotdo introspect` to update.')
+        process.exitCode = 1
+        return emitted
+      }
+    } else {
+      console.log(`❌ Types file not found: ${outPath}`)
+      process.exitCode = 1
+      return emitted
+    }
+  }
+
+  // Write types file
+  const outDir = dirname(outPath)
+  if (!existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true })
+  }
+
+  writeFileSync(outPath, emitted.content, 'utf-8')
+  console.log(`✅ Generated ${outPath}`)
+  console.log(`   ${emitted.entities.length} entities, ${emitted.events.length} events`)
+
+  return emitted
+}
+
+/**
+ * Watch mode - regenerate on file changes
+ */
+async function watchMode(options: IntrospectOptions): Promise<void> {
+  const root = resolve(options.root || process.cwd())
+
+  console.log(`👀 Watching for changes in ${root}...`)
+
+  // Initial generation
+  await generateTypes(options)
+
+  // Watch for changes
+  const watcher = watch(root, { recursive: true }, async (eventType, filename) => {
+    if (!filename) return
+
+    // Only watch MDX files
+    if (filename.endsWith('.mdx') || filename.endsWith('.do.mdx')) {
+      console.log(`\n📝 Changed: ${filename}`)
+      await generateTypes({ ...options, verbose: false })
+    }
+  })
+
+  // Keep process running
+  process.on('SIGINT', () => {
+    watcher.close()
+    console.log('\n👋 Stopped watching')
+    process.exit(0)
+  })
+}
+
+/**
+ * Main command handler
+ */
+export async function run(args: string[]): Promise<void> {
+  const options = parseArgs(args)
+
+  // Show help
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage: dotdo introspect [options] [root]
+
+Generate TypeScript types from DB.mdx schema files.
+
+Options:
+  -o, --out <path>   Output path (default: .do/types.d.ts)
+  -w, --watch        Watch mode - regenerate on changes
+  -c, --check        Check if types are up to date (CI mode)
+  -v, --verbose      Verbose output
+  -r, --root <path>  Project root directory
+  -h, --help         Show this help
+
+Examples:
+  dotdo introspect                    Generate types
+  dotdo introspect --watch            Watch mode
+  dotdo introspect --check            CI validation
+  dotdo introspect --out types.d.ts   Custom output
+`)
+    return
+  }
+
+  if (options.watch) {
+    await watchMode(options)
+  } else {
+    await generateTypes(options)
+  }
+}
+
+export { emitFromMdxSchema, emitFromDOSchema, mergeEmittedTypes } from './emitter'