@dboio/cli 0.4.2 → 0.6.0

package/src/lib/delta.js

@@ -0,0 +1,204 @@
+import { readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { log } from './logger.js';
+
+/**
+ * Load the baseline file (.app.json) from disk.
+ *
+ * @param {string} cwd - Current working directory
+ * @returns {Promise<Object|null>} - Baseline JSON or null if not found
+ */
+export async function loadBaseline(cwd = process.cwd()) {
+  const baselinePath = join(cwd, '.app.json');
+  try {
+    const raw = await readFile(baselinePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return null; // Baseline doesn't exist
+    }
+    log.warn(`Failed to parse .app.json: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save baseline data to .app.json file.
+ *
+ * @param {Object} data - Baseline JSON data
+ * @param {string} cwd - Current working directory
+ */
+export async function saveBaseline(data, cwd = process.cwd()) {
+  const { writeFile } = await import('fs/promises');
+  const baselinePath = join(cwd, '.app.json');
+  await writeFile(baselinePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+/**
+ * Find a baseline entry by UID and entity type.
+ * Traverses the baseline's children hierarchy.
+ *
+ * @param {Object} baseline - The baseline JSON
+ * @param {string} entity - Entity type (e.g., "content", "output")
+ * @param {string} uid - Record UID
+ * @returns {Object|null} - Matching entry or null
+ */
+export function findBaselineEntry(baseline, entity, uid) {
+  if (!baseline || !baseline.children) {
+    return null;
+  }
+
+  const entityArray = baseline.children[entity];
+  if (!Array.isArray(entityArray)) {
+    return null;
+  }
+
+  return entityArray.find(item => item.UID === uid) || null;
+}
+
+/**
+ * Compare a file's content on disk against a baseline value.
+ *
+ * @param {string} filePath - Absolute path to file
+ * @param {string|null} baselineValue - Baseline value to compare against
+ * @returns {Promise<boolean>} - True if different, false if same
+ */
+export async function compareFileContent(filePath, baselineValue) {
+  try {
+    const currentContent = await readFile(filePath, 'utf8');
+
+    // Normalize line endings for comparison
+    const normalizedCurrent = currentContent.replace(/\r\n/g, '\n').trim();
+    const normalizedBaseline = (baselineValue || '').replace(/\r\n/g, '\n').trim();
+
+    return normalizedCurrent !== normalizedBaseline;
+  } catch (err) {
+    // If file doesn't exist or can't be read, consider it changed
+    log.warn(`Failed to read ${filePath}: ${err.message}`);
+    return true;
+  }
+}
+
+/**
+ * Detect which columns have changed by comparing current metadata against baseline.
+ *
+ * @param {string} metaPath - Path to metadata.json file
+ * @param {Object} baseline - The baseline JSON
+ * @param {Object} config - CLI config (for resolving file paths)
+ * @returns {Promise<string[]>} - Array of changed column names
+ */
+export async function detectChangedColumns(metaPath, baseline, config) {
+  // Load current metadata
+  const metaRaw = await readFile(metaPath, 'utf8');
+  const metadata = JSON.parse(metaRaw);
+
+  const { UID, _entity } = metadata;
+
+  // Find matching baseline entry
+  const baselineEntry = findBaselineEntry(baseline, _entity, UID);
+
+  // If no baseline exists for this record, all non-system columns are "changed"
+  if (!baselineEntry) {
+    return getAllUserColumns(metadata);
+  }
+
+  const changedColumns = [];
+  const metaDir = dirname(metaPath);
+
+  // Compare each column
+  for (const [columnName, columnValue] of Object.entries(metadata)) {
+    // Skip system columns and special fields
+    if (shouldSkipColumn(columnName)) {
+      continue;
+    }
+
+    // Check if value is a @reference
+    if (isReference(columnValue)) {
+      const refPath = resolveReferencePath(columnValue, metaDir);
+      const baselineValue = baselineEntry[columnName];
+
+      // Compare file content
+      const isDifferent = await compareFileContent(refPath, baselineValue);
+      if (isDifferent) {
+        changedColumns.push(columnName);
+      }
+    } else {
+      // Scalar value comparison
+      const currentValue = normalizeValue(columnValue);
+      const baselineValue = normalizeValue(baselineEntry[columnName]);
+
+      if (currentValue !== baselineValue) {
+        changedColumns.push(columnName);
+      }
+    }
+  }
+
+  return changedColumns;
+}
+
+/**
+ * Get all user-defined columns (non-system columns).
+ *
+ * @param {Object} metadata - Metadata object
+ * @returns {string[]} - Array of user column names
+ */
+function getAllUserColumns(metadata) {
+  return Object.keys(metadata).filter(col => !shouldSkipColumn(col));
+}
+
+/**
+ * Determine if a column should be skipped (system columns).
+ *
+ * @param {string} columnName - Column name
+ * @returns {boolean} - True if should skip
+ */
+function shouldSkipColumn(columnName) {
+  // Skip system columns starting with underscore, UID, and children
+  return columnName.startsWith('_') ||
+         columnName === 'UID' ||
+         columnName === 'children';
+}
+
+/**
+ * Check if a value is a @reference object.
+ *
+ * @param {*} value - Value to check
+ * @returns {boolean} - True if reference
+ */
+function isReference(value) {
+  return value &&
+         typeof value === 'object' &&
+         !Array.isArray(value) &&
+         value['@reference'] !== undefined;
+}
+
+/**
+ * Resolve a @reference path to absolute file path.
+ *
+ * @param {Object} reference - Reference object with @reference property
+ * @param {string} baseDir - Base directory containing metadata
+ * @returns {string} - Absolute file path
+ */
+function resolveReferencePath(reference, baseDir) {
+  const refPath = reference['@reference'];
+  return join(baseDir, refPath);
+}
+
+/**
+ * Normalize a value for comparison (handle null, undefined, etc.).
+ *
+ * @param {*} value - Value to normalize
+ * @returns {string} - Normalized string value
+ */
+function normalizeValue(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  // If it's still a @reference object in baseline, compare as string
+  if (isReference(value)) {
+    return JSON.stringify(value);
+  }
+
+  return String(value).trim();
+}

package/src/lib/dependencies.js

@@ -0,0 +1,131 @@
+/**
+ * Dependency management for entity synchronization.
+ * Ensures children are processed before parents to maintain referential integrity.
+ */
+
+/**
+ * Entity dependency hierarchy.
+ * Lower levels must be processed before higher levels.
+ * This ensures foreign key relationships are maintained (children before parents).
+ */
+export const ENTITY_DEPENDENCIES = {
+  // Level 1: Most dependent (children)
+  'output_value_filter': 1,
+  'output_value_entity_column_rel': 2,
+
+  // Level 2: Mid-level dependencies
+  'output_value': 2,
+
+  // Level 3: Parent entities
+  'output': 3,
+
+  // Default level 0 for entities not in this map
+};
+
+/**
+ * Get the dependency level for an entity type.
+ *
+ * @param {string} entity - Entity type name
+ * @returns {number} - Dependency level (0 = no dependencies, higher = more dependent)
+ */
+function getDependencyLevel(entity) {
+  return ENTITY_DEPENDENCIES[entity] || 0;
+}
+
+/**
+ * Build a dependency-ordered structure from synchronize.json data.
+ * Returns operations grouped by type and sorted by dependency level.
+ *
+ * @param {Object} synchronizeData - The synchronize.json contents
+ * @returns {Object} - Ordered structure: { delete: [], add: [], edit: [] }
+ */
+export function buildDependencyGraph(synchronizeData) {
+  if (!synchronizeData) {
+    return { delete: [], add: [], edit: [] };
+  }
+
+  const result = {
+    delete: sortByDependency(synchronizeData.delete || [], 'delete'),
+    add: sortByDependency(synchronizeData.add || [], 'add'),
+    edit: sortByDependency(synchronizeData.edit || [], 'edit'),
+  };
+
+  return result;
+}
+
+/**
+ * Sort entries by dependency level and UID.
+ * For delete operations: process parents before children (descending order)
+ * For add/edit operations: process children before parents (ascending order)
+ *
+ * @param {Array} entries - Array of sync entries
+ * @param {string} operationType - Operation type: 'delete', 'add', or 'edit'
+ * @returns {Array} - Sorted entries
+ */
+function sortByDependency(entries, operationType) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return [];
+  }
+
+  // Group by entity type
+  const grouped = groupByEntity(entries);
+
+  // Sort entity types by dependency level
+  const entityTypes = Object.keys(grouped);
+  entityTypes.sort((a, b) => {
+    const levelA = getDependencyLevel(a);
+    const levelB = getDependencyLevel(b);
+
+    // Delete operations: parents before children (descending)
+    // Add/Edit operations: children before parents (ascending)
+    if (operationType === 'delete') {
+      return levelB - levelA; // Higher level first
+    } else {
+      return levelA - levelB; // Lower level first
+    }
+  });
+
+  // Flatten back to array, maintaining UID sort within each entity type
+  const sorted = [];
+  for (const entity of entityTypes) {
+    const entityEntries = grouped[entity];
+    // Sort by UID for consistent ordering
+    entityEntries.sort((a, b) => (a.UID || '').localeCompare(b.UID || ''));
+    sorted.push(...entityEntries);
+  }
+
+  return sorted;
+}
+
+/**
+ * Group entries by entity type.
+ *
+ * @param {Array} entries - Array of sync entries
+ * @returns {Object} - Entries grouped by entity: { entityType: [...entries] }
+ */
+function groupByEntity(entries) {
+  const groups = {};
+
+  for (const entry of entries) {
+    const entity = entry.entity || entry._entity || 'unknown';
+    if (!groups[entity]) {
+      groups[entity] = [];
+    }
+    groups[entity].push(entry);
+  }
+
+  return groups;
+}
+
+/**
+ * Sort entries by UID for consistent ordering within an entity type.
+ *
+ * @param {Array} entries - Array of entries
+ * @returns {Array} - Sorted entries
+ */
+export function sortEntriesByUid(entries) {
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+  return entries.slice().sort((a, b) => (a.UID || '').localeCompare(b.UID || ''));
+}