@sprig-and-prose/sprig-universe 0.1.0

package/src/validators/mysql/connection.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview MySQL connection validation and management
+ */
+
+import mysql from 'mysql2/promise';
+import { clearColumnMetadataCache } from './schema.js';
+
+/**
+ * Validates connection configuration exists and has required fields
+ * @param {string} connectionName - Name of the connection
+ * @param {Object} connections - Connections config from sprig.config.json
+ * @returns {{ valid: boolean, config?: Object, error?: string }} Validation result
+ */
+export function validateConnectionConfig(connectionName, connections) {
+  if (!connections || typeof connections !== 'object') {
+    return {
+      valid: false,
+      error: `No connections configured in sprig.config.json`,
+    };
+  }
+
+  const config = connections[connectionName];
+  if (!config) {
+    return {
+      valid: false,
+      error: `Connection '${connectionName}' not found in connections config`,
+    };
+  }
+
+  if (config.provider !== 'mysql') {
+    return {
+      valid: false,
+      error: `Connection '${connectionName}' has provider '${config.provider}', expected 'mysql'`,
+    };
+  }
+
+  const requiredFields = ['host', 'port', 'database', 'user'];
+  const missingFields = requiredFields.filter((field) => !(field in config));
+
+  if (missingFields.length > 0) {
+    return {
+      valid: false,
+      error: `Connection '${connectionName}' missing required fields: ${missingFields.join(', ')}`,
+    };
+  }
+
+  return {
+    valid: true,
+    config,
+  };
+}
+
+/**
+ * Creates a MySQL connection from config
+ * @param {Object} config - MySQL connection config
+ * @returns {Promise<mysql.Connection>} MySQL connection
+ */
+export async function createConnection(config) {
+  const connectionConfig = {
+    host: config.host,
+    port: config.port,
+    database: config.database,
+    user: config.user,
+    password: config.password,
+    // Enable multiple statements if needed
+    multipleStatements: false,
+  };
+
+  try {
+    const connection = await mysql.createConnection(connectionConfig);
+    return connection;
+  } catch (error) {
+    // Never include password in error messages
+    const connectionInfo = `${config.host}:${config.port}/${config.database} (user: ${config.user})`;
+    throw new Error(
+      `Failed to connect to MySQL at ${connectionInfo}: ${error.code || error.message}`,
+    );
+  }
+}
+
+/**
+ * Tests database connection and verifies information_schema access
+ * @param {mysql.Connection} connection - MySQL connection
+ * @param {Object} config - Connection config (for error messages)
+ * @returns {Promise<{ success: boolean, error?: string, databaseName?: string }>} Test result
+ */
+export async function testConnection(connection, config) {
+  try {
+    // Test basic connectivity with SELECT DATABASE()
+    const [rows] = await connection.execute('SELECT DATABASE() as db');
+    const databaseName = rows[0]?.db;
+
+    // Verify information_schema access
+    const [schemaRows] = await connection.execute(
+      'SELECT 1 FROM information_schema.tables LIMIT 1',
+    );
+
+    if (schemaRows.length === 0) {
+      return {
+        success: false,
+        error: 'Cannot access information_schema (permissions issue)',
+      };
+    }
+
+    return {
+      success: true,
+      databaseName,
+    };
+  } catch (error) {
+    const connectionInfo = `${config.host}:${config.port}/${config.database} (user: ${config.user})`;
+    return {
+      success: false,
+      error: `Connection test failed: ${error.code || error.message}`,
+    };
+  }
+}
+
+/**
+ * Connection cache for reuse during validation
+ */
+const connectionCache = new Map();
+
+/**
+ * Gets or creates a cached connection
+ * @param {string} connectionName - Connection name
+ * @param {Object} config - Connection config
+ * @returns {Promise<mysql.Connection>} MySQL connection
+ */
+export async function getCachedConnection(connectionName, config) {
+  if (connectionCache.has(connectionName)) {
+    return connectionCache.get(connectionName);
+  }
+
+  const connection = await createConnection(config);
+  connectionCache.set(connectionName, connection);
+  return connection;
+}
+
+/**
+ * Closes all cached connections
+ */
+export async function closeAllConnections() {
+  for (const [name, connection] of connectionCache.entries()) {
+    try {
+      await connection.end();
+    } catch (error) {
+      // Ignore errors during cleanup
+    }
+  }
+  connectionCache.clear();
+  // Also clear column metadata cache
+  clearColumnMetadataCache();
+}
+

package/src/validators/mysql/schema.js

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview MySQL schema introspection using information_schema
+ */
+
+/**
+ * Column metadata cache for reuse during validation
+ * Key format: `${connectionName}|${database}|${table}`
+ */
+const columnMetadataCache = new Map();
+
+/**
+ * Checks if a table exists in the database
+ * @param {import('mysql2/promise').Connection} connection - MySQL connection
+ * @param {string} schema - Database schema name
+ * @param {string} table - Table name
+ * @returns {Promise<boolean>} True if table exists
+ */
+export async function checkTableExists(connection, schema, table) {
+  try {
+    // First, try to get the actual database name from the connection
+    // This handles case sensitivity issues
+    let actualSchema = schema;
+    try {
+      const [dbRows] = await connection.execute('SELECT DATABASE() as db');
+      if (dbRows.length > 0 && dbRows[0].db) {
+        actualSchema = dbRows[0].db;
+      }
+    } catch {
+      // If DATABASE() fails, fall back to provided schema
+    }
+
+    const [rows] = await connection.execute(
+      'SELECT 1 FROM information_schema.tables WHERE table_schema = ? AND table_name = ? LIMIT 1',
+      [actualSchema, table],
+    );
+    return rows.length > 0;
+  } catch (error) {
+    throw new Error(`Failed to check table existence: ${error.message}`);
+  }
+}
+
+/**
+ * @typedef {Object} ColumnMetadata
+ * @property {string} column_name
+ * @property {string} data_type - MySQL data type (e.g., 'int', 'varchar', 'enum')
+ * @property {string} column_type - Full column type (e.g., "int(11)", "enum('a','b')")
+ * @property {string} is_nullable - 'YES' or 'NO'
+ * @property {number|null} character_maximum_length
+ * @property {number|null} numeric_precision
+ * @property {number|null} numeric_scale
+ */
+
+/**
+ * Gets column metadata for a table
+ * @param {import('mysql2/promise').Connection} connection - MySQL connection
+ * @param {string} schema - Database schema name
+ * @param {string} table - Table name
+ * @param {string} connectionName - Connection name for caching
+ * @returns {Promise<Map<string, ColumnMetadata>>} Map of column name to metadata
+ */
+export async function getColumnMetadata(connection, schema, table, connectionName) {
+  try {
+    // First, try to get the actual database name from the connection
+    // This handles case sensitivity issues
+    let actualSchema = schema;
+    try {
+      const [dbRows] = await connection.execute('SELECT DATABASE() as db');
+      if (dbRows.length > 0 && dbRows[0].db) {
+        actualSchema = dbRows[0].db;
+      }
+    } catch {
+      // If DATABASE() fails, fall back to provided schema
+    }
+
+    // Check cache first
+    const cacheKey = `${connectionName}|${actualSchema}|${table}`;
+    if (columnMetadataCache.has(cacheKey)) {
+      return columnMetadataCache.get(cacheKey);
+    }
+
+    const [rows] = await connection.execute(
+      `SELECT 
+        column_name,
+        data_type,
+        column_type,
+        is_nullable,
+        character_maximum_length,
+        numeric_precision,
+        numeric_scale
+      FROM information_schema.columns
+      WHERE table_schema = ? AND table_name = ?
+      ORDER BY ordinal_position`,
+      [actualSchema, table],
+    );
+
+    // Create a case-insensitive map by storing both original and lowercase keys
+    const columnMap = new Map();
+    const lowerToOriginal = new Map(); // Track original case for each lowercase name
+    
+    for (const row of rows) {
+      // MySQL returns column names in uppercase (COLUMN_NAME) or lowercase (column_name)
+      // depending on version/config, so handle both
+      const originalName = row.column_name || row.COLUMN_NAME;
+      
+      // Skip rows with missing column_name
+      if (!originalName || typeof originalName !== 'string') {
+        continue;
+      }
+      
+      const lowerName = originalName.toLowerCase();
+      
+      // Store metadata with original column name
+      // Handle both uppercase and lowercase column names from MySQL
+      const metadata = {
+        column_name: originalName,
+        data_type: row.data_type || row.DATA_TYPE,
+        column_type: row.column_type || row.COLUMN_TYPE,
+        is_nullable: row.is_nullable || row.IS_NULLABLE,
+        character_maximum_length: row.character_maximum_length || row.CHARACTER_MAXIMUM_LENGTH,
+        numeric_precision: row.numeric_precision || row.NUMERIC_PRECISION,
+        numeric_scale: row.numeric_scale || row.NUMERIC_SCALE,
+      };
+      
+      // Store with original case as primary key
+      columnMap.set(originalName, metadata);
+      
+      // Track lowercase mapping for case-insensitive lookup
+      if (!lowerToOriginal.has(lowerName)) {
+        lowerToOriginal.set(lowerName, originalName);
+      }
+    }
+
+    // Store the lowercase mapping on the map for later use
+    columnMap._lowerToOriginal = lowerToOriginal;
+
+    // Cache the result
+    columnMetadataCache.set(cacheKey, columnMap);
+
+    return columnMap;
+  } catch (error) {
+    throw new Error(`Failed to get column metadata: ${error.message}`);
+  }
+}
+
+/**
+ * Clears the column metadata cache
+ * Should be called after validation is complete
+ */
+export function clearColumnMetadataCache() {
+  columnMetadataCache.clear();
+}
+
+/**
+ * Parses ENUM values from column_type string
+ * @param {string} columnType - Column type string like "enum('player','playerpaperdoll')"
+ * @returns {string[]|null} Array of enum values or null if not an enum
+ */
+export function parseEnumValues(columnType) {
+  if (!columnType || typeof columnType !== 'string') {
+    return null;
+  }
+
+  const enumMatch = columnType.match(/^enum\s*\((.+)\)$/i);
+  if (!enumMatch) {
+    return null;
+  }
+
+  const valuesStr = enumMatch[1];
+  // Parse quoted values: 'value1','value2' or "value1","value2"
+  const values = [];
+  let current = '';
+  let inQuotes = false;
+  let quoteChar = null;
+
+  for (let i = 0; i < valuesStr.length; i++) {
+    const char = valuesStr[i];
+
+    if (!inQuotes && (char === "'" || char === '"')) {
+      inQuotes = true;
+      quoteChar = char;
+    } else if (inQuotes && char === quoteChar) {
+      // Check if it's escaped
+      if (i + 1 < valuesStr.length && valuesStr[i + 1] === quoteChar) {
+        current += char;
+        i++; // Skip next quote
+      } else {
+        inQuotes = false;
+        quoteChar = null;
+        if (current) {
+          values.push(current);
+          current = '';
+        }
+      }
+    } else if (inQuotes) {
+      current += char;
+    } else if (char === ',' || char === ' ') {
+      // Skip commas and spaces outside quotes
+      continue;
+    }
+  }
+
+  // Handle last value if no trailing comma
+  if (current) {
+    values.push(current);
+  }
+
+  return values.length > 0 ? values : null;
+}
+

package/src/validators/mysql/type-compat.js

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview Type compatibility checking between Sprig types and MySQL column types
+ */
+
+import { parseEnumValues } from './schema.js';
+
+/**
+ * @typedef {Object} TypeCompatibilityResult
+ * @property {boolean} compatible - Whether types are compatible
+ * @property {'error'|'warning'|'info'} severity - Severity if incompatible
+ * @property {string} message - Human-readable message
+ */
+
+/**
+ * Checks if a Sprig integer type is compatible with MySQL column type
+ * @param {Object} columnMeta - Column metadata
+ * @returns {TypeCompatibilityResult}
+ */
+function checkIntegerCompatibility(columnMeta) {
+  const integerTypes = ['tinyint', 'smallint', 'mediumint', 'int', 'bigint'];
+  const dataType = columnMeta.data_type.toLowerCase();
+
+  if (integerTypes.includes(dataType)) {
+    return { compatible: true, severity: 'info', message: '' };
+  }
+
+  // Check for decimal/numeric with scale 0
+  if (dataType === 'decimal' || dataType === 'numeric') {
+    if (columnMeta.numeric_scale === 0) {
+      return {
+        compatible: true,
+        severity: 'warning',
+        message: `Column is ${dataType} with scale 0 (acceptable for integer)`,
+      };
+    }
+    return {
+      compatible: false,
+      severity: 'error',
+      message: `Column is ${dataType} with scale ${columnMeta.numeric_scale} (expected integer type)`,
+    };
+  }
+
+  return {
+    compatible: false,
+    severity: 'error',
+    message: `Column type '${columnMeta.data_type}' is not compatible with integer (expected: tinyint, smallint, mediumint, int, bigint)`,
+  };
+}
+
+/**
+ * Checks if a Sprig string oneOf type is compatible with MySQL column type
+ * @param {Object} fieldType - Sprig field type AST (oneOf with string values)
+ * @param {Object} columnMeta - Column metadata
+ * @returns {TypeCompatibilityResult}
+ */
+function checkStringOneOfCompatibility(fieldType, columnMeta) {
+  const dataType = columnMeta.data_type.toLowerCase();
+  const stringTypes = ['varchar', 'char', 'text', 'tinytext', 'mediumtext', 'longtext'];
+
+  // Best case: ENUM type
+  if (dataType === 'enum') {
+    const enumValues = parseEnumValues(columnMeta.column_type);
+    if (enumValues) {
+      // Check if all field values are in enum
+      const missingValues = fieldType.values.filter(
+        (val) => !enumValues.includes(String(val)),
+      );
+      if (missingValues.length === 0) {
+        return {
+          compatible: true,
+          severity: 'info',
+          message: `ENUM contains all required values`,
+        };
+      }
+      return {
+        compatible: true,
+        severity: 'warning',
+        message: `ENUM missing values: ${missingValues.join(', ')}`,
+      };
+    }
+  }
+
+  // Acceptable: string types
+  if (stringTypes.includes(dataType)) {
+    return {
+      compatible: true,
+      severity: 'info',
+      message: `Column is ${dataType} (acceptable for string one-of)`,
+    };
+  }
+
+  return {
+    compatible: false,
+    severity: 'error',
+    message: `Column type '${columnMeta.data_type}' is not compatible with string one-of (expected: enum, varchar, char, or text types)`,
+  };
+}
+
+/**
+ * Checks if a Sprig numeric oneOf type is compatible with MySQL column type
+ * @param {Object} fieldType - Sprig field type AST (oneOf with numeric values)
+ * @param {Object} columnMeta - Column metadata
+ * @returns {TypeCompatibilityResult}
+ */
+function checkNumericOneOfCompatibility(fieldType, columnMeta) {
+  const dataType = columnMeta.data_type.toLowerCase();
+  const integerTypes = ['tinyint', 'smallint', 'mediumint', 'int', 'bigint'];
+  const stringTypes = ['varchar', 'char', 'text'];
+
+  // Best case: integer types
+  if (integerTypes.includes(dataType)) {
+    return { compatible: true, severity: 'info', message: '' };
+  }
+
+  // Acceptable but warn: ENUM
+  if (dataType === 'enum') {
+    return {
+      compatible: true,
+      severity: 'warning',
+      message: `Column is ENUM (acceptable but numeric one-of stored as enum)`,
+    };
+  }
+
+  // Warn: string types (numeric enum stored as string)
+  if (stringTypes.includes(dataType)) {
+    return {
+      compatible: true,
+      severity: 'warning',
+      message: `Column is ${dataType} but prose expects numeric one-of (numeric enum stored as string)`,
+    };
+  }
+
+  return {
+    compatible: false,
+    severity: 'error',
+    message: `Column type '${columnMeta.data_type}' is not compatible with numeric one-of (expected: integer types)`,
+  };
+}
+
+/**
+ * Checks type compatibility between Sprig field type and MySQL column
+ * @param {Object} fieldType - Sprig field type AST
+ * @param {Object} columnMeta - MySQL column metadata
+ * @returns {TypeCompatibilityResult}
+ */
+export function checkTypeCompatibility(fieldType, columnMeta) {
+  if (!fieldType || !columnMeta) {
+    return {
+      compatible: false,
+      severity: 'error',
+      message: 'Missing field type or column metadata',
+    };
+  }
+
+  // Handle optional wrapper
+  if (fieldType.kind === 'optional') {
+    const innerResult = checkTypeCompatibility(fieldType.of, columnMeta);
+    // Keep compatibility but preserve severity
+    return innerResult;
+  }
+
+  // Handle primitive types
+  if (fieldType.kind === 'primitive') {
+    if (fieldType.name === 'integer') {
+      return checkIntegerCompatibility(columnMeta);
+    }
+    if (fieldType.name === 'string') {
+      const stringTypes = ['varchar', 'char', 'text', 'tinytext', 'mediumtext', 'longtext'];
+      const dataType = columnMeta.data_type.toLowerCase();
+      if (stringTypes.includes(dataType)) {
+        return { compatible: true, severity: 'info', message: '' };
+      }
+      return {
+        compatible: false,
+        severity: 'error',
+        message: `Column type '${columnMeta.data_type}' is not compatible with string (expected: varchar, char, or text types)`,
+      };
+    }
+    if (fieldType.name === 'float' || fieldType.name === 'double' || fieldType.name === 'number') {
+      const floatTypes = ['float', 'double', 'decimal', 'numeric'];
+      const dataType = columnMeta.data_type.toLowerCase();
+      if (floatTypes.includes(dataType)) {
+        return { compatible: true, severity: 'info', message: '' };
+      }
+      return {
+        compatible: false,
+        severity: 'error',
+        message: `Column type '${columnMeta.data_type}' is not compatible with ${fieldType.name} (expected: float, double, decimal, or numeric)`,
+      };
+    }
+    // Unknown primitive - skip validation
+    return { compatible: true, severity: 'info', message: '' };
+  }
+
+  // Handle oneOf types
+  if (fieldType.kind === 'oneOf') {
+    if (fieldType.valueType === 'string') {
+      return checkStringOneOfCompatibility(fieldType, columnMeta);
+    }
+    if (fieldType.valueType === 'number') {
+      return checkNumericOneOfCompatibility(fieldType, columnMeta);
+    }
+    // Unknown value type
+    return { compatible: true, severity: 'info', message: '' };
+  }
+
+  // Handle nested objects - skip for v1
+  if (fieldType.kind === 'object' || fieldType.kind === 'reference') {
+    return {
+      compatible: true,
+      severity: 'warning',
+      message: 'Nested object not validated for mysql yet',
+    };
+  }
+
+  // Unknown type kind - skip validation
+  return { compatible: true, severity: 'info', message: '' };
+}
+