@principal-ai/subsystems-core 0.29.0 → 0.31.0

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

@@ -1,383 +0,0 @@
-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

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

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