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

package/src/auxiliary/AuxiliaryManifestValidator.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { AuxiliaryManifestValidator } from './AuxiliaryManifestValidator';
+import type { AuxiliaryManifest } from '../types/auxiliary';
+
+function makeRepo(layout: string[]): string {
+  const root = mkdtempSync(join(tmpdir(), 'aux-manifest-'));
+  for (const rel of layout) {
+    const full = join(root, rel);
+    mkdirSync(full.substring(0, full.lastIndexOf('/')) || full, { recursive: true });
+    if (!rel.endsWith('/')) writeFileSync(full, '');
+  }
+  return root;
+}
+
+describe('AuxiliaryManifestValidator', () => {
+  const validator = new AuxiliaryManifestValidator();
+
+  test('no manifest is a no-op', () => {
+    const result = validator.validate({ basePath: '/tmp' });
+    expect(result.valid).toBe(true);
+    expect(result.violations).toHaveLength(0);
+  });
+
+  test('passes for a clean manifest', () => {
+    const root = makeRepo(['docs/README.md', '.github/workflows/ci.yml']);
+    const manifest: AuxiliaryManifest = {
+      areas: [
+        { name: 'Documentation', paths: ['docs'], description: 'design docs' },
+        { name: 'GitHub', paths: ['.github'], description: 'CI config' },
+      ],
+    };
+    const result = validator.validate({ manifest, basePath: root });
+    expect(result.valid).toBe(true);
+    expect(result.violations).toHaveLength(0);
+  });
+
+  test('flags duplicate area names', () => {
+    const root = makeRepo(['docs/README.md', 'misc/note.txt']);
+    const manifest: AuxiliaryManifest = {
+      areas: [
+        { name: 'Docs', paths: ['docs'], description: 'a' },
+        { name: 'Docs', paths: ['misc'], description: 'b' },
+      ],
+    };
+    const result = validator.validate({ manifest, basePath: root });
+    const dup = result.violations.find((v) => v.ruleId === 'auxiliary-area-name-duplicate');
+    expect(dup).toBeDefined();
+    expect(dup!.severity).toBe('error');
+    expect(result.valid).toBe(false);
+  });
+
+  test('warns when a declared path does not exist', () => {
+    const root = makeRepo(['docs/README.md']);
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Ghost', paths: ['nope'], description: 'missing' }],
+    };
+    const result = validator.validate({ manifest, basePath: root });
+    const missing = result.violations.find((v) => v.ruleId === 'auxiliary-area-path-missing');
+    expect(missing).toBeDefined();
+    expect(missing!.severity).toBe('warn');
+    // Warnings alone don't invalidate the manifest
+    expect(result.valid).toBe(true);
+  });
+
+  test('flags overlap between two areas', () => {
+    const root = makeRepo(['docs/sub/file.md']);
+    const manifest: AuxiliaryManifest = {
+      areas: [
+        { name: 'A', paths: ['docs'], description: 'a' },
+        { name: 'B', paths: ['docs/sub'], description: 'b' },
+      ],
+    };
+    const result = validator.validate({ manifest, basePath: root });
+    const overlap = result.violations.find((v) => v.ruleId === 'auxiliary-area-paths-overlap');
+    expect(overlap).toBeDefined();
+    expect(overlap!.severity).toBe('error');
+    expect(result.valid).toBe(false);
+  });
+
+  test('flags duplicate paths within a single area as self-overlap', () => {
+    const root = makeRepo(['docs/file.md']);
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'A', paths: ['docs', 'docs'], description: 'a' }],
+    };
+    const result = validator.validate({ manifest, basePath: root });
+    const self = result.violations.find((v) => v.ruleId === 'auxiliary-area-paths-self-overlap');
+    expect(self).toBeDefined();
+  });
+});

package/src/auxiliary/AuxiliaryManifestValidator.ts

@@ -0,0 +1,129 @@
+/**
+ * Auxiliary Manifest Validator
+ *
+ * Own-file checks for `.principal-views/auxiliary.manifest.json`:
+ *   - area names are unique
+ *   - declared paths exist on disk
+ *   - paths don't overlap each other (within or across areas)
+ *
+ * Cross-file overlap with scope paths lives in `validateAreaScopeDisjoint`,
+ * mirroring the way `validateScopeNamespaceNesting` handles cross-canvas
+ * checks for scopes/namespaces.
+ */
+
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import type { AuxiliaryManifest } from '../types/auxiliary';
+import { pathsOverlap } from '../events/path-helpers';
+
+export interface AuxiliaryManifestValidationContext {
+  /** Parsed manifest. When absent, validation is a no-op (manifest is optional). */
+  manifest?: AuxiliaryManifest;
+
+  /** Path to the manifest file — used in violation messages. */
+  manifestPath?: string;
+
+  /** Repo root for resolving area paths against the filesystem. */
+  basePath: string;
+}
+
+export interface AuxiliaryManifestViolation {
+  ruleId: string;
+  severity: 'error' | 'warn';
+  file: string;
+  path?: string;
+  message: string;
+  impact: string;
+  suggestion: string;
+}
+
+export interface AuxiliaryManifestValidationResult {
+  valid: boolean;
+  violations: AuxiliaryManifestViolation[];
+}
+
+const DEFAULT_MANIFEST_PATH = '.principal-views/auxiliary.manifest.json';
+
+export class AuxiliaryManifestValidator {
+  validate(context: AuxiliaryManifestValidationContext): AuxiliaryManifestValidationResult {
+    const violations: AuxiliaryManifestViolation[] = [];
+    const { manifest, basePath } = context;
+    const file = context.manifestPath || DEFAULT_MANIFEST_PATH;
+
+    if (!manifest) {
+      return { valid: true, violations };
+    }
+
+    const areas = manifest.areas || [];
+
+    // Unique area names
+    const seenNames = new Map<string, number>();
+    areas.forEach((area, idx) => {
+      const count = seenNames.get(area.name) ?? 0;
+      seenNames.set(area.name, count + 1);
+      if (count === 1) {
+        violations.push({
+          ruleId: 'auxiliary-area-name-duplicate',
+          severity: 'error',
+          file,
+          path: `areas[${idx}].name`,
+          message: `Area name "${area.name}" is declared more than once`,
+          impact: 'Duplicate names make diagnostics ambiguous — a violation cannot be tied back to a single area',
+          suggestion: 'Rename one of the areas so names are unique across the manifest.',
+        });
+      }
+    });
+
+    // Path existence + collect for overlap pass
+    const declaredPaths: Array<{ areaName: string; areaIndex: number; pathIndex: number; path: string }> = [];
+    areas.forEach((area, areaIdx) => {
+      const paths = area.paths || [];
+      paths.forEach((p, pathIdx) => {
+        declaredPaths.push({ areaName: area.name, areaIndex: areaIdx, pathIndex: pathIdx, path: p });
+
+        const resolved = resolve(basePath, p);
+        if (!existsSync(resolved)) {
+          violations.push({
+            ruleId: 'auxiliary-area-path-missing',
+            severity: 'warn',
+            file,
+            path: `areas[${areaIdx}].paths[${pathIdx}]`,
+            message: `Path "${p}" declared by area "${area.name}" does not exist`,
+            impact: 'The manifest documents a folder that is not present in the repository',
+            suggestion: 'Verify the path exists relative to the repository root, or remove it from the area declaration.',
+          });
+        }
+      });
+    });
+
+    // Path overlap. Unlike scopes, areas have no dotted-name hierarchy, so
+    // parent-child nesting between two areas is just as ambiguous as a flat
+    // overlap — both are flagged.
+    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];
+        const relationship = pathsOverlap(a.path, b.path);
+        if (relationship === 'none') continue;
+
+        const sameArea = a.areaName === b.areaName;
+        violations.push({
+          ruleId: sameArea ? 'auxiliary-area-paths-self-overlap' : 'auxiliary-area-paths-overlap',
+          severity: 'error',
+          file,
+          path: sameArea
+            ? `areas[${a.areaIndex}].paths`
+            : undefined,
+          message: sameArea
+            ? `Area "${a.areaName}" declares overlapping paths "${a.path}" and "${b.path}"`
+            : `Paths overlap between areas "${a.areaName}" ("${a.path}") and "${b.areaName}" ("${b.path}")`,
+          impact: 'Two area declarations covering the same file make ownership ambiguous',
+          suggestion: 'Make the paths disjoint. If one folder genuinely sits inside another area, drop the redundant entry.',
+        });
+      }
+    }
+
+    const errors = violations.filter((v) => v.severity === 'error');
+    return { valid: errors.length === 0, violations };
+  }
+}

package/src/auxiliary/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Auxiliary module
+ *
+ * Validation for `auxiliary.manifest.json` — the catalog of project regions
+ * that sit outside the OTEL telemetry surface (docs, .github, etc.).
+ */
+
+export {
+  AuxiliaryManifestValidator,
+  type AuxiliaryManifestValidationContext,
+  type AuxiliaryManifestValidationResult,
+  type AuxiliaryManifestViolation,
+} from './AuxiliaryManifestValidator';
+
+export {
+  validateAreaScopeDisjoint,
+  type ValidateAreaScopeDisjointInput,
+} from './validateAreaScopeDisjoint';

package/src/auxiliary/validateAreaScopeDisjoint.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test';
+import { validateAreaScopeDisjoint } from './validateAreaScopeDisjoint';
+import type { AuxiliaryManifest } from '../types/auxiliary';
+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;
+}
+
+describe('validateAreaScopeDisjoint', () => {
+  test('returns no violations when areas and scopes are disjoint', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/core/src'] }]),
+    });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('flags exact overlap with a scope path', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Core', paths: ['packages/core/src'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/core/src'] }]),
+    });
+    expect(violations).toHaveLength(1);
+    expect(violations[0].ruleId).toBe('auxiliary-area-scope-overlap');
+  });
+
+  test('flags parent-child overlap (area covering a scope path)', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'All', paths: ['packages'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/core/src'] }]),
+    });
+    expect(violations).toHaveLength(1);
+    expect(violations[0].ruleId).toBe('auxiliary-area-scope-overlap');
+  });
+
+  test('flags parent-child overlap (scope path covering an area)', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Inner', paths: ['packages/core/src/docs'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/core/src'] }]),
+    });
+    expect(violations).toHaveLength(1);
+  });
+
+  test('no scopes canvas means no cross-check', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({ manifest });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('scopes without paths impose no constraint', () => {
+    const manifest: AuxiliaryManifest = {
+      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
+    };
+    const violations = validateAreaScopeDisjoint({
+      manifest,
+      scopesCanvas: scopesCanvas([{ scope: 'core' }]),
+    });
+    expect(violations).toHaveLength(0);
+  });
+});

package/src/auxiliary/validateAreaScopeDisjoint.ts

@@ -0,0 +1,72 @@
+/**
+ * Area / Scope Disjointness Validator
+ *
+ * Cross-file check: project-area paths declared in
+ * `auxiliary.manifest.json` must be disjoint from every scope path declared
+ * in `architecture.scopes.canvas`. Areas and scopes carve up the repo into
+ * non-overlapping regions — any overlap (parent-child or otherwise) means a
+ * file is claimed by both an OTEL scope and an auxiliary area, which makes
+ * ownership ambiguous.
+ *
+ * Mirrors `validateScopeNamespaceNesting`'s cross-canvas pattern: takes both
+ * inputs, returns violations.
+ */
+
+import type { AuxiliaryManifest } from '../types/auxiliary';
+import type { ExtendedCanvas } from '../types/canvas';
+import { isOtelScopeNode } from '../types/canvas';
+import { pathsOverlap } from '../events/path-helpers';
+import type { AuxiliaryManifestViolation } from './AuxiliaryManifestValidator';
+
+export interface ValidateAreaScopeDisjointInput {
+  manifest: AuxiliaryManifest;
+  manifestPath?: string;
+  scopesCanvas?: ExtendedCanvas;
+  scopesCanvasPath?: string;
+}
+
+const DEFAULT_MANIFEST_PATH = '.principal-views/auxiliary.manifest.json';
+
+export function validateAreaScopeDisjoint(
+  input: ValidateAreaScopeDisjointInput,
+): AuxiliaryManifestViolation[] {
+  const { manifest, scopesCanvas } = input;
+  const manifestFile = input.manifestPath || DEFAULT_MANIFEST_PATH;
+
+  if (!scopesCanvas) return [];
+
+  const scopePaths: Array<{ scope: string; path: 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;
+    for (const p of paths) scopePaths.push({ scope, path: p });
+  }
+
+  if (scopePaths.length === 0) return [];
+
+  const violations: AuxiliaryManifestViolation[] = [];
+  const areas = manifest.areas || [];
+
+  areas.forEach((area, areaIdx) => {
+    (area.paths || []).forEach((areaPath, pathIdx) => {
+      for (const sp of scopePaths) {
+        const relationship = pathsOverlap(areaPath, sp.path);
+        if (relationship === 'none') continue;
+
+        violations.push({
+          ruleId: 'auxiliary-area-scope-overlap',
+          severity: 'error',
+          file: manifestFile,
+          path: `areas[${areaIdx}].paths[${pathIdx}]`,
+          message: `Area "${area.name}" path "${areaPath}" overlaps scope "${sp.scope}" path "${sp.path}"`,
+          impact: 'A file claimed by both an OTEL scope and an auxiliary area has ambiguous ownership — the manifest is meant to catalog regions outside the telemetry surface',
+          suggestion: 'Make the area path disjoint from every scope path. If the folder is genuinely runtime code, drop it from the manifest; if it is auxiliary, narrow the scope path or move the folder.',
+        });
+      }
+    });
+  });
+
+  return violations;
+}

package/src/index.ts

@@ -339,6 +339,8 @@ export {
 // Export scopes module (canvas validation + scope utilities)
 export {
   ScopesCanvasValidator,
+  ScopePathIndex,
+  validateScopeNamespaceNesting,
   DEFAULT_SCOPE_COLOR,
   DRAFT_NODE_COLOR,
   getScopeNames,
@@ -352,6 +354,10 @@ export type {
   ScopesCanvasValidationContext,
   ScopesCanvasValidationResult,
   ScopesCanvasViolation,
+  ScopePathEntry,
+  ScopePathMatch,
+  ScopeEventsCanvasPair,
+  ValidateScopeNamespaceNestingInput,
   NormalizedScope,
 } from './scopes';
 

package/src/node.ts

@@ -202,6 +202,8 @@ export type {
 // Export scopes module (canvas validation + scope utilities)
 export {
   ScopesCanvasValidator,
+  ScopePathIndex,
+  validateScopeNamespaceNesting,
   DEFAULT_SCOPE_COLOR,
   DRAFT_NODE_COLOR,
   getScopeNames,
@@ -215,9 +217,25 @@ export type {
   ScopesCanvasValidationContext,
   ScopesCanvasValidationResult,
   ScopesCanvasViolation,
+  ScopePathEntry,
+  ScopePathMatch,
+  ScopeEventsCanvasPair,
+  ValidateScopeNamespaceNestingInput,
   NormalizedScope,
 } from './scopes';
 
+// Export auxiliary module (manifest validation for non-OTEL project regions)
+export {
+  AuxiliaryManifestValidator,
+  validateAreaScopeDisjoint,
+} from './auxiliary';
+export type {
+  AuxiliaryManifestValidationContext,
+  AuxiliaryManifestValidationResult,
+  AuxiliaryManifestViolation,
+  ValidateAreaScopeDisjointInput,
+} from './auxiliary';
+
 // Export events module (canvas validation)
 export {
   EventsCanvasValidator,

package/src/scopes/ScopePathIndex.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test';
+import { ScopePathIndex } from './ScopePathIndex';
+
+function makeIndex(entries: Array<{ scope: string; paths: string[] }>) {
+  const idx = new ScopePathIndex();
+  idx.addAll(entries);
+  return idx;
+}
+
+describe('ScopePathIndex.resolve', () => {
+  test('empty index resolves to null', () => {
+    const idx = new ScopePathIndex();
+    expect(idx.resolve('packages/core/src/foo.ts')).toBeNull();
+  });
+
+  test('matches file nested under a declared folder path', () => {
+    const idx = makeIndex([{ scope: 'principal-ai.core', paths: ['packages/core/src'] }]);
+    const match = idx.resolve('packages/core/src/events/foo.ts');
+    expect(match?.entry.scope).toBe('principal-ai.core');
+    expect(match?.matchedPath).toBe('packages/core/src');
+  });
+
+  test('returns null when no path covers the file', () => {
+    const idx = makeIndex([{ scope: 'principal-ai.core', paths: ['packages/core/src'] }]);
+    expect(idx.resolve('packages/cli/src/foo.ts')).toBeNull();
+  });
+
+  test('longest-prefix wins: nested child scope beats parent', () => {
+    const idx = makeIndex([
+      { scope: 'principal-ai.core', paths: ['packages/core/src'] },
+      { scope: 'principal-ai.core.validation', paths: ['packages/core/src/validation'] },
+    ]);
+
+    // Parent-only subtree → parent wins
+    expect(idx.resolve('packages/core/src/events/foo.ts')?.entry.scope).toBe('principal-ai.core');
+    // Child subtree → child wins (longer prefix)
+    expect(idx.resolve('packages/core/src/validation/engine.ts')?.entry.scope).toBe(
+      'principal-ai.core.validation',
+    );
+    // Deeper under child → still child (inherited)
+    expect(idx.resolve('packages/core/src/validation/rules/foo.ts')?.entry.scope).toBe(
+      'principal-ai.core.validation',
+    );
+  });
+
+  test('sibling scopes resolve disjointly', () => {
+    const idx = makeIndex([
+      { scope: 'principal-ai.core', paths: ['packages/core/src'] },
+      { scope: 'principal-ai.cli', paths: ['packages/cli/src'] },
+    ]);
+    expect(idx.resolve('packages/core/src/foo.ts')?.entry.scope).toBe('principal-ai.core');
+    expect(idx.resolve('packages/cli/src/foo.ts')?.entry.scope).toBe('principal-ai.cli');
+  });
+
+  test('exact-file path matches when declared as a file', () => {
+    const idx = makeIndex([{ scope: 'tiny', paths: ['packages/tiny/src/index.ts'] }]);
+    expect(idx.resolve('packages/tiny/src/index.ts')?.entry.scope).toBe('tiny');
+    expect(idx.resolve('packages/tiny/src/other.ts')).toBeNull();
+  });
+
+  test('normalization: trailing slash and ./ prefix are equivalent', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/core/src/'] }]);
+    expect(idx.resolve('./packages/core/src/foo.ts')?.entry.scope).toBe('s');
+  });
+
+  test('similar-prefix paths are not mistaken for nesting', () => {
+    const idx = makeIndex([
+      { scope: 'foo', paths: ['packages/foo/src'] },
+      { scope: 'foobar', paths: ['packages/foobar/src'] },
+    ]);
+    expect(idx.resolve('packages/foobar/src/x.ts')?.entry.scope).toBe('foobar');
+    expect(idx.resolve('packages/foo/src/x.ts')?.entry.scope).toBe('foo');
+  });
+});
+
+describe('ScopePathIndex.getEntry / getScopes', () => {
+  test('getEntry returns null when scope not registered', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/core/src'] }]);
+    expect(idx.getEntry('other')).toBeNull();
+  });
+
+  test('getEntry returns the entry when present', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/core/src'] }]);
+    expect(idx.getEntry('s')?.paths).toEqual(['packages/core/src']);
+  });
+
+  test('getScopes lists each scope once', () => {
+    const idx = makeIndex([
+      { scope: 'a', paths: ['packages/a/src'] },
+      { scope: 'b', paths: ['packages/b/src'] },
+    ]);
+    expect(idx.getScopes().slice().sort()).toEqual(['a', 'b']);
+  });
+});

package/src/scopes/ScopePathIndex.ts

@@ -0,0 +1,89 @@
+/**
+ * Scope Path Index
+ *
+ * Maps a filepath to the `otel-scope` that owns it, using the `paths` field
+ * declared on `otel-scope` nodes.
+ *
+ * Resolution uses the longest-prefix partitioning rule: when multiple scopes
+ * have paths covering the same file, the one whose matched path is the most
+ * specific (longest after normalization) wins. This naturally supports nested
+ * scopes by dotted-name (e.g. `principal-ai.core` and
+ * `principal-ai.core.validation`), where the child claims its subtree without
+ * stealing the parent's.
+ *
+ * Pure/browser-safe — no filesystem access, just string comparison.
+ */
+
+import { normalizePath, pathCovers } from '../events/path-helpers';
+
+/**
+ * One declared scope/paths tuple. Multiple entries may share the same scope
+ * if a scope canvas needs to declare more than one region (generated code,
+ * platform splits, migration periods).
+ */
+export interface ScopePathEntry {
+  scope: 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 ScopePathMatch {
+  /** The winning entry (by longest-prefix). */
+  entry: ScopePathEntry;
+  /** Which of the entry's paths covered the file — the one that won. */
+  matchedPath: string;
+}
+
+export class ScopePathIndex {
+  private entries: ScopePathEntry[] = [];
+
+  /** Register a single scope/paths entry. */
+  add(entry: ScopePathEntry): void {
+    this.entries.push(entry);
+  }
+
+  /** Register many entries at once. */
+  addAll(entries: readonly ScopePathEntry[]): void {
+    for (const e of entries) this.add(e);
+  }
+
+  /**
+   * Resolve a filepath to its owning scope.
+   * Returns null if no entry has a path covering the file.
+   */
+  resolve(filepath: string): ScopePathMatch | null {
+    const normalizedFile = normalizePath(filepath);
+    let best: { entry: ScopePathEntry; matchedPath: string; length: number } | null = null;
+
+    for (const entry of this.entries) {
+      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;
+  }
+
+  /**
+   * Look up the entry for a specific scope. Returns null when the scope
+   * isn't registered — either because its scopes-canvas node omits `paths`
+   * (opt-out of enforcement) or because no such scope is declared.
+   */
+  getEntry(scope: string): ScopePathEntry | null {
+    return this.entries.find((e) => e.scope === scope) ?? null;
+  }
+
+  /** All scopes present in the index. */
+  getScopes(): readonly string[] {
+    return Array.from(new Set(this.entries.map((e) => e.scope)));
+  }
+}