@memberjunction/query-gen 0.0.1 → 2.126.1

package/src/cli/commands/validate.ts

@@ -0,0 +1,185 @@
+/**
+ * Validate command - Validate existing query templates
+ *
+ * Tests existing query metadata files to ensure they are valid:
+ * - SQL syntax validation
+ * - Parameter validation
+ * - Output field validation
+ * - Execution testing (optional)
+ */
+
+import ora from 'ora';
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { Metadata, DatabaseProviderBase } from '@memberjunction/core';
+import { getSystemUser } from '../../utils/user-helpers';
+import { QueryTester } from '../../core/QueryTester';
+import { extractErrorMessage } from '../../utils/error-handlers';
+import { GeneratedQuery, QueryMetadataRecord } from '../../data/schema';
+import { loadConfig } from '../config';
+
+/**
+ * Execute the validate command
+ *
+ * Loads query metadata files and validates each query template.
+ * Reports success/failure statistics.
+ */
+export async function validateCommand(options: Record<string, unknown>): Promise<void> {
+  const spinner = ora('Initializing validation...').start();
+
+  try {
+    const queryPath = String(options.path || './metadata/queries');
+    const verbose = Boolean(options.verbose);
+
+    // Load configuration
+    const config = loadConfig(options);
+
+    // 1. Get system user from UserCache (populated by provider initialization)
+    const contextUser = getSystemUser();
+
+    // 2. Verify database connection and load metadata
+    spinner.text = 'Loading metadata...';
+    // Assume provider is already configured by the calling application
+    if (!Metadata.Provider) {
+      throw new Error('Metadata provider not configured. Please ensure database connection is set up before running CLI.');
+    }
+    spinner.succeed('Metadata loaded');
+
+    // 3. Load query metadata files
+    spinner.start(`Loading query files from ${queryPath}...`);
+    const queryFiles = await loadQueryFiles(queryPath);
+    spinner.succeed(chalk.green(`Found ${queryFiles.length} query files`));
+
+    // 4. Validate each query
+    const dataProvider = Metadata.Provider.DatabaseConnection as DatabaseProviderBase;
+    let passCount = 0;
+    let failCount = 0;
+    const errors: Array<{ file: string; error: string }> = [];
+
+    for (let i = 0; i < queryFiles.length; i++) {
+      const { file, queries } = queryFiles[i];
+      const filePrefix = chalk.cyan(`[${i + 1}/${queryFiles.length}]`);
+
+      spinner.start(`${filePrefix} Validating ${chalk.dim(file)}...`);
+
+      for (const queryRecord of queries) {
+        try {
+          const query = convertMetadataToGeneratedQuery(queryRecord);
+
+          // Create a minimal business question and entity metadata for testing
+          const dummyQuestion = {
+            userQuestion: queryRecord.fields.UserQuestion || 'Test query',
+            description: queryRecord.fields.Description || '',
+            technicalDescription: queryRecord.fields.TechnicalDescription || '',
+            complexity: 'medium' as const,
+            requiresAggregation: false,
+            requiresJoins: false,
+            entities: []
+          };
+
+          const tester = new QueryTester(dataProvider, [], dummyQuestion, contextUser, config);
+
+          // Test query execution
+          const testResult = await tester.testQuery(query, 1);
+
+          if (testResult.success) {
+            passCount++;
+            if (verbose) {
+              spinner.info(`${filePrefix} ${chalk.green('✓')} ${queryRecord.fields.Name}`);
+            }
+          } else {
+            failCount++;
+            const errorMsg = testResult.error || 'Unknown error';
+            errors.push({ file, error: `${queryRecord.fields.Name}: ${errorMsg}` });
+            if (verbose) {
+              spinner.warn(`${filePrefix} ${chalk.red('✗')} ${queryRecord.fields.Name}: ${errorMsg}`);
+            }
+          }
+        } catch (error: unknown) {
+          failCount++;
+          const errorMsg = extractErrorMessage(error, 'Query Validation');
+          errors.push({ file, error: `${queryRecord.fields.Name}: ${errorMsg}` });
+          if (verbose) {
+            spinner.warn(`${filePrefix} ${chalk.red('✗')} ${queryRecord.fields.Name}: ${errorMsg}`);
+          }
+        }
+      }
+
+      spinner.succeed(`${filePrefix} ${chalk.dim(file)} complete`);
+    }
+
+    // 5. Summary
+    if (failCount === 0) {
+      spinner.succeed(chalk.green.bold(`✓ All ${passCount} queries validated successfully!`));
+      console.log('\n' + chalk.green.bold('✓ Validation complete!\n'));
+      console.log(chalk.bold('Summary:'));
+      console.log(`  Total Queries: ${chalk.cyan(passCount.toString())}`);
+      console.log(`  Passed: ${chalk.green(passCount.toString())}`);
+      console.log(`  Failed: ${chalk.green('0')}`);
+      process.exit(0);
+    } else {
+      spinner.fail(chalk.yellow(`Validation completed with ${failCount} errors`));
+      console.log('\n' + chalk.yellow.bold('⚠ Validation completed with errors\n'));
+      console.log(chalk.bold('Summary:'));
+      console.log(`  Total Queries: ${chalk.cyan((passCount + failCount).toString())}`);
+      console.log(`  Passed: ${chalk.green(passCount.toString())}`);
+      console.log(`  Failed: ${chalk.red(failCount.toString())}`);
+
+      if (errors.length > 0) {
+        console.log('\n' + chalk.bold('Errors:'));
+        for (const { file, error } of errors) {
+          console.log(chalk.red(`  ${file}: ${error}`));
+        }
+      }
+      process.exit(1);
+    }
+
+  } catch (error: unknown) {
+    spinner.fail(chalk.red('Validation failed'));
+    console.error(chalk.red(extractErrorMessage(error, 'Query Validation')));
+    process.exit(1);
+  }
+}
+
+/**
+ * Load all query metadata files from the specified directory
+ */
+async function loadQueryFiles(queryPath: string): Promise<Array<{ file: string; queries: QueryMetadataRecord[] }>> {
+  const files: Array<{ file: string; queries: QueryMetadataRecord[] }> = [];
+
+  if (!fs.existsSync(queryPath)) {
+    throw new Error(`Query path not found: ${queryPath}`);
+  }
+
+  const entries = fs.readdirSync(queryPath);
+  for (const entry of entries) {
+    const fullPath = path.join(queryPath, entry);
+    const stat = fs.statSync(fullPath);
+
+    if (stat.isFile() && entry.endsWith('.json')) {
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      const data = JSON.parse(content);
+
+      // Handle both single query and array formats
+      const queries = Array.isArray(data) ? data : [data];
+      files.push({ file: entry, queries });
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Convert metadata record to GeneratedQuery format for testing
+ *
+ * Note: QueryFields and QueryParameters are auto-extracted by QueryEntity.server.ts,
+ * so we only validate the SQL itself. The validate command focuses on SQL syntax
+ * and execution, not on field/parameter metadata which is managed by MJ.
+ */
+function convertMetadataToGeneratedQuery(record: QueryMetadataRecord): GeneratedQuery {
+  return {
+    sql: record.fields.SQL,
+    parameters: [],    // Not needed for validation - QueryEntity will extract
+  };
+}

package/src/cli/config.ts

@@ -0,0 +1,203 @@
+/**
+ * Configuration loader for QueryGen
+ *
+ * Loads configuration from mj.config.cjs and merges with CLI options
+ */
+
+/**
+ * QueryGen configuration options
+ */
+export interface QueryGenConfig {
+  // Entity Filtering
+  // NOTE: includeEntities and excludeEntities are mutually exclusive
+  // - includeEntities: If provided, ONLY these entities will be processed (allowlist)
+  // - excludeEntities: If provided, these entities will be excluded from processing (denylist)
+  // - If both are provided, includeEntities takes precedence and excludeEntities is ignored
+  includeEntities: string[];
+  excludeEntities: string[];
+  excludeSchemas: string[];
+
+  // Entity Grouping
+  questionsPerGroup: number;
+  minGroupSize: number;        // Minimum entities per group
+  maxGroupSize: number;        // Maximum entities per group
+
+  // AI Configuration
+  modelOverride?: string;    // Override model for all prompts (e.g., "GPT-OSS-120B")
+  vendorOverride?: string;   // Override vendor for all prompts (e.g., "Groq")
+  embeddingModel: string;
+
+  // Iteration Limits
+  maxRefinementIterations: number;
+  maxFixingIterations: number;
+
+  // Few-Shot Learning
+  topSimilarQueries: number;
+
+  // Similarity Weighting
+  similarityWeights: {
+    userQuestion: number;
+    description: number;
+    technicalDescription: number;
+  };
+
+  // Output Configuration
+  outputMode: 'metadata' | 'database' | 'both';
+  outputDirectory: string;
+  outputCategoryDirectory?: string; // Optional: defaults to outputDirectory if not provided
+
+  // Query Category Configuration
+  rootQueryCategory: string;
+  autoCreateEntityQueryCategories: boolean;
+
+  // Performance
+  parallelGenerations: number;
+  enableCaching: boolean;
+
+  // Validation
+  testWithSampleData: boolean;
+  requireMinRows: number;
+  maxRefinementRows: number;
+
+  // Verbose Logging
+  verbose: boolean;
+}
+
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG: QueryGenConfig = {
+  includeEntities: [],
+  excludeEntities: [],
+  excludeSchemas: ['sys', 'INFORMATION_SCHEMA', '__mj'],
+  questionsPerGroup: 2,
+  minGroupSize: 2,              // Multi-entity groups have at least 2 entities
+  maxGroupSize: 3,              // Keep groups small for focused questions
+  embeddingModel: 'text-embedding-3-small',
+  maxRefinementIterations: 3,
+  maxFixingIterations: 5,
+  topSimilarQueries: 5,
+  similarityWeights: {
+    userQuestion: 0.2,
+    description: 0.40,
+    technicalDescription: 0.40,
+  },
+  outputMode: 'metadata',
+  outputDirectory: './metadata/queries',
+  rootQueryCategory: 'Auto-Generated',
+  autoCreateEntityQueryCategories: false,
+  parallelGenerations: 1,
+  enableCaching: true,
+  testWithSampleData: true,
+  requireMinRows: 0,
+  maxRefinementRows: 10,
+  verbose: false,
+};
+
+/**
+ * Load configuration from mj.config.cjs and merge with CLI options
+ *
+ * Configuration priority (highest to lowest):
+ * 1. CLI options (command line flags)
+ * 2. mj.config.cjs queryGen section
+ * 3. Default values
+ *
+ * @param cliOptions - Options provided via command line
+ * @returns Merged configuration ready for use
+ */
+export function loadConfig(cliOptions: Record<string, unknown>): QueryGenConfig {
+  // Start with defaults
+  const config: QueryGenConfig = { ...DEFAULT_CONFIG };
+
+  // Load mj.config.cjs if it exists
+  const mjConfig = loadMjConfig();
+  if (mjConfig && mjConfig.queryGen) {
+    Object.assign(config, mjConfig.queryGen);
+  }
+
+  // Override with CLI options
+  if (cliOptions.entities) {
+    config.includeEntities = parseArrayOption(cliOptions.entities);
+  }
+  if (cliOptions.excludeEntities) {
+    config.excludeEntities = parseArrayOption(cliOptions.excludeEntities);
+  }
+  if (cliOptions.excludeSchemas) {
+    config.excludeSchemas = parseArrayOption(cliOptions.excludeSchemas);
+  }
+  if (cliOptions.maxRefinements) {
+    config.maxRefinementIterations = parseNumberOption(cliOptions.maxRefinements, 'maxRefinements');
+  }
+  if (cliOptions.maxFixes) {
+    config.maxFixingIterations = parseNumberOption(cliOptions.maxFixes, 'maxFixes');
+  }
+  if (cliOptions.model) {
+    config.modelOverride = String(cliOptions.model);
+  }
+  if (cliOptions.vendor) {
+    config.vendorOverride = String(cliOptions.vendor);
+  }
+  if (cliOptions.output) {
+    config.outputDirectory = String(cliOptions.output);
+  }
+  if (cliOptions.mode) {
+    const mode = String(cliOptions.mode);
+    if (mode === 'metadata' || mode === 'database' || mode === 'both') {
+      config.outputMode = mode;
+    } else {
+      throw new Error(`Invalid output mode: ${mode}. Must be metadata, database, or both`);
+    }
+  }
+  if (cliOptions.verbose) {
+    config.verbose = true;
+  }
+
+  // Validate entity filtering (includeEntities and excludeEntities are mutually exclusive)
+  if (config.includeEntities.length > 0 && config.excludeEntities.length > 0) {
+    console.warn('[Warning] Both includeEntities and excludeEntities provided. includeEntities takes precedence, excludeEntities will be ignored.');
+    config.excludeEntities = [];
+  }
+
+  return config;
+}
+
+/**
+ * Load mj.config.cjs from current working directory
+ * Returns null if file doesn't exist or can't be loaded
+ */
+function loadMjConfig(): { queryGen?: Partial<QueryGenConfig> } | null {
+  try {
+    const configPath = require('path').join(process.cwd(), 'mj.config.cjs');
+    const fs = require('fs');
+    if (fs.existsSync(configPath)) {
+      return require(configPath);
+    }
+  } catch (error) {
+    // Config file doesn't exist or couldn't be loaded - not an error
+  }
+  return null;
+}
+
+/**
+ * Parse array option from CLI (handles both comma-separated strings and arrays)
+ */
+function parseArrayOption(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.map(String);
+  }
+  if (typeof value === 'string') {
+    return value.split(',').map(s => s.trim());
+  }
+  return [];
+}
+
+/**
+ * Parse number option from CLI with validation
+ */
+function parseNumberOption(value: unknown, name: string): number {
+  const num = Number(value);
+  if (isNaN(num) || num < 0) {
+    throw new Error(`Invalid ${name}: must be a positive number`);
+  }
+  return num;
+}

package/src/cli/index.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for QueryGen package
+ *
+ * Usage: mj-querygen <command> [options]
+ *
+ * Commands:
+ *   generate  - Generate queries for entities
+ *   validate  - Validate existing query templates
+ *   export    - Export queries from database to metadata files
+ */
+
+import { Command } from 'commander';
+import { generateCommand } from './commands/generate';
+import { validateCommand } from './commands/validate';
+import { exportCommand } from './commands/export';
+
+const packageJson = require('../../package.json');
+
+const program = new Command();
+
+program
+  .name('mj-querygen')
+  .description('AI-powered SQL query template generation for MemberJunction')
+  .version(packageJson.version);
+
+program
+  .command('generate')
+  .description('Generate queries for entities')
+  .option('-e, --entities <names...>', 'Specific entities to generate queries for')
+  .option('-x, --exclude-entities <names...>', 'Entities to exclude')
+  .option('-s, --exclude-schemas <names...>', 'Schemas to exclude')
+  .option('-m, --max-entities <number>', 'Max entities per group', '3')
+  .option('-r, --max-refinements <number>', 'Max refinement iterations', '3')
+  .option('-f, --max-fixes <number>', 'Max error-fixing attempts', '5')
+  .option('--model <name>', 'Preferred AI model')
+  .option('--vendor <name>', 'Preferred AI vendor')
+  .option('-o, --output <path>', 'Output directory')
+  .option('--mode <mode>', 'Output mode: metadata|database|both')
+  .option('-v, --verbose', 'Verbose output')
+  .action(generateCommand);
+
+program
+  .command('validate')
+  .description('Validate existing query templates')
+  .option('-p, --path <path>', 'Path to queries metadata file', './metadata/queries')
+  .option('-v, --verbose', 'Verbose output')
+  .action(validateCommand);
+
+program
+  .command('export')
+  .description('Export queries from database to metadata files')
+  .option('-o, --output <path>', 'Output directory')
+  .option('-v, --verbose', 'Verbose output')
+  .action(exportCommand);
+
+// Parse command line arguments
+program.parse();
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}