@principal-ai/subsystems-core 0.29.0

package/src/registry/VersionRegistry.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Tests for InMemoryVersionRegistry
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InMemoryVersionRegistry, createInMemoryVersionRegistry } from './VersionRegistry';
+import type { RegisterVersionRequest } from '../types/version-registry';
+
+describe('InMemoryVersionRegistry', () => {
+  let registry: InMemoryVersionRegistry;
+
+  beforeEach(() => {
+    registry = createInMemoryVersionRegistry();
+  });
+
+  describe('register', () => {
+    it('should register a new version', async () => {
+      const request: RegisterVersionRequest = {
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'abc123',
+        storyboards: [
+          {
+            id: 'test-storyboard',
+            name: 'Test Storyboard',
+            path: '.principal-views/test.otel.canvas',
+            basename: 'test',
+            scope: 'root',
+            canvas: {
+              id: 'test',
+              name: 'Test',
+              path: '.principal-views/test.otel.canvas',
+              basename: 'test',
+              type: 'otel',
+              scope: 'root',
+            },
+            workflows: [],
+          },
+        ],
+      };
+
+      await registry.register(request);
+
+      const response = await registry.get('https://github.com/test/repo', 'abc123');
+      expect(response.found).toBe(true);
+      expect(response.snapshot).toBeDefined();
+      expect(response.snapshot?.repositoryUrl).toBe('https://github.com/test/repo');
+      expect(response.snapshot?.commitSha).toBe('abc123');
+      expect(response.snapshot?.storyboards).toHaveLength(1);
+      expect(response.snapshot?.registeredAt).toBeDefined();
+    });
+
+    it('should overwrite existing version with same repository and commit', async () => {
+      const request1: RegisterVersionRequest = {
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'abc123',
+        storyboards: [],
+      };
+
+      const request2: RegisterVersionRequest = {
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'abc123',
+        storyboards: [
+          {
+            id: 'new-storyboard',
+            name: 'New Storyboard',
+            path: '.principal-views/new.otel.canvas',
+            basename: 'new',
+            scope: 'root',
+            canvas: {
+              id: 'new',
+              name: 'New',
+              path: '.principal-views/new.otel.canvas',
+              basename: 'new',
+              type: 'otel',
+              scope: 'root',
+            },
+            workflows: [],
+          },
+        ],
+      };
+
+      await registry.register(request1);
+      await registry.register(request2);
+
+      const response = await registry.get('https://github.com/test/repo', 'abc123');
+      expect(response.found).toBe(true);
+      expect(response.snapshot?.storyboards).toHaveLength(1);
+      expect(response.snapshot?.storyboards[0].id).toBe('new-storyboard');
+    });
+  });
+
+  describe('get', () => {
+    it('should return found=false when version does not exist', async () => {
+      const response = await registry.get('https://github.com/test/repo', 'nonexistent');
+      expect(response.found).toBe(false);
+      expect(response.snapshot).toBeUndefined();
+      expect(response.error).toBeDefined();
+    });
+
+    it('should return found=true when version exists', async () => {
+      const request: RegisterVersionRequest = {
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'abc123',
+        storyboards: [],
+      };
+
+      await registry.register(request);
+
+      const response = await registry.get('https://github.com/test/repo', 'abc123');
+      expect(response.found).toBe(true);
+      expect(response.snapshot).toBeDefined();
+    });
+  });
+
+  describe('exists', () => {
+    it('should return false when version does not exist', async () => {
+      const exists = await registry.exists('https://github.com/test/repo', 'nonexistent');
+      expect(exists).toBe(false);
+    });
+
+    it('should return true when version exists', async () => {
+      const request: RegisterVersionRequest = {
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'abc123',
+        storyboards: [],
+      };
+
+      await registry.register(request);
+
+      const exists = await registry.exists('https://github.com/test/repo', 'abc123');
+      expect(exists).toBe(true);
+    });
+  });
+
+  describe('delete', () => {
+    it('should delete a version', async () => {
+      const request: RegisterVersionRequest = {
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'abc123',
+        storyboards: [],
+      };
+
+      await registry.register(request);
+      expect(await registry.exists('https://github.com/test/repo', 'abc123')).toBe(true);
+
+      await registry.delete('https://github.com/test/repo', 'abc123');
+      expect(await registry.exists('https://github.com/test/repo', 'abc123')).toBe(false);
+    });
+
+    it('should not throw when deleting non-existent version', async () => {
+      await expect(
+        registry.delete('https://github.com/test/repo', 'nonexistent')
+      ).resolves.toBeUndefined();
+    });
+  });
+
+  describe('listVersions', () => {
+    it('should return empty array when no versions exist', async () => {
+      const versions = await registry.listVersions('https://github.com/test/repo');
+      expect(versions).toEqual([]);
+    });
+
+    it('should return all versions for a repository', async () => {
+      await registry.register({
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'abc123',
+        storyboards: [],
+      });
+
+      await registry.register({
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'def456',
+        storyboards: [],
+      });
+
+      await registry.register({
+        repositoryUrl: 'https://github.com/other/repo',
+        commitSha: 'xyz789',
+        storyboards: [],
+      });
+
+      const versions = await registry.listVersions('https://github.com/test/repo');
+      expect(versions).toHaveLength(2);
+      expect(versions[0].commitSha).toBe('abc123');
+      expect(versions[1].commitSha).toBe('def456');
+    });
+
+    it('should return sorted versions', async () => {
+      await registry.register({
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'zzz',
+        storyboards: [],
+      });
+
+      await registry.register({
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'aaa',
+        storyboards: [],
+      });
+
+      const versions = await registry.listVersions('https://github.com/test/repo');
+      expect(versions[0].commitSha).toBe('aaa');
+      expect(versions[1].commitSha).toBe('zzz');
+    });
+  });
+
+  describe('clear', () => {
+    it('should clear all versions', async () => {
+      await registry.register({
+        repositoryUrl: 'https://github.com/test/repo',
+        commitSha: 'abc123',
+        storyboards: [],
+      });
+
+      expect(registry.size).toBe(1);
+
+      registry.clear();
+
+      expect(registry.size).toBe(0);
+      expect(await registry.exists('https://github.com/test/repo', 'abc123')).toBe(false);
+    });
+  });
+});

package/src/registry/VersionRegistry.ts

@@ -0,0 +1,121 @@
+/**
+ * In-Memory Version Registry Implementation
+ *
+ * This is a simple in-memory implementation of the VersionRegistry interface,
+ * useful for testing and development. For production use, implement a persistent
+ * backend (database, S3, etc.).
+ */
+
+import type {
+  VersionRegistry,
+  VersionSnapshot,
+  RegisterVersionRequest,
+  GetVersionResponse,
+  VersionIdentifier,
+} from '../types/version-registry';
+
+/**
+ * In-memory version registry for testing and development
+ */
+export class InMemoryVersionRegistry implements VersionRegistry {
+  private versions: Map<string, VersionSnapshot> = new Map();
+
+  /**
+   * Create a unique key for a version
+   */
+  private getKey(repositoryUrl: string, commitSha: string): string {
+    return `${repositoryUrl}@${commitSha}`;
+  }
+
+  /**
+   * Register a new version snapshot
+   */
+  async register(request: RegisterVersionRequest): Promise<void> {
+    const key = this.getKey(request.repositoryUrl, request.commitSha);
+
+    const snapshot: VersionSnapshot = {
+      repositoryUrl: request.repositoryUrl,
+      commitSha: request.commitSha,
+      storyboards: request.storyboards,
+      registeredAt: new Date().toISOString(),
+      metadata: request.metadata,
+    };
+
+    this.versions.set(key, snapshot);
+  }
+
+  /**
+   * Get a version snapshot by repository URL and commit SHA
+   */
+  async get(repositoryUrl: string, commitSha: string): Promise<GetVersionResponse> {
+    const key = this.getKey(repositoryUrl, commitSha);
+    const snapshot = this.versions.get(key);
+
+    if (!snapshot) {
+      return {
+        found: false,
+        error: `Version not found: ${repositoryUrl}@${commitSha}`,
+      };
+    }
+
+    return {
+      found: true,
+      snapshot,
+    };
+  }
+
+  /**
+   * Check if a version exists in the registry
+   */
+  async exists(repositoryUrl: string, commitSha: string): Promise<boolean> {
+    const key = this.getKey(repositoryUrl, commitSha);
+    return this.versions.has(key);
+  }
+
+  /**
+   * Delete a version from the registry
+   */
+  async delete(repositoryUrl: string, commitSha: string): Promise<void> {
+    const key = this.getKey(repositoryUrl, commitSha);
+    this.versions.delete(key);
+  }
+
+  /**
+   * List all versions for a repository
+   */
+  async listVersions(repositoryUrl: string): Promise<VersionIdentifier[]> {
+    const versions: VersionIdentifier[] = [];
+
+    for (const [_key, snapshot] of this.versions.entries()) {
+      if (snapshot.repositoryUrl === repositoryUrl) {
+        versions.push({
+          repositoryUrl: snapshot.repositoryUrl,
+          commitSha: snapshot.commitSha,
+        });
+      }
+    }
+
+    return versions.sort((a, b) => a.commitSha.localeCompare(b.commitSha));
+  }
+
+  /**
+   * Clear all versions (for testing)
+   */
+  clear(): void {
+    this.versions.clear();
+  }
+
+  /**
+   * Get the number of versions in the registry (for testing)
+   */
+  get size(): number {
+    return this.versions.size;
+  }
+}
+
+/**
+ * Create a new in-memory version registry
+ */
+export function createInMemoryVersionRegistry(): InMemoryVersionRegistry {
+  return new InMemoryVersionRegistry();
+}

package/src/rules/config.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validatePrivuConfig,
+  getDefaultConfig,
+  mergeConfigs,
+  formatConfigErrors,
+  VALID_RULE_IDS,
+} from './config';
+import type { PrivuConfig } from './types';
+
+describe('validatePrivuConfig', () => {
+  it('should accept valid minimal config', () => {
+    const config = { root: true };
+    const result = validatePrivuConfig(config);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('should accept valid full config', () => {
+    const config: PrivuConfig = {
+      $schema: 'https://principal.ai/schemas/privurc.json',
+      root: true,
+      library: '.principal-views/library.yaml',
+      include: ['.principal-views/**/*.yaml'],
+      exclude: ['**/*.test.yaml'],
+      rules: {
+        'required-metadata': 'error',
+        'valid-color-format': 'warn',
+        'orphaned-node-types': 'off',
+        'minimum-node-sources': {
+          severity: 'error',
+          options: {
+            minimum: 1,
+            excludeNodeTypes: ['external'],
+          },
+        },
+      },
+    };
+    const result = validatePrivuConfig(config);
+    expect(result.valid).toBe(true);
+  });
+
+  it('should reject non-object config', () => {
+    const result = validatePrivuConfig('string');
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].message).toContain('must be an object');
+  });
+
+  it('should reject null config', () => {
+    const result = validatePrivuConfig(null);
+    expect(result.valid).toBe(false);
+  });
+
+  it('should flag unknown top-level fields', () => {
+    const config = {
+      root: true,
+      unknownField: 'value',
+    };
+    const result = validatePrivuConfig(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.message.includes('unknownField'))).toBe(true);
+  });
+
+  it('should validate root is boolean', () => {
+    const config = { root: 'yes' };
+    const result = validatePrivuConfig(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'root')).toBe(true);
+  });
+
+  it('should validate library is string', () => {
+    const config = { library: 123 };
+    const result = validatePrivuConfig(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'library')).toBe(true);
+  });
+
+  it('should validate include is array of strings', () => {
+    const config = { include: 'not-an-array' };
+    const result = validatePrivuConfig(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'include')).toBe(true);
+  });
+
+  it('should validate extends is string or array', () => {
+    const validString = { extends: 'base-config' };
+    expect(validatePrivuConfig(validString).valid).toBe(true);
+
+    const validArray = { extends: ['config1', 'config2'] };
+    expect(validatePrivuConfig(validArray).valid).toBe(true);
+
+    const invalid = { extends: 123 };
+    expect(validatePrivuConfig(invalid).valid).toBe(false);
+  });
+
+  describe('rules validation', () => {
+    it('should accept valid rule ID', () => {
+      const config = {
+        rules: {
+          'required-metadata': 'error',
+        },
+      };
+      const result = validatePrivuConfig(config);
+      expect(result.valid).toBe(true);
+    });
+
+    it('should flag unknown rule ID', () => {
+      const config = {
+        rules: {
+          'unknown-rule': 'error',
+        },
+      };
+      const result = validatePrivuConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.message.includes('Unknown rule ID'))).toBe(true);
+    });
+
+    it('should suggest similar rule ID', () => {
+      const config = {
+        rules: {
+          'required-metdata': 'error', // typo
+        },
+      };
+      const result = validatePrivuConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.suggestion?.includes('required-metadata'))).toBe(true);
+    });
+
+    it('should accept numeric severity', () => {
+      const config = {
+        rules: {
+          'required-metadata': 2,
+        },
+      };
+      const result = validatePrivuConfig(config);
+      expect(result.valid).toBe(true);
+    });
+
+    it('should accept false to disable', () => {
+      const config = {
+        rules: {
+          'required-metadata': false,
+        },
+      };
+      const result = validatePrivuConfig(config);
+      expect(result.valid).toBe(true);
+    });
+
+    it('should flag invalid severity', () => {
+      const config = {
+        rules: {
+          'required-metadata': 'fatal',
+        },
+      };
+      const result = validatePrivuConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.message.includes('Invalid severity'))).toBe(true);
+    });
+
+    it('should validate rule config object', () => {
+      const valid = {
+        rules: {
+          'minimum-node-sources': {
+            severity: 'error',
+            options: { minimum: 2 },
+          },
+        },
+      };
+      expect(validatePrivuConfig(valid).valid).toBe(true);
+    });
+
+    it('should flag unknown rule config fields', () => {
+      const config = {
+        rules: {
+          'required-metadata': {
+            severity: 'error',
+            unknownField: 'value',
+          },
+        },
+      };
+      const result = validatePrivuConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.message.includes('unknownField'))).toBe(true);
+    });
+
+    it('should flag unknown rule options', () => {
+      const config = {
+        rules: {
+          'minimum-node-sources': {
+            options: {
+              minumum: 2, // typo
+            },
+          },
+        },
+      };
+      const result = validatePrivuConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.suggestion?.includes('minimum'))).toBe(true);
+    });
+  });
+});
+
+describe('getDefaultConfig', () => {
+  it('should return default values', () => {
+    const config = getDefaultConfig();
+    expect(config.root).toBe(false);
+    expect(config.include).toBeDefined();
+    expect(config.exclude).toBeDefined();
+    expect(config.rules).toEqual({});
+  });
+});
+
+describe('mergeConfigs', () => {
+  it('should merge configs with later taking precedence', () => {
+    const base: PrivuConfig = {
+      root: false,
+      library: 'base-lib.yaml',
+      rules: {
+        'required-metadata': 'warn',
+      },
+    };
+
+    const override: PrivuConfig = {
+      root: true,
+      rules: {
+        'required-metadata': 'error',
+        'valid-color-format': 'off',
+      },
+    };
+
+    const merged = mergeConfigs(base, override);
+    expect(merged.root).toBe(true);
+    expect(merged.library).toBe('base-lib.yaml');
+    expect(merged.rules?.['required-metadata']).toBe('error');
+    expect(merged.rules?.['valid-color-format']).toBe('off');
+  });
+
+  it('should handle undefined configs', () => {
+    const config: PrivuConfig = { root: true };
+    const merged = mergeConfigs(undefined, config, undefined);
+    expect(merged.root).toBe(true);
+  });
+});
+
+describe('formatConfigErrors', () => {
+  it('should format errors for display', () => {
+    const errors = [
+      { path: 'rules.unknown', message: 'Unknown rule', suggestion: 'Did you mean X?' },
+      { path: 'root', message: 'Must be boolean' },
+    ];
+
+    const output = formatConfigErrors(errors);
+    expect(output).toContain('rules.unknown');
+    expect(output).toContain('Unknown rule');
+    expect(output).toContain('Did you mean X?');
+    expect(output).toContain('2 configuration errors');
+  });
+
+  it('should handle single error', () => {
+    const errors = [{ path: 'root', message: 'Must be boolean' }];
+    const output = formatConfigErrors(errors);
+    expect(output).toContain('1 configuration error');
+  });
+});
+
+describe('VALID_RULE_IDS', () => {
+  it('should contain all 13 rule IDs', () => {
+    expect(VALID_RULE_IDS.length).toBe(13);
+  });
+
+  it('should include expected rules', () => {
+    expect(VALID_RULE_IDS).toContain('required-metadata');
+    expect(VALID_RULE_IDS).toContain('no-unknown-fields');
+    expect(VALID_RULE_IDS).toContain('minimum-node-sources');
+    expect(VALID_RULE_IDS).toContain('valid-action-patterns');
+  });
+});