@sprig-and-prose/sprig-universe 0.1.0

package/src/validators/mysql/validator.js

@@ -0,0 +1,332 @@
+/**
+ * @fileoverview MySQL actor source validator
+ */
+
+import {
+  validateConnectionConfig,
+  getCachedConnection,
+  testConnection,
+  closeAllConnections,
+} from './connection.js';
+import { checkTableExists, getColumnMetadata } from './schema.js';
+import { checkTypeCompatibility } from './type-compat.js';
+
+/**
+ * Validates a MySQL source for an actor
+ * @param {Object} actor - Actor from manifest
+ * @param {Object} mysqlSource - MySQL source block from manifest
+ * @param {Object} connections - Connections config from sprig.config.json
+ * @returns {Promise<Array>} Array of validation errors (empty if valid)
+ */
+export async function validateMysqlSource(actor, mysqlSource, connections) {
+  const errors = [];
+  const connectionName = mysqlSource.connection;
+  const tableName = mysqlSource.table;
+  const sourceLocation = mysqlSource.location || actor.location;
+
+  // Step 1: Validate connection config
+  const configResult = validateConnectionConfig(connectionName, connections);
+  if (!configResult.valid) {
+    errors.push({
+      actorName: actor.name,
+      sourceKind: 'mysql',
+      path: connectionName,
+      message: configResult.error,
+      location: sourceLocation,
+      fieldName: '<root>',
+      errorKind: 'mysql.connection',
+      expected: `valid MySQL connection '${connectionName}'`,
+      actual: configResult.error,
+      schemaLocation: sourceLocation || actor.location,
+      occurrence: {
+        dataFile: connectionName,
+        recordIndex: null,
+      },
+    });
+    return errors; // Can't continue without valid config
+  }
+
+  const config = configResult.config;
+
+  // Step 2: Test database connection and get actual database name
+  let connection;
+  let actualSchema;
+  try {
+    connection = await getCachedConnection(connectionName, config);
+    const testResult = await testConnection(connection, config);
+    if (!testResult.success) {
+      const connectionInfo = `${config.host}:${config.port}/${config.database} (user: ${config.user})`;
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'mysql',
+        path: connectionName,
+        message: `Failed to connect to MySQL: ${testResult.error}`,
+        location: sourceLocation,
+        fieldName: '<root>',
+        errorKind: 'mysql.connection',
+        expected: `successful connection to ${connectionInfo}`,
+        actual: testResult.error,
+        schemaLocation: sourceLocation || actor.location,
+        occurrence: {
+          dataFile: connectionName,
+          recordIndex: null,
+        },
+      });
+      return errors; // Can't continue without connection
+    }
+    // Get the actual database name from the connection (handles case sensitivity)
+    actualSchema = testResult.databaseName || config.database;
+  } catch (error) {
+    const connectionInfo = `${config.host}:${config.port}/${config.database} (user: ${config.user})`;
+    errors.push({
+      actorName: actor.name,
+      sourceKind: 'mysql',
+      path: connectionName,
+      message: `Failed to connect to MySQL: ${error.message}`,
+      location: sourceLocation,
+      fieldName: '<root>',
+      errorKind: 'mysql.connection',
+      expected: `successful connection to ${connectionInfo}`,
+      actual: error.message,
+      schemaLocation: sourceLocation || actor.location,
+      occurrence: {
+        dataFile: connectionName,
+        recordIndex: null,
+      },
+    });
+    return errors;
+  }
+
+  // Step 3: Check table exists
+  let tableExists;
+  try {
+    tableExists = await checkTableExists(connection, actualSchema, tableName);
+  } catch (error) {
+    errors.push({
+      actorName: actor.name,
+      sourceKind: 'mysql',
+      path: tableName,
+      message: `Failed to check table existence: ${error.message}`,
+      location: sourceLocation,
+      fieldName: '<root>',
+      errorKind: 'mysql.tableExists',
+      expected: `table '${tableName}' exists in schema '${actualSchema}'`,
+      actual: `error: ${error.message}`,
+      schemaLocation: sourceLocation || actor.location,
+      occurrence: {
+        dataFile: `${actualSchema}.${tableName}`,
+        recordIndex: null,
+      },
+    });
+    return errors;
+  }
+
+  if (!tableExists) {
+    errors.push({
+      actorName: actor.name,
+      sourceKind: 'mysql',
+      path: tableName,
+      message: `Table '${tableName}' does not exist in schema '${actualSchema}'`,
+      location: sourceLocation,
+      fieldName: '<root>',
+      errorKind: 'mysql.tableExists',
+      expected: `table '${tableName}' exists in schema '${actualSchema}'`,
+      actual: 'table not found',
+      schemaLocation: sourceLocation || actor.location,
+      occurrence: {
+        dataFile: `${actualSchema}.${tableName}`,
+        recordIndex: null,
+      },
+    });
+    return errors; // Can't continue without table
+  }
+
+  // Step 4: Get column metadata
+  let columnMetadata;
+  try {
+    columnMetadata = await getColumnMetadata(connection, actualSchema, tableName, connectionName);
+    
+    // If table exists but no columns found, this indicates a problem
+    if (columnMetadata.size === 0) {
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'mysql',
+        path: tableName,
+        message: `Table '${tableName}' exists but no columns found in schema '${actualSchema}'. This may indicate a permissions issue or schema mismatch.`,
+        location: sourceLocation,
+        fieldName: '<root>',
+        errorKind: 'mysql.columns',
+        expected: `column metadata for table '${tableName}' in schema '${actualSchema}'`,
+        actual: '0 columns found',
+        schemaLocation: sourceLocation || actor.location,
+        occurrence: {
+          dataFile: `${actualSchema}.${tableName}`,
+          recordIndex: null,
+        },
+        hint: 'Verify the table exists and you have SELECT permissions on information_schema.columns',
+      });
+      return errors;
+    }
+  } catch (error) {
+    errors.push({
+      actorName: actor.name,
+      sourceKind: 'mysql',
+      path: tableName,
+      message: `Failed to get column metadata: ${error.message}`,
+      location: sourceLocation,
+      fieldName: '<root>',
+      errorKind: 'mysql.columns',
+      expected: `column metadata for table '${tableName}'`,
+      actual: `error: ${error.message}`,
+      schemaLocation: sourceLocation || actor.location,
+      occurrence: {
+        dataFile: `${actualSchema}.${tableName}`,
+        recordIndex: null,
+      },
+    });
+    return errors;
+  }
+
+  // Step 5: Validate each field
+  const typeFields = actor.type?.fields || [];
+  for (const field of typeFields) {
+    const fieldName = field.name;
+    const fieldType = field.type;
+    const fieldLocation = field.location || sourceLocation;
+
+    // Skip nested objects for v1 (emit warning)
+    if (fieldType && (fieldType.kind === 'object' || fieldType.kind === 'reference')) {
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'mysql',
+        path: tableName,
+        message: `Field '${fieldName}' is a nested object (not validated for mysql yet)`,
+        location: fieldLocation,
+        fieldName: fieldName,
+        errorKind: 'mysql.columns',
+        expected: 'nested object validation (not implemented in v1)',
+        actual: 'skipped',
+        schemaLocation: fieldLocation || actor.location,
+        occurrence: {
+          dataFile: `${actualSchema}.${tableName}`,
+          recordIndex: null,
+        },
+        hint: 'Nested object validation for MySQL is not yet implemented',
+      });
+      continue;
+    }
+
+    // Check column exists (case-insensitive lookup)
+    let columnMeta = columnMetadata.get(fieldName);
+    
+    // If not found, try case-insensitive lookup
+    if (!columnMeta && columnMetadata._lowerToOriginal) {
+      const lowerName = fieldName.toLowerCase();
+      const originalName = columnMetadata._lowerToOriginal.get(lowerName);
+      if (originalName) {
+        columnMeta = columnMetadata.get(originalName);
+      }
+    }
+    
+    if (!columnMeta) {
+      // Get list of available columns for better error message
+      const availableColumns = Array.from(columnMetadata.keys())
+        .filter(k => typeof k === 'string' && !k.startsWith('__lower__'))
+        .join(', ');
+      
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'mysql',
+        path: tableName,
+        message: `Missing column '${fieldName}' in table '${tableName}'. Available columns: ${availableColumns || '(none)'}`,
+        location: fieldLocation,
+        fieldName: fieldName,
+        errorKind: 'mysql.missingColumn',
+        expected: `column '${fieldName}' exists`,
+        actual: `column not found. Available: ${availableColumns || '(none)'}`,
+        schemaLocation: fieldLocation || actor.location,
+        occurrence: {
+          dataFile: `${actualSchema}.${tableName}`,
+          recordIndex: null,
+        },
+      });
+      continue;
+    }
+
+    // Check nullability compatibility (informational warning)
+    const isNullable = columnMeta.is_nullable === 'YES';
+    const isOptional = !field.required;
+
+    if (!isOptional && isNullable) {
+      // Required field but column is nullable - structural warning
+      // The database schema does not enforce the required constraint
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'mysql',
+        path: tableName,
+        message: `Database column '${fieldName}' is nullable but prose requires this field (DB does not enforce required field)`,
+        location: fieldLocation,
+        fieldName: fieldName,
+        errorKind: 'mysql.nullability',
+        severity: 'warning',
+        expected: 'required (NOT NULL)',
+        actual: 'nullable (NULL allowed)',
+        schemaLocation: fieldLocation || actor.location,
+        occurrence: {
+          dataFile: `${actualSchema}.${tableName}`,
+          recordIndex: null,
+        },
+        hint: 'The database allows NULLs for this field. If you rely on this field being present, consider enforcing NOT NULL after any backfill or migration.',
+      });
+    }
+
+    // Check type compatibility
+    const typeResult = checkTypeCompatibility(fieldType, columnMeta);
+    if (!typeResult.compatible) {
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'mysql',
+        path: tableName,
+        message: `Column '${fieldName}' type mismatch: ${typeResult.message}`,
+        location: fieldLocation,
+        fieldName: fieldName,
+        errorKind: 'mysql.typeMismatch',
+        expected: field.typeExpr || 'compatible type',
+        actual: columnMeta.column_type,
+        schemaLocation: fieldLocation || actor.location,
+        occurrence: {
+          dataFile: `${actualSchema}.${tableName}`,
+          recordIndex: null,
+        },
+      });
+    } else if (typeResult.severity === 'warning' && typeResult.message) {
+      // Add warning-level errors for type compatibility warnings
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'mysql',
+        path: tableName,
+        message: `Column '${fieldName}' type compatibility: ${typeResult.message}`,
+        location: fieldLocation,
+        fieldName: fieldName,
+        errorKind: 'mysql.typeMismatch',
+        expected: field.typeExpr || 'compatible type',
+        actual: columnMeta.column_type,
+        schemaLocation: fieldLocation || actor.location,
+        occurrence: {
+          dataFile: `${actualSchema}.${tableName}`,
+          recordIndex: null,
+        },
+        hint: typeResult.message,
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Cleanup function to close all connections
+ * Should be called after validation is complete
+ */
+export { closeAllConnections };
+

package/test/fixtures/amaranthine-mini.prose

@@ -0,0 +1,53 @@
+universe Amaranthine {
+  describe {
+    Amaranthine is a persistent text-based roleplaying game. At its core, it is
+    a semi-afk game where you can do any of the twelve in-game skills and
+    progress your character.
+  }
+
+  series Player {
+    describe {
+      The player is central to everything. From chat to skills to inventory,
+      nearly everything is based around the player.
+    }
+
+    references {
+      reference {
+        repository { 'amaranthine' }
+        paths { '/backends/api/src/routers/players.js' }
+      }
+    }
+  }
+
+  series Item {
+    describe {
+      Items are physical objects in the game that players can interact with.
+    }
+
+    references {
+      reference {
+        repository { 'amaranthine' }
+        paths { '/data/items/*.yaml' }
+      }
+    }
+  }
+
+  book Equipment in Item {
+    describe {
+      Equipment is a category of items that are used to equip a player.
+    }
+  }
+
+  book Resource in Item {
+    describe {
+      Resources are items that are used to create other items.
+    }
+  }
+
+  chapter Tool in Equipment {
+    describe {
+      Tools are categories of items that are used to perform a task.
+    }
+  }
+}
+

package/test/fixtures/conflicting-universes-a.prose

@@ -0,0 +1,8 @@
+universe Amaranthine {
+  series Items {
+    describe {
+      Items are objects.
+    }
+  }
+}
+

package/test/fixtures/conflicting-universes-b.prose

@@ -0,0 +1,8 @@
+universe OtherUniverse {
+  series Skills {
+    describe {
+      Skills are abilities.
+    }
+  }
+}
+

package/test/fixtures/duplicate-names.prose

@@ -0,0 +1,20 @@
+universe Test {
+  series Duplicate {
+    describe { First occurrence }
+  }
+
+  -- This is a duplicate name
+  series Duplicate {
+    describe { Second occurrence }
+  }
+
+  book Book1 in Duplicate {
+    describe { Book 1 }
+  }
+
+  -- Another duplicate (different kind, but same name)
+  book Book1 in Duplicate {
+    describe { Book 1 duplicate }
+  }
+}
+

package/test/fixtures/first-line-aware.prose

@@ -0,0 +1,32 @@
+universe Test {
+  describe {
+    This is a test universe
+    with multiple lines
+      and indented content
+    that should be dedented.
+  }
+
+  series Example {
+    describe {
+      This describe block
+        has leading indentation
+      that should be removed
+    but internal indentation preserved.
+    }
+  }
+
+  book SingleLine in Example {
+    describe {
+      Single line describe should remain unchanged.
+    }
+  }
+
+  book AllIndented in Example {
+    describe {
+      All lines
+        are indented
+          consistently
+    }
+  }
+}
+

package/test/fixtures/indented-describe.prose

@@ -0,0 +1,18 @@
+universe Test {
+  describe {
+    This is a test universe
+    with multiple lines
+      and indented content
+    that should be dedented.
+  }
+
+  series Example {
+    describe {
+        This describe block
+          has leading indentation
+        that should be removed
+      but internal indentation preserved.
+    }
+  }
+}
+

package/test/fixtures/multi-file-universe-a.prose

@@ -0,0 +1,15 @@
+universe Amaranthine {
+  series Items {
+    describe {
+      Items are objects that can exist in the world.
+    }
+  }
+
+  references {
+    reference {
+      repository { 'amaranthine' }
+      paths { '/data/items.yaml' }
+    }
+  }
+}
+

package/test/fixtures/multi-file-universe-b.prose

@@ -0,0 +1,15 @@
+universe Amaranthine {
+  series Skills {
+    describe {
+      Skills represent abilities that players can learn.
+    }
+  }
+
+  references {
+    reference {
+      repository { 'amaranthine' }
+      paths { '/data/skills.yaml' }
+    }
+  }
+}
+

package/test/fixtures/multi-file-universe-conflict-desc.prose

@@ -0,0 +1,12 @@
+universe Amaranthine {
+  describe {
+    This is a conflicting describe block.
+  }
+
+  series Conflict {
+    describe {
+      This series should still work.
+    }
+  }
+}
+

package/test/fixtures/multi-file-universe-conflict-title.prose

@@ -0,0 +1,4 @@
+universe Amaranthine {
+  title { Conflicting Title }
+}
+

package/test/fixtures/multi-file-universe-with-title.prose

@@ -0,0 +1,10 @@
+universe Amaranthine {
+  title { Amaranthine Universe }
+  
+  series Items {
+    describe {
+      Items are objects.
+    }
+  }
+}
+

package/test/fixtures/named-document.prose

@@ -0,0 +1,17 @@
+universe Test {
+  document ItemsDesignDoc {
+    kind { 'internal' }
+    path { '/docs/items/overview.md' }
+    describe { High-level items design notes. }
+  }
+
+  series Items {
+    documentation {
+      document {
+        kind { 'internal' }
+        path { '/docs/items/details.md' }
+      }
+    }
+  }
+}
+

package/test/fixtures/named-duplicate.prose

@@ -0,0 +1,22 @@
+universe Test {
+  reference ItemRouter {
+    repository { 'amaranthine-backend' }
+    paths { '/src/routers/items.ts' }
+  }
+
+  reference ItemRouter {
+    repository { 'amaranthine-backend' }
+    paths { '/src/routers/items-v2.ts' }
+  }
+
+  document ItemsDesignDoc {
+    kind { 'internal' }
+    path { '/docs/items/overview.md' }
+  }
+
+  document ItemsDesignDoc {
+    kind { 'public' }
+    path { '/docs/items/public-overview.md' }
+  }
+}
+

package/test/fixtures/named-reference.prose

@@ -0,0 +1,17 @@
+universe Test {
+  reference ItemRouter {
+    repository { 'amaranthine-backend' }
+    paths { '/src/routers/items.ts' }
+    describe { Routes that implement item endpoints. }
+  }
+
+  series Items {
+    references {
+      reference {
+        repository { 'amaranthine-backend' }
+        paths { '/src/items/helpers.ts' }
+      }
+    }
+  }
+}
+

package/test/fixtures/relates-errors.prose

@@ -0,0 +1,38 @@
+universe Test {
+  series Item {
+    describe { Items are physical objects in the game. }
+  }
+
+  series Action {
+    describe { Actions are things players can do. }
+  }
+
+  -- Unknown endpoint
+  relates Unknown and Item {
+    describe { This should produce a warning. }
+  }
+
+  -- Invalid from endpoint
+  relates Item and Action {
+    from Tool {
+      relationships { 'invalid' }
+    }
+  }
+
+  -- Duplicate describe
+  relates Item and Action {
+    describe { First describe. }
+    describe { Second describe. }
+  }
+
+  -- Duplicate from
+  relates Item and Action {
+    from Item {
+      relationships { 'first' }
+    }
+    from Item {
+      relationships { 'second' }
+    }
+  }
+}
+

package/test/fixtures/relates-tier1.prose

@@ -0,0 +1,14 @@
+universe Test {
+  series Item {
+    describe { Items are physical objects in the game. }
+  }
+
+  series Action {
+    describe { Actions are things players can do. }
+  }
+
+  relates Item and Action {
+    describe { Items can be consumed by actions and can also be produced by actions. }
+  }
+}
+

package/test/fixtures/relates-tier2.prose

@@ -0,0 +1,16 @@
+universe Test {
+  series Item {
+    describe { Items are physical objects in the game. }
+  }
+
+  series Action {
+    describe { Actions are things players can do. }
+  }
+
+  relates Item and Action {
+    from Item { relationships { 'used in' } }
+    from Action { relationships { 'produces and consumes' } }
+    describe { Items can be consumed by actions and can also be produced by actions. }
+  }
+}
+

package/test/fixtures/relates-tier3.prose

@@ -0,0 +1,21 @@
+universe Test {
+  series Item {
+    describe { Items are physical objects in the game. }
+  }
+
+  series Action {
+    describe { Actions are things players can do. }
+  }
+
+  relates Item and Action {
+    from Item {
+      relationships { 'produced by', 'consumed by', }
+      describe { Items can be produced by and consumed by actions. }
+    }
+    from Action {
+      relationships { 'produces', 'consumes' }
+      describe { Actions can produce and consume items. }
+    }
+  }
+}
+