@principal-ai/subsystems-core 0.29.0

package/src/discovery/LibraryDiscovery.test.ts

@@ -0,0 +1,329 @@
+import { describe, expect, test, beforeEach } from 'bun:test';
+import { LibraryDiscovery } from './LibraryDiscovery';
+import type { FileTree, FileInfo, DirectoryInfo, FileSystemAdapter } from '@principal-ai/repository-abstraction';
+
+describe('LibraryDiscovery', () => {
+  let discovery: LibraryDiscovery;
+  let mockFsAdapter: FileSystemAdapter;
+
+  beforeEach(() => {
+    mockFsAdapter = createMockFsAdapter({});
+    discovery = new LibraryDiscovery(mockFsAdapter);
+  });
+
+  describe('scopes canvas validation', () => {
+    test('adds error when library has owned-scopes but no .scopes.canvas file', async () => {
+      const libraryYaml = `
+version: '1.0'
+name: test-library
+scopes:
+  scope-a:
+    color: "#ff0000"
+  scope-b:
+    color: "#00ff00"
+nodeComponents:
+  box: { shape: rectangle }
+edgeComponents:
+  connection: {}
+resources:
+  my-service:
+    service.name: my-service
+    owned-scopes:
+      - scope-a
+      - scope-b
+`;
+      mockFsAdapter = createMockFsAdapter({
+        '/.principal-views': { isDir: true, contents: ['library.yaml'] },
+        '/.principal-views/library.yaml': { content: libraryYaml },
+      });
+      discovery = new LibraryDiscovery(mockFsAdapter);
+
+      const fileTree = createMockFileTree([
+        '.principal-views/library.yaml',
+      ]);
+
+      const result = await discovery.discover(fileTree);
+
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0].type).toBe('scopes-canvas-required');
+      expect(result.errors[0].message).toContain('owned-scopes');
+      expect(result.errors[0].message).toContain('scope-a');
+      expect(result.errors[0].message).toContain('scope-b');
+    });
+
+    test('no error when library has owned-scopes and .scopes.canvas exists', async () => {
+      const libraryYaml = `
+version: '1.0'
+name: test-library
+scopes:
+  scope-a:
+    color: "#ff0000"
+nodeComponents:
+  box: { shape: rectangle }
+edgeComponents:
+  connection: {}
+resources:
+  my-service:
+    service.name: my-service
+    owned-scopes:
+      - scope-a
+`;
+      mockFsAdapter = createMockFsAdapter({
+        '/.principal-views': { isDir: true, contents: ['library.yaml', 'architecture.scopes.canvas'] },
+        '/.principal-views/library.yaml': { content: libraryYaml },
+        '/.principal-views/architecture.scopes.canvas': { content: '{}' },
+      });
+      discovery = new LibraryDiscovery(mockFsAdapter);
+
+      const fileTree = createMockFileTree([
+        '.principal-views/library.yaml',
+        '.principal-views/architecture.scopes.canvas',
+      ]);
+
+      const result = await discovery.discover(fileTree);
+
+      // No scopes-canvas-required errors
+      const scopesErrors = result.errors.filter(e => e.type === 'scopes-canvas-required');
+      expect(scopesErrors).toHaveLength(0);
+    });
+
+    test('no error when library has no owned-scopes', async () => {
+      const libraryYaml = `
+version: '1.0'
+name: test-library
+nodeComponents:
+  box: { shape: rectangle }
+edgeComponents:
+  connection: {}
+resources:
+  my-service:
+    service.name: my-service
+`;
+      mockFsAdapter = createMockFsAdapter({
+        '/.principal-views': { isDir: true, contents: ['library.yaml'] },
+        '/.principal-views/library.yaml': { content: libraryYaml },
+      });
+      discovery = new LibraryDiscovery(mockFsAdapter);
+
+      const fileTree = createMockFileTree([
+        '.principal-views/library.yaml',
+      ]);
+
+      const result = await discovery.discover(fileTree);
+
+      // No errors
+      expect(result.errors).toHaveLength(0);
+    });
+
+    test('validates scope references exist in top-level scopes', async () => {
+      const libraryYaml = `
+version: '1.0'
+name: test-library
+scopes:
+  scope-a:
+    color: "#ff0000"
+  scope-b:
+    color: "#00ff00"
+nodeComponents:
+  box: { shape: rectangle }
+edgeComponents:
+  connection: {}
+resources:
+  my-service:
+    service.name: my-service
+    owned-scopes:
+      - scope-a
+      - scope-b
+`;
+      mockFsAdapter = createMockFsAdapter({
+        '/.principal-views': { isDir: true, contents: ['library.yaml'] },
+        '/.principal-views/library.yaml': { content: libraryYaml },
+      });
+      discovery = new LibraryDiscovery(mockFsAdapter);
+
+      const fileTree = createMockFileTree([
+        '.principal-views/library.yaml',
+      ]);
+
+      const result = await discovery.discover(fileTree);
+
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0].type).toBe('scopes-canvas-required');
+      expect(result.errors[0].message).toContain('scope-a');
+      expect(result.errors[0].message).toContain('scope-b');
+    });
+
+    test('finds .scopes.canvas in subdirectory', async () => {
+      const libraryYaml = `
+version: '1.0'
+name: test-library
+scopes:
+  scope-a:
+    color: "#ff0000"
+nodeComponents:
+  box: { shape: rectangle }
+edgeComponents:
+  connection: {}
+resources:
+  my-service:
+    service.name: my-service
+    owned-scopes:
+      - scope-a
+`;
+      mockFsAdapter = createMockFsAdapter({
+        '/.principal-views': { isDir: true, contents: ['library.yaml', 'architecture'] },
+        '/.principal-views/library.yaml': { content: libraryYaml },
+        '/.principal-views/architecture': { isDir: true, contents: ['architecture.scopes.canvas'] },
+        '/.principal-views/architecture/architecture.scopes.canvas': { content: '{}' },
+      });
+      discovery = new LibraryDiscovery(mockFsAdapter);
+
+      const fileTree = createMockFileTree([
+        '.principal-views/library.yaml',
+        '.principal-views/architecture/architecture.scopes.canvas',
+      ]);
+
+      const result = await discovery.discover(fileTree);
+
+      // No scopes-canvas-required errors
+      const scopesErrors = result.errors.filter(e => e.type === 'scopes-canvas-required');
+      expect(scopesErrors).toHaveLength(0);
+    });
+
+    test('validation can be disabled with requireScopesCanvas: false', async () => {
+      const libraryYaml = `
+version: '1.0'
+name: test-library
+scopes:
+  scope-a:
+    color: "#ff0000"
+nodeComponents:
+  box: { shape: rectangle }
+edgeComponents:
+  connection: {}
+resources:
+  my-service:
+    service.name: my-service
+    owned-scopes:
+      - scope-a
+`;
+      mockFsAdapter = createMockFsAdapter({
+        '/.principal-views': { isDir: true, contents: ['library.yaml'] },
+        '/.principal-views/library.yaml': { content: libraryYaml },
+      });
+      discovery = new LibraryDiscovery(mockFsAdapter);
+
+      const fileTree = createMockFileTree([
+        '.principal-views/library.yaml',
+      ]);
+
+      const result = await discovery.discover(fileTree, { requireScopesCanvas: false });
+
+      // No errors when validation is disabled
+      expect(result.errors).toHaveLength(0);
+    });
+  });
+});
+
+/**
+ * Helper to create mock FileTree for testing
+ */
+function createMockFileTree(paths: string[]): FileTree {
+  const allFiles: FileInfo[] = paths.map(path => ({
+    path,
+    relativePath: path,
+    name: path.split('/').pop() || '',
+    extension: path.split('.').pop() || '',
+    size: 100,
+    lastModified: new Date(),
+    isDirectory: false,
+  }));
+
+  const root: DirectoryInfo = {
+    path: '/',
+    name: '',
+    relativePath: '',
+    children: [],
+    fileCount: allFiles.length,
+    totalSize: allFiles.length * 100,
+    depth: 0,
+  };
+
+  return {
+    sha: 'test-sha-' + Math.random(),
+    root,
+    allFiles,
+    allDirectories: [],
+    stats: {
+      totalFiles: allFiles.length,
+      totalDirectories: 0,
+      totalSize: allFiles.length * 100,
+      maxDepth: 3,
+    },
+    metadata: {
+      id: 'test',
+      timestamp: new Date(),
+      sourceType: 'test',
+      sourceInfo: {},
+    },
+  };
+}
+
+/**
+ * Helper to create mock FileSystemAdapter for testing
+ */
+function createMockFsAdapter(
+  files: Record<string, { content?: string; isDir?: boolean; contents?: string[] }>
+): FileSystemAdapter {
+  return {
+    async readFile(path: string): Promise<string> {
+      const file = files[path];
+      if (file?.content !== undefined) {
+        return file.content;
+      }
+      throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    },
+    async exists(path: string): Promise<boolean> {
+      return path in files;
+    },
+    async isDirectory(path: string): Promise<boolean> {
+      return files[path]?.isDir === true;
+    },
+    async readDir(path: string): Promise<string[]> {
+      const file = files[path];
+      if (file?.isDir && file.contents) {
+        return file.contents;
+      }
+      return [];
+    },
+    join(...parts: string[]): string {
+      return parts.join('/').replace(/\/+/g, '/');
+    },
+    dirname(path: string): string {
+      return path.split('/').slice(0, -1).join('/');
+    },
+    basename(path: string): string {
+      return path.split('/').pop() || '';
+    },
+    async writeFile(): Promise<void> {},
+    async mkdir(): Promise<void> {},
+    async rm(): Promise<void> {},
+    async stat(): Promise<{ isDirectory: boolean; size: number; mtime: Date }> {
+      return { isDirectory: false, size: 0, mtime: new Date() };
+    },
+    async copyFile(): Promise<void> {},
+    async rename(): Promise<void> {},
+    async getAbsolutePath(path: string): Promise<string> {
+      return path;
+    },
+    isAbsolute(path: string): boolean {
+      return path.startsWith('/');
+    },
+    resolve(...paths: string[]): string {
+      return paths.join('/').replace(/\/+/g, '/');
+    },
+    relative(from: string, to: string): string {
+      return to.replace(from, '').replace(/^\//, '');
+    },
+  };
+}

package/src/discovery/LibraryDiscovery.ts

@@ -0,0 +1,386 @@
+/**
+ * Library Discovery System
+ *
+ * Discovers all library.yaml files across a monorepo's packages and loads their resources.
+ * This is the package-aware equivalent of LibraryLoader.
+ */
+
+import type { FileTree, FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import { PackageLayerModule, type PackageLayer } from '@principal-ai/codebase-composition';
+import { LibraryLoader } from '../LibraryLoader';
+import type { ComponentLibrary } from '../types/library';
+import { getScopeNames } from '../scopes/utils';
+import type { LibraryValidationError, LibraryValidationErrorType } from '../validation';
+
+/**
+ * Service with its owned scopes
+ */
+export interface ServiceWithScopes {
+  /** Service name (from service.name attribute) */
+  serviceName: string;
+
+  /** Instrumentation scopes owned by this service */
+  ownedScopes: string[];
+}
+
+/**
+ * Discovered library with metadata
+ */
+export interface DiscoveredLibrary {
+  /** Library file path */
+  path: string;
+
+  /** Package this library belongs to */
+  packageName: string;
+
+  /** Package path */
+  packagePath: string;
+
+  /** Loaded library content */
+  library: ComponentLibrary;
+
+  /** Service names from this library's resources */
+  serviceNames: string[];
+
+  /** Services with their owned scopes */
+  servicesWithScopes: ServiceWithScopes[];
+}
+
+// Re-export validation types from shared module
+export type { LibraryValidationError, LibraryValidationErrorType };
+
+/**
+ * Result of library discovery
+ */
+export interface LibraryDiscoveryResult {
+  /** All discovered libraries */
+  libraries: DiscoveredLibrary[];
+
+  /** All service names across all libraries */
+  allServiceNames: string[];
+
+  /**
+   * Mapping from instrumentation scope name to owning service name
+   *
+   * Used to route spans from owned scopes to the correct service's storyboards.
+   * For example: { "auth-me": "web-ade", "checkout": "web-ade" }
+   */
+  scopeToServiceMap: Map<string, string>;
+
+  /** Errors encountered during discovery */
+  errors: LibraryValidationError[];
+}
+
+/**
+ * Discovery system for finding and loading all library.yaml files in a monorepo
+ *
+ * @example
+ * ```typescript
+ * const discovery = new LibraryDiscovery(fsAdapter);
+ * const result = await discovery.discover(fileTree);
+ *
+ * console.log('Found libraries:', result.libraries.length);
+ * console.log('All services:', result.allServiceNames);
+ * ```
+ */
+export class LibraryDiscovery {
+  private static readonly CANVAS_DIR = '.principal-views';
+
+  private packageModule: PackageLayerModule;
+  private packageCache: Map<string, PackageLayer[]> = new Map();
+  private loader: LibraryLoader;
+
+  constructor(private fsAdapter: FileSystemAdapter) {
+    this.packageModule = new PackageLayerModule();
+    this.loader = new LibraryLoader(fsAdapter);
+  }
+
+  /**
+   * Discover all library.yaml files in the file tree
+   *
+   * @param fileTree - FileTree from repository-abstraction
+   * @param options - Discovery options
+   * @param options.fileReader - Optional function to read file contents (for package.json parsing)
+   * @param options.requireScopesCanvas - If true, validates that .scopes.canvas exists when owned-scopes is defined (default: true)
+   * @returns Discovery result with libraries, service names, and errors
+   */
+  async discover(
+    fileTree: FileTree,
+    options?: {
+      fileReader?: (path: string) => Promise<string>;
+      requireScopesCanvas?: boolean;
+    }
+  ): Promise<LibraryDiscoveryResult> {
+    const { fileReader, requireScopesCanvas = true } = options || {};
+    const errors: LibraryValidationError[] = [];
+    const libraries: DiscoveredLibrary[] = [];
+
+    // 1. Discover packages (with caching by fileTree.sha)
+    const packages = await this.discoverPackagesWithCache(fileTree, fileReader);
+
+    // 2. For each package, try to load its library.yaml
+    // Note: pkg.packageData.path is relative (e.g., '' for root or 'packages/foo' for nested)
+    // We must resolve against fileTree.root.path to get absolute paths for fsAdapter calls
+    const rootPath = fileTree.root.path;
+
+    for (const pkg of packages) {
+      try {
+        // Resolve package path to absolute
+        const absolutePackagePath = pkg.packageData.path
+          ? this.fsAdapter.join(rootPath, pkg.packageData.path)
+          : rootPath;
+
+        // Check if this package has a .principal-views directory
+        const pvDir = this.fsAdapter.join(absolutePackagePath, LibraryDiscovery.CANVAS_DIR);
+        const pvDirExists = await this.fsAdapter.exists(pvDir);
+
+        if (!pvDirExists) {
+          continue; // No .principal-views directory, skip
+        }
+
+        // Try to load library from this package
+        const loadResult = await this.loader.load(absolutePackagePath);
+
+        if (loadResult.success && loadResult.library) {
+          // Extract service names and owned scopes from resources
+          const { serviceNames, servicesWithScopes } = this.extractServicesInfo(loadResult.library);
+
+          libraries.push({
+            path: loadResult.path,
+            packageName: pkg.packageData.name,
+            packagePath: pkg.packageData.path,
+            library: loadResult.library,
+            serviceNames,
+            servicesWithScopes,
+          });
+
+          // Validate scopes canvas requirement
+          if (requireScopesCanvas) {
+            await this.validateScopesCanvasRequirement(
+              absolutePackagePath,
+              servicesWithScopes,
+              loadResult.path,
+              errors
+            );
+          }
+        } else if (loadResult.error && !loadResult.error.includes('No library file found')) {
+          // Only report errors that aren't "file not found" (which is normal)
+          errors.push({
+            path: loadResult.path,
+            message: loadResult.error,
+            type: 'parse-error',
+          });
+        }
+      } catch (error) {
+        errors.push({
+          path: pkg.packageData.path,
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    // 3. Also check root directory for a library.yaml (non-package libraries)
+    try {
+      const rootPath = fileTree.root.path;
+      const hasRootLibrary = await this.loader.hasLibrary(rootPath);
+
+      if (hasRootLibrary) {
+        const loadResult = await this.loader.load(rootPath);
+
+        if (loadResult.success && loadResult.library) {
+          const { serviceNames, servicesWithScopes } = this.extractServicesInfo(loadResult.library);
+
+          // Check if we already loaded this from a package
+          const alreadyLoaded = libraries.some(lib => lib.path === loadResult.path);
+
+          if (!alreadyLoaded) {
+            libraries.push({
+              path: loadResult.path,
+              packageName: 'root',
+              packagePath: rootPath,
+              library: loadResult.library,
+              serviceNames,
+              servicesWithScopes,
+            });
+
+            // Validate scopes canvas requirement for root library
+            if (requireScopesCanvas) {
+              await this.validateScopesCanvasRequirement(
+                rootPath,
+                servicesWithScopes,
+                loadResult.path,
+                errors
+              );
+            }
+          }
+        } else if (loadResult.error) {
+          errors.push({
+            path: loadResult.path,
+            message: loadResult.error,
+            type: 'parse-error',
+          });
+        }
+      }
+    } catch (error) {
+      // Ignore root library errors
+    }
+
+    // 4. Collect all service names
+    const allServiceNames = libraries.flatMap(lib => lib.serviceNames);
+
+    // 5. Build scope to service mapping
+    const scopeToServiceMap = new Map<string, string>();
+    for (const lib of libraries) {
+      for (const service of lib.servicesWithScopes) {
+        // Map the service name to itself (service names are also valid scope names)
+        scopeToServiceMap.set(service.serviceName, service.serviceName);
+
+        // Map each owned scope to its owning service
+        for (const scope of service.ownedScopes) {
+          scopeToServiceMap.set(scope, service.serviceName);
+        }
+      }
+    }
+
+    // 6. Sort libraries by package name
+    libraries.sort((a, b) => a.packageName.localeCompare(b.packageName));
+
+    return {
+      libraries,
+      allServiceNames,
+      scopeToServiceMap,
+      errors,
+    };
+  }
+
+  /**
+   * Clear package cache (useful when file tree changes)
+   */
+  clearCache(): void {
+    this.packageCache.clear();
+  }
+
+  /**
+   * Extract service names and owned scopes from a library's resources
+   */
+  private extractServicesInfo(library: ComponentLibrary): {
+    serviceNames: string[];
+    servicesWithScopes: ServiceWithScopes[];
+  } {
+    if (!library.resources) {
+      return { serviceNames: [], servicesWithScopes: [] };
+    }
+
+    const serviceNames: string[] = [];
+    const servicesWithScopes: ServiceWithScopes[] = [];
+
+    for (const attrs of Object.values(library.resources)) {
+      const serviceName = attrs['service.name'];
+      if (!serviceName) continue;
+
+      serviceNames.push(serviceName);
+
+      // Extract owned-scopes (supports both legacy array and new record format)
+      const ownedScopes = attrs['owned-scopes'];
+      const scopeNames = getScopeNames(ownedScopes);
+
+      servicesWithScopes.push({
+        serviceName,
+        ownedScopes: scopeNames,
+      });
+    }
+
+    return { serviceNames, servicesWithScopes };
+  }
+
+  /**
+   * Validate that a .scopes.canvas file exists when owned-scopes is defined
+   */
+  private async validateScopesCanvasRequirement(
+    packagePath: string,
+    servicesWithScopes: ServiceWithScopes[],
+    libraryPath: string,
+    errors: LibraryValidationError[]
+  ): Promise<void> {
+    // Check if any service has owned-scopes
+    const hasOwnedScopes = servicesWithScopes.some(s => s.ownedScopes.length > 0);
+    if (!hasOwnedScopes) {
+      return; // No owned-scopes defined, no canvas required
+    }
+
+    // Collect all owned scopes
+    const allOwnedScopes = servicesWithScopes.flatMap(s => s.ownedScopes);
+
+    // Check if a .scopes.canvas file exists
+    // Look for any file matching *.scopes.canvas in .principal-views/
+    const pvDir = this.fsAdapter.join(packagePath, LibraryDiscovery.CANVAS_DIR);
+    const pvDirExists = await this.fsAdapter.exists(pvDir);
+
+    if (!pvDirExists) {
+      errors.push({
+        path: libraryPath,
+        message: `Scopes canvas required: library.yaml defines owned-scopes [${allOwnedScopes.join(', ')}] but no .principal-views/ directory exists. Create a .scopes.canvas file (e.g., architecture.scopes.canvas) documenting scope boundaries.`,
+        type: 'scopes-canvas-required',
+      });
+      return;
+    }
+
+    // Check for any .scopes.canvas file in the directory
+    const scopesCanvasExists = await this.checkScopesCanvasExists(pvDir);
+
+    if (!scopesCanvasExists) {
+      errors.push({
+        path: libraryPath,
+        message: `Scopes canvas required: library.yaml defines owned-scopes [${allOwnedScopes.join(', ')}] but no .scopes.canvas file found. Create a .scopes.canvas file (e.g., .principal-views/architecture.scopes.canvas) with nodes for each scope (set pv.otel.scope to the scope name).`,
+        type: 'scopes-canvas-required',
+      });
+    }
+  }
+
+  /**
+   * Check if any .scopes.canvas file exists in a directory
+   */
+  private async checkScopesCanvasExists(dirPath: string): Promise<boolean> {
+    try {
+      const entries = await this.fsAdapter.readDir(dirPath);
+      for (const entry of entries) {
+        if (entry.endsWith('.scopes.canvas')) {
+          return true;
+        }
+        // Also check subdirectories (for hierarchical structure)
+        const fullPath = this.fsAdapter.join(dirPath, entry);
+        const isDir = await this.fsAdapter.isDirectory(fullPath);
+        if (isDir) {
+          const subEntries = await this.fsAdapter.readDir(fullPath);
+          for (const subEntry of subEntries) {
+            if (subEntry.endsWith('.scopes.canvas')) {
+              return true;
+            }
+          }
+        }
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Discover packages with caching by fileTree SHA
+   */
+  private async discoverPackagesWithCache(
+    fileTree: FileTree,
+    fileReader?: (path: string) => Promise<string>
+  ): Promise<PackageLayer[]> {
+    const cacheKey = fileTree.sha;
+
+    if (this.packageCache.has(cacheKey)) {
+      return this.packageCache.get(cacheKey)!;
+    }
+
+    const packages = await this.packageModule.discoverPackages(fileTree, fileReader);
+    this.packageCache.set(cacheKey, packages);
+
+    return packages;
+  }
+}