@principal-ai/principal-view-core 0.5.16 → 0.6.0

package/src/utils/ExecutionFileDiscovery.ts

@@ -0,0 +1,521 @@
+/**
+ * Execution File Discovery
+ *
+ * Discovers execution artifacts and canvas files in a repository with monorepo awareness.
+ * Uses codebase-composition to intelligently detect package boundaries and workspace patterns.
+ */
+
+import { PackageLayerModule } from '@principal-ai/codebase-composition';
+import type { PackageLayer } from '@principal-ai/codebase-composition';
+
+/**
+ * Represents a discovered execution artifact file
+ */
+export interface ExecutionFile {
+  /** Unique identifier for this execution */
+  id: string;
+  /** Display name for this execution */
+  name: string;
+  /** Full file path (relative to repository root) */
+  path: string;
+  /** Canvas basename (without extension) that this execution is linked to */
+  canvasBasename: string;
+  /** Package context if this execution belongs to a specific package */
+  packageContext?: PackageContext;
+}
+
+/**
+ * Represents a discovered canvas file
+ */
+export interface CanvasFile {
+  /** Unique identifier for this canvas */
+  id: string;
+  /** Display name for this canvas */
+  name: string;
+  /** Full file path (relative to repository root) */
+  path: string;
+  /** Canvas basename (without .otel.canvas or .canvas extension) */
+  basename: string;
+  /** Package context if this canvas belongs to a specific package */
+  packageContext?: PackageContext;
+}
+
+/**
+ * Package context for execution/canvas files
+ */
+export interface PackageContext {
+  /** Package name (from package.json, Cargo.toml, etc.) */
+  name: string;
+  /** Package directory path (relative to repository root) */
+  packagePath: string;
+  /** Package type (npm, cargo, go, etc.) */
+  packageType?: string;
+}
+
+/**
+ * Execution artifact metadata
+ */
+export interface ExecutionMetadata {
+  name: string;
+  canvasName?: string;
+  exportedAt?: string;
+  source?: string;
+  framework?: string;
+  status?: 'success' | 'error' | 'OK';
+  spanCount: number;
+  eventCount: number;
+}
+
+/**
+ * Execution span structure
+ */
+export interface ExecutionSpan {
+  id: string;
+  name: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  status?: string;
+  attributes?: Record<string, any>;
+  events: Array<{
+    time: number;
+    name: string;
+    attributes?: Record<string, any>;
+  }>;
+}
+
+/**
+ * Execution artifact file structure
+ */
+export interface ExecutionArtifact {
+  metadata?: {
+    canvasName?: string;
+    exportedAt?: string;
+    source?: string;
+    framework?: string;
+    status?: 'success' | 'error';
+  };
+  spans: ExecutionSpan[];
+}
+
+/**
+ * File tree entry for discovery
+ */
+export interface FileTreeEntry {
+  path?: string;
+  relativePath?: string;
+  name?: string;
+}
+
+/**
+ * Options for execution file discovery
+ */
+export interface DiscoveryOptions {
+  /** Whether to include package-level .principal-views folders */
+  includePackagePrincipalViews?: boolean;
+  /** Custom execution folder names (defaults to ['__executions__']) */
+  executionFolders?: string[];
+  /** Custom canvas extensions (defaults to ['.otel.canvas']) */
+  canvasExtensions?: string[];
+}
+
+/**
+ * Execution File Discovery Engine
+ *
+ * Discovers execution artifacts and canvas files using monorepo-aware logic.
+ */
+export class ExecutionFileDiscovery {
+  private packageLayerModule: PackageLayerModule;
+  private options: Required<DiscoveryOptions>;
+
+  constructor(options: DiscoveryOptions = {}) {
+    this.packageLayerModule = new PackageLayerModule();
+    this.options = {
+      includePackagePrincipalViews: options.includePackagePrincipalViews ?? true,
+      executionFolders: options.executionFolders ?? ['__executions__'],
+      canvasExtensions: options.canvasExtensions ?? ['.otel.canvas'],
+    };
+  }
+
+  /**
+   * Find all execution artifact files in the repository
+   */
+  async findExecutionFiles(files: FileTreeEntry[]): Promise<ExecutionFile[]> {
+    const executionFiles: ExecutionFile[] = [];
+
+    // Detect packages in the repository
+    const packages = await this.detectPackages(files);
+
+    // Search for execution files in each package
+    for (const pkg of packages) {
+      const pkgExecutions = this.findExecutionsInPackage(pkg, files);
+      executionFiles.push(...pkgExecutions);
+    }
+
+    // Search in root-level locations
+    const rootExecutions = this.findExecutionsInRoot(files);
+    executionFiles.push(...rootExecutions);
+
+    // Sort by package name, then by basename
+    return this.sortExecutionFiles(executionFiles);
+  }
+
+  /**
+   * Find all canvas files in the repository
+   */
+  async findCanvasFiles(files: FileTreeEntry[]): Promise<CanvasFile[]> {
+    const canvasFiles: CanvasFile[] = [];
+
+    // Detect packages in the repository
+    const packages = await this.detectPackages(files);
+
+    // Search for canvas files in root .principal-views/
+    const rootCanvases = this.findCanvasesInDirectory('.principal-views', files);
+    canvasFiles.push(...rootCanvases);
+
+    // Search for canvas files in package-level .principal-views/ if enabled
+    if (this.options.includePackagePrincipalViews) {
+      for (const pkg of packages) {
+        const pkgCanvases = this.findCanvasesInDirectory(
+          `${pkg.packageData.path}/.principal-views`,
+          files,
+          this.createPackageContext(pkg)
+        );
+        canvasFiles.push(...pkgCanvases);
+      }
+    }
+
+    // Sort by name
+    return canvasFiles.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Find execution artifact for a given canvas
+   * Now package-aware - can disambiguate between packages
+   */
+  findExecutionForCanvas(
+    canvas: CanvasFile,
+    executionFiles: ExecutionFile[]
+  ): ExecutionFile | null {
+    // First, try exact package match if canvas has package context
+    if (canvas.packageContext) {
+      const exactMatch = executionFiles.find(
+        exec =>
+          exec.canvasBasename === canvas.basename &&
+          exec.packageContext?.name === canvas.packageContext?.name
+      );
+      if (exactMatch) return exactMatch;
+    }
+
+    // Fallback to basename-only match (for root-level canvases)
+    return executionFiles.find(exec => exec.canvasBasename === canvas.basename) || null;
+  }
+
+  /**
+   * Find canvas file for a given execution
+   */
+  findCanvasForExecution(
+    execution: ExecutionFile,
+    canvasFiles: CanvasFile[]
+  ): CanvasFile | null {
+    // First, try exact package match if execution has package context
+    if (execution.packageContext) {
+      const exactMatch = canvasFiles.find(
+        canvas =>
+          canvas.basename === execution.canvasBasename &&
+          canvas.packageContext?.name === execution.packageContext?.name
+      );
+      if (exactMatch) return exactMatch;
+    }
+
+    // Fallback to basename-only match (for root-level executions)
+    return canvasFiles.find(canvas => canvas.basename === execution.canvasBasename) || null;
+  }
+
+  /**
+   * Parse execution artifact JSON
+   */
+  static parseExecutionArtifact(content: string): ExecutionArtifact {
+    try {
+      const parsed = JSON.parse(content);
+      return parsed as ExecutionArtifact;
+    } catch (error) {
+      throw new Error(`Failed to parse execution artifact JSON: ${(error as Error).message}`);
+    }
+  }
+
+  /**
+   * Get spans from an artifact
+   */
+  static getSpans(artifact: ExecutionArtifact): ExecutionSpan[] {
+    return artifact.spans || [];
+  }
+
+  /**
+   * Extract metadata from an execution artifact
+   */
+  static getExecutionMetadata(artifact: ExecutionArtifact): ExecutionMetadata {
+    const spans = ExecutionFileDiscovery.getSpans(artifact);
+    const spanCount = spans.length;
+
+    const eventCount = spans.reduce((total, span) => {
+      return total + (span.events?.length || 0);
+    }, 0);
+
+    const metadata = artifact.metadata;
+
+    let status: 'success' | 'error' | 'OK' = 'success';
+    if (metadata?.status) {
+      status = metadata.status;
+    } else if (spans.length > 0) {
+      const hasError = spans.some(
+        s => s.status === 'ERROR' || s.status === 'error' || s.status === 'FAILED'
+      );
+      status = hasError ? 'error' : 'OK';
+    }
+
+    return {
+      name: metadata?.canvasName || 'Untitled Execution',
+      canvasName: metadata?.canvasName,
+      exportedAt: metadata?.exportedAt,
+      source: metadata?.source,
+      framework: metadata?.framework,
+      status,
+      spanCount,
+      eventCount,
+    };
+  }
+
+  // Private helper methods
+
+  /**
+   * Detect packages using codebase-composition
+   */
+  private async detectPackages(files: FileTreeEntry[]): Promise<PackageLayer[]> {
+    try {
+      // Convert files to the format expected by codebase-composition
+      const fileTree = this.convertToFileTree(files);
+      const packages = await this.packageLayerModule.discoverPackages(fileTree);
+      return packages || [];
+    } catch (error) {
+      // If package detection fails, continue with fallback patterns
+      console.warn('Package detection failed, using fallback patterns:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Convert file entries to file tree format for codebase-composition
+   */
+  private convertToFileTree(files: FileTreeEntry[]): any {
+    // This is a simplified conversion - codebase-composition expects a specific format
+    // In practice, the caller should provide a proper FileTree from repository-abstraction
+    return {
+      files: files.map(f => ({
+        path: f.relativePath || f.path || '',
+        name: f.name || (f.relativePath || f.path || '').split('/').pop() || '',
+      })),
+    };
+  }
+
+  /**
+   * Find executions in a specific package
+   */
+  private findExecutionsInPackage(
+    pkg: PackageLayer,
+    files: FileTreeEntry[]
+  ): ExecutionFile[] {
+    const executions: ExecutionFile[] = [];
+    const pkgPath = pkg.packageData.path || '';
+    const packageContext = this.createPackageContext(pkg);
+
+    for (const execFolder of this.options.executionFolders) {
+      const execPath = pkgPath ? `${pkgPath}/${execFolder}` : execFolder;
+
+      for (const file of files) {
+        const filePath = file.relativePath || file.path || '';
+        const fileName = file.name || filePath.split('/').pop() || '';
+
+        if (filePath.startsWith(execPath + '/') && this.isExecutionFile(fileName)) {
+          const basename = this.extractExecutionBasename(fileName);
+          executions.push({
+            id: this.generateExecutionId(basename, packageContext),
+            name: this.formatDisplayName(basename),
+            path: filePath,
+            canvasBasename: basename,
+            packageContext,
+          });
+        }
+      }
+    }
+
+    return executions;
+  }
+
+  /**
+   * Find executions in root-level locations
+   */
+  private findExecutionsInRoot(files: FileTreeEntry[]): ExecutionFile[] {
+    const executions: ExecutionFile[] = [];
+
+    // Root __executions__/
+    for (const execFolder of this.options.executionFolders) {
+      for (const file of files) {
+        const filePath = file.relativePath || file.path || '';
+        const fileName = file.name || filePath.split('/').pop() || '';
+
+        if (filePath.startsWith(`${execFolder}/`) && this.isExecutionFile(fileName)) {
+          const basename = this.extractExecutionBasename(fileName);
+          executions.push({
+            id: `root-${basename}`,
+            name: this.formatDisplayName(basename),
+            path: filePath,
+            canvasBasename: basename,
+          });
+        }
+      }
+    }
+
+    // .principal-views/__executions__/
+    const pvExecPath = '.principal-views/__executions__';
+    for (const file of files) {
+      const filePath = file.relativePath || file.path || '';
+      const fileName = file.name || filePath.split('/').pop() || '';
+
+      if (filePath.startsWith(pvExecPath + '/') && this.isExecutionFile(fileName)) {
+        const basename = this.extractExecutionBasename(fileName);
+        executions.push({
+          id: `pv-${basename}`,
+          name: this.formatDisplayName(basename),
+          path: filePath,
+          canvasBasename: basename,
+        });
+      }
+    }
+
+    return executions;
+  }
+
+  /**
+   * Find canvas files in a specific directory
+   */
+  private findCanvasesInDirectory(
+    directory: string,
+    files: FileTreeEntry[],
+    packageContext?: PackageContext
+  ): CanvasFile[] {
+    const canvases: CanvasFile[] = [];
+
+    for (const file of files) {
+      const filePath = file.relativePath || file.path || '';
+      const fileName = file.name || filePath.split('/').pop() || '';
+
+      if (filePath.startsWith(directory + '/') && this.isCanvasFile(fileName)) {
+        const basename = this.extractCanvasBasename(fileName);
+        canvases.push({
+          id: this.generateCanvasId(basename, packageContext),
+          name: this.formatDisplayName(basename),
+          path: filePath,
+          basename,
+          packageContext,
+        });
+      }
+    }
+
+    return canvases;
+  }
+
+  /**
+   * Create package context from PackageLayer
+   */
+  private createPackageContext(pkg: PackageLayer): PackageContext {
+    return {
+      name: pkg.packageData.name || 'unknown',
+      packagePath: pkg.packageData.path || '',
+      packageType: pkg.type,
+    };
+  }
+
+  /**
+   * Check if filename is an execution file
+   */
+  private isExecutionFile(filename: string): boolean {
+    return /\.(spans|execution|events)\.json$/.test(filename);
+  }
+
+  /**
+   * Check if filename is a canvas file
+   */
+  private isCanvasFile(filename: string): boolean {
+    return this.options.canvasExtensions.some(ext => filename.endsWith(ext));
+  }
+
+  /**
+   * Extract basename from execution filename
+   */
+  private extractExecutionBasename(filename: string): string {
+    return filename.replace(/\.(spans|execution|events)\.json$/, '');
+  }
+
+  /**
+   * Extract basename from canvas filename
+   */
+  private extractCanvasBasename(filename: string): string {
+    for (const ext of this.options.canvasExtensions) {
+      if (filename.endsWith(ext)) {
+        return filename.slice(0, -ext.length);
+      }
+    }
+    return filename;
+  }
+
+  /**
+   * Format display name from basename (kebab-case to Title Case)
+   */
+  private formatDisplayName(basename: string): string {
+    return basename
+      .split('-')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  /**
+   * Generate unique ID for execution file
+   */
+  private generateExecutionId(basename: string, packageContext?: PackageContext): string {
+    if (packageContext) {
+      return `${packageContext.name}-${basename}`;
+    }
+    return basename;
+  }
+
+  /**
+   * Generate unique ID for canvas file
+   */
+  private generateCanvasId(basename: string, packageContext?: PackageContext): string {
+    if (packageContext) {
+      return `${packageContext.name}-${basename}`;
+    }
+    return basename;
+  }
+
+  /**
+   * Sort execution files by package name, then by basename
+   */
+  private sortExecutionFiles(files: ExecutionFile[]): ExecutionFile[] {
+    return files.sort((a, b) => {
+      // Sort by package name first
+      if (a.packageContext && b.packageContext) {
+        const pkgCompare = a.packageContext.name.localeCompare(b.packageContext.name);
+        if (pkgCompare !== 0) return pkgCompare;
+      } else if (a.packageContext) {
+        return -1;
+      } else if (b.packageContext) {
+        return 1;
+      }
+
+      // Then by basename
+      return a.canvasBasename.localeCompare(b.canvasBasename);
+    });
+  }
+}

package/src/utils/GraphConverter.test.ts

@@ -9,6 +9,8 @@ import {
   markTestFailed,
   setSpanAttribute,
   exportSpans,
+  log,
+  recordLog,
 } from '../../test/otel-setup';
 
 describe('GraphConverter', () => {
@@ -24,11 +26,25 @@ describe('GraphConverter', () => {
     });
 
     try {
+      // TRACE log at test start (automatically correlated with testSpan)
+      log('TRACE', 'Entering test case for simple config conversion', {
+        'service.name': 'graph-converter-service',
+        'service.version': '1.0.0',
+      });
+
       // Setup - record as event
       addEvent(testSpan, 'setup.started', {
         description: 'Creating test configuration with 2 nodes and 1 edge',
       });
 
+      // INFO log during setup
+      log('INFO', 'Initializing test configuration', {
+        'service.name': 'graph-converter-service',
+      }, {
+        'config.nodeCount': 2,
+        'config.edgeCount': 1,
+      });
+
       const config: PathBasedGraphConfiguration = {
         metadata: {
           name: 'Test Config',
@@ -70,6 +86,15 @@ describe('GraphConverter', () => {
         'config.edges': 1,
       });
 
+      // DEBUG log with structured data after setup
+      log('DEBUG', {
+        phase: 'setup-complete',
+        nodeTypes: Object.keys(config.nodeTypes),
+        edgeTypes: Object.keys(config.edgeTypes),
+      }, {
+        'service.name': 'graph-converter-service',
+      });
+
       // Execution - record as event
       // Note: execution happens in GraphConverter.ts, not the test file
       addEvent(testSpan, 'execution.started', {
@@ -78,8 +103,25 @@ describe('GraphConverter', () => {
         'code.lineno': 15,
       });
 
+      // INFO log before conversion
+      log('INFO', 'Starting graph conversion process', {
+        'service.name': 'graph-converter-service',
+      }, {
+        'operation': 'configToGraph',
+        'inputSize.bytes': JSON.stringify(config).length,
+      });
+
       const result = GraphConverter.configToGraph(config);
 
+      // DEBUG log after conversion with result details
+      log('DEBUG', 'Conversion completed successfully', {
+        'service.name': 'graph-converter-service',
+      }, {
+        'output.nodeCount': result.nodes.length,
+        'output.edgeCount': result.edges.length,
+        'processingTime.ms': 5,
+      });
+
       addEvent(testSpan, 'execution.complete', {
         'result.nodes.count': result.nodes.length,
         'result.edges.count': result.edges.length,
@@ -92,6 +134,13 @@ describe('GraphConverter', () => {
         assertions: 'Verifying nodes and edges structure',
       });
 
+      // INFO log at assertion phase
+      log('INFO', 'Running assertions on converted graph', {
+        'service.name': 'graph-converter-service',
+      }, {
+        'totalAssertions': 11,
+      });
+
       expect(result.nodes).toHaveLength(2);
       expect(result.edges).toHaveLength(1);
 
@@ -116,8 +165,24 @@ describe('GraphConverter', () => {
         'assertions.failed': 0,
       });
 
+      // INFO log on successful test completion
+      log('INFO', 'All assertions passed - test successful', {
+        'service.name': 'graph-converter-service',
+      }, {
+        'test.status': 'passed',
+        'test.duration.ms': Date.now() - testSpan.startTime,
+      });
+
       markTestPassed(testSpan);
     } catch (error) {
+      // ERROR log on failure
+      log('ERROR', `Test failed: ${(error as Error).message}`, {
+        'service.name': 'graph-converter-service',
+      }, {
+        'test.status': 'failed',
+        'error.type': (error as Error).name,
+      });
+
       addEvent(testSpan, 'test.failed', {
         error: (error as Error).message,
       });
@@ -125,6 +190,20 @@ describe('GraphConverter', () => {
       throw error;
     } finally {
       endSpan(testSpan);
+
+      // Uncorrelated log after span ends (simulating cleanup/background task)
+      recordLog({
+        severity: 'DEBUG',
+        body: 'Test cleanup completed',
+        resource: {
+          'service.name': 'test-cleanup-service',
+          'cleanup.type': 'post-test',
+        },
+        attributes: {
+          'test.name': 'should convert simple config to nodes and edges',
+        },
+        // No traceId/spanId - this is an uncorrelated log
+      });
     }
   });