@objectstack/core 0.9.1 → 1.0.0

package/src/dependency-resolver.test.ts

@@ -0,0 +1,287 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SemanticVersionManager, DependencyResolver } from './dependency-resolver.js';
+import { createLogger } from './logger.js';
+
+describe('SemanticVersionManager', () => {
+  describe('parse', () => {
+    it('should parse standard semver', () => {
+      const version = SemanticVersionManager.parse('1.2.3');
+      expect(version).toEqual({
+        major: 1,
+        minor: 2,
+        patch: 3,
+        preRelease: undefined,
+        build: undefined,
+      });
+    });
+
+    it('should parse semver with pre-release', () => {
+      const version = SemanticVersionManager.parse('1.2.3-alpha.1');
+      expect(version).toEqual({
+        major: 1,
+        minor: 2,
+        patch: 3,
+        preRelease: 'alpha.1',
+        build: undefined,
+      });
+    });
+
+    it('should parse semver with build metadata', () => {
+      const version = SemanticVersionManager.parse('1.2.3+build.123');
+      expect(version).toEqual({
+        major: 1,
+        minor: 2,
+        patch: 3,
+        preRelease: undefined,
+        build: 'build.123',
+      });
+    });
+
+    it('should parse semver with both pre-release and build', () => {
+      const version = SemanticVersionManager.parse('1.2.3-beta.2+build.456');
+      expect(version).toEqual({
+        major: 1,
+        minor: 2,
+        patch: 3,
+        preRelease: 'beta.2',
+        build: 'build.456',
+      });
+    });
+
+    it('should handle v prefix', () => {
+      const version = SemanticVersionManager.parse('v1.2.3');
+      expect(version.major).toBe(1);
+      expect(version.minor).toBe(2);
+      expect(version.patch).toBe(3);
+    });
+  });
+
+  describe('compare', () => {
+    it('should compare major versions', () => {
+      const v1 = SemanticVersionManager.parse('2.0.0');
+      const v2 = SemanticVersionManager.parse('1.0.0');
+      expect(SemanticVersionManager.compare(v1, v2)).toBeGreaterThan(0);
+      expect(SemanticVersionManager.compare(v2, v1)).toBeLessThan(0);
+    });
+
+    it('should compare minor versions', () => {
+      const v1 = SemanticVersionManager.parse('1.2.0');
+      const v2 = SemanticVersionManager.parse('1.1.0');
+      expect(SemanticVersionManager.compare(v1, v2)).toBeGreaterThan(0);
+    });
+
+    it('should compare patch versions', () => {
+      const v1 = SemanticVersionManager.parse('1.0.2');
+      const v2 = SemanticVersionManager.parse('1.0.1');
+      expect(SemanticVersionManager.compare(v1, v2)).toBeGreaterThan(0);
+    });
+
+    it('should handle equal versions', () => {
+      const v1 = SemanticVersionManager.parse('1.2.3');
+      const v2 = SemanticVersionManager.parse('1.2.3');
+      expect(SemanticVersionManager.compare(v1, v2)).toBe(0);
+    });
+
+    it('should treat pre-release as lower than release', () => {
+      const v1 = SemanticVersionManager.parse('1.0.0-alpha');
+      const v2 = SemanticVersionManager.parse('1.0.0');
+      expect(SemanticVersionManager.compare(v1, v2)).toBeLessThan(0);
+    });
+  });
+
+  describe('satisfies', () => {
+    it('should match exact version', () => {
+      const version = SemanticVersionManager.parse('1.2.3');
+      expect(SemanticVersionManager.satisfies(version, '1.2.3')).toBe(true);
+      expect(SemanticVersionManager.satisfies(version, '1.2.4')).toBe(false);
+    });
+
+    it('should match caret range', () => {
+      const version = SemanticVersionManager.parse('1.2.5');
+      expect(SemanticVersionManager.satisfies(version, '^1.2.3')).toBe(true);
+      expect(SemanticVersionManager.satisfies(version, '^1.3.0')).toBe(false);
+      expect(SemanticVersionManager.satisfies(version, '^2.0.0')).toBe(false);
+    });
+
+    it('should match tilde range', () => {
+      const version = SemanticVersionManager.parse('1.2.5');
+      expect(SemanticVersionManager.satisfies(version, '~1.2.3')).toBe(true);
+      expect(SemanticVersionManager.satisfies(version, '~1.3.0')).toBe(false);
+    });
+
+    it('should match greater than or equal', () => {
+      const version = SemanticVersionManager.parse('1.2.5');
+      expect(SemanticVersionManager.satisfies(version, '>=1.2.3')).toBe(true);
+      expect(SemanticVersionManager.satisfies(version, '>=1.2.5')).toBe(true);
+      expect(SemanticVersionManager.satisfies(version, '>=1.3.0')).toBe(false);
+    });
+
+    it('should match less than', () => {
+      const version = SemanticVersionManager.parse('1.2.5');
+      expect(SemanticVersionManager.satisfies(version, '<1.3.0')).toBe(true);
+      expect(SemanticVersionManager.satisfies(version, '<1.2.5')).toBe(false);
+    });
+
+    it('should match range', () => {
+      const version = SemanticVersionManager.parse('1.2.5');
+      expect(SemanticVersionManager.satisfies(version, '1.2.0 - 1.3.0')).toBe(true);
+      expect(SemanticVersionManager.satisfies(version, '1.3.0 - 1.4.0')).toBe(false);
+    });
+
+    it('should match wildcard', () => {
+      const version = SemanticVersionManager.parse('1.2.5');
+      expect(SemanticVersionManager.satisfies(version, '*')).toBe(true);
+      expect(SemanticVersionManager.satisfies(version, 'latest')).toBe(true);
+    });
+  });
+
+  describe('getCompatibilityLevel', () => {
+    it('should detect fully compatible versions', () => {
+      const from = SemanticVersionManager.parse('1.2.3');
+      const to = SemanticVersionManager.parse('1.2.3');
+      expect(SemanticVersionManager.getCompatibilityLevel(from, to)).toBe('fully-compatible');
+    });
+
+    it('should detect backward compatible versions', () => {
+      const from = SemanticVersionManager.parse('1.2.3');
+      const to = SemanticVersionManager.parse('1.3.0');
+      expect(SemanticVersionManager.getCompatibilityLevel(from, to)).toBe('backward-compatible');
+    });
+
+    it('should detect breaking changes', () => {
+      const from = SemanticVersionManager.parse('1.2.3');
+      const to = SemanticVersionManager.parse('2.0.0');
+      expect(SemanticVersionManager.getCompatibilityLevel(from, to)).toBe('breaking-changes');
+    });
+
+    it('should detect incompatible (downgrade)', () => {
+      const from = SemanticVersionManager.parse('1.3.0');
+      const to = SemanticVersionManager.parse('1.2.0');
+      expect(SemanticVersionManager.getCompatibilityLevel(from, to)).toBe('incompatible');
+    });
+  });
+});
+
+describe('DependencyResolver', () => {
+  let resolver: DependencyResolver;
+  let logger: ReturnType<typeof createLogger>;
+
+  beforeEach(() => {
+    logger = createLogger({ level: 'silent' });
+    resolver = new DependencyResolver(logger);
+  });
+
+  describe('resolve', () => {
+    it('should resolve dependencies in topological order', () => {
+      const plugins = new Map([
+        ['a', { dependencies: [] }],
+        ['b', { dependencies: ['a'] }],
+        ['c', { dependencies: ['a', 'b'] }],
+      ]);
+
+      const order = resolver.resolve(plugins);
+      
+      expect(order.indexOf('a')).toBeLessThan(order.indexOf('b'));
+      expect(order.indexOf('b')).toBeLessThan(order.indexOf('c'));
+    });
+
+    it('should handle plugins with no dependencies', () => {
+      const plugins = new Map([
+        ['a', { dependencies: [] }],
+        ['b', { dependencies: [] }],
+      ]);
+
+      const order = resolver.resolve(plugins);
+      expect(order).toHaveLength(2);
+      expect(order).toContain('a');
+      expect(order).toContain('b');
+    });
+
+    it('should detect circular dependencies', () => {
+      const plugins = new Map([
+        ['a', { dependencies: ['b'] }],
+        ['b', { dependencies: ['a'] }],
+      ]);
+
+      expect(() => resolver.resolve(plugins)).toThrow('Circular dependency');
+    });
+
+    it('should detect missing dependencies', () => {
+      const plugins = new Map([
+        ['a', { dependencies: ['missing'] }],
+      ]);
+
+      expect(() => resolver.resolve(plugins)).toThrow('Missing dependency');
+    });
+  });
+
+  describe('detectConflicts', () => {
+    it('should detect version mismatches', () => {
+      const plugins = new Map<string, any>([
+        ['core', { version: '1.0.0', dependencies: {} }],
+        ['plugin-a', { version: '1.0.0', dependencies: { core: '^2.0.0' } }],
+      ]);
+
+      const conflicts = resolver.detectConflicts(plugins);
+      expect(conflicts.length).toBeGreaterThan(0);
+      expect(conflicts[0].type).toBe('version-mismatch');
+    });
+
+    it('should return no conflicts for compatible versions', () => {
+      const plugins = new Map<string, any>([
+        ['core', { version: '1.2.0', dependencies: {} }],
+        ['plugin-a', { version: '1.0.0', dependencies: { core: '^1.0.0' } }],
+      ]);
+
+      const conflicts = resolver.detectConflicts(plugins);
+      expect(conflicts.length).toBe(0);
+    });
+  });
+
+  describe('findBestVersion', () => {
+    it('should find highest matching version', () => {
+      const available = ['1.0.0', '1.1.0', '1.2.0', '2.0.0'];
+      const constraints = ['^1.0.0'];
+      
+      const best = resolver.findBestVersion(available, constraints);
+      expect(best).toBe('1.2.0');
+    });
+
+    it('should satisfy all constraints', () => {
+      const available = ['1.0.0', '1.1.0', '1.2.0', '2.0.0'];
+      const constraints = ['^1.0.0', '>=1.1.0', '<2.0.0'];
+      
+      const best = resolver.findBestVersion(available, constraints);
+      expect(best).toBe('1.2.0');
+    });
+
+    it('should return undefined if no version satisfies', () => {
+      const available = ['1.0.0', '1.1.0'];
+      const constraints = ['^2.0.0'];
+      
+      const best = resolver.findBestVersion(available, constraints);
+      expect(best).toBeUndefined();
+    });
+  });
+
+  describe('isAcyclic', () => {
+    it('should detect acyclic graph', () => {
+      const deps = new Map([
+        ['a', []],
+        ['b', ['a']],
+        ['c', ['a', 'b']],
+      ]);
+
+      expect(resolver.isAcyclic(deps)).toBe(true);
+    });
+
+    it('should detect cyclic graph', () => {
+      const deps = new Map([
+        ['a', ['b']],
+        ['b', ['a']],
+      ]);
+
+      expect(resolver.isAcyclic(deps)).toBe(false);
+    });
+  });
+});

package/src/dependency-resolver.ts

@@ -0,0 +1,388 @@
+import type { 
+  SemanticVersion,
+  VersionConstraint,
+  CompatibilityLevel,
+  DependencyConflict
+} from '@objectstack/spec/kernel';
+import type { ObjectLogger } from './logger.js';
+
+/**
+ * Semantic Version Parser and Comparator
+ * 
+ * Implements semantic versioning comparison and constraint matching
+ */
+export class SemanticVersionManager {
+  /**
+   * Parse a version string into semantic version components
+   */
+  static parse(versionStr: string): SemanticVersion {
+    // Remove 'v' prefix if present
+    const cleanVersion = versionStr.replace(/^v/, '');
+    
+    // Match semver pattern: major.minor.patch[-prerelease][+build]
+    const match = cleanVersion.match(
+      /^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9.-]+))?(?:\+([a-zA-Z0-9.-]+))?$/
+    );
+
+    if (!match) {
+      throw new Error(`Invalid semantic version: ${versionStr}`);
+    }
+
+    return {
+      major: parseInt(match[1], 10),
+      minor: parseInt(match[2], 10),
+      patch: parseInt(match[3], 10),
+      preRelease: match[4],
+      build: match[5],
+    };
+  }
+
+  /**
+   * Convert semantic version back to string
+   */
+  static toString(version: SemanticVersion): string {
+    let str = `${version.major}.${version.minor}.${version.patch}`;
+    if (version.preRelease) {
+      str += `-${version.preRelease}`;
+    }
+    if (version.build) {
+      str += `+${version.build}`;
+    }
+    return str;
+  }
+
+  /**
+   * Compare two semantic versions
+   * Returns: -1 if a < b, 0 if a === b, 1 if a > b
+   */
+  static compare(a: SemanticVersion, b: SemanticVersion): number {
+    // Compare major, minor, patch
+    if (a.major !== b.major) return a.major - b.major;
+    if (a.minor !== b.minor) return a.minor - b.minor;
+    if (a.patch !== b.patch) return a.patch - b.patch;
+
+    // Pre-release versions have lower precedence
+    if (a.preRelease && !b.preRelease) return -1;
+    if (!a.preRelease && b.preRelease) return 1;
+    
+    // Compare pre-release versions
+    if (a.preRelease && b.preRelease) {
+      return a.preRelease.localeCompare(b.preRelease);
+    }
+
+    return 0;
+  }
+
+  /**
+   * Check if version satisfies constraint
+   */
+  static satisfies(version: SemanticVersion, constraint: VersionConstraint): boolean {
+    const constraintStr = constraint as string;
+
+    // Any version
+    if (constraintStr === '*' || constraintStr === 'latest') {
+      return true;
+    }
+
+    // Exact version
+    if (/^[\d.]+$/.test(constraintStr)) {
+      const exact = this.parse(constraintStr);
+      return this.compare(version, exact) === 0;
+    }
+
+    // Caret range (^): Compatible with version
+    if (constraintStr.startsWith('^')) {
+      const base = this.parse(constraintStr.slice(1));
+      return (
+        version.major === base.major &&
+        this.compare(version, base) >= 0
+      );
+    }
+
+    // Tilde range (~): Approximately equivalent
+    if (constraintStr.startsWith('~')) {
+      const base = this.parse(constraintStr.slice(1));
+      return (
+        version.major === base.major &&
+        version.minor === base.minor &&
+        this.compare(version, base) >= 0
+      );
+    }
+
+    // Greater than or equal
+    if (constraintStr.startsWith('>=')) {
+      const base = this.parse(constraintStr.slice(2));
+      return this.compare(version, base) >= 0;
+    }
+
+    // Greater than
+    if (constraintStr.startsWith('>')) {
+      const base = this.parse(constraintStr.slice(1));
+      return this.compare(version, base) > 0;
+    }
+
+    // Less than or equal
+    if (constraintStr.startsWith('<=')) {
+      const base = this.parse(constraintStr.slice(2));
+      return this.compare(version, base) <= 0;
+    }
+
+    // Less than
+    if (constraintStr.startsWith('<')) {
+      const base = this.parse(constraintStr.slice(1));
+      return this.compare(version, base) < 0;
+    }
+
+    // Range (1.2.3 - 2.3.4)
+    const rangeMatch = constraintStr.match(/^([\d.]+)\s*-\s*([\d.]+)$/);
+    if (rangeMatch) {
+      const min = this.parse(rangeMatch[1]);
+      const max = this.parse(rangeMatch[2]);
+      return this.compare(version, min) >= 0 && this.compare(version, max) <= 0;
+    }
+
+    return false;
+  }
+
+  /**
+   * Determine compatibility level between two versions
+   */
+  static getCompatibilityLevel(from: SemanticVersion, to: SemanticVersion): CompatibilityLevel {
+    const cmp = this.compare(from, to);
+
+    // Same version
+    if (cmp === 0) {
+      return 'fully-compatible';
+    }
+
+    // Major version changed - breaking changes
+    if (from.major !== to.major) {
+      return 'breaking-changes';
+    }
+
+    // Minor version increased - backward compatible
+    if (from.minor < to.minor) {
+      return 'backward-compatible';
+    }
+
+    // Patch version increased - fully compatible
+    if (from.patch < to.patch) {
+      return 'fully-compatible';
+    }
+
+    // Downgrade - incompatible
+    return 'incompatible';
+  }
+}
+
+/**
+ * Plugin Dependency Resolver
+ * 
+ * Resolves plugin dependencies using topological sorting and conflict detection
+ */
+export class DependencyResolver {
+  private logger: ObjectLogger;
+
+  constructor(logger: ObjectLogger) {
+    this.logger = logger.child({ component: 'DependencyResolver' });
+  }
+
+  /**
+   * Resolve dependencies using topological sort
+   */
+  resolve(
+    plugins: Map<string, { version?: string; dependencies?: string[] }>
+  ): string[] {
+    const graph = new Map<string, string[]>();
+    const inDegree = new Map<string, number>();
+
+    // Build dependency graph
+    for (const [pluginName, pluginInfo] of plugins) {
+      if (!graph.has(pluginName)) {
+        graph.set(pluginName, []);
+        inDegree.set(pluginName, 0);
+      }
+
+      const deps = pluginInfo.dependencies || [];
+      for (const dep of deps) {
+        // Check if dependency exists
+        if (!plugins.has(dep)) {
+          throw new Error(`Missing dependency: ${pluginName} requires ${dep}`);
+        }
+
+        // Add edge
+        if (!graph.has(dep)) {
+          graph.set(dep, []);
+          inDegree.set(dep, 0);
+        }
+        graph.get(dep)!.push(pluginName);
+        inDegree.set(pluginName, (inDegree.get(pluginName) || 0) + 1);
+      }
+    }
+
+    // Topological sort using Kahn's algorithm
+    const queue: string[] = [];
+    const result: string[] = [];
+
+    // Add all nodes with no incoming edges
+    for (const [node, degree] of inDegree) {
+      if (degree === 0) {
+        queue.push(node);
+      }
+    }
+
+    while (queue.length > 0) {
+      const node = queue.shift()!;
+      result.push(node);
+
+      // Reduce in-degree for dependent nodes
+      const dependents = graph.get(node) || [];
+      for (const dependent of dependents) {
+        const newDegree = (inDegree.get(dependent) || 0) - 1;
+        inDegree.set(dependent, newDegree);
+        
+        if (newDegree === 0) {
+          queue.push(dependent);
+        }
+      }
+    }
+
+    // Check for circular dependencies
+    if (result.length !== plugins.size) {
+      const remaining = Array.from(plugins.keys()).filter(p => !result.includes(p));
+      this.logger.error('Circular dependency detected', { remaining });
+      throw new Error(`Circular dependency detected among: ${remaining.join(', ')}`);
+    }
+
+    this.logger.debug('Dependencies resolved', { order: result });
+    return result;
+  }
+
+  /**
+   * Detect dependency conflicts
+   */
+  detectConflicts(
+    plugins: Map<string, { version: string; dependencies?: Record<string, VersionConstraint> }>
+  ): DependencyConflict[] {
+    const conflicts: DependencyConflict[] = [];
+    const versionRequirements = new Map<string, Map<string, VersionConstraint>>();
+
+    // Collect all version requirements
+    for (const [pluginName, pluginInfo] of plugins) {
+      if (!pluginInfo.dependencies) continue;
+
+      for (const [depName, constraint] of Object.entries(pluginInfo.dependencies)) {
+        if (!versionRequirements.has(depName)) {
+          versionRequirements.set(depName, new Map());
+        }
+        versionRequirements.get(depName)!.set(pluginName, constraint);
+      }
+    }
+
+    // Check for version mismatches
+    for (const [depName, requirements] of versionRequirements) {
+      const depInfo = plugins.get(depName);
+      if (!depInfo) continue;
+
+      const depVersion = SemanticVersionManager.parse(depInfo.version);
+      const unsatisfied: Array<{ pluginId: string; version: string }> = [];
+
+      for (const [requiringPlugin, constraint] of requirements) {
+        if (!SemanticVersionManager.satisfies(depVersion, constraint)) {
+          unsatisfied.push({
+            pluginId: requiringPlugin,
+            version: constraint as string,
+          });
+        }
+      }
+
+      if (unsatisfied.length > 0) {
+        conflicts.push({
+          type: 'version-mismatch',
+          severity: 'error',
+          description: `Version mismatch for ${depName}: detected ${unsatisfied.length} unsatisfied requirements`,
+          plugins: [
+            { pluginId: depName, version: depInfo.version },
+            ...unsatisfied,
+          ],
+          resolutions: [{
+            strategy: 'upgrade',
+            description: `Upgrade ${depName} to satisfy all constraints`,
+            targetPlugins: [depName],
+            automatic: false,
+          } as any],
+        });
+      }
+    }
+
+    // Check for circular dependencies (will be caught by resolve())
+    try {
+      this.resolve(new Map(
+        Array.from(plugins.entries()).map(([name, info]) => [
+          name,
+          { version: info.version, dependencies: info.dependencies ? Object.keys(info.dependencies) : [] }
+        ])
+      ));
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('Circular dependency')) {
+        conflicts.push({
+          type: 'circular-dependency',
+          severity: 'critical',
+          description: error.message,
+          plugins: [], // Would need to extract from error
+          resolutions: [{
+            strategy: 'manual',
+            description: 'Remove circular dependency by restructuring plugins',
+            automatic: false,
+          } as any],
+        });
+      }
+    }
+
+    return conflicts;
+  }
+
+  /**
+   * Find best version that satisfies all constraints
+   */
+  findBestVersion(
+    availableVersions: string[],
+    constraints: VersionConstraint[]
+  ): string | undefined {
+    // Parse and sort versions (highest first)
+    const versions = availableVersions
+      .map(v => ({ str: v, parsed: SemanticVersionManager.parse(v) }))
+      .sort((a, b) => -SemanticVersionManager.compare(a.parsed, b.parsed));
+
+    // Find highest version that satisfies all constraints
+    for (const version of versions) {
+      const satisfiesAll = constraints.every(constraint =>
+        SemanticVersionManager.satisfies(version.parsed, constraint)
+      );
+
+      if (satisfiesAll) {
+        return version.str;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Check if dependencies form a valid DAG (no cycles)
+   */
+  isAcyclic(dependencies: Map<string, string[]>): boolean {
+    try {
+      const plugins = new Map(
+        Array.from(dependencies.entries()).map(([name, deps]) => [
+          name,
+          { dependencies: deps }
+        ])
+      );
+      this.resolve(plugins);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}