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

package/dist/utils/ExecutionFileDiscovery.js

@@ -0,0 +1,339 @@
+/**
+ * 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';
+/**
+ * Execution File Discovery Engine
+ *
+ * Discovers execution artifacts and canvas files using monorepo-aware logic.
+ */
+export class ExecutionFileDiscovery {
+    constructor(options = {}) {
+        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) {
+        const executionFiles = [];
+        // 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) {
+        const canvasFiles = [];
+        // 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, executionFiles) {
+        // 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, canvasFiles) {
+        // 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) {
+        try {
+            const parsed = JSON.parse(content);
+            return parsed;
+        }
+        catch (error) {
+            throw new Error(`Failed to parse execution artifact JSON: ${error.message}`);
+        }
+    }
+    /**
+     * Get spans from an artifact
+     */
+    static getSpans(artifact) {
+        return artifact.spans || [];
+    }
+    /**
+     * Extract metadata from an execution artifact
+     */
+    static getExecutionMetadata(artifact) {
+        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';
+        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
+     */
+    async detectPackages(files) {
+        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
+     */
+    convertToFileTree(files) {
+        // 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
+     */
+    findExecutionsInPackage(pkg, files) {
+        const executions = [];
+        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
+     */
+    findExecutionsInRoot(files) {
+        const executions = [];
+        // 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
+     */
+    findCanvasesInDirectory(directory, files, packageContext) {
+        const canvases = [];
+        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
+     */
+    createPackageContext(pkg) {
+        return {
+            name: pkg.packageData.name || 'unknown',
+            packagePath: pkg.packageData.path || '',
+            packageType: pkg.type,
+        };
+    }
+    /**
+     * Check if filename is an execution file
+     */
+    isExecutionFile(filename) {
+        return /\.(spans|execution|events)\.json$/.test(filename);
+    }
+    /**
+     * Check if filename is a canvas file
+     */
+    isCanvasFile(filename) {
+        return this.options.canvasExtensions.some(ext => filename.endsWith(ext));
+    }
+    /**
+     * Extract basename from execution filename
+     */
+    extractExecutionBasename(filename) {
+        return filename.replace(/\.(spans|execution|events)\.json$/, '');
+    }
+    /**
+     * Extract basename from canvas filename
+     */
+    extractCanvasBasename(filename) {
+        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)
+     */
+    formatDisplayName(basename) {
+        return basename
+            .split('-')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+    /**
+     * Generate unique ID for execution file
+     */
+    generateExecutionId(basename, packageContext) {
+        if (packageContext) {
+            return `${packageContext.name}-${basename}`;
+        }
+        return basename;
+    }
+    /**
+     * Generate unique ID for canvas file
+     */
+    generateCanvasId(basename, packageContext) {
+        if (packageContext) {
+            return `${packageContext.name}-${basename}`;
+        }
+        return basename;
+    }
+    /**
+     * Sort execution files by package name, then by basename
+     */
+    sortExecutionFiles(files) {
+        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);
+        });
+    }
+}
+//# sourceMappingURL=ExecutionFileDiscovery.js.map

package/dist/utils/ExecutionFileDiscovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionFileDiscovery.js","sourceRoot":"","sources":["../../src/utils/ExecutionFileDiscovery.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/principal-view-core",
-  "version": "0.5.16",
+  "version": "0.6.0",
   "description": "Core logic and types for graph-based principal view framework",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,6 +28,7 @@
     "zod": "^3.22.0",
     "date-fns": "^3.0.0",
     "@principal-ai/repository-abstraction": "^0.2.5",
+    "@principal-ai/codebase-composition": "^0.2.31",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -29,6 +29,19 @@ export type { LogEntry } from './PathBasedEventProcessor';
 export { PathMatcher } from './utils/PathMatcher';
 export { GraphConverter } from './utils/GraphConverter';
 
+// Export execution file discovery
+export { ExecutionFileDiscovery } from './utils/ExecutionFileDiscovery';
+export type {
+  ExecutionFile,
+  CanvasFile,
+  PackageContext,
+  ExecutionMetadata,
+  ExecutionSpan,
+  ExecutionArtifact,
+  FileTreeEntry,
+  DiscoveryOptions,
+} from './utils/ExecutionFileDiscovery';
+
 // Export Canvas types and converter
 export * from './types/canvas';
 export { CanvasConverter } from './utils/CanvasConverter';
@@ -38,6 +51,10 @@ export type { ReactFlowNode, ReactFlowEdge } from './utils/CanvasConverter';
 export { EventValidator, createValidatedEmitter, EventValidationError } from './telemetry/event-validator';
 export type { ValidationResult } from './telemetry/event-validator';
 
+// Export telemetry coverage analysis
+export { analyzeCoverage } from './telemetry/coverage';
+export type { CoverageMetrics, NodeCoverage, CanvasNode as CoverageCanvasNode } from './telemetry/coverage';
+
 // Export code generation
 export { generateTypes, TypeScriptGenerator, generatorRegistry } from './codegen/type-generator';
 export type { CodegenOptions, CodegenResult, CodeGenerator } from './codegen/type-generator';

package/src/telemetry/coverage.ts

@@ -0,0 +1,162 @@
+/**
+ * Telemetry Coverage Analysis
+ *
+ * Measures observability coverage by analyzing which canvas nodes have
+ * OpenTelemetry instrumentation in their source files.
+ */
+
+import { readFile, access } from 'fs/promises';
+import { resolve } from 'path';
+import { glob } from 'glob';
+
+export interface CanvasNode {
+  id: string;
+  text?: string;
+  anchors?: Array<{ path?: string }>;
+  [key: string]: any;
+}
+
+export interface Canvas {
+  nodes?: CanvasNode[];
+  [key: string]: any;
+}
+
+export interface NodeCoverage {
+  nodeId: string;
+  filePaths: string[];
+  hasInstrumentation: boolean;
+  instrumentedFiles: string[];
+  missingFiles: string[];
+}
+
+export interface CoverageMetrics {
+  totalNodes: number;
+  nodesWithFiles: number;
+  nodesWithInstrumentation: number;
+  coveragePercentage: number;
+  nodeCoverage: NodeCoverage[];
+  canvasFiles: string[];
+}
+
+/**
+ * Extract file paths from a canvas node anchors (REQUIRED)
+ */
+function extractFilePaths(node: CanvasNode): string[] {
+  const paths: string[] = [];
+
+  if (node.anchors) {
+    for (const anchor of node.anchors) {
+      if (anchor.path) {
+        paths.push(anchor.path);
+      }
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Check if a file has OpenTelemetry instrumentation
+ */
+async function hasInstrumentation(filePath: string): Promise<boolean> {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+
+    const hasOtelImport = content.includes('@opentelemetry/api');
+    const hasTracer = /getTracer|startSpan|addEvent/.test(content);
+    const hasTestOtel = /['"]\.\.?\/.*test\/otel-setup['"]/.test(content);
+
+    return hasOtelImport || hasTracer || hasTestOtel;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if file exists
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Analyze coverage for a single canvas node
+ */
+async function analyzeNodeCoverage(
+  node: CanvasNode,
+  rootDir: string
+): Promise<NodeCoverage> {
+  const filePaths = extractFilePaths(node);
+  const instrumentedFiles: string[] = [];
+  const missingFiles: string[] = [];
+
+  for (const path of filePaths) {
+    const fullPath = resolve(rootDir, path);
+    const exists = await fileExists(fullPath);
+
+    if (!exists) {
+      missingFiles.push(path);
+      continue;
+    }
+
+    const instrumented = await hasInstrumentation(fullPath);
+    if (instrumented) {
+      instrumentedFiles.push(path);
+    }
+  }
+
+  return {
+    nodeId: node.id,
+    filePaths,
+    hasInstrumentation: instrumentedFiles.length > 0,
+    instrumentedFiles,
+    missingFiles
+  };
+}
+
+/**
+ * Generate telemetry coverage report from canvas files
+ */
+export async function analyzeCoverage(rootDir: string): Promise<CoverageMetrics> {
+  const canvasFiles = await glob('**/*.otel.canvas', {
+    cwd: rootDir,
+    absolute: true,
+    dot: true,
+    ignore: ['**/node_modules/**']
+  });
+
+  const allNodeCoverage: NodeCoverage[] = [];
+
+  for (const canvasFile of canvasFiles) {
+    const content = await readFile(canvasFile, 'utf-8');
+    const canvas: Canvas = JSON.parse(content);
+
+    if (!canvas.nodes || canvas.nodes.length === 0) {
+      continue;
+    }
+
+    for (const node of canvas.nodes) {
+      const coverage = await analyzeNodeCoverage(node, rootDir);
+      allNodeCoverage.push(coverage);
+    }
+  }
+
+  const nodesWithFiles = allNodeCoverage.filter(n => n.filePaths.length > 0);
+  const nodesWithInstrumentation = allNodeCoverage.filter(n => n.hasInstrumentation);
+
+  return {
+    totalNodes: allNodeCoverage.length,
+    nodesWithFiles: nodesWithFiles.length,
+    nodesWithInstrumentation: nodesWithInstrumentation.length,
+    coveragePercentage: nodesWithFiles.length > 0
+      ? (nodesWithInstrumentation.length / nodesWithFiles.length) * 100
+      : 0,
+    nodeCoverage: allNodeCoverage,
+    canvasFiles: canvasFiles.map(f => f.replace(rootDir + '/', ''))
+  };
+}