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

package/src/scopes/ScopesCanvasValidator.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { ScopesCanvasValidator } from './ScopesCanvasValidator';
+import type { ExtendedCanvas } from '../types/canvas';
+
+function makeScopeNode(opts: {
+  id: string;
+  scope: string;
+  description?: string;
+  paths?: string[];
+}): any {
+  return {
+    id: opts.id,
+    type: 'otel-scope',
+    description: opts.description ?? `${opts.scope} scope`,
+    ...(opts.paths !== undefined ? { paths: opts.paths } : {}),
+    otel: { scope: opts.scope },
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 50,
+  };
+}
+
+function makeCanvas(nodes: any[]): ExtendedCanvas {
+  return { nodes, edges: [] } as ExtendedCanvas;
+}
+
+function withTempRepo(layout: string[], fn: (root: string) => Promise<void>): Promise<void> {
+  const root = mkdtempSync(join(tmpdir(), 'scope-paths-'));
+  try {
+    for (const rel of layout) {
+      const full = join(root, rel);
+      mkdirSync(full, { recursive: true });
+      writeFileSync(join(full, '.keep'), '');
+    }
+    return fn(root).finally(() => rmSync(root, { recursive: true, force: true }));
+  } catch (e) {
+    rmSync(root, { recursive: true, force: true });
+    throw e;
+  }
+}
+
+describe('ScopesCanvasValidator scope paths', () => {
+  test('no paths declared → no path violations', async () => {
+    const canvas = makeCanvas([makeScopeNode({ id: 's1', scope: 'a.b' })]);
+    const v = new ScopesCanvasValidator();
+    const r = await v.validate({
+      scopesCanvas: canvas,
+      ownedScopes: ['a.b'],
+      basePath: '/tmp',
+    });
+    expect(r.violations.find(x => x.ruleId.startsWith('scopes-paths'))).toBeUndefined();
+  });
+
+  test('scopes-paths-multiple warns when more than one path', async () => {
+    await withTempRepo(['packages/a/src', 'packages/a/generated'], async (root) => {
+      const canvas = makeCanvas([
+        makeScopeNode({
+          id: 's1',
+          scope: 'a',
+          paths: ['packages/a/src', 'packages/a/generated'],
+        }),
+      ]);
+      const v = new ScopesCanvasValidator();
+      const r = await v.validate({ scopesCanvas: canvas, ownedScopes: ['a'], basePath: root });
+      const w = r.violations.find(x => x.ruleId === 'scopes-paths-multiple');
+      expect(w).toBeDefined();
+      expect(w?.severity).toBe('warn');
+    });
+  });
+
+  test('scopes-paths-missing warns when path does not exist', async () => {
+    await withTempRepo(['packages/a/src'], async (root) => {
+      const canvas = makeCanvas([
+        makeScopeNode({ id: 's1', scope: 'a', paths: ['packages/a/missing'] }),
+      ]);
+      const v = new ScopesCanvasValidator();
+      const r = await v.validate({ scopesCanvas: canvas, ownedScopes: ['a'], basePath: root });
+      const w = r.violations.find(x => x.ruleId === 'scopes-paths-missing');
+      expect(w).toBeDefined();
+      expect(w?.severity).toBe('warn');
+    });
+  });
+
+  test('scopes-paths-overlap errors on identical paths across scopes', async () => {
+    await withTempRepo(['packages/shared/src'], async (root) => {
+      const canvas = makeCanvas([
+        makeScopeNode({ id: 's1', scope: 'a', paths: ['packages/shared/src'] }),
+        makeScopeNode({ id: 's2', scope: 'b', paths: ['packages/shared/src'] }),
+      ]);
+      const v = new ScopesCanvasValidator();
+      const r = await v.validate({
+        scopesCanvas: canvas,
+        ownedScopes: ['a', 'b'],
+        basePath: root,
+      });
+      const e = r.violations.find(x => x.ruleId === 'scopes-paths-overlap');
+      expect(e).toBeDefined();
+      expect(e?.severity).toBe('error');
+      expect(r.valid).toBe(false);
+    });
+  });
+
+  test('parent-child path nesting is allowed (no overlap error)', async () => {
+    await withTempRepo(['packages/core/src/validation'], async (root) => {
+      const canvas = makeCanvas([
+        makeScopeNode({ id: 's1', scope: 'principal-ai.core', paths: ['packages/core/src'] }),
+        makeScopeNode({
+          id: 's2',
+          scope: 'principal-ai.core.validation',
+          paths: ['packages/core/src/validation'],
+        }),
+      ]);
+      const v = new ScopesCanvasValidator();
+      const r = await v.validate({
+        scopesCanvas: canvas,
+        ownedScopes: ['principal-ai.core', 'principal-ai.core.validation'],
+        basePath: root,
+      });
+      expect(r.violations.find(x => x.ruleId === 'scopes-paths-overlap')).toBeUndefined();
+    });
+  });
+});

package/src/scopes/ScopesCanvasValidator.ts

@@ -5,8 +5,11 @@
  * all instrumentation scopes declared in library.yaml.
  */
 
+import { existsSync } from 'fs';
+import { resolve } from 'path';
 import type { ExtendedCanvas, ExtendedCanvasNode, OtelScopeNode, isOtelScopeNode } from '../types/canvas';
 import { isOtelScopeNode as checkOtelScopeNode } from '../types/canvas';
+import { pathsOverlap } from '../events/path-helpers';
 
 /**
  * Scopes canvas validation context
@@ -194,6 +197,71 @@ export class ScopesCanvasValidator {
       }
     }
 
+    // Validate scope paths (optional field — enforcement is opt-in per scope).
+    // Collects declared paths across scopes to check for cross-scope overlap.
+    const declaredPaths: Array<{ scope: string; nodeId: string; path: string }> = [];
+    for (const { scope, nodeId, node } of canvasScopes) {
+      const otelScopeNode = node as unknown as OtelScopeNode;
+      const paths = otelScopeNode.paths;
+      if (!paths || paths.length === 0) continue;
+
+      // Warn when a scope declares more than one path — prompt author to
+      // confirm the multi-location is intentional (monorepo bundling,
+      // generated code, platform splits, migration) rather than accidental.
+      if (paths.length > 1) {
+        violations.push({
+          ruleId: 'scopes-paths-multiple',
+          severity: 'warn',
+          file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+          path: `nodes[${nodeId}].paths`,
+          message: `Scope "${scope}" declares ${paths.length} paths`,
+          impact: 'Multiple paths can indicate legitimate cases (monorepo bundling, generated code, platform splits, migration) but often signal that the scope should be split',
+          suggestion: 'Confirm the multi-location is intentional. Otherwise consider splitting the scope or grouping the code under a single parent folder.',
+        });
+      }
+
+      for (const p of paths) {
+        declaredPaths.push({ scope, nodeId, path: p });
+
+        // Warn when a declared path does not exist relative to the repo root.
+        const resolved = resolve(basePath, p);
+        if (!existsSync(resolved)) {
+          violations.push({
+            ruleId: 'scopes-paths-missing',
+            severity: 'warn',
+            file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+            path: `nodes[${nodeId}].paths`,
+            message: `Path "${p}" declared by scope "${scope}" does not exist`,
+            impact: 'Events emitted under this scope cannot be validated against a real code location',
+            suggestion: 'Verify the path exists relative to the repository root, or remove it from the scope declaration.',
+          });
+        }
+      }
+    }
+
+    // Cross-scope overlap check. Parent-child path nesting is a valid partition
+    // (longest-prefix wins at runtime); any other overlap makes scope ownership
+    // of a file ambiguous.
+    for (let i = 0; i < declaredPaths.length; i++) {
+      for (let j = i + 1; j < declaredPaths.length; j++) {
+        const a = declaredPaths[i];
+        const b = declaredPaths[j];
+        if (a.scope === b.scope) continue;
+
+        const relationship = pathsOverlap(a.path, b.path);
+        if (relationship === 'conflict') {
+          violations.push({
+            ruleId: 'scopes-paths-overlap',
+            severity: 'error',
+            file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+            message: `Paths overlap between scopes "${a.scope}" ("${a.path}") and "${b.scope}" ("${b.path}")`,
+            impact: 'A file covered by two scopes makes scope ownership ambiguous',
+            suggestion: 'Separate the paths so they are disjoint, or restructure as parent/child scopes by dotted name (e.g., "principal-ai.core" covering "packages/core/src" and "principal-ai.core.validation" covering "packages/core/src/validation").',
+          });
+        }
+      }
+    }
+
     const errors = violations.filter(v => v.severity === 'error');
 
     return {

package/src/scopes/index.ts

@@ -13,6 +13,18 @@ export {
   type ScopesCanvasViolation,
 } from './ScopesCanvasValidator';
 
+export {
+  ScopePathIndex,
+  type ScopePathEntry,
+  type ScopePathMatch,
+} from './ScopePathIndex';
+
+export {
+  validateScopeNamespaceNesting,
+  type ScopeEventsCanvasPair,
+  type ValidateScopeNamespaceNestingInput,
+} from './validateScopeNamespaceNesting';
+
 export {
   DEFAULT_SCOPE_COLOR,
   DRAFT_NODE_COLOR,

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/auxiliary.ts

@@ -0,0 +1,63 @@
+/**
+ * Auxiliary Manifest Types
+ *
+ * The auxiliary manifest catalogs project regions that are *not* OTEL scopes —
+ * folders like `docs/` or `.github/` that support the project but don't emit
+ * telemetry. Scope paths and area paths together form a partition of the
+ * accounted-for filesystem.
+ *
+ * The manifest is open-ended: `areas` is the first section, but the top-level
+ * shape leaves room for future sibling sections (e.g. external integrations)
+ * without breaking the format.
+ */
+
+/**
+ * One project area — a folder (or file) that supports the project outside the
+ * OTEL telemetry surface.
+ */
+export interface ProjectArea {
+  /**
+   * Display name. Must be unique across all areas in the manifest — used as
+   * the area's identifier in diagnostics.
+   */
+  name: string;
+
+  /**
+   * One or more repo-relative paths owned by this area. Each entry may be a
+   * folder (covers all descendants) or a specific file. Paths must not
+   * overlap other areas, and must not overlap any scope path declared in a
+   * `.scopes.canvas`.
+   */
+  paths: string[];
+
+  /**
+   * Free-text purpose. The "light documentation" — a sentence about why this
+   * folder exists.
+   */
+  description: string;
+}
+
+/**
+ * The full manifest document. Persisted at
+ * `.principal-views/auxiliary.manifest.json`.
+ */
+export interface AuxiliaryManifest {
+  /**
+   * Optional pointer to the JSON Schema that describes this file. Lets editors
+   * give autocomplete and validation when the field is set.
+   */
+  $schema?: string;
+
+  /** Project areas declared in this manifest. */
+  areas: ProjectArea[];
+}
+
+/**
+ * Type guard: true when the value plausibly conforms to `AuxiliaryManifest`.
+ * Shallow check — full validation lives in `AuxiliaryManifestValidator`.
+ */
+export function isAuxiliaryManifest(value: unknown): value is AuxiliaryManifest {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as { areas?: unknown };
+  return Array.isArray(v.areas);
+}

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')) */

package/src/types/index.ts

@@ -456,3 +456,4 @@ export * from './resource-match';
 export * from './canvas-scope';
 export * from './audit';
 export * from './dashboard';
+export * from './auxiliary';