@principal-ai/principal-view-core 0.5.6

package/src/rules/engine.test.ts

@@ -0,0 +1,332 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { GraphRulesEngine, createRulesEngine } from './engine';
+import { builtinRules } from './implementations';
+import type { GraphConfiguration } from '../types';
+import type { GraphRule } from './types';
+
+describe('GraphRulesEngine', () => {
+  let engine: GraphRulesEngine;
+
+  beforeEach(() => {
+    engine = new GraphRulesEngine();
+  });
+
+  describe('rule registration', () => {
+    it('should register a rule', () => {
+      const mockRule: GraphRule = {
+        id: 'test-rule',
+        name: 'Test Rule',
+        description: 'A test rule',
+        impact: 'Test impact',
+        severity: 'error',
+        category: 'schema',
+        enabled: true,
+        fixable: false,
+        check: async () => [],
+      };
+
+      engine.registerRule(mockRule);
+      expect(engine.getRule('test-rule')).toBe(mockRule);
+    });
+
+    it('should throw when registering duplicate rule', () => {
+      const mockRule: GraphRule = {
+        id: 'test-rule',
+        name: 'Test Rule',
+        description: 'A test rule',
+        impact: 'Test impact',
+        severity: 'error',
+        category: 'schema',
+        enabled: true,
+        fixable: false,
+        check: async () => [],
+      };
+
+      engine.registerRule(mockRule);
+      expect(() => engine.registerRule(mockRule)).toThrow('already registered');
+    });
+
+    it('should register multiple rules', () => {
+      const rules: GraphRule[] = [
+        {
+          id: 'rule-1',
+          name: 'Rule 1',
+          description: 'Rule 1',
+          impact: 'Impact 1',
+          severity: 'error',
+          category: 'schema',
+          enabled: true,
+          fixable: false,
+          check: async () => [],
+        },
+        {
+          id: 'rule-2',
+          name: 'Rule 2',
+          description: 'Rule 2',
+          impact: 'Impact 2',
+          severity: 'warn',
+          category: 'reference',
+          enabled: true,
+          fixable: false,
+          check: async () => [],
+        },
+      ];
+
+      engine.registerRules(rules);
+      expect(engine.getAllRules().size).toBe(2);
+    });
+
+    it('should unregister a rule', () => {
+      const mockRule: GraphRule = {
+        id: 'test-rule',
+        name: 'Test Rule',
+        description: 'A test rule',
+        impact: 'Test impact',
+        severity: 'error',
+        category: 'schema',
+        enabled: true,
+        fixable: false,
+        check: async () => [],
+      };
+
+      engine.registerRule(mockRule);
+      expect(engine.unregisterRule('test-rule')).toBe(true);
+      expect(engine.getRule('test-rule')).toBeUndefined();
+    });
+
+    it('should get rules by category', () => {
+      engine.registerRules(builtinRules);
+      const schemaRules = engine.getRulesByCategory('schema');
+      expect(schemaRules.length).toBeGreaterThan(0);
+      expect(schemaRules.every((r) => r.category === 'schema')).toBe(true);
+    });
+  });
+
+  describe('linting', () => {
+    const validConfig: GraphConfiguration = {
+      metadata: {
+        name: 'Test Config',
+        version: '1.0.0',
+      },
+      nodeTypes: {
+        service: {
+          shape: 'rectangle',
+          dataSchema: {
+            name: { type: 'string' },
+          },
+        },
+      },
+      edgeTypes: {
+        calls: {
+          style: 'solid',
+        },
+      },
+      allowedConnections: [
+        { from: 'service', to: 'service', via: 'calls' },
+      ],
+    };
+
+    it('should return no violations for valid config', async () => {
+      engine.registerRules(builtinRules);
+
+      // Add sources to avoid minimum-node-sources violation
+      const configWithSources = {
+        ...validConfig,
+        nodeTypes: {
+          service: {
+            ...validConfig.nodeTypes.service,
+            sources: ['lib/service.ts'],
+          },
+        },
+      };
+
+      const result = await engine.lint(configWithSources);
+      expect(result.errorCount).toBe(0);
+    });
+
+    it('should detect missing metadata', async () => {
+      engine.registerRules(builtinRules);
+
+      const invalidConfig = {
+        nodeTypes: validConfig.nodeTypes,
+        edgeTypes: validConfig.edgeTypes,
+        allowedConnections: validConfig.allowedConnections,
+      } as GraphConfiguration;
+
+      const result = await engine.lint(invalidConfig);
+      expect(result.violations.some((v) => v.ruleId === 'required-metadata')).toBe(true);
+    });
+
+    it('should detect invalid color format', async () => {
+      engine.registerRules(builtinRules);
+
+      const invalidConfig: GraphConfiguration = {
+        ...validConfig,
+        nodeTypes: {
+          service: {
+            ...validConfig.nodeTypes.service,
+            color: 'blue', // Invalid - should be hex
+            sources: ['lib/service.ts'],
+          },
+        },
+      };
+
+      const result = await engine.lint(invalidConfig);
+      const colorViolation = result.violations.find((v) => v.ruleId === 'valid-color-format');
+      expect(colorViolation).toBeDefined();
+      expect(colorViolation?.message).toContain('blue');
+    });
+
+    it('should respect disabled rules', async () => {
+      engine.registerRules(builtinRules);
+
+      const invalidConfig: GraphConfiguration = {
+        ...validConfig,
+        nodeTypes: {
+          service: {
+            ...validConfig.nodeTypes.service,
+            color: 'invalid',
+          },
+        },
+      };
+
+      const result = await engine.lint(invalidConfig, {
+        disabledRules: ['valid-color-format'],
+      });
+
+      expect(result.violations.some((v) => v.ruleId === 'valid-color-format')).toBe(false);
+    });
+
+    it('should respect enabled rules filter', async () => {
+      engine.registerRules(builtinRules);
+
+      const result = await engine.lint(validConfig, {
+        enabledRules: ['required-metadata'],
+      });
+
+      // Should only have violations from required-metadata (or none if valid)
+      expect(result.violations.every((v) => v.ruleId === 'required-metadata')).toBe(true);
+    });
+
+    it('should apply severity overrides', async () => {
+      engine.registerRules(builtinRules);
+
+      const invalidConfig: GraphConfiguration = {
+        ...validConfig,
+        nodeTypes: {
+          service: {
+            ...validConfig.nodeTypes.service,
+            color: 'invalid',
+            sources: ['lib/service.ts'],
+          },
+        },
+      };
+
+      const result = await engine.lint(invalidConfig, {
+        severityOverrides: new Map([['valid-color-format', 'warn']]),
+      });
+
+      const colorViolation = result.violations.find((v) => v.ruleId === 'valid-color-format');
+      expect(colorViolation?.severity).toBe('warn');
+    });
+
+    it('should count violations correctly', async () => {
+      engine.registerRules(builtinRules);
+
+      const invalidConfig: GraphConfiguration = {
+        metadata: { name: 'Test', version: '1.0.0' },
+        nodeTypes: {
+          service: {
+            shape: 'rectangle',
+            color: 'invalid1',
+            dataSchema: {},
+          },
+          database: {
+            shape: 'rectangle',
+            color: 'invalid2',
+            dataSchema: {},
+          },
+        },
+        edgeTypes: {
+          calls: { style: 'solid' },
+        },
+        allowedConnections: [{ from: 'service', to: 'database', via: 'calls' }],
+      };
+
+      const result = await engine.lint(invalidConfig);
+      expect(result.errorCount).toBeGreaterThan(0);
+      expect(result.violations.length).toBe(
+        result.errorCount + result.warningCount
+      );
+    });
+
+    it('should handle rule execution errors gracefully', async () => {
+      const errorRule: GraphRule = {
+        id: 'error-rule',
+        name: 'Error Rule',
+        description: 'A rule that throws',
+        impact: 'Test',
+        severity: 'error',
+        category: 'schema',
+        enabled: true,
+        fixable: false,
+        check: async () => {
+          throw new Error('Test error');
+        },
+      };
+
+      engine.registerRule(errorRule);
+
+      const result = await engine.lint(validConfig);
+      const errorViolation = result.violations.find((v) => v.ruleId === 'error-rule');
+      expect(errorViolation).toBeDefined();
+      expect(errorViolation?.message).toContain('Test error');
+    });
+  });
+
+  describe('createRulesEngine', () => {
+    it('should create engine with provided rules', () => {
+      const rules: GraphRule[] = [
+        {
+          id: 'test-rule',
+          name: 'Test',
+          description: 'Test',
+          impact: 'Test',
+          severity: 'error',
+          category: 'schema',
+          enabled: true,
+          fixable: false,
+          check: async () => [],
+        },
+      ];
+
+      const engine = createRulesEngine(rules);
+      expect(engine.getAllRules().size).toBe(1);
+    });
+
+    it('should create empty engine when no rules provided', () => {
+      const engine = createRulesEngine();
+      expect(engine.getAllRules().size).toBe(0);
+    });
+  });
+});
+
+describe('builtinRules', () => {
+  it('should have 14 rules', () => {
+    expect(builtinRules.length).toBe(14);
+  });
+
+  it('should have unique IDs', () => {
+    const ids = builtinRules.map((r) => r.id);
+    const uniqueIds = new Set(ids);
+    expect(uniqueIds.size).toBe(ids.length);
+  });
+
+  it('should all default to error severity', () => {
+    expect(builtinRules.every((r) => r.severity === 'error')).toBe(true);
+  });
+
+  it('should all be enabled by default', () => {
+    expect(builtinRules.every((r) => r.enabled === true)).toBe(true);
+  });
+});

package/src/rules/engine.ts

@@ -0,0 +1,318 @@
+/**
+ * Graph Rules Engine
+ * Central orchestrator for configuration validation rules
+ */
+
+import type { GraphConfiguration } from '../types';
+import type { ComponentLibrary } from '../types/library';
+import type {
+  GraphRule,
+  GraphRuleContext,
+  GraphRuleViolation,
+  GraphLintResult,
+  LintOptions,
+  RuleOptions,
+  NormalizedSeverity,
+  RuleCategory,
+  PrivuConfig,
+  RuleConfig,
+  RuleSeverity,
+} from './types';
+import { normalizeSeverity, isRuleDisabled } from './types';
+
+/**
+ * Graph Rules Engine - validates GraphConfiguration against registered rules
+ */
+export class GraphRulesEngine {
+  private rules: Map<string, GraphRule> = new Map();
+
+  constructor() {
+    // Rules are registered via registerRule() or registerBuiltinRules()
+  }
+
+  /**
+   * Register a single rule
+   */
+  registerRule(rule: GraphRule): void {
+    if (this.rules.has(rule.id)) {
+      throw new Error(`Rule "${rule.id}" is already registered`);
+    }
+    this.rules.set(rule.id, rule);
+  }
+
+  /**
+   * Register multiple rules at once
+   */
+  registerRules(rules: GraphRule[]): void {
+    for (const rule of rules) {
+      this.registerRule(rule);
+    }
+  }
+
+  /**
+   * Unregister a rule by ID
+   */
+  unregisterRule(ruleId: string): boolean {
+    return this.rules.delete(ruleId);
+  }
+
+  /**
+   * Get a rule by ID
+   */
+  getRule(ruleId: string): GraphRule | undefined {
+    return this.rules.get(ruleId);
+  }
+
+  /**
+   * Get all registered rules
+   */
+  getAllRules(): Map<string, GraphRule> {
+    return new Map(this.rules);
+  }
+
+  /**
+   * Get rules by category
+   */
+  getRulesByCategory(category: RuleCategory): GraphRule[] {
+    return Array.from(this.rules.values()).filter((rule) => rule.category === category);
+  }
+
+  /**
+   * Lint a configuration against all enabled rules
+   */
+  async lint(configuration: GraphConfiguration, options?: LintOptions): Promise<GraphLintResult> {
+    const violations: GraphRuleViolation[] = [];
+
+    for (const [ruleId, rule] of this.rules) {
+      // Check if rule should be skipped
+      if (!this.shouldRunRule(rule, options)) {
+        continue;
+      }
+
+      // Build context for this rule
+      const context = this.buildRuleContext(configuration, rule, options);
+
+      // Get effective severity
+      const effectiveSeverity = this.getEffectiveSeverity(rule, options);
+      if (effectiveSeverity === 'off') {
+        continue;
+      }
+
+      try {
+        // Execute rule check
+        const ruleViolations = await rule.check(context);
+
+        // Apply effective severity to all violations
+        for (const violation of ruleViolations) {
+          violation.severity = effectiveSeverity;
+          violations.push(violation);
+        }
+      } catch (error) {
+        // Rule execution error - report as a violation
+        violations.push({
+          ruleId,
+          severity: 'error',
+          message: `Rule "${ruleId}" threw an error: ${error instanceof Error ? error.message : String(error)}`,
+          impact: 'Rule could not complete validation',
+          fixable: false,
+        });
+      }
+    }
+
+    return this.buildResult(violations);
+  }
+
+  /**
+   * Lint a configuration with VGC config file settings applied
+   */
+  async lintWithConfig(
+    configuration: GraphConfiguration,
+    privuConfig: PrivuConfig,
+    options?: Omit<LintOptions, 'ruleOptions' | 'severityOverrides'>
+  ): Promise<GraphLintResult> {
+    // Convert VGC config rules to lint options
+    const { ruleOptions, severityOverrides, disabledRules } = this.parsePrivuConfigRules(
+      privuConfig.rules
+    );
+
+    return this.lint(configuration, {
+      ...options,
+      ruleOptions,
+      severityOverrides,
+      disabledRules: [...(options?.disabledRules ?? []), ...disabledRules],
+    });
+  }
+
+  /**
+   * Check if a rule should run based on options
+   */
+  private shouldRunRule(rule: GraphRule, options?: LintOptions): boolean {
+    // Check disabled rules list
+    if (options?.disabledRules?.includes(rule.id)) {
+      return false;
+    }
+
+    // Check enabled rules list (if specified, only run those)
+    if (options?.enabledRules && options.enabledRules.length > 0) {
+      return options.enabledRules.includes(rule.id);
+    }
+
+    // Check rule's default enabled state
+    return rule.enabled;
+  }
+
+  /**
+   * Get the effective severity for a rule
+   */
+  private getEffectiveSeverity(rule: GraphRule, options?: LintOptions): NormalizedSeverity {
+    // Check for override
+    if (options?.severityOverrides?.has(rule.id)) {
+      return options.severityOverrides.get(rule.id)!;
+    }
+
+    // Use rule's default severity
+    return rule.severity;
+  }
+
+  /**
+   * Build the context object for a rule
+   */
+  private buildRuleContext<TOptions extends RuleOptions>(
+    configuration: GraphConfiguration,
+    rule: GraphRule<TOptions>,
+    options?: LintOptions
+  ): GraphRuleContext<TOptions> {
+    // Merge default options with provided options
+    const ruleSpecificOptions = options?.ruleOptions?.get(rule.id) as TOptions | undefined;
+    const mergedOptions = {
+      ...rule.defaultOptions,
+      ...ruleSpecificOptions,
+    } as TOptions;
+
+    return {
+      configuration,
+      library: options?.library,
+      configPath: options?.configPath,
+      libraryPath: options?.libraryPath,
+      rawContent: options?.rawContent,
+      options: mergedOptions,
+      allRuleOptions: options?.ruleOptions,
+    };
+  }
+
+  /**
+   * Build the final lint result from violations
+   */
+  private buildResult(violations: GraphRuleViolation[]): GraphLintResult {
+    const byCategory: Record<RuleCategory, number> = {
+      schema: 0,
+      reference: 0,
+      structure: 0,
+      pattern: 0,
+      library: 0,
+    };
+
+    const byRule: Record<string, number> = {};
+
+    let errorCount = 0;
+    let warningCount = 0;
+    let fixableCount = 0;
+
+    for (const violation of violations) {
+      // Count by severity
+      if (violation.severity === 'error') {
+        errorCount++;
+      } else if (violation.severity === 'warn') {
+        warningCount++;
+      }
+
+      // Count fixable
+      if (violation.fixable) {
+        fixableCount++;
+      }
+
+      // Count by rule
+      byRule[violation.ruleId] = (byRule[violation.ruleId] ?? 0) + 1;
+
+      // Count by category
+      const rule = this.rules.get(violation.ruleId);
+      if (rule) {
+        byCategory[rule.category]++;
+      }
+    }
+
+    return {
+      violations,
+      errorCount,
+      warningCount,
+      fixableCount,
+      byCategory,
+      byRule,
+    };
+  }
+
+  /**
+   * Parse VGC config rules into lint options
+   */
+  private parsePrivuConfigRules(rules?: PrivuConfig['rules']): {
+    ruleOptions: Map<string, RuleOptions>;
+    severityOverrides: Map<string, NormalizedSeverity>;
+    disabledRules: string[];
+  } {
+    const ruleOptions = new Map<string, RuleOptions>();
+    const severityOverrides = new Map<string, NormalizedSeverity>();
+    const disabledRules: string[] = [];
+
+    if (!rules) {
+      return { ruleOptions, severityOverrides, disabledRules };
+    }
+
+    for (const [ruleId, config] of Object.entries(rules)) {
+      // Handle false (disabled)
+      if (config === false) {
+        disabledRules.push(ruleId);
+        continue;
+      }
+
+      // Handle severity shorthand
+      if (typeof config === 'string' || typeof config === 'number') {
+        const severity = normalizeSeverity(config as RuleSeverity);
+        if (severity === 'off') {
+          disabledRules.push(ruleId);
+        } else {
+          severityOverrides.set(ruleId, severity);
+        }
+        continue;
+      }
+
+      // Handle full config object
+      const ruleConfig = config as RuleConfig;
+
+      if (ruleConfig.severity !== undefined) {
+        const severity = normalizeSeverity(ruleConfig.severity);
+        if (severity === 'off') {
+          disabledRules.push(ruleId);
+        } else {
+          severityOverrides.set(ruleId, severity);
+        }
+      }
+
+      if (ruleConfig.options) {
+        ruleOptions.set(ruleId, ruleConfig.options);
+      }
+    }
+
+    return { ruleOptions, severityOverrides, disabledRules };
+  }
+}
+
+/**
+ * Create a new rules engine with optional initial rules
+ */
+export function createRulesEngine(rules?: GraphRule[]): GraphRulesEngine {
+  const engine = new GraphRulesEngine();
+  if (rules) {
+    engine.registerRules(rules);
+  }
+  return engine;
+}