@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/events/OtelEventPathsValidator.test.ts

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

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

@@ -1,173 +0,0 @@
-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([]);
-  });
-});