@principal-ai/subsystems-core 0.29.0

package/src/registry/EventRegistry.ts

@@ -0,0 +1,191 @@
+/**
+ * EventRegistry - indexes events across library and canvases
+ *
+ * Provides a centralized registry for looking up where events are defined,
+ * enabling improved validation error messages with actionable suggestions.
+ */
+
+import type { ComponentLibrary } from '../types/library';
+import type { ExtendedCanvas, PVEventSchema } from '../types/canvas';
+import { isOtelEventNode, isStandardCanvasNode } from '../types/canvas';
+
+/**
+ * Describes where an event is defined
+ */
+export interface EventSource {
+  /** Whether the event is defined in the library or a canvas */
+  type: 'library' | 'canvas';
+  /** Path to the source file (library.yaml path or canvas path) */
+  path: string;
+  /** The full event schema if available */
+  eventSchema?: PVEventSchema;
+}
+
+/**
+ * EventRegistry indexes all events across a library and set of canvases.
+ *
+ * Build order (priority):
+ * 1. Library eventSchemas (the intended sharing mechanism)
+ * 2. Canvas inline events (pv.event)
+ * 3. Canvas eventRefs (pv.eventRef) - these reference library schemas
+ *
+ * Usage:
+ * ```typescript
+ * const registry = EventRegistry.build(library, canvases, libraryPath);
+ * const sources = registry.findEvent('cleanup.started');
+ * if (sources.length > 0) {
+ *   // Event found - provide helpful error message
+ * }
+ * ```
+ */
+export class EventRegistry {
+  private events: Map<string, EventSource[]>;
+
+  private constructor() {
+    this.events = new Map();
+  }
+
+  /**
+   * Build an EventRegistry from a library and set of canvases.
+   *
+   * @param library - The component library (may be undefined)
+   * @param canvases - Map of canvas path to parsed canvas
+   * @param libraryPath - Path to the library file (for error messages)
+   * @returns A populated EventRegistry
+   */
+  static build(
+    library: ComponentLibrary | undefined,
+    canvases: Map<string, ExtendedCanvas>,
+    libraryPath?: string
+  ): EventRegistry {
+    const registry = new EventRegistry();
+
+    // 1. Index library eventSchemas first (priority source)
+    if (library?.eventSchemas) {
+      const libPath = libraryPath ?? 'library.yaml';
+      for (const [eventName, schema] of Object.entries(library.eventSchemas)) {
+        const fullSchema: PVEventSchema = {
+          name: eventName,
+          description: schema.description,
+          attributes: schema.attributes,
+        };
+        registry.addEvent(eventName, {
+          type: 'library',
+          path: libPath,
+          eventSchema: fullSchema,
+        });
+      }
+    }
+
+    // 2. Index canvas events
+    for (const [canvasPath, canvas] of canvases) {
+      if (!canvas.nodes) continue;
+
+      for (const node of canvas.nodes) {
+        // Handle OTEL event nodes (top-level event/eventRef)
+        if (isOtelEventNode(node)) {
+          // Inline event definition
+          if (node.event && typeof node.event === 'object' && node.event.name) {
+            registry.addEvent(node.event.name, {
+              type: 'canvas',
+              path: canvasPath,
+              eventSchema: node.event,
+            });
+          }
+
+          // Event reference
+          if (node.eventRef && typeof node.eventRef === 'string') {
+            // Only add if not already in registry (library takes priority)
+            if (!registry.hasEvent(node.eventRef)) {
+              registry.addEvent(node.eventRef, {
+                type: 'canvas',
+                path: canvasPath,
+                // No schema available - it's just a reference
+              });
+            }
+          }
+        }
+        // Handle standard nodes with pv.event/pv.eventRef
+        else if (isStandardCanvasNode(node) && node.pv) {
+          // Inline event definition (pv.event)
+          if (node.pv.event && typeof node.pv.event === 'object' && node.pv.event.name) {
+            registry.addEvent(node.pv.event.name, {
+              type: 'canvas',
+              path: canvasPath,
+              eventSchema: node.pv.event,
+            });
+          }
+
+          // Event reference (pv.eventRef)
+          if (node.pv.eventRef && typeof node.pv.eventRef === 'string') {
+            // Only add if not already in registry (library takes priority)
+            if (!registry.hasEvent(node.pv.eventRef)) {
+              registry.addEvent(node.pv.eventRef, {
+                type: 'canvas',
+                path: canvasPath,
+                // No schema available - it's just a reference
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return registry;
+  }
+
+  /**
+   * Add an event source to the registry
+   */
+  private addEvent(eventName: string, source: EventSource): void {
+    const existing = this.events.get(eventName) ?? [];
+    // Avoid duplicate entries for the same path
+    if (!existing.some((s) => s.path === source.path && s.type === source.type)) {
+      existing.push(source);
+      this.events.set(eventName, existing);
+    }
+  }
+
+  /**
+   * Find all sources where an event is defined.
+   * Returns library sources first, then canvas sources.
+   *
+   * @param eventName - The event name to look up
+   * @returns Array of EventSource objects, empty if not found
+   */
+  findEvent(eventName: string): EventSource[] {
+    const sources = this.events.get(eventName) ?? [];
+    // Sort: library sources first, then canvases alphabetically
+    return [...sources].sort((a, b) => {
+      if (a.type === 'library' && b.type !== 'library') return -1;
+      if (a.type !== 'library' && b.type === 'library') return 1;
+      return a.path.localeCompare(b.path);
+    });
+  }
+
+  /**
+   * Check if an event exists anywhere in the registry.
+   *
+   * @param eventName - The event name to check
+   * @returns true if the event is defined somewhere
+   */
+  hasEvent(eventName: string): boolean {
+    return this.events.has(eventName);
+  }
+
+  /**
+   * Get all known event names in the registry.
+   *
+   * @returns Array of event names, sorted alphabetically
+   */
+  getAllEventNames(): string[] {
+    return [...this.events.keys()].sort();
+  }
+
+  /**
+   * Get the count of registered events.
+   */
+  get size(): number {
+    return this.events.size;
+  }
+}

package/src/registry/LocalRegistry.ts

@@ -0,0 +1,416 @@
+/**
+ * LocalRegistry - Browser-safe registry for local workspaces
+ *
+ * Features:
+ * - Uses FileTree abstraction (browser-safe)
+ * - No version registry lookups (uses FileTree directly)
+ * - Cache invalidation via external triggers
+ * - Supports multiple registered workspaces
+ * - Auto-discovers scope names from library.yaml resources
+ *
+ * Note: File watching must be handled externally by calling invalidateCache()
+ * when .principal-views files change.
+ */
+
+import type { FileTree, FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import type { StoryboardRegistryInterface, ScopeLookupResult } from '../types/registered-trace';
+import type { VersionSnapshot } from '../types/version-registry';
+import { CanvasDiscovery } from '../discovery/CanvasDiscovery';
+import { LibraryDiscovery } from '../discovery/LibraryDiscovery';
+
+/**
+ * File reader function type
+ */
+export type FileReader = (path: string) => Promise<string>;
+
+/**
+ * Workspace registration
+ */
+interface WorkspaceRegistration {
+  workspaceId: string;
+  fileTree: FileTree;
+  fileTreeSha: string; // SHA of the fileTree when scopes were discovered
+  serviceNames: string[]; // Service names (from service.name attribute)
+  ownedScopes: string[]; // All owned instrumentation scopes
+}
+
+/**
+ * Local registry for development mode
+ */
+export class LocalRegistry implements StoryboardRegistryInterface {
+  private cache = new Map<string, VersionSnapshot>();
+  private workspaces = new Map<string, WorkspaceRegistration>(); // workspaceId → registration
+  private scopeToWorkspaceId = new Map<string, string>(); // scopeName → workspaceId
+  private discovery: CanvasDiscovery;
+  private libraryDiscovery: LibraryDiscovery | null = null;
+
+  constructor(
+    private fileReader: FileReader,
+    fsAdapter?: FileSystemAdapter
+  ) {
+    this.discovery = new CanvasDiscovery();
+    if (fsAdapter) {
+      this.libraryDiscovery = new LibraryDiscovery(fsAdapter);
+    }
+  }
+
+  /**
+   * Register a local workspace
+   *
+   * Auto-discovers service names and owned scopes from library.yaml resources section.
+   * Each service in resources with a service.name becomes a registered scope.
+   * Additionally, owned-scopes from each service are mapped to their owning service.
+   *
+   * File watching should be handled externally. When .principal-views files change,
+   * call invalidateCache(scopeName) to rebuild the snapshot.
+   *
+   * @param fileTree - FileTree for the workspace
+   * @returns Array of all registered scope names (services + owned scopes)
+   */
+  async registerWorkspace(fileTree: FileTree): Promise<string[]> {
+    // Use stable identifier: rootPath (repository path) or sha (content hash)
+    // Note: metadata.id includes a timestamp suffix making it unique per build,
+    // which would cause duplicate registrations on every file tree update
+    const workspaceId =
+      (fileTree.metadata.sourceInfo?.rootPath as string) || fileTree.sha || fileTree.metadata.id;
+
+    // Check if already registered
+    if (this.workspaces.has(workspaceId)) {
+      const existing = this.workspaces.get(workspaceId)!;
+      const currentSha = fileTree.sha || '';
+
+      // Check if fileTree content changed (different SHA)
+      if (existing.fileTreeSha !== currentSha) {
+        console.log('[LocalRegistry] Workspace content changed, re-discovering scopes:', {
+          workspaceId,
+          oldSha: existing.fileTreeSha,
+          newSha: currentSha,
+        });
+
+        // Re-discover scope names from updated library.yaml
+        const { serviceNames, ownedScopes, scopeToServiceMap } = await this.discoverScopesInfo(fileTree);
+
+        // Clear old scope mappings
+        for (const scopeName of [...existing.serviceNames, ...existing.ownedScopes]) {
+          this.scopeToWorkspaceId.delete(scopeName);
+        }
+
+        // Update registration with new scope info
+        existing.fileTree = fileTree;
+        existing.fileTreeSha = currentSha;
+        existing.serviceNames = serviceNames;
+        existing.ownedScopes = ownedScopes;
+
+        // Update scope-to-workspace mapping with new scopes
+        for (const [scopeName] of scopeToServiceMap) {
+          this.scopeToWorkspaceId.set(scopeName, workspaceId);
+        }
+
+        console.log('[LocalRegistry] Updated workspace registration:', {
+          workspaceId,
+          serviceNames,
+          ownedScopes,
+          fileTreeSha: currentSha,
+        });
+
+        return [...new Set([...serviceNames, ...ownedScopes])];
+      }
+
+      console.log('[LocalRegistry] Workspace already registered (no changes):', workspaceId);
+      // Update the fileTree reference to the latest version
+      existing.fileTree = fileTree;
+      return [...new Set([...existing.serviceNames, ...existing.ownedScopes])];
+    }
+
+    // Auto-discover service names and owned scopes from library.yaml
+    const { serviceNames, ownedScopes, scopeToServiceMap } = await this.discoverScopesInfo(fileTree);
+
+    if (serviceNames.length === 0) {
+      console.warn('[LocalRegistry] No service names discovered for workspace:', workspaceId);
+      console.warn('[LocalRegistry] Make sure library.yaml has a resources section with service.name attributes');
+    }
+
+    // Register workspace
+    this.workspaces.set(workspaceId, {
+      workspaceId,
+      fileTree,
+      fileTreeSha: fileTree.sha || '',
+      serviceNames,
+      ownedScopes,
+    });
+
+    // Map all scope names (services + owned scopes) to this workspace
+    for (const [scopeName] of scopeToServiceMap) {
+      this.scopeToWorkspaceId.set(scopeName, workspaceId);
+    }
+
+    console.log('[LocalRegistry] Registered workspace:', {
+      workspaceId,
+      serviceNames,
+      ownedScopes,
+      fileTreeSha: fileTree.sha,
+    });
+
+    return [...new Set([...serviceNames, ...ownedScopes])];
+  }
+
+  /**
+   * Unregister a workspace (cleanup)
+   * @param workspaceId - Workspace ID (rootPath, sha, or metadata.id)
+   */
+  unregisterWorkspace(workspaceId: string): void {
+    const workspace = this.workspaces.get(workspaceId);
+    if (!workspace) {
+      return;
+    }
+
+    // Clear cache for all scope names (services + owned scopes)
+    const allScopes = [...workspace.serviceNames, ...workspace.ownedScopes];
+    for (const scopeName of allScopes) {
+      this.cache.delete(scopeName);
+      this.scopeToWorkspaceId.delete(scopeName);
+    }
+
+    // Remove registration
+    this.workspaces.delete(workspaceId);
+
+    console.log('[LocalRegistry] Unregistered workspace:', {
+      workspaceId,
+      serviceNames: workspace.serviceNames,
+      ownedScopes: workspace.ownedScopes,
+    });
+  }
+
+  async lookupByScope(
+    scope: { name: string; version: string },
+    _resource: { attributes?: Record<string, unknown> }
+  ): Promise<ScopeLookupResult> {
+    // Map scope name to workspace ID
+    const workspaceId = this.scopeToWorkspaceId.get(scope.name);
+    if (!workspaceId) {
+      console.log('[LocalRegistry] No workspace registered for scope:', scope.name);
+      return { found: false, reason: 'scope_not_owned', scopeName: scope.name };
+    }
+
+    const workspace = this.workspaces.get(workspaceId);
+    if (!workspace) {
+      console.error('[LocalRegistry] Workspace not found:', workspaceId);
+      return { found: false, reason: 'scope_not_owned', scopeName: scope.name };
+    }
+
+    // Check cache first (cache by scope name for granularity)
+    const cacheKey = scope.name;
+    if (this.cache.has(cacheKey)) {
+      const cachedSnapshot = this.cache.get(cacheKey)!;
+      if (cachedSnapshot.storyboards.length === 0) {
+        return { found: false, reason: 'no_storyboards', scopeName: scope.name };
+      }
+      return { found: true, snapshot: cachedSnapshot };
+    }
+
+    // Build VersionSnapshot from FileTree
+    const snapshot = await this.buildFromFileTree(workspace.fileTree);
+
+    // Cache it
+    this.cache.set(cacheKey, snapshot);
+
+    // Check if storyboards were found
+    if (snapshot.storyboards.length === 0) {
+      return { found: false, reason: 'no_storyboards', scopeName: scope.name };
+    }
+
+    return { found: true, snapshot };
+  }
+
+  /**
+   * Auto-discover service names and owned scopes from library.yaml files
+   *
+   * Uses LibraryDiscovery to find all library.yaml files across packages
+   * and extract service.name and owned-scopes from their resources sections.
+   *
+   * @param fileTree - FileTree to discover scopes from
+   * @returns Object with serviceNames, ownedScopes, and scopeToServiceMap
+   */
+  private async discoverScopesInfo(fileTree: FileTree): Promise<{
+    serviceNames: string[];
+    ownedScopes: string[];
+    scopeToServiceMap: Map<string, string>;
+  }> {
+    if (!this.libraryDiscovery) {
+      console.warn('[LocalRegistry] No LibraryDiscovery available - provide FileSystemAdapter to constructor');
+      return { serviceNames: [], ownedScopes: [], scopeToServiceMap: new Map() };
+    }
+
+    try {
+      const result = await this.libraryDiscovery.discover(fileTree, {
+        fileReader: this.fileReader,
+      });
+
+      if (result.errors.length > 0) {
+        console.warn('[LocalRegistry] Errors during library discovery:', result.errors);
+      }
+
+      // Collect all owned scopes across all services (deduplicated)
+      const ownedScopesSet = new Set<string>();
+      for (const lib of result.libraries) {
+        for (const service of lib.servicesWithScopes) {
+          for (const scope of service.ownedScopes) {
+            ownedScopesSet.add(scope);
+          }
+        }
+      }
+      const ownedScopes = [...ownedScopesSet];
+
+      console.log('[LocalRegistry] Discovered services and scopes:', {
+        serviceNames: result.allServiceNames,
+        ownedScopes,
+        scopeToServiceMapSize: result.scopeToServiceMap.size,
+      });
+
+      return {
+        serviceNames: result.allServiceNames,
+        ownedScopes,
+        scopeToServiceMap: result.scopeToServiceMap,
+      };
+    } catch (error) {
+      console.error('[LocalRegistry] Failed to discover scopes:', error);
+      return { serviceNames: [], ownedScopes: [], scopeToServiceMap: new Map() };
+    }
+  }
+
+  /**
+   * Build VersionSnapshot from FileTree using CanvasDiscovery
+   */
+  private async buildFromFileTree(fileTree: FileTree): Promise<VersionSnapshot> {
+    // Use CanvasDiscovery to find all storyboards
+    const discoveryResult = await this.discovery.discover(fileTree, {
+      fileReader: this.fileReader,
+      includeContent: true,
+    });
+
+    const snapshot: VersionSnapshot = {
+      repositoryUrl: 'local',
+      commitSha: fileTree.sha || 'dev',
+      storyboards: discoveryResult.storyboards,
+      registeredAt: new Date().toISOString(),
+      metadata: {
+        environment: 'development',
+        isLocal: true,
+      },
+    };
+
+    // Log errors if any
+    if (discoveryResult.errors.length > 0) {
+      console.warn('[LocalRegistry] Discovery errors:', discoveryResult.errors);
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Invalidate cache for a scope
+   *
+   * Call this when .principal-views files change to trigger rebuild on next lookup.
+   * Debouncing should be handled by external file watcher if needed.
+   */
+  invalidateCache(scopeName: string): void {
+    this.cache.delete(scopeName);
+    console.log('[LocalRegistry] Cache invalidated:', scopeName);
+  }
+
+  async listScopes(): Promise<Array<{ name: string; versions: string[] }>> {
+    const scopes: Array<{ name: string; versions: string[] }> = [];
+
+    for (const workspace of this.workspaces.values()) {
+      // Include service names and owned scopes
+      const allScopes = [...workspace.serviceNames, ...workspace.ownedScopes];
+      for (const scopeName of allScopes) {
+        scopes.push({
+          name: scopeName,
+          versions: ['dev'], // Local workspaces always use 'dev' version
+        });
+      }
+    }
+
+    return scopes;
+  }
+
+  supportsHotReload(): boolean {
+    return true;
+  }
+
+  /**
+   * Get list of registered workspaces
+   */
+  getRegisteredWorkspaces(): Array<{ scopeName: string; fileTreeSha: string }> {
+    const workspaces: Array<{ scopeName: string; fileTreeSha: string }> = [];
+
+    for (const workspace of this.workspaces.values()) {
+      // Include service names and owned scopes
+      const allScopes = [...workspace.serviceNames, ...workspace.ownedScopes];
+      for (const scopeName of allScopes) {
+        workspaces.push({
+          scopeName,
+          fileTreeSha: workspace.fileTree.sha || 'unknown',
+        });
+      }
+    }
+
+    return workspaces;
+  }
+
+  /**
+   * Get all cached VersionSnapshots
+   *
+   * Returns snapshots that have been built and cached via lookupByScope().
+   * Note: This only returns snapshots that have been looked up at least once.
+   * Call lookupByScope() for each scope to ensure all snapshots are cached.
+   */
+  getAllSnapshots(): VersionSnapshot[] {
+    return Array.from(this.cache.values());
+  }
+
+  /**
+   * Get all snapshots for all registered scopes
+   *
+   * Unlike getAllSnapshots(), this method ensures all registered scopes
+   * have their snapshots built and cached before returning.
+   * Note: Returns one snapshot per workspace (not per scope).
+   */
+  async getAllSnapshotsForRegisteredScopes(): Promise<VersionSnapshot[]> {
+    const snapshots: VersionSnapshot[] = [];
+    const seenWorkspaceIds = new Set<string>();
+
+    for (const workspace of this.workspaces.values()) {
+      // Only build one snapshot per workspace
+      if (seenWorkspaceIds.has(workspace.workspaceId)) continue;
+      seenWorkspaceIds.add(workspace.workspaceId);
+
+      // Use first service name to trigger snapshot build
+      const firstServiceName = workspace.serviceNames[0];
+      if (firstServiceName) {
+        const result = await this.lookupByScope(
+          { name: firstServiceName, version: 'dev' },
+          {}
+        );
+        if (result.found) {
+          snapshots.push(result.snapshot);
+        }
+      }
+    }
+
+    return snapshots;
+  }
+
+  /**
+   * Cleanup: clear all state
+   */
+  destroy(): void {
+    console.log('[LocalRegistry] Destroying and clearing state...');
+
+    // Clear state
+    this.workspaces.clear();
+    this.cache.clear();
+    this.discovery.clearCache();
+  }
+}