@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/scopes/ScopesCanvasValidator.test.ts

@@ -1,127 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-import { NodeFileSystemAdapter } from '@principal-ai/repository-abstraction/node';
-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(new NodeFileSystemAdapter());
-    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(new NodeFileSystemAdapter());
-      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(new NodeFileSystemAdapter());
-      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(new NodeFileSystemAdapter());
-      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/subsystems-core/src/validation'], async (root) => {
-      const canvas = makeCanvas([
-        makeScopeNode({ id: 's1', scope: 'principal-ai.core', paths: ['packages/subsystems-core/src'] }),
-        makeScopeNode({
-          id: 's2',
-          scope: 'principal-ai.core.validation',
-          paths: ['packages/subsystems-core/src/validation'],
-        }),
-      ]);
-      const v = new ScopesCanvasValidator(new NodeFileSystemAdapter());
-      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

@@ -1,305 +0,0 @@
-/**
- * Scopes Canvas Validator
- *
- * Validates that a .scopes.canvas file exists and properly documents
- * all instrumentation scopes declared in library.yaml.
- */
-
-import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
-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
- */
-export interface ScopesCanvasValidationContext {
-  /** The scopes canvas (if found) */
-  scopesCanvas?: ExtendedCanvas;
-
-  /** Path to the scopes canvas file */
-  scopesCanvasPath?: string;
-
-  /** Owned scopes from library.yaml */
-  ownedScopes: string[];
-
-  /** Base path for resolving relative paths */
-  basePath: string;
-}
-
-/**
- * Scopes canvas validation violation
- */
-export interface ScopesCanvasViolation {
-  /** Rule ID that detected this violation */
-  ruleId: string;
-
-  /** Severity level */
-  severity: 'error' | 'warn';
-
-  /** File path where violation occurred */
-  file: string;
-
-  /** JSON path within file (optional) */
-  path?: string;
-
-  /** Human-readable description of what's wrong */
-  message: string;
-
-  /** Why this matters */
-  impact: string;
-
-  /** How to fix it */
-  suggestion: string;
-}
-
-/**
- * Scopes canvas validation result
- */
-export interface ScopesCanvasValidationResult {
-  /** Whether validation passed (no errors) */
-  valid: boolean;
-
-  /** List of violations found */
-  violations: ScopesCanvasViolation[];
-
-  /** Summary of scopes coverage */
-  coverage: {
-    /** Total owned scopes from library.yaml */
-    totalOwnedScopes: number;
-    /** Scopes documented in canvas */
-    documentedScopes: string[];
-    /** Scopes missing from canvas */
-    missingScopes: string[];
-    /** Scopes in canvas but not in owned-scopes */
-    extraScopes: string[];
-  };
-}
-
-/**
- * Validates scopes canvas files
- */
-export class ScopesCanvasValidator {
-  constructor(private fsAdapter: FileSystemAdapter) {}
-
-  /**
-   * Validate a scopes canvas against library.yaml owned-scopes
-   */
-  async validate(context: ScopesCanvasValidationContext): Promise<ScopesCanvasValidationResult> {
-    const violations: ScopesCanvasViolation[] = [];
-    const { scopesCanvas, scopesCanvasPath, ownedScopes, basePath } = context;
-
-    // Initialize coverage tracking
-    const documentedScopes: string[] = [];
-    const missingScopes: string[] = [];
-    const extraScopes: string[] = [];
-
-    // Check if scopes canvas exists when owned-scopes are defined
-    if (ownedScopes.length > 0 && !scopesCanvas) {
-      violations.push({
-        ruleId: 'scopes-canvas-required',
-        severity: 'error',
-        file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
-        message: 'Scopes canvas is required when library.yaml defines owned-scopes',
-        impact: 'Cannot visualize or validate instrumentation scope boundaries',
-        suggestion: `Create a scopes canvas at .principal-views/architecture.scopes.canvas with nodes for each scope:\n` +
-          ownedScopes.map(s => `  - ${s}`).join('\n') +
-          '\n\nUse type: "otel-scope" with otel.scope set to the scope name.',
-      });
-
-      return {
-        valid: false,
-        violations,
-        coverage: {
-          totalOwnedScopes: ownedScopes.length,
-          documentedScopes: [],
-          missingScopes: [...ownedScopes],
-          extraScopes: [],
-        },
-      };
-    }
-
-    // If no owned scopes and no canvas, that's fine
-    if (ownedScopes.length === 0) {
-      return {
-        valid: true,
-        violations,
-        coverage: {
-          totalOwnedScopes: 0,
-          documentedScopes: [],
-          missingScopes: [],
-          extraScopes: [],
-        },
-      };
-    }
-
-    // Extract scopes from canvas nodes
-    const canvasScopes = this.extractScopesFromCanvas(scopesCanvas!);
-    const canvasScopeSet = new Set(canvasScopes.map(s => s.scope));
-    const ownedScopeSet = new Set(ownedScopes);
-
-    // Check which scopes are documented
-    for (const scope of ownedScopes) {
-      if (canvasScopeSet.has(scope)) {
-        documentedScopes.push(scope);
-      } else {
-        missingScopes.push(scope);
-      }
-    }
-
-    // Check for extra scopes not in owned-scopes
-    for (const { scope, nodeId } of canvasScopes) {
-      if (!ownedScopeSet.has(scope)) {
-        extraScopes.push(scope);
-      }
-    }
-
-    // Report missing scopes
-    if (missingScopes.length > 0) {
-      violations.push({
-        ruleId: 'scopes-canvas-incomplete',
-        severity: 'error',
-        file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
-        message: `Scopes canvas is missing ${missingScopes.length} scope(s) from library.yaml`,
-        impact: 'These scopes are not documented in the scope boundary map',
-        suggestion: `Add nodes for the following scopes:\n` +
-          missingScopes.map(s => `  - ${s}: Add type: "otel-scope" node with otel.scope: "${s}"`).join('\n'),
-      });
-    }
-
-    // Report extra scopes (warning, not error)
-    if (extraScopes.length > 0) {
-      violations.push({
-        ruleId: 'scopes-canvas-extra-scopes',
-        severity: 'warn',
-        file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
-        message: `Scopes canvas contains ${extraScopes.length} scope(s) not in library.yaml owned-scopes`,
-        impact: 'These scopes may be external or need to be added to library.yaml',
-        suggestion: `Either:\n` +
-          `  - Add these scopes to owned-scopes in library.yaml: ${extraScopes.join(', ')}\n` +
-          `  - Or remove them from the scopes canvas if they are external`,
-      });
-    }
-
-    // Validate scope nodes have required fields (otel-scope nodes only)
-    for (const { scope, nodeId, node } of canvasScopes) {
-      // type === 'otel-scope' with top-level description
-      const otelScopeNode = node as unknown as OtelScopeNode;
-      if (!otelScopeNode.description) {
-        violations.push({
-          ruleId: 'scopes-canvas-node-description',
-          severity: 'warn',
-          file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
-          path: `nodes[${nodeId}]`,
-          message: `Scope node "${scope}" is missing a description`,
-          impact: 'Scope documentation is incomplete without a description',
-          suggestion: `Add a description field to explain what this scope covers`,
-        });
-      }
-    }
-
-    // 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 = this.fsAdapter.join(basePath, p);
-        if (!(await this.fsAdapter.exists(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/subsystems-core/src" and "principal-ai.core.validation" covering "packages/subsystems-core/src/validation").',
-          });
-        }
-      }
-    }
-
-    const errors = violations.filter(v => v.severity === 'error');
-
-    return {
-      valid: errors.length === 0,
-      violations,
-      coverage: {
-        totalOwnedScopes: ownedScopes.length,
-        documentedScopes,
-        missingScopes,
-        extraScopes,
-      },
-    };
-  }
-
-  /**
-   * Extract scope information from canvas nodes (otel-scope nodes only)
-   */
-  private extractScopesFromCanvas(
-    canvas: ExtendedCanvas
-  ): Array<{ scope: string; nodeId: string; node: ExtendedCanvasNode }> {
-    const scopes: Array<{ scope: string; nodeId: string; node: ExtendedCanvasNode }> = [];
-
-    for (const node of canvas.nodes || []) {
-      // Only process otel-scope nodes
-      if (checkOtelScopeNode(node)) {
-        const scope = node.otel?.scope;
-        if (scope && typeof scope === 'string') {
-          scopes.push({
-            scope,
-            nodeId: node.id,
-            node: node as ExtendedCanvasNode,
-          });
-        }
-      }
-      // Legacy pv.otel.scope format is no longer supported
-    }
-
-    return scopes;
-  }
-}