@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/src/scopes/validateScopeNamespaceNesting.test.ts

@@ -1,127 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { validateScopeNamespaceNesting } from './validateScopeNamespaceNesting';
-import type { ExtendedCanvas } from '../types/canvas';
-
-function scopesCanvas(nodes: Array<{ scope: string; paths?: string[] }>): ExtendedCanvas {
-  return {
-    nodes: nodes.map((n, i) => ({
-      id: `s${i}`,
-      type: 'otel-scope',
-      description: `${n.scope} scope`,
-      ...(n.paths !== undefined ? { paths: n.paths } : {}),
-      otel: { scope: n.scope },
-      x: 0, y: 0, width: 100, height: 50,
-    })),
-    edges: [],
-  } as ExtendedCanvas;
-}
-
-function eventsCanvas(namespaces: Array<{ name: string; paths?: string[] }>): ExtendedCanvas {
-  return {
-    nodes: namespaces.map((ns, i) => ({
-      id: `n${i}`,
-      type: 'event-namespace',
-      namespace: {
-        name: ns.name,
-        description: `${ns.name} namespace`,
-        ...(ns.paths !== undefined ? { paths: ns.paths } : {}),
-        events: [],
-      },
-      x: 0, y: 0, width: 100, height: 50,
-    })),
-    edges: [],
-  } as ExtendedCanvas;
-}
-
-describe('validateScopeNamespaceNesting', () => {
-  test('passes when every namespace path is covered by its scope path', () => {
-    const violations = validateScopeNamespaceNesting({
-      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/subsystems-core/src'] }]),
-      eventsCanvases: [
-        {
-          scope: 'a',
-          eventsCanvas: eventsCanvas([
-            { name: 'events', paths: ['packages/subsystems-core/src/events'] },
-            { name: 'workflow', paths: ['packages/subsystems-core/src/workflow'] },
-          ]),
-        },
-      ],
-    });
-    expect(violations).toHaveLength(0);
-  });
-
-  test('flags namespace paths that escape their scope', () => {
-    const violations = validateScopeNamespaceNesting({
-      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/subsystems-core/src'] }]),
-      eventsCanvases: [
-        {
-          scope: 'a',
-          eventsCanvas: eventsCanvas([
-            { name: 'rogue', paths: ['packages/subsystems-react/src/hooks'] },
-          ]),
-        },
-      ],
-    });
-    expect(violations).toHaveLength(1);
-    expect(violations[0].ruleId).toBe('scopes-namespace-paths-escape');
-    expect(violations[0].severity).toBe('error');
-    expect(violations[0].message).toContain('rogue');
-    expect(violations[0].message).toContain('packages/subsystems-react/src/hooks');
-  });
-
-  test('namespace path equal to scope path is covered (not an escape)', () => {
-    const violations = validateScopeNamespaceNesting({
-      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/subsystems-core/src'] }]),
-      eventsCanvases: [
-        {
-          scope: 'a',
-          eventsCanvas: eventsCanvas([{ name: 'whole', paths: ['packages/subsystems-core/src'] }]),
-        },
-      ],
-    });
-    expect(violations).toHaveLength(0);
-  });
-
-  test('scope without paths imposes no constraint (opt-out)', () => {
-    const violations = validateScopeNamespaceNesting({
-      scopesCanvas: scopesCanvas([{ scope: 'a' }]),
-      eventsCanvases: [
-        {
-          scope: 'a',
-          eventsCanvas: eventsCanvas([{ name: 'anywhere', paths: ['packages/anywhere/src'] }]),
-        },
-      ],
-    });
-    expect(violations).toHaveLength(0);
-  });
-
-  test('namespaces without paths are skipped (opt-in per namespace)', () => {
-    const violations = validateScopeNamespaceNesting({
-      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/subsystems-core/src'] }]),
-      eventsCanvases: [
-        {
-          scope: 'a',
-          eventsCanvas: eventsCanvas([{ name: 'unenforced' }]),
-        },
-      ],
-    });
-    expect(violations).toHaveLength(0);
-  });
-
-  test('multiple scope paths: namespace covered by any one is allowed', () => {
-    const violations = validateScopeNamespaceNesting({
-      scopesCanvas: scopesCanvas([
-        { scope: 'a', paths: ['packages/subsystems-core/src', 'packages/subsystems-core/generated'] },
-      ]),
-      eventsCanvases: [
-        {
-          scope: 'a',
-          eventsCanvas: eventsCanvas([
-            { name: 'gen', paths: ['packages/subsystems-core/generated/events'] },
-          ]),
-        },
-      ],
-    });
-    expect(violations).toHaveLength(0);
-  });
-});

package/src/scopes/validateScopeNamespaceNesting.ts

@@ -1,88 +0,0 @@
-/**
- * Scope-Namespace Nesting Validator
- *
- * Cross-canvas check: every `event-namespace.paths` entry declared in a
- * scope's events canvas must be covered by that scope's own `paths`.
- * Surfaces `scopes-namespace-paths-escape` when a namespace claims a region
- * outside its owning scope.
- *
- * Runs alongside the existing scopes-canvas validation but requires both
- * canvases as input, so it lives outside `ScopesCanvasValidator` (which is
- * single-canvas).
- */
-
-import type { ExtendedCanvas } from '../types/canvas';
-import { isOtelScopeNode } from '../types/canvas';
-import { pathCovers } from '../events/path-helpers';
-import type { ScopesCanvasViolation } from './ScopesCanvasValidator';
-
-/**
- * One events canvas paired with the scope it documents.
- * The mapping comes from the existing scope → events-canvas filename
- * convention (see `ScopeEventsValidator`); callers resolve it before
- * passing it in.
- */
-export interface ScopeEventsCanvasPair {
-  scope: string;
-  eventsCanvas: ExtendedCanvas;
-  eventsCanvasPath?: string;
-}
-
-export interface ValidateScopeNamespaceNestingInput {
-  scopesCanvas: ExtendedCanvas;
-  scopesCanvasPath?: string;
-  eventsCanvases: readonly ScopeEventsCanvasPair[];
-}
-
-/**
- * For every namespace.paths entry, verify it is covered by its scope's paths.
- * Scopes without `paths` impose no constraint (opt-in per scope) and are
- * skipped. Namespaces without `paths` are also skipped — namespace-level
- * enforcement remains independently opt-in.
- */
-export function validateScopeNamespaceNesting(
-  input: ValidateScopeNamespaceNestingInput,
-): ScopesCanvasViolation[] {
-  const { scopesCanvas, scopesCanvasPath, eventsCanvases } = input;
-  const violations: ScopesCanvasViolation[] = [];
-
-  // Build scope → paths map from the scopes canvas.
-  const scopePaths = new Map<string, string[]>();
-  for (const node of scopesCanvas.nodes || []) {
-    if (!isOtelScopeNode(node)) continue;
-    const scope = node.otel?.scope;
-    const paths = node.paths;
-    if (!scope || !paths || paths.length === 0) continue;
-    scopePaths.set(scope, paths);
-  }
-
-  // For each events canvas, walk its event-namespace nodes and check that
-  // every namespace.paths entry sits inside the owning scope's paths.
-  for (const pair of eventsCanvases) {
-    const ownerPaths = scopePaths.get(pair.scope);
-    if (!ownerPaths) continue; // scope opted out — nothing to check
-
-    for (const node of pair.eventsCanvas.nodes || []) {
-      if ((node as any)?.type !== 'event-namespace') continue;
-      const ns = (node as any).namespace;
-      if (!ns?.name || !Array.isArray(ns.paths) || ns.paths.length === 0) continue;
-
-      for (const declared of ns.paths as string[]) {
-        const covered = ownerPaths.some((sp) => pathCovers(sp, declared));
-        if (covered) continue;
-
-        violations.push({
-          ruleId: 'scopes-namespace-paths-escape',
-          severity: 'error',
-          file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
-          path: `nodes[scope="${pair.scope}"].paths`,
-          message: `Namespace "${ns.name}" path "${declared}" escapes the bounds of scope "${pair.scope}" (paths: ${ownerPaths.map((p) => `"${p}"`).join(', ')})`,
-          impact: 'A namespace claiming code outside its owning scope breaks the scope→namespace partition; events from that file would be attributed to the wrong scope',
-          suggestion: `Either move the namespace path under one of "${pair.scope}"'s paths, or extend the scope to cover the namespace's region. If the code genuinely belongs to a different scope, declare the namespace in that scope's events canvas instead.`,
-        });
-      }
-    }
-  }
-
-  return violations;
-}

package/src/spans/index.ts

@@ -1,24 +0,0 @@
-/**
- * Spans module
- *
- * Provides utilities for working with span conventions from .spans.canvas files.
- * Span colors are used as fill colors for events emitted within that span.
- *
- * Color Contract:
- * - Scope color → Border (from library.yaml owned-scopes)
- * - Span color → Fill (from .spans.canvas)
- */
-
-export {
-  DEFAULT_SPAN_COLOR,
-  extractSpanConvention,
-  extractSpanConventions,
-  buildSpanColorMap,
-  buildSpanColorMapFromCanvases,
-  buildSpanIconMap,
-  matchSpanPattern,
-  getSpanColor,
-  getSpanIcon,
-  resolveEventSpanColor,
-  type NormalizedSpanConvention,
-} from './utils';

package/src/spans/utils.ts

@@ -1,249 +0,0 @@
-/**
- * Span utility functions
- *
- * Helpers for working with span conventions from .spans.canvas files.
- * Span colors are used as fill colors for events emitted within that span.
- */
-
-import type { ExtendedCanvas, ExtendedCanvasNode } from '../types/canvas';
-import { isOtelSpanConventionNode, isStandardCanvasNode } from '../types/canvas';
-
-/** Default color for spans without a defined color */
-export const DEFAULT_SPAN_COLOR = '#9CA3AF'; // gray-400
-
-/**
- * Normalized span convention entry
- */
-export interface NormalizedSpanConvention {
-  /** Unique identifier for this span convention */
-  id: string;
-  /** Pattern to match span names (e.g., "validate.*") */
-  spanPattern: string;
-  /** Color for this span (used as fill for events) */
-  color: string;
-  /** Icon identifier (Lucide icons) */
-  icon?: string;
-  /** Human-readable description */
-  description?: string;
-  /** Status of the span convention */
-  status?: 'draft' | 'approved' | 'implemented';
-}
-
-/**
- * Extract span convention from a canvas node
- */
-export function extractSpanConvention(node: ExtendedCanvasNode): NormalizedSpanConvention | null {
-  // Handle OTEL span convention nodes (top-level otel field)
-  if (isOtelSpanConventionNode(node)) {
-    const spanPattern = node.otel?.spanPattern;
-    if (!spanPattern) return null;
-
-    const color = node.color as string | undefined;
-    if (!color) return null;
-
-    return {
-      id: node.id,
-      spanPattern,
-      color,
-      icon: node.icon,
-      description: node.description,
-      status: node.otel?.status,
-    };
-  }
-
-  // Handle standard nodes with pv.nodeType === 'span-convention'
-  if (!isStandardCanvasNode(node)) return null;
-
-  const pv = node.pv;
-  if (!pv) return null;
-
-  const nodeType = pv.nodeType;
-  if (nodeType !== 'span-convention') return null;
-
-  const otel = pv.otel as { spanPattern?: string; spanKind?: string } | undefined;
-  const spanPattern = otel?.spanPattern;
-  if (!spanPattern) return null;
-
-  // Get color from node (required for span conventions)
-  const color = node.color as string | undefined;
-  if (!color) return null;
-
-  // Extract description from node text if present (only text nodes have text)
-  let description: string | undefined;
-  if ('text' in node && typeof node.text === 'string') {
-    const text = node.text;
-    // Try to extract description from markdown (lines after the header)
-    const lines = text.split('\n');
-    const descLines = lines.filter(line => !line.startsWith('#') && line.trim());
-    if (descLines.length > 0) {
-      description = descLines.join(' ').trim();
-    }
-  }
-
-  // Get icon from pv.icon (Lucide icon identifier)
-  const icon = pv.icon as string | undefined;
-
-  return {
-    id: node.id,
-    spanPattern,
-    color,
-    icon,
-    description,
-    status: pv.status as 'draft' | 'approved' | 'implemented' | undefined,
-  };
-}
-
-/**
- * Extract all span conventions from a spans.canvas file
- */
-export function extractSpanConventions(canvas: ExtendedCanvas): NormalizedSpanConvention[] {
-  const conventions: NormalizedSpanConvention[] = [];
-
-  if (!canvas.nodes) return conventions;
-
-  for (const node of canvas.nodes) {
-    const convention = extractSpanConvention(node);
-    if (convention) {
-      conventions.push(convention);
-    }
-  }
-
-  return conventions;
-}
-
-/**
- * Build a span color map from a spans.canvas
- * Returns a map of spanPattern -> color for fast lookups
- */
-export function buildSpanColorMap(canvas: ExtendedCanvas | null | undefined): Record<string, string> {
-  const colorMap: Record<string, string> = {};
-
-  if (!canvas) return colorMap;
-
-  const conventions = extractSpanConventions(canvas);
-  for (const convention of conventions) {
-    colorMap[convention.spanPattern] = convention.color;
-  }
-
-  return colorMap;
-}
-
-/**
- * Build a span color map from multiple spans.canvas files
- * Later files override earlier ones for duplicate patterns
- */
-export function buildSpanColorMapFromCanvases(
-  canvases: (ExtendedCanvas | null | undefined)[]
-): Record<string, string> {
-  const colorMap: Record<string, string> = {};
-
-  for (const canvas of canvases) {
-    if (!canvas) continue;
-    const conventions = extractSpanConventions(canvas);
-    for (const convention of conventions) {
-      colorMap[convention.spanPattern] = convention.color;
-    }
-  }
-
-  return colorMap;
-}
-
-/**
- * Match a span name to a span pattern
- * Supports exact matches and wildcard patterns (e.g., "validate.*")
- */
-export function matchSpanPattern(spanName: string, pattern: string): boolean {
-  // Exact match
-  if (spanName === pattern) return true;
-
-  // Wildcard pattern (e.g., "validate.*")
-  if (pattern.endsWith('.*')) {
-    const prefix = pattern.slice(0, -2);
-    return spanName.startsWith(prefix + '.') || spanName === prefix;
-  }
-
-  return false;
-}
-
-/**
- * Find the color for a span name by matching against span patterns
- * Returns the first matching pattern's color, or default if none match
- */
-export function getSpanColor(
-  spanName: string,
-  spanColorMap: Record<string, string>
-): string {
-  // First try exact match
-  if (spanColorMap[spanName]) {
-    return spanColorMap[spanName];
-  }
-
-  // Then try pattern matching
-  for (const [pattern, color] of Object.entries(spanColorMap)) {
-    if (matchSpanPattern(spanName, pattern)) {
-      return color;
-    }
-  }
-
-  return DEFAULT_SPAN_COLOR;
-}
-
-/**
- * Resolve span color for an event based on its workflow's spanPattern
- * This is the primary method for determining event fill color
- */
-export function resolveEventSpanColor(
-  workflowSpanPattern: string | undefined,
-  spanColorMap: Record<string, string>
-): string {
-  if (!workflowSpanPattern) return DEFAULT_SPAN_COLOR;
-
-  // Direct lookup (pattern as key)
-  if (spanColorMap[workflowSpanPattern]) {
-    return spanColorMap[workflowSpanPattern];
-  }
-
-  return DEFAULT_SPAN_COLOR;
-}
-
-/**
- * Build a span icon map from a spans.canvas
- * Returns a map of spanPattern -> icon for fast lookups
- */
-export function buildSpanIconMap(canvas: ExtendedCanvas | null | undefined): Record<string, string> {
-  const iconMap: Record<string, string> = {};
-
-  if (!canvas) return iconMap;
-
-  const conventions = extractSpanConventions(canvas);
-  for (const convention of conventions) {
-    if (convention.icon) {
-      iconMap[convention.spanPattern] = convention.icon;
-    }
-  }
-
-  return iconMap;
-}
-
-/**
- * Find the icon for a span name by matching against span patterns
- * Returns the first matching pattern's icon, or undefined if none match
- */
-export function getSpanIcon(
-  spanName: string,
-  spanIconMap: Record<string, string>
-): string | undefined {
-  // First try exact match
-  if (spanIconMap[spanName]) {
-    return spanIconMap[spanName];
-  }
-
-  // Then try pattern matching
-  for (const [pattern, icon] of Object.entries(spanIconMap)) {
-    if (matchSpanPattern(spanName, pattern)) {
-      return icon;
-    }
-  }
-
-  return undefined;
-}