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

package/dist/events/path-helpers.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathsOverlap = exports.pathCovers = exports.isPathDescendant = exports.normalizePath = void 0;
+/**
+ * Canonicalize a declared path for comparison.
+ * Strips leading `./`, trailing slashes, and collapses duplicate slashes.
+ */
+function normalizePath(p) {
+    return p
+        .replace(/^\.\//, '')
+        .replace(/\/+$/, '')
+        .replace(/\/+/g, '/');
+}
+exports.normalizePath = normalizePath;
+/**
+ * True when `child` is strictly nested under `parent` (not equal).
+ * Both inputs should already be normalized.
+ */
+function isPathDescendant(child, parent) {
+    return child.startsWith(parent + '/');
+}
+exports.isPathDescendant = isPathDescendant;
+/**
+ * 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.
+ */
+function pathCovers(declaredPath, filepath) {
+    const d = normalizePath(declaredPath);
+    const f = normalizePath(filepath);
+    return d === f || isPathDescendant(f, d);
+}
+exports.pathCovers = pathCovers;
+/**
+ * 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
+ */
+function pathsOverlap(a, b) {
+    const na = normalizePath(a);
+    const nb = normalizePath(b);
+    if (na === nb)
+        return 'conflict';
+    if (isPathDescendant(na, nb) || isPathDescendant(nb, na))
+        return 'partition';
+    return 'none';
+}
+exports.pathsOverlap = pathsOverlap;
+//# sourceMappingURL=path-helpers.js.map

package/dist/events/path-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-helpers.js","sourceRoot":"","sources":["../../src/events/path-helpers.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH;;;GAGG;AACH,SAAgB,aAAa,CAAC,CAAS;IACrC,OAAO,CAAC;SACL,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC1B,CAAC;AALD,sCAKC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,KAAa,EAAE,MAAc;IAC5D,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;AACxC,CAAC;AAFD,4CAEC;AAED;;;;GAIG;AACH,SAAgB,UAAU,CAAC,YAAoB,EAAE,QAAgB;IAC/D,MAAM,CAAC,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,CAAC,KAAK,CAAC,IAAI,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3C,CAAC;AAJD,gCAIC;AAED;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,UAAU,CAAC;IACjC,IAAI,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC;QAAE,OAAO,WAAW,CAAC;IAC7E,OAAO,MAAM,CAAC;AAChB,CAAC;AAND,oCAMC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/principal-view-core",
-  "version": "0.27.2",
+  "version": "0.28.0",
   "description": "Core logic and types for graph-based principal view framework",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/events/EventsCanvasValidator.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { EventsCanvasValidator } from './EventsCanvasValidator';
+import type { ExtendedCanvas } from '../types/canvas';
+
+let testRoot: string;
+
+beforeAll(() => {
+  testRoot = mkdtempSync(join(tmpdir(), 'events-canvas-validator-'));
+  mkdirSync(join(testRoot, 'src/events'), { recursive: true });
+  mkdirSync(join(testRoot, 'src/workflow/scenarios'), { recursive: true });
+  mkdirSync(join(testRoot, 'src/trace'), { recursive: true });
+  mkdirSync(join(testRoot, 'src/generated/events'), { recursive: true });
+});
+
+afterAll(() => {
+  rmSync(testRoot, { recursive: true, force: true });
+});
+
+function namespaceNode(
+  id: string,
+  name: string,
+  opts: { paths?: string[]; eventNames?: string[] } = {},
+): any {
+  const eventNames = opts.eventNames ?? [`${name}.happened`];
+  return {
+    id,
+    type: 'event-namespace',
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    namespace: {
+      name,
+      description: `${name} description`,
+      paths: opts.paths,
+      events: eventNames.map((n) => ({
+        name: n,
+        severity: 'INFO',
+        description: `desc for ${n}`,
+      })),
+    },
+  };
+}
+
+function canvas(nodes: any[]): ExtendedCanvas {
+  return { nodes, edges: [] } as unknown as ExtendedCanvas;
+}
+
+async function runValidator(nodes: any[]) {
+  const validator = new EventsCanvasValidator();
+  return validator.validate({
+    eventsCanvas: canvas(nodes),
+    eventsCanvasPath: 'test.events.canvas',
+    basePath: testRoot,
+  });
+}
+
+function rules(result: { violations: Array<{ ruleId: string }> }, ruleId: string) {
+  return result.violations.filter((v) => v.ruleId === ruleId);
+}
+
+describe('EventsCanvasValidator — paths field', () => {
+  test('namespace without paths: no path-related violations (opt-in, backward compatible)', async () => {
+    const result = await runValidator([namespaceNode('events', 'events')]);
+
+    expect(rules(result, 'events-namespace-multiple-paths')).toHaveLength(0);
+    expect(rules(result, 'events-namespace-paths-missing')).toHaveLength(0);
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+
+  test('namespace with one existing path: no path-related violations', async () => {
+    const result = await runValidator([
+      namespaceNode('events', 'events', { paths: ['src/events'] }),
+    ]);
+
+    expect(rules(result, 'events-namespace-multiple-paths')).toHaveLength(0);
+    expect(rules(result, 'events-namespace-paths-missing')).toHaveLength(0);
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+
+  test('namespace with missing path: warns events-namespace-paths-missing', async () => {
+    const result = await runValidator([
+      namespaceNode('events', 'events', { paths: ['src/does-not-exist'] }),
+    ]);
+
+    const missing = rules(result, 'events-namespace-paths-missing');
+    expect(missing).toHaveLength(1);
+    expect(missing[0].severity).toBe('warn');
+    expect(missing[0].message).toContain('src/does-not-exist');
+  });
+
+  test('namespace with multiple paths: warns events-namespace-multiple-paths', async () => {
+    const result = await runValidator([
+      namespaceNode('events', 'events', {
+        paths: ['src/events', 'src/generated/events'],
+      }),
+    ]);
+
+    const multi = rules(result, 'events-namespace-multiple-paths');
+    expect(multi).toHaveLength(1);
+    expect(multi[0].severity).toBe('warn');
+    expect(multi[0].message).toContain('2 paths');
+  });
+
+  test('two namespaces declaring identical paths: errors events-namespace-paths-overlap', async () => {
+    const result = await runValidator([
+      namespaceNode('a', 'alpha', {
+        paths: ['src/events'],
+        eventNames: ['alpha.happened'],
+      }),
+      namespaceNode('b', 'beta', {
+        paths: ['src/events'],
+        eventNames: ['beta.happened'],
+      }),
+    ]);
+
+    const overlap = rules(result, 'events-namespace-paths-overlap');
+    expect(overlap).toHaveLength(1);
+    expect(overlap[0].severity).toBe('error');
+    expect(result.valid).toBe(false);
+  });
+
+  test('parent-child partition (workflow / workflow.scenarios): no overlap error', async () => {
+    const result = await runValidator([
+      namespaceNode('workflow', 'workflow', {
+        paths: ['src/workflow'],
+        eventNames: ['workflow.happened'],
+      }),
+      namespaceNode('workflow.scenarios', 'workflow.scenarios', {
+        paths: ['src/workflow/scenarios'],
+        eventNames: ['workflow.scenarios.matched'],
+      }),
+    ]);
+
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+
+  test('disjoint sibling paths: no overlap error', async () => {
+    const result = await runValidator([
+      namespaceNode('events', 'events', {
+        paths: ['src/events'],
+        eventNames: ['events.happened'],
+      }),
+      namespaceNode('trace', 'trace', {
+        paths: ['src/trace'],
+        eventNames: ['trace.happened'],
+      }),
+    ]);
+
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+
+  test('path normalization: trailing slashes and "./" prefix compared equivalently', async () => {
+    const result = await runValidator([
+      namespaceNode('a', 'alpha', {
+        paths: ['src/events/'],
+        eventNames: ['alpha.happened'],
+      }),
+      namespaceNode('b', 'beta', {
+        paths: ['./src/events'],
+        eventNames: ['beta.happened'],
+      }),
+    ]);
+
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(1);
+  });
+
+  test('similar-prefix paths that are not parent/child: no overlap error', async () => {
+    // src/foo and src/foobar share a prefix but neither is a descendant of the other.
+    // These should not trigger the overlap rule.
+    mkdirSync(join(testRoot, 'src/foo'), { recursive: true });
+    mkdirSync(join(testRoot, 'src/foobar'), { recursive: true });
+
+    const result = await runValidator([
+      namespaceNode('a', 'foo', {
+        paths: ['src/foo'],
+        eventNames: ['foo.happened'],
+      }),
+      namespaceNode('b', 'foobar', {
+        paths: ['src/foobar'],
+        eventNames: ['foobar.happened'],
+      }),
+    ]);
+
+    expect(rules(result, 'events-namespace-paths-overlap')).toHaveLength(0);
+  });
+});

package/src/events/EventsCanvasValidator.ts

@@ -6,6 +6,9 @@
  */
 
 import type { ExtendedCanvas, ExtendedCanvasNode } from '../types/canvas';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { pathsOverlap } from './path-helpers';
 
 /**
  * Event namespace node structure
@@ -16,6 +19,19 @@ export interface EventNamespaceNode {
   namespace: {
     name: string;
     description: string;
+    /**
+     * Optional source paths that define this component's code location.
+     * Each entry may be a folder (covers all descendants) or a specific file.
+     * When present, events in this namespace may only be emitted from files
+     * covered by one of these paths. Namespaces without `paths` remain
+     * unenforced — enforcement is opt-in per namespace.
+     *
+     * Multiple entries are valid for cases like generated code, platform-split
+     * implementations, or migration periods. The validator warns when
+     * `paths.length > 1` to prompt authors to confirm the multi-location
+     * is intentional.
+     */
+    paths?: string[];
     events: Array<{
       name: string;
       severity?: 'INFO' | 'WARN' | 'ERROR';
@@ -328,6 +344,76 @@ export class EventsCanvasValidator {
       }
     }
 
+    // Validate namespace paths (optional field — enforcement is opt-in per namespace).
+    // Collects declared paths across namespaces to check for cross-namespace overlap.
+    const declaredPaths: Array<{ namespace: string; nodeId: string; path: string }> = [];
+    for (const node of eventsCanvas.nodes || []) {
+      if (!this.isEventNamespaceNode(node)) continue;
+      const namespaceNode = node as EventNamespaceNode;
+      const paths = namespaceNode.namespace.paths;
+      if (!paths || paths.length === 0) continue;
+
+      // Warn when a namespace declares more than one path — prompt author to
+      // confirm the multi-location is intentional (generated code, platform
+      // splits, migration) rather than an accidental sprawl.
+      if (paths.length > 1) {
+        violations.push({
+          ruleId: 'events-namespace-multiple-paths',
+          severity: 'warn',
+          file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+          path: `nodes[id="${namespaceNode.id}"].namespace.paths`,
+          message: `Namespace "${namespaceNode.namespace.name}" declares ${paths.length} paths`,
+          impact: 'Multiple paths can indicate legitimate cases (generated code, platform splits, migration) but often signal that the namespace should be split',
+          suggestion: 'Confirm the multi-location is intentional. Otherwise consider splitting the namespace or grouping the code under a single parent folder.',
+        });
+      }
+
+      for (const p of paths) {
+        declaredPaths.push({
+          namespace: namespaceNode.namespace.name,
+          nodeId: namespaceNode.id,
+          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: 'events-namespace-paths-missing',
+            severity: 'warn',
+            file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+            path: `nodes[id="${namespaceNode.id}"].namespace.paths`,
+            message: `Path "${p}" declared by namespace "${namespaceNode.namespace.name}" does not exist`,
+            impact: 'Events emitted under this namespace cannot be validated against a real code location',
+            suggestion: 'Verify the path exists relative to the repository root, or remove it from the namespace declaration.',
+          });
+        }
+      }
+    }
+
+    // Cross-namespace overlap check. Parent-child nesting is a valid partition
+    // (longest-prefix wins at runtime); any other overlap makes namespace
+    // 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.namespace === b.namespace) continue;
+
+        const relationship = pathsOverlap(a.path, b.path);
+        if (relationship === 'conflict') {
+          violations.push({
+            ruleId: 'events-namespace-paths-overlap',
+            severity: 'error',
+            file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+            message: `Paths overlap between namespaces "${a.namespace}" ("${a.path}") and "${b.namespace}" ("${b.path}")`,
+            impact: 'A file covered by two namespaces makes namespace ownership ambiguous',
+            suggestion: 'Separate the paths so they are disjoint, or restructure as parent/child namespaces (e.g., "workflow" covering "src/workflow" and "workflow.scenarios" covering "src/workflow/scenarios").',
+          });
+        }
+      }
+    }
+
     metrics.totalNamespaces = extractedNamespaces.size;
 
     const errors = violations.filter(v => v.severity === 'error');

package/src/events/NamespacePathIndex.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from 'bun:test';
+import { NamespacePathIndex } from './NamespacePathIndex';
+
+function makeIndex(entries: Array<{ scope: string; namespace: string; paths: string[] }>) {
+  const idx = new NamespacePathIndex();
+  idx.addAll(entries);
+  return idx;
+}
+
+describe('NamespacePathIndex.resolve', () => {
+  test('empty index resolves to null', () => {
+    const idx = new NamespacePathIndex();
+    expect(idx.resolve('scope', 'src/foo.ts')).toBeNull();
+  });
+
+  test('matches file nested under a declared folder path', () => {
+    const idx = makeIndex([{ scope: 's', namespace: 'events', paths: ['src/events'] }]);
+    const match = idx.resolve('s', 'src/events/foo.ts');
+    expect(match?.entry.namespace).toBe('events');
+    expect(match?.matchedPath).toBe('src/events');
+  });
+
+  test('returns null when no path covers the file', () => {
+    const idx = makeIndex([{ scope: 's', namespace: 'events', paths: ['src/events'] }]);
+    expect(idx.resolve('s', 'src/other/foo.ts')).toBeNull();
+  });
+
+  test('scope isolation: match in scope A is not returned when querying scope B', () => {
+    const idx = makeIndex([{ scope: 'A', namespace: 'events', paths: ['src/events'] }]);
+    expect(idx.resolve('B', 'src/events/foo.ts')).toBeNull();
+  });
+
+  test('longest-prefix wins: nested child namespace beats parent', () => {
+    const idx = makeIndex([
+      { scope: 's', namespace: 'workflow', paths: ['src/workflow'] },
+      { scope: 's', namespace: 'workflow.scenarios', paths: ['src/workflow/scenarios'] },
+    ]);
+
+    // Parent-only subtree → parent wins
+    expect(idx.resolve('s', 'src/workflow/orchestrator.ts')?.entry.namespace).toBe('workflow');
+    // Child subtree → child wins (longer prefix)
+    expect(idx.resolve('s', 'src/workflow/scenarios/matcher.ts')?.entry.namespace).toBe(
+      'workflow.scenarios',
+    );
+    // Deeper under child → still child (inherited)
+    expect(idx.resolve('s', 'src/workflow/scenarios/helpers/fmt.ts')?.entry.namespace).toBe(
+      'workflow.scenarios',
+    );
+  });
+
+  test('exact-file path matches when declared as a file', () => {
+    const idx = makeIndex([{ scope: 's', namespace: 'retry', paths: ['src/utils/retry.ts'] }]);
+    expect(idx.resolve('s', 'src/utils/retry.ts')?.entry.namespace).toBe('retry');
+    // Not a folder, so unrelated files don't match
+    expect(idx.resolve('s', 'src/utils/other.ts')).toBeNull();
+  });
+
+  test('normalization: trailing slash and ./ prefix are equivalent', () => {
+    const idx = makeIndex([{ scope: 's', namespace: 'events', paths: ['src/events/'] }]);
+    expect(idx.resolve('s', './src/events/foo.ts')?.entry.namespace).toBe('events');
+  });
+
+  test('similar-prefix paths are not mistaken for nesting', () => {
+    const idx = makeIndex([
+      { scope: 's', namespace: 'foo', paths: ['src/foo'] },
+      { scope: 's', namespace: 'foobar', paths: ['src/foobar'] },
+    ]);
+    expect(idx.resolve('s', 'src/foobar/x.ts')?.entry.namespace).toBe('foobar');
+    expect(idx.resolve('s', 'src/foo/x.ts')?.entry.namespace).toBe('foo');
+  });
+});
+
+describe('NamespacePathIndex.getEntry', () => {
+  test('returns null when (scope, namespace) not registered', () => {
+    const idx = makeIndex([{ scope: 's', namespace: 'events', paths: ['src/events'] }]);
+    expect(idx.getEntry('s', 'workflow')).toBeNull();
+    expect(idx.getEntry('other', 'events')).toBeNull();
+  });
+
+  test('returns the entry when present', () => {
+    const idx = makeIndex([{ scope: 's', namespace: 'events', paths: ['src/events'] }]);
+    expect(idx.getEntry('s', 'events')?.paths).toEqual(['src/events']);
+  });
+});
+
+describe('NamespacePathIndex.getScopeEntries / getScopes', () => {
+  test('returns only entries for the requested scope', () => {
+    const idx = makeIndex([
+      { scope: 'A', namespace: 'a1', paths: ['src/a1'] },
+      { scope: 'A', namespace: 'a2', paths: ['src/a2'] },
+      { scope: 'B', namespace: 'b1', paths: ['src/b1'] },
+    ]);
+    expect(idx.getScopeEntries('A')).toHaveLength(2);
+    expect(idx.getScopeEntries('B')).toHaveLength(1);
+    expect(idx.getScopes().sort()).toEqual(['A', 'B']);
+  });
+});

package/src/events/NamespacePathIndex.ts

@@ -0,0 +1,100 @@
+/**
+ * Namespace Path Index
+ *
+ * Maps (scope, filepath) to the event-namespace that owns the file, using the
+ * `paths` field declared on `event-namespace` nodes.
+ *
+ * Resolution uses the longest-prefix partitioning rule: when multiple
+ * namespaces within a scope have paths that cover the same file, the one
+ * whose matched path is the most specific (longest after normalization) wins.
+ * This naturally supports nested namespaces such as `workflow` and
+ * `workflow.scenarios`, where the child claims its subtree without stealing
+ * the parent's.
+ *
+ * Pure/browser-safe — no filesystem access, just string comparison.
+ */
+
+import { normalizePath, pathCovers } from './path-helpers';
+
+/**
+ * One declared namespace/paths tuple, tagged with the scope it belongs to.
+ * Multiple entries may share the same scope (different namespaces in the
+ * same events canvas) or the same namespace across scopes (no cross-scope
+ * conflict — resolution is scoped).
+ */
+export interface NamespacePathEntry {
+  scope: string;
+  namespace: string;
+  paths: string[];
+  /** Optional — useful for surfacing where a match came from in diagnostics. */
+  sourceCanvasPath?: string;
+}
+
+/**
+ * Result of resolving a file against the index.
+ */
+export interface NamespacePathMatch {
+  /** The winning entry (by longest-prefix). */
+  entry: NamespacePathEntry;
+  /** Which of the entry's paths covered the file — the one that won. */
+  matchedPath: string;
+}
+
+export class NamespacePathIndex {
+  private entries: NamespacePathEntry[] = [];
+
+  /** Register a single namespace/paths entry. */
+  add(entry: NamespacePathEntry): void {
+    this.entries.push(entry);
+  }
+
+  /** Register many entries at once. */
+  addAll(entries: readonly NamespacePathEntry[]): void {
+    for (const e of entries) this.add(e);
+  }
+
+  /**
+   * Resolve a filepath to its owning namespace within a scope.
+   * Returns null if no entry in that scope has a path covering the file.
+   */
+  resolve(scope: string, filepath: string): NamespacePathMatch | null {
+    const normalizedFile = normalizePath(filepath);
+    let best: { entry: NamespacePathEntry; matchedPath: string; length: number } | null = null;
+
+    for (const entry of this.entries) {
+      if (entry.scope !== scope) continue;
+      for (const declared of entry.paths) {
+        if (!pathCovers(declared, normalizedFile)) continue;
+        const normalizedDeclared = normalizePath(declared);
+        const length = normalizedDeclared.length;
+        if (best === null || length > best.length) {
+          best = { entry, matchedPath: declared, length };
+        }
+      }
+    }
+
+    return best ? { entry: best.entry, matchedPath: best.matchedPath } : null;
+  }
+
+  /** All entries registered under the given scope (for diagnostics). */
+  getScopeEntries(scope: string): readonly NamespacePathEntry[] {
+    return this.entries.filter((e) => e.scope === scope);
+  }
+
+  /**
+   * Look up the entry for a specific (scope, namespace) pair. Returns null
+   * when the namespace isn't registered — either because its events-canvas
+   * node omits `paths` (opt-out of enforcement) or because no such namespace
+   * is declared at all.
+   */
+  getEntry(scope: string, namespace: string): NamespacePathEntry | null {
+    return this.entries.find(
+      (e) => e.scope === scope && e.namespace === namespace,
+    ) ?? null;
+  }
+
+  /** All scopes present in the index. */
+  getScopes(): readonly string[] {
+    return Array.from(new Set(this.entries.map((e) => e.scope)));
+  }
+}