@famgia/omnify-core 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,6 @@
 # @famgia/omnify-core
 
-Core engine for the Omnify schema system. Load, validate, and process YAML/JSON schemas.
+Core engine for the Omnify schema system. Provides schema loading, validation, plugin management, and generator execution.
 
 ## Installation
 
@@ -10,40 +10,247 @@ npm install @famgia/omnify-core
 
 ## Usage
 
+### Load and Validate Schemas
+
 ```typescript
-import {
-  loadSchemas,
-  validateSchemas,
-  createOmnify,
-  Omnify
-} from '@famgia/omnify-core';
+import { loadSchemas, validateSchemas } from '@famgia/omnify-core';
 
 // Load schemas from directory
 const schemas = await loadSchemas('./schemas');
 
 // Validate schemas
 const result = validateSchemas(schemas);
+
 if (!result.valid) {
-  console.error(result.errors);
+  for (const error of result.errors) {
+    console.error(`${error.schemaName}: ${error.message}`);
+  }
 }
+```
+
+### Plugin Manager
+
+```typescript
+import { PluginManager } from '@famgia/omnify-core';
+import type { OmnifyPlugin } from '@famgia/omnify-types';
+
+const manager = new PluginManager({
+  cwd: process.cwd(),
+  verbose: true,
+  logger: console,
+});
+
+// Register a plugin
+await manager.register(myPlugin);
+
+// Get all registered custom types
+const customTypes = manager.getCustomTypes();
+
+// Run all generators
+const result = await manager.runGenerators(schemas);
+
+if (result.success) {
+  for (const output of result.outputs) {
+    console.log(`Generated: ${output.path}`);
+  }
+}
+```
+
+### Generator Runner (DAG-based)
+
+```typescript
+import { GeneratorRunner } from '@famgia/omnify-core';
 
-// Or use the Omnify class for full API
-const omnify = createOmnify({
-  schemaDir: './schemas',
-  plugins: [myPlugin],
+const runner = new GeneratorRunner({
+  cwd: process.cwd(),
+  verbose: true,
+  logger: console,
 });
 
-await omnify.initialize();
-const schemas = omnify.getSchemas();
+// Register generators (automatically sorts by dependencies)
+runner.registerAll([
+  {
+    definition: schemaGenerator,
+    pluginName: 'my-plugin',
+    pluginConfig: {},
+  },
+  {
+    definition: migrationGenerator,
+    pluginName: 'my-plugin',
+    pluginConfig: {},
+  },
+]);
+
+// Execute in topological order
+const result = await runner.runAll(schemas);
+```
+
+### Error Handling
+
+```typescript
+import { OmnifyError } from '@famgia/omnify-core';
+
+try {
+  await loadSchemas('./invalid-path');
+} catch (error) {
+  if (error instanceof OmnifyError) {
+    console.error(`[${error.code}] ${error.message}`);
+    if (error.schemaName) {
+      console.error(`  Schema: ${error.schemaName}`);
+    }
+    if (error.suggestion) {
+      console.error(`  Suggestion: ${error.suggestion}`);
+    }
+  }
+}
+```
+
+## API Reference
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `loadSchemas(path)` | Load all YAML/JSON schema files from directory |
+| `loadSchema(filePath)` | Load a single schema file |
+| `validateSchemas(schemas)` | Validate schema collection |
+| `validateSchema(schema)` | Validate a single schema |
+
+### Classes
+
+#### `PluginManager`
+
+Manages plugin registration and generator execution.
+
+```typescript
+new PluginManager(options: PluginManagerOptions)
+
+interface PluginManagerOptions {
+  cwd: string;
+  verbose?: boolean;
+  logger?: PluginLogger;
+}
 ```
 
-## Features
+Methods:
+- `register(plugin)` - Register a plugin
+- `getPlugin(name)` - Get plugin by name
+- `getCustomTypes()` - Get all custom types
+- `hasCustomType(name)` - Check if custom type exists
+- `getGenerators()` - Get all registered generators
+- `runGenerators(schemas)` - Execute all generators
+
+#### `GeneratorRunner`
+
+Executes generators in dependency order using topological sort.
+
+```typescript
+new GeneratorRunner(options: GeneratorRunnerOptions)
+```
+
+Methods:
+- `register(generator)` - Register a single generator
+- `registerAll(generators)` - Register multiple generators
+- `runAll(schemas)` - Execute all generators in order
+- `getOrder()` - Get execution order (for debugging)
+
+#### `OmnifyError`
+
+Custom error class with detailed error information.
+
+```typescript
+class OmnifyError extends Error {
+  code: string;
+  schemaName?: string;
+  propertyName?: string;
+  filePath?: string;
+  suggestion?: string;
+}
+```
+
+## Plugin System
+
+### Creating a Plugin
+
+```typescript
+import type { OmnifyPlugin } from '@famgia/omnify-types';
+
+const myPlugin: OmnifyPlugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+
+  // Lifecycle hooks
+  setup: async (context) => {
+    console.log('Plugin initialized');
+  },
+
+  teardown: async () => {
+    console.log('Plugin cleanup');
+  },
+
+  // Custom types
+  types: [
+    {
+      name: 'Money',
+      typescript: 'number',
+      laravel: 'decimal',
+      laravelParams: [10, 2],
+    },
+  ],
+
+  // Generators
+  generators: [
+    {
+      name: 'my-generator',
+      description: 'Generate custom files',
+      dependsOn: ['other-generator'],
+
+      generate: async (ctx) => {
+        return [{
+          path: 'output/file.ts',
+          content: '// Generated',
+          type: 'other',
+        }];
+      },
+    },
+  ],
+};
+```
+
+### Generator Dependencies
+
+Generators can specify `dependsOn` to control execution order:
+
+```typescript
+generators: [
+  {
+    name: 'schema-generator',
+    generate: async (ctx) => { /* ... */ },
+  },
+  {
+    name: 'migration-generator',
+    dependsOn: ['schema-generator'], // Runs after schema-generator
+    generate: async (ctx) => {
+      // Access previous outputs
+      const schemaOutputs = ctx.previousOutputs.get('schema-generator');
+      // ...
+    },
+  },
+]
+```
+
+The GeneratorRunner uses Kahn's algorithm for topological sorting and detects circular dependencies.
+
+## Validation Rules
+
+The validator checks for:
 
-- YAML/JSON schema loading
-- Schema validation with detailed errors
-- Plugin system for custom types
-- Programmatic API for tooling integration
-- Metadata introspection utilities
+- Valid schema structure (name, kind, properties)
+- Valid property types (built-in or custom)
+- Valid association types and references
+- Unique property names
+- Required fields presence
+- Circular reference detection
 
 ## Related Packages
 

package/dist/index.cjs

@@ -1156,6 +1156,163 @@ function validateSchemas(schemas, options = {}) {
   };
 }
 
+// src/plugins/generator-runner.ts
+var GeneratorRunner = class {
+  generators = /* @__PURE__ */ new Map();
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Register a generator.
+   */
+  register(generator) {
+    const name = generator.definition.name;
+    if (this.generators.has(name)) {
+      throw new Error(`Generator "${name}" is already registered`);
+    }
+    this.generators.set(name, generator);
+  }
+  /**
+   * Register multiple generators.
+   */
+  registerAll(generators) {
+    for (const gen of generators) {
+      this.register(gen);
+    }
+  }
+  /**
+   * Clear all registered generators.
+   */
+  clear() {
+    this.generators.clear();
+  }
+  /**
+   * Get all registered generator names.
+   */
+  getGeneratorNames() {
+    return Array.from(this.generators.keys());
+  }
+  /**
+   * Check if a generator is registered.
+   */
+  hasGenerator(name) {
+    return this.generators.has(name);
+  }
+  /**
+   * Run all generators in topological order.
+   */
+  async runAll(schemas) {
+    const errors = [];
+    const outputs = [];
+    const outputsByGenerator = /* @__PURE__ */ new Map();
+    let executionOrder;
+    try {
+      executionOrder = this.topologicalSort();
+    } catch (error) {
+      return {
+        success: false,
+        outputs: [],
+        outputsByGenerator: /* @__PURE__ */ new Map(),
+        executionOrder: [],
+        errors: [{
+          generatorName: "",
+          message: error instanceof Error ? error.message : String(error),
+          cause: error
+        }]
+      };
+    }
+    const previousOutputs = /* @__PURE__ */ new Map();
+    for (const name of executionOrder) {
+      const generator = this.generators.get(name);
+      const { definition, pluginConfig } = generator;
+      try {
+        this.options.logger.debug(`Running generator: ${name}`);
+        const ctx = {
+          schemas,
+          pluginConfig,
+          cwd: this.options.cwd,
+          logger: this.options.logger,
+          previousOutputs
+        };
+        const result = await definition.generate(ctx);
+        const generatorOutputs = Array.isArray(result) ? result : [result];
+        outputsByGenerator.set(name, generatorOutputs);
+        previousOutputs.set(name, generatorOutputs);
+        outputs.push(...generatorOutputs);
+        this.options.logger.debug(`Generator ${name} produced ${generatorOutputs.length} outputs`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.options.logger.error(`Generator ${name} failed: ${message}`);
+        errors.push({
+          generatorName: name,
+          message,
+          cause: error
+        });
+      }
+    }
+    return {
+      success: errors.length === 0,
+      outputs,
+      outputsByGenerator,
+      executionOrder,
+      errors
+    };
+  }
+  /**
+   * Topological sort using Kahn's algorithm.
+   * Returns generators in execution order (dependencies first).
+   * Throws if circular dependencies detected.
+   */
+  topologicalSort() {
+    const names = Array.from(this.generators.keys());
+    const inDegree = /* @__PURE__ */ new Map();
+    const adjacency = /* @__PURE__ */ new Map();
+    for (const name of names) {
+      inDegree.set(name, 0);
+      adjacency.set(name, []);
+    }
+    for (const name of names) {
+      const generator = this.generators.get(name);
+      const deps = generator.definition.dependsOn ?? [];
+      for (const dep of deps) {
+        if (!this.generators.has(dep)) {
+          throw new Error(
+            `Generator "${name}" depends on "${dep}" which is not registered`
+          );
+        }
+        adjacency.get(dep).push(name);
+        inDegree.set(name, inDegree.get(name) + 1);
+      }
+    }
+    const queue = [];
+    const result = [];
+    for (const [name, degree] of inDegree) {
+      if (degree === 0) {
+        queue.push(name);
+      }
+    }
+    while (queue.length > 0) {
+      const current = queue.shift();
+      result.push(current);
+      for (const neighbor of adjacency.get(current)) {
+        const newDegree = inDegree.get(neighbor) - 1;
+        inDegree.set(neighbor, newDegree);
+        if (newDegree === 0) {
+          queue.push(neighbor);
+        }
+      }
+    }
+    if (result.length !== names.length) {
+      const remaining = names.filter((n) => !result.includes(n));
+      throw new Error(
+        `Circular dependency detected among generators: ${remaining.join(", ")}`
+      );
+    }
+    return result;
+  }
+};
+
 // src/plugins/manager.ts
 var nullLogger = {
   debug: () => {
@@ -1176,6 +1333,8 @@ var consoleLogger = {
 var PluginManager = class {
   _plugins = /* @__PURE__ */ new Map();
   _types = /* @__PURE__ */ new Map();
+  _generators = /* @__PURE__ */ new Map();
+  _pluginConfigs = /* @__PURE__ */ new Map();
   _cwd;
   _verbose;
   _logger;
@@ -1196,8 +1355,10 @@ var PluginManager = class {
   }
   /**
    * Registers a single plugin.
+   * @param plugin - The plugin to register
+   * @param pluginConfig - Optional configuration passed to plugin generators
    */
-  async register(plugin) {
+  async register(plugin, pluginConfig = {}) {
     const warnings = [];
     const registeredTypes = [];
     if (this._plugins.has(plugin.name)) {
@@ -1209,6 +1370,7 @@ var PluginManager = class {
       };
     }
     this._logger.debug(`Registering plugin: ${plugin.name}@${plugin.version}`);
+    this._pluginConfigs.set(plugin.name, pluginConfig);
     if (plugin.setup) {
       try {
         await plugin.setup(this.createContext());
@@ -1247,8 +1409,30 @@ var PluginManager = class {
         this._logger.debug(`  Registered type: ${typeDef.name}`);
       }
     }
+    if (plugin.generators) {
+      for (const genDef of plugin.generators) {
+        const existing = this._generators.get(genDef.name);
+        if (existing) {
+          warnings.push(
+            `Generator '${genDef.name}' already registered by plugin '${existing.pluginName}'`
+          );
+          continue;
+        }
+        const registeredGenerator = {
+          definition: genDef,
+          pluginName: plugin.name,
+          pluginVersion: plugin.version,
+          pluginConfig
+        };
+        this._generators.set(genDef.name, registeredGenerator);
+        this._logger.debug(`  Registered generator: ${genDef.name}`);
+      }
+    }
     this._plugins.set(plugin.name, plugin);
-    this._logger.info(`Plugin registered: ${plugin.name} (${registeredTypes.length} types)`);
+    const genCount = plugin.generators?.length ?? 0;
+    this._logger.info(
+      `Plugin registered: ${plugin.name} (${registeredTypes.length} types, ${genCount} generators)`
+    );
     return {
       success: true,
       types: registeredTypes,
@@ -1299,7 +1483,7 @@ var PluginManager = class {
     return void 0;
   }
   /**
-   * Unregisters a plugin and its types.
+   * Unregisters a plugin and its types/generators.
    */
   async unregister(pluginName) {
     const plugin = this._plugins.get(pluginName);
@@ -1319,6 +1503,12 @@ var PluginManager = class {
         this._types.delete(typeName);
       }
     }
+    for (const [genName, gen] of this._generators) {
+      if (gen.pluginName === pluginName) {
+        this._generators.delete(genName);
+      }
+    }
+    this._pluginConfigs.delete(pluginName);
     this._plugins.delete(pluginName);
     this._logger.info(`Plugin unregistered: ${pluginName}`);
   }
@@ -1358,17 +1548,57 @@ var PluginManager = class {
   getAllPlugins() {
     return this._plugins;
   }
+  /**
+   * Gets a registered generator by name.
+   */
+  getGenerator(generatorName) {
+    return this._generators.get(generatorName);
+  }
+  /**
+   * Checks if a generator is registered.
+   */
+  hasGenerator(generatorName) {
+    return this._generators.has(generatorName);
+  }
+  /**
+   * Gets all registered generators.
+   */
+  getAllGenerators() {
+    return this._generators;
+  }
+  /**
+   * Gets all registered generator names.
+   */
+  getGeneratorNames() {
+    return Array.from(this._generators.keys());
+  }
   /**
    * Gets the current registry state.
    */
   getRegistry() {
     return {
       plugins: this._plugins,
-      types: this._types
+      types: this._types,
+      generators: this._generators
     };
   }
   /**
-   * Clears all registered plugins and types.
+   * Runs all registered generators in topological order.
+   * @param schemas - The schemas to generate from
+   * @returns Result with all generated outputs
+   */
+  async runGenerators(schemas) {
+    const runner = new GeneratorRunner({
+      cwd: this._cwd,
+      logger: this._logger
+    });
+    for (const gen of this._generators.values()) {
+      runner.register(gen);
+    }
+    return runner.runAll(schemas);
+  }
+  /**
+   * Clears all registered plugins, types, and generators.
    */
   async clear() {
     for (const plugin of this._plugins.values()) {
@@ -1381,6 +1611,8 @@ var PluginManager = class {
     }
     this._plugins.clear();
     this._types.clear();
+    this._generators.clear();
+    this._pluginConfigs.clear();
     this._logger.debug("Plugin registry cleared");
   }
 };