@principal-ai/principal-view-core 0.5.6

package/src/utils/GraphConverter.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test } from 'bun:test';
+import { GraphConverter } from './GraphConverter';
+import type { PathBasedGraphConfiguration } from '../types/path-based-config';
+
+describe('GraphConverter', () => {
+  test('should convert simple config to nodes and edges', () => {
+    const config: PathBasedGraphConfiguration = {
+      metadata: {
+        name: 'Test Config',
+        version: '1.0.0',
+      },
+      nodeTypes: {
+        'node-a': {
+          shape: 'circle',
+          icon: 'user',
+          color: '#3b82f6',
+          dataSchema: {},
+        },
+        'node-b': {
+          shape: 'rectangle',
+          icon: 'server',
+          color: '#8b5cf6',
+          dataSchema: {},
+        },
+      },
+      edgeTypes: {
+        'connection': {
+          style: 'solid',
+          color: '#64748b',
+          width: 2,
+          directed: true,
+        },
+      },
+      allowedConnections: [
+        {
+          from: 'node-a',
+          to: 'node-b',
+          via: 'connection',
+        },
+      ],
+    };
+
+    const result = GraphConverter.configToGraph(config);
+
+    expect(result.nodes).toHaveLength(2);
+    expect(result.edges).toHaveLength(1);
+
+    // Check nodes
+    expect(result.nodes[0].id).toBe('node-a');
+    expect(result.nodes[0].type).toBe('node-a');
+    expect(result.nodes[0].data.shape).toBe('circle');
+    expect(result.nodes[0].data.icon).toBe('user');
+
+    expect(result.nodes[1].id).toBe('node-b');
+    expect(result.nodes[1].type).toBe('node-b');
+    expect(result.nodes[1].data.shape).toBe('rectangle');
+
+    // Check edges
+    expect(result.edges[0].from).toBe('node-a');
+    expect(result.edges[0].to).toBe('node-b');
+    expect(result.edges[0].type).toBe('connection');
+    expect(result.edges[0].data.style).toBe('solid');
+  });
+
+  test('should extract manual positions from node types', () => {
+    const config: PathBasedGraphConfiguration = {
+      metadata: {
+        name: 'Test Config',
+        version: '1.0.0',
+      },
+      nodeTypes: {
+        'node-a': {
+          shape: 'circle',
+          color: '#3b82f6',
+          dataSchema: {},
+          position: { x: 100, y: 200 },
+        },
+        'node-b': {
+          shape: 'rectangle',
+          color: '#8b5cf6',
+          dataSchema: {},
+          position: { x: 300, y: 400 },
+        },
+      },
+      edgeTypes: {},
+      allowedConnections: [],
+    };
+
+    const result = GraphConverter.configToGraph(config);
+
+    expect(result.nodes[0].position).toEqual({ x: 100, y: 200 });
+    expect(result.nodes[1].position).toEqual({ x: 300, y: 400 });
+  });
+
+  test('should handle nodes without positions', () => {
+    const config: PathBasedGraphConfiguration = {
+      metadata: {
+        name: 'Test Config',
+        version: '1.0.0',
+      },
+      nodeTypes: {
+        'node-a': {
+          shape: 'circle',
+          color: '#3b82f6',
+          dataSchema: {},
+        },
+      },
+      edgeTypes: {},
+      allowedConnections: [],
+    };
+
+    const result = GraphConverter.configToGraph(config);
+
+    expect(result.nodes[0].position).toBeUndefined();
+  });
+
+  test('should include source paths and actions in node data', () => {
+    const config: PathBasedGraphConfiguration = {
+      metadata: {
+        name: 'Test Config',
+        version: '1.0.0',
+      },
+      nodeTypes: {
+        'node-a': {
+          shape: 'circle',
+          color: '#3b82f6',
+          dataSchema: {},
+          sources: ['src/api/**/*.ts'],
+          actions: [
+            {
+              pattern: 'Lock acquired: (?<lockId>.*)',
+              event: 'lock-acquired',
+              state: 'locked',
+            },
+          ],
+        },
+      },
+      edgeTypes: {},
+      allowedConnections: [],
+    };
+
+    const result = GraphConverter.configToGraph(config);
+
+    expect(result.nodes[0].data.sources).toEqual(['src/api/**/*.ts']);
+    expect(result.nodes[0].data.actions).toHaveLength(1);
+    expect(result.nodes[0].data.actions[0].event).toBe('lock-acquired');
+  });
+
+  test('should handle edge animation config', () => {
+    const config: PathBasedGraphConfiguration = {
+      metadata: {
+        name: 'Test Config',
+        version: '1.0.0',
+      },
+      nodeTypes: {
+        'node-a': {
+          shape: 'circle',
+          color: '#3b82f6',
+          dataSchema: {},
+        },
+        'node-b': {
+          shape: 'rectangle',
+          color: '#8b5cf6',
+          dataSchema: {},
+        },
+      },
+      edgeTypes: {
+        'animated-flow': {
+          style: 'solid',
+          color: '#3b82f6',
+          width: 3,
+          animation: {
+            type: 'flow',
+            duration: 1500,
+            color: '#60a5fa',
+          },
+        },
+      },
+      allowedConnections: [
+        {
+          from: 'node-a',
+          to: 'node-b',
+          via: 'animated-flow',
+        },
+      ],
+    };
+
+    const result = GraphConverter.configToGraph(config);
+
+    expect(result.edges[0].data.animation).toBeDefined();
+    expect(result.edges[0].data.animation?.type).toBe('flow');
+    expect(result.edges[0].data.animation?.duration).toBe(1500);
+    expect(result.edges[0].data.animation?.color).toBe('#60a5fa');
+  });
+});

package/src/utils/GraphConverter.ts

@@ -0,0 +1,71 @@
+/**
+ * Utility for converting PathBasedGraphConfiguration to nodes and edges
+ */
+
+import type { PathBasedGraphConfiguration } from '../types/path-based-config';
+import type { NodeState, EdgeState } from '../types';
+
+/**
+ * Converts PathBasedGraphConfiguration to graph state (nodes and edges)
+ */
+export class GraphConverter {
+  /**
+   * Convert configuration to nodes and edges
+   */
+  static configToGraph(config: PathBasedGraphConfiguration): {
+    nodes: NodeState[];
+    edges: EdgeState[];
+  } {
+    const nodes: NodeState[] = [];
+    const edges: EdgeState[] = [];
+    const now = Date.now();
+
+    // Create nodes from nodeTypes
+    Object.entries(config.nodeTypes).forEach(([id, nodeType]) => {
+      nodes.push({
+        id,
+        type: id,
+        data: {
+          label: id,
+          shape: nodeType.shape,
+          icon: nodeType.icon,
+          color: nodeType.color,
+          size: nodeType.size,
+          sources: nodeType.sources || [],
+          actions: nodeType.actions || [],
+          ...nodeType.dataSchema,
+        },
+        // Extract position if provided in manual layout mode
+        position: nodeType.position,
+        state: 'idle',
+        createdAt: now,
+        updatedAt: now,
+      });
+    });
+
+    // Create edges from allowedConnections
+    if (config.allowedConnections) {
+      config.allowedConnections.forEach((connection, index) => {
+        const edgeType = config.edgeTypes?.[connection.via];
+
+        edges.push({
+          id: `${connection.from}-${connection.to}-${index}`,
+          type: connection.via,
+          from: connection.from,
+          to: connection.to,
+          data: {
+            label: connection.via,
+            style: edgeType?.style || 'solid',
+            color: edgeType?.color,
+            width: edgeType?.width,
+            animation: edgeType?.animation,
+          },
+          createdAt: now,
+          updatedAt: now,
+        });
+      });
+    }
+
+    return { nodes, edges };
+  }
+}

package/src/utils/LibraryConverter.ts

@@ -0,0 +1,245 @@
+/**
+ * Library Converter
+ *
+ * Utilities for converting library components to canvas nodes/edges.
+ * Used when adding components from the library to a canvas.
+ */
+
+import type { LibraryNodeComponent, LibraryEdgeComponent, ComponentLibrary } from '../types/library';
+import type {
+  ExtendedCanvasTextNode,
+  ExtendedCanvasEdge,
+  PVNodeExtension,
+  PVEdgeExtension,
+  PVEdgeTypeDefinition,
+} from '../types/canvas';
+
+/**
+ * Options for creating a canvas node from a library component
+ */
+export interface CreateNodeOptions {
+  /** Unique ID for the node */
+  id: string;
+
+  /** X position in pixels */
+  x: number;
+
+  /** Y position in pixels */
+  y: number;
+
+  /** Optional label override (defaults to component's defaultLabel or the component key) */
+  label?: string;
+
+  /** Optional initial data values */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Options for creating a canvas edge from a library component
+ */
+export interface CreateEdgeOptions {
+  /** Unique ID for the edge */
+  id: string;
+
+  /** Source node ID */
+  fromNode: string;
+
+  /** Target node ID */
+  toNode: string;
+
+  /** Optional label */
+  label?: string;
+
+  /** Optional side of source node */
+  fromSide?: 'top' | 'right' | 'bottom' | 'left';
+
+  /** Optional side of target node */
+  toSide?: 'top' | 'right' | 'bottom' | 'left';
+}
+
+/**
+ * Library Converter utility class
+ */
+export class LibraryConverter {
+  /**
+   * Create a canvas node from a library node component
+   *
+   * @param componentKey - The key of the component in the library
+   * @param component - The library node component definition
+   * @param options - Node creation options (id, position, etc.)
+   * @returns Extended canvas text node ready to add to a canvas
+   */
+  static createCanvasNode(
+    componentKey: string,
+    component: LibraryNodeComponent,
+    options: CreateNodeOptions
+  ): ExtendedCanvasTextNode {
+    const { id, x, y, label, data } = options;
+
+    // Build the PV extension from the library component
+    const pv: PVNodeExtension = {
+      nodeType: componentKey,
+      shape: component.shape,
+      icon: component.icon,
+      states: component.states,
+      sources: component.sources,
+      actions: component.actions,
+      dataSchema: component.dataSchema,
+      layout: component.layout,
+    };
+
+    // Build the canvas node
+    const node: ExtendedCanvasTextNode = {
+      id,
+      type: 'text',
+      text: label || component.defaultLabel || componentKey,
+      x,
+      y,
+      width: component.size?.width || 120,
+      height: component.size?.height || 60,
+      color: component.color,
+      pv,
+    };
+
+    // If there's initial data, merge it with the text
+    if (data) {
+      // Store additional data in the pv extension
+      // The data will be accessible via the node's data field when converted to React Flow
+      (pv as PVNodeExtension & { initialData?: Record<string, unknown> }).initialData = data;
+    }
+
+    return node;
+  }
+
+  /**
+   * Create a canvas edge from a library edge component
+   *
+   * @param componentKey - The key of the component in the library
+   * @param component - The library edge component definition
+   * @param options - Edge creation options
+   * @returns Extended canvas edge ready to add to a canvas
+   */
+  static createCanvasEdge(
+    componentKey: string,
+    component: LibraryEdgeComponent,
+    options: CreateEdgeOptions
+  ): ExtendedCanvasEdge {
+    const { id, fromNode, toNode, label, fromSide, toSide } = options;
+
+    // Build the PV extension
+    const pv: PVEdgeExtension = {
+      edgeType: componentKey,
+      style: component.style,
+      width: component.width,
+      animation: component.animation,
+    };
+
+    // Build the canvas edge
+    const edge: ExtendedCanvasEdge = {
+      id,
+      fromNode,
+      toNode,
+      label,
+      fromSide,
+      toSide,
+      color: component.color,
+      toEnd: component.directed !== false ? 'arrow' : 'none',
+      pv,
+    };
+
+    return edge;
+  }
+
+  /**
+   * Convert library edge components to canvas-level edge type definitions
+   *
+   * This is useful when initializing a new canvas from a library.
+   *
+   * @param edgeComponents - Library edge components
+   * @returns Record of edge type definitions for the canvas pv.edgeTypes field
+   */
+  static createEdgeTypeDefinitions(
+    edgeComponents: Record<string, LibraryEdgeComponent>
+  ): Record<string, PVEdgeTypeDefinition> {
+    const edgeTypes: Record<string, PVEdgeTypeDefinition> = {};
+
+    for (const [key, component] of Object.entries(edgeComponents)) {
+      edgeTypes[key] = {
+        style: component.style,
+        color: component.color,
+        width: component.width,
+        directed: component.directed,
+        animation: component.animation,
+        labelConfig: component.label,
+      };
+    }
+
+    return edgeTypes;
+  }
+
+  /**
+   * Generate a unique ID for a new node
+   *
+   * @param prefix - Optional prefix (defaults to 'node')
+   * @returns Unique ID string
+   */
+  static generateNodeId(prefix = 'node'): string {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  /**
+   * Generate a unique ID for a new edge
+   *
+   * @param fromNode - Source node ID
+   * @param toNode - Target node ID
+   * @returns Unique ID string
+   */
+  static generateEdgeId(fromNode: string, toNode: string): string {
+    return `edge-${fromNode}-${toNode}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  /**
+   * Get all node component keys that match the given tags
+   *
+   * @param library - Component library
+   * @param tags - Tags to filter by (matches if component has ANY of these tags)
+   * @returns Array of component keys
+   */
+  static filterNodesByTags(library: ComponentLibrary, tags: string[]): string[] {
+    return Object.entries(library.nodeComponents)
+      .filter(([, component]) => component.tags?.some((tag) => tags.includes(tag)))
+      .map(([key]) => key);
+  }
+
+  /**
+   * Get all edge component keys that match the given tags
+   *
+   * @param library - Component library
+   * @param tags - Tags to filter by (matches if component has ANY of these tags)
+   * @returns Array of component keys
+   */
+  static filterEdgesByTags(library: ComponentLibrary, tags: string[]): string[] {
+    return Object.entries(library.edgeComponents)
+      .filter(([, component]) => component.tags?.some((tag) => tags.includes(tag)))
+      .map(([key]) => key);
+  }
+
+  /**
+   * Get allowed edge types between two node types based on connection rules
+   *
+   * @param library - Component library
+   * @param fromNodeType - Source node type key
+   * @param toNodeType - Target node type key
+   * @returns Array of allowed edge type keys
+   */
+  static getAllowedEdgeTypes(library: ComponentLibrary, fromNodeType: string, toNodeType: string): string[] {
+    if (!library.connectionRules) {
+      // If no rules defined, allow any edge type
+      return Object.keys(library.edgeComponents);
+    }
+
+    return library.connectionRules
+      .filter((rule) => rule.from === fromNodeType && rule.to === toNodeType)
+      .map((rule) => rule.via);
+  }
+}

package/src/utils/PathMatcher.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'bun:test';
+import { PathMatcher } from './PathMatcher';
+
+describe('PathMatcher', () => {
+  describe('exact matches', () => {
+    it('should match exact paths', () => {
+      expect(PathMatcher.matches('lib/lock-manager.ts', 'lib/lock-manager.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/lock-manager.ts', 'lib/github-api.ts')).toBe(false);
+    });
+
+    it('should normalize path separators', () => {
+      expect(PathMatcher.matches('lib\\lock-manager.ts', 'lib/lock-manager.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/lock-manager.ts', 'lib\\lock-manager.ts')).toBe(true);
+    });
+  });
+
+  describe('wildcard patterns', () => {
+    it('should match * (single segment wildcard)', () => {
+      expect(PathMatcher.matches('lib/lock-manager.ts', 'lib/*.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/github-api.ts', 'lib/*.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/foo/bar.ts', 'lib/*.ts')).toBe(false); // * doesn't cross directories
+    });
+
+    it('should match ** (recursive wildcard)', () => {
+      expect(PathMatcher.matches('lib/lock-manager.ts', 'lib/**/*.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/foo/bar.ts', 'lib/**/*.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/foo/baz/qux.ts', 'lib/**/*.ts')).toBe(true);
+      expect(PathMatcher.matches('src/index.ts', 'lib/**/*.ts')).toBe(false);
+    });
+
+    it('should match ? (single character)', () => {
+      expect(PathMatcher.matches('lib/a.ts', 'lib/?.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/b.ts', 'lib/?.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/ab.ts', 'lib/?.ts')).toBe(false);
+    });
+  });
+
+  describe('character sets', () => {
+    it('should match [abc] patterns', () => {
+      expect(PathMatcher.matches('lib/a.ts', 'lib/[abc].ts')).toBe(true);
+      expect(PathMatcher.matches('lib/b.ts', 'lib/[abc].ts')).toBe(true);
+      expect(PathMatcher.matches('lib/c.ts', 'lib/[abc].ts')).toBe(true);
+      expect(PathMatcher.matches('lib/d.ts', 'lib/[abc].ts')).toBe(false);
+    });
+
+    it('should match [a-z] range patterns', () => {
+      expect(PathMatcher.matches('lib/a.ts', 'lib/[a-z].ts')).toBe(true);
+      expect(PathMatcher.matches('lib/m.ts', 'lib/[a-z].ts')).toBe(true);
+      expect(PathMatcher.matches('lib/z.ts', 'lib/[a-z].ts')).toBe(true);
+      expect(PathMatcher.matches('lib/A.ts', 'lib/[a-z].ts')).toBe(false);
+    });
+  });
+
+  describe('alternatives', () => {
+    it('should match {a,b,c} alternatives', () => {
+      expect(PathMatcher.matches('lib/foo.ts', 'lib/{foo,bar,baz}.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/bar.ts', 'lib/{foo,bar,baz}.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/baz.ts', 'lib/{foo,bar,baz}.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/qux.ts', 'lib/{foo,bar,baz}.ts')).toBe(false);
+    });
+
+    it('should match nested alternatives', () => {
+      expect(PathMatcher.matches('lib/services/api.ts', '{lib,src}/**/*.ts')).toBe(true);
+      expect(PathMatcher.matches('src/components/App.tsx', '{lib,src}/**/*.{ts,tsx}')).toBe(true);
+    });
+  });
+
+  describe('complex patterns', () => {
+    it('should match combined patterns', () => {
+      const pattern = 'lib/{services,utils}/**/*.{ts,js}';
+      expect(PathMatcher.matches('lib/services/api.ts', pattern)).toBe(true);
+      expect(PathMatcher.matches('lib/utils/helper.js', pattern)).toBe(true);
+      expect(PathMatcher.matches('lib/models/user.ts', pattern)).toBe(false);
+    });
+  });
+
+  describe('findMatches', () => {
+    it('should return all matching patterns', () => {
+      const patterns = [
+        'lib/lock-manager.ts',
+        'lib/*.ts',
+        'lib/**/*.ts',
+        'src/**/*.ts'
+      ];
+
+      const matches = PathMatcher.findMatches('lib/lock-manager.ts', patterns);
+      expect(matches).toEqual([
+        'lib/lock-manager.ts',
+        'lib/*.ts',
+        'lib/**/*.ts'
+      ]);
+    });
+
+    it('should return empty array when no patterns match', () => {
+      const patterns = ['src/**/*.ts', 'test/**/*.ts'];
+      const matches = PathMatcher.findMatches('lib/lock-manager.ts', patterns);
+      expect(matches).toEqual([]);
+    });
+  });
+
+  describe('isGlob', () => {
+    it('should detect glob patterns', () => {
+      expect(PathMatcher.isGlob('lib/*.ts')).toBe(true);
+      expect(PathMatcher.isGlob('lib/**/*.ts')).toBe(true);
+      expect(PathMatcher.isGlob('lib/?.ts')).toBe(true);
+      expect(PathMatcher.isGlob('lib/[abc].ts')).toBe(true);
+      expect(PathMatcher.isGlob('lib/{a,b}.ts')).toBe(true);
+    });
+
+    it('should not detect non-glob patterns', () => {
+      expect(PathMatcher.isGlob('lib/lock-manager.ts')).toBe(false);
+      expect(PathMatcher.isGlob('lib/services/api.ts')).toBe(false);
+    });
+  });
+
+  describe('getBaseDir', () => {
+    it('should extract base directory from glob patterns', () => {
+      expect(PathMatcher.getBaseDir('lib/**/*.ts')).toBe('lib');
+      expect(PathMatcher.getBaseDir('lib/services/**/*.ts')).toBe('lib/services');
+      expect(PathMatcher.getBaseDir('lib/*.ts')).toBe('lib');
+      expect(PathMatcher.getBaseDir('**/*.ts')).toBe('');
+    });
+
+    it('should handle non-glob patterns', () => {
+      expect(PathMatcher.getBaseDir('lib/lock-manager.ts')).toBe('lib');
+      expect(PathMatcher.getBaseDir('lib/services/api.ts')).toBe('lib/services');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty paths', () => {
+      expect(PathMatcher.matches('', '')).toBe(true);
+      expect(PathMatcher.matches('lib/foo.ts', '')).toBe(false);
+      expect(PathMatcher.matches('', '**')).toBe(true);
+    });
+
+    it('should handle special characters in paths', () => {
+      expect(PathMatcher.matches('lib/foo-bar.ts', 'lib/*.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/foo_bar.ts', 'lib/*.ts')).toBe(true);
+      expect(PathMatcher.matches('lib/foo.bar.ts', 'lib/*.ts')).toBe(true);
+    });
+
+    it('should not match across directory boundaries with *', () => {
+      expect(PathMatcher.matches('lib/services/api.ts', 'lib/*.ts')).toBe(false);
+      expect(PathMatcher.matches('lib/services/api.ts', 'lib/**/*.ts')).toBe(true);
+    });
+  });
+});