@principal-ai/principal-view-core 0.5.6

package/src/rules/implementations/unreachable-states.ts

@@ -0,0 +1,94 @@
+/**
+ * Rule: unreachable-states
+ * Warns when states have no entry transitions (cannot be reached)
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+export const unreachableStates: GraphRule = {
+  id: 'unreachable-states',
+  name: 'Unreachable States',
+  description: 'States should have at least one entry transition or be an initial state',
+  impact: 'Unreachable states can never be entered and may indicate configuration errors',
+  severity: 'error',
+  category: 'structure',
+  enabled: true,
+  fixable: false,
+
+  async check(context: GraphRuleContext): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath } = context;
+
+    if (!configuration.nodeTypes) {
+      return violations;
+    }
+
+    // For each nodeType with states, check if all states are reachable
+    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, it's implicitly the initial state
+      if (stateIds.length <= 1) {
+        continue;
+      }
+
+      // Get state transitions for this nodeType
+      const transitions = configuration.validation?.stateTransitions?.[typeId];
+
+      if (!transitions || !Array.isArray(transitions) || transitions.length === 0) {
+        // No transitions defined - all states except the first are unreachable
+        // The first state is conventionally the initial state
+        for (let i = 1; i < stateIds.length; i++) {
+          violations.push({
+            ruleId: 'unreachable-states',
+            severity: 'error',
+            file: configPath,
+            path: `nodeTypes.${typeId}.states.${stateIds[i]}`,
+            message: `State "${stateIds[i]}" in node type "${typeId}" has no entry transitions`,
+            impact: 'This state can never be reached',
+            suggestion: `Add a state transition to "${stateIds[i]}" in validation.stateTransitions.${typeId}`,
+            fixable: false,
+          });
+        }
+        continue;
+      }
+
+      // Build set of states that can be reached (are targets of transitions)
+      const reachableStates = new Set<string>();
+
+      // First state is assumed to be the initial state
+      reachableStates.add(stateIds[0]);
+
+      // Add all states that are targets of transitions
+      for (const transition of transitions) {
+        if (Array.isArray(transition.to)) {
+          for (const toState of transition.to) {
+            reachableStates.add(toState);
+          }
+        }
+      }
+
+      // Check for unreachable states
+      for (const stateId of stateIds) {
+        if (!reachableStates.has(stateId)) {
+          violations.push({
+            ruleId: 'unreachable-states',
+            severity: 'error',
+            file: configPath,
+            path: `nodeTypes.${typeId}.states.${stateId}`,
+            message: `State "${stateId}" in node type "${typeId}" has no entry transitions`,
+            impact: 'This state can never be reached',
+            suggestion: `Add a state transition to "${stateId}" in validation.stateTransitions.${typeId}`,
+            fixable: false,
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/src/rules/implementations/valid-action-patterns.ts

@@ -0,0 +1,136 @@
+/**
+ * Rule: valid-action-patterns
+ * Ensures action pattern regex is syntactically valid
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation, RuleOptions } from '../types';
+
+/**
+ * Options for valid-action-patterns rule
+ */
+export interface ValidActionPatternsOptions extends RuleOptions {
+  /**
+   * Enable strict mode - also validates capture group references
+   * @default false
+   */
+  strictMode: boolean;
+}
+
+const DEFAULT_OPTIONS: ValidActionPatternsOptions = {
+  strictMode: false,
+};
+
+export const validActionPatterns: GraphRule<ValidActionPatternsOptions> = {
+  id: 'valid-action-patterns',
+  name: 'Valid Action Patterns',
+  description: 'Action pattern regex must be syntactically valid',
+  impact: 'Invalid regex patterns will cause runtime errors during log processing',
+  severity: 'error',
+  category: 'pattern',
+  enabled: true,
+  fixable: false,
+  defaultOptions: DEFAULT_OPTIONS,
+
+  async check(context: GraphRuleContext<ValidActionPatternsOptions>): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath, options } = context;
+
+    if (!configuration.nodeTypes) {
+      return violations;
+    }
+
+    for (const [typeId, nodeType] of Object.entries(configuration.nodeTypes)) {
+      // Check if nodeType has actions (from path-based config extension)
+      const nodeTypeAny = nodeType as unknown as Record<string, unknown>;
+      const actions = nodeTypeAny.actions;
+
+      if (!Array.isArray(actions)) {
+        continue;
+      }
+
+      for (let i = 0; i < actions.length; i++) {
+        const action = actions[i] as Record<string, unknown>;
+        const pattern = action.pattern;
+        const basePath = `nodeTypes.${typeId}.actions[${i}]`;
+
+        if (typeof pattern !== 'string') {
+          violations.push({
+            ruleId: 'valid-action-patterns',
+            severity: 'error',
+            file: configPath,
+            path: `${basePath}.pattern`,
+            message: `Action pattern must be a string`,
+            impact: 'Pattern matching will fail',
+            suggestion: 'Provide a valid regex pattern string',
+            fixable: false,
+          });
+          continue;
+        }
+
+        // Test if regex is valid
+        try {
+          new RegExp(pattern);
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          violations.push({
+            ruleId: 'valid-action-patterns',
+            severity: 'error',
+            file: configPath,
+            path: `${basePath}.pattern`,
+            message: `Invalid regex pattern "${pattern}": ${errorMessage}`,
+            impact: 'Pattern matching will fail at runtime',
+            suggestion: 'Fix the regex syntax error',
+            fixable: false,
+          });
+          continue;
+        }
+
+        // In strict mode, validate capture group references in metadata
+        if (options.strictMode) {
+          const metadata = action.metadata as Record<string, unknown> | undefined;
+          if (metadata) {
+            // Extract capture group names from pattern
+            const captureGroupNames = extractCaptureGroupNames(pattern);
+
+            for (const [metaKey, metaValue] of Object.entries(metadata)) {
+              if (typeof metaValue === 'string' && metaValue.startsWith('$')) {
+                const groupName = metaValue.slice(1);
+                if (!captureGroupNames.has(groupName)) {
+                  violations.push({
+                    ruleId: 'valid-action-patterns',
+                    severity: 'error',
+                    file: configPath,
+                    path: `${basePath}.metadata.${metaKey}`,
+                    message: `Metadata references undefined capture group "$${groupName}"`,
+                    impact: 'Metadata extraction will fail',
+                    suggestion: `Available capture groups: ${[...captureGroupNames].join(', ') || '(none)'}`,
+                    fixable: false,
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return violations;
+  },
+};
+
+/**
+ * Extract named capture group names from a regex pattern
+ */
+function extractCaptureGroupNames(pattern: string): Set<string> {
+  const names = new Set<string>();
+
+  // Match named capture groups: (?<name>...)
+  const namedGroupRegex = /\(\?<([a-zA-Z_][a-zA-Z0-9_]*)>/g;
+  let match;
+
+  while ((match = namedGroupRegex.exec(pattern)) !== null) {
+    names.add(match[1]);
+  }
+
+  return names;
+}

package/src/rules/implementations/valid-color-format.ts

@@ -0,0 +1,140 @@
+/**
+ * Rule: valid-color-format
+ * Ensures all color values are valid hex codes
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+/**
+ * Regex for valid hex color codes (#RGB or #RRGGBB)
+ */
+const HEX_COLOR_REGEX = /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;
+
+export const validColorFormat: GraphRule = {
+  id: 'valid-color-format',
+  name: 'Valid Color Format',
+  description: 'Color values must be valid hex codes (#RGB or #RRGGBB)',
+  impact: 'Invalid colors may render incorrectly or cause visualization errors',
+  severity: 'error',
+  category: 'schema',
+  enabled: true,
+  fixable: true,
+
+  async check(context: GraphRuleContext): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath } = context;
+
+    // Check nodeTypes colors
+    if (configuration.nodeTypes) {
+      for (const [typeId, nodeType] of Object.entries(configuration.nodeTypes)) {
+        // Check node color
+        if (nodeType.color && !isValidColor(nodeType.color)) {
+          violations.push(createColorViolation(
+            configPath,
+            `nodeTypes.${typeId}.color`,
+            nodeType.color,
+            `node type "${typeId}"`
+          ));
+        }
+
+        // Check node stroke color
+        if (nodeType.stroke && !isValidColor(nodeType.stroke)) {
+          violations.push(createColorViolation(
+            configPath,
+            `nodeTypes.${typeId}.stroke`,
+            nodeType.stroke,
+            `node type "${typeId}" stroke`
+          ));
+        }
+
+        // Check state colors
+        if (nodeType.states) {
+          for (const [stateName, stateDef] of Object.entries(nodeType.states)) {
+            if (stateDef.color && !isValidColor(stateDef.color)) {
+              violations.push(createColorViolation(
+                configPath,
+                `nodeTypes.${typeId}.states.${stateName}.color`,
+                stateDef.color,
+                `state "${stateName}" in node type "${typeId}"`
+              ));
+            }
+          }
+        }
+      }
+    }
+
+    // Check edgeTypes colors
+    if (configuration.edgeTypes) {
+      for (const [typeId, edgeType] of Object.entries(configuration.edgeTypes)) {
+        // Check edge color
+        if (edgeType.color && !isValidColor(edgeType.color)) {
+          violations.push(createColorViolation(
+            configPath,
+            `edgeTypes.${typeId}.color`,
+            edgeType.color,
+            `edge type "${typeId}"`
+          ));
+        }
+
+        // Check animation color
+        if (edgeType.animation?.color && !isValidColor(edgeType.animation.color)) {
+          violations.push(createColorViolation(
+            configPath,
+            `edgeTypes.${typeId}.animation.color`,
+            edgeType.animation.color,
+            `animation in edge type "${typeId}"`
+          ));
+        }
+      }
+    }
+
+    // Check display theme colors
+    if (configuration.display?.theme) {
+      const theme = configuration.display.theme;
+      const themeColors = ['primary', 'success', 'warning', 'danger', 'info'] as const;
+
+      for (const colorKey of themeColors) {
+        const colorValue = theme[colorKey];
+        if (colorValue && !isValidColor(colorValue)) {
+          violations.push(createColorViolation(
+            configPath,
+            `display.theme.${colorKey}`,
+            colorValue,
+            `theme ${colorKey} color`
+          ));
+        }
+      }
+    }
+
+    return violations;
+  },
+};
+
+/**
+ * Check if a color value is valid
+ */
+function isValidColor(color: string): boolean {
+  return HEX_COLOR_REGEX.test(color);
+}
+
+/**
+ * Create a color format violation
+ */
+function createColorViolation(
+  configPath: string | undefined,
+  path: string,
+  value: string,
+  description: string
+): GraphRuleViolation {
+  return {
+    ruleId: 'valid-color-format',
+    severity: 'error',
+    file: configPath,
+    path,
+    message: `Invalid color format "${value}" for ${description}`,
+    impact: 'Color may not render correctly',
+    suggestion: 'Use hex format: #RGB or #RRGGBB (e.g., #3b82f6 or #f00)',
+    fixable: true,
+    fixData: { path, value, description },
+  };
+}

package/src/rules/implementations/valid-edge-types.ts

@@ -0,0 +1,258 @@
+/**
+ * Rule: valid-edge-types
+ * Ensures edgeTypes have required fields and valid values
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+/**
+ * Valid style values for edges
+ */
+const VALID_STYLES = ['solid', 'dashed', 'dotted', 'animated'] as const;
+
+/**
+ * Valid animation types
+ */
+const VALID_ANIMATION_TYPES = ['flow', 'pulse', 'particle', 'glow'] as const;
+
+/**
+ * Valid label positions
+ */
+const VALID_LABEL_POSITIONS = ['start', 'middle', 'end'] as const;
+
+/**
+ * Valid data schema field types
+ */
+const VALID_DATA_TYPES = ['string', 'number', 'boolean', 'object', 'array'] as const;
+
+export const validEdgeTypes: GraphRule = {
+  id: 'valid-edge-types',
+  name: 'Valid Edge Types',
+  description: 'edgeTypes must have required fields and valid values',
+  impact: 'Invalid edge types will cause rendering errors or unexpected behavior',
+  severity: 'error',
+  category: 'schema',
+  enabled: true,
+  fixable: false,
+
+  async check(context: GraphRuleContext): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath } = context;
+
+    if (!configuration.edgeTypes) {
+      violations.push({
+        ruleId: 'valid-edge-types',
+        severity: 'error',
+        file: configPath,
+        path: 'edgeTypes',
+        message: 'Configuration is missing edgeTypes section',
+        impact: 'No edges can be defined without edgeTypes',
+        suggestion: 'Add an edgeTypes section with at least one edge type definition',
+        fixable: false,
+      });
+      return violations;
+    }
+
+    if (Object.keys(configuration.edgeTypes).length === 0) {
+      violations.push({
+        ruleId: 'valid-edge-types',
+        severity: 'error',
+        file: configPath,
+        path: 'edgeTypes',
+        message: 'edgeTypes section is empty',
+        impact: 'No edges can be defined without at least one edge type',
+        suggestion: 'Add at least one edge type definition',
+        fixable: false,
+      });
+      return violations;
+    }
+
+    for (const [typeId, edgeType] of Object.entries(configuration.edgeTypes)) {
+      const basePath = `edgeTypes.${typeId}`;
+
+      // Check required style field
+      if (!edgeType.style) {
+        violations.push({
+          ruleId: 'valid-edge-types',
+          severity: 'error',
+          file: configPath,
+          path: `${basePath}.style`,
+          message: `Edge type "${typeId}" is missing required "style" field`,
+          impact: 'Edge cannot be rendered without a style',
+          suggestion: `Add a style field. Valid values: ${VALID_STYLES.join(', ')}`,
+          fixable: false,
+        });
+      } else if (!VALID_STYLES.includes(edgeType.style as (typeof VALID_STYLES)[number])) {
+        violations.push({
+          ruleId: 'valid-edge-types',
+          severity: 'error',
+          file: configPath,
+          path: `${basePath}.style`,
+          message: `Edge type "${typeId}" has invalid style "${edgeType.style}"`,
+          impact: 'Edge may not render correctly',
+          suggestion: `Valid styles: ${VALID_STYLES.join(', ')}`,
+          fixable: false,
+        });
+      }
+
+      // Check width is a number if provided
+      if (edgeType.width !== undefined && typeof edgeType.width !== 'number') {
+        violations.push({
+          ruleId: 'valid-edge-types',
+          severity: 'error',
+          file: configPath,
+          path: `${basePath}.width`,
+          message: `Edge type "${typeId}" width must be a number`,
+          impact: 'Edge width may not render correctly',
+          suggestion: 'Provide width as a number (e.g., 2)',
+          fixable: false,
+        });
+      }
+
+      // Check directed is a boolean if provided
+      if (edgeType.directed !== undefined && typeof edgeType.directed !== 'boolean') {
+        violations.push({
+          ruleId: 'valid-edge-types',
+          severity: 'error',
+          file: configPath,
+          path: `${basePath}.directed`,
+          message: `Edge type "${typeId}" directed must be a boolean`,
+          impact: 'Edge direction may not work correctly',
+          suggestion: 'Provide directed as true or false',
+          fixable: false,
+        });
+      }
+
+      // Check animated is a boolean if provided
+      if (edgeType.animated !== undefined && typeof edgeType.animated !== 'boolean') {
+        violations.push({
+          ruleId: 'valid-edge-types',
+          severity: 'error',
+          file: configPath,
+          path: `${basePath}.animated`,
+          message: `Edge type "${typeId}" animated must be a boolean`,
+          impact: 'Edge animation may not work correctly',
+          suggestion: 'Provide animated as true or false',
+          fixable: false,
+        });
+      }
+
+      // Check label configuration
+      if (edgeType.label) {
+        if (typeof edgeType.label !== 'object' || edgeType.label === null) {
+          violations.push({
+            ruleId: 'valid-edge-types',
+            severity: 'error',
+            file: configPath,
+            path: `${basePath}.label`,
+            message: `Edge type "${typeId}" label must be an object`,
+            impact: 'Edge label configuration is invalid',
+            suggestion: 'Provide label as { field?: string, position?: "start" | "middle" | "end" }',
+            fixable: false,
+          });
+        } else {
+          if (edgeType.label.position !== undefined) {
+            if (!VALID_LABEL_POSITIONS.includes(edgeType.label.position as (typeof VALID_LABEL_POSITIONS)[number])) {
+              violations.push({
+                ruleId: 'valid-edge-types',
+                severity: 'error',
+                file: configPath,
+                path: `${basePath}.label.position`,
+                message: `Edge type "${typeId}" has invalid label position "${edgeType.label.position}"`,
+                impact: 'Label may not appear in expected position',
+                suggestion: `Valid positions: ${VALID_LABEL_POSITIONS.join(', ')}`,
+                fixable: false,
+              });
+            }
+          }
+        }
+      }
+
+      // Check animation configuration
+      if (edgeType.animation) {
+        if (typeof edgeType.animation !== 'object' || edgeType.animation === null) {
+          violations.push({
+            ruleId: 'valid-edge-types',
+            severity: 'error',
+            file: configPath,
+            path: `${basePath}.animation`,
+            message: `Edge type "${typeId}" animation must be an object`,
+            impact: 'Edge animation configuration is invalid',
+            suggestion: 'Provide animation as { type: "flow" | "pulse" | "particle" | "glow", duration?: number }',
+            fixable: false,
+          });
+        } else {
+          // Check animation type
+          if (!edgeType.animation.type) {
+            violations.push({
+              ruleId: 'valid-edge-types',
+              severity: 'error',
+              file: configPath,
+              path: `${basePath}.animation.type`,
+              message: `Edge type "${typeId}" animation is missing required "type" field`,
+              impact: 'Animation cannot run without a type',
+              suggestion: `Add a type field. Valid values: ${VALID_ANIMATION_TYPES.join(', ')}`,
+              fixable: false,
+            });
+          } else if (!VALID_ANIMATION_TYPES.includes(edgeType.animation.type as (typeof VALID_ANIMATION_TYPES)[number])) {
+            violations.push({
+              ruleId: 'valid-edge-types',
+              severity: 'error',
+              file: configPath,
+              path: `${basePath}.animation.type`,
+              message: `Edge type "${typeId}" has invalid animation type "${edgeType.animation.type}"`,
+              impact: 'Animation may not work correctly',
+              suggestion: `Valid animation types: ${VALID_ANIMATION_TYPES.join(', ')}`,
+              fixable: false,
+            });
+          }
+
+          // Check animation duration
+          if (edgeType.animation.duration !== undefined && typeof edgeType.animation.duration !== 'number') {
+            violations.push({
+              ruleId: 'valid-edge-types',
+              severity: 'error',
+              file: configPath,
+              path: `${basePath}.animation.duration`,
+              message: `Edge type "${typeId}" animation duration must be a number`,
+              impact: 'Animation timing may not work correctly',
+              suggestion: 'Provide duration as a number in milliseconds',
+              fixable: false,
+            });
+          }
+        }
+      }
+
+      // Check dataSchema field types
+      if (edgeType.dataSchema) {
+        for (const [fieldName, fieldDef] of Object.entries(edgeType.dataSchema)) {
+          if (!fieldDef.type) {
+            violations.push({
+              ruleId: 'valid-edge-types',
+              severity: 'error',
+              file: configPath,
+              path: `${basePath}.dataSchema.${fieldName}.type`,
+              message: `Data schema field "${fieldName}" in edge type "${typeId}" is missing "type"`,
+              impact: 'Data validation will not work for this field',
+              suggestion: `Add a type field. Valid values: ${VALID_DATA_TYPES.join(', ')}`,
+              fixable: false,
+            });
+          } else if (!VALID_DATA_TYPES.includes(fieldDef.type as (typeof VALID_DATA_TYPES)[number])) {
+            violations.push({
+              ruleId: 'valid-edge-types',
+              severity: 'error',
+              file: configPath,
+              path: `${basePath}.dataSchema.${fieldName}.type`,
+              message: `Invalid data type "${fieldDef.type}" for field "${fieldName}" in edge type "${typeId}"`,
+              impact: 'Data validation may fail',
+              suggestion: `Valid types: ${VALID_DATA_TYPES.join(', ')}`,
+              fixable: false,
+            });
+          }
+        }
+      }
+    }
+
+    return violations;
+  },
+};