@principal-ai/subsystems-core 0.29.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/ScopeEventsValidator.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test, beforeEach } from 'bun:test';
+import { InMemoryFileSystemAdapter } from '@principal-ai/repository-abstraction';
+import { ScopeEventsValidator } from './ScopeEventsValidator';
+import type { ExtendedCanvas, OtelScopeNode, ExtendedCanvasNode } from '../types/canvas';
+
+const BASE = '/project';
+
+function scopeNode(id: string, scope: string): OtelScopeNode {
+  return {
+    id,
+    type: 'otel-scope',
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    otel: { scope },
+  } as OtelScopeNode;
+}
+
+function canvas(nodes: ExtendedCanvasNode[]): ExtendedCanvas {
+  return { nodes, edges: [] } as unknown as ExtendedCanvas;
+}
+
+describe('ScopeEventsValidator', () => {
+  let fsAdapter: InMemoryFileSystemAdapter;
+  let validator: ScopeEventsValidator;
+
+  beforeEach(async () => {
+    fsAdapter = new InMemoryFileSystemAdapter();
+    await fsAdapter.createDir(`${BASE}/.principal-views`, { recursive: true });
+    validator = new ScopeEventsValidator(fsAdapter);
+  });
+
+  async function writeEventsCanvas(filename: string): Promise<void> {
+    await fsAdapter.writeFile(
+      `${BASE}/.principal-views/${filename}`,
+      '{"nodes":[],"edges":[]}',
+    );
+  }
+
+  test('returns empty result when no scopes canvas is provided', async () => {
+    const result = await validator.validate({ basePath: BASE });
+
+    expect(result.valid).toBe(true);
+    expect(result.violations).toHaveLength(0);
+    expect(result.coverage).toEqual({
+      totalScopes: 0,
+      scopesWithEvents: [],
+      scopesMissingEvents: [],
+    });
+  });
+
+  test('passes when every scope has a matching events canvas file', async () => {
+    await writeEventsCanvas('auth.events.canvas');
+    await writeEventsCanvas('billing.events.canvas');
+
+    const result = await validator.validate({
+      scopesCanvas: canvas([
+        scopeNode('s1', 'auth'),
+        scopeNode('s2', 'billing'),
+      ]),
+      basePath: BASE,
+    });
+
+    expect(result.valid).toBe(true);
+    expect(result.violations).toHaveLength(0);
+    expect(result.coverage.totalScopes).toBe(2);
+    expect(result.coverage.scopesWithEvents).toEqual(['auth', 'billing']);
+    expect(result.coverage.scopesMissingEvents).toEqual([]);
+  });
+
+  test('flags a warn violation for each scope missing its events canvas file', async () => {
+    const result = await validator.validate({
+      scopesCanvas: canvas([
+        scopeNode('s1', 'nope-one'),
+        scopeNode('s2', 'nope-two'),
+      ]),
+      basePath: BASE,
+    });
+
+    // valid remains true because violations are warn-level, not errors
+    expect(result.valid).toBe(true);
+    expect(result.violations).toHaveLength(2);
+    expect(result.violations.every((v) => v.severity === 'warn')).toBe(true);
+    expect(result.violations.every((v) => v.ruleId === 'scope-events-canvas-required')).toBe(true);
+    expect(result.coverage.scopesMissingEvents).toEqual(['nope-one', 'nope-two']);
+    expect(result.coverage.scopesWithEvents).toEqual([]);
+  });
+
+  test('reports mixed coverage when some scopes have files and others do not', async () => {
+    await writeEventsCanvas('present.events.canvas');
+
+    const result = await validator.validate({
+      scopesCanvas: canvas([
+        scopeNode('s1', 'present'),
+        scopeNode('s2', 'absent'),
+      ]),
+      basePath: BASE,
+    });
+
+    expect(result.coverage.scopesWithEvents).toEqual(['present']);
+    expect(result.coverage.scopesMissingEvents).toEqual(['absent']);
+    expect(result.violations).toHaveLength(1);
+    expect(result.violations[0].scope).toBe('absent');
+    expect(result.violations[0].expectedPath).toBe('.principal-views/absent.events.canvas');
+  });
+
+  test('converts dots in scope names to dashes for the expected filename', async () => {
+    await writeEventsCanvas('backlog-md-cli.events.canvas');
+
+    const result = await validator.validate({
+      scopesCanvas: canvas([scopeNode('s1', 'backlog.md.cli')]),
+      basePath: BASE,
+    });
+
+    expect(result.violations).toHaveLength(0);
+    expect(result.coverage.scopesWithEvents).toEqual(['backlog.md.cli']);
+  });
+
+  test('ignores non-otel-scope nodes', async () => {
+    await writeEventsCanvas('present.events.canvas');
+    const mixedNodes = [
+      scopeNode('s1', 'present'),
+      {
+        id: 'e1',
+        type: 'otel-event',
+        x: 0,
+        y: 0,
+        width: 100,
+        height: 100,
+        eventRef: 'some.event',
+      },
+      {
+        id: 't1',
+        type: 'text',
+        x: 0,
+        y: 0,
+        width: 100,
+        height: 100,
+        text: 'not a scope',
+      },
+    ] as unknown as ExtendedCanvasNode[];
+
+    const result = await validator.validate({
+      scopesCanvas: canvas(mixedNodes),
+      basePath: BASE,
+    });
+
+    expect(result.coverage.totalScopes).toBe(1);
+    expect(result.coverage.scopesWithEvents).toEqual(['present']);
+  });
+
+  test('skips otel-scope nodes missing otel.scope without throwing', async () => {
+    const nodeWithoutScope = {
+      id: 's-bad',
+      type: 'otel-scope',
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      otel: {},
+    } as unknown as OtelScopeNode;
+
+    const result = await validator.validate({
+      scopesCanvas: canvas([nodeWithoutScope]),
+      basePath: BASE,
+    });
+
+    expect(result.violations).toHaveLength(0);
+    expect(result.coverage.scopesWithEvents).toEqual([]);
+    expect(result.coverage.scopesMissingEvents).toEqual([]);
+  });
+});