@principal-ai/subsystems-core 0.29.0

package/src/scopes/validateScopeNamespaceNesting.test.ts

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

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

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

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