pg-migration-engine 0.1.0

package/src/differ/schema-differ.js

@@ -0,0 +1,309 @@
+import crypto from 'crypto';
+import { ObjectMatcher } from './object-matcher.js';
+import { PropertyDiffer } from './property-differ.js';
+import { DependencyResolver } from './dependency-resolver.js';
+import { ChangeClassifier } from './change-classifier.js';
+import { RiskTagger } from './risk-tagger.js';
+
+/**
+ * Schema Differ - Main orchestrator for comparing two schema snapshots.
+ * Produces a complete SchemaDiff with all changes, properly ordered and classified.
+ */
+
+export class SchemaDiffer {
+  constructor(options = {}) {
+    this.pgVersion = options.pgVersion || 150000;
+    this.objectMatcher = new ObjectMatcher();
+    this.propertyDiffer = new PropertyDiffer();
+    this.dependencyResolver = new DependencyResolver();
+    this.changeClassifier = new ChangeClassifier();
+    this.riskTagger = new RiskTagger(this.pgVersion);
+  }
+
+  /**
+   * Diff two schema snapshots (desired vs current).
+   * @param {Object} desired - The desired/target schema
+   * @param {Object} current - The current/live schema
+   * @returns {Object} SchemaDiff
+   */
+  diff(desired, current) {
+    const startTime = Date.now();
+    const allChanges = [];
+
+    // Step 1: Match objects between snapshots
+    const matched = this.objectMatcher.match(desired, current);
+
+    // Step 2: Handle creates (objects only in desired)
+    for (const create of matched.creates) {
+      allChanges.push(this.createChangeObject('CREATE', create.objectType, create.key, null, create.object, create));
+    }
+
+    // Step 3: Handle drops (objects only in current)
+    for (const drop of matched.drops) {
+      allChanges.push(this.createChangeObject('DROP', drop.objectType, drop.key, drop.object, null, drop));
+    }
+
+    // Step 4: Handle detected renames
+    for (const rename of matched.renames) {
+      allChanges.push(this.createChangeObject('RENAME', rename.objectType, rename.key, rename, rename, rename, rename));
+    }
+
+    // Step 5: Property-level diff for matched objects
+    const propertyResults = this.propertyDiffer.diff(matched.matches, desired, current);
+    allChanges.push(...propertyResults.changes.map(c => {
+      let pluralKey = c.objectType + 's';
+      if (c.objectType === 'index') pluralKey = 'indexes';
+      else if (c.objectType === 'materializedView') pluralKey = 'materializedViews';
+      else if (c.objectType === 'operatorClass') pluralKey = 'operatorClasses';
+      else if (c.objectType === 'operatorFamily') pluralKey = 'operatorFamilies';
+      else if (c.objectType === 'defaultPrivileges') pluralKey = 'defaultPrivileges';
+      else if (c.objectType === 'foreignTable') pluralKey = 'tables';
+      else if (c.objectType === 'function' && desired.procedures?.[c.path]) pluralKey = 'procedures';
+      else if (c.objectType === 'function' && desired.aggregates?.[c.path]) pluralKey = 'aggregates';
+      else if (c.objectType === 'textSearchConfig') pluralKey = 'textSearchConfigs';
+      else if (c.objectType === 'textSearchDict') pluralKey = 'textSearchDictionaries';
+      else if (c.objectType === 'textSearchParser') pluralKey = 'textSearchParsers';
+      else if (c.objectType === 'textSearchTemplate') pluralKey = 'textSearchTemplates';
+
+      const beforeObj = current[pluralKey]?.[c.path] || null;
+      const afterObj = desired[pluralKey]?.[c.path] || null;
+
+      const changeObj = this.createChangeObject(
+        'ALTER',
+        c.objectType,
+        c.path,
+        beforeObj,
+        afterObj,
+        c,
+        c.property
+      );
+      changeObj.currentValue = c.currentValue;
+      changeObj.desiredValue = c.desiredValue;
+      return changeObj;
+    }));
+
+    // Step 6: Process warnings from property differ
+
+    // Step 7: Classify changes (track 1 vs track 2)
+    this.changeClassifier.classify(allChanges);
+
+    // Step 8: Resolve dependency order
+    const orderedChanges = this.dependencyResolver.resolve(allChanges, desired, current);
+
+    // Step 9: Tag risks
+    this.riskTagger.tag(orderedChanges);
+
+    // Step 10: Build output
+    return {
+      summary: this.buildSummary(orderedChanges),
+      changes: orderedChanges,
+      warnings: [...matched.renames.filter(r => !r.confirmed).map(r => ({
+        code: 'RENAME_UNCONFIRMED',
+        message: `Possible rename detected: ${r.oldName} → ${r.newName}`,
+        changeKey: r.key,
+        action: 'Confirm rename or treat as drop+add',
+      })), ...propertyResults.warnings],
+      dependencyGraph: this.dependencyResolver.getGraph(),
+      metadata: {
+        diffDuration: Date.now() - startTime,
+        pgVersion: this.pgVersion,
+        desiredChecksum: desired.checksum,
+        currentChecksum: current.checksum,
+      },
+    };
+  }
+
+  /**
+   * Create a standardized change object.
+   */
+  createChangeObject(changeType, objectType, objectKey, before, after, extra = {}, property = null) {
+    const id = `change_${crypto.randomUUID().slice(0, 8)}`;
+
+    return {
+      id,
+      changeType,
+      objectType,
+      objectKey,
+      schema: extra?.schema,
+      name: extra?.name || objectKey?.split('.').pop(),
+      property,
+      before: before || null,
+      after: after || null,
+      track: extra?.track || 1,
+      phase: extra?.phase || 10,
+      ddlStrategy: extra?.ddlStrategy || 'ALTER',
+      dependencies: extra?.dependencies || [],
+      dependents: [],
+      risk: extra?.risk || { level: 'none', categories: [], warnings: [] },
+      requiresRecreation: extra?.requiresRecreation || false,
+      safePatternAvailable: extra?.safePatternAvailable || false,
+      isNonTransactional: extra?.isTransactional === false,
+      pgVersionMinimum: extra?.pgVersionMinimum,
+      dataLossRisk: extra?.dataLossRisk,
+      ...extra,
+    };
+  }
+
+  /**
+   * Build summary statistics.
+   */
+  buildSummary(changes) {
+    const summary = {
+      totalChanges: changes.length,
+      creates: 0,
+      drops: 0,
+      alters: 0,
+      renames: 0,
+      recreates: 0,
+      replaces: 0,
+
+      byTrack: {
+        track1: { count: 0, phases: {} },
+        track2: { count: 0, phases: {} },
+      },
+
+      byPhase: {},
+
+      byObjectType: {},
+
+      riskSummary: {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        none: 0,
+        categories: {},
+      },
+
+      requiresDowntime: false,
+      estimatedDuration: this.estimateDuration(changes),
+    };
+
+    for (const change of changes) {
+      // Count by change type
+      if (change.changeType === 'CREATE') summary.creates++;
+      else if (change.changeType === 'DROP') summary.drops++;
+      else if (change.changeType === 'ALTER') summary.alters++;
+      else if (change.changeType === 'RENAME') summary.renames++;
+      else if (change.changeType?.includes('RECREATE')) summary.recreates++;
+      else if (change.changeType?.includes('REPLACE')) summary.replaces++;
+
+      // Count by track
+      const track = change.track === 2 ? 'track2' : 'track1';
+      summary.byTrack[track].count++;
+      const phase = change.phase;
+      if (!summary.byTrack[track].phases[phase]) {
+        summary.byTrack[track].phases[phase] = 0;
+      }
+      summary.byTrack[track].phases[phase]++;
+
+      // Count by phase
+      if (!summary.byPhase[phase]) summary.byPhase[phase] = { count: 0, name: this.getPhaseName(phase) };
+      summary.byPhase[phase].count++;
+
+      // Count by object type
+      const objType = change.objectType;
+      if (!summary.byObjectType[objType]) summary.byObjectType[objType] = 0;
+      summary.byObjectType[objType]++;
+
+      // Risk counts
+      const level = change.risk?.level || 'none';
+      summary.riskSummary[level]++;
+
+      for (const cat of (change.risk?.categories || [])) {
+        if (!summary.riskSummary.categories[cat]) {
+          summary.riskSummary.categories[cat] = 0;
+        }
+        summary.riskSummary.categories[cat]++;
+      }
+
+      // Check for downtime
+      if (change.risk?.requiresDowntime) {
+        summary.requiresDowntime = true;
+      }
+    }
+
+    return summary;
+  }
+
+  /**
+   * Get human-readable phase name.
+   */
+  getPhaseName(phase) {
+    const phases = {
+      1: 'pre_check',
+      2: 'advisory_lock',
+      3: 'extensions',
+      4: 'types',
+      5: 'schemas',
+      6: 'tables_create',
+      7: 'columns_add',
+      8: 'sequences',
+      9: 'indexes_create',
+      10: 'constraints_non_fk',
+      11: 'data_migration',
+      12: 'constraints_fk',
+      13: 'validate_constraints',
+      14: 'views',
+      15: 'materialized_views',
+      16: 'functions',
+      17: 'triggers',
+      18: 'policies',
+      19: 'rules',
+      20: 'behavioral_other',
+      21: 'grants',
+      22: 'comments',
+      23: 'indexes_concurrent',
+      24: 'cleanup',
+      25: 'post_check',
+    };
+    return phases[phase] || `phase_${phase}`;
+  }
+
+  /**
+   * Estimate migration duration.
+   */
+  estimateDuration(changes) {
+    let seconds = 0;
+
+    for (const change of changes) {
+      switch (change.objectType) {
+        case 'index':
+          seconds += change.isConcurrent ? 30 : 2;
+          break;
+        case 'constraint':
+          seconds += change.constraintType === 'FOREIGN_KEY' ? 5 : 2;
+          break;
+        case 'table':
+          seconds += change.changeType === 'CREATE' ? 1 : 2;
+          break;
+        case 'column':
+          seconds += change.property === 'dataType' ? 10 : 1;
+          break;
+        case 'type':
+          seconds += 2;
+          break;
+        case 'view':
+        case 'materializedView':
+          seconds += 3;
+          break;
+        case 'function':
+          seconds += 2;
+          break;
+        default:
+          seconds += 1;
+      }
+    }
+
+    if (seconds < 60) return `${seconds} seconds`;
+    if (seconds < 3600) return `${Math.ceil(seconds / 60)} minutes`;
+    return `${Math.ceil(seconds / 3600)} hours`;
+  }
+}
+
+// Export all sub-modules
+export { ObjectMatcher } from './object-matcher.js';
+export { PropertyDiffer } from './property-differ.js';
+export { DependencyResolver } from './dependency-resolver.js';
+export { ChangeClassifier } from './change-classifier.js';
+export { RiskTagger } from './risk-tagger.js';

package/src/differ/utils/levenshtein.js

@@ -0,0 +1,210 @@
+/**
+ * Levenshtein distance implementation for rename detection.
+ * Pure JS, zero dependencies.
+ */
+
+/**
+ * Calculate the Levenshtein distance between two strings.
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} - Minimum number of edits to transform a into b
+ */
+export function levenshtein(a, b) {
+  if (!a) return b ? b.length : 0;
+  if (!b) return a.length;
+
+  const aLen = a.length;
+  const bLen = b.length;
+
+  // Use the shorter string for the outer loop to minimize memory
+  if (aLen > bLen) {
+    return levenshtein(b, a);
+  }
+
+  // Initialize row
+  let prevRow = Array.from({ length: aLen + 1 }, (_, i) => i);
+
+  for (let j = 1; j <= bLen; j++) {
+    const currRow = [j];
+    const bChar = b.charCodeAt(j - 1);
+
+    for (let i = 1; i <= aLen; i++) {
+      const aChar = a.charCodeAt(i - 1);
+      const cost = aChar === bChar ? 0 : 1;
+
+      currRow[i] = Math.min(
+        prevRow[i] + 1,      // deletion
+        currRow[i - 1] + 1,  // insertion
+        prevRow[i - 1] + cost // substitution
+      );
+    }
+
+    prevRow = currRow;
+  }
+
+  return prevRow[aLen];
+}
+
+/**
+ * Calculate similarity score between two strings (0-1).
+ * Higher values mean more similar.
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} - Similarity score between 0 and 1
+ */
+export function similarity(a, b) {
+  if (!a && !b) return 1;
+  if (!a || !b) return 0;
+
+  const distance = levenshtein(a.toLowerCase(), b.toLowerCase());
+  const maxLen = Math.max(a.length, b.length);
+
+  return maxLen === 0 ? 1 : 1 - (distance / maxLen);
+}
+
+/**
+ * Check if two strings are similar enough to be rename candidates.
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @param {number} threshold - Minimum similarity threshold (default 0.4)
+ * @returns {boolean}
+ */
+export function isSimilarEnough(a, b, threshold = 0.4) {
+  return similarity(a, b) >= threshold;
+}
+
+/**
+ * Calculate Damerau-Levenshtein distance (includes transpositions).
+ * More accurate for detecting typos like "teh" vs "the".
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number}
+ */
+export function damerauLevenshtein(a, b) {
+  if (!a) return b ? b.length : 0;
+  if (!b) return a.length;
+
+  const aLen = a.length;
+  const bLen = b.length;
+
+  const matrix = Array.from({ length: aLen + 1 }, () =>
+    Array.from({ length: bLen + 1 }, (_, j) => j)
+  );
+
+  for (let i = 0; i <= aLen; i++) {
+    matrix[i][0] = i;
+  }
+
+  for (let j = 0; j <= bLen; j++) {
+    matrix[0][j] = j;
+  }
+
+  for (let i = 1; i <= aLen; i++) {
+    for (let j = 1; j <= bLen; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,      // deletion
+        matrix[i][j - 1] + 1,      // insertion
+        matrix[i - 1][j - 1] + cost // substitution
+      );
+
+      // Transposition
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        matrix[i][j] = Math.min(matrix[i][j], matrix[i - 2][j - 2] + cost);
+      }
+    }
+  }
+
+  return matrix[aLen][bLen];
+}
+
+/**
+ * Find the best matching string from a list.
+ * @param {string} target - String to match
+ * @param {string[]} candidates - List of candidate strings
+ * @param {number} threshold - Minimum similarity (default 0.4)
+ * @returns {{match: string|null, similarity: number}}
+ */
+export function findBestMatch(target, candidates, threshold = 0.4) {
+  let bestMatch = null;
+  let bestScore = threshold - 1; // Start below threshold
+
+  for (const candidate of candidates) {
+    const score = similarity(target, candidate);
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = candidate;
+    }
+  }
+
+  return { match: bestMatch, similarity: bestMatch };
+}
+
+/**
+ * Calculate Jaro-Winkler similarity (better for name matching).
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} - Similarity score between 0 and 1
+ */
+export function jaroWinkler(a, b) {
+  if (!a && !b) return 1;
+  if (!a || !b) return 0;
+  if (a === b) return 1;
+
+  const aLower = a.toLowerCase();
+  const bLower = b.toLowerCase();
+
+  const aLen = aLower.length;
+  const bLen = bLower.length;
+
+  const matchDistance = Math.floor(Math.max(aLen, bLen) / 2) - 1;
+  if (matchDistance < 0) return 0;
+
+  const aMatches = new Array(aLen).fill(false);
+  const bMatches = new Array(bLen).fill(false);
+
+  let matches = 0;
+  let transpositions = 0;
+
+  // Find matches
+  for (let i = 0; i < aLen; i++) {
+    const start = Math.max(0, i - matchDistance);
+    const end = Math.min(i + matchDistance + 1, bLen);
+
+    for (let j = start; j < end; j++) {
+      if (bMatches[j] || aLower[i] !== bLower[j]) continue;
+      aMatches[i] = true;
+      bMatches[j] = true;
+      matches++;
+      break;
+    }
+  }
+
+  if (matches === 0) return 0;
+
+  // Count transpositions
+  let k = 0;
+  for (let i = 0; i < aLen; i++) {
+    if (!aMatches[i]) continue;
+    while (!bMatches[k]) k++;
+    if (aLower[i] !== bLower[k]) transpositions++;
+    k++;
+  }
+
+  // Jaro similarity
+  const jaro = (
+    matches / aLen +
+    matches / bLen +
+    (matches - transpositions / 2) / matches
+  ) / 3;
+
+  // Winkler modification (boost for common prefix)
+  let prefix = 0;
+  const maxPrefix = Math.min(4, aLen, bLen);
+  for (let i = 0; i < maxPrefix && aLower[i] === bLower[i]; i++) {
+    prefix++;
+  }
+
+  return jaro + prefix * 0.1 * (1 - jaro);
+}

package/src/differ/utils/path-builder.js

@@ -0,0 +1,198 @@
+/**
+ * Utility for building dotted paths like "public.users.email"
+ */
+
+/**
+ * Build a path for an object.
+ * @param {Object} options
+ * @param {string} [options.schema]
+ * @param {string} [options.table]
+ * @param {string} [options.name]
+ * @param {string} [options.column]
+ * @param {string} [options.objectType]
+ * @returns {string}
+ */
+export function buildPath(options) {
+  const parts = [];
+  
+  if (options.schema) {
+    parts.push(options.schema);
+  }
+  
+  if (options.table) {
+    parts.push(options.table);
+  } else if (options.parent) {
+    parts.push(options.parent);
+  }
+  
+  if (options.column) {
+    parts.push(options.column);
+  } else if (options.name) {
+    parts.push(options.name);
+  }
+  
+  return parts.join('.');
+}
+
+/**
+ * Build a path for a table.
+ * @param {string} schema
+ * @param {string} tableName
+ * @returns {string}
+ */
+export function tablePath(schema, tableName) {
+  return `${schema}.${tableName}`;
+}
+
+/**
+ * Build a path for a column.
+ * @param {string} schema
+ * @param {string} tableName
+ * @param {string} columnName
+ * @returns {string}
+ */
+export function columnPath(schema, tableName, columnName) {
+  return `${schema}.${tableName}.${columnName}`;
+}
+
+/**
+ * Build a path for an index.
+ * @param {string} schema
+ * @param {string} indexName
+ * @returns {string}
+ */
+export function indexPath(schema, indexName) {
+  return `${schema}.${indexName}`;
+}
+
+/**
+ * Build a path for a constraint.
+ * @param {string} schema
+ * @param {string} constraintName
+ * @returns {string}
+ */
+export function constraintPath(schema, constraintName) {
+  return `${schema}.${constraintName}`;
+}
+
+/**
+ * Build a path for a function.
+ * @param {string} schema
+ * @param {string} functionName
+ * @param {string} [args]
+ * @returns {string}
+ */
+export function functionPath(schema, functionName, args) {
+  if (args) {
+    return `${schema}.${functionName}(${args})`;
+  }
+  return `${schema}.${functionName}`;
+}
+
+/**
+ * Build a path for a trigger.
+ * @param {string} schema
+ * @param {string} tableName
+ * @param {string} triggerName
+ * @returns {string}
+ */
+export function triggerPath(schema, tableName, triggerName) {
+  return `${schema}.${tableName}.${triggerName}`;
+}
+
+/**
+ * Build a path for a policy.
+ * @param {string} schema
+ * @param {string} tableName
+ * @param {string} policyName
+ * @returns {string}
+ */
+export function policyPath(schema, tableName, policyName) {
+  return `${schema}.${tableName}.${policyName}`;
+}
+
+/**
+ * Build a path for a view.
+ * @param {string} schema
+ * @param {string} viewName
+ * @returns {string}
+ */
+export function viewPath(schema, viewName) {
+  return `${schema}.${viewName}`;
+}
+
+/**
+ * Build a path for a type.
+ * @param {string} schema
+ * @param {string} typeName
+ * @returns {string}
+ */
+export function typePath(schema, typeName) {
+  return `${schema}.${typeName}`;
+}
+
+/**
+ * Build a path for a sequence.
+ * @param {string} schema
+ * @param {string} sequenceName
+ * @returns {string}
+ */
+export function sequencePath(schema, sequenceName) {
+  return `${schema}.${sequenceName}`;
+}
+
+/**
+ * Parse a path into its components.
+ * @param {string} path
+ * @returns {{schema: string, name: string, parent: string|null}}
+ */
+export function parsePath(path) {
+  const parts = path.split('.');
+  
+  if (parts.length === 1) {
+    return { schema: null, name: parts[0], parent: null };
+  }
+  
+  if (parts.length === 2) {
+    return { schema: parts[0], name: parts[1], parent: null };
+  }
+  
+  if (parts.length >= 3) {
+    return { schema: parts[0], parent: `${parts[0]}.${parts[1]}`, name: parts[parts.length - 1] };
+  }
+  
+  return { schema: null, name: path, parent: null };
+}
+
+/**
+ * Get the parent path (table for column, schema for table, etc.)
+ * @param {string} path
+ * @returns {string|null}
+ */
+export function getParentPath(path) {
+  const parts = path.split('.');
+  
+  if (parts.length <= 1) return null;
+  
+  return parts.slice(0, -1).join('.');
+}
+
+/**
+ * Get the leaf name from a path.
+ * @param {string} path
+ * @returns {string}
+ */
+export function getLeafName(path) {
+  const parts = path.split('.');
+  return parts[parts.length - 1];
+}
+
+/**
+ * Get the schema from a path.
+ * @param {string} path
+ * @returns {string|null}
+ */
+export function getSchema(path) {
+  const parts = path.split('.');
+  return parts.length >= 1 ? parts[0] : null;
+}