@principal-ai/subsystems-core 0.29.0

package/src/LibraryLoader.ts

@@ -0,0 +1,194 @@
+/**
+ * Library Loader
+ *
+ * Loads component library files (.yaml, .yml, or .json) from the .principal-views/ folder.
+ * Component libraries contain reusable node and edge type definitions.
+ */
+
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import type { ComponentLibrary, LibraryLoadResult } from './types/library';
+import { validateLibraryStructure } from './validation/libraryValidation';
+import * as yaml from 'js-yaml';
+
+/**
+ * Default library file names to search for (in order of preference)
+ */
+const DEFAULT_LIBRARY_FILES = ['library.yaml', 'library.yml', 'library.json'];
+
+/**
+ * Configuration directory name
+ */
+const CONFIG_DIR = '.principal-views';
+
+/**
+ * Loader for component library files
+ */
+export class LibraryLoader {
+  constructor(private fsAdapter: FileSystemAdapter) {}
+
+  /**
+   * Load the component library from the .principal-views/ folder
+   *
+   * Searches for library.yaml, library.yml, or library.json (in that order).
+   *
+   * @param baseDir - Base directory containing .principal-views/ folder
+   * @returns Library load result
+   */
+  async load(baseDir: string): Promise<LibraryLoadResult> {
+    const configPath = this.fsAdapter.join(baseDir, CONFIG_DIR);
+
+    // Check if .principal-views directory exists
+    const configExists = await this.fsAdapter.exists(configPath);
+    const isDir = configExists ? await this.fsAdapter.isDirectory(configPath) : false;
+
+    if (!configExists || !isDir) {
+      return {
+        success: false,
+        error: 'Configuration directory .principal-views/ not found',
+        path: configPath,
+      };
+    }
+
+    // Try each default library file name
+    for (const fileName of DEFAULT_LIBRARY_FILES) {
+      const fullPath = this.fsAdapter.join(configPath, fileName);
+
+      if (await this.fsAdapter.exists(fullPath)) {
+        return this.loadFromPath(fullPath);
+      }
+    }
+
+    return {
+      success: false,
+      error: `No library file found. Expected one of: ${DEFAULT_LIBRARY_FILES.join(', ')}`,
+      path: configPath,
+    };
+  }
+
+  /**
+   * Load a library from a specific file path
+   *
+   * @param filePath - Full path to the library file
+   * @returns Library load result
+   */
+  async loadFromPath(filePath: string): Promise<LibraryLoadResult> {
+    try {
+      const content = await this.fsAdapter.readFile(filePath);
+      const isJson = filePath.endsWith('.json');
+
+      const library = isJson
+        ? this.parseJson(content, filePath)
+        : this.parseYaml(content, filePath);
+
+      const validationError = this.validate(library, filePath);
+      if (validationError) {
+        return {
+          success: false,
+          error: validationError,
+          path: filePath,
+        };
+      }
+
+      return {
+        success: true,
+        library,
+        path: filePath,
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        error: `Failed to load library: ${errorMessage}`,
+        path: filePath,
+      };
+    }
+  }
+
+  /**
+   * Check if a library file exists in the .principal-views/ folder
+   *
+   * @param baseDir - Base directory containing .principal-views/ folder
+   * @returns True if a library file exists
+   */
+  async hasLibrary(baseDir: string): Promise<boolean> {
+    const configPath = this.fsAdapter.join(baseDir, CONFIG_DIR);
+
+    const configExists = await this.fsAdapter.exists(configPath);
+    if (!configExists) {
+      return false;
+    }
+
+    const isDir = await this.fsAdapter.isDirectory(configPath);
+    if (!isDir) {
+      return false;
+    }
+
+    for (const fileName of DEFAULT_LIBRARY_FILES) {
+      const fullPath = this.fsAdapter.join(configPath, fileName);
+      if (await this.fsAdapter.exists(fullPath)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get the path where the library file would be located
+   *
+   * @param baseDir - Base directory
+   * @param format - Preferred format ('yaml' or 'json')
+   * @returns Full path to the library file
+   */
+  getLibraryPath(baseDir: string, format: 'yaml' | 'json' = 'yaml'): string {
+    const fileName = format === 'json' ? 'library.json' : 'library.yaml';
+    return this.fsAdapter.join(baseDir, CONFIG_DIR, fileName);
+  }
+
+  /**
+   * Parse YAML content into a library object
+   */
+  private parseYaml(content: string, filePath: string): ComponentLibrary {
+    const data = yaml.load(content);
+
+    if (!data || typeof data !== 'object') {
+      throw new Error(`Empty or invalid YAML in ${filePath}`);
+    }
+
+    return data as ComponentLibrary;
+  }
+
+  /**
+   * Parse JSON content into a library object
+   */
+  private parseJson(content: string, filePath: string): ComponentLibrary {
+    try {
+      const data = JSON.parse(content);
+      return data as ComponentLibrary;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Invalid JSON in ${filePath}: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Validate the library structure
+   *
+   * Uses the shared validateLibraryStructure function from validation module.
+   *
+   * @param library - Parsed library object
+   * @param filePath - File path for error messages
+   * @returns Error message if invalid, undefined if valid
+   */
+  private validate(library: ComponentLibrary, filePath: string): string | undefined {
+    const result = validateLibraryStructure(library);
+
+    if (!result.valid && result.errors.length > 0) {
+      // Return the first error with file path context
+      const firstError = result.errors[0];
+      return `${firstError.message} in ${filePath}`;
+    }
+
+    return undefined;
+  }
+}

package/src/PathBasedEventProcessor.test.ts

@@ -0,0 +1,336 @@
+import { describe, it, expect } from 'bun:test';
+import { PathBasedEventProcessor, type LogEntry } from './PathBasedEventProcessor';
+import type {
+  PathBasedGraphConfiguration,
+  ComponentActivityEvent,
+} from './types/path-based-config';
+
+describe('PathBasedEventProcessor', () => {
+  // Sample configuration
+  const sampleConfig: PathBasedGraphConfiguration = {
+    metadata: {
+      name: 'Test System',
+      version: '1.0.0',
+    },
+    nodeTypes: {
+      'lock-manager': {
+        shape: 'rectangle',
+        icon: 'lock',
+        color: '#3b82f6',
+        dataSchema: {},
+        sources: ['lib/lock-manager.ts', 'lib/branch-aware-lock-manager.ts'],
+      },
+      'github-api': {
+        shape: 'hexagon',
+        icon: 'github',
+        color: '#22c55e',
+        dataSchema: {},
+        sources: ['lib/github-api-client.ts', 'services/github/*.ts'],
+      },
+      'request-handler': {
+        shape: 'rectangle',
+        icon: 'server',
+        color: '#f59e0b',
+        dataSchema: {},
+        sources: ['app/**/*.ts'],
+      },
+    },
+    edgeTypes: {},
+    allowedConnections: [],
+  };
+
+  describe('Milestone 1: Basic path-based association', () => {
+    it('should associate log with component by exact path match', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const log: LogEntry = {
+        message: 'Lock acquired',
+        metadata: {
+          timestamp: Date.now(),
+          level: 'info',
+          source: {
+            file: 'lib/lock-manager.ts',
+            line: 42,
+          },
+        },
+      };
+
+      const events = processor.processLog(log);
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe('component-activity');
+      const activityEvent = events[0] as ComponentActivityEvent;
+      expect(activityEvent.componentId).toBe('lock-manager');
+      expect(activityEvent.level).toBe('info');
+      expect(activityEvent.message).toBe('Lock acquired');
+    });
+
+    it('should associate log with component by glob pattern match', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const log: LogEntry = {
+        message: 'GitHub API call',
+        metadata: {
+          timestamp: Date.now(),
+          level: 'debug',
+          source: {
+            file: 'services/github/client.ts',
+            line: 10,
+          },
+        },
+      };
+
+      const events = processor.processLog(log);
+
+      expect(events).toHaveLength(1);
+      const activityEvent = events[0] as ComponentActivityEvent;
+      expect(activityEvent.componentId).toBe('github-api');
+    });
+
+    it('should associate log with component using ** wildcard', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const log: LogEntry = {
+        message: 'Request received',
+        metadata: {
+          timestamp: Date.now(),
+          level: 'info',
+          source: {
+            file: 'app/handlers/webhook.ts',
+            line: 5,
+          },
+        },
+      };
+
+      const events = processor.processLog(log);
+
+      expect(events).toHaveLength(1);
+      const activityEvent = events[0] as ComponentActivityEvent;
+      expect(activityEvent.componentId).toBe('request-handler');
+    });
+
+    it('should return empty array for logs without source', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const log: LogEntry = {
+        message: 'No source info',
+        metadata: {
+          timestamp: Date.now(),
+          level: 'info',
+        },
+      };
+
+      const events = processor.processLog(log);
+      expect(events).toHaveLength(0);
+    });
+
+    it('should return empty array for logs that do not match any component', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const log: LogEntry = {
+        message: 'Unmatched log',
+        metadata: {
+          timestamp: Date.now(),
+          level: 'info',
+          source: {
+            file: 'test/foo.ts',
+            line: 1,
+          },
+        },
+      };
+
+      const events = processor.processLog(log);
+      expect(events).toHaveLength(0);
+    });
+
+    it('should preserve log level in activity event', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const levels = ['debug', 'info', 'warn', 'error'] as const;
+
+      for (const level of levels) {
+        const log: LogEntry = {
+          message: `${level} message`,
+          metadata: {
+            timestamp: Date.now(),
+            level,
+            source: {
+              file: 'lib/lock-manager.ts',
+              line: 1,
+            },
+          },
+        };
+
+        const events = processor.processLog(log);
+        expect(events).toHaveLength(1);
+        const activityEvent = events[0] as ComponentActivityEvent;
+        expect(activityEvent.level).toBe(level);
+      }
+    });
+
+    it('should batch process multiple logs', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const logs: LogEntry[] = [
+        {
+          message: 'Log 1',
+          metadata: {
+            timestamp: Date.now(),
+            level: 'info',
+            source: { file: 'lib/lock-manager.ts' },
+          },
+        },
+        {
+          message: 'Log 2',
+          metadata: {
+            timestamp: Date.now(),
+            level: 'info',
+            source: { file: 'lib/github-api-client.ts' },
+          },
+        },
+        {
+          message: 'Log 3',
+          metadata: {
+            timestamp: Date.now(),
+            level: 'warn',
+            source: { file: 'app/main.ts' },
+          },
+        },
+      ];
+
+      const events = processor.processLogs(logs);
+      expect(events).toHaveLength(3);
+      expect((events[0] as ComponentActivityEvent).componentId).toBe('lock-manager');
+      expect((events[1] as ComponentActivityEvent).componentId).toBe('github-api');
+      expect((events[2] as ComponentActivityEvent).componentId).toBe('request-handler');
+    });
+  });
+
+  describe('Validation', () => {
+    it('should detect overlapping source patterns', () => {
+      const configWithOverlap: PathBasedGraphConfiguration = {
+        ...sampleConfig,
+        nodeTypes: {
+          'comp-a': {
+            shape: 'rectangle',
+            dataSchema: {},
+            sources: ['lib/*.ts'],
+          },
+          'comp-b': {
+            shape: 'circle',
+            dataSchema: {},
+            sources: ['lib/*.ts'], // Same pattern!
+          },
+        },
+      };
+
+      const processor = new PathBasedEventProcessor(configWithOverlap);
+      const issues = processor.validate();
+
+      expect(issues.length).toBeGreaterThan(0);
+      expect(issues[0].type).toBe('warning');
+      expect(issues[0].message).toContain('both use pattern');
+    });
+  });
+
+  describe('Statistics', () => {
+    it('should return correct stats', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+      const stats = processor.getStats();
+
+      expect(stats.totalComponents).toBe(3);
+      expect(stats.componentsWithSources).toBe(3);
+      expect(stats.totalSourcePatterns).toBe(5); // Sum of all source patterns
+    });
+  });
+
+  describe('Instance ID support', () => {
+    it('should include instanceId in activity event when provided', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const log: LogEntry = {
+        message: 'Client connected',
+        metadata: {
+          timestamp: Date.now(),
+          level: 'info',
+          source: {
+            file: 'lib/lock-manager.ts',
+            line: 42,
+          },
+          instanceId: 'client-1',
+        },
+      };
+
+      const events = processor.processLog(log);
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe('component-activity');
+      const activityEvent = events[0] as ComponentActivityEvent;
+      expect(activityEvent.componentId).toBe('lock-manager');
+      expect(activityEvent.instanceId).toBe('client-1');
+    });
+
+    it('should have undefined instanceId when not provided', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const log: LogEntry = {
+        message: 'Client connected',
+        metadata: {
+          timestamp: Date.now(),
+          level: 'info',
+          source: {
+            file: 'lib/lock-manager.ts',
+            line: 42,
+          },
+          // No instanceId
+        },
+      };
+
+      const events = processor.processLog(log);
+
+      expect(events).toHaveLength(1);
+      const activityEvent = events[0] as ComponentActivityEvent;
+      expect(activityEvent.instanceId).toBeUndefined();
+    });
+
+    it('should preserve instanceId across batch processing', () => {
+      const processor = new PathBasedEventProcessor(sampleConfig);
+
+      const logs: LogEntry[] = [
+        {
+          message: 'Log from client 1',
+          metadata: {
+            timestamp: Date.now(),
+            level: 'info',
+            source: { file: 'lib/lock-manager.ts' },
+            instanceId: 'client-1',
+          },
+        },
+        {
+          message: 'Log from client 2',
+          metadata: {
+            timestamp: Date.now(),
+            level: 'info',
+            source: { file: 'lib/lock-manager.ts' },
+            instanceId: 'client-2',
+          },
+        },
+        {
+          message: 'Log without instance',
+          metadata: {
+            timestamp: Date.now(),
+            level: 'info',
+            source: { file: 'lib/lock-manager.ts' },
+          },
+        },
+      ];
+
+      const events = processor.processLogs(logs);
+
+      expect(events).toHaveLength(3);
+      expect((events[0] as ComponentActivityEvent).instanceId).toBe('client-1');
+      expect((events[1] as ComponentActivityEvent).instanceId).toBe('client-2');
+      expect((events[2] as ComponentActivityEvent).instanceId).toBeUndefined();
+    });
+  });
+});