@principal-ai/principal-view-core 0.25.0 → 0.26.0

package/src/discovery/CanvasFileManifest.ts

@@ -0,0 +1,419 @@
+/**
+ * Canvas File Manifest Builder
+ *
+ * Utilities for building aggregated file manifests from canvases, workflows, and storyboards.
+ * These manifests provide structured access to all files associated with OTEL canvases,
+ * with bidirectional mappings between files, nodes, and events.
+ */
+
+import type {
+  ExtendedCanvas,
+  ExtendedCanvasNode,
+  OtelNode,
+  OtelEventNode,
+} from '../types/canvas';
+import type { WorkflowTemplate, WorkflowScenario } from '../workflow/types';
+import type {
+  CanvasFileManifest,
+  WorkflowFileManifest,
+  StoryboardFileManifest,
+  CanvasFile,
+  CanvasFileRole,
+  CanvasFileOrigin,
+  CanvasType,
+} from './types';
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+function isOtelNode(node: ExtendedCanvasNode): node is OtelNode {
+  return node.type.startsWith('otel-');
+}
+
+function isOtelEventNode(node: ExtendedCanvasNode): node is OtelEventNode {
+  return node.type === 'otel-event';
+}
+
+// =============================================================================
+// Node File Extraction
+// =============================================================================
+
+interface ExtractedFile {
+  path: string;
+  role: CanvasFileRole;
+  origin: CanvasFileOrigin;
+  eventName?: string;
+}
+
+function extractNodeFiles(node: ExtendedCanvasNode): ExtractedFile[] {
+  const files: ExtractedFile[] = [];
+
+  // Only process OTEL nodes
+  if (!isOtelNode(node) || !node.otel) {
+    return files;
+  }
+
+  // Get event name if this is an otel-event node
+  let eventName: string | undefined;
+  if (isOtelEventNode(node)) {
+    eventName = node.event?.name ?? node.eventRef;
+  }
+
+  const origin: CanvasFileOrigin = node.otel.origin ?? 'internal';
+
+  // Instrumentation files
+  if (node.otel.files) {
+    for (const path of node.otel.files) {
+      files.push({ path, role: 'instrumentation', origin, eventName });
+    }
+  }
+
+  // References
+  if (node.otel.references) {
+    for (const path of node.otel.references) {
+      files.push({ path, role: 'reference', origin: 'external', eventName });
+    }
+  }
+
+  return files;
+}
+
+// =============================================================================
+// Canvas Manifest Builder
+// =============================================================================
+
+/**
+ * Build a file manifest from a canvas
+ *
+ * @param canvas - The parsed ExtendedCanvas
+ * @param canvasId - Canvas identifier
+ * @param canvasPath - Canvas file path
+ * @param canvasType - Canvas type (otel, scopes, spans, resources)
+ * @returns Aggregated file manifest
+ *
+ * @example
+ * ```typescript
+ * const manifest = buildCanvasFileManifest(
+ *   canvas,
+ *   'my-canvas',
+ *   '.principal-views/my-canvas.otel.canvas',
+ *   'otel'
+ * );
+ *
+ * // Get all instrumentation files
+ * const instrumentationFiles = manifest.byRole.instrumentation;
+ *
+ * // Find which nodes reference a specific file
+ * const nodeIds = manifest.fileToNodes.get('src/api/checkout.ts');
+ *
+ * // Get all files for a specific node
+ * const files = manifest.nodeToFiles.get('node-123');
+ * ```
+ */
+export function buildCanvasFileManifest(
+  canvas: ExtendedCanvas,
+  canvasId: string,
+  canvasPath: string,
+  canvasType: CanvasType = 'otel'
+): CanvasFileManifest {
+  const fileMap = new Map<string, CanvasFile>();
+  const fileToNodes = new Map<string, string[]>();
+  const nodeToFiles = new Map<string, string[]>();
+  const eventToFiles = new Map<string, string[]>();
+  const eventNames = new Set<string>();
+
+  let nodesWithFiles = 0;
+  let nodesWithoutFiles = 0;
+
+  for (const node of canvas.nodes ?? []) {
+    const nodeFiles = extractNodeFiles(node);
+
+    if (nodeFiles.length > 0) {
+      nodesWithFiles++;
+      nodeToFiles.set(
+        node.id,
+        nodeFiles.map((f) => f.path)
+      );
+    } else {
+      nodesWithoutFiles++;
+    }
+
+    for (const { path, role, origin, eventName } of nodeFiles) {
+      // Track event names
+      if (eventName) {
+        eventNames.add(eventName);
+        const existingEventFiles = eventToFiles.get(eventName) ?? [];
+        if (!existingEventFiles.includes(path)) {
+          existingEventFiles.push(path);
+          eventToFiles.set(eventName, existingEventFiles);
+        }
+      }
+
+      // Update fileToNodes mapping
+      const existingNodes = fileToNodes.get(path) ?? [];
+      if (!existingNodes.includes(node.id)) {
+        existingNodes.push(node.id);
+        fileToNodes.set(path, existingNodes);
+      }
+
+      // Update or create CanvasFile entry
+      const existing = fileMap.get(path);
+      if (existing) {
+        if (!existing.nodeIds.includes(node.id)) {
+          existing.nodeIds.push(node.id);
+        }
+        if (!existing.nodeTypes.includes(node.type)) {
+          existing.nodeTypes.push(node.type);
+        }
+        if (eventName && !existing.eventNames.includes(eventName)) {
+          existing.eventNames.push(eventName);
+        }
+        // Role priority: instrumentation > root-span > reference
+        const rolePriority: Record<CanvasFileRole, number> = {
+          instrumentation: 3,
+          'root-span': 2,
+          reference: 1,
+        };
+        if (rolePriority[role] > rolePriority[existing.role]) {
+          existing.role = role;
+        }
+      } else {
+        fileMap.set(path, {
+          path,
+          role,
+          origin,
+          level: 'canvas-node',
+          nodeIds: [node.id],
+          nodeTypes: [node.type],
+          workflowIds: [],
+          eventNames: eventName ? [eventName] : [],
+        });
+      }
+    }
+  }
+
+  const files = Array.from(fileMap.values());
+
+  // Build byRole lookup
+  const byRole: Record<CanvasFileRole, CanvasFile[]> = {
+    instrumentation: files.filter((f) => f.role === 'instrumentation'),
+    reference: files.filter((f) => f.role === 'reference'),
+    'root-span': files.filter((f) => f.role === 'root-span'),
+  };
+
+  // Build byOrigin lookup
+  const byOrigin: Record<CanvasFileOrigin, CanvasFile[]> = {
+    internal: files.filter((f) => f.origin === 'internal'),
+    external: files.filter((f) => f.origin === 'external'),
+  };
+
+  return {
+    canvasId,
+    canvasPath,
+    canvasType,
+    files,
+    byRole,
+    byOrigin,
+    fileToNodes,
+    nodeToFiles,
+    eventToFiles,
+    stats: {
+      totalFiles: files.length,
+      internalFiles: byOrigin.internal.length,
+      externalFiles: byOrigin.external.length,
+      instrumentationFiles: byRole.instrumentation.length,
+      referenceFiles: byRole.reference.length,
+      nodesWithFiles,
+      nodesWithoutFiles,
+      uniqueEventNames: eventNames.size,
+    },
+  };
+}
+
+// =============================================================================
+// Workflow Manifest Builder
+// =============================================================================
+
+/**
+ * Get files relevant to a specific scenario
+ */
+function getFilesForScenario(
+  scenario: WorkflowScenario,
+  canvasManifest: CanvasFileManifest,
+  workflowFiles: CanvasFile[]
+): CanvasFile[] {
+  const files: CanvasFile[] = [];
+
+  // Always include workflow-level files (root span)
+  files.push(...workflowFiles);
+
+  // Get event names from scenario template
+  const eventNames = Object.keys(scenario.template.events ?? {});
+
+  // Find files for each event
+  for (const eventName of eventNames) {
+    const eventFiles = canvasManifest.eventToFiles.get(eventName) ?? [];
+    for (const filePath of eventFiles) {
+      const canvasFile = canvasManifest.files.find((f) => f.path === filePath);
+      if (canvasFile && !files.some((f) => f.path === filePath)) {
+        files.push(canvasFile);
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Build a file manifest for a workflow (includes canvas files)
+ *
+ * @param canvasManifest - The canvas manifest to extend
+ * @param workflow - The workflow template
+ * @param workflowId - Workflow identifier
+ * @param workflowPath - Workflow file path
+ * @returns Workflow file manifest with scenario filtering
+ *
+ * @example
+ * ```typescript
+ * const workflowManifest = buildWorkflowFileManifest(
+ *   canvasManifest,
+ *   workflow,
+ *   'checkout-workflow',
+ *   '.principal-views/checkout/checkout.workflow.json'
+ * );
+ *
+ * // Get files for a specific scenario
+ * const scenarioFiles = workflowManifest.byScenario.get('success-scenario');
+ * ```
+ */
+export function buildWorkflowFileManifest(
+  canvasManifest: CanvasFileManifest,
+  workflow: WorkflowTemplate,
+  workflowId: string,
+  workflowPath: string
+): WorkflowFileManifest {
+  // Extract workflow-level files
+  const workflowFiles: CanvasFile[] = (workflow.files ?? []).map((path) => ({
+    path,
+    role: 'root-span' as CanvasFileRole,
+    origin: 'internal' as CanvasFileOrigin,
+    level: 'workflow' as const,
+    nodeIds: [],
+    nodeTypes: [],
+    workflowIds: [workflowId],
+    eventNames: [],
+  }));
+
+  // Merge canvas files with workflow files
+  const allFilesMap = new Map<string, CanvasFile>();
+
+  // Add canvas files first
+  for (const file of canvasManifest.files) {
+    allFilesMap.set(file.path, { ...file });
+  }
+
+  // Add/merge workflow files
+  for (const file of workflowFiles) {
+    const existing = allFilesMap.get(file.path);
+    if (existing) {
+      existing.workflowIds.push(workflowId);
+      // Upgrade role if workflow-level
+      if (file.role === 'root-span') {
+        existing.role = 'root-span';
+        existing.level = 'workflow';
+      }
+    } else {
+      allFilesMap.set(file.path, file);
+    }
+  }
+
+  const allFiles = Array.from(allFilesMap.values());
+
+  // Build scenario -> files mapping
+  const byScenario = new Map<string, CanvasFile[]>();
+  for (const scenario of workflow.scenarios) {
+    const scenarioFiles = getFilesForScenario(scenario, canvasManifest, workflowFiles);
+    byScenario.set(scenario.id, scenarioFiles);
+  }
+
+  return {
+    ...canvasManifest,
+    workflowId,
+    workflowPath,
+    rootSpan: workflow.rootSpan ?? workflow.spanPattern,
+    workflowFiles,
+    allFiles,
+    byScenario,
+  };
+}
+
+// =============================================================================
+// Storyboard Manifest Builder
+// =============================================================================
+
+/**
+ * Build a file manifest for an entire storyboard
+ *
+ * @param canvasManifest - The main canvas manifest
+ * @param workflowManifests - Array of workflow manifests
+ * @param storyboardId - Storyboard identifier
+ * @param storyboardPath - Storyboard folder path
+ * @returns Storyboard file manifest aggregating all files
+ *
+ * @example
+ * ```typescript
+ * const storyboardManifest = buildStoryboardFileManifest(
+ *   canvasManifest,
+ *   workflowManifests,
+ *   'checkout-flow',
+ *   '.principal-views/checkout-flow'
+ * );
+ *
+ * // Get all files across canvas and workflows
+ * const allFiles = storyboardManifest.allFiles;
+ * ```
+ */
+export function buildStoryboardFileManifest(
+  canvasManifest: CanvasFileManifest,
+  workflowManifests: WorkflowFileManifest[],
+  storyboardId: string,
+  storyboardPath: string
+): StoryboardFileManifest {
+  // Merge all files across canvas and workflows
+  const allFilesMap = new Map<string, CanvasFile>();
+
+  for (const file of canvasManifest.files) {
+    allFilesMap.set(file.path, { ...file });
+  }
+
+  for (const workflow of workflowManifests) {
+    for (const file of workflow.workflowFiles) {
+      const existing = allFilesMap.get(file.path);
+      if (existing) {
+        existing.workflowIds.push(...file.workflowIds);
+      } else {
+        allFilesMap.set(file.path, { ...file });
+      }
+    }
+  }
+
+  const allFiles = Array.from(allFilesMap.values());
+
+  // Count scenarios across all workflows
+  const scenarioCount = workflowManifests.reduce((sum, w) => sum + w.byScenario.size, 0);
+
+  return {
+    storyboardId,
+    storyboardPath,
+    canvas: canvasManifest,
+    workflows: workflowManifests,
+    allFiles,
+    stats: {
+      ...canvasManifest.stats,
+      workflowCount: workflowManifests.length,
+      scenarioCount,
+      rootSpanFiles: allFiles.filter((f) => f.role === 'root-span').length,
+    },
+  };
+}

package/src/discovery/types.ts

@@ -208,3 +208,179 @@ export interface CanvasDiscoveryResultWithContent {
   errors: Array<{ path: string; error: string }>;
   warnings: Array<{ path: string; message: string; type: 'deprecation' }>;
 }
+
+// =============================================================================
+// Canvas File Manifest Types
+// =============================================================================
+
+/**
+ * Classification of how a file relates to a canvas/workflow
+ */
+export type CanvasFileRole =
+  | 'instrumentation' // File contains OTEL instrumentation (from otel.files)
+  | 'reference' // External reference/documentation (from otel.references)
+  | 'root-span'; // Root span instrumentation (from workflow.files)
+
+/**
+ * Origin of the file - internal to repo or external
+ */
+export type CanvasFileOrigin = 'internal' | 'external';
+
+/**
+ * Source level where the file was defined
+ */
+export type CanvasFileLevel = 'canvas-node' | 'workflow';
+
+/**
+ * A file referenced by a canvas, workflow, or scenario
+ */
+export interface CanvasFile {
+  /** File path (relative to repo root for internal, URL/package ref for external) */
+  path: string;
+
+  /** How this file relates to the canvas */
+  role: CanvasFileRole;
+
+  /** Whether the file is in this repo or external */
+  origin: CanvasFileOrigin;
+
+  /** Where this file reference was defined */
+  level: CanvasFileLevel;
+
+  /** IDs of nodes that reference this file (for canvas-node level) */
+  nodeIds: string[];
+
+  /** Node types that reference this file */
+  nodeTypes: string[];
+
+  /** Workflow IDs that reference this file (for workflow level) */
+  workflowIds: string[];
+
+  /** Event names associated with this file's nodes */
+  eventNames: string[];
+}
+
+/**
+ * Canvas-level statistics
+ */
+export interface CanvasFileStats {
+  totalFiles: number;
+  internalFiles: number;
+  externalFiles: number;
+  instrumentationFiles: number;
+  referenceFiles: number;
+  nodesWithFiles: number;
+  nodesWithoutFiles: number;
+  uniqueEventNames: number;
+}
+
+/**
+ * Storyboard-level statistics
+ */
+export interface StoryboardFileStats extends CanvasFileStats {
+  workflowCount: number;
+  scenarioCount: number;
+  rootSpanFiles: number;
+}
+
+/**
+ * File manifest for a single canvas (without workflows)
+ */
+export interface CanvasFileManifest {
+  /** Canvas ID */
+  canvasId: string;
+
+  /** Canvas path */
+  canvasPath: string;
+
+  /** Canvas type */
+  canvasType: CanvasType;
+
+  /** All files from canvas nodes, deduplicated */
+  files: CanvasFile[];
+
+  /** Quick lookup by role */
+  byRole: Record<CanvasFileRole, CanvasFile[]>;
+
+  /** Quick lookup by origin */
+  byOrigin: Record<CanvasFileOrigin, CanvasFile[]>;
+
+  /** Reverse mapping: file path -> node IDs */
+  fileToNodes: Map<string, string[]>;
+
+  /** Reverse mapping: node ID -> file paths */
+  nodeToFiles: Map<string, string[]>;
+
+  /** Reverse mapping: event name -> file paths */
+  eventToFiles: Map<string, string[]>;
+
+  /** Summary statistics */
+  stats: CanvasFileStats;
+}
+
+/**
+ * File manifest for a workflow (includes canvas + workflow-level files)
+ */
+export interface WorkflowFileManifest extends CanvasFileManifest {
+  /** Workflow ID */
+  workflowId: string;
+
+  /** Workflow path */
+  workflowPath: string;
+
+  /** Root span name */
+  rootSpan?: string;
+
+  /** Files from workflow.files property */
+  workflowFiles: CanvasFile[];
+
+  /** Merged files (canvas + workflow) */
+  allFiles: CanvasFile[];
+
+  /** Files filtered by scenario (scenario ID -> files) */
+  byScenario: Map<string, CanvasFile[]>;
+}
+
+/**
+ * File manifest for an entire storyboard
+ */
+export interface StoryboardFileManifest {
+  /** Storyboard ID */
+  storyboardId: string;
+
+  /** Storyboard path */
+  storyboardPath: string;
+
+  /** Main canvas manifest */
+  canvas: CanvasFileManifest;
+
+  /** Workflow manifests */
+  workflows: WorkflowFileManifest[];
+
+  /** All files across canvas and all workflows */
+  allFiles: CanvasFile[];
+
+  /** Summary statistics */
+  stats: StoryboardFileStats;
+}
+
+/**
+ * Discovered canvas with content AND file manifest
+ */
+export interface DiscoveredCanvasWithManifest extends DiscoveredCanvasWithContent {
+  manifest: CanvasFileManifest;
+}
+
+/**
+ * Discovered workflow with content AND file manifest
+ */
+export interface DiscoveredWorkflowWithManifest extends DiscoveredWorkflowWithContent {
+  manifest: WorkflowFileManifest;
+}
+
+/**
+ * Discovered storyboard with content AND file manifest
+ */
+export interface DiscoveredStoryboardWithManifest extends DiscoveredStoryboardWithContent {
+  manifest: StoryboardFileManifest;
+}

package/src/index.ts

@@ -282,8 +282,28 @@ export type {
   DiscoveredWorkflowWithContent,
   DiscoveredStoryboardWithContent,
   CanvasDiscoveryResultWithContent,
+  // File manifest types
+  CanvasFileRole,
+  CanvasFileOrigin,
+  CanvasFileLevel,
+  CanvasFile,
+  CanvasFileStats,
+  StoryboardFileStats,
+  CanvasFileManifest,
+  WorkflowFileManifest,
+  StoryboardFileManifest,
+  DiscoveredCanvasWithManifest,
+  DiscoveredWorkflowWithManifest,
+  DiscoveredStoryboardWithManifest,
 } from './discovery/types';
 
+// Export file manifest builders (browser-safe)
+export {
+  buildCanvasFileManifest,
+  buildWorkflowFileManifest,
+  buildStoryboardFileManifest,
+} from './discovery/CanvasFileManifest';
+
 // Export scopes module (canvas validation + scope utilities)
 export {
   ScopesCanvasValidator,
@@ -403,7 +423,6 @@ export type {
 } from './storyboard/index';
 export {
   buildStoryboardContext,
-  buildNodeSourcesMap,
   buildEventNodeMap,
   getNodeEventName,
   resolveScenarioNodeIds,

package/src/storyboard/builder.ts

@@ -13,6 +13,8 @@ import type {
   ScenarioReference,
   StoryboardContextSliceData,
 } from './types';
+import type { CanvasType } from '../discovery/types';
+import { buildCanvasFileManifest } from '../discovery/CanvasFileManifest';
 
 // ============================================================================
 // Types
@@ -33,6 +35,9 @@ export interface BuildStoryboardContextOptions {
   /** Storyboard metadata (id, name, path) */
   storyboard: StoryboardReference;
 
+  /** Canvas type (defaults to 'otel') */
+  canvasType?: CanvasType;
+
   /** Optional: Selected workflow template and its path */
   workflow?: {
     template: WorkflowTemplate;
@@ -50,37 +55,6 @@ export interface BuildStoryboardContextOptions {
 // Core Functions
 // ============================================================================
 
-/**
- * Build a map of canvas node ID to reference paths.
- * Extracts `pv.references` (or deprecated `pv.sources`) from each node.
- *
- * @param canvas - The extended canvas with nodes
- * @returns Record mapping node IDs to their reference paths
- *
- * @example
- * ```typescript
- * const nodeSources = buildNodeSourcesMap(canvas);
- * // { 'node-abc': ['src/auth/login.ts'], 'node-xyz': ['@logfire/pydantic-ai'] }
- * ```
- */
-export function buildNodeSourcesMap(canvas: ExtendedCanvas): Record<string, string[]> {
-  const nodeSources: Record<string, string[]> = {};
-
-  if (!canvas.nodes) {
-    return nodeSources;
-  }
-
-  for (const node of canvas.nodes) {
-    // Prefer references, fall back to deprecated sources
-    const refs = node.pv?.references ?? node.pv?.sources;
-    if (refs && refs.length > 0) {
-      nodeSources[node.id] = [...refs];
-    }
-  }
-
-  return nodeSources;
-}
-
 /**
  * Build a map of event name to canvas node IDs.
  * Uses `pv.event.name` or `pv.eventRef` from each node.
@@ -267,10 +241,10 @@ export function getAllNodeIds(canvas: ExtendedCanvas): string[] {
 export function buildStoryboardContext(
   options: BuildStoryboardContextOptions
 ): StoryboardContextSliceData {
-  const { canvas, storyboard, workflow, scenario, additionalSupportingFiles = [] } = options;
+  const { canvas, storyboard, canvasType = 'otel', workflow, scenario, additionalSupportingFiles = [] } = options;
 
-  // Build node sources map from canvas
-  const nodeSources = buildNodeSourcesMap(canvas);
+  // Build canvas file manifest
+  const manifest = buildCanvasFileManifest(canvas, storyboard.id, storyboard.path, canvasType);
 
   // Build supporting files list
   const supportingFiles: string[] = [storyboard.path];
@@ -310,7 +284,7 @@ export function buildStoryboardContext(
     storyboard,
     workflow: workflowReference,
     scenario: scenarioReference,
-    nodeSources,
+    manifest,
     supportingFiles,
   };
 }