@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/registry/EventRegistry.ts

@@ -1,191 +0,0 @@
-/**
- * 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

@@ -1,416 +0,0 @@
-/**
- * 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();
-  }
-}