@principal-ai/principal-view-core 0.27.2 → 0.28.0

package/src/events/OtelEventPathsValidator.test.ts

@@ -0,0 +1,243 @@
+import { describe, expect, test } from 'bun:test';
+import { OtelEventPathsValidator } from './OtelEventPathsValidator';
+import type { ExtendedCanvas } from '../types/canvas';
+
+function namespaceNode(name: string, opts: { paths?: string[] } = {}): any {
+  return {
+    id: `ns-${name}`,
+    type: 'event-namespace',
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    namespace: {
+      name,
+      description: `${name} description`,
+      paths: opts.paths,
+      events: [],
+    },
+  };
+}
+
+function eventNode(
+  id: string,
+  eventName: string,
+  scope: string,
+  files: string[] | undefined,
+): any {
+  return {
+    id,
+    type: 'otel-event',
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    label: eventName,
+    event: { name: eventName, attributes: {} },
+    otel: { scope, files },
+  };
+}
+
+function canvas(nodes: any[]): ExtendedCanvas {
+  return { nodes, edges: [] } as unknown as ExtendedCanvas;
+}
+
+function validate(input: {
+  events: Array<{ scope: string; nodes: any[] }>;
+  otel: any[][];
+}) {
+  const validator = new OtelEventPathsValidator();
+  return validator.validate({
+    eventsCanvases: input.events.map((e, i) => ({
+      canvas: canvas(e.nodes),
+      canvasPath: `scope-${i}.events.canvas`,
+      scope: e.scope,
+    })),
+    otelCanvases: input.otel.map((nodes, i) => ({
+      canvas: canvas(nodes),
+      canvasPath: `otel-${i}.otel.canvas`,
+    })),
+  });
+}
+
+function rules(result: { violations: Array<{ ruleId: string }> }, ruleId: string) {
+  return result.violations.filter((v) => v.ruleId === ruleId);
+}
+
+describe('OtelEventPathsValidator', () => {
+  test('empty input produces no violations', () => {
+    const result = validate({ events: [], otel: [] });
+    expect(result.violations).toHaveLength(0);
+    expect(result.valid).toBe(true);
+  });
+
+  test('skips events whose namespace has no paths declared (opt-in)', () => {
+    const result = validate({
+      events: [{ scope: 's', nodes: [namespaceNode('events')] }], // no paths
+      otel: [[eventNode('e1', 'events.happened', 's', ['src/somewhere/else.ts'])]],
+    });
+    expect(result.violations).toHaveLength(0);
+    expect(result.metrics.eventsSkippedNoPaths).toBe(1);
+    expect(result.metrics.eventsChecked).toBe(0);
+  });
+
+  test('file covered by the event’s namespace: no violation', () => {
+    const result = validate({
+      events: [
+        {
+          scope: 's',
+          nodes: [namespaceNode('events', { paths: ['src/events'] })],
+        },
+      ],
+      otel: [[eventNode('e1', 'events.happened', 's', ['src/events/foo.ts'])]],
+    });
+    expect(result.violations).toHaveLength(0);
+    expect(result.metrics.eventsChecked).toBe(1);
+    expect(result.metrics.filesChecked).toBe(1);
+  });
+
+  test('file covered by a different namespace: wrong-namespace error', () => {
+    const result = validate({
+      events: [
+        {
+          scope: 's',
+          nodes: [
+            namespaceNode('validation', { paths: ['src/validation'] }),
+            namespaceNode('middleware', { paths: ['src/middleware'] }),
+          ],
+        },
+      ],
+      otel: [
+        [eventNode('e1', 'validation.started', 's', ['src/middleware/auth.ts'])],
+      ],
+    });
+
+    const wrong = rules(result, 'events-otel-files-wrong-namespace');
+    expect(wrong).toHaveLength(1);
+    expect(wrong[0].severity).toBe('error');
+    expect(wrong[0].message).toContain('middleware');
+    expect(wrong[0].message).toContain('validation.started');
+    expect(result.valid).toBe(false);
+  });
+
+  test('file in no namespace: orphan warning', () => {
+    const result = validate({
+      events: [
+        {
+          scope: 's',
+          nodes: [namespaceNode('events', { paths: ['src/events'] })],
+        },
+      ],
+      otel: [
+        [eventNode('e1', 'events.happened', 's', ['src/nowhere/foo.ts'])],
+      ],
+    });
+
+    const orphan = rules(result, 'events-otel-files-orphan');
+    expect(orphan).toHaveLength(1);
+    expect(orphan[0].severity).toBe('warn');
+    expect(orphan[0].message).toContain('src/nowhere/foo.ts');
+    expect(result.valid).toBe(true); // only warnings
+  });
+
+  test('parent-child partition: event on parent using child-owned file is flagged', () => {
+    const result = validate({
+      events: [
+        {
+          scope: 's',
+          nodes: [
+            namespaceNode('workflow', { paths: ['src/workflow'] }),
+            namespaceNode('workflow.scenarios', { paths: ['src/workflow/scenarios'] }),
+          ],
+        },
+      ],
+      otel: [
+        // "workflow.started" declared with a file under workflow.scenarios/
+        [eventNode('e1', 'workflow.started', 's', ['src/workflow/scenarios/matcher.ts'])],
+      ],
+    });
+
+    const wrong = rules(result, 'events-otel-files-wrong-namespace');
+    expect(wrong).toHaveLength(1);
+    expect(wrong[0].message).toContain('workflow.scenarios');
+  });
+
+  test('parent-child partition: event on child using child-owned file is OK', () => {
+    const result = validate({
+      events: [
+        {
+          scope: 's',
+          nodes: [
+            namespaceNode('workflow', { paths: ['src/workflow'] }),
+            namespaceNode('workflow.scenarios', { paths: ['src/workflow/scenarios'] }),
+          ],
+        },
+      ],
+      otel: [
+        [eventNode('e1', 'workflow.scenarios.matched', 's', ['src/workflow/scenarios/m.ts'])],
+      ],
+    });
+    expect(result.violations).toHaveLength(0);
+  });
+
+  test('scope isolation: namespace paths from scope A do not claim files for scope B events', () => {
+    const result = validate({
+      events: [
+        {
+          scope: 'A',
+          nodes: [namespaceNode('events', { paths: ['src/events'] })],
+        },
+        // Scope B has no paths declared at all
+        {
+          scope: 'B',
+          nodes: [namespaceNode('events')],
+        },
+      ],
+      otel: [
+        // Event in scope B with a file that WOULD be covered in scope A.
+        // Since scope B namespace has no paths → skipped (opt-in).
+        [eventNode('e1', 'events.happened', 'B', ['src/events/foo.ts'])],
+      ],
+    });
+
+    expect(result.violations).toHaveLength(0);
+    expect(result.metrics.eventsSkippedNoPaths).toBe(1);
+  });
+
+  test('events with no scope or no files are skipped', () => {
+    const result = validate({
+      events: [
+        { scope: 's', nodes: [namespaceNode('events', { paths: ['src/events'] })] },
+      ],
+      otel: [
+        [
+          eventNode('no-scope', 'events.happened', '', ['src/nowhere.ts']),
+          eventNode('no-files', 'events.happened', 's', undefined),
+        ],
+      ],
+    });
+    expect(result.violations).toHaveLength(0);
+    expect(result.metrics.eventsChecked).toBe(0);
+    // The "no-files" event is counted in eventsSkippedNoFiles;
+    // the "no-scope" event is skipped silently before namespace resolution.
+    expect(result.metrics.eventsSkippedNoFiles).toBe(1);
+  });
+
+  test('multiple otel canvases are all checked', () => {
+    const result = validate({
+      events: [
+        {
+          scope: 's',
+          nodes: [namespaceNode('events', { paths: ['src/events'] })],
+        },
+      ],
+      otel: [
+        [eventNode('e1', 'events.one', 's', ['src/events/ok.ts'])],
+        [eventNode('e2', 'events.two', 's', ['src/other/bad.ts'])],
+      ],
+    });
+
+    expect(rules(result, 'events-otel-files-orphan')).toHaveLength(1);
+    expect(result.metrics.filesChecked).toBe(2);
+  });
+});

package/src/events/OtelEventPathsValidator.ts

@@ -0,0 +1,191 @@
+/**
+ * OTEL Event Paths Validator (Phase 2)
+ *
+ * Cross-canvas static check. For every `otel-event` node in an OTEL canvas,
+ * cross-reference each entry in `otel.files` against the `paths` declared on
+ * the event's namespace in the corresponding events canvas.
+ *
+ * Enforcement is opt-in per namespace: a namespace without `paths` (or a
+ * namespace not declared at all) produces no violations for its events.
+ *
+ * Pure/browser-safe — no filesystem access.
+ */
+
+import type { ExtendedCanvas, OtelEventNode } from '../types/canvas';
+import { isOtelEventNode } from '../types/canvas';
+import { NamespacePathIndex, type NamespacePathEntry } from './NamespacePathIndex';
+
+/**
+ * One events canvas, pre-paired with the scope it owns. Scope pairing is
+ * typically derived via the existing scope → filename convention
+ * (e.g., scope `principal-view.cli` owns `principal-view-cli.events.canvas`).
+ */
+export interface EventsCanvasInput {
+  canvas: ExtendedCanvas;
+  canvasPath: string;
+  scope: string;
+}
+
+/**
+ * One OTEL canvas whose `otel-event` nodes we want to cross-check.
+ */
+export interface OtelCanvasInput {
+  canvas: ExtendedCanvas;
+  canvasPath: string;
+}
+
+export interface OtelEventPathsValidationContext {
+  eventsCanvases: EventsCanvasInput[];
+  otelCanvases: OtelCanvasInput[];
+}
+
+export type OtelEventPathsRuleId =
+  | 'events-otel-files-wrong-namespace'
+  | 'events-otel-files-orphan';
+
+export interface OtelEventPathsViolation {
+  ruleId: OtelEventPathsRuleId;
+  severity: 'error' | 'warn';
+  file: string;
+  path?: string;
+  message: string;
+  impact: string;
+  suggestion: string;
+}
+
+export interface OtelEventPathsValidationResult {
+  valid: boolean;
+  violations: OtelEventPathsViolation[];
+  metrics: {
+    /** Events whose files were cross-checked against namespace paths. */
+    eventsChecked: number;
+    /** Total files examined across all checked events. */
+    filesChecked: number;
+    /**
+     * Events skipped because the event's namespace has no `paths` declared
+     * (or is not declared at all) — enforcement is opt-in per namespace.
+     */
+    eventsSkippedNoPaths: number;
+    /**
+     * Events skipped because the `otel-event` node declares no `otel.files`.
+     * These events have no claimed implementation location to cross-check.
+     */
+    eventsSkippedNoFiles: number;
+  };
+}
+
+export class OtelEventPathsValidator {
+  /**
+   * Build a path index from the events canvases, keyed by scope.
+   * Only namespaces that declare `paths` contribute entries.
+   */
+  private buildIndex(eventsCanvases: EventsCanvasInput[]): NamespacePathIndex {
+    const index = new NamespacePathIndex();
+    for (const ec of eventsCanvases) {
+      for (const node of ec.canvas.nodes || []) {
+        if ((node as any)?.type !== 'event-namespace') continue;
+        const ns = (node as any).namespace;
+        if (!ns || typeof ns.name !== 'string') continue;
+        if (!Array.isArray(ns.paths) || ns.paths.length === 0) continue;
+
+        const entry: NamespacePathEntry = {
+          scope: ec.scope,
+          namespace: ns.name,
+          paths: ns.paths,
+          sourceCanvasPath: ec.canvasPath,
+        };
+        index.add(entry);
+      }
+    }
+    return index;
+  }
+
+  /** Extract the namespace from an event name (all segments except the last). */
+  private extractNamespace(eventName: string): string | null {
+    const segments = eventName.split('.');
+    if (segments.length < 2) return null;
+    return segments.slice(0, -1).join('.');
+  }
+
+  validate(context: OtelEventPathsValidationContext): OtelEventPathsValidationResult {
+    const violations: OtelEventPathsViolation[] = [];
+    const metrics = {
+      eventsChecked: 0,
+      filesChecked: 0,
+      eventsSkippedNoPaths: 0,
+      eventsSkippedNoFiles: 0,
+    };
+
+    const index = this.buildIndex(context.eventsCanvases);
+
+    for (const oc of context.otelCanvases) {
+      for (const node of oc.canvas.nodes || []) {
+        if (!isOtelEventNode(node as any)) continue;
+        const eventNode = node as OtelEventNode;
+        const eventName = eventNode.event?.name;
+        const scope = eventNode.otel?.scope;
+        const files = eventNode.otel?.files;
+
+        if (!eventName || !scope) continue; // malformed — other validators catch this
+
+        const namespace = this.extractNamespace(eventName);
+        if (!namespace) continue; // invalid event name — caught by other validators
+
+        if (!files || files.length === 0) {
+          metrics.eventsSkippedNoFiles++;
+          continue;
+        }
+
+        // Enforcement is opt-in: if the event's namespace has no declared
+        // paths (or isn't declared at all), we don't check its files.
+        const eventEntry = index.getEntry(scope, namespace);
+        if (!eventEntry) {
+          metrics.eventsSkippedNoPaths++;
+          continue;
+        }
+
+        metrics.eventsChecked++;
+
+        for (const file of files) {
+          metrics.filesChecked++;
+
+          const match = index.resolve(scope, file);
+          if (match === null) {
+            violations.push({
+              ruleId: 'events-otel-files-orphan',
+              severity: 'warn',
+              file: oc.canvasPath,
+              path: `nodes[id="${eventNode.id}"].otel.files["${file}"]`,
+              message: `Event "${eventName}" declares file "${file}" which is not covered by any namespace's paths in scope "${scope}"`,
+              impact: 'The file emits an event but has no declared component home, so its location cannot be validated against namespace conventions.',
+              suggestion: `Either add "${file}" (or an ancestor folder) to the "paths" of the "${namespace}" namespace in the events canvas, or move the implementation into one of the namespace's declared paths: ${eventEntry.paths.map((p) => `"${p}"`).join(', ')}.`,
+            });
+            continue;
+          }
+
+          if (match.entry.namespace === namespace) {
+            // File belongs to the event's namespace (longest-prefix match).
+            continue;
+          }
+
+          violations.push({
+            ruleId: 'events-otel-files-wrong-namespace',
+            severity: 'error',
+            file: oc.canvasPath,
+            path: `nodes[id="${eventNode.id}"].otel.files["${file}"]`,
+            message: `Event "${eventName}" declares file "${file}", but namespace "${match.entry.namespace}" (path "${match.matchedPath}") owns that location — not "${namespace}"`,
+            impact: 'Event identity disagrees with code location. Consumers discovering the event by name will land in a folder that belongs to a different namespace.',
+            suggestion: `Either rename the event to start with "${match.entry.namespace}." (if the code placement is correct), or move the implementation into one of the "${namespace}" namespace's declared paths (${eventEntry.paths.map((p) => `"${p}"`).join(', ')}).`,
+          });
+        }
+      }
+    }
+
+    const errors = violations.filter((v) => v.severity === 'error');
+    return {
+      valid: errors.length === 0,
+      violations,
+      metrics,
+    };
+  }
+}

package/src/events/index.ts

@@ -12,3 +12,16 @@ export type {
   ScopeEventsViolation,
   ScopeEventsValidationResult,
 } from './ScopeEventsValidator';
+
+export { NamespacePathIndex } from './NamespacePathIndex';
+export type { NamespacePathEntry, NamespacePathMatch } from './NamespacePathIndex';
+
+export { OtelEventPathsValidator } from './OtelEventPathsValidator';
+export type {
+  OtelEventPathsValidationContext,
+  OtelEventPathsValidationResult,
+  OtelEventPathsViolation,
+  OtelEventPathsRuleId,
+  EventsCanvasInput,
+  OtelCanvasInput,
+} from './OtelEventPathsValidator';

package/src/events/path-helpers.ts

@@ -0,0 +1,53 @@
+/**
+ * Path helpers shared across events-canvas validators.
+ *
+ * Paths declared in canvases (namespace `paths`, `otel.files`, etc.) are
+ * always repo-relative. These helpers give a consistent notion of
+ * canonicalization and prefix-based containment so that separate validators
+ * don't drift.
+ */
+
+/**
+ * Canonicalize a declared path for comparison.
+ * Strips leading `./`, trailing slashes, and collapses duplicate slashes.
+ */
+export function normalizePath(p: string): string {
+  return p
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '')
+    .replace(/\/+/g, '/');
+}
+
+/**
+ * True when `child` is strictly nested under `parent` (not equal).
+ * Both inputs should already be normalized.
+ */
+export function isPathDescendant(child: string, parent: string): boolean {
+  return child.startsWith(parent + '/');
+}
+
+/**
+ * True when `filepath` is covered by `declaredPath` — either equal to it
+ * (file match) or nested under it (folder match). Inputs are normalized
+ * internally so callers can pass raw canvas values.
+ */
+export function pathCovers(declaredPath: string, filepath: string): boolean {
+  const d = normalizePath(declaredPath);
+  const f = normalizePath(filepath);
+  return d === f || isPathDescendant(f, d);
+}
+
+/**
+ * Classify the relationship between two declared paths.
+ * - 'none':      disjoint — no overlap
+ * - 'partition': one is strictly a parent of the other — valid nested-namespace case
+ *                (longest-prefix wins at runtime, parent/child partition the tree)
+ * - 'conflict':  identical, or overlap that isn't a clean parent-child partition
+ */
+export function pathsOverlap(a: string, b: string): 'none' | 'partition' | 'conflict' {
+  const na = normalizePath(a);
+  const nb = normalizePath(b);
+  if (na === nb) return 'conflict';
+  if (isPathDescendant(na, nb) || isPathDescendant(nb, na)) return 'partition';
+  return 'none';
+}