@principal-ai/subsystems-core 0.29.0

package/src/scopes/__tests__/utils.test.ts

@@ -0,0 +1,383 @@
+import { describe, it, expect } from 'vitest';
+import {
+  buildScopeColorMapFromCanvas,
+  buildScopeColorMap,
+  getScopeNamesFromCanvas,
+  getScopeNodeFromCanvas,
+  DEFAULT_SCOPE_COLOR,
+} from '../utils';
+import type { ExtendedCanvas, OtelScopeNode } from '../../types/canvas';
+
+describe('buildScopeColorMapFromCanvas', () => {
+  it('extracts colors from otel-scope nodes', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          color: '#3B82F6',
+          otel: { scope: 'auth-service' },
+        } as OtelScopeNode,
+        {
+          id: 'payment',
+          type: 'otel-scope',
+          x: 250,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Payment',
+          color: '#10B981',
+          otel: { scope: 'payment-service' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const colorMap = buildScopeColorMapFromCanvas(canvas);
+
+    expect(colorMap).toEqual({
+      'auth-service': '#3B82F6',
+      'payment-service': '#10B981',
+    });
+  });
+
+  it('ignores non-otel-scope nodes', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'regular',
+          type: 'text',
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 50,
+          text: 'Regular node',
+          color: '#FF0000',
+        },
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          color: '#3B82F6',
+          otel: { scope: 'auth' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const colorMap = buildScopeColorMapFromCanvas(canvas);
+
+    expect(colorMap).toEqual({ auth: '#3B82F6' });
+    expect(colorMap).not.toHaveProperty('regular');
+  });
+
+  it('uses default color when node has no color', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          otel: { scope: 'auth' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const colorMap = buildScopeColorMapFromCanvas(canvas);
+
+    expect(colorMap.auth).toBe(DEFAULT_SCOPE_COLOR);
+  });
+
+  it('handles canvas color presets', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          color: 1, // Red preset
+          otel: { scope: 'auth' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const colorMap = buildScopeColorMapFromCanvas(canvas);
+
+    // Red preset should resolve to red hex color
+    expect(colorMap.auth).toBe('#ef4444');
+  });
+
+  it('returns empty map for undefined canvas', () => {
+    const colorMap = buildScopeColorMapFromCanvas(undefined);
+    expect(colorMap).toEqual({});
+  });
+
+  it('returns empty map for canvas with no nodes', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [],
+      edges: [],
+    };
+
+    const colorMap = buildScopeColorMapFromCanvas(canvas);
+    expect(colorMap).toEqual({});
+  });
+
+  it('skips nodes with no otel.scope field', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'invalid',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Invalid',
+          color: '#3B82F6',
+          // Missing otel.scope
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const colorMap = buildScopeColorMapFromCanvas(canvas);
+    expect(colorMap).toEqual({});
+  });
+});
+
+describe('buildScopeColorMap', () => {
+  it('builds color map from scopesCanvas', () => {
+    const scopesCanvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          color: '#3B82F6',
+          otel: { scope: 'auth' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const colorMap = buildScopeColorMap(scopesCanvas);
+
+    expect(colorMap).toEqual({ auth: '#3B82F6' });
+  });
+
+  it('returns empty map when no canvas provided', () => {
+    const colorMap = buildScopeColorMap(undefined);
+
+    expect(colorMap).toEqual({});
+  });
+});
+
+describe('getScopeNamesFromCanvas', () => {
+  it('extracts all scope names', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          otel: { scope: 'auth-service' },
+        } as OtelScopeNode,
+        {
+          id: 'payment',
+          type: 'otel-scope',
+          x: 250,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Payment',
+          otel: { scope: 'payment-service' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const scopeNames = getScopeNamesFromCanvas(canvas);
+
+    expect(scopeNames).toEqual(['auth-service', 'payment-service']);
+  });
+
+  it('filters out non-otel-scope nodes', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'text-node',
+          type: 'text',
+          x: 0,
+          y: 0,
+          width: 100,
+          height: 50,
+          text: 'Text',
+        },
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          otel: { scope: 'auth' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const scopeNames = getScopeNamesFromCanvas(canvas);
+
+    expect(scopeNames).toEqual(['auth']);
+    expect(scopeNames).not.toContain('text-node');
+  });
+
+  it('returns empty array for undefined canvas', () => {
+    expect(getScopeNamesFromCanvas(undefined)).toEqual([]);
+  });
+
+  it('returns empty array for canvas with no nodes', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [],
+      edges: [],
+    };
+
+    expect(getScopeNamesFromCanvas(canvas)).toEqual([]);
+  });
+
+  it('filters out nodes without otel.scope', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'valid',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Valid',
+          otel: { scope: 'valid-scope' },
+        } as OtelScopeNode,
+        {
+          id: 'invalid',
+          type: 'otel-scope',
+          x: 250,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Invalid',
+          // Missing otel.scope
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const scopeNames = getScopeNamesFromCanvas(canvas);
+
+    expect(scopeNames).toEqual(['valid-scope']);
+  });
+});
+
+describe('getScopeNodeFromCanvas', () => {
+  it('finds scope node by name', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          color: '#3B82F6',
+          otel: { scope: 'auth-service' },
+        } as OtelScopeNode,
+        {
+          id: 'payment',
+          type: 'otel-scope',
+          x: 250,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Payment',
+          color: '#10B981',
+          otel: { scope: 'payment-service' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const node = getScopeNodeFromCanvas(canvas, 'auth-service');
+
+    expect(node).toBeDefined();
+    expect(node?.id).toBe('auth');
+    expect(node?.otel?.scope).toBe('auth-service');
+    expect(node?.color).toBe('#3B82F6');
+  });
+
+  it('returns undefined for non-existent scope', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [
+        {
+          id: 'auth',
+          type: 'otel-scope',
+          x: 0,
+          y: 0,
+          width: 200,
+          height: 80,
+          label: 'Auth',
+          otel: { scope: 'auth-service' },
+        } as OtelScopeNode,
+      ],
+      edges: [],
+    };
+
+    const node = getScopeNodeFromCanvas(canvas, 'non-existent');
+
+    expect(node).toBeUndefined();
+  });
+
+  it('returns undefined for undefined canvas', () => {
+    const node = getScopeNodeFromCanvas(undefined, 'auth-service');
+    expect(node).toBeUndefined();
+  });
+
+  it('returns undefined for canvas with no nodes', () => {
+    const canvas: ExtendedCanvas = {
+      nodes: [],
+      edges: [],
+    };
+
+    const node = getScopeNodeFromCanvas(canvas, 'auth-service');
+    expect(node).toBeUndefined();
+  });
+});

package/src/scopes/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Scopes module
+ *
+ * Provides utilities and validation for instrumentation scopes:
+ * - Scope utilities for working with top-level scopes and owned-scopes references
+ * - Validation for .scopes.canvas files that document scope boundaries
+ */
+
+export {
+  ScopesCanvasValidator,
+  type ScopesCanvasValidationContext,
+  type ScopesCanvasValidationResult,
+  type ScopesCanvasViolation,
+} from './ScopesCanvasValidator';
+
+export {
+  ScopePathIndex,
+  type ScopePathEntry,
+  type ScopePathMatch,
+} from './ScopePathIndex';
+
+export {
+  validateScopeNamespaceNesting,
+  type ScopeEventsCanvasPair,
+  type ValidateScopeNamespaceNestingInput,
+} from './validateScopeNamespaceNesting';
+
+export {
+  DEFAULT_SCOPE_COLOR,
+  DRAFT_NODE_COLOR,
+  getScopeNames,
+  getScopeDefinition,
+  getScopeColor,
+  getScopeIcon,
+  normalizeScopes,
+  buildScopeColorMap,
+  buildScopeColorMapFromCanvas,
+  getScopeNamesFromCanvas,
+  getScopeNodeFromCanvas,
+  getAllScopeNames,
+  type NormalizedScope,
+} from './utils';

package/src/scopes/utils.ts

@@ -0,0 +1,182 @@
+/**
+ * Scope utility functions
+ *
+ * Helpers for working with scopes defined in the top-level `scopes` section
+ * and referenced by resources via `owned-scopes`.
+ */
+
+import type { OwnedScopes, ScopeDefinition } from '../types/library';
+import type { ExtendedCanvas, OtelScopeNode } from '../types/canvas';
+import { isOtelScopeNode, resolveCanvasColor } from '../types/canvas';
+
+/** Default color for scopes without a defined color */
+export const DEFAULT_SCOPE_COLOR = '#6B7280'; // gray-500
+
+/** Default color for draft nodes (no scope) */
+export const DRAFT_NODE_COLOR = '#9CA3AF'; // gray-400
+
+/**
+ * Normalized scope entry with name and definition
+ */
+export interface NormalizedScope {
+  name: string;
+  color: string;
+  /** Icon identifier (Lucide icons) */
+  icon?: string;
+  description?: string;
+  /** Whether this scope is defined externally (in another library) */
+  external?: boolean;
+}
+
+/**
+ * Get all scope names from owned-scopes array
+ */
+export function getScopeNames(scopes: OwnedScopes | undefined): string[] {
+  return scopes ?? [];
+}
+
+/**
+ * Get scope definition by name from library scopes
+ */
+export function getScopeDefinition(
+  libraryScopes: Record<string, ScopeDefinition> | undefined,
+  scopeName: string
+): ScopeDefinition | undefined {
+  return libraryScopes?.[scopeName];
+}
+
+/**
+ * Get scope color by name from library scopes
+ * Returns the defined color, or default color if not found
+ */
+export function getScopeColor(
+  libraryScopes: Record<string, ScopeDefinition> | undefined,
+  scopeName: string
+): string {
+  return libraryScopes?.[scopeName]?.color ?? DEFAULT_SCOPE_COLOR;
+}
+
+/**
+ * Normalize scope names to NormalizedScope array using library scope definitions
+ */
+export function normalizeScopes(
+  scopeNames: OwnedScopes | undefined,
+  libraryScopes: Record<string, ScopeDefinition> | undefined
+): NormalizedScope[] {
+  if (!scopeNames) return [];
+
+  return scopeNames.map((name) => {
+    const definition = libraryScopes?.[name];
+    return {
+      name,
+      color: definition?.color ?? DEFAULT_SCOPE_COLOR,
+      icon: definition?.icon,
+      description: definition?.description,
+      external: definition?.external,
+    };
+  });
+}
+
+/**
+ * Get scope icon by name from library scopes
+ * Returns the defined icon, or undefined if not found
+ */
+export function getScopeIcon(
+  libraryScopes: Record<string, ScopeDefinition> | undefined,
+  scopeName: string
+): string | undefined {
+  return libraryScopes?.[scopeName]?.icon;
+}
+
+/**
+ * Build a scope color map from .scopes.canvas
+ * Returns a simple name -> color mapping for fast lookups
+ *
+ * @deprecated The library.scopes parameter has been removed. Use scopesCanvas instead.
+ * @param scopesCanvas - Canvas containing scope definitions with colors
+ * @returns Map of scope name to color (hex format)
+ */
+export function buildScopeColorMap(
+  scopesCanvas: ExtendedCanvas | undefined
+): Record<string, string> {
+  return buildScopeColorMapFromCanvas(scopesCanvas);
+}
+
+/**
+ * Get all scope names defined in library
+ */
+export function getAllScopeNames(
+  library: { scopes?: Record<string, ScopeDefinition> } | undefined
+): string[] {
+  if (!library?.scopes) return [];
+  return Object.keys(library.scopes);
+}
+
+/**
+ * Build scope color map from .scopes.canvas nodes
+ * Extracts color from otel-scope nodes only
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @returns Map of scope name to color (hex format)
+ */
+export function buildScopeColorMapFromCanvas(
+  scopesCanvas: ExtendedCanvas | undefined
+): Record<string, string> {
+  const colorMap: Record<string, string> = {};
+
+  if (!scopesCanvas?.nodes) return colorMap;
+
+  for (const node of scopesCanvas.nodes) {
+    // Only process otel-scope nodes
+    if (!isOtelScopeNode(node)) continue;
+
+    const scopeName = node.otel?.scope;
+    if (!scopeName) continue;
+
+    // Get color from node.color field and resolve presets to hex
+    const resolvedColor = resolveCanvasColor(node.color);
+    if (resolvedColor) {
+      colorMap[scopeName] = resolvedColor;
+    } else {
+      // Use default color if no color specified
+      colorMap[scopeName] = DEFAULT_SCOPE_COLOR;
+    }
+  }
+
+  return colorMap;
+}
+
+/**
+ * Extract all scope names from a scopes canvas
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @returns Array of scope names
+ */
+export function getScopeNamesFromCanvas(
+  scopesCanvas: ExtendedCanvas | undefined
+): string[] {
+  if (!scopesCanvas?.nodes) return [];
+
+  return scopesCanvas.nodes
+    .filter(isOtelScopeNode)
+    .map(node => node.otel?.scope)
+    .filter((scope): scope is string => !!scope);
+}
+
+/**
+ * Get scope node by scope name
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @param scopeName - Name of the scope to find
+ * @returns The scope node, or undefined if not found
+ */
+export function getScopeNodeFromCanvas(
+  scopesCanvas: ExtendedCanvas | undefined,
+  scopeName: string
+): OtelScopeNode | undefined {
+  if (!scopesCanvas?.nodes) return undefined;
+
+  return scopesCanvas.nodes.find(
+    node => isOtelScopeNode(node) && node.otel?.scope === scopeName
+  ) as OtelScopeNode | undefined;
+}