@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/rules/engine.ts

@@ -1,448 +0,0 @@
-/**
- * Graph Rules Engine
- * Central orchestrator for configuration validation rules
- */
-
-import { trace, SpanStatusCode } from '@opentelemetry/api';
-import type { GraphConfiguration } from '../types';
-import type {
-  GraphRule,
-  GraphRuleContext,
-  GraphRuleViolation,
-  GraphLintResult,
-  LintOptions,
-  RuleOptions,
-  NormalizedSeverity,
-  RuleCategory,
-  PrivuConfig,
-  RuleConfig,
-  RuleSeverity,
-} from './types';
-import { normalizeSeverity } from './types';
-
-// Get tracer for instrumentation
-const tracer = trace.getTracer('principal-view-core');
-
-/**
- * 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 span = tracer.startSpan('rules.lint', {
-      attributes: {
-        'lint.config.path': options?.configPath ?? 'unknown',
-        'lint.rules.total': this.rules.size,
-        'lint.library.provided': !!options?.library,
-      },
-    });
-
-    try {
-      const violations: GraphRuleViolation[] = [];
-      let rulesExecuted = 0;
-      let rulesSkipped = 0;
-
-      span.addEvent('lint.started', {
-        'rules.registered': this.rules.size,
-      });
-
-      for (const [ruleId, rule] of this.rules) {
-        // Check if rule should be skipped
-        if (!this.shouldRunRule(rule, options)) {
-          rulesSkipped++;
-          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') {
-          rulesSkipped++;
-          continue;
-        }
-
-        // Create child span for rule execution
-        // Note: Not using context propagation here to avoid Bun compatibility issues
-        const ruleSpan = tracer.startSpan('rule.execute', {
-          attributes: {
-            'rule.id': ruleId,
-            'rule.category': rule.category,
-            'rule.severity': effectiveSeverity,
-            'rule.name': rule.name,
-            'parent.span.id': span.spanContext().spanId,
-          },
-        });
-
-        try {
-          const ruleStartTime = Date.now();
-
-          // Execute rule check
-          const ruleViolations = await rule.check(context);
-
-          const ruleDuration = Date.now() - ruleStartTime;
-          rulesExecuted++;
-
-          // Apply effective severity to all violations
-          for (const violation of ruleViolations) {
-            violation.severity = effectiveSeverity;
-            violations.push(violation);
-          }
-
-          // Record rule completion event
-          ruleSpan.addEvent('rule.completed', {
-            'rule.violations.count': ruleViolations.length,
-            'rule.duration.ms': ruleDuration,
-          });
-
-          // If violations found, add event to parent span
-          if (ruleViolations.length > 0) {
-            span.addEvent('violations.detected', {
-              'rule.id': ruleId,
-              'rule.category': rule.category,
-              'violations.count': ruleViolations.length,
-              'violations.severity': effectiveSeverity,
-            });
-          }
-
-          ruleSpan.setStatus({ code: SpanStatusCode.OK });
-        } catch (error) {
-          // Rule execution error - report as a violation
-          const errorMessage =
-            error instanceof Error ? error.message : String(error);
-
-          violations.push({
-            ruleId,
-            severity: 'error',
-            message: `Rule "${ruleId}" threw an error: ${errorMessage}`,
-            impact: 'Rule could not complete validation',
-            fixable: false,
-          });
-
-          ruleSpan.addEvent('rule.error', {
-            'error.message': errorMessage,
-            'error.type': error instanceof Error ? error.constructor.name : 'unknown',
-          });
-
-          ruleSpan.setStatus({
-            code: SpanStatusCode.ERROR,
-            message: errorMessage,
-          });
-
-          span.addEvent('rule.execution.error', {
-            'rule.id': ruleId,
-            'error.message': errorMessage,
-          });
-        } finally {
-          ruleSpan.end();
-        }
-      }
-
-      const result = this.buildResult(violations);
-
-      // Record final statistics
-      span.addEvent('lint.completed', {
-        'lint.rules.executed': rulesExecuted,
-        'lint.rules.skipped': rulesSkipped,
-        'lint.violations.total': violations.length,
-        'lint.violations.errors': result.errorCount,
-        'lint.violations.warnings': result.warningCount,
-        'lint.violations.fixable': result.fixableCount,
-      });
-
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: errorMessage,
-      });
-      span.recordException(error instanceof Error ? error : new Error(errorMessage));
-      throw error;
-    } finally {
-      span.end();
-    }
-  }
-
-  /**
-   * Lint a configuration with VGC config file settings applied
-   */
-  async lintWithConfig(
-    configuration: GraphConfiguration,
-    privuConfig: PrivuConfig,
-    options?: Omit<LintOptions, 'ruleOptions' | 'severityOverrides'>
-  ): Promise<GraphLintResult> {
-    const span = tracer.startSpan('rules.lintWithConfig', {
-      attributes: {
-        'config.path': options?.configPath ?? 'unknown',
-        'config.has.rules': !!privuConfig.rules,
-        'config.has.library': !!privuConfig.library,
-      },
-    });
-
-    try {
-      span.addEvent('config.parsing');
-
-      // Convert VGC config rules to lint options
-      const { ruleOptions, severityOverrides, disabledRules } = this.parsePrivuConfigRules(
-        privuConfig.rules
-      );
-
-      span.addEvent('config.parsed', {
-        'config.rule.options.count': ruleOptions.size,
-        'config.severity.overrides.count': severityOverrides.size,
-        'config.disabled.rules.count': disabledRules.length,
-      });
-
-      const result = await this.lint(configuration, {
-        ...options,
-        ruleOptions,
-        severityOverrides,
-        disabledRules: [...(options?.disabledRules ?? []), ...disabledRules],
-      });
-
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: errorMessage,
-      });
-      span.recordException(error instanceof Error ? error : new Error(errorMessage));
-      throw error;
-    } finally {
-      span.end();
-    }
-  }
-
-  /**
-   * 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;
-}

package/src/rules/implementations/connection-type-references.ts

@@ -1,117 +0,0 @@
-/**
- * Rule: connection-type-references
- * Ensures allowedConnections only reference existing nodeTypes and edgeTypes
- */
-
-import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
-
-export const connectionTypeReferences: GraphRule = {
-  id: 'connection-type-references',
-  name: 'Connection Type References',
-  description: 'allowedConnections must reference existing nodeTypes and edgeTypes',
-  impact: 'Invalid references will cause connection validation to fail',
-  severity: 'error',
-  category: 'reference',
-  enabled: true,
-  fixable: false,
-
-  async check(context: GraphRuleContext): Promise<GraphRuleViolation[]> {
-    const violations: GraphRuleViolation[] = [];
-    const { configuration, configPath } = context;
-
-    if (!configuration.allowedConnections || configuration.allowedConnections.length === 0) {
-      return violations;
-    }
-
-    // Get defined node and edge types
-    const nodeTypeIds = new Set(Object.keys(configuration.nodeTypes ?? {}));
-    const edgeTypeIds = new Set(Object.keys(configuration.edgeTypes ?? {}));
-
-    for (let i = 0; i < configuration.allowedConnections.length; i++) {
-      const connection = configuration.allowedConnections[i];
-      const basePath = `allowedConnections[${i}]`;
-
-      // Check 'from' references a valid nodeType
-      if (connection.from && !nodeTypeIds.has(connection.from)) {
-        const suggestion = findSimilar(connection.from, nodeTypeIds);
-        violations.push({
-          ruleId: 'connection-type-references',
-          severity: 'error',
-          file: configPath,
-          path: `${basePath}.from`,
-          message: `Connection rule references undefined nodeType "${connection.from}"`,
-          impact: 'This connection rule will not match any nodes',
-          suggestion: suggestion
-            ? `Did you mean "${suggestion}"?`
-            : `Available nodeTypes: ${[...nodeTypeIds].join(', ') || '(none defined)'}`,
-          fixable: false,
-        });
-      }
-
-      // Check 'to' references a valid nodeType
-      if (connection.to && !nodeTypeIds.has(connection.to)) {
-        const suggestion = findSimilar(connection.to, nodeTypeIds);
-        violations.push({
-          ruleId: 'connection-type-references',
-          severity: 'error',
-          file: configPath,
-          path: `${basePath}.to`,
-          message: `Connection rule references undefined nodeType "${connection.to}"`,
-          impact: 'This connection rule will not match any nodes',
-          suggestion: suggestion
-            ? `Did you mean "${suggestion}"?`
-            : `Available nodeTypes: ${[...nodeTypeIds].join(', ') || '(none defined)'}`,
-          fixable: false,
-        });
-      }
-
-      // Check 'via' references a valid edgeType
-      if (connection.via && !edgeTypeIds.has(connection.via)) {
-        const suggestion = findSimilar(connection.via, edgeTypeIds);
-        violations.push({
-          ruleId: 'connection-type-references',
-          severity: 'error',
-          file: configPath,
-          path: `${basePath}.via`,
-          message: `Connection rule references undefined edgeType "${connection.via}"`,
-          impact: 'This connection rule will not match any edges',
-          suggestion: suggestion
-            ? `Did you mean "${suggestion}"?`
-            : `Available edgeTypes: ${[...edgeTypeIds].join(', ') || '(none defined)'}`,
-          fixable: false,
-        });
-      }
-    }
-
-    return violations;
-  },
-};
-
-/**
- * Find a similar string from a set (for "did you mean" suggestions)
- */
-function findSimilar(input: string, candidates: Set<string>): string | null {
-  const inputLower = input.toLowerCase();
-
-  for (const candidate of candidates) {
-    const candidateLower = candidate.toLowerCase();
-
-    // Exact substring match
-    if (inputLower.includes(candidateLower) || candidateLower.includes(inputLower)) {
-      return candidate;
-    }
-
-    // Small edit distance
-    if (Math.abs(input.length - candidate.length) <= 2) {
-      let differences = 0;
-      const minLen = Math.min(inputLower.length, candidateLower.length);
-      for (let i = 0; i < minLen; i++) {
-        if (inputLower[i] !== candidateLower[i]) differences++;
-      }
-      differences += Math.abs(input.length - candidate.length);
-      if (differences <= 2) return candidate;
-    }
-  }
-
-  return null;
-}

package/src/rules/implementations/dead-end-states.ts

@@ -1,101 +0,0 @@
-/**
- * Rule: dead-end-states
- * Warns when states have no exit transitions (except terminal states)
- */
-
-import type { GraphRule, GraphRuleContext, GraphRuleViolation, RuleOptions } from '../types';
-
-/**
- * Options for dead-end-states rule
- */
-export interface DeadEndStatesOptions extends RuleOptions {
-  /**
-   * States that are intentionally terminal (no exits expected)
-   * @default ["completed", "failed", "terminated", "done", "error", "finished", "end"]
-   */
-  terminalStates: string[];
-}
-
-const DEFAULT_OPTIONS: DeadEndStatesOptions = {
-  terminalStates: ['completed', 'failed', 'terminated', 'done', 'error', 'finished', 'end'],
-};
-
-export const deadEndStates: GraphRule<DeadEndStatesOptions> = {
-  id: 'dead-end-states',
-  name: 'Dead End States',
-  description: 'States should have exit transitions unless they are terminal states',
-  impact: 'Dead-end states may trap entities unexpectedly',
-  severity: 'error',
-  category: 'structure',
-  enabled: true,
-  fixable: false,
-  defaultOptions: DEFAULT_OPTIONS,
-
-  async check(context: GraphRuleContext<DeadEndStatesOptions>): Promise<GraphRuleViolation[]> {
-    const violations: GraphRuleViolation[] = [];
-    const { configuration, configPath, options } = context;
-
-    const terminalStates = new Set(
-      (options.terminalStates ?? DEFAULT_OPTIONS.terminalStates).map((s) => s.toLowerCase())
-    );
-
-    if (!configuration.nodeTypes) {
-      return violations;
-    }
-
-    // For each nodeType with states, check if all non-terminal states have exits
-    for (const [typeId, nodeType] of Object.entries(configuration.nodeTypes)) {
-      if (!nodeType.states || Object.keys(nodeType.states).length === 0) {
-        continue;
-      }
-
-      const stateIds = Object.keys(nodeType.states);
-
-      // If there's only one state, no transitions expected
-      if (stateIds.length <= 1) {
-        continue;
-      }
-
-      // Get state transitions for this nodeType
-      const transitions = configuration.validation?.stateTransitions?.[typeId];
-
-      // Build set of states that have exit transitions
-      const statesWithExits = new Set<string>();
-
-      if (transitions && Array.isArray(transitions)) {
-        for (const transition of transitions) {
-          if (transition.from) {
-            statesWithExits.add(transition.from);
-          }
-        }
-      }
-
-      // Check for dead-end states
-      for (const stateId of stateIds) {
-        // Skip if this state has exits
-        if (statesWithExits.has(stateId)) {
-          continue;
-        }
-
-        // Skip if this is a known terminal state
-        if (terminalStates.has(stateId.toLowerCase())) {
-          continue;
-        }
-
-        // This is a dead-end state
-        violations.push({
-          ruleId: 'dead-end-states',
-          severity: 'error',
-          file: configPath,
-          path: `nodeTypes.${typeId}.states.${stateId}`,
-          message: `State "${stateId}" in node type "${typeId}" has no exit transitions`,
-          impact: 'Entities in this state cannot transition to other states',
-          suggestion: `Add a transition from "${stateId}" in validation.stateTransitions.${typeId}, or mark it as a terminal state`,
-          fixable: false,
-        });
-      }
-    }
-
-    return violations;
-  },
-};