@principal-ai/principal-view-core 0.28.2 → 0.28.3

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/core/src'] }]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([
+            { name: 'events', paths: ['packages/core/src/events'] },
+            { name: 'workflow', paths: ['packages/core/src/workflow'] },
+          ]),
+        },
+      ],
+    });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('flags namespace paths that escape their scope', () => {
+    const violations = validateScopeNamespaceNesting({
+      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/core/src'] }]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([
+            { name: 'rogue', paths: ['packages/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/react/src/hooks');
+  });
+
+  test('namespace path equal to scope path is covered (not an escape)', () => {
+    const violations = validateScopeNamespaceNesting({
+      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/core/src'] }]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([{ name: 'whole', paths: ['packages/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/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/core/src', 'packages/core/generated'] },
+      ]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([
+            { name: 'gen', paths: ['packages/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/types/canvas.ts

@@ -1014,6 +1014,21 @@ export interface OtelScopeNode extends OtelNodeBase {
   type: 'otel-scope';
   /** Short description of this instrumentation scope */
   description?: string;
+  /**
+   * Optional source paths that define this scope's code region.
+   * Each entry may be a folder (covers all descendants) or a specific file.
+   * When present, events under this scope may only originate from files
+   * covered by one of these paths, and every `event-namespace` declared in
+   * this scope's events canvas must have its own `paths` nested inside this
+   * region. Scopes without `paths` remain unenforced — enforcement is opt-in
+   * per scope.
+   *
+   * Semantics are "ownership / partition", distinct from `otel.files` on
+   * `otel-event` nodes (which lists specific emission sites). Across scopes,
+   * paths must be disjoint except for strict parent-child nesting by
+   * dotted-scope name (longest-prefix wins).
+   */
+  paths?: string[];
   /** OTEL metadata - scope name is required */
   otel: OtelMetadata & {
     /** Scope name (required - maps to getTracer('scope-name')) */