@devilsdev/rag-pipeline-utils 2.1.12 → 2.2.0

package/src/utils/plugin-scaffolder.js

@@ -0,0 +1,447 @@
+/**
+ * Version: 1.0.0
+ * Path: /src/utils/plugin-scaffolder.js
+ * Description: Plugin scaffolding utility for creating new plugins with best practices
+ * Author: Ali Kahwaji
+ */
+
+const fs = require('fs');
+// eslint-disable-line global-require
+const path = require('path');
+// eslint-disable-line global-require
+const { pluginContracts } = require('../core/plugin-contracts.js');
+// eslint-disable-line global-require
+
+class PluginScaffolder {
+  constructor(_options = {}) {
+    this.outputDir = _options.outputDir || process.cwd();
+    this.author = _options.author || 'Your Name';
+    this.namespace = _options.namespace || 'your-namespace';
+  }
+
+  /**
+   * Scaffold a new plugin with all necessary files
+   * @param {string} pluginType - Type of plugin (loader, embedder, retriever, llm, reranker)
+   * @param {string} pluginName - Name of the plugin
+   * @param {object} _options - Additional _options
+   */
+  async scaffoldPlugin(pluginType, pluginName, _options = {}) {
+    if (!pluginContracts[pluginType]) {
+      throw new Error(
+        `Unknown plugin _type: ${pluginType}. Available types: ${Object.keys(pluginContracts).join(', ')}`,
+      );
+    }
+
+    const pluginDir = path.join(this.outputDir, `${pluginName}-${pluginType}`);
+
+    // Create plugin directory
+    if (!fs.existsSync(pluginDir)) {
+      fs.mkdirSync(pluginDir, { recursive: true });
+    }
+
+    // Generate all plugin files
+    await this.generatePluginFile(pluginDir, pluginType, pluginName, _options);
+    await this.generateTestFile(pluginDir, pluginType, pluginName);
+    await this.generateMockFile(pluginDir, pluginType, pluginName);
+    await this.generateConfigExample(pluginDir, pluginType, pluginName);
+    await this.generateReadme(pluginDir, pluginType, pluginName, _options);
+    await this.generatePackageJson(pluginDir, pluginType, pluginName, _options);
+
+    console.log(`✅ Plugin scaffolded successfully at: ${pluginDir}`);
+    // eslint-disable-line no-console
+    console.log('📁 Generated files:');
+    // eslint-disable-line no-console
+    console.log(`   - src/${pluginName}-${pluginType}.js (main plugin)`);
+    // eslint-disable-line no-console
+    console.log(`   - __tests__/${pluginName}-${pluginType}.test.js (tests)`);
+    // eslint-disable-line no-console
+    console.log(
+      `   - mocks/${pluginName}-${pluginType}-mock.js (mock implementation)`,
+    );
+    // eslint-disable-line no-console
+    console.log('   - .ragrc.example.json (configuration example)');
+    // eslint-disable-line no-console
+    console.log('   - README.md (documentation)');
+    // eslint-disable-line no-console
+    console.log('   - package.json (npm package)');
+    // eslint-disable-line no-console
+  }
+
+  /**
+   * Generate the main plugin implementation file
+   */
+  async generatePluginFile(pluginDir, pluginType, pluginName, _options) {
+    const contract = pluginContracts[pluginType];
+    const className = this.toPascalCase(`${pluginName}_${pluginType}`);
+    const srcDir = path.join(pluginDir, 'src');
+
+    if (!fs.existsSync(srcDir)) {
+      fs.mkdirSync(srcDir, { recursive: true });
+    }
+
+    const methods = contract.requiredMethods
+      .map((methodName) => {
+        const signature = contract.methodSignatures?.[methodName];
+        return this.generateMethodStub(methodName, signature);
+      })
+      .join('\n\n');
+
+    const optionalMethods =
+      contract.optionalMethods
+        ?.map((methodName) => {
+          const signature = contract.methodSignatures?.[methodName];
+          return this.generateMethodStub(methodName, signature, true);
+        })
+        .join('\n\n') || '';
+
+    const kebabName = pluginName
+      .replace(/([A-Z])/g, '-$1')
+      .toLowerCase()
+      .replace(/^-/, '');
+
+    const content = `/**
+ * ${className} - ${pluginType} plugin implementation
+ * Generated by RAG Pipeline Utils Plugin Scaffolder
+ * Author: ${this.author}
+ */
+
+class ${className} {
+  constructor(options = {}) {
+    this.name = '${kebabName}';
+    this.options = options;
+    
+    // Add your initialization logic here
+    // Example: this.apiKey = options.apiKey;
+    // Example: this.endpoint = options.endpoint || 'https://api.example.com';
+  }
+
+${methods}${optionalMethods ? '\n\n  // Optional methods\n' + optionalMethods : ''}
+}
+
+module.exports = ${className};
+`;
+
+    const _filePath = path.join(srcDir, `${pluginName}-${pluginType}.js`);
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate method stub with proper signature
+   */
+  generateMethodStub(methodName, signature, isOptional = false) {
+    const params = signature?.params || ['input'];
+    const paramTypes = signature?.paramTypes || ['any'];
+    const returnType = signature?.returnType || 'Promise<any>';
+    const description =
+      signature?.description ||
+      `${isOptional ? 'Optional: ' : ''}Implement ${methodName} functionality`;
+
+    const paramList = params.map((param, _i) => `${param}`).join(', ');
+    const paramDocs = params
+      .map((param, _i) => `   * @param {${paramTypes[_i]}} ${param}`)
+      .join('\n');
+
+    return `  /**
+   * ${description}
+${paramDocs}
+   * @returns {${returnType}}
+   */
+  async ${methodName}(${paramList}) {
+    // TODO: Implement ${methodName} logic
+    throw new Error('${methodName} not yet implemented');
+  }`;
+  }
+
+  /**
+   * Generate test file
+   */
+  async generateTestFile(pluginDir, pluginType, pluginName) {
+    const className = this.toPascalCase(`${pluginName}_${pluginType}`);
+    const testDir = path.join(pluginDir, '__tests__');
+
+    if (!fs.existsSync(testDir)) {
+      fs.mkdirSync(testDir, { recursive: true });
+    }
+
+    const contract = pluginContracts[pluginType];
+    const testCases = contract.requiredMethods
+      .map((method) => {
+        return `  describe('${method}', () => {
+    it('should implement ${method} method', () => {
+      expect(typeof plugin.${method}).toBe('function');
+    });
+
+    it('should handle ${method} functionality', async () => {
+      // TODO: Add specific test cases for ${method}
+      // Example: const result = await plugin.${method}(testInput);
+      // Example: expect(result).toBeDefined();
+    });
+  });`;
+      })
+      .join('\n\n');
+
+    const content = `/**
+ * Tests for ${className}
+ * Generated by RAG Pipeline Utils Plugin Scaffolder
+ */
+
+const { ${className} } = require('../src/${pluginName}-${pluginType}.js');
+
+describe('${className}', () => {
+  let plugin;
+
+  beforeEach(() => {
+    plugin = new ${className}({
+      // Add test configuration _options here
+    });
+  });
+
+  describe('constructor', () => {
+    it('should create _instance with default _options', () => {
+      const _instance = new ${className}();
+      expect(_instance).toBeInstanceOf(${className});
+    });
+
+    it('should accept configuration _options', () => {
+      const _options = { testOption: 'value' };
+      const _instance = new ${className}(_options);
+      expect(_instance._options).toEqual(_options);
+    });
+  });
+
+${testCases}
+
+  describe('error handling', () => {
+    it('should handle invalid inputs gracefully', async () => {
+      // TODO: Add error handling tests
+      // Example: await expect(plugin.someMethod(null)).rejects.toThrow();
+    });
+  });
+});
+`;
+
+    const _filePath = path.join(testDir, `${pluginName}-${pluginType}.test.js`);
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate mock implementation file
+   */
+  async generateMockFile(pluginDir, pluginType, pluginName) {
+    const className = this.toPascalCase(`${pluginName}_${pluginType}`);
+    const mockDir = path.join(pluginDir, 'mocks');
+
+    if (!fs.existsSync(mockDir)) {
+      fs.mkdirSync(mockDir, { recursive: true });
+    }
+
+    const contract = pluginContracts[pluginType];
+    const mockMethods = contract.requiredMethods
+      .map((methodName) => {
+        return `  async ${methodName}(...args) {
+    // Mock implementation for ${methodName}
+    console.log(\`Mock ${className}.${methodName} called with:\`, args);
+ // eslint-disable-line no-console
+    return \`Mock result from ${methodName}\`;
+  }`;
+      })
+      .join('\n\n');
+
+    const content = `/**
+ * Mock implementation of ${className}
+ * Generated by RAG Pipeline Utils Plugin Scaffolder
+ * Use this for testing and development
+ */
+
+class Mock${className} {
+  constructor(_options = {}) {
+    this._options = _options;
+    this.mockMode = true;
+  }
+
+${mockMethods}
+}
+
+// Export default instance for easy use
+ Mock${className}();
+`;
+
+    const _filePath = path.join(mockDir, `${pluginName}-${pluginType}-mock.js`);
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate configuration example
+   */
+  async generateConfigExample(pluginDir, pluginType, pluginName) {
+    const _config = {
+      [pluginType]: {
+        [pluginName]: `./src/${pluginName}-${pluginType}.js`,
+      },
+      namespace: `${pluginName}-namespace`,
+      pipeline: ['loader', 'embedder', 'retriever'],
+    };
+
+    const content = JSON.stringify(_config, null, 2);
+    const _filePath = path.join(pluginDir, '.ragrc.example.json');
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate README documentation
+   */
+  async generateReadme(pluginDir, pluginType, pluginName, _options) {
+    const className = this.toPascalCase(`${pluginName}_${pluginType}`);
+    const contract = pluginContracts[pluginType];
+
+    const methodDocs = contract.requiredMethods
+      .map((method) => {
+        const signature = contract.methodSignatures?.[method];
+        return `### \`${method}(${signature?.params?.join(', ') || '...args'})\`
+
+${signature?.description || `Implements ${method} functionality`}
+
+**Parameters:**
+${signature?.params?.map((param, _i) => `- \`${param}\` (${signature.paramTypes?.[_i] || 'any'})`).join('\n') || '- TBD'}
+
+**Returns:** \`${signature?.returnType || 'Promise<any>'}\``;
+      })
+      .join('\n\n');
+
+    const content = `# ${className}
+
+A ${pluginType} plugin for RAG Pipeline Utils.
+
+## Description
+
+${_options.description || `This plugin provides ${pluginType} functionality for RAG (Retrieval-Augmented Generation) pipelines.`}
+
+## Installation
+
+\`\`\`bash
+npm install ${this.namespace}/${pluginName}-${pluginType}
+\`\`\`
+
+## Usage
+
+### Basic Usage
+
+\`\`\`javascript
+const { ${className} } = require('${this.namespace}/${pluginName}-${pluginType}');
+
+const plugin = new ${className}({
+  // Configuration _options
+});
+
+// Use the plugin methods
+// const result = await plugin.someMethod(input);
+\`\`\`
+
+### With RAG Pipeline Utils
+
+\`\`\`json
+{
+  "${pluginType}": {
+    "${pluginName}": "./src/${pluginName}-${pluginType}.js"
+  }
+}
+\`\`\`
+
+## API Reference
+
+${methodDocs}
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| \`option1\` | \`string\` | \`"default"\` | Description of option1 |
+| \`option2\` | \`number\` | \`100\` | Description of option2 |
+
+## Testing
+
+\`\`\`bash
+npm test
+\`\`\`
+
+## Development
+
+1. Clone the repository
+2. Install dependencies: \`npm install\`
+3. Run tests: \`npm test\`
+4. Build: \`npm run build\`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT
+
+## Author
+
+${this.author}
+`;
+
+    const _filePath = path.join(pluginDir, 'README.md');
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Generate package.json
+   */
+  async generatePackageJson(pluginDir, pluginType, pluginName, _options) {
+    const packageName = `${this.namespace}/${pluginName}-${pluginType}`;
+
+    const packageJson = {
+      name: packageName,
+      version: '1.0.0',
+      description:
+        _options.description || `A ${pluginType} plugin for RAG Pipeline Utils`,
+      main: `src/${pluginName}-${pluginType}.js`,
+      _type: 'module',
+      scripts: {
+        test: 'jest',
+        'test:watch': 'jest --watch',
+        lint: 'eslint src/ __tests__/',
+        'lint:fix': 'eslint src/ __tests__/ --fix',
+      },
+      keywords: ['rag', 'pipeline', 'plugin', pluginType, 'ai', 'ml'],
+      author: this.author,
+      license: 'MIT',
+      peerDependencies: {
+        '@devilsdev/rag-pipeline-utils': '^2.0.0',
+      },
+      devDependencies: {
+        jest: '^29.7.0',
+        eslint: '^8.57.1',
+      },
+      files: ['src/', 'mocks/', 'README.md', '.ragrc.example.json'],
+    };
+
+    const content = JSON.stringify(packageJson, null, 2);
+    const _filePath = path.join(pluginDir, 'package.json');
+    fs.writeFileSync(_filePath, content);
+  }
+
+  /**
+   * Convert string to PascalCase
+   */
+  toPascalCase(str) {
+    return str
+      .split(/[-_\s]/)
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join('');
+  }
+}
+
+// Default export
+
+module.exports = {
+  PluginScaffolder,
+};